a73x

d8888d14

docs: two assumptions the narration work rests on

a73x   2026-08-11 18:44

Commit message
docs: two assumptions the narration work rests on

Mid-pass narration is commentary that cannot outlive its pass, and exposure
counters are honest exactly as far as an agent's uptime. Both are load-bearing
readings of the observability work: the first is why a report row may exist
for unfinished work, the second is why the console can answer a datagram
question without a metrics store.
docs/assumptions.md
Old New
@@ -528,3 +528,27 @@ one principal, and every client path (`eitri ssh`, the console recipe, the
528 manual flow) dials that name with `StrictHostKeyChecking=yes`. False if a 528 manual flow) dials that name with `StrictHostKeyChecking=yes`. False if a
529 deployment ever fronts the gate at a second name — that needs a second 529 deployment ever fronts the gate at a second name — that needs a second
530 principal on the cert, not a second address in the config. 530 principal on the cert, not a second address in the config.
531
532 ### Narration is commentary, not state
533
534 A creating VM's `status_detail` is published from inside a running reconcile
535 pass — the one moment the agent knows it is 1.2 GiB into a download — and the
536 pass's own result lands on top when it ends, so nothing said mid-pass can
537 outlive the pass that said it. Underpins letting a report row exist for work
538 that has not finished without weakening the level-triggered contract: the row
539 carries the same address and host key the final row would, and a v0.0.5 agent
540 that never narrates produces exactly the old silence. False if anything ever
541 reads `status_detail` to decide — it is written for eyes, dropped on
542 completion, and absent on any agent that predates it.
543
544 ### Exposure counters start at the agent, not at zero forever
545
546 An exposure's session counts — the active gauge, and the cumulative refusals
547 and drops — live in agent memory and reset when the agent restarts. Underpins
548 answering "did the datagram arrive" from the console without a metrics store:
549 a counter that survives rebinds but not restarts is enough to read a live
550 incident, and the console labels the totals "since agent start" so a reset
551 reads as what it is. The counters ride a nested message, so an agent that
552 never counted stays distinguishable from a port that counted zero. False if
553 anything alerts or bills on these numbers — that needs durable counters with
554 an epoch, which these are deliberately not.