Open Standard · Working Draft
mekaniskt·kontrakt

Requests for comment  ·  RFC 0007

The verb set and its register

A closed vocabulary only pays off if each word means exactly one thing and reads in the register of the people who sign. This RFC puts the whole naming question on one decision table - collapse emit and notify into issue, rename payload to document, make staged pool movements compositions of one movement verb, list the engine's undeclared builtins - and raises one the standard's own section title gets wrong: two spellings of the guard, with inverted polarity.

STATUS
Open for comment
TOPICS
Naming, one word one meaning, legal register, emit vs notify, staged pool movements, undeclared builtins, guard polarity

This is a request for comment, not part of the specification. The syntax is a strawman and much of it is pseudo-code; it exists to be argued with, not adopted by default.

Two tests every verb must pass

  1. One word, one meaning. Two verbs for one act is a bug; one verb for two acts is a worse bug.
  2. The register of the reader. A public-sector lawyer signs this document. check, reserve, release, record, notify, escalate are words she uses. emit, payload, flatten are words from our world - each has to earn its jargon or be replaced.

One fused verb was already removed from the registry for failing the first test. This RFC applies the same discipline to everything that survived that pass - as one decision, because a vocabulary decided piecemeal is a vocabulary that churns the same files repeatedly.

The decision table

Today Proposal Note
emit and notify issue Two verbs, one act: put a document on a declared out-port. issue is the legal verb for exactly that - issue an invoice, issue a notice, issue an instruction. notify X "..." becomes issue notice.emit to: X. (serve is the alternative for notices, but one verb is the point.)
payload document It is a document, and the whole thesis is that documents already won. “Payload” is transport vocabulary in a design that insists transport is not its business.
record <reg>.<field> = <v> set <status> -> <value> on a declared status cell record currently means both append a row and set a field. With status cells declared (RFC 0004), record keeps exactly one meaning.
latch (the proposed cell) status “The status of the financing condition” is the clause; latch is electronics. The transition table already carries the one-way property.
reserve / draw / release named compositions over move <n> <pool>.<stage> -> <pool>.<stage> Three core verbs for one mechanic - a staged movement. Keep the words, because a finance officer reads encumbrance vocabulary on sight, but as named compositions rather than three primitives.
draw pools an explicit operand The only verb in the language with no operand. It means “commit every reservation in scope”, which is exactly the implicitness that RFC 0008 forbids: both legs, always named.
moves / copies / borrows in the flow block move / copy / borrow Third-person inflection is a second token for one node.
within doing three jobs within (time) / in (membership) / during (scope) Decided in RFC 0005; listed here because the sweep must carry it.
rate-at(rate, period) versus rates.senior at line.period at is the authored surface; rate-at is the internal node - documented as a pair Two spellings live in two normative documents today. Surface/internal pairs are fine; undocumented ones are not.
pool-remaining(pool) list it as an accessor Legitimate, and missing from the file that claims to be closed.
deliveries-unbilled(item) remove from the engine; decompose into register combinators Domain logic fused into the machine - the same sin as the fused pricing verb, one layer down.
mark ... paid record / set Already forbidden by the registry, and still present in the standard’s own worked example.
check <cond> else reject and if <cond> -> reject check only See below.

The one the review missed: the guard has two spellings, with inverted polarity

The standard’s section on minimalism is titled “Why if + which is enough”, and the original framing was “if statements, which statements”. But the registry makes check the canonical guard and demotes if to sugar compiling to the same node. So the headline slogan names a keyword the registry treats as secondary.

Worse than untidy - the two forms have opposite polarity:

check payload.total <= limit  else reject over-limit   # assert what MUST hold
if    payload.total >  limit  ->   reject over-limit   # trigger on what MUST NOT

Both compile to one node, and inverting a comparison by accident is the easiest mistake available in a signed document. Two spellings with inverted polarity for one construct is a footgun in a language whose entire pitch is that it cannot surprise you.

Proposal: keep check, drop if from rule bodies, retitle the section “Why check + which is enough”. The slogan loses nothing - check is more legible to a lawyer than if, because it states an obligation (“check that the price matches”) rather than a branch. if survives where it already belongs: threshold legs in the approval table, which the grammar renders as a decision table anyway.

The sweep, sequenced

One decision, then one coordinated pass, in this order, so nothing is ever half-renamed:

  1. The registry - the yardstick moves first.
  2. Parser, schema and tests - token table, statement kinds, formatter, then the suite green. The parser is small today, which is precisely why this is cheap now.
  3. The worked contracts and modules - mechanical, and they are the de-facto grammar, so they must not lag.
  4. The standard’s text - including the worked example and the section title.
  5. The surface grammar - folded into the registry pair per RFC 0011.
  6. This site - re-port every affected page, so the published vocabulary changes in one deploy rather than gradually.

Rule for the sweep: no compatibility aliases. A signed document with two spellings for one act is the disease; shipping both “for a transition” would institutionalise it. Before 1.0 is exactly when a standard may rename cleanly.

Honest creaks

  1. issue loses a distinction some drafters like. In legal English a notice is served, an invoice is issued, an instruction is given. Collapsing to one verb trades a little idiom for one-word-one-meaning; the rendering can restore the idiom in prose, since a projection is allowed to be more fluent than its source.
  2. status loses the one-way connotation latch carried. The transition table restores it explicitly - and if that table ever becomes optional, this trade goes bad.
  3. Renaming a published vocabulary costs something: this site is live and its pages quote the old words. Cheap today; dearer every week the corpus grows.
  4. Staged movements as compositions is a small readability loss in raw source - a reader follows a name to its definition instead of reading a primitive. The module system exists for exactly that indirection, but it is indirection.
  5. The sweep only stays cheap while nobody has implemented against the standard. That window closes by itself.

This RFC is exploratory. It is published as a basis for discussion, not as normative text; where it touches the standard, the standard governs until a decision is recorded.