agentfootprint 9.87.1 → 9.89.0

package/dist/lib/time-travel/servedView.js

@@ -0,0 +1,826 @@
+"use strict";
+/**
+ * servedView — the request an epoch was SERVED, rebuilt from what was
+ * committed, plus an honest list of what the log cannot rebuild.
+ *
+ * Role:  Fold. `servedAt` reads a finished run's commit log and returns the
+ *        model-facing request that epoch's call assembled; `receiptAt` reads
+ *        the fingerprint that call left behind. Neither executes anything,
+ *        records anything, or stores anything beside the log.
+ * Reads: a recording, through `epochs.ts` (which log, which index) and
+ *        footprintjs's `commitValueAt`.
+ * Emits: N/A.
+ *
+ * ── THE LAW ────────────────────────────────────────────────────────────────
+ *
+ *     hash(servedAt(k)) === receiptAt(k).hash
+ *
+ * The receipt is minted at the stop, from the values about to go out. The
+ * served view is rebuilt afterwards, from the values that were committed. When
+ * the two agree, the record is complete: everything the model read is derivable
+ * from the trace. When they disagree, something reached the model that the run
+ * never wrote down — and that is a defect in the RECORD, not in the check.
+ * `test/lib/time-travel/receipt-conformance.test.ts` is where the law is
+ * enforced; five real divergences were found by running it and each one was
+ * closed by committing a fact or declaring a gap, never by loosening it.
+ *
+ * ── WHY THE REBUILD DOES NOT RE-IMPLEMENT THE ASSEMBLY ─────────────────────
+ * The joined system string is a local inside the calling stage; it is never
+ * committed, only its pieces are. So the rebuild has to apply the identical
+ * join to the identical records — which is why the join is one exported
+ * function, `composeRequest.ts` · `joinSystemPrompt`, called by the stage on
+ * the way out and by this file on the way back. Same for the framework-field
+ * strip and the staged-refs nudge. A second implementation of any of them would
+ * make this file agree with itself and disagree with the wire.
+ *
+ * ── WHAT A GAP IS ──────────────────────────────────────────────────────────
+ * A `ServedGap` is a fact this view cannot PROVE — because the log cannot
+ * rebuild it, because the recording travelled without the base it folds
+ * against, or because the fact lives past the boundary a receipt is minted at.
+ * It is on the view rather than left implicit because a rebuild that quietly
+ * omits a piece looks exactly like a rebuild that proved the piece was absent.
+ * Naming the gap is what keeps the two apart.
+ *
+ * ── A GAP, NOT AN `undefined` ──────────────────────────────────────────────
+ * When the rebuild cannot recover the conversation at all — a chart that
+ * commits neither `history` nor `messagesInjections`, or a recording whose
+ * fold base did not travel — `servedAt` still returns a view, carrying a gap,
+ * rather than `undefined`.
+ *
+ * The alternative was tried and it is worse. Returning `undefined` withholds
+ * the system prompt, the tool list and the request-only lines, all of which
+ * this recording CAN prove, in order to avoid overstating one field it cannot.
+ * A Lens may omit; it may not deny — and dropping four proved facts to hide
+ * one hole omits more than the hole does. The gap says exactly which field is
+ * unproved, in wording a renderer prints verbatim, and leaves the rest
+ * standing.
+ *
+ * ── A CHART THAT MINTS NO RECEIPT DECLARES, IT DOES NOT MINT ───────────────
+ * `buildReceipt` is called from exactly one place: the agent charts' `call-llm`
+ * stage (`stages/callLLM.ts`). `LLMCall` and the two message-API charts
+ * (`buildMessageApiChart`, `buildAgentMessageApiChart`) run their own `call-llm`
+ * stage, so `epochAt` locates their epochs and `servedAt` rebuilds their views
+ * — but no receipt is minted there, `ServedView.basis` is dropped, and until
+ * 9.88.0 nothing said why. That is the Lens denying: a reader saw a view with
+ * no model on it and no sentence explaining the absence.
+ *
+ * MINTING was the other option and it was refused. The reason that holds is
+ * narrow and applies to the two message-API charts alone: they are exported
+ * chart BUILDERS run on a consumer's own executor and their deps carry no run
+ * id, so their hashes could not be salted. It is NOT true of `LLMCall`, which
+ * owns its executor and mints a run id exactly as `Agent` does — a paragraph
+ * here said otherwise until 9.88.0, in a sentence a renderer printed verbatim.
+ *
+ * A SECOND REASON WAS RECORDED AT THE TIME AND DOES NOT HOLD, and it is left
+ * here refuted rather than deleted so nobody argues it again:
+ * `Receipt.cache.transform` was said to have no honest value on a chart that
+ * runs no cache strategy, because `'unchanged'` would claim a strategy
+ * returned what it was given when none ran. But `Agent` runs with no cache
+ * strategy record exactly that today — `buildReceipt` compares the request it
+ * was handed against itself and writes `'unchanged'` — and
+ * `receipt-conformance.test.ts` asserts it and calls it correct. So NO
+ * recorded reason survives for `LLMCall`: it has the salt and it needs no
+ * fourth enum value. It runs its own `call-llm` (`LLMCall.ts` · `callLLM`),
+ * that stage does not call `buildReceipt`, and until somebody makes it the
+ * absence is DECLARED rather than argued away.
+ *
+ * So the absence is DECLARED: `no-receipt-on-chart` names the fields only a
+ * receipt carries and says what follows for them. The rebuild never needed the
+ * receipt to work, and `servedAt`'s own `@param` is true about `LLMCall`
+ * because the view it returns declares what it has and what it has not.
+ *
+ * ── AND THE CAUSE IS A VALUE, NOT A LIST INSIDE A SENTENCE ────────────────
+ * That gap's sentence used to end with the causes that produce it. That is
+ * PROSE DOING DATA'S JOB: a frozen constant cannot know what happened at the
+ * site it is printed beside, so it listed the causes somebody could think of —
+ * and a path it had never accounted for, the shape refusal in `readReceipt`
+ * below, made the count AND the verdict false with nobody editing the string.
+ * The discriminating fact moved to the one place that holds it: `readReceipt`
+ * reports whether the receipt key held nothing or held something it refused,
+ * and {@link ServedGap.cause} carries that answer out.
+ *
+ * ── AND THEN THE MECHANISM WENT TOO (9.88.0, sixth round) ─────────────────
+ * Five rounds tried to write TRUE mechanism sentences, and the rate of new
+ * falsehoods did not fall. The sixth round applied one question to all ten
+ * printed sentences — COULD THIS BECOME FALSE WITHOUT ANYONE EDITING IT? —
+ * and nine could, two of them being false the day they shipped. Exactly one
+ * could not, and it is the one that makes no claim about code at all:
+ * `UNGAPPED_FIELDS.gaps`, which says what its field MEANS inside the account.
+ * Nothing outside that sentence can falsify it.
+ *
+ * So the conclusion was not to write mechanism sentences better. It was to
+ * STOP WRITING THEM. A printed gap sentence may now say only: which fields it
+ * covers; what they mean on this view for the person reading (unproven,
+ * possibly short, absent-means-unknown, unchecked against what went out); and
+ * what to do differently. It may not name a module, a function, a key, a
+ * version, a chart, a strategy, an option, or any mechanism at all. If a
+ * sentence needs one of those words to be understood, it is explaining WHY the
+ * gap exists, which is not the printed sentence's job.
+ *
+ * NONE OF IT IS LOST. The mechanism is in the comment above each catalogue
+ * entry, where a maintainer reads it and review catches its rot, with the
+ * `file · symbol` pointers that are correct there and banned in printed prose.
+ * The cause is already data. The docs may explain the mechanism at length,
+ * because a doc is versioned with the code and its reader can open the file.
+ * The rule is enforced by `test/helpers/gapProseClaims.ts`, which on the
+ * printed surface admits no code-shaped token and no mechanism verb — close to
+ * a whitelist, and a whitelist has no synonyms.
+ *
+ * ── AND THE SEVENTH ROUND MEASURED WHAT THE SIXTH HAD CLAIMED ─────────────
+ * The sixth round said the reduction ENDED the class: a sentence with no code
+ * claim in it cannot go false when the code changes. That was checked, sentence
+ * by sentence, by driving a real run for each one — and it is not true. TEN of
+ * the eleven reduced sentences still make a claim a code edit falsifies. The
+ * one that does not is `UNGAPPED_FIELDS.gaps`, and it survives because it is
+ * SELF-REFERENTIAL: it says what its field is inside the account, not anything
+ * about the request. That is not a shape the other ten can copy. "May be
+ * SHORT", "absent means unknown", "the list is complete and the schemas are one
+ * short" are all claims about how the rebuild behaves, and the rebuild is code.
+ * The reduction changed the VOCABULARY of the claims, not their CLASS.
+ *
+ * The same round proved what does close it, by finding a BRAND-NEW false
+ * sentence in the round written to end false sentences: `no-run-log` shipped
+ * "The fields below could not be fully recovered here", and on the ordinary
+ * view that raises it nothing is lost at all. No rule caught that. A run
+ * caught it.
+ *
+ * SO THE POSITION IS: a gap sentence MAY make a code claim, because a sentence
+ * that makes none cannot inform. Every claim it makes is ASSERTED against a
+ * real view in `test/lib/time-travel/gap-sentences.test.ts`, which drives one
+ * run per entry and checks the claim rather than the firing. The prose rule
+ * STAYS — it keeps the sentences short and readable and stops the enumerations
+ * coming back — but it is not what makes them true. The assertion is, and its
+ * blind spot is honest and small: a claim nobody wrote an assertion for.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.receiptAt = exports.servedViews = exports.servedAt = exports.UNGAPPED_FIELDS = exports.SERVED_GAPS = void 0;
+const composeRequest_js_1 = require("../../core/agent/composeRequest.js");
+const stagedRefs_js_1 = require("../../core/agent/stagedRefs.js");
+const epochs_js_1 = require("./epochs.js");
+const receipt_js_1 = require("./receipt.js");
+/**
+ * The gap catalogue. Exported because a reader that renders a served view
+ * renders its gaps beside it, and a renderer should print the library's own
+ * sentence rather than invent one.
+ */
+exports.SERVED_GAPS = Object.freeze({
+    'cache-transform': Object.freeze({
+        // MECHANISM (not printed — see the header's rule). A `CacheStrategy`'s
+        // `prepareRequest` is handed the whole composed request after assembly and
+        // hands one back; `buildReceipt` fingerprints the one it was GIVEN. So the
+        // field list is everything a rewrite could have touched, not only the
+        // three `cache.*` fields that DESCRIBE the rewrite — listing those alone
+        // named the report and excused nothing it reports on.
+        //
+        // THE DAY-ONE FALSEHOOD THIS ENTRY SHIPPED WITH, killed in 9.88.0's sixth
+        // round: the printed sentence said "only its INPUTS are on the record".
+        // Three of its own fields are OUTPUTS and are on the record —
+        // `cache.transform` (the verdict of comparing given against returned),
+        // `cache.transformHash` (the digest of what came back when it differed)
+        // and `cache.markersApplied` (the breakpoints the strategy actually
+        // applied, as against the candidates in `scope.cacheMarkers`, which are
+        // the inputs). A sentence describing the mechanism went false about the
+        // mechanism; the sentence below describes only what the fields MEAN.
+        //
+        // This entry is on EVERY view, so it is the weakest claim on the list: it
+        // says the rebuild stops before whatever the request met next, never that
+        // the rebuild got that far. Whether it did is what the other gaps on the
+        // same view say — see the qualifier on `ServedGap.fields`.
+        //
+        // AND BEING ON EVERY VIEW IS WHY IT NO LONGER QUOTES `RECEIPT_BOUNDARY`
+        // (9.88.0, seventh round). That sentence opens "A receipt describes the
+        // request as this library last saw it" — and this entry is printed on views
+        // that have no receipt at all. Measured: an `LLMCall` view carries exactly
+        // `['no-receipt-on-chart', 'cache-transform']`, so the reader was told what
+        // a receipt describes beside a view that has none. The boundary CLAIM is
+        // not lost — the first sentence below is that claim in the vocabulary of a
+        // view, and it is true whether or not a receipt exists. The quote stays on
+        // `provider-defaults`, which fires only where a receipt was read.
+        fields: Object.freeze([
+            'cache.transform',
+            'cache.transformHash',
+            'cache.markersApplied',
+            'system.hash',
+            'system.chars',
+            'system.pieces',
+            'messages.count',
+            'messages.entries',
+            'messages.requestOnly',
+            'tools.names',
+            'tools.schemaHashes',
+        ]),
+        why: 'What reached the provider may differ from the fields below, and nothing on this view ' +
+            'would show it. Where another gap on this view covers one of them, that gap is the ' +
+            'stronger claim.',
+    }),
+    'forced-tool-schema': Object.freeze({
+        // MECHANISM (not printed). Under a `'tool-forced'` output strategy the
+        // synthetic answer tool is added at assembly from a build-time schema that
+        // no stage commits, so `tools.schemaHashes` on the receipt carries a row
+        // the rebuild has no counterpart for. The tool's NAME is a run constant
+        // (`FORCED_OUTPUT_TOOL_KEY`, written by `stages/seed.ts`), which is why
+        // `tools.names` and `tools.forced` rebuild and the schema body does not.
+        fields: Object.freeze(['tools.schemaHashes']),
+        why: 'The schema body behind the forced answer tool is not on this view. Its name is, so the ' +
+            'tool list is complete and the schemas beside it are one short.',
+    }),
+    'provider-defaults': Object.freeze({
+        // MECHANISM (not printed). `buildReceipt` reads `params` off the PREPARED
+        // request — the object `LLMProvider.complete` is handed, after any cache
+        // strategy has had it — so it is the one part of a receipt read past the
+        // strategy, and `cache-transform` deliberately does not name it. What is
+        // still past the record is the vendor: an adapter or SDK can resolve a
+        // final value the port never saw. `params` is also VALUE-CONDITIONAL —
+        // `buildReceipt` writes no key for a dial nobody set — which is the whole
+        // reason the printed sentence has to say what an absent key means.
+        //
+        // THE ONE ENTRY THAT QUOTES `RECEIPT_BOUNDARY`, and it is the only one that
+        // honestly can: it is pushed inside `if (receipt !== undefined)`, so a view
+        // carrying it always has a receipt for that sentence to be about.
+        // `cache-transform` quoted it too until 9.88.0's seventh round, and
+        // `cache-transform` is on every view — including the receipt-less ones,
+        // where the reader was told what a receipt describes beside a view that has
+        // none. Measured: an `LLMCall` view carries `no-receipt-on-chart` and
+        // `cache-transform`, and never this entry.
+        fields: Object.freeze(['params']),
+        why: 'A dial absent below was not recorded; that is not the same as the model running ' +
+            'without one. ' +
+            receipt_js_1.RECEIPT_BOUNDARY,
+    }),
+    'no-fold-base': Object.freeze({
+        // MECHANISM (not printed). Raised when `location.basis` or
+        // `location.runBasis` is `'log-only'` — the recording travelled without the
+        // `initialState` the fold folds against (`getSnapshot({ redact: true })`
+        // hands back exactly that shape: the log travels, the base does not), so
+        // every read can see only what the log itself wrote. A rebuild that
+        // recovered one turn of three reports one; a system prompt it could not
+        // read at all is 0 characters rather than unknown; and `EpochLocation.epoch`
+        // falls back to POSITION when it cannot read the run's committed
+        // `iteration`, which is how a view can call the second turn the first while
+        // that turn's own receipt still says 2.
+        //
+        // TWO bases, so every field the rebuild reads through a fold. The epoch's
+        // own log rebuilds the system prompt, the conversation, the tool schemas
+        // and the wrap-up flag; the RUN's log holds the run constants the forced
+        // tool name and the staged-refs nudge are composed from. Under
+        // 'dynamic-grouped' those are different logs with different bases, and a
+        // gap raised off only the first denied the second.
+        //
+        // THE RULE FOR THIS LIST is mechanical, so it does not go short again: a
+        // field belongs here when the rebuild derives it from `readAtCall` or
+        // `readRunConstant` — both fold over values the log itself may never have
+        // written, so both read absent when the base did not travel. `readAfterCall`
+        // is the THIRD reader and is deliberately NOT on the rule: the only thing
+        // read through it is the receipt, which the call's own bundle commits, so it
+        // is there whatever the base. Naming it made the rule read wider than the
+        // mechanism and put the receipt's own fields inside a gap that cannot touch
+        // them. `system.chars` and `messages.count` were missed on the first two
+        // passes because they are COUNTS of things the list already named, and a
+        // short rebuild makes a count wrong exactly as it makes the thing wrong.
+        //
+        // `epoch` — THE VIEW'S OWN NUMBER — is here for a fourth reason, in
+        // `EpochLocation.epoch`'s own words: a fold that cannot read `iteration`
+        // numbers the epoch by its POSITION instead. Measured on a resumed run with
+        // its base and its `iteration` writes gone, the rebuild called the second
+        // turn epoch 1 while that turn's own receipt still said 2. The RECEIPT's
+        // `basis.epoch` is NOT here and used to be: it is minted live and rides in
+        // the call's bundle, so no missing base can move it. That inversion — the
+        // list naming the number a missing base cannot touch, while the number it
+        // fabricates was excused as ungappable — is what 9.88.0's fourth review
+        // round found.
+        //
+        // THE PRINTED CLAUSE STOPPED NAMING THE RECEIPT (seventh round). It read
+        // "may differ from the one the receipt for this turn carries", and this
+        // gap is raised on views that have no receipt to carry anything — a
+        // base-less `LLMCall` recording gets both gaps at once. The fact a reader
+        // needs is about the NUMBER, not about the witness: it may be the turn's
+        // place in run order rather than the count the run kept. Measured on a
+        // resumed run with its base and its `iteration` writes gone, the view calls
+        // the second turn the first while that turn's own receipt still says 2.
+        fields: Object.freeze([
+            'system.hash',
+            'system.chars',
+            'system.pieces',
+            'messages.count',
+            'messages.entries',
+            'messages.requestOnly',
+            'tools.schemaHashes',
+            'tools.names',
+            'tools.forced',
+            'tools.withheld',
+            'epoch',
+        ]),
+        why: 'The fields below are unproven and may be SHORT: a count can be lower than what really ' +
+            'went out, and a value that could not be recovered reads as empty rather than as ' +
+            "unknown. The turn number below may be this turn's place in run order rather than the " +
+            'number the run itself gave it.',
+    }),
+    'no-conversation-on-record': Object.freeze({
+        // MECHANISM (not printed). `viewOf` reads the conversation from `history`
+        // (the agent charts) or, failing that, from `messagesInjections` (`LLMCall`
+        // and the message-API charts, which have no history at all). Neither
+        // committed ⇒ `conversation` is `undefined` and `asSent` is `[]`, which is
+        // indistinguishable from a call that really sent nothing — hence the gap.
+        //
+        // `messages.requestOnly` is on the list for a second reason: the
+        // staged-refs nudge is recomposed FROM the conversation by `findStagedRefs`,
+        // so a rebuild with no conversation finds no refs and reports no nudge,
+        // which looks exactly like a call that had none.
+        fields: Object.freeze(['messages.count', 'messages.entries', 'messages.requestOnly']),
+        why: 'The turns that went out are unknown, not empty: an empty list here is the absence of a ' +
+            'record, never a record of absence. The request-only lines are unproved with them.',
+    }),
+    'no-receipt-on-chart': Object.freeze({
+        // Exactly the fields ONLY a receipt carries — the ones no rebuild produces,
+        // so with no receipt they are absent rather than short. Everything else on
+        // the view is folded from committed pieces as usual; what it loses is not
+        // the value but the WITNESS, and the sentence below says so, because a
+        // field list cannot.
+        //
+        // MECHANISM (not printed). Raised when `readReceipt` returns no receipt —
+        // either nothing was committed under `RECEIPT_KEY` (a recording made before
+        // the receipt existed, a run with `recordReceipt: false`, or a chart whose
+        // `call-llm` stage mints none: `LLMCall` and the two message-API charts) or
+        // something WAS committed there and was refused for carrying no basis.
+        // Which of the two is {@link ServedGap.cause}, computed at that read.
+        // Everything else on the view is still folded from committed pieces; what
+        // it loses is the WITNESS, not the value.
+        //
+        // THE DAY-ONE FALSEHOOD THIS ENTRY SHIPPED WITH, killed in 9.88.0's sixth
+        // round: the printed sentence opened "No receipt was found for this epoch"
+        // and closed "absent here means unrecorded". Both are false under
+        // `'receipt-shape-rejected'`, where a value WAS found and WAS recorded and
+        // the read refused it. The sentence asserted a cause; the cause is a field.
+        // The sentence below says only what the fields mean, which is the same
+        // under either cause.
+        //
+        // TWO CHANGES in 9.88.0's fourth review round, both of them the same test:
+        // does this gap's MECHANISM cause this field's absence?
+        //   • `basis.epoch` JOINED the list. It is a receipt-only field like the
+        //     other three on `basis`, and with no receipt it is gone with them. It
+        //     used to be named by `no-fold-base` alone, which cannot touch it.
+        //   • `omittedForAttention` LEFT it. It is absent on EVERY view, receipt or
+        //     not — no chart IN THIS LIBRARY supplies it — so a gap about the
+        //     missing receipt was explaining an absence it does not cause, and on a
+        //     view that HAS a receipt nothing explained it at all. It is in
+        //     `UNGAPPED_FIELDS` now, with the reason that is actually true of it.
+        //
+        // AND THE SEVENTH ROUND SCOPED THE PRINTED CLAIM TO THE LEVEL IT HOLDS AT.
+        // It said the absence of these fields is "a gap in the record, never a call
+        // made without them". True of each field AS A WHOLE — a receipt always
+        // carries `params` and always carries a `cache.transform` verdict, so those
+        // containers go missing only with the receipt. FALSE one level down, and
+        // that is the level a reader reads at: measured on an agent that set no
+        // dials, `receipt.params` is `{}` — an absence inside the container that IS
+        // "a call made without one", and `provider-defaults` says so on the very
+        // views that have a receipt. The sentence below claims nothing about what
+        // is inside a field it cannot see.
+        fields: Object.freeze([
+            'basis.model',
+            'basis.provider',
+            'basis.runId',
+            'basis.epoch',
+            'params',
+            'cache.transform',
+            'cache.transformHash',
+            'cache.markersApplied',
+        ]),
+        why: 'Nothing on this view has been checked against what went out. Every field below is ' +
+            'missing as a whole, and an absence among them says nothing about the call — not even ' +
+            'that a dial was left unset.',
+    }),
+    'no-run-log': Object.freeze({
+        // MECHANISM (not printed). Raised on `!location.hasRunLog` — a SUBTREE
+        // handed in on its own, with no run log to read. `readRunConstant` is the
+        // only reader that touches that log, and everything it fetches is a
+        // build-time fact `stages/seed.ts` wrote once: the forced output tool's
+        // NAME (`FORCED_OUTPUT_TOOL_KEY`) and `toolWantsByName`, which
+        // `findStagedRefs` composes the nudge from.
+        //
+        // `tools.schemaHashes` is on the list because the forced tool's NAME is the
+        // run constant: losing it also loses the row the receipt hashes under that
+        // name. The fix a reader has is to pass the whole recording rather than the
+        // subtree, which is what the printed sentence says without naming any of
+        // this.
+        //
+        // THE MEASURED-FALSE SENTENCE, killed in 9.88.0's seventh round. It said
+        // "The fields below could not be fully recovered here" — a claim that the
+        // recovery DID fail. Driven on the ordinary view that raises this gap (a
+        // 'dynamic-grouped' agent with one plain tool, run log emptied), the
+        // damaged rebuild is byte-identical to the intact one: same `tools.names`,
+        // same `tools.schemas`, same absent `tools.forced`, same empty
+        // `messages.requestOnly`. The gap fires and costs NOTHING, and the sentence
+        // told the reader otherwise.
+        //
+        // THE REPAIR IS THE SENTENCE, NOT THE CONDITION, and the reason is that the
+        // condition cannot be narrowed by anything this file can read. What the
+        // missing log would have held is a forced tool's name and a `wants`
+        // declaration; whether the run had either is recorded IN THAT LOG. To fire
+        // the gap only where it costs something, the read would have to consult the
+        // record whose absence raises it. So the gap stays unconditional — it is
+        // the "you cannot tell" declaration, which is what this file is for — and
+        // the sentence became the conditional it always was: the fields MAY be
+        // short. Both directions are measured beside it in
+        // `gap-sentences.test.ts`: emptying the run log on a forced-output run
+        // takes the tool list from one name to none, on a staged-refs run it takes
+        // away the request-only line, and on the plain run it takes nothing.
+        fields: Object.freeze([
+            'tools.names',
+            'tools.forced',
+            'tools.schemaHashes',
+            'messages.requestOnly',
+        ]),
+        why: 'The fields below may be SHORT: a name can be missing from the tool list, and a line ' +
+            'that went out with the request can be missing too. An absence below is not evidence ' +
+            'that there was nothing there — read the whole recording rather than a piece of it.',
+    }),
+});
+/**
+ * The fields no gap names, and the reason each one needs none — the OTHER half
+ * of the account.
+ *
+ * WHY IT EXISTS. `SERVED_GAPS` was hand-checked against the two shapes three
+ * times in one release and came up short every time, because "is every field
+ * named by a gap?" was a question a person answered by reading. It is now a
+ * question a walk answers: `test/lib/time-travel/gap-catalogue-walk.test.ts`
+ * enumerates every field a real `Receipt` and a real `ServedView` carry and
+ * requires each one to be named by a gap OR to be a key here. A field in
+ * neither fails, by name.
+ *
+ * So this is not an exemption list. It is the place a field goes when NO GAP'S
+ * MECHANISM EXPLAINS IT, and the value is the reason in one sentence, for the
+ * next person who asks why the field has no gap. Adding a key here is as
+ * reviewable as adding one to a gap, and that is the point: both are a claim
+ * somebody wrote down.
+ *
+ * TWO reasons qualify, and they are not the same reason:
+ *
+ *   • NO FOLD CAN FAIL TO PRODUCE IT — the field is read straight off the
+ *     located epoch, never through a fold. `callRuntimeStageId` is this kind.
+ *   • ITS ABSENCE IS UNIVERSAL AND HAS NOTHING TO DO WITH THIS RECORDING — no
+ *     chart IN THIS LIBRARY supplies it, on any run, so no gap about a limit of
+ *     the rebuild describes it. `omittedForAttention` is this kind, and it was
+ *     inside `no-receipt-on-chart` until 9.88.0's fourth review round, where a
+ *     gap that fires on some views was carrying an absence that is on all of
+ *     them. The narrowing to THIS LIBRARY is load-bearing: `buildReceipt` is a
+ *     pure exported mint, so a consumer that calls it can hand it the fact, and
+ *     a sentence saying no chart anywhere supplies one would be false the day
+ *     somebody did.
+ *
+ * A field a gap DOES name never belongs here, whatever else is also true of it.
+ * `epoch` was a key here through three rounds, on the true-but-irrelevant
+ * ground that `servedAt(k)` hands `k` back; what a base-less fold changes is
+ * what that number MEANS, `servedViews()` returns the fold's number outright,
+ * and `no-fold-base` names it now.
+ *
+ * Paths are spelled as they are on the shape that HAS the field: `ServedView`
+ * for a view field, `Receipt` for `omittedForAttention`, which is a receipt
+ * field the view has no counterpart for. Gap `fields` are spelled as `Receipt`
+ * paths — see {@link ServedGap.fields} for the places the two shapes differ.
+ *
+ * @example
+ * ```ts
+ * import { SERVED_GAPS, UNGAPPED_FIELDS } from 'agentfootprint';
+ *
+ * // Why does nothing explain `callRuntimeStageId`? Because nothing has to.
+ * UNGAPPED_FIELDS['callRuntimeStageId'];
+ * Object.keys(SERVED_GAPS).length; // 7 gap kinds
+ * ```
+ */
+exports.UNGAPPED_FIELDS = Object.freeze({
+    // MECHANISM (not printed). `Receipt.omittedForAttention` is written from
+    // `buildReceipt`'s `omittedForAttention` input, and measured on 9.88.0 no
+    // chart in this library ever supplies it: no boundary bubbles
+    // `slotCompositions` out of the slot subflow that writes it, so request
+    // assembly has nothing to pass. Its absence is therefore universal and has
+    // nothing to do with any one recording — which is why it is here and not
+    // inside `no-receipt-on-chart`, where it sat until 9.88.0's fourth round.
+    // `buildReceipt` is a pure exported mint, so a CONSUMER that calls it can
+    // hand it the fact; the narrowing to THIS LIBRARY is what keeps that true.
+    omittedForAttention: 'Absent means nobody recorded a drop, never that nothing was dropped. No limit of this ' +
+        'rebuild explains it, so no gap names it.',
+    // MECHANISM (not printed). Read straight off `EpochLocation.callRuntimeStageId`,
+    // which `epochAt` takes from the call's own commit bundle — never through
+    // `keyedFold`, so no missing base and no missing run log can touch it. An
+    // epoch with no bundle is not located at all, so there is no view to carry it.
+    callRuntimeStageId: 'Never absent here, so there is nothing about it for a gap to excuse.',
+    // THE SENTENCE THE RULE IS MODELLED ON. It makes no claim about code at all:
+    // it says what the field MEANS inside the account, and nothing outside the
+    // sentence can falsify it. Every other entry in this file was reduced to
+    // this shape in 9.88.0's sixth round.
+    gaps: 'The account itself rather than a fact about the request: a gap naming this list would be ' +
+        'the account excusing its own absence.',
+});
+/** A gap record, assembled from the catalogue — plus, where the site that
+ *  raises it established one, the cause it read. */
+function gapOf(kind, cause) {
+    return { gap: kind, ...exports.SERVED_GAPS[kind], ...(cause !== undefined && { cause }) };
+}
+/**
+ * The receipt this epoch's call committed, or WHY there is none. Shared by
+ * `receiptAt` and by the rebuild, which reads exactly ONE thing off a receipt —
+ * the model/provider/runId basis — and nothing else.
+ *
+ * THE ONE PLACE THAT KNOWS. This function is where the difference between
+ * "nothing was committed" and "something was committed and it is not a
+ * receipt" exists at all: everywhere else the two are one `undefined`. It used
+ * to be spent here, and the gap's printed sentence tried to make it up
+ * afterwards from a list of causes — which is how a shape refusal added in this
+ * release became a cause that sentence had already ruled out. So the answer
+ * carries the reason out, and {@link ServedGap.cause} is where it lands.
+ */
+function readReceipt(location) {
+    const value = (0, epochs_js_1.readAfterCall)(location, receipt_js_1.RECEIPT_KEY);
+    // Nothing under the key: the run never minted one here. The record does not
+    // say which of the ways that happens applied, and neither does this.
+    if (value === undefined)
+        return { cause: 'no-receipt-committed' };
+    // Something IS under the key. A value without a basis is not a receipt —
+    // refuse it rather than hand back a half-shape a caller would read
+    // `.basis.runId` off — and REPORT the refusal, because a log that holds a
+    // non-receipt under the receipt key is damaged, which is a different fact
+    // about the recording from a run that never minted.
+    const candidate = value;
+    if (value === null || typeof value !== 'object' || typeof candidate.basis?.epoch !== 'number') {
+        return { cause: 'receipt-shape-rejected' };
+    }
+    return { receipt: value };
+}
+/** `toolWantsByName` back as the map `findStagedRefs` takes. It is committed
+ *  as a plain record because a `Map` does not survive the scope's write path
+ *  (an object write is JSON-round-tripped, and a `Map` round-trips to `{}`). */
+function wantsMapOf(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const map = new Map();
+    for (const [name, kinds] of Object.entries(value)) {
+        if (Array.isArray(kinds) && kinds.every((k) => typeof k === 'string')) {
+            map.set(name, kinds);
+        }
+    }
+    return map.size > 0 ? map : undefined;
+}
+/**
+ * The BOUNDARY half of the fold law: a container that leaves this file is this
+ * file's own.
+ *
+ * `keyedFold` deep-freezes its answers, so nothing a consumer does to a view
+ * can reach a later epoch. This is the second, cheaper guarantee on top of it:
+ * the two arrays a view would otherwise ALIAS straight out of the fold — the
+ * conversation and the tool schemas — are copied, so `ServedView` is a value in
+ * its own right and not a window onto the fold's cache. Elements are the fold's
+ * frozen objects; the container is ours.
+ *
+ * Every other array on a view is built in `viewOf` from scratch and aliases
+ * nothing, so it needs the COPY half of this and not the freeze — but it is
+ * frozen anyway, by {@link frozenView}, because the type says `readonly`
+ * throughout and a claim that is true of two containers out of six is a claim
+ * a reader cannot use.
+ */
+function detachedList(items) {
+    return Object.freeze([...items]);
+}
+/**
+ * A `ServedView` is a VALUE — all of it, not the two containers that happened
+ * to need copying.
+ *
+ * Freezing the whole view costs a handful of `Object.freeze` calls per epoch
+ * over containers that are already the right size to hand a person: a few
+ * system pieces, at most one request-only line, a tool list, the gaps. It buys
+ * one sentence a reader can rely on instead of a rule about which two arrays
+ * are safe. `messages.asSent` and `tools.schemas` are already frozen by
+ * {@link detachedList} — their ELEMENTS are the fold's own frozen objects and
+ * this function does not walk into them, because they are not ours to freeze
+ * twice.
+ *
+ * What this is NOT: protection against a shared reference. Nothing on a view
+ * except those two arrays is shared with anything — every other container is
+ * built here per call. The freeze makes the type's promise exact; the copy in
+ * `detachedList` is what makes the fold safe.
+ */
+function frozenView(view) {
+    for (const piece of view.system.pieces)
+        Object.freeze(piece);
+    Object.freeze(view.system.pieces);
+    for (const line of view.messages.requestOnly)
+        Object.freeze(line);
+    Object.freeze(view.messages.requestOnly);
+    Object.freeze(view.tools.names);
+    for (const gap of view.gaps)
+        Object.freeze(gap);
+    Object.freeze(view.gaps);
+    if (view.basis !== undefined)
+        Object.freeze(view.basis);
+    Object.freeze(view.system);
+    Object.freeze(view.messages);
+    Object.freeze(view.tools);
+    return Object.freeze(view);
+}
+/** Rebuild one epoch's view from a located epoch. */
+function viewOf(location) {
+    // The receipt is read for exactly one thing — WHICH model saw this, through
+    // WHICH provider, salted with WHICH run id. Every other field below is
+    // rebuilt from committed pieces and never from the record it is checked
+    // against; a rebuild that read its own answer sheet would prove nothing.
+    const read = readReceipt(location);
+    const receipt = read.receipt;
+    // ── the system prompt ──────────────────────────────────────────────────
+    // The pieces are committed; the joined string never is. Same function the
+    // stage used, over the records as the stage read them.
+    const injections = ((0, epochs_js_1.readAtCall)(location, 'systemPromptInjections') ?? []);
+    const pieces = (0, composeRequest_js_1.contributingPieces)(injections).map((record) => ({
+        text: record.rawContent,
+        slot: record.slot,
+        source: record.source,
+    }));
+    // ── the conversation ───────────────────────────────────────────────────
+    // Read BEFORE the call's own bundle: the call appends the assistant turn to
+    // `history`, so the committed value at the call already includes the answer.
+    //
+    // TWO committed sources, because there are two kinds of chart and they do
+    // not agree on where the conversation lives. The agent charts keep it in
+    // `history` and treat `messagesInjections` as an observability projection.
+    // `LLMCall` and the message-API charts have NO history at all: the messages
+    // slot IS the conversation, composed by `messagesFromInjections` — the same
+    // function called here. Reading only `history` on those charts found nothing
+    // and reported an empty conversation the provider never sent.
+    //
+    // Neither present ⇒ the turns are UNKNOWN, and the gap below says so rather
+    // than letting `[]` pass for a proof.
+    const committedHistory = (0, epochs_js_1.readAtCall)(location, 'history');
+    const committedInjections = (0, epochs_js_1.readAtCall)(location, 'messagesInjections');
+    const conversation = Array.isArray(committedHistory)
+        ? committedHistory
+        : Array.isArray(committedInjections)
+            ? [...(0, composeRequest_js_1.messagesFromInjections)(committedInjections)]
+            : undefined;
+    const asSent = (0, composeRequest_js_1.stripFrameworkFields)(conversation ?? []);
+    // ── the tools ──────────────────────────────────────────────────────────
+    // `dynamicToolSchemas` is the PRE-assembly list. Two rules run after it and
+    // both are on the record: the wrap-up call withholds every tool, and a
+    // 'tool-forced' strategy adds one.
+    const withheld = (0, epochs_js_1.readAtCall)(location, 'wrapUpAsked') === true;
+    const dynamic = ((0, epochs_js_1.readAtCall)(location, 'dynamicToolSchemas') ?? []);
+    const registered = withheld ? [] : dynamic;
+    const forcedRaw = (0, epochs_js_1.readRunConstant)(location, receipt_js_1.FORCED_OUTPUT_TOOL_KEY);
+    const forced = typeof forcedRaw === 'string' && forcedRaw.length > 0 ? forcedRaw : undefined;
+    // ── the request-only lines ─────────────────────────────────────────────
+    // The staged-refs nudge is a pure function of committed state: the
+    // conversation, the tools really served this call, and the `wants`
+    // declarations `seed` put on the record for exactly this reason.
+    const requestOnly = [];
+    const wants = wantsMapOf((0, epochs_js_1.readRunConstant)(location, 'toolWantsByName'));
+    if (wants !== undefined) {
+        const match = (0, stagedRefs_js_1.findStagedRefs)(asSent, wants, new Set(registered.map((t) => t.name)));
+        if (match !== undefined) {
+            requestOnly.push({
+                role: 'user',
+                text: (0, stagedRefs_js_1.stagedRefsNudgeLine)(match),
+                reason: 'staged-refs-nudge',
+            });
+        }
+    }
+    // ── what this view cannot prove ────────────────────────────────────────
+    // Order is deliberate: the two that make the WHOLE view suspect come first,
+    // so a renderer that shows one gap shows the one that matters most.
+    const gaps = [];
+    // BOTH bases, because there are two folds above and either can be baseless.
+    // Under 'dynamic-grouped' the epoch's pieces come from the turn's own inner
+    // log (`location.basis`) and every run constant — the forced tool's name, the
+    // `wants` the nudge is composed from — comes from the RUN log
+    // (`location.runBasis`). Raising the gap off the first alone let a grouped
+    // recording that travelled without its RUN base read every constant as absent
+    // and declare NOTHING: a Lens denying rather than omitting, which is the law
+    // this whole file is built on.
+    if (location.basis === 'log-only' || location.runBasis === 'log-only') {
+        gaps.push(gapOf('no-fold-base'));
+    }
+    if (conversation === undefined)
+        gaps.push(gapOf('no-conversation-on-record'));
+    if (!location.hasRunLog)
+        gaps.push(gapOf('no-run-log'));
+    // No receipt ⇒ nothing checks the rebuild, and the receipt-only fields are
+    // absent. Mutually exclusive with `provider-defaults` below, which is the
+    // caveat that applies when a receipt DID record the dials.
+    //
+    // The CAUSE rides along, from the one read that can tell "nothing was
+    // committed" from "something was, and it is not a receipt". The gap's
+    // sentence says neither — see {@link ServedGap.cause}.
+    if (read.receipt === undefined)
+        gaps.push(gapOf('no-receipt-on-chart', read.cause));
+    gaps.push(gapOf('cache-transform'));
+    if (receipt !== undefined)
+        gaps.push(gapOf('provider-defaults'));
+    if (forced !== undefined)
+        gaps.push(gapOf('forced-tool-schema'));
+    return frozenView({
+        epoch: location.epoch,
+        callRuntimeStageId: location.callRuntimeStageId,
+        ...(receipt !== undefined && {
+            basis: {
+                model: receipt.basis.model,
+                provider: receipt.basis.provider,
+                runId: receipt.basis.runId,
+            },
+        }),
+        system: { text: (0, composeRequest_js_1.joinSystemPrompt)(injections), pieces },
+        messages: { asSent: detachedList(asSent), requestOnly },
+        tools: {
+            names: [...registered.map((t) => t.name), ...(forced !== undefined ? [forced] : [])],
+            schemas: detachedList(registered),
+            ...(forced !== undefined && { forced }),
+            ...(withheld && { withheld: 'wrap-up' }),
+        },
+        gaps,
+    });
+}
+/**
+ * Rebuild what the model was SERVED on epoch `k`, from the run's committed
+ * pieces alone.
+ *
+ * Works on a live snapshot and on a recording read back from JSON, in both
+ * chart shapes, on a run whose conversation lives in `messagesInjections`
+ * rather than `history` (`LLMCall`, the message-API charts), on a resumed run
+ * (every read folds from the checkpoint the run was seeded with), on a
+ * redacted run (the pieces are read exactly as the run committed them — a
+ * redacted piece rebuilds to its redacted bytes, which is what the record says
+ * a reader is allowed to see) and on a recording made before the receipt
+ * existed.
+ *
+ * It returns `undefined` for ONE reason only: the run has no such epoch.
+ * Anything it cannot prove about an epoch that DOES exist comes back as a
+ * named entry in `gaps`, never as a missing view and never as a confident
+ * empty one.
+ *
+ * @param source a runner (`Agent`, `LLMCall`) or a snapshot. On `LLMCall` and
+ *   the message-API charts the rebuild is complete but UNCHECKED: those charts
+ *   mint no receipt, so `basis` is absent and `gaps` carries
+ *   `no-receipt-on-chart` saying so.
+ * @param epoch  the iteration number, 1-based — the run's own count.
+ *
+ * @example
+ * ```ts
+ * import { receiptAt, receiptHash, servedAt } from 'agentfootprint';
+ *
+ * const snapshot = agent.getSnapshot()!;
+ * const view = servedAt(snapshot, 1)!;
+ * const receipt = receiptAt(snapshot, 1)!;
+ * receiptHash(receipt.basis.runId, view.system.text) === receipt.system.hash; // true
+ * ```
+ */
+function servedAt(source, epoch) {
+    const location = (0, epochs_js_1.epochAt)(source, epoch);
+    return location === undefined ? undefined : viewOf(location);
+}
+exports.servedAt = servedAt;
+/**
+ * Every epoch's served view, in run order — `servedAt` for a whole run, with
+ * one pass over the recording instead of one per epoch.
+ *
+ * @example
+ * ```ts
+ * servedViews(agent.getSnapshot()!).map((v) => v.tools.names.length); // [3, 3, 0]
+ * ```
+ */
+function servedViews(source) {
+    return (0, epochs_js_1.epochLocations)(source).map(viewOf);
+}
+exports.servedViews = servedViews;
+/**
+ * The receipt epoch `k`'s call left behind, or `undefined`.
+ *
+ * `undefined` means one of two things on the record, and the same epoch's
+ * `servedAt(...)` view carries which: its `no-receipt-on-chart` gap has a
+ * {@link ServedGapCause}. Either nothing was committed under the receipt key —
+ * a recording made before the receipt existed, a chart whose LLM stage mints
+ * none, a run with `recordReceipt: false`, all of which leave that same record
+ * — or something WAS committed there and `readReceipt` refused it, because it
+ * is not a non-null object with a number at `basis.epoch`, and handing back a
+ * half-object a caller reads `.basis.runId` off is worse than saying no.
+ *
+ * It also returns `undefined` when the run has no epoch `k` at all, which is
+ * the answer `epochAt` gives and is not a fact about receipts; ask
+ * `servedAt(source, k)` if you need to tell a missing epoch from a missing
+ * receipt, because that one returns `undefined` for the missing epoch only.
+ *
+ * `servedAt` still rebuilds the view of an epoch that exists in every one of
+ * these cases, which is what makes an old recording readable instead of
+ * unreadable.
+ *
+ * The receipt comes back DEEP-FROZEN and is the same object every caller gets
+ * for this epoch: it is a value folded out of the log, and a fold's answers are
+ * detached (`keyedFold.ts` · `freezeDeep`). Copy it if you need to edit one.
+ *
+ * @example
+ * ```ts
+ * import { receiptAt } from 'agentfootprint';
+ *
+ * receiptAt(agent.getSnapshot()!, 3)?.tools.withheld; // 'wrap-up' on a wrap-up call
+ * ```
+ */
+function receiptAt(source, epoch) {
+    const location = (0, epochs_js_1.epochAt)(source, epoch);
+    return location === undefined ? undefined : readReceipt(location).receipt;
+}
+exports.receiptAt = receiptAt;
+//# sourceMappingURL=servedView.js.map