agentfootprint 9.75.0 → 9.76.1

package/dist/esm/core/runbook/types.d.ts

@@ -0,0 +1,203 @@
+/**
+ * runbook/types — the vocabulary of the runbook bridge.
+ *
+ * Pattern: one options bag, four concerns (declarations, procedure, evidence
+ *          policy, walk policy) + one envelope type split into a MANDATORY
+ *          SPINE and an OPTIONAL projection. Pure data, no behavior.
+ * Role:    core/ layer. `runbookAsTool.ts` consumes; consumers read the
+ *          envelope types when they assert on results.
+ * Emits:   N/A.
+ *
+ * The SPINE / PROJECTION split is load-bearing honesty, not taste: the spine
+ * (coverage, provenance, rule version, the recorded walk) is what EVERY
+ * runbook ships whatever its shape, so an answer can never arrive without its
+ * boundary; the verdict/rowset projection is one shape of answer (a triage),
+ * selected by `resultKind: 'verdict/*'` — an action-taking runbook ships the
+ * spine plus its own `report` payload and no rowset. The spine's wire shape
+ * is explicitly PROVISIONAL until a second, differently-shaped consumer has
+ * shipped through it.
+ */
+import type { CombinedRecorder, FlowChart, RedactionPolicy } from 'footprintjs';
+import type { CoverageItem } from '../agent/coverage/types.js';
+import type { ToolDispatch, ToolOwner, ToolResultCeiling } from '../tools.js';
+import type { ToolResultClass } from '../../lib/semantics/types.js';
+import type { ToolWants } from '../../artifacts/wants.js';
+/**
+ * The procedure: a factory invoked PER CALL with the run's own tool dispatch
+ * (`ctx.tools`), returning a FRESH chart whose stages close over it.
+ *
+ * Per call for two reasons that are really one: a chart shared between two
+ * runs is a chart whose closures belong to whichever run built it last, and
+ * the dispatch only exists at execute time — so the factory is both the
+ * fresh-chart law and the delivery mechanism.
+ *
+ * It is ALSO invoked once at definition time, with a probe dispatch whose
+ * `has` answers false and whose `call` refuses — to read the chart's declared
+ * contract (input schema, the named decider's branches). Stage bodies do not
+ * run at build, so a well-formed factory pays nothing; a factory with side
+ * effects at build time is a factory that lies about being a declaration.
+ */
+export type RunbookProcedure = (tools: ToolDispatch) => FlowChart;
+/** Rule provenance — threaded bridge → envelope → coverage sentence, so an
+ *  answer produced under one reading of the rules can be told apart from an
+ *  answer produced under the next. */
+export interface RunbookRules {
+    /** The rule set's name ('health-signal'). Non-empty. */
+    readonly name: string;
+    /** Its version stamp ('v1'). Non-empty; bump when the READING changes,
+     *  never for wording. */
+    readonly version: string;
+}
+/** The verdict/rowset projection's dials. */
+export interface RunbookVerdictsOptions {
+    /**
+     * The decider stage (by id or name) whose declared branch labels generate
+     * `verdict_meanings`. Branch descriptions come from the chart's own
+     * structure when the decider is statically declared; rule labels observed
+     * in this run's decide() evidence refine them (and are the only source
+     * when the decider lives inside a dynamically generated fan-out branch,
+     * where build-time structure cannot see it).
+     */
+    readonly decider: string;
+    /** Cap on `verdicts` rows AND the rendered table — ONE number for both
+     *  halves (a longer list beside a shorter table is an invitation to retype
+     *  identifiers). Default 50. */
+    readonly maxRows?: number;
+}
+/** The walk policy. */
+export interface RunbookWalkOptions {
+    /** Row cap on the minted walk (default 500). When the full walk does not
+     *  fit, the CONTROL FLOW survives — see `walk.ts` for the projection law. */
+    readonly cap?: number;
+}
+/** Everything `runbookAsTool` accepts. Smallest legal call:
+ *  `{ name, description, procedure }` — and it still yields the spine. */
+export interface RunbookAsToolOptions {
+    /** Tool name the LLM dispatches by. */
+    readonly name: string;
+    /** REQUIRED — a description-less tool is invisible to the model. */
+    readonly description: string;
+    /** The procedure factory — see {@link RunbookProcedure}. */
+    readonly procedure: RunbookProcedure;
+    /** Selects the envelope projection (`'verdict/*'` gets the rowset) AND is
+     *  the artifact kind a placed result is minted under. */
+    readonly resultKind?: string;
+    readonly resultClass?: ToolResultClass;
+    readonly owner?: ToolOwner;
+    readonly resultCeiling?: ToolResultCeiling;
+    readonly wants?: ToolWants;
+    readonly argumentsFrom?: readonly string[];
+    /** The named ingredient tools the procedure calls through `ctx.tools` —
+     *  drift-checked at agent build. */
+    readonly composedOf?: readonly string[];
+    /** Explicit input schema wins; otherwise the chart's `.contract()` input
+     *  is lifted when it is a plain JSON-Schema object (a parseable schema —
+     *  zod et al. — cannot be serialized for the model and falls back to the
+     *  empty-object default). */
+    readonly inputSchema?: Readonly<Record<string, unknown>>;
+    /** Rule provenance — see {@link RunbookRules}. */
+    readonly rules?: RunbookRules;
+    /** The verdict projection's dials — see {@link RunbookVerdictsOptions}. */
+    readonly verdicts?: RunbookVerdictsOptions;
+    /** The walk policy — see {@link RunbookWalkOptions}. */
+    readonly walk?: RunbookWalkOptions;
+    /** Observers attached to each invocation's fresh inner executor. */
+    readonly recorders?: ReadonlyArray<CombinedRecorder>;
+    /** Keep each invocation's inner record for `inspect_tool_run` descent. */
+    readonly keepRecord?: boolean;
+    /** Bounded LRU size for kept records (requires `keepRecord: true`). */
+    readonly keepRecordLimit?: number;
+    /** Redaction policy for the inner run (commit-time scrub). */
+    readonly redact?: RedactionPolicy;
+}
+/**
+ * The recorded-walk descriptor — ALWAYS on the spine. The walk itself ships
+ * as an artifact ticket (`ref`), never as bytes in the envelope; with no
+ * store attached (or a failed mint) the descriptor still states its
+ * counters and the `note` names why there is no ticket — a missing walk must
+ * never be mistaken for a short run.
+ */
+export interface WalkDescriptor {
+    /** The claim-ticket ref of the minted walk artifact. Absent when no store
+     *  is attached or the mint failed — `note` says which. */
+    readonly ref?: string;
+    /** The artifact kind (`'recording/chart-walk'`). Present with `ref`. */
+    readonly kind?: string;
+    /** Rows in the minted artifact. */
+    readonly rows: number;
+    /** Total execution steps the narrative recorder counted — spans isolated
+     *  subflow logs, which the root commit log cannot. */
+    readonly steps_executed: number;
+    /** `'full'` — every narrative entry fit under the cap; `'control-flow'` —
+     *  it did not, and the stages/forks/subflows/decisions survived while the
+     *  per-key reads and writes were dropped. */
+    readonly projection: 'full' | 'control-flow';
+    readonly shown: number;
+    readonly total: number;
+    readonly complete: boolean;
+    /**
+     * WHICH SEGMENT of the run this walk covers. `'full'` for an un-gated run
+     * (all of phase 1). When approval gates land, a resumed run's recorders
+     * start empty on the fresh executor — its walk will say `'post-resume'`
+     * and its counters will count only that segment; the discriminant ships
+     * NOW so the wire does not break then.
+     */
+    readonly walk_segment: 'full' | 'pre-pause' | 'post-resume';
+    /** The human sentence: what the walk is, and (when projected) what the
+     *  control-flow projection kept and dropped, or why there is no ticket. */
+    readonly note: string;
+}
+/** One verdict row, as the chart wrote it. The bridge reads rows from the
+ *  final state's `verdicts` key and requires only `verdict`; every other
+ *  column is the app's own vocabulary. */
+export interface VerdictRow {
+    readonly verdict: string;
+    readonly [column: string]: unknown;
+}
+/** The mandatory-spine + optional-projection envelope every runbook returns
+ *  (unless an inner absence passed through — then the answer IS that absence,
+ *  verbatim). Recognized by the framework's coverage funnel at the dispatch
+ *  boundary like any `coverage()` ledger. */
+export interface RunbookEnvelope {
+    readonly af_coverage: {
+        readonly checked?: readonly CoverageItem[];
+        readonly not_checked?: readonly CoverageItem[];
+        readonly cannot_cover?: readonly CoverageItem[];
+        /** The static coverage law sentence (the `coverage()` note). */
+        readonly note: string;
+        /** The run's own sentence — names the rule set and version. */
+        readonly sentence: string;
+    };
+    readonly result: {
+        /** Re-emitted FIRST: the carried inner provenance stamp (if any inner
+         *  tool declared one — a LOCAL SEED confession survives composition)
+         *  plus this call's own `{tool, toolCallId}`. */
+        readonly af_provenance: Readonly<Record<string, unknown>>;
+        /** `rules.version`, or the honest `'undeclared'` when no rules were
+         *  declared — the field never silently vanishes. */
+        readonly rule_version: string;
+        /** The recorded walk — always present. */
+        readonly walk: WalkDescriptor;
+        readonly verdicts?: readonly VerdictRow[];
+        readonly rows_shown?: number;
+        readonly rows_total?: number;
+        readonly rows_complete?: boolean;
+        /** Pre-rendered markdown table over the SAME rows as `verdicts`. */
+        readonly table?: string;
+        /** The render law, stated to the model. Present with `table`. */
+        readonly render_note?: string;
+        /** branch → meaning, GENERATED from the decider's declared branches and
+         *  the rule labels this run's evidence carried — never hand-restated. */
+        readonly verdict_meanings?: Readonly<Record<string, string>>;
+        /** Present ONLY when the chart's `report` spelled one of the envelope's
+         *  own names: it names every discarded field and says the values under
+         *  those names are the bridge's. Absent on the clean path. */
+        readonly report_note?: string;
+        /** Everything the chart put in its `report` state key — the app's own
+         *  result fields, spread here verbatim BESIDE the spine. Spine keys win:
+         *  a report field spelling `af_coverage`, `af_provenance`, `rule_version`,
+         *  `walk`, `report_note`, or a projection key this run assembled is
+         *  discarded and named in `report_note`. */
+        readonly [appField: string]: unknown;
+    };
+}

