agentfootprint 13.0.0 → 14.0.0

package/dist/esm/events/payloads/context.d.ts

@@ -0,0 +1,276 @@
+import type { ContextLifetime, ContextRecency, ContextRole, ContextSlot, ContextSource } from './dependencyTypes.js';
+export interface ContextInjectedPayload {
+    readonly contentSummary: string;
+    readonly contentHash: string;
+    readonly rawContent?: string;
+    readonly slot: ContextSlot;
+    readonly asRole?: ContextRole;
+    readonly asRecency?: ContextRecency;
+    readonly position?: number;
+    readonly sectionTag?: string;
+    readonly source: ContextSource;
+    readonly sourceId?: string;
+    readonly upstreamRef?: string;
+    readonly reason: string;
+    readonly retrievalScore?: number;
+    readonly rankPosition?: number;
+    readonly threshold?: number;
+    readonly budgetSpent?: {
+        readonly tokens: number;
+        readonly fractionOfCap: number;
+    };
+    readonly expiresAfter?: ContextLifetime;
+}
+export interface ContextEvictedPayload {
+    readonly slot: ContextSlot;
+    readonly contentHash: string;
+    readonly reason: 'budget' | 'stale' | 'low_score' | 'policy' | 'user_revoked';
+    readonly survivalMs: number;
+}
+export interface ContextSlotComposedPayload {
+    readonly slot: ContextSlot;
+    readonly iteration: number;
+    readonly budget: {
+        readonly cap: number;
+        readonly used: number;
+        readonly headroomChars: number;
+    };
+    readonly sourceBreakdown: Readonly<Partial<Record<ContextSource, {
+        readonly chars: number;
+        readonly count: number;
+    }>>>;
+    readonly orderingStrategy?: string;
+    readonly droppedCount: number;
+    readonly droppedSummaries: readonly string[];
+}
+/**
+ * Fired when a budget is exceeded — by a context SLOT composing over its
+ * `budgetCap`, or by a window STRATEGY measuring the window over its
+ * `thresholdTokens`.
+ *
+ * ## Read `unit` before you read a number (8.14.0)
+ *
+ * Two emitters share this event name and the `slot: 'messages'` value, and
+ * **they do not count in the same unit**:
+ *
+ * | emitter | what it measures | `unit` |
+ * |---|---|---|
+ * | the three context slots (`contextBudget`) | `String.length` of what it composed | `'chars'` |
+ * | a window strategy (`.window()` / `.compaction()`) | the provider's reported input tokens | `'tokens'` |
+ *
+ * Since `contextBudget` is on by default, one subscriber routinely receives
+ * both — and before 8.14.0 nothing in the payload told them apart, so
+ * "cap 200, projected 258" could be 258 characters or 258 tokens. `unit` is
+ * the answer; `cap` and `projected` are the same two numbers under names that
+ * do not assert an untrue one.
+ *
+ * `planAction: 'none'` means no mitigation was performed — nothing was
+ * evicted or truncated and the full content still went to the LLM. That
+ * is what the built-in slots report: they never truncate, so the event is
+ * the signal that the budget is not being respected.
+ */
+export interface ContextBudgetPressurePayload {
+    readonly slot: ContextSlot;
+    /** How far over the cap, in {@link unit}. Never carried a unit in its name. */
+    readonly overflowBy: number;
+    readonly planAction: 'evict' | 'summarize' | 'abort' | 'none';
+    /**
+     * What {@link cap}, {@link projected} and {@link overflowBy} are counted in
+     * (8.14.0). `'chars'` from a context slot, `'tokens'` from a window
+     * strategy. Branch on this before comparing any of the three numbers to
+     * anything.
+     */
+    readonly unit: 'chars' | 'tokens';
+    /**
+     * The budget that was exceeded, in {@link unit}.
+     *
+     * Called `capTokens` until 9.0.0 — a name that asserted tokens on a channel
+     * that is CHARS half the time, since `contextBudget` is on by default and a
+     * slot counts `String.length`. Both spellings shipped through 8.x with the
+     * identical value; 9.0.0 keeps only this one.
+     */
+    readonly cap: number;
+    /** What was measured, in {@link unit}. Called `projectedTokens` until 9.0.0
+     *  — see {@link cap}. */
+    readonly projected: number;
+}
+/**
+ * Fired once per iteration by the Injection Engine after it evaluates every
+ * Injection's trigger — BEFORE the Context fork routes the survivors into the
+ * three slots. This is the "what was considered, what won, what was skipped
+ * and why" signal; `context.slot_composed` is its downstream counterpart
+ * ("what actually landed in each slot"). Pure observability — no flow stage
+ * reads it.
+ */
+/** A guard threshold value as the record carries it — plain data only. */
+export type SkillGuardValueRecord = string | number | boolean | null | ReadonlyArray<string | number | boolean | null>;
+/**
+ * One route-edge guard evaluation, as `cursorMove.guard` / `guardsClosed`
+ * carry it (9.51.0): the guarded edge, the tool result it judged, the
+ * verdict, and per-condition evidence — each declared condition
+ * (`key`/`op`/`value`), the summarized value it was judged against (bounded
+ * to 80 chars — evidence, not a transcript), and whether it passed. The
+ * operator vocabulary deliberately mirrors footprintjs's `WhereFilter`
+ * (`eq/ne/gt/gte/lt/lte/in/notIn`).
+ */
+export interface SkillGuardEvaluationRecord {
+    readonly from: string;
+    readonly to: string;
+    readonly toolName: string;
+    readonly toolCallId?: string;
+    readonly verdict: boolean;
+    readonly conditions: ReadonlyArray<{
+        readonly key: string;
+        readonly op: string;
+        readonly value: SkillGuardValueRecord;
+        readonly actualSummary: string;
+        readonly passed: boolean;
+    }>;
+}
+export interface ContextEvaluatedPayload {
+    readonly iteration: number;
+    /** Number of injections active this iteration. */
+    readonly activeCount: number;
+    /** Number skipped (predicate false counts as neither — only errors/unknown land here). */
+    readonly skippedCount: number;
+    /** Total injections evaluated (the full declared list). */
+    readonly evaluatedTotal: number;
+    /** Ids of the active injections, in evaluation order. */
+    readonly activeIds: readonly string[];
+    /** Why each skipped injection was skipped (errors / unknown trigger kinds). */
+    readonly skippedDetails: readonly {
+        readonly id: string;
+        /** `'unknown-fact'` (9.57.0): a templated instruction named a run-time
+         *  fact this evaluation could not supply, so it was skipped whole.
+         *  `'parked'` (9.58.0): a member of a map the mount kernel parked —
+         *  served without corroboration for the grace window; the map's own
+         *  cursor is untouched and evidence re-engages it.
+         *  `'hidden'`: a skill the caller's role may not see (`skill_read`),
+         *  refused whatever tried to activate it. */
+        readonly reason: 'predicate-threw' | 'unknown-trigger-kind' | 'unknown-fact' | 'parked' | 'hidden';
+        readonly error?: string;
+    }[];
+    /** Count of active injections by trigger kind (always / rule / on-tool-return / llm-activated). */
+    readonly triggerKindCounts: Readonly<Record<string, number>>;
+    /**
+     * The Skill CATALOG the LLM was offered this turn — every registered Skill's
+     * `id` + `description` (the same text that lands in the `read_skill` tool
+     * description). Lets observers pair "what was offered" against "what the LLM
+     * chose" (`read_skill` → `activatedInjectionIds`) when debugging a missed or
+     * wrong activation. Empty when no Skills are registered. Static across turns.
+     */
+    readonly skillCatalog: readonly {
+        readonly id: string;
+        readonly description: string;
+    }[];
+    /**
+     * Routing PROVENANCE for the active injections that came from a `skillGraph()`
+     * — *why* each was reached. One entry per active skill-graph injection (a
+     * decision-tree leaf, a flat entry, or a route edge); absent when no active
+     * injection carries skill-graph metadata. The structured counterpart to the
+     * `context.routed` commentary line — lets the lens show the decision path, the
+     * matched predicate, and the tools a route unlocked. Structural shape (mirrors
+     * `SkillRouting` from the injection engine; events stay decoupled from it).
+     */
+    readonly routing?: readonly {
+        readonly injectionId: string;
+        readonly flavor: string;
+        /** `'tree' | 'entry' | 'route' | 'model'`. */
+        readonly via: string;
+        /** Decision path (tree only): predicates root→leaf + branch taken. */
+        readonly path?: readonly {
+            readonly label: string;
+            readonly branch: string;
+        }[];
+        /** Entry/route edge caption. */
+        readonly label?: string;
+        /** Source skill id (route only). */
+        readonly from?: string;
+        /** Compiled trigger kind for a route. */
+        readonly triggerKind?: string;
+        /** Tool names this injection unlocked. */
+        readonly tools?: readonly string[];
+    }[];
+    /**
+     * How the skill-graph CURSOR moved on THIS iteration — the winning clause of the
+     * graph's one cursor resolver, reported by it (8.5.0). Present only for an agent
+     * built with `.skillGraph()` (and a graph new enough to explain itself).
+     *
+     * Distinct from `routing[]` above, and the distinction is the point: `routing[]`
+     * is per-SKILL build-time provenance ("how is this skill reachable"), while this
+     * is per-HOP runtime truth ("what moved us, this turn"). `by: 'model-pick'` is the
+     * case the two disagree on — a `read_skill` pick the gate accepted, into a skill
+     * that also has a declared edge whose predicate never fired.
+     */
+    readonly cursorMove?: {
+        readonly from?: string;
+        readonly to?: string;
+        /** `'entry' | 'route' | 'model-pick' | 'intent' | 'continuity' | 'stay' | 'none'`. */
+        readonly by: string;
+        /** The turn-start MENU this model pick resolved (SG-C) — present only on
+         *  the iteration an accepted pick closed an outstanding menu. */
+        readonly offered?: readonly string[];
+        /** The accepted pick was reachable but NOT on the offered menu — the
+         *  model's divergence, on the record (data under `'assist'`, a refusal
+         *  under `'guard'`/`'rails'`, which never reach here). */
+        readonly declinedOffer?: boolean;
+        /** WHAT the message said that routed this hop (9.28.0) — present only for a
+         *  `by: 'entry'` move a DATA matcher (`match:` — RegExp / `{ keywords }` /
+         *  `{ all }`) decided. `text` is the matched substring of the USER message,
+         *  whitespace-collapsed and bounded to 80 characters (ellipsis included);
+         *  `keyword` names WHICH declared keyword hit, for the keywords arm.
+         *  Absent for `when` predicates (opaque code), unconditional entries, and
+         *  every scorer verdict (whose evidence is its scores). */
+        readonly witness?: {
+            readonly text: string;
+            readonly keyword?: string;
+        };
+        /**
+         * The EVIDENCE the winning data GUARD routed on (9.51.0) — present only
+         * for a `by: 'route'` move whose firing edge declared a `guard:`. The
+         * full per-condition evaluation (verdict `true`): which edge, which tool
+         * result it judged, and every declared condition with the summarized
+         * value it saw. Structural shape (mirrors the graph's `GuardEvaluation`;
+         * events stay decoupled from it).
+         */
+        readonly guard?: SkillGuardEvaluationRecord;
+        /**
+         * The data guards that REFUSED this iteration (9.51.0) — guarded edges
+         * out of the cursor whose other declared conditions a tool result met
+         * and whose guard said no (verdict `false`; at most one record per
+         * edge). Rides whatever move resulted — including a `'stay'`, where it
+         * answers "why didn't my guarded edge fire?" with the conditions and
+         * values that closed it. Absent when no guard decided anything.
+         */
+        readonly guardsClosed?: readonly SkillGuardEvaluationRecord[];
+        /**
+         * The REACHABLE set from the cursor this move landed on (9.50.0) — the
+         * skill ids the `read_skill` gate will admit on THIS iteration: declared
+         * hops out of the landed cursor plus the open skills (`llm-activated`
+         * skills the graph wires no edge to). It is the same set, from the same
+         * two resolvers, that builds the `read_skill` offer prose and any
+         * `skill.rejected.allowed` list this iteration — as DATA, so no consumer
+         * has to parse the menu sentence back into ids. `[]` is a fact (a dead
+         * end: no hop and no open skill is admissible); ABSENT means the graph
+         * predates `reachableSkills` and the set was not on the record.
+         */
+        readonly reachable?: readonly string[];
+    };
+    /**
+     * Skill-graph entries whose own `when` matched this iteration and which the cursor
+     * law kept OFF the wire (8.15.0). A conditional entry is active exactly while the
+     * cursor is on it — `when` says where a turn STARTS, not what stays loaded — so an
+     * entry whose rule still matches while the graph is elsewhere is suppressed.
+     *
+     * Read it beside `cursorMove`, which names where the graph went instead: together
+     * they answer "why isn't my entry loading?" without re-running a predicate to
+     * guess. Absent when nothing was suppressed, and for every non-skill-graph run.
+     *
+     * Distinct from `agentfootprint.skill.reroute_superseded`, which reports a DISCRETE
+     * broken promise (a `read_skill` pick the gate accepted and a declared edge
+     * outranked). This is a CONTINUOUS condition — an entry whose rule stays true while
+     * the cursor is parked elsewhere is suppressed on every iteration — so it rides the
+     * per-iteration event.
+     */
+    readonly supersededIds?: readonly string[];
+}

