Glossary
Glossary
The design vocabulary of the mechanical contract - one line per term, with the prior art beside it.
The artifact
| Term | What | Why it matters |
|---|---|---|
| mechanical contract | our artifact: a signed contract a dumb machine can run | Deliberately boring anti-“smart contract” brand: if/which rules over declared state, typed ports, receipts, idempotency. |
| mk | the prefix/extension: Mekaniskt Kontrakt (mechanical contract) | Used everywhere: .mk files, mk-core, mk-se-public, mk-envelope, contract ids (mk-se-2027-000042). Yes, .mk collides with Makefiles; a signed contract is not going to be confused with a build script. |
| port | typed entry/exit point of a mechanical contract | The capability manifest: what documents may flow in/out (invoice.in, allocation.request…), who may submit, in which standard format. Absent port = prohibition. |
| receipt (judgment-level) | signed, hash-chained proof of execution per submission | Carries rule trace + state hashes; accepted AND rejected submissions get one. Rides the Peppol MLR pattern one level up. |
| idempotency key | client-supplied submission-id (IETF Idempotency-Key pattern) | Resubmission returns the original receipt; state moves exactly once. Stripe/PayPal practice, being IETF-standardized. |
| envelope / body (mk) | universal signed wrapper + typed payload, for every message | mk-envelope (ids, hashes, chain, verdict ENUM, seal) is mk-core’s forever; the body (rule trace, amounts) is schema’d per port + version. Verdict in envelope, judgment in body -> body detachable via body-hash = OSL 31:16 redaction falls out of the grammar. Prior art: Peppol SBDH, ISO 20022 BAH, EDIFACT UNB/UNH, JOSE, VC “enveloping proofs”. |
| mk-core / profiles | the mechanical contract’s universality architecture | Jurisdiction-free core (party, pool, cadence, approval, escalation, artifact, receipt); profiles bind law + terms: mk-se-public (LOU/OSL/attest), mk-se-b2b (two ABs, räntelagen), mk-dk/mk-eu later. Profiles constrain, never extend computation. Bar: the two-person-AB test. |
| template / instance (mk) | contract with unbound parameter slots / genesis event binding them | The million-customer B2C shape: one governed template artifact (hashed, versioned), instances = cheap parameter tuples + tiny logs. Instance pins template hash forever -> “we updated our terms” = per-instance amendment offer, never silent rewrite. Prior art: Daml template, ISDA Master + confirmations, standardavtal + orderbekräftelse. |
The machine
| Term | What | Why it matters |
|---|---|---|
| accumulator | counted state in a mechanical contract (pools, balances, cadence buckets) | What lifts the model beyond a plain FSM: finite control + accumulators; changed only by declared effects, so safety stays decidable. Formal home: Petri nets/VAS. |
| cadence | rate limiting as a contract primitive | “Fakturering månadsvis”, “30 dagar netto”, “max N avrop/dag” as executable guards (token-bucket over event timestamps, no wall clock). Works per-month down to per-second; also catches invoice splitting. |
| contract as automaton | Flood & Goodenough 2015/2022 | Academic proof a contract is a deterministic finite automaton; the memoryless special case of the mechanical contract’s machine class. |
| optimistic execution (mk) | lock-free evaluate-then-conditionally-append runtime | Read state (no locks), evaluate purely, append iff log head still = state-before (the receipt’s state hash IS the ETag), else re-fold + retry. Safe because evaluation is pure - a lost race costs a redo, never a wrong verdict. Prior art: Kung-Robinson OCC, event-store expectedVersion, Tango/Corfu, Calvin, FoundationDB. |
| fork / join (mk) | concurrency without threads | Fork = one event opens many obligations (parallel branches = open expectation-register entries). Join = conjunctive guard over the log: when all-of(...), any-of (OR-join), N-of (quorum). Waiting = an unfired guard; can’t deadlock because nothing runs. Dead joins = Petri coverability lint findings. Prior art: Petri nets, join calculus, BPMN gateways, Harel orthogonal regions. |
heartbeat / at-least |
optional liveness cadence: the mirror of at-most |
NAMED ticks with own rhythms + calendar windows (tick.daily, tick.business within working-hours) forcing derived predicates (overdue, timeouts) to surface per scope. Timeouts are PREDICATES over (log, as-of), never clocked events - ticks bound staleness, cannot change outcomes, and each tick’s own absence is log-visible and escalatable. |
| expectation register | derived view of everything currently open and dated | Due obligations in window, awaited ladder rungs, reservations nearing expiry, alert thresholds, escalation deadlines - one queryable store. NOT stored state: a view recomputed by the fold, so it can never disagree with the receipts. |
| executor as a party | ERP/bank/rail modeled as a counterparty with ports + obligations | The contract signals, the executor executes - and owes acks/results on declared windows, judged like any supplier. Contract = ledger of expectations vs confirmations = the singular view of in-flight money. POETS thesis, on purpose. |
expectation ladder (expect) |
every emission declares its confirmation rungs | Ack ≠ execution ≠ outcome: pain.001 -> pain.002 ACCP (acked) -> camt.054 (settled) -> camt.053 (reconciled ground truth). expect ... within = due within pointed at the executor; missed rung throws to escalation. Two-generals honesty: heal by idempotent retry + reconciliation, never stronger promises. |
Money, data, types
| Term | What | Why it matters |
|---|---|---|
| reserve (primitive) | staged pool allocation: available -> reserved -> disbursed | Encumbrance accounting as an event effect; optional expiry auto-releases by event math. Also the try-leg of cross-contract TCC. |
| due / claim (primitives) | schedules as declared obligations + anyone-may-wake | “Allocate now, disburse later”: due disburse y by x is judged, never executed (no clock) - date-due or event-due; betalplan/vesting = schedule artifacts. Claim = untrusted alarm clock (Marlowe timeout lesson); breach + dröjsmålsränta run from the log’s due date, not claim time. |
| declared storage / shape | the closed data surface of a mechanical contract | Every storable field declared with a type: pools, typed registers, genesis bindings. Absent field = prohibited memory (mirror of absent port = prohibited flow). Two provenances: bound-at-genesis (immutable) vs accumulated-by-events. Disclosure policies enumerate over a CLOSED list. |
| move / copy / borrow | declarative data-ownership verbs on every flow | Move = linear transfer (money, title, receivables; Petri tokens ARE move semantics; retention of title = guarded move). Copy = receipted share, irreversible. Borrow = scoped reference (artifact pin/track, disclosure scopes). Prior art: linear types (Girard/Wadler), Rust ownership, Incoterms, GDPR Art 28 DPAs. |
| domain types (mk) | closed type vocabulary; no naked primitives, no floats | money (ISO 4217 + rounding; Fowler’s Money pattern), quantity<unit> (UN/ECE Rec 20), id<kind> (equality only, kinded), party (ISO 6523), opaque (hash-equality; the type of sealed data), lookupOf<K,V>/tableOf<shape> (artifacts/registers), linear modifier (spend-once). Core adopted from EN 16931 semantic data types; units/currencies propagate through arithmetic (F# units-of-measure). |
| pool flavors | fungible-bounded / named / human / unbounded | Every industry’s allocatables: default capacity pools (hours, SEK, tonnes, kWh), capacity-1 identity pools (a specific house/machine/person; double-booking = boundedness), human = role pool or named person + calendar window + competence register checks, capacity unlimited = löpande avrop/all-you-can-eat (still counted+receipted, never exhausts). No industry vocabulary in the core. |
People and process
| Term | What | Why it matters |
|---|---|---|
| approval leg | straight-through vs in-the-loop paths in a mechanical contract | Attestordning as signed contract terms: STP under threshold, 1 or 2 attestants above. Approver = human eIDAS role OR agent (signing key + hashed policy). Machine waits, never decides. |
| escalation (primitive) | throw/catch/finally for contracts | Eskaleringstrappa with a runtime: conditions throw, declared levels catch (notify -> suspend -> mediation -> termination, deadlines all the way up), survival clauses = finally. BPMN 2.0 escalation events are the semantics prior art. |
| fault / FAULTED | machinery failure as first-class: never judged on the merits | FAULTED ≠ REJECTED: moves no state, consumes NO cadence counters, submission-id stays retryable. Every fault names its at-fault domain (submitter/import/host/contract-logic) - host faults suspend blame (kontrollansvar/CISG 79 as executable carve-out). Handling declared per port/import: retry/fallback/park/escalate/halt + circuit breaker as a signed term. Prior art: Erlang/OTP supervision, Nygard breaker, DLQ, wasm traps, RFC 9457. |
| selective disclosure | reveal chosen fields of a signed document, verifiably (SD-JWT salted hashes, BBS+) | The v2 answer to sekretess: contract public in structure, sealed in parameters; disclosed subsets verify against the signature. Same primitive as the EUDI wallet stack. |
| disclosure policy | per-audience field visibility declared IN the contract | Public/counterparty/mediator/court views + per-escalation-level scopes, signed like everything else. The sekretessprövning, pre-declared. |
Composition and evolution
| Term | What | Why it matters |
|---|---|---|
| artifact (mechanical contract) | external versioned table/variable, hash-referenced | Rate tables, price lists, calendars, attest tables, index series - one mechanism (fixings generalized). Carries its own update contract: who proposes/approves, cadence, bounds. Illegal update = rejected, never becomes a version. |
| pin / track | artifact binding modes | pin v2 = updates reach the contract only via amendment; track latest-approved = updates flow if they passed the artifact’s own governance AND the contract’s bounds. Shared artifacts (Adda prisbilaga) = one table, hundreds of referencing contracts. |
| trust anchor (artifact) | how a referenced artifact is believed | Hierarchy: publisher seal ON the data (eIDAS XAdES/JAdES - survives replay) > HTTPS/cert pinning + signed ingest attestation (today’s SCB reality) > declared trust: none. Store artifacts + signatures, never URLs alone. |
| binding (universal) | THE one attachment verb, everywhere | Genesis binds parameters (§6.3), pin/track binds artifacts (§5), imports bind implementations (§7.6, strict linking), profiles bind law+terms (§6), windows bind calendars (§3.6). One mechanism: name -> hash-identified thing, under declared governance. Late-binding with receipts instead of link-time mystery. |
| may call (contract port) | a port whose from: names a contract, not a party |
Contract-to-contract topology, declared: ramavtal->avrop (shared pool draws), back-to-back, factoring. Trust = pinned contract hash + offline-verified judgment receipts; messages are enveloped documents, never RPC. Transport-agnostic: ports declare payload + sender, never a pipe (§7.4; profiles name a default rail, AS1-AS4 style). |
| call-out (primitive) | contract calls an external service, parks, resumes on response | Emit request + §3.6 expectation + verdict PENDING(awaiting) + response in-port; resume = the fold reads one more event. Latency-blind by construction (2 days ≡ 20 ms modulo timestamps). Response = signed input (oracle/fixing pattern), guarded not obeyed; approval = the human special case. Prior art: durable execution (Temporal), Step Functions task tokens, BPMN message events. |
| import manifest | external functions declared like wasm imports | Tax/tariff/freight math BY DESCRIPTION: signature (input/output shapes) + mode: inline|deferred (must state park?) + has_side_effects (auto idempotency key + declared compensation) + binding (hash-pinned wasm artifact OR oracle party) + result guards. STRICT LINKING: any signature mismatch -> contract refuses to activate (wasm instantiation rule). Core stays if/which; industries import their math. |
| saga / compensation (mk) | cross-contract transaction model: ACID inside, sagas between | No distributed ACID across autonomous parties (2PC rejected; Canton = the declined shared-domain road). The compensating documents already exist as standards: kreditfaktura (EN 16931 type 381), pacs.004 payment return. Receipts embed foreign receipt hashes -> saga completion/compensation is provable by replay. |
| no-middleware rule | governing/proxy/decorator contracts: refused, permanently | Interception breaks replay (sibling-log entanglement = shared ledger via side door), hides terms (invisible governor = the silent-term fraud we hunt), needs 2PC, and its prior art is the Solidity-proxy exploit graveyard. Governance flows DOWN via declared bindings, UP via receipts, never SIDEWAYS. Lex superior doesn’t intercept either. See §7.3b. |
| transform (recipe) | THE amendment mechanism: V2 = apply(V1, transform) | STANDALONE artifact (never in the contract): signed declarative delta from a closed verb set + init data + state migration (conservation linted). From-hash guard = once-only + right-version, structurally. Self-verifying Hoare triple: {precondition} ops {postcondition} + doctest-style example tests riding inside - failing tests = unapplicable, FAULTED adoption, nothing half-migrated. Inline imports only, strict linking (OR FAILURE). Adherence per instance (ISDA Protocol, hashed). No down-migrations. |
Prior-art shelf
| Term | What | Why it matters |
|---|---|---|
| Ricardian contract | {prose, parameters, code} under one hash (Grigg 1996) | The legal form for protocol artifacts: signed prose + executable spec bound as ONE document; neither can silently diverge. |
| POETS | Process-Oriented Event-driven Transaction Systems (Henglein et al., DIKU 2009) | ERP = append-only event log + contracts as expected-transaction specs + derived reports. The architecture of “the machine”; never productized. |
| CSL | Contract Specification Language (Deon Digital, Copenhagen/Zurich) | Commercial descendant of POETS/Hvitved: deterministic contract calculus, descriptive-not-executive. Closest technical prior art; on the watchlist. |
| Daml | Digital Asset’s contract language (Canton Network) | Deterministic by construction; rights/obligations/authorization as primitives; scenario tests. In production in finance; no procurement domain. |
| Catala | Inria law-as-code language | Literate pairing: each statute paragraph sits beside the code implementing it; runs French tax/benefit calculations. Model for lawyer-reviewable specs. |
| Rules as Code | RaC (NZ Better Rules, OECD “Cracking the Code”, OpenFisca) | Governments already execute law as deterministic code for taxes/benefits - proves state trust in the approach. Codifies statutes, never agreements. |
| deontic logic | logic of obligation/permission/prohibition (von Wright 1951) | Formal backbone of every legal-contract calculus (CSL, Symboleo); the obligation primitive’s semantics. |
| ISDA CDM | derivatives Common Domain Model | Existence proof that a contract domain can be fully standardized; nobody did it for goods/services. Now open source at FINOS (CDM 6.0, 2025). |