package/dist/esm/core/runbook/types.js

@@ -0,0 +1,21 @@
+/**
+ * runbook/types — the vocabulary of the runbook bridge.
+ *
+ * Pattern: one options bag, four concerns (declarations, procedure, evidence
+ *          policy, walk policy) + one envelope type split into a MANDATORY
+ *          SPINE and an OPTIONAL projection. Pure data, no behavior.
+ * Role:    core/ layer. `runbookAsTool.ts` consumes; consumers read the
+ *          envelope types when they assert on results.
+ * Emits:   N/A.
+ *
+ * The SPINE / PROJECTION split is load-bearing honesty, not taste: the spine
+ * (coverage, provenance, rule version, the recorded walk) is what EVERY
+ * runbook ships whatever its shape, so an answer can never arrive without its
+ * boundary; the verdict/rowset projection is one shape of answer (a triage),
+ * selected by `resultKind: 'verdict/*'` — an action-taking runbook ships the
+ * spine plus its own `report` payload and no rowset. The spine's wire shape
+ * is explicitly PROVISIONAL until a second, differently-shaped consumer has
+ * shipped through it.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/core/runbook/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/runbook/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/esm/core/runbook/verdicts.d.ts

@@ -0,0 +1,78 @@
+/**
+ * runbook/verdicts — the OPTIONAL verdict/rowset projection.
+ *
+ * Pattern: pure selection + rendering over the run's final state, plus one
+ *          tiny recorder that harvests decide() evidence for generated
+ *          meanings. Selected by `resultKind: 'verdict/*'`; a runbook of any
+ *          other kind never sees this module.
+ * Role:    core/runbook.
+ * Emits:   N/A.
+ *
+ * THE ONE-NUMBER LAW: the rendered table and the structured `verdicts` list
+ * show the SAME rows under the SAME cap. A rendered table beside a longer
+ * structured list is an invitation that gets accepted — rows come back
+ * retyped with subtly wrong identifiers.
+ *
+ * GENERATED MEANINGS, never hand-restated: `verdict_meanings` is composed
+ * from (a) the named decider's declared branches in the chart's own structure
+ * (branch description, falling back to branch name), overlaid by (b) the rule
+ * LABELS this run's decide() evidence carried — the rule speaking for itself.
+ * A decider inside a dynamically generated fan-out branch is invisible to (a)
+ * by construction (the branch chart does not exist at build time); (b) still
+ * covers every verdict an executed rule produced.
+ */
+import type { CombinedRecorder } from 'footprintjs';
+import type { FlowChart } from 'footprintjs';
+import type { VerdictRow } from './types.js';
+/** Default cap on `verdicts` rows and the rendered table. */
+export declare const DEFAULT_MAX_ROWS = 50;
+/** The render law, stated to the model beside every table. */
+export declare const VERDICT_RENDER_NOTE: string;
+/** The reserved verdict word for "no classification was reached" — rows
+ *  carrying it are counted into the coverage ledger as not-checked ground
+ *  (the three-outcome honesty: reached, reached-and-clear, DECLINED). */
+export declare const DECLINED_VERDICT = "declined";
+/** Read the rowset off the final state's `verdicts` key — an array of bags
+ *  each carrying a string `verdict`. Anything else reads as "no rowset". */
+export declare function verdictRowsOf(state: Readonly<Record<string, unknown>>): VerdictRow[];
+/**
+ * Render the shown rows as one markdown table. Columns are the FIRST row's
+ * own keys in declaration order — the chart writes its rows, so the chart
+ * owns the column vocabulary; the bridge only renders it.
+ */
+export declare function renderVerdictTable(rows: readonly VerdictRow[]): string;
+/** The two spellings of the configured decider, once the static walk has
+ *  (maybe) resolved it — flow events report the decider by name. */
+export interface DeciderIdentity {
+    readonly spellings: ReadonlySet<string>;
+    /** branch → declared meaning, from the chart's own structure. */
+    readonly declared: ReadonlyMap<string, string>;
+}
+/**
+ * Find the named decider in the chart's static structure (root graph plus
+ * statically declared subflows) and read its branches. Loop-ref stubs are
+ * skipped FIRST — they deliberately violate node-id uniqueness.
+ */
+export declare function resolveDecider(chart: FlowChart, decider: string): DeciderIdentity;
+/** The evidence harvest: rule labels observed in this run, branch → label. */
+export interface MeaningsHarvest {
+    readonly recorder: CombinedRecorder;
+    readonly observed: ReadonlyMap<string, string>;
+}
+/**
+ * A tiny flow recorder capturing the named decider's decide() evidence as it
+ * fires — collected DURING the traversal, never reconstructed after. Rule
+ * labels are harvested for every rule the evidence lists (matched or not):
+ * a rule that was evaluated has spoken its label, whichever branch won.
+ *
+ * A decider inside a subflow (including a generated fan-out branch) reports
+ * itself PATH-PREFIXED (`per-subject~0/Protection posture`), so the match is
+ * on the LAST `/`-segment — the same last-delimiter reading every upstream
+ * parser of these paths uses, which is what keeps the generated-branch
+ * marker opaque here.
+ */
+export declare function meaningsRecorder(identity: DeciderIdentity): MeaningsHarvest;
+/** Compose the final meanings: declared branches first, observed rule labels
+ *  winning where both speak (the rule is the sharper sentence). Undefined
+ *  when neither source produced anything — absent, never `{}`. */
+export declare function composeMeanings(identity: DeciderIdentity, observed: ReadonlyMap<string, string>): Record<string, string> | undefined;

package/dist/esm/core/runbook/verdicts.js

@@ -0,0 +1,148 @@
+/**
+ * runbook/verdicts — the OPTIONAL verdict/rowset projection.
+ *
+ * Pattern: pure selection + rendering over the run's final state, plus one
+ *          tiny recorder that harvests decide() evidence for generated
+ *          meanings. Selected by `resultKind: 'verdict/*'`; a runbook of any
+ *          other kind never sees this module.
+ * Role:    core/runbook.
+ * Emits:   N/A.
+ *
+ * THE ONE-NUMBER LAW: the rendered table and the structured `verdicts` list
+ * show the SAME rows under the SAME cap. A rendered table beside a longer
+ * structured list is an invitation that gets accepted — rows come back
+ * retyped with subtly wrong identifiers.
+ *
+ * GENERATED MEANINGS, never hand-restated: `verdict_meanings` is composed
+ * from (a) the named decider's declared branches in the chart's own structure
+ * (branch description, falling back to branch name), overlaid by (b) the rule
+ * LABELS this run's decide() evidence carried — the rule speaking for itself.
+ * A decider inside a dynamically generated fan-out branch is invisible to (a)
+ * by construction (the branch chart does not exist at build time); (b) still
+ * covers every verdict an executed rule produced.
+ */
+/** Default cap on `verdicts` rows and the rendered table. */
+export const DEFAULT_MAX_ROWS = 50;
+/** The render law, stated to the model beside every table. */
+export const VERDICT_RENDER_NOTE = 'table is PRE-RENDERED over the same rows as `verdicts` — output it VERBATIM. Never ' +
+    'retype an identifier from `verdicts`; a transcribed name that looks right and matches ' +
+    'nothing is the failure this note exists to stop.';
+/** The reserved verdict word for "no classification was reached" — rows
+ *  carrying it are counted into the coverage ledger as not-checked ground
+ *  (the three-outcome honesty: reached, reached-and-clear, DECLINED). */
+export const DECLINED_VERDICT = 'declined';
+/** Read the rowset off the final state's `verdicts` key — an array of bags
+ *  each carrying a string `verdict`. Anything else reads as "no rowset". */
+export function verdictRowsOf(state) {
+    const raw = state.verdicts;
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((row) => row !== null &&
+        typeof row === 'object' &&
+        !Array.isArray(row) &&
+        typeof row.verdict === 'string');
+}
+/** The one place a `—` is written for a value the source did not report — a
+ *  blank cell reads as a zero; a dash reads as "not reported". */
+function cell(value) {
+    if (value === null || value === undefined || value === '')
+        return '—';
+    if (value === true)
+        return 'yes';
+    if (value === false)
+        return 'no';
+    return String(value).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+/**
+ * Render the shown rows as one markdown table. Columns are the FIRST row's
+ * own keys in declaration order — the chart writes its rows, so the chart
+ * owns the column vocabulary; the bridge only renders it.
+ */
+export function renderVerdictTable(rows) {
+    if (rows.length === 0)
+        return 'No rows in the projected set.';
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const columns = Object.keys(rows[0]);
+    const head = `| ${columns.join(' | ')} |\n|${columns.map(() => '---').join('|')}|\n`;
+    return (head +
+        rows.map((row) => `| ${columns.map((column) => cell(row[column])).join(' | ')} |`).join('\n'));
+}
+/**
+ * Find the named decider in the chart's static structure (root graph plus
+ * statically declared subflows) and read its branches. Loop-ref stubs are
+ * skipped FIRST — they deliberately violate node-id uniqueness.
+ */
+export function resolveDecider(chart, decider) {
+    const spellings = new Set([decider]);
+    const declared = new Map();
+    const visited = new Set();
+    const walk = (node) => {
+        if (node === undefined || node.isLoopRef === true || visited.has(node))
+            return;
+        visited.add(node);
+        if ((node.id === decider || node.name === decider) && (node.children?.length ?? 0) > 0) {
+            if (node.id !== undefined)
+                spellings.add(node.id);
+            if (node.name !== undefined)
+                spellings.add(node.name);
+            for (const child of node.children ?? []) {
+                const branch = child.branchId ?? child.id;
+                if (branch === undefined)
+                    continue;
+                const meaning = child.description ?? child.name;
+                if (meaning !== undefined && !declared.has(branch))
+                    declared.set(branch, meaning);
+            }
+        }
+        for (const child of node.children ?? [])
+            walk(child);
+        walk(node.next);
+    };
+    walk(chart.root);
+    for (const subflow of Object.values(chart.subflows ?? {})) {
+        walk(subflow.root);
+    }
+    return { spellings, declared };
+}
+/**
+ * A tiny flow recorder capturing the named decider's decide() evidence as it
+ * fires — collected DURING the traversal, never reconstructed after. Rule
+ * labels are harvested for every rule the evidence lists (matched or not):
+ * a rule that was evaluated has spoken its label, whichever branch won.
+ *
+ * A decider inside a subflow (including a generated fan-out branch) reports
+ * itself PATH-PREFIXED (`per-subject~0/Protection posture`), so the match is
+ * on the LAST `/`-segment — the same last-delimiter reading every upstream
+ * parser of these paths uses, which is what keeps the generated-branch
+ * marker opaque here.
+ */
+export function meaningsRecorder(identity) {
+    const observed = new Map();
+    const lastSegment = (path) => path.slice(path.lastIndexOf('/') + 1);
+    const recorder = {
+        id: 'runbook-verdict-meanings',
+        onDecision(event) {
+            if (!identity.spellings.has(lastSegment(event.decider)))
+                return;
+            const evidence = event.evidence;
+            for (const rule of evidence?.rules ?? []) {
+                if (typeof rule.branch === 'string' && typeof rule.label === 'string') {
+                    observed.set(rule.branch, rule.label);
+                }
+            }
+        },
+    };
+    return { recorder, observed };
+}
+/** Compose the final meanings: declared branches first, observed rule labels
+ *  winning where both speak (the rule is the sharper sentence). Undefined
+ *  when neither source produced anything — absent, never `{}`. */
+export function composeMeanings(identity, observed) {
+    const meanings = {};
+    for (const [branch, meaning] of identity.declared)
+        meanings[branch] = meaning;
+    for (const [branch, label] of observed)
+        meanings[branch] = label;
+    return Object.keys(meanings).length > 0 ? meanings : undefined;
+}
+//# sourceMappingURL=verdicts.js.map

package/dist/esm/core/runbook/verdicts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdicts.js","sourceRoot":"","sources":["../../../../src/core/runbook/verdicts.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/runbook/walk.d.ts

@@ -0,0 +1,72 @@
+/**
+ * runbook/walk — the recorded walk: projection law, counters, mint.
+ *
+ * Pattern: pure projection (`projectWalk`) + one guarded side effect
+ *          (`mintWalk`, which files the artifact and NEVER fails the answer).
+ * Role:    core/runbook. The walk is not a debugging extra — a procedure that
+ *          cannot show how it reached a verdict is a procedure somebody has
+ *          to take on trust.
+ * Emits:   nothing (the artifact capability emits its own `artifacts.*`).
+ *
+ * THE CAP LAW, and why a head slice is the wrong cap: in a chart walk the
+ * per-key reads and writes come FIRST and the decisions come LAST, so a
+ * naive head slice over a fleet sweep keeps four hundred writes and drops
+ * every decision — a walk with the walking taken out. When the whole thing
+ * does not fit, the CONTROL FLOW survives (stages, forks, subflows, and
+ * every `condition` entry carrying its decide() evidence) and the projection
+ * is DECLARED, so a reader knows which of the two they are holding.
+ */
+import type { ToolExecutionContext } from '../tools.js';
+import type { WalkDescriptor } from './types.js';
+/** The default row cap — a readable artifact, not an archive. The count is
+ *  always reported, so a truncated walk says it is truncated instead of
+ *  looking like a short run. */
+export declare const DEFAULT_WALK_CAP = 500;
+/** A narrative entry as this module reads it. `rawValue` is deliberately NOT
+ *  in the list: it is a LIVE reference into engine memory and has no business
+ *  in a value checked into an artifact store. */
+export interface NarrativeEntryView {
+    readonly type: string;
+    readonly text: string;
+    readonly depth: number;
+    readonly stageName?: string;
+    readonly stageId?: string;
+    readonly runtimeStageId?: string;
+    readonly subflowId?: string;
+}
+/** One walk row — plain data by construction (every field projected). */
+export interface WalkRow {
+    readonly step: number;
+    readonly type: string;
+    readonly depth: number;
+    readonly stage: string | null;
+    readonly stage_id: string | null;
+    readonly runtime_stage_id: string | null;
+    readonly subflow: string | null;
+    readonly text: string;
+}
+/** The pure projection result — rows plus truthful counters. */
+export interface ProjectedWalk {
+    readonly rows: readonly WalkRow[];
+    readonly projection: 'full' | 'control-flow';
+    readonly shown: number;
+    readonly total: number;
+    readonly complete: boolean;
+}
+/** Apply the cap law. Counters are about the WHOLE narrative (`total`), so a
+ *  projected walk cannot read as a short run. */
+export declare function projectWalk(entries: readonly NarrativeEntryView[], cap: number): ProjectedWalk;
+/** What the mint needs from the call. */
+export interface WalkMintFacts {
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly runId?: string;
+    readonly stepsExecuted: number;
+}
+/**
+ * File the walk and build the descriptor. THE SPINE ALWAYS GETS A
+ * DESCRIPTOR: with no store attached, or when the mint fails, the counters
+ * still travel and the note names why there is no ticket — a failed mint
+ * costs the TICKET, never the answer and never the counts.
+ */
+export declare function mintWalk(ctx: ToolExecutionContext, projected: ProjectedWalk, facts: WalkMintFacts): Promise<WalkDescriptor>;

package/dist/esm/core/runbook/walk.js

@@ -0,0 +1,110 @@
+/**
+ * runbook/walk — the recorded walk: projection law, counters, mint.
+ *
+ * Pattern: pure projection (`projectWalk`) + one guarded side effect
+ *          (`mintWalk`, which files the artifact and NEVER fails the answer).
+ * Role:    core/runbook. The walk is not a debugging extra — a procedure that
+ *          cannot show how it reached a verdict is a procedure somebody has
+ *          to take on trust.
+ * Emits:   nothing (the artifact capability emits its own `artifacts.*`).
+ *
+ * THE CAP LAW, and why a head slice is the wrong cap: in a chart walk the
+ * per-key reads and writes come FIRST and the decisions come LAST, so a
+ * naive head slice over a fleet sweep keeps four hundred writes and drops
+ * every decision — a walk with the walking taken out. When the whole thing
+ * does not fit, the CONTROL FLOW survives (stages, forks, subflows, and
+ * every `condition` entry carrying its decide() evidence) and the projection
+ * is DECLARED, so a reader knows which of the two they are holding.
+ */
+import { CHART_WALK_ARTIFACT_KIND, chartWalkPutInput } from '../../artifacts/recordingArtifact.js';
+/** The default row cap — a readable artifact, not an archive. The count is
+ *  always reported, so a truncated walk says it is truncated instead of
+ *  looking like a short run. */
+export const DEFAULT_WALK_CAP = 500;
+function toWalkRow(entry, step) {
+    return {
+        step,
+        type: entry.type,
+        depth: entry.depth,
+        stage: entry.stageName ?? null,
+        stage_id: entry.stageId ?? null,
+        runtime_stage_id: entry.runtimeStageId ?? null,
+        subflow: entry.subflowId ?? null,
+        text: entry.text,
+    };
+}
+/** Apply the cap law. Counters are about the WHOLE narrative (`total`), so a
+ *  projected walk cannot read as a short run. */
+export function projectWalk(entries, cap) {
+    const full = entries.length <= cap;
+    const projection = full ? 'full' : 'control-flow';
+    const chosen = full ? entries : entries.filter((entry) => entry.type !== 'step');
+    const rows = chosen.slice(0, cap).map(toWalkRow);
+    return {
+        rows,
+        projection,
+        shown: rows.length,
+        total: entries.length,
+        complete: rows.length === entries.length,
+    };
+}
+/** The descriptor's standing sentence, plus the projection clause when the
+ *  control flow is what survived. */
+function walkNote(projection) {
+    return ("The chart's own walk, one row per execution step. The `condition` rows carry the " +
+        'rule that matched, the values it compared and the branch it chose — that is where a ' +
+        'verdict can be checked rather than taken on trust.' +
+        (projection === 'control-flow'
+            ? ' This one is the CONTROL-FLOW projection: the walk did not fit, so the stages, ' +
+                'forks, subflows and decisions are here and the per-key reads and writes are not.'
+            : ''));
+}
+/**
+ * File the walk and build the descriptor. THE SPINE ALWAYS GETS A
+ * DESCRIPTOR: with no store attached, or when the mint fails, the counters
+ * still travel and the note names why there is no ticket — a failed mint
+ * costs the TICKET, never the answer and never the counts.
+ */
+export async function mintWalk(ctx, projected, facts) {
+    const base = {
+        rows: projected.rows.length,
+        steps_executed: facts.stepsExecuted,
+        projection: projected.projection,
+        shown: projected.shown,
+        total: projected.total,
+        complete: projected.complete,
+        walk_segment: 'full',
+    };
+    if (!ctx.hasArtifacts || projected.rows.length === 0) {
+        return {
+            ...base,
+            note: projected.rows.length === 0
+                ? 'The run produced no narrative entries, so there was no walk to file.'
+                : walkNote(projected.projection) +
+                    ' No artifact store is attached to this run, so the walk was recorded but not ' +
+                    'filed — the counters above are still the truth about it.',
+        };
+    }
+    try {
+        const meta = await ctx.artifacts.put(chartWalkPutInput([...projected.rows], {
+            toolName: facts.toolName,
+            toolCallId: facts.toolCallId,
+            ...(facts.runId !== undefined && { runId: facts.runId }),
+        }));
+        return {
+            ref: meta.ref,
+            kind: CHART_WALK_ARTIFACT_KIND,
+            ...base,
+            note: walkNote(projected.projection),
+        };
+    }
+    catch (err) {
+        return {
+            ...base,
+            note: walkNote(projected.projection) +
+                ` The walk could not be filed (${err instanceof Error ? err.message : String(err)}) — ` +
+                'the mint failure cost the ticket, never the answer.',
+        };
+    }
+}
+//# sourceMappingURL=walk.js.map

package/dist/esm/core/runbook/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../../../../src/core/runbook/walk.ts"],"names":[],"mappings":"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"}