package/dist/esm/events/payloads/context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context.js.map

package/dist/esm/events/payloads/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../../src/events/payloads/context.ts"],"names":[],"mappings":""}

package/dist/esm/events/payloads/cost.d.ts

@@ -0,0 +1,40 @@
+export interface CostTickPayload {
+    readonly scope: 'iteration' | 'turn' | 'run';
+    /**
+     * The model this money was spent on — the one `pricingTable.pricePerToken`
+     * was asked about.
+     *
+     * Always present: a tick exists because a priced call happened, and a call
+     * has a model. Without it the event said what was spent and not on what, so
+     * a run that switched models mid-loop (a `'retry-other'` failover, a
+     * summarizer on a cheaper model) produced a bill nothing could break down.
+     */
+    readonly model: string;
+    /**
+     * The provider that billed it, by `LLMProvider.name` — the other half of
+     * attribution, since one model name can be served by several providers
+     * (Bedrock and Anthropic both answer to a Claude model id, at different
+     * prices).
+     *
+     * Optional for ONE honest reason: a window/compaction strategy reports its
+     * summarizer spend through `WindowStrategyResult.spend`, and the provider is
+     * read from that strategy's `billing` declaration, which the seam leaves
+     * optional. Every shipped strategy declares it. Absent therefore means "the
+     * strategy that billed this did not say", never "the agent's provider".
+     */
+    readonly provider?: string;
+    readonly tokensInput: number;
+    readonly tokensOutput: number;
+    readonly estimatedUsd: number;
+    readonly cumulative: {
+        readonly tokensInput: number;
+        readonly tokensOutput: number;
+        readonly estimatedUsd: number;
+    };
+}
+export interface CostLimitHitPayload {
+    readonly kind: 'max_tokens' | 'max_cost' | 'max_iterations' | 'max_wallclock';
+    readonly limit: number;
+    readonly actual: number;
+    readonly action: 'abort' | 'warn' | 'degrade';
+}

package/dist/esm/events/payloads/cost.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cost.js.map

package/dist/esm/events/payloads/cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../../../../src/events/payloads/cost.ts"],"names":[],"mappings":""}

package/dist/esm/events/payloads/dependencyTypes.d.ts

@@ -0,0 +1,18 @@
+/** Internal type vocabulary; never re-exported by the payload facade. */
+export type { CompositionKind, ContextLifetime, ContextRecency, ContextRole, ContextSlot, ContextSource, LLMProviderName, ToolProtocol, ToolCallEventIdentity, } from '../types.js';
+export type { LLMMessage, PermissionCapability } from '../../provider-contract/types.js';
+export type { MemoryFlavor, MemoryStrategyKind, MemoryType } from '../../memory/define.types.js';
+export type { ArtifactOp, ArtifactRefusalReason } from '../../artifacts/capability.js';
+export type { ArtifactOrigin, ArtifactSweepReason } from '../../artifacts/types.js';
+export type { DatasetTimeAxis } from '../../time/axis.js';
+export type { ThinkingBlock } from '../../thinking/types.js';
+export type { LoopMoment } from '../../lib/moments.js';
+export type { ScriptsVerdict, TurnEndScripts } from '../../lib/scriptRecord.js';
+export type { InstructionDeliveryLease, ToolResultStatus } from '../../semantics/toolEffects.js';
+export type { ToolSemantics } from '../../semantics/types.js';
+export type { Basis, Expect, Standing } from '../../core/agent/findings/types.js';
+export type { ArgumentAsked, ArgumentCheckFailed, ArgumentClaim, ArgumentSource, } from '../../core/agent/arguments/rows.js';
+export type { AssessmentCheck, AssessmentReason, HonestyLayer, } from '../../core/agent/assessment/types.js';
+export type { ThinkingReplayReason } from '../../thinking/replay.js';
+export type { ContextError } from '../../integrity/finding/types.js';
+export type { CheckReport } from '../../integrity/disposition/types.js';

package/dist/esm/events/payloads/dependencyTypes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dependencyTypes.js.map

package/dist/esm/events/payloads/dependencyTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencyTypes.js","sourceRoot":"","sources":["../../../../src/events/payloads/dependencyTypes.ts"],"names":[],"mappings":""}

package/dist/esm/events/payloads/evaluation.d.ts

@@ -0,0 +1,297 @@
+import type { ScriptsVerdict } from './dependencyTypes.js';
+export interface EvalScorePayload {
+    readonly metricId: string;
+    readonly value: number;
+    readonly threshold?: number;
+    readonly target: 'iteration' | 'turn' | 'run' | 'toolCall';
+    /**
+     * What the score is about: the run id (`event.meta.runId`) for `'run'` /
+     * `'turn'`, the iteration index for `'iteration'`, the provider's call id
+     * for `'toolCall'`. A NAME, not a capability: run ids are minted in
+     * sequence and anyone can write one, so a host filing a score from user
+     * input (a feedback button) checks the run is that user's before it emits.
+     * `otelObservability` parents a score to a run only when the score's own
+     * meta places it in that run's session; otherwise it rides a span of its
+     * own that names the ref.
+     */
+    readonly targetRef: string;
+    readonly evaluator?: 'llm' | 'fn' | 'heuristic';
+    readonly evidence?: Readonly<Record<string, unknown>>;
+    /**
+     * The evaluator's own reading of the score, in a small vocabulary it
+     * documents — `'pass'` / `'fail'`, `'relevant'` / `'not_relevant'`.
+     * Optional and never derived: a `threshold` does not say which
+     * side of it passes, so no label is ever computed from one.
+     * `otelObservability` exports it BY DEFAULT as
+     * `gen_ai.evaluation.score.label` (the spec's "SHOULD have low
+     * cardinality"), so it must be a word from that vocabulary — never a
+     * judge's sentence, which belongs in {@link EvalScorePayload.explanation}.
+     */
+    readonly label?: string;
+    /**
+     * The evaluator's free-form reason for the score. It is CONTENT —
+     * a judge's reason can quote the answer it graded — so
+     * `otelObservability` exports it (`gen_ai.evaluation.explanation`) only
+     * under `captureContent`.
+     */
+    readonly explanation?: string;
+}
+export interface EvalThresholdCrossedPayload {
+    readonly metricId: string;
+    readonly direction: 'above' | 'below';
+    readonly value: number;
+    readonly threshold: number;
+    readonly actionTaken?: string;
+}
+/**
+ * Emitted (v2.13) when the agent's final answer fails the agent's
+ * configured `outputSchema` (the parser passed to
+ * `Agent.create({...}).outputSchema(parser)`).
+ *
+ * Scope: ONLY agent-level final-answer validation. Tool-input validation
+ * (`LLMToolSchema.inputSchema`) is a different concern handled by
+ * provider-side type checks; this event does NOT fire for tool-arg
+ * validation failures.
+ *
+ * Lives in the `agent.*` domain (parallel to `agent.turn_end`) because
+ * final-answer validation is a turn-level concern, not a generic
+ * evaluation metric.
+ *
+ * Pairs with `agentfootprint.error.retried` (when a reliability rule
+ * routes the failure to retry with feedback) or
+ * `agentfootprint.reliability.fail_fast` (when retries are exhausted).
+ *
+ * The event is the OBSERVABILITY signal — it fires on EVERY validation
+ * failure, regardless of whether retries are configured. Use the
+ * `attempt` + `cumulativeRetries` fields to drive operator dashboards
+ * for retry-rate trending (a leading indicator for model drift).
+ *
+ * Fires BEFORE PostDecide rules evaluate, so observability sees the
+ * failure even if a buggy rule routes to fail-fast or swallows it.
+ */
+/**
+ * Emitted (7.26) once per failed final answer that the run is about to
+ * ASK AGAIN about, on an agent built with
+ * `.outputSchema(parser, { retries })`.
+ *
+ * Its sibling `agent.output_schema_validation_failed` reports a failure the
+ * reliability gate is handling INSIDE one `call-llm` stage. This one reports
+ * a failure the LOOP is handling: the corrective message named here joins the
+ * conversation, the ReAct loop re-enters, and the next attempt arrives with
+ * its own `stream.llm_start` / `stream.llm_end` bracket and its own
+ * `cost.tick`. Subscribe to it to see how often a model needs a second ask —
+ * a leading indicator of drift, and of a schema that is harder to hit than
+ * its author thinks.
+ *
+ * Fires from the retry branch, after the corrective turn is committed, so a
+ * consumer that reads `snapshot.sharedState.outputAttempts` finds the
+ * matching row (joined by `correctiveMessageHash`) already there.
+ */
+/**
+ * The run's answer does NOT satisfy its own `outputSchema` (8.18.0).
+ *
+ * Fires once, from the Route decider, on the run that hands back an answer the
+ * contract rejects — including the default `retries: 0` case, where the first
+ * answer is the only one. It is the event that was missing: `run()` returned
+ * the failing string, `runTyped()` threw at a boundary the caller may not have
+ * used, and nothing in between said a contract had been missed.
+ *
+ * Alert on it. A rise in `stage: 'json-parse'` is a model that stopped
+ * honouring the instruction; a rise in `'schema-validate'` is drift against
+ * the shape; any `brokenBy` at all is one of your own output rules.
+ */
+export interface AgentOutputContractUnmetPayload {
+    /** Which half of validation failed. */
+    readonly stage: 'json-parse' | 'schema-validate';
+    /** The validator's own message, verbatim. DATA, not narrative. */
+    readonly error: string;
+    /** Failing field path when the parser exposes one (Zod-style issues). */
+    readonly path?: string;
+    /** Answers judged in this run, the first included. `1` under `retries: 0`. */
+    readonly attempts: number;
+    /** Corrective re-asks the run paid for. `0` under `retries: 0`. */
+    readonly retriesSpent: number;
+    /** True when `.outputFallback()` is configured — a tier `runTyped()` reaches
+     *  and `run()` does not. */
+    readonly fallbackConfigured: boolean;
+    /** The ReAct iteration that produced the answer. */
+    readonly iteration: number;
+    /** Present when an `act({ output })` middleware rewrote an answer that had
+     *  PASSED into one that fails — the name of that middleware. The run stops
+     *  re-asking when this is set: the model's answer was already right. */
+    readonly brokenBy?: string;
+}
+export interface AgentOutputSchemaRetryPayload {
+    /** 1-based attempt that just failed. `1` is the first answer. */
+    readonly attempt: number;
+    /** Corrective asks left AFTER this one. `0` means this is the last. */
+    readonly retriesRemaining: number;
+    /** The ReAct iteration the failed answer came from. A retry consumes an
+     *  iteration, so the next attempt reports `iteration + 1`. */
+    readonly iteration: number;
+    /** Which half of validation failed — `'json-parse'` (the model emitted
+     *  prose) vs `'schema-validate'` (JSON, wrong shape). They trend
+     *  differently under model drift. */
+    readonly stage: 'json-parse' | 'schema-validate';
+    /** The validator's own message, verbatim. DATA, not narrative: it is
+     *  quoted into the corrective message after an authored frame, and it is
+     *  quoted here the same way. */
+    readonly error: string;
+    /** Failing field path when the parser exposes one (Zod-style issues). */
+    readonly path?: string;
+    /** `fnv1a` of the corrective message that went back to the model — the
+     *  join to the message in `history` and to the `outputAttempts` row. */
+    readonly correctiveMessageHash: string;
+}
+/**
+ * One verdict from the evidence gate (`.namesAndNumbersFromEvidence()`,
+ * 9.35.0) — fired once per would-be-final answer the gate judged, whatever
+ * the posture and whatever the outcome.
+ *
+ * It rides the emit channel rather than a CommitBundle because it is a fact
+ * about ONE attempt, not conversation state; the only thing that reaches the
+ * commit log is the terminal verdict (`unsupportedValues`), which the boundary
+ * needs.
+ *
+ * **What this event does NOT claim:** the check catches values that appear in
+ * no tool result. It cannot see a false statement assembled from real values,
+ * so `action: 'grounded'` means "every name and number was read from
+ * somewhere", never "the answer is true".
+ */
+export interface AgentEvidenceCheckedPayload {
+    /** The ReAct iteration that produced the judged answer. */
+    readonly iteration: number;
+    /** The posture in force — `'assist'` records only, `'guard'` may revise
+     *  once, `'rails'` may withhold the answer. */
+    readonly posture: 'assist' | 'guard' | 'rails';
+    /** How many distinct values the answer had to ground. `0` means the answer
+     *  asserted nothing the extractor treats as data. INCLUDES exempt values —
+     *  see {@link lookedUp}. */
+    readonly candidates: number;
+    /**
+     * How many of `candidates` the gate actually looked up in the tool results:
+     * the values found plus the values not found, before `unsupported` is
+     * sliced. The rest were EXEMPT — the person's message, the conversation or
+     * the app's own instructions (recalled memory included) already held them —
+     * and were never looked up. Present on every row from the release that
+     * added it; absent on a recording made before it, which therefore cannot
+     * say how many values were looked up.
+     */
+    readonly lookedUp?: number;
+    /** The values that appear in no tool result, truncated to a readable list.
+     *  Empty when `action` is `'grounded'`. Under `code: 'match'` each says
+     *  where it sat: `'code'` when every occurrence was inside a fenced block
+     *  that matched no submission, `'prose'` otherwise. */
+    readonly unsupported: readonly {
+        readonly value: string;
+        readonly shape: string;
+        readonly region?: 'prose' | 'code';
+    }[];
+    /**
+     *   • `'grounded'`       — every value was found; the answer stands.
+     *   • `'revision-asked'` — the values went back to the model for one more
+     *                          turn (emitted by the EvidenceRecheck branch).
+     *   • `'flagged'`        — the answer ships carrying them, on the record.
+     *   • `'refused'`        — `'rails'`: the answer was withheld and the
+     *                          boundary raises `UnsupportedValuesError`.
+     */
+    readonly action: 'grounded' | 'flagged' | 'revision-asked' | 'refused';
+    /** True when this judgement ran on an answer a revision already corrected —
+     *  which is how a reader tells "the revision fixed it" (`grounded`, after
+     *  revision) from "it did not" (`flagged`/`refused`, after revision). */
+    readonly afterRevision: boolean;
+    /** Set when the evidence index hit its ceiling and could not hold every
+     *  tool result. The gate then records its verdict WITHOUT acting on it —
+     *  a partial corpus can call a grounded value fabricated. */
+    readonly evidenceTruncated?: boolean;
+    /**
+     * WHICH RESULTS OF THIS TURN THE ANSWER'S VALUES WERE READ FROM — on the
+     * verdicts about an answer that ships (`'grounded'`, `'flagged'`,
+     * `'refused'`), never on `'revision-asked'` (a draft). One entry per
+     * `role: 'tool'` result of this turn that carried at least one of the
+     * answer's names and numbers: `values` = how many, `only` = how many of
+     * those no other result of this turn carried. A result of this turn that
+     * is NOT listed carried none of them — a fact about tokens, not meaning:
+     * read it as "the answer cites nothing from it", never "unused" (an answer
+     * that states no value can still rest on a result). `[]` is a fact too:
+     * no result of this turn carried any of them (an answer drawn from an
+     * earlier turn, or one that states no value — `lookedUp` tells which).
+     *
+     * ABSENT when the list cannot be whole: the evidence index hit its ceiling,
+     * or one value was carried by more results than the index keeps. Absent on
+     * recordings made before the field existed. Identities and counts only,
+     * never a value (`evidence/answerCarriers.ts`).
+     */
+    readonly carriedBy?: readonly {
+        readonly toolCallId: string;
+        readonly values: number;
+        readonly only: number;
+    }[];
+    /**
+     * On `action: 'revision-asked'` only, and only when the turn held placed
+     * artifact tickets a served `wants` tool can spend: the refs the
+     * correction NAMED as the route to a grounded number. Absent otherwise —
+     * including for every agent without a `wants`-declaring tool.
+     */
+    readonly stagedRefs?: readonly {
+        readonly ref: string;
+        readonly kind: string;
+    }[];
+    /** The spender tools the correction named, beside {@link stagedRefs}. */
+    readonly spenderTools?: readonly string[];
+    /**
+     * Under the figures dial (`namesAndNumbersFromEvidence({ figures: true })`),
+     * on `'grounded'`, `'flagged'` and `'refused'`: the numbers no tool result
+     * carried that ARE a declared derivation of the numbers the results carry —
+     * each with its `derivation` (`rounded`, `unit-scale`, `column-sum`,
+     * `column-ratio`, `column-difference`, `complement`) and `from` (the
+     * operands, in the results' own keys). Not read and not invented: the model
+     * computed them. Present (possibly `[]`) exactly when the dial is on, so its
+     * presence says the derivation check ran; the `unsupported` numbers beside
+     * it matched no value AND no derivation. Sliced like `unsupported`.
+     */
+    readonly computed?: readonly {
+        readonly value: string;
+        readonly shape: string;
+        readonly derivation: string;
+        readonly from: string;
+    }[];
+    /**
+     * Under `.namesAndNumbersFromEvidence({ code: 'match' })`, on a prose
+     * answer: one verdict per fenced block the answer showed — a block equal,
+     * byte for byte after removing only the Markdown wrapper, to a program a
+     * call of THIS turn submitted to a declared code-running tool carries that
+     * call's id, tool and label (`completed`, `outcome-unknown`, …) and was not
+     * read for values; any other block is `unmatched` with a reason and was
+     * read as prose. `earlierTurnRows` counts earlier turns' script rows (never
+     * compared); `regionsDropped` the blocks past the cap. Never the code.
+     */
+    readonly scripts?: ScriptsVerdict;
+}
+/**
+ * The staged-refs nudge fired (`.namesAndNumbersFromEvidence({ nudge: true })`)
+ * — one per iteration whose request gained the late line naming staged
+ * artifact refs and the `wants` tool that spends them.
+ *
+ * The line itself is request-only (never history), so this event is the ONE
+ * record that it existed: which refs, which spenders, which iteration. A run
+ * where the nudge never armed emits none of these.
+ */
+export interface AgentGroundingNudgedPayload {
+    /** The ReAct iteration whose request carried the line. */
+    readonly iteration: number;
+    /** The staged refs the line named — `ref` verbatim, `kind` as minted
+     *  (`Tool.resultKind` / `tool-result/<toolName>`). Capped; see
+     *  {@link refsOmitted}. */
+    readonly refs: readonly {
+        readonly ref: string;
+        readonly kind: string;
+    }[];
+    /** Matched refs beyond the cap, stated rather than silently dropped.
+     *  Absent when every match was named. */
+    readonly refsOmitted?: number;
+    /** The spender tools named, by their registered names — the tools whose
+     *  declared `wants` matched a staged ref's kind, exact-string, never by
+     *  tool name. */
+    readonly tools: readonly string[];
+}

package/dist/esm/events/payloads/evaluation.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=evaluation.js.map

package/dist/esm/events/payloads/evaluation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluation.js","sourceRoot":"","sources":["../../../../src/events/payloads/evaluation.ts"],"names":[],"mappings":""}