Versioned policies, fingerprints, append-only evidence

Why an agent-written system needs this more than a hand-written one

The core rule is one sentence: CRM state is deterministic; AI agents interpret the user's intent and compose the system, but state changes pass through services and workflows (ARCHITECTURE.md).

A hand-written system keeps part of its rules in the memory of the person who wrote them. Six months later somebody asks why a deal was approved, and there is a human to ask. A system composed by a coding agent has no such author, and the agent that wrote it does not remember. So the rules have to be in artifacts a reviewer can diff and a machine can verify: a versioned policy, a fingerprint, a named migration, a step-level trace, an audit event. Every mutation goes through a module service or a named workflow and leaves an audit event and a step-level trace behind it (C-16), and preserving validation, actor identity, audit and trace is one of the repository's non-negotiable rules rather than a convention.

This is also why the same architecture insists that generated infrastructure is not generated behaviour. Manifests generate migrations and adapters; business logic stays explicit, reviewable source (ADR-006, ADR-011). There is no interpreter over a config format to read when you want to know what the system decided.

A version is a fingerprint, not a commit

ADR-015 puts it directly: git history alone is not runtime policy versioning. Every scoring-model, routing-policy, enrichment-provider and discount-policy version carries a deterministic SHA-256 fingerprint of its canonicalized source. A core migration adds a definition_versions table, and startup inserts-or-verifies each name, version and fingerprint in one transaction: re-registering identical source is a no-op, and a registered version whose source has changed stops the application. Definitions are immutable once registered, and rollback means publishing a new version derived from an earlier definition — v3 carrying v1's rules — never editing history.

What the fingerprint does not capture is stated as plainly as what it does. It covers a definition's own source and its declared config; a handler closing over a mutable outer variable or an out-of-file helper is not captured, because toString() serializes identifiers and not values, and closure analysis is deliberately not attempted. Thresholds and tunables must therefore live in config, which is fingerprinted and passed frozen into every evaluation. Values that cannot be canonicalized — Date, Map, Set, class instances, BigInt, symbols, non-finite numbers, cycles — fail fingerprinting loudly rather than producing a fingerprint that does not describe the definition.

The runs carry their versions with them. Every score run stores the model name, version and fingerprint it executed under plus stable references to its inputs, and persists one contribution row per rule, so a number from last quarter can still be accounted for (C-07). Every quote version stores the discount policy's decision, name, version and fingerprint (C-08).

Atomicity, and the outbox named precisely

ADR-012 was written after two real gaps were found rather than imagined: the workflow engine ran steps with manual compensation and no outer transaction, and generated services emitted domain events as each savepoint released, so a subscriber could observe a half-applied multi-step action. An action's business writes now run inside one BEGIN IMMEDIATE transaction with generated-service savepoints nested inside it — all writes commit or none do — and the event bus installs a transaction-scoped outbox on Node's AsyncLocalStorage. Events are queued inside that scope, dispatched only after the commit, and dropped on rollback or on a throw. The workflow trace is written after the transaction resolves, so a failed action still leaves a record (ADR-011).

The ADR then names the thing precisely, and this page repeats the name rather than the benefit: this is a transaction-scoped in-process event buffer, not a durable transactional outbox. Events live only in memory until the flush, and a process crash after the database commit but before the flush loses delivery. In-process subscribers are the intended consumers. A persistent outbox is required before these events can back remote integrations, and none is claimed.

Schema history is append-only too

A generated module that already holds rows gains a field, a status or an index by an explicit revision bump. A changed schema at the same revision is refused and names the field; an identical schema with a bumped revision is refused; skipping a revision is refused, so each step has its own reviewable migration. The factory then appends exactly one migration for the difference, and the next boot runs it (ADR-019, docs/MODULE_EVOLUTION.md, C-19).

History is not rewritten. The create migration keeps its original identity forever and is never regenerated from a newer manifest, because its checksum is recorded in every database that ran it; an edited applied migration stops the next boot. The module.state.json file that records the last generated definition is checked in deliberately — it travels with the source, is reviewable in a diff, exists before any database does, and is identical in every environment — and a hand-edited one is refused, because its fingerprint and every migration checksum must match what they describe.

What v1 refuses is the list of things that could lose or silently reinterpret stored data, and every refusal happens before any file or database write: removing or renaming a field, changing a type, narrowing an enum, adding a required or unique field, changing unique or a reference target or delete rule, renaming a table, and rebuilding a table another table holds a foreign key into. There is no data transformation, no default backfill, no arbitrary SQL hook and no field split or merge. If you need one, you write and review it yourself.

Evidence you can break on purpose

Determinism claims are easy to write and hard to check, so five of them can be removed on purpose in one command. Each mutation deletes exactly one rule this project makes in public, runs the suite that is supposed to defend it, and reports which named test caught it — in about two seconds, with every edit restored in a finally block and the restoration verified byte-for-byte (C-23, docs/FALSIFY.md). One of the five is definition-version-immutability: with it removed, a scoring model or discount policy could change behaviour while keeping its version, so every historical decision citing that version would now cite something else.

The same discipline shows up in what the domains persist. Delivery records what it consumed as append-only time and expense evidence, costed server-side by a versioned fingerprinted policy, with a reproducible contribution estimate (C-12). A submitted quote version snapshots everything needed to reproduce the commercial decision, and a later catalog sync leaves every existing quote version byte-identical (C-08).