i2y/ritsu/kaname

When this applies

The job is a functional core: the part of a program that takes values and answers values, with no input or output. The next state of an order for an event, the reasons a form is refused, the difference of two counts of a stockroom, the paths of a tree of categories are each a function of it. So is the code between the decisions of other languages: a rule of rulec decides, a dates file of koyomi computes a day, a book of chobo moves an amount, and something has to put a rule's inputs together, carry an answer into the next call, spread an amount over lines and hand an amount to a book. kaname writes that code in ritsu's types, checks it by the rules the other languages are checked by, and says for each function whether it answers every input it declares (total), which places the code checks when it runs, or that it recurses and may not stop. The host calls the code ritsu gen writes of it.

It does not apply to input and output of any kind, to the state a program keeps between calls, or to the clock (the host's: it reads them and passes them in), to a decision of the business itself (a threshold, a fee, a category chosen by a value: that is a rulec table), to a day computed from a day (koyomi), to a balance kept by a book (chobo), or to waiting and side effects in order (a dandori workflow).

The files bundled with this skill are reference.md (the whole language and the commands) and codes.md (every diagnostic). Read them when you need them, not all up front.

Working with kaname

Your part is to write the module, get it past ritsu kaname check and ritsu check, and generate its code with ritsu gen. Three things stay with people:

1. The decisions. A choice of an amount, a rate or a category by a value belongs in a rulec

table, where it is checked complete and shown to the person who approves it. Never write one in kaname to make a check pass; W501 says where one is.

1. The ranges a function declares. They are what the host promises, and what the analysis

reads. Widening one to make a rule's call pass changes the promise: ask.

1. What a function promises. total on a function's head is a promise to the host (and, later,

to a workflow). Whether a function may fail at run time, and how the host handles it, is a person's to say.

1. The loop

1. Read the host's data the code is given and what it does with the answers, and the rules, the

dates files and the books the code will call, if any (ritsu rulec doc, ritsu koyomi doc, ritsu chobo doc).

1. Write the module: the heading, the use lines if it calls other languages, the records and

enums (a state with fields of its own is an enum whose values have fields), with the ranges the host promises where it can promise them, the functions, and examples from a case a person can check.

1. Run the check and fix what it says, one diagnostic at a time, from the top; `ritsu kaname explain

<code> says how. Then ritsu check` on the project, which adds ritsu's checks across the languages (X2, X3, X4, X6) and hands kaname their verdicts.

1. Generate the code into the host's package (ritsu gen --target <language>, once for each

language, or the target line of ritsu.mod), call it from the host, and have CI run the same ritsu gen with --check.

1. Write the page with ritsu kaname doc, and show it to the people who approve the decisions.
2. For a claim about every input of a function, write a property and, if it is to be shown, a proof in

Lean (section 5).

$ ritsu kaname check examples/order_flow/order_flow.kn
$ ritsu kaname explain E301
$ ritsu kaname run examples/order_flow/order_flow.kn replay --input events.json --trace
$ ritsu kaname doc examples/late_payment/late_payment.kn --root examples/late_payment --format html

Run every command as ritsu kaname <command> (through a link to ritsu named kaname, kaname <command> is the same): it reads the rules, the dates files and the books a module names in the same process, where kaname built alone from its crate reads no other language and stops with E202. Add --lang ja for Japanese.

2. The language on one page

# the handle a person typed, as it is kept, or every reason it cannot be
fn handle(raw: string) -> result[string, list[string]]
  let h = normalized(raw: raw)
  let why = problems(handle: h)
  if why.count() = 0 then ok(h) else err(why)
 
# a tag written `<handle>#<number>`: the handle made as `handle` makes it, the number from 1 to 9999
fn tag(text: string) -> result[Tag, list[string]]
  match text.index_of("#")
    none => err(["no # between the handle and the number"])
    some i =>
      let h = try handle(raw: text.take(i))
      match text.drop(i + 1).parse_number()
        none => err(["the number is not written in digits"])
        some n => if n >= 1 and n <= 9999 then ok(Tag { handle: h, number: n }) else err(["the number is not from 1 to 9999"])

# every code that differs, in the order of the codes: a dict and a set go round in their keys' order
fn changes(before: dict[string, number] range >=0 <=1_000_000, after: dict[string, number] range >=0 <=1_000_000) -> list[Change]
  let skus = before.keys().to_set().union(after.keys().to_set())
  skus.to_list().filter_map(sku => change(sku: sku, before: before.get(sku), after: after.get(sku)))

module late_payment v1
description "What a supplier claims for an invoice paid late: the day it fell due, how many days late it was paid, and the fixed sum and the interest the rule gives for them"
 
use dates terms from "dates/payment_terms.cal"
use rule charges from "rules/late_payment_charges.rule"
 
record Invoice
  id       : string
  invoiced : date  range >=2026-01-01 <=2027-12-31
  amount   : money[GBPc]  range >=1GBPc <=100_000_000GBPc
 
fn claim(invoice: Invoice, paid_on: date range >=2026-01-01 <=2029-12-31, reference_rate: rate[step 0.01%] range >=0% <=15%) -> Claim? total
  description "None when the invoice was paid by the day it fell due"
  let due = terms.due(invoiced: invoice.invoiced)
  let late = paid_on - due
  if late >= 1
    let c = charges(debt: invoice.amount, days_late: late, reference_rate: reference_rate)
    Claim { due: due, days_late: late, compensation: c.compensation, interest: c.interest }
  else
    none

record Settlement
  capture : ledger.capture.do
  fee     : ledger.processing_fee.do
 
fn split(lines: list[Line] count >=1 <=10, discount: money[USDc] range >=0USDc <=10_000_000USDc) -> list[Share] total
  map(running_totals(lines, l => l.amount), r =>
    Share { label: r.item.label, share: discount_share(discount: discount, before: r.before, upto: r.upto, total: r.total).share })