agentfootprint 9.76.1 → 9.78.0

package/CHANGELOG.md

@@ -7,6 +7,194 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [9.78.0] - 2026-08-30
+
+### Added
+
+- **`Tool.resultColumns` + `checkColumnTypes` — the column-type contract: a
+  tool declares what its rows contain, and the library checks the rows against
+  it at the boundary.** Three recorded failures, and they are one shape — *a
+  number became something else, and nothing noticed at the seam*:
+
+  1. A mapping report wrote `str(m.get("logical_unit_number") or "")`. **LUN 0
+     is falsy**, so LUN 0 was stored as an EMPTY STRING on 2,094 mappings, and
+     a host group missing the LUN an initiator probes first became
+     indistinguishable from one that had it.
+  2. A capacity view rendered `round(mib / 1024, 1)`, so an 8 MiB disk came out
+     as `0.0 GB` — which reads as NO DISK, a provisioning failure, during a
+     live incident.
+  3. A whole family of tools returned their numbers as quoted strings
+     (`"1240"`), which silently blanked every chart, because nothing downstream
+     could tell a measure from a label.
+
+  Every rail passed, honestly, in all three: nothing errored, nothing was
+  ungrounded. The library already lets a tool declare what its result IS
+  (`resultKind`, 9.70.0); it did not let a tool declare what its result
+  CONTAINS, so a rowset had nothing to be wrong against — and every consumer
+  downstream was left SNIFFING types out of the data, where one stray `''`
+  demotes a numeric column to text in silence.
+
+  `resultColumns` is the sibling declaration: a column-name → type map, on
+  `Tool` beside `resultKind`. Types are `number` / `string` / `boolean` /
+  `date` — **the vocabulary this ecosystem's rowset consumers already sniff
+  their way to**, not a new one. The one word deliberately left behind is
+  `'unknown'`: a sniffer needs it ("I could not tell"), a declaration has no
+  use for it. A column maps to a bare word or to `{ type, nullable }` (the
+  `CostBudget` two-spellings pattern, normalized once).
+
+  **THE CEILING**, exported as `COLUMN_TYPE_CEILING` and quoted verbatim into
+  every finding, the `EMPTY_LOOKUP_CEILING` law: *"This judges TYPE, never
+  MEANING — it can see that a column declared `number` holds a string, and it
+  can never see that the string should have been 0, or that a 0.0 should have
+  been an 8; a column whose every value has its declared type passes here and
+  can still be wrong."* Failures 1 and 3 are caught. **Failure 2 is not, and
+  never will be** — `0.0` is a perfectly good number — and the check says so
+  out loud rather than letting a green row imply otherwise.
+
+  **TWO finding kinds, because the field bug turned on the difference.** New
+  `ContextErrorKind`s at the **write seam**: **`column-type-mismatch`** (the
+  column is THERE and holds the wrong thing) and **`missing-column`** (the
+  declared column is in NONE of the rows). *"The value is not what it should
+  be"* sends a person to the mapping code; *"the column was never delivered"*
+  sends them to the query. A checker that said only "something is off with
+  logical_unit_number" would have helped with neither. Each finding names the
+  column, the offending value quoted, the rows affected of the rows read, and
+  the tool.
+
+  **OPEN, never closed.** A declaration is a promise about what it NAMES — an
+  unlisted column is allowed and never judged. A closed schema would punish the
+  wrong party the day a backend adds a column, and it is the rule the
+  neighbouring boundary (`toolArgsValidation`) already keeps.
+
+  **`nullable`, and what "no value" means.** `null`, `undefined` and a key not
+  set on a row are one idea with three spellings, and by default all three are
+  violations; `nullable: true` legitimizes them and every finding about an
+  absence names that one-word fix in its own message. `nullable` is a promise
+  about VALUES, not about the column's existence: a declared column in no row
+  at all is `missing-column` regardless.
+
+  **The dial: `AgentOptions.checkColumnTypes`, default `'off'`** —
+  `'off'` | `'warn'` | `'enforce'`. **The three words are borrowed, not
+  minted:** this boundary is the MIRROR of `toolArgsValidation` (arguments in,
+  against `inputSchema`; rows out, against `resultColumns`), and two validators
+  at one seam grading themselves in different vocabularies would be a worse
+  defect than either could catch — so there is no new `assist`/`guard`/`rails`
+  trio here and no new `observe`/`warn`/`refuse` one either. `'warn'` files
+  findings and the model reads the rows **exactly** as the tool returned them.
+  `'enforce'` REFUSES in the library's own refusal idiom — the `resultCeiling`
+  teaching sentence ("…Fix the tool so the column holds what it declares, or
+  change the declaration. No data was returned."), the whole payload on every
+  channel, delivered status `'invalid'`, never a thrown stack trace.
+
+  **What it refuses to judge** (`readRowset`): a result is read only when it is
+  an ARRAY OF PLAIN OBJECTS with at least one row. Prose, a `null`, a bespoke
+  `{ rows: [...] }` wrapper, a claim ticket — and the **zero-row** result,
+  which has no columns to be wrong about and is `empty-lookup`'s subject next
+  door — all file an explicit `not-applicable` ROW and no finding. Filing
+  `missing-column` for every declared column of an empty answer would turn one
+  honest emptiness into a pile of false accusations.
+
+  **Armed by two halves**: the dial off `'off'` **and** at least one tool
+  declaring `resultColumns`. Absent either, the run is byte-identical — no
+  finding, no event, nothing on the wire, and a declaring tool with the dial
+  off runs byte-for-byte the run it ran before the declaration existed. The one
+  visible difference is the two registered rows in the disposition report,
+  filed `not-applicable`: registered-but-unarmed is a ROW, never silence.
+
+  **Travels MCP `_meta`** like the library's other tool declarations, both
+  directions — a remote catalogue is exactly where a numeric column arriving as
+  text goes unnoticed, and leaving the declaration behind would arm the check
+  for local tools while leaving every MCP tool a second-class citizen of it. A
+  malformed declaration from a foreign server is warned about once and dropped;
+  the tool still registers.
+
+  Exports: `COLUMN_TYPE_CEILING`, `COLUMN_TYPES`, `readRowset`,
+  `assertResultColumns`, and the types `ColumnType`, `ColumnDeclaration`,
+  `ToolResultColumns`, `ColumnCheckMode`, `ColumnViolation`, `RowsetReading`.
+  Docs: `docs-next` → Monitor → Column Types, which also names the three
+  existing consumers this declaration feeds (chart axis pickers that sniff, the
+  panel deciding table-vs-chart by inference, and `compute` staging rows blind)
+  — none of those integrations are built here, they are named so the next
+  person does not add an eighth sniffer.
+
+## [9.77.0] - 2026-08-29
+
+### Added
+
+- **`noticeEmptyLookups` — the run produced the identifier, and the lookup for
+  it came back empty.** A triage agent's reverse-lookup tool filtered a column
+  before a pivot, so the column did not exist yet and EVERY reverse lookup
+  returned an empty result — for every identifier, always. The tool then
+  answered *successfully* with an empty list, and the agent reported in a
+  table, with confidence, that the device was not logged in to any port on any
+  collected switch, advising a check of the physical cabling. It was logged in
+  the whole time. Every rail passed, and passed honestly: nothing errored,
+  nothing was ungrounded, no coverage was overstated. **An empty result from a
+  broken filter is byte-identical to an empty result from a genuine absence**,
+  and nothing in the framework was responsible for noticing the difference.
+
+  The library was already holding both halves of the answer, separately: that
+  the identifier was GROUNDED (it came out of an earlier tool result in this
+  run, from a tool the consumer's own author named in `Tool.argumentsFrom` —
+  the same declaration that arms `dangling-reference` and
+  `unsupported-argument`), and that the lookup keyed on it came back EMPTY.
+  Joining them is the whole check: new `ContextErrorKind` **`empty-lookup`** at
+  the **write seam**, filed at the tool-dispatch boundary — the one moment a
+  lookup's answer becomes a fact in the conversation.
+
+  **THE CEILING, and it is why this can never be an accusation.** An empty
+  answer can be perfectly true; the device may exist and simply have no logins
+  right now. Nothing here can tell those apart and nothing here pretends to, so
+  every finding is an **`advisory: true`** and the IDENTICAL advisory is filed
+  for the broken filter and for the honest absence. The bound ships as one
+  exported string, `EMPTY_LOOKUP_CEILING`, quoted verbatim into every message
+  so it cannot drift out of one doc and leave a reader thinking the library
+  knows more than it does: *"An empty result can be perfectly true — the thing
+  may exist and simply have nothing to show right now — so this is a place to
+  look, never a verdict that anything is wrong."*
+
+  Deliberately NOT `dangling-reference`, whose meaning is the opposite: there
+  the ground has left reach; here the ground IS in reach and the lookup found
+  nothing.
+
+  **What counts as empty is COUNTED, never interpreted** (`readLookupResult`):
+  an array with zero elements is a rowset with zero rows, and an `absent(…)`
+  envelope is an author saying the search ran and matched nothing. Every other
+  shape — a sentence, a `null`, a bespoke `{ rows: [] }` wrapper, a placement
+  claim ticket — is unreadable, and files an explicit **`not-applicable` row
+  with no finding**. That row is the point: a check that silently skipped what
+  it could not read would be the decoration the disposition ledger exists to
+  make impossible.
+
+  **Armed by two halves**, and the second one is why: `noticeEmptyLookups:
+  true` on `Agent.create` **and** at least one tool declaring `argumentsFrom`.
+  The declaration alone is not enough — it already arms two other checks, and
+  an advisory that armed itself off a declaration made for something else
+  would not be opt-in at all. **Default off is byte-identical**: no finding, no
+  event, nothing on the wire, in the history or in the answer changes. The one
+  visible difference is the registered `empty-lookup` row in the disposition
+  report, filed `not-applicable` — the family's law rather than an exception to
+  it, since silence is exactly what let two shipped checks decay into
+  decoration. Posture is the family's own (`integrityPosture`), with a dev
+  canary like every sibling; the evidence gate's `assist`/`guard`/`rails` trio
+  is deliberately absent, because those grade how hard a rail pushes back and
+  this check never pushes back on anything.
+
+### Changed
+
+- **One rail for integrity findings, one spelling for an argument leaf.** The
+  seen-list dedup that turns "detected many times" into one
+  `integrity.context_error` per run moved out of `callLLM` into
+  `core/agent/integrityFindings.ts` — the write seam files from a second STAGE,
+  and its old header already warned that a second copy of that loop would
+  eventually disagree with the first about what "already filed" means.
+  Likewise the argument walk, the four-character fence and the quoting length
+  moved to `src/integrity/argumentLeaves.ts`, shared by the choice seam and the
+  write seam: the second check's whole job is to notice something about a value
+  the first one already excused, so the two must agree to the character about
+  which leaves are candidates and what their dot-paths are. No behaviour change
+  on either move.
+
 ## [9.76.1] - 2026-08-28
 
 ### Fixed

package/CLAUDE.md

@@ -51,6 +51,8 @@ not in this table, search `src/index.ts` for the nearest noun before writing cod
 | asking a debugging model "what did this run contradict itself about, and why?" — the Context Integrity findings, joined to the step that filed them | `find_context_errors` | `src/lib/trace-toolpack/traceToolpack.ts` | 9.61.0 |
 | the model inventing an id or a reading that no tool ever returned — a deterministic fabrication detector on the final answer, with a posture for how hard it pushes back | `.namesAndNumbersFromEvidence()` + `posture` (`'assist'` record+flag, the default / `'guard'` one revision then ship flagged / `'rails'` refuse instead) + `shapes` + `exempt` + `minDigits` (default 4) + `nudge` (default off) | `src/core/agent/evidence/` | 9.35.0 |
 | counting a HUMAN-VERIFIED value as ground for the choice-seam check — the person clicked a row, the app verified the cells against the artifact, and the id the model takes from that selection is not fabricated; the source label travels onto the record | `externalGrounds` + `ExternalGround` + `external_ground_used` | `src/integrity/unsupported-argument/check.ts` | 9.72.0 |
+| a lookup tool that answers "nothing found" for EVERY id because a filter broke, and an agent reporting that absence as fact — the run itself produced the id, the lookup came back empty, and that PAIR is worth a look | `noticeEmptyLookups` + `readLookupResult` + `EMPTY_LOOKUP_CEILING` (dial default OFF and needs a tool declaring `argumentsFrom` too — two halves; kind `empty-lookup` at seam `write`, always `advisory: true`; empty = a zero-length ARRAY or an `absent()` envelope, every other shape files `not-applicable` and no finding; the ceiling is quoted verbatim into every message) | `src/integrity/empty-lookup/` | 9.77.0 |
+| a tool's ROWS quietly disagreeing with what the tool promised — a LUN 0 stored as `""` because it is falsy, a numeric column arriving as quoted strings, a declared column present in no row at all | `Tool.resultColumns` + `checkColumnTypes` + `COLUMN_TYPE_CEILING` + `readRowset` (dial `'off'` (default) / `'warn'` (file findings, model reads the rows unchanged) / `'enforce'` (refuse the rows, `resultCeiling`'s teaching-sentence idiom, delivered status `'invalid'`) — the `toolArgsValidation` trio, this seam's mirror; needs a tool declaring `resultColumns` too — two halves; types `number`/`string`/`boolean`/`date`, bare word or `{type, nullable}`, deliberately NO `'unknown'`; OPEN — unlisted columns allowed and unjudged; TWO kinds at seam `write` — `column-type-mismatch` (there, wrong type) vs `missing-column` (declared, in no row); rowset = an ARRAY OF PLAIN OBJECTS with ≥1 row, everything else incl. the ZERO-ROW result files `not-applicable` (empty is `empty-lookup`'s subject); travels MCP `_meta`; the ceiling is quoted verbatim into every message) | `src/integrity/column-types/` | 9.78.0 |
 | a model head-mathing a total from tool-result numbers while a compute tool sits unused on the wire — a LATE line each iteration naming the staged refs and the `wants` tool that spends them (recency working FOR the instruction), plus the revise correction naming the same route | `nudge: true` (default off) + `stagedRefsNudgeLine` + `findStagedRefs` + `grounding_nudged` | `src/core/agent/stagedRefs.ts` | 9.75.0 |
 | a tool answering "I looked and found nothing", routably | `absent` + `looked_for` + `checked`/`not_checked`/`cannot_cover` + `tryInstead` (delivered status `'absent'`, routable by `onToolStatus`) | `src/core/agent/coverage/absent.ts` | 9.43.0 |
 | stating what a clean answer does NOT rule out | `coverage` + the declaration `{ checked, not_checked?, cannot_cover? }` | `src/core/agent/coverage/ledger.ts` | 9.43.0 |

package/dist/core/Agent.js

@@ -312,6 +312,16 @@ class Agent extends RunnerBase_js_1.RunnerBase {
     /** Set at chart build: whether any tool in the FULL declared catalog
      *  (static registry + skill-carried tools) declared `argumentsFrom`. */
     integrityDanglingPresent = false;
+    /** See AgentOptions.noticeEmptyLookups (9.77.0). Default false — absent is
+     *  byte-identical, save for the registered not-applicable ledger row. */
+    noticeEmptyLookups = false;
+    /** Set at chart build: whether any tool in the FULL declared catalog
+     *  declared `resultColumns` (9.78.0) — the other half of the column-type
+     *  contract's arming. */
+    integrityColumnsPresent = false;
+    /** See AgentOptions.checkColumnTypes (9.78.0). Default 'off' — absent is
+     *  byte-identical, save for the registered not-applicable ledger rows. */
+    checkColumnTypes = 'off';
     /** See AgentOptions.externalGrounds (9.72.0). Absent = door closed,
      *  byte-identical behavior. */
     externalGrounds;
@@ -658,6 +668,36 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             }
             this.externalGrounds = opts.externalGrounds;
         }
+        // The write-seam advisory's dial (9.77.0) — refused at construction for
+        // the same reason as the posture above: a truthy non-boolean here (a
+        // string, a number) would silently arm a check the author only half
+        // asked for, and the arming is what decides whether a run is
+        // byte-identical to the one before it.
+        if (opts.noticeEmptyLookups !== undefined) {
+            if (typeof opts.noticeEmptyLookups !== 'boolean') {
+                throw new Error(`Agent: noticeEmptyLookups must be a boolean, got ` +
+                    `${JSON.stringify(opts.noticeEmptyLookups)}. It arms the write-seam 'empty-lookup' ` +
+                    `advisory — a lookup for a value this run itself produced coming back empty. ` +
+                    `Omit it (or pass false) and no such advisory is ever filed.`);
+            }
+            this.noticeEmptyLookups = opts.noticeEmptyLookups;
+        }
+        // The column-type contract's dial (9.78.0) — refused at construction for
+        // the same reason as the postures above, and with one more: `'enforce'`
+        // REFUSES tool results, so a misspelling silently downgraded to off would
+        // leave an operator believing a boundary is held that nothing is holding.
+        if (opts.checkColumnTypes !== undefined) {
+            if (opts.checkColumnTypes !== 'off' &&
+                opts.checkColumnTypes !== 'warn' &&
+                opts.checkColumnTypes !== 'enforce') {
+                throw new Error(`Agent: checkColumnTypes must be 'off', 'warn' or 'enforce', got ` +
+                    `${JSON.stringify(opts.checkColumnTypes)}. It reads each tool's declared ` +
+                    `\`resultColumns\` and judges the rows it returns: 'warn' files findings and ` +
+                    `changes nothing the model reads; 'enforce' refuses the rows and hands the model a ` +
+                    `teaching sentence instead. Omit it (or pass 'off') and nothing is ever measured.`);
+            }
+            this.checkColumnTypes = opts.checkColumnTypes;
+        }
         // The claim-check seam (9.21.0). One store per agent, attached at
         // construction — idempotent by shape: there is no second door to attach a
         // competing one through, so "one per agent" is a fact of the type rather
@@ -2342,6 +2382,13 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             composeInvariant: this.mapsPlan !== undefined,
             dangling: this.integrityDanglingPresent,
             claim: this.claimContract !== undefined,
+            // TWO HALVES (9.77.0): the operator's dial AND a declaration to arm
+            // on. Either alone leaves a registered `not-applicable` row.
+            emptyLookup: this.noticeEmptyLookups && this.integrityDanglingPresent,
+            // TWO HALVES (9.78.0), the same law: the operator's dial off `'off'`
+            // AND a tool declaring `resultColumns`. Either alone leaves two
+            // registered `not-applicable` rows.
+            columnTypes: this.checkColumnTypes !== 'off' && this.integrityColumnsPresent,
         }, this.integrityPosture);
     }
     /**
@@ -3072,6 +3119,14 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             .filter(([, tool]) => tool.argumentsFrom !== undefined)
             .map(([name, tool]) => [name, tool.argumentsFrom]));
         this.integrityDanglingPresent = toolGrounding.size > 0;
+        // The column-type contract's declared half (9.78.0) — harvested from the
+        // SAME catalog and with the same ToolProvider caveat, so an MCP-carried
+        // `resultColumns` (which rides `_meta`) arms the check exactly as a
+        // locally-defined one does.
+        // `flatMap` rather than filter-then-assert: the narrowing is real here,
+        // so the twin harvest above's non-null assertion is not inherited.
+        const toolColumns = new Map([...registryByName.entries()].flatMap(([name, tool]) => tool.resultColumns === undefined ? [] : [[name, tool.resultColumns]]));
+        this.integrityColumnsPresent = toolColumns.size > 0;
         // The staged-refs join's other half (grounded numbers): `Tool.wants` by
         // tool name, harvested the same way and with the same ToolProvider caveat.
         // Consumed only by the evidence gate (the callLLM nudge and the recheck
@@ -3117,6 +3172,16 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // The external-ground door (9.72.0) — value-conditional for the same
             // reason: no provider, no key, byte-identical corpus assembly.
             ...(this.externalGrounds !== undefined && { externalGrounds: this.externalGrounds }),
+            // The write-seam advisory's arming (9.77.0) — this stage owns only the
+            // "no armed call this response" not-applicable note; the check itself
+            // runs where the result is. Value-conditional on BOTH halves, so an
+            // agent that never asked for it reads no new key.
+            ...(this.noticeEmptyLookups && toolGrounding.size > 0 && { noticeEmptyLookups: true }),
+            // The column-type contract's arming (9.78.0), same job and same
+            // value-conditional law: this stage owns only the "no declaring tool
+            // was called this response" not-applicable notes.
+            ...(this.checkColumnTypes !== 'off' &&
+                toolColumns.size > 0 && { columnDeclaringTools: new Set(toolColumns.keys()) }),
             integrityLedger: this.integrityLedgerHolder,
             ...(this.reliabilityConfig !== undefined && { reliability: this.reliabilityConfig }),
             ...(this.outputSchemaParser !== undefined && {
@@ -3210,6 +3275,27 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // contract to read it (9.61.0) — value-conditional, so every other
             // agent commits exactly what it always did.
             ...(this.claimContract !== undefined && { collectClaimFacts: true }),
+            // THE WRITE SEAM (9.77.0) — `empty-lookup`. Handed the SAME harvested
+            // map callLLM reads at the choice seam, so the two stages agree by
+            // construction about which calls are armed. Value-conditional on both
+            // halves — the operator's dial and at least one `argumentsFrom`
+            // declaration — so an agent that asked for neither hands the handler
+            // exactly the deps object it always did.
+            ...(this.noticeEmptyLookups &&
+                toolGrounding.size > 0 && {
+                emptyLookupGrounding: toolGrounding,
+                integrityLedger: this.integrityLedgerHolder,
+            }),
+            // THE WRITE SEAM'S other check (9.78.0) — the column-type contract.
+            // Value-conditional on both halves for the same reason, so an agent
+            // that asked for neither hands the handler exactly the deps object it
+            // always did.
+            ...(this.checkColumnTypes !== 'off' &&
+                toolColumns.size > 0 && {
+                columnDeclarations: toolColumns,
+                columnCheckMode: this.checkColumnTypes,
+                integrityLedger: this.integrityLedgerHolder,
+            }),
             ...(this.externalToolProvider && { externalToolProvider: this.externalToolProvider }),
             ...(this.externalToolProvider && { providerToolCache }),
             ...(permissionChecker && { permissionChecker }),