Who did it, who may, and how you would know

The failure this prevents

The same measurement behind freshness. In 20 of 33 residual-harm rows of a preregistered campaign, the decisive warning was on the exact control, at the exact turn, and the model fired anyway.

A warning can be ignored. A required protocol step cannot be skipped silently.

Freshness answers was the world still the one you planned in. This page answers the three questions a reader of the log asks next — and each one used to be answerable only by guessing.

Every transition says which rung filed it

updateState() associates a state delta with a fire through a ladder — an explicit transitionId, a report from inside the handler's own call, a unique signature, the oldest pending fire. Every rung used to write the same shape of row, so a log reader could not tell an observation from a guess.

const fired = session.fire('bank.transfer', { source: 'agent' });
fired.transition.attribution;
// { principal: 'agent', basis: 'caller-asserted', certainty: 'observed' }

session.updateState({ balance: 40 });          // nothing named this delta
// the row is now { principal: 'agent', basis: 'queue-order', certainty: 'inferred' }

certainty grades the association between the record and the motion — never an identity, and never a value. caller-asserted is observed because the library watched the call come through its own door; who was behind that door is your word, which is what ASSERTED is doing in the name.

Certainty only ever goes down. A fire is stamped when it happens and settled later by a report, and the row's honest claim afterwards is the weakest link in that chain. A fire closed by FIFO is an inferred row whatever door it came through; a fire whose action an anchor guessed stays inferred however precisely you then name the row. An upgrade path is a laundering path.

attributionPolicy: 'strict' — refuse the guesses

map.createSession({ node: 'bank', state, attributionPolicy: 'strict' });

Exactly two rungs change, and nothing else moves:

• queue-order is never used. Arrival order is not evidence of anything.
• signature-match must be unambiguous. The default asks do one pending fire's declared writes all appear here? Strict asks a second question: could anything else have produced this? A second pending fire whose writes merely overlap the delta is a plausible source too, so strict requires the delta to touch exactly one candidate at all.

The stamp itself is unaffected by the switch: every transition carries its attribution in both modes, because disclosure is never a policy.

principalPolicy — who may perform this

Three facts that are constantly mistaken for one, kept in three fields.

'transfer': {
  does: 'Transfer the balance',
  writes: ['balance'],
  principalPolicy: {
    mayInvoke: ['human'],          // ACTOR IDENTITY  — the only half enforcement gates
    decisionOwner: 'human',        // DECISION OWNER  — disclosure, never a permission
    requiresHumanApproval: true,   // CONSENT STATUS  — a recorded yes is required
  },
}

map.createSession({ node: 'bank', state, enforcePrincipalPolicy: true });

session.fire('bank.transfer', { source: 'agent' });
// { ok: false, reason: 'PRINCIPAL_NOT_ALLOWED', affordanceId: 'bank.transfer',
//   required: ['human'], attempted: 'agent' }

The refusal names the requirement, because an agent told only no tries again, while an agent told a human must do this hands it to the person. Nothing about the world changes this one, and the served sentence says so rather than inviting a retry.

Two vocabularies, one bridge. A record files an act under a principal ('user'); a policy names a kind of actor ('human'). mayInvoke: ['user'] is refused loudly at both authoring doors, with the correction in hand — ignoring it would silently lock a person out of their own control. And mayInvoke: [] is refused too: an action nobody may ever perform is an action not to declare.

It never refuses reality. The app self-reporting motion it already performed (invoke: false, the record-only DOM sensor) passes untouched.

observability — how would anyone see this happened

One word, next to the action. Declared, never inferred: the library does not read your handler, watch the DOM, or promote a writes list into an answer.

'pay': { does: 'Pay the invoice', highEffect: true, writes: ['paid'], observability: 'external' }

map.createSession({ node: 'shop', state, effectPolicy: { highEffectRequiresVerify: true } });

session.fire('shop.pay', { source: 'agent' });
// { ok: false, reason: 'EFFECT_NOT_VERIFIABLE', affordanceId: 'shop.pay',
//   needs: 'postcondition', observability: 'state-delta' }

needs says which half is missing — 'observability' when you declared nothing, 'postcondition' when you declared something that is not a check. The audience is you, and the served sentence tells the model that plainly instead of sending it looking for a workaround it does not have.

observeEffect — the app hands in what only it can see

A payment clears at a processor, a job finishes on a queue, a letter is posted. The browser sees none of it, so the honest answer used to be 'unobservable' forever.

const fired = session.fire('checkout.pay', { source: 'agent' });
// …the webhook arrives, minutes later…
session.observeEffect(fired.transition.id, {
  source: 'stripe-webhook',
  status: 'performed',
  evidenceRef: 'evt_1P2x…',
});

• First report settles; every report is kept. A later one — a reversal, a second source — is appended to transition.observations, and settled: false says the receipt it did not rewrite.
• It moves no state. effectVerified stays honestly 'unobservable': no report exists to check the declared writes against, and that has not changed because somebody said the work was done.
• It still asks your own verify contract. A report from outside is not a licence to skip your own check.
• It is a fourth settling door. A single-flight hold clears on it, and howToSettle names it.

The served answer says who answered

effectStatus: 'performed' is the same word for a handler the library watched run and for a sentence handed in about a processor it cannot see, so did_it_work serves the difference:

{ "effectStatus": "performed",
  "settledBy": "external-report",
  "reportedBy": "ops-desk",
  "evidenceOnRecord": true,
  "settledByMeans": "The word above came from OUTSIDE this client: a source the app named reported this action's outcome, and this library recorded that report without checking it. …" }

Names and presence only. The evidenceRef itself never crosses — the library does not follow it, so quoting it would dress a pointer up as a check. You hold it; read the trail with session.observationsOf(transitionId).

What none of it says

• No value crosses. Action ids, actor kinds, key names, and one label you wrote, capped.
• An acknowledgement, an approval and a report are acts, never understandings. Each proves a protocol step was performed. None is evidence that anybody read a value, weighed a risk, or comprehended a consequence.
• A refusal is your declared response to a mechanical fact, not the library's opinion about the plan.

The full law, including the alternatives that were considered and refused, is in docs/design/attribution-authority-and-evidence.md.