agentfootprint 9.75.0 → 9.76.0

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

@@ -0,0 +1,354 @@
+/**
+ * runbookAsTool — turn a written operational procedure into a tool whose
+ * every answer is EVIDENCE: who decided what, against which threshold, on
+ * which rule version, with the recorded walk to check it against.
+ *
+ * The standard bridge from a footprintjs chart to the Agent's tool surface.
+ * Where `flowchartAsTool` returns bare `JSON.stringify(values)`,
+ * runbookAsTool supplies the missing middle — the honesty envelope every
+ * hand-rolled triage tool was building for itself:
+ *
+ *   THE MANDATORY SPINE (every runbook, whatever its shape):
+ *     - `af_coverage` — the three-list ledger, with every INNER tool's own
+ *       ledger folded upward through the run's dispatch, plus the sentence
+ *       naming the rule set and version;
+ *     - `result.af_provenance` — re-emitted FIRST (a carried `LOCAL SEED`
+ *       confession survives composition);
+ *     - `result.rule_version` — the declared rules' version, or the honest
+ *       `'undeclared'`;
+ *     - `result.walk` — the recorded walk's descriptor. The walk itself
+ *       ships as an artifact ticket (kind `recording/chart-walk`), never as
+ *       bytes; when it does not fit, the CONTROL FLOW survives and the
+ *       projection is declared.
+ *
+ *   THE OPTIONAL PROJECTION (selected by `resultKind: 'verdict/*'`):
+ *     verdict rows off the chart's `verdicts` state key, capped with
+ *     truthful counters, a pre-rendered table over the SAME rows, and
+ *     `verdict_meanings` GENERATED from the decider's declared branches +
+ *     the rule labels this run's decide() evidence carried.
+ *
+ *   THREE OUTCOMES, honestly: a clean envelope; an inner ABSENCE passed
+ *   through verbatim (the framework still reads it as an absence); and
+ *   DECLINED rows counted into the ledger as not-checked ground.
+ *
+ * The procedure is a FACTORY invoked per call with the run's own tool
+ * dispatch (`ctx.tools`) — fresh chart every run, stages close over the
+ * dispatch, and every inner tool's honesty ledger folds into this tool's
+ * answer.
+ *
+ * Reserved state keys the bridge reads off the final scope:
+ *   - `verdicts` — the rowset (verdict projection only);
+ *   - `coverage` — chart-declared coverage entries (`{checked?, not_checked?,
+ *     cannot_cover?}`);
+ *   - `report`  — the app's own result fields, spread into `result` verbatim
+ *     (spine keys win).
+ *
+ * Pause: NOT yet bridged. A paused inner chart throws with the checkpoint
+ * attached, exactly like `flowchartAsTool` — the approval-gate integration
+ * is the next phase of the runbook program.
+ *
+ * @example the smallest legal call — still yields the honest spine
+ *   const tool = runbookAsTool({
+ *     name: 'restart_check',
+ *     description: 'Run the restart-safety procedure.',
+ *     procedure: () =>
+ *       flowChart<{ safe: boolean }>('restart-safety', (scope) => {
+ *         scope.safe = true;
+ *       }, 'check').build(),
+ *   });
+ *
+ * @example a triage runbook with rules, verdicts, and an inner tool
+ *   const triage = runbookAsTool({
+ *     name: 'backup_triage',
+ *     description: 'Assess backup protection posture for every subject.',
+ *     resultKind: 'verdict/backup-posture',
+ *     rules: { name: 'health-signal', version: 'v1' },
+ *     verdicts: { decider: 'posture' },
+ *     composedOf: ['backup_inventory'],
+ *     procedure: (tools) =>
+ *       flowChart<TriageState>('backup-triage', async (scope) => {
+ *         const inner = (await tools.call('backup_inventory', {})) as InventoryResult;
+ *         scope.subjects = inner.result.rows;
+ *       }, 'inventory')
+ *         .addDeciderFunction('Posture', postureDecider, 'posture')
+ *           .addFunctionBranch('protected', 'Protected', landProtected)
+ *           .addFunctionBranch('unprotected', 'Unprotected', landUnprotected)
+ *           .end()
+ *         .build(),
+ *   });
+ */
+import { FlowChartExecutor, narrative } from 'footprintjs';
+import { controlDepRecorder } from 'footprintjs/trace';
+import { DEFAULT_INNER_RUN_LIMIT, INNER_RUN_RECORDS, innerRunStore, } from '../../lib/trace-toolpack/innerRunRecords.js';
+import { defineTool } from '../tools.js';
+import { carriedProvenanceOf, chartCoverageOf, composeLedger, foldInnerCoverage, } from './coverage.js';
+import { absenceSignalOf, probeDispatch, recordingDispatch } from './dispatch.js';
+import { composeMeanings, DECLINED_VERDICT, DEFAULT_MAX_ROWS, meaningsRecorder, renderVerdictTable, resolveDecider, VERDICT_RENDER_NOTE, verdictRowsOf, } from './verdicts.js';
+import { DEFAULT_WALK_CAP, mintWalk, projectWalk } from './walk.js';
+/** The projection selector: a `resultKind` in the `verdict/` namespace gets
+ *  the rowset projection; every other kind ships the spine plus the chart's
+ *  own `report`. */
+const VERDICT_KIND_PREFIX = 'verdict/';
+function bagOf(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Lift the chart's declared input schema when it is a PLAIN JSON-Schema
+ *  object. A parseable schema (`.safeParse`/`.parse` — zod et al.) validates
+ *  at the executor but cannot be serialized for the model: skipped, default
+ *  applies. */
+function liftInputSchema(chart) {
+    const schema = bagOf(chart.inputSchema);
+    if (schema === undefined)
+        return undefined;
+    const parseable = typeof schema.safeParse === 'function' ||
+        typeof schema.parse === 'function';
+    return parseable ? undefined : schema;
+}
+/**
+ * Wrap a footprintjs procedure as a `Tool` whose every answer carries the
+ * honesty spine. See the module header for the envelope; see
+ * {@link RunbookAsToolOptions} for the full options bag. The smallest legal
+ * call is `{ name, description, procedure }`.
+ */
+export function runbookAsTool(opts) {
+    const label = `runbookAsTool(${opts.name || '?'})`;
+    if (!opts.name || opts.name.trim().length === 0) {
+        throw new Error('runbookAsTool: `name` is required and must be non-empty.');
+    }
+    if (!opts.description || opts.description.length === 0) {
+        throw new Error(`${label}: \`description\` is required — a description-less tool is invisible to the model.`);
+    }
+    if (typeof opts.procedure !== 'function') {
+        throw new Error(`${label}: \`procedure\` is required — a factory invoked per call with the run's ` +
+            `tool dispatch, returning a built chart. (Migrating from flowchartAsTool? Wrap ` +
+            `your chart: \`procedure: () => chart\` builds it fresh each run.)`);
+    }
+    if (opts.rules !== undefined) {
+        const { name, version } = opts.rules;
+        if (typeof name !== 'string' ||
+            name.trim() === '' ||
+            typeof version !== 'string' ||
+            version.trim() === '') {
+            throw new Error(`${label}: \`rules\` must carry a non-empty name and version — it is the provenance ` +
+                `stamp every evidence sentence names. Got ${JSON.stringify(opts.rules)}.`);
+        }
+    }
+    if (opts.verdicts !== undefined) {
+        if (typeof opts.verdicts.decider !== 'string' || opts.verdicts.decider.trim() === '') {
+            throw new Error(`${label}: \`verdicts.decider\` must name the decider stage whose branches generate ` +
+                `verdict_meanings. Got ${JSON.stringify(opts.verdicts.decider)}.`);
+        }
+        const maxRows = opts.verdicts.maxRows;
+        if (maxRows !== undefined && (!Number.isInteger(maxRows) || maxRows < 1)) {
+            throw new Error(`${label}: \`verdicts.maxRows\` must be a whole number of rows, at least 1 — got ` +
+                `${String(maxRows)}.`);
+        }
+    }
+    const cap = opts.walk?.cap;
+    if (cap !== undefined && (!Number.isInteger(cap) || cap < 1)) {
+        throw new Error(`${label}: \`walk.cap\` must be a whole number of rows, at least 1 — got ${String(cap)}.`);
+    }
+    if (opts.keepRecordLimit !== undefined) {
+        if (opts.keepRecord !== true) {
+            throw new Error(`${label}: \`keepRecordLimit\` caps records that are never kept — add ` +
+                `\`keepRecord: true\`, or drop the limit.`);
+        }
+        if (!Number.isInteger(opts.keepRecordLimit) || opts.keepRecordLimit < 1) {
+            throw new Error(`${label}: \`keepRecordLimit\` must be a whole number of invocations, at least 1 — ` +
+                `got ${String(opts.keepRecordLimit)}.`);
+        }
+    }
+    // ── Definition-time probe: read the chart's declared contract ─────────
+    let probeChart;
+    try {
+        probeChart = opts.procedure(probeDispatch(opts.name));
+    }
+    catch (err) {
+        throw new Error(`${label}: the procedure factory threw at the definition probe — ` +
+            `${err instanceof Error ? err.message : String(err)}. The factory is invoked once ` +
+            `at definition (stage bodies do not run) to read the chart's declared contract; ` +
+            `it must be side-effect-free at build.`);
+    }
+    if (probeChart === null ||
+        typeof probeChart !== 'object' ||
+        typeof probeChart.stageMap !== 'object') {
+        throw new Error(`${label}: \`procedure\` must return a BUILT chart (call .build() on the builder).`);
+    }
+    const inputSchema = opts.inputSchema ?? liftInputSchema(probeChart);
+    const isVerdictKind = opts.resultKind?.startsWith(VERDICT_KIND_PREFIX) === true;
+    const maxRows = opts.verdicts?.maxRows ?? DEFAULT_MAX_ROWS;
+    const walkCap = opts.walk?.cap ?? DEFAULT_WALK_CAP;
+    const store = opts.keepRecord === true
+        ? innerRunStore(opts.keepRecordLimit ?? DEFAULT_INNER_RUN_LIMIT)
+        : undefined;
+    const tool = defineTool({
+        name: opts.name,
+        description: opts.description,
+        ...(inputSchema !== undefined && { inputSchema }),
+        // GAP-8 closed: the rail-read declarations forward verbatim.
+        ...(opts.resultKind !== undefined && { resultKind: opts.resultKind }),
+        ...(opts.resultClass !== undefined && { resultClass: opts.resultClass }),
+        ...(opts.owner !== undefined && { owner: opts.owner }),
+        ...(opts.resultCeiling !== undefined && { resultCeiling: opts.resultCeiling }),
+        ...(opts.wants !== undefined && { wants: opts.wants }),
+        ...(opts.argumentsFrom !== undefined && { argumentsFrom: opts.argumentsFrom }),
+        ...(opts.composedOf !== undefined && { composedOf: opts.composedOf }),
+        execute: async (args, ctx) => {
+            const dispatch = recordingDispatch(ctx.tools, opts.name);
+            const chart = opts.procedure(dispatch.tools);
+            const executor = new FlowChartExecutor(chart);
+            if (opts.redact)
+                executor.setRedactionPolicy(opts.redact);
+            for (const recorder of opts.recorders ?? []) {
+                executor.attachCombinedRecorder(recorder);
+            }
+            // Values off: the walk is about the DECISIONS — a per-key value dump
+            // would bury six branch choices under four hundred reads.
+            const walkRecorder = narrative({ includeValues: false });
+            executor.attachCombinedRecorder(walkRecorder);
+            // Meanings harvest — resolve the decider on THIS run's chart (a fresh
+            // chart per call; the static branches are the same, the resolution is
+            // cheap) and collect rule labels as the evidence fires.
+            const identity = opts.verdicts !== undefined ? resolveDecider(chart, opts.verdicts.decider) : undefined;
+            const harvest = identity !== undefined ? meaningsRecorder(identity) : undefined;
+            if (harvest !== undefined)
+                executor.attachCombinedRecorder(harvest.recorder);
+            const ctrl = store ? controlDepRecorder() : undefined;
+            if (ctrl)
+                executor.attachCombinedRecorder(ctrl);
+            const keepRecordOf = (outcome, known) => {
+                if (!store)
+                    return;
+                try {
+                    const snapshot = known ?? executor.getSnapshot();
+                    const commitLog = snapshot.commitLog;
+                    const lines = walkRecorder.getEntries()
+                        .map((entry) => entry.text)
+                        .filter((text) => typeof text === 'string' && text.length > 0);
+                    store.keep({
+                        toolCallId: ctx.toolCallId,
+                        toolName: opts.name,
+                        outcome,
+                        steps: Array.isArray(commitLog) ? commitLog.length : 0,
+                        recording: {
+                            snapshot,
+                            structure: chart.buildTimeStructure,
+                        },
+                        ...(ctrl !== undefined && { controlDeps: ctrl.asLookup() }),
+                        ...(lines.length > 0 && { narrative: lines }),
+                    });
+                }
+                catch (e) {
+                    store.keep({
+                        toolCallId: ctx.toolCallId,
+                        toolName: opts.name,
+                        outcome,
+                        steps: 0,
+                        problem: e instanceof Error ? e.message : String(e),
+                    });
+                }
+            };
+            const env = {};
+            if (ctx.signal)
+                env.signal = ctx.signal;
+            try {
+                await executor.run({ input: args, env });
+            }
+            catch (e) {
+                const signal = absenceSignalOf(e);
+                if (signal !== undefined) {
+                    // ABSENCE PASS-THROUGH: the inner source answered "I looked and
+                    // there is nothing", and the runbook has nothing to add. It goes
+                    // back EXACTLY as it arrived so the framework still reads it as an
+                    // absence. The kept record files as 'error' — the closed outcome
+                    // word nearest "the traversal ended on a thrown signal".
+                    keepRecordOf('error');
+                    return signal.absence;
+                }
+                keepRecordOf('error');
+                throw e;
+            }
+            if (executor.isPaused()) {
+                keepRecordOf('paused');
+                const err = new Error(`${label}: the inner chart paused. Approval-gate integration (typed resume ` +
+                    `through agent.resume) is the runbook program's next phase; until it lands a ` +
+                    `paused procedure cannot be resumed through the tool boundary. The checkpoint ` +
+                    `is on err.checkpoint.`);
+                err.checkpoint = executor.getCheckpoint();
+                throw err;
+            }
+            const raw = executor.getSnapshot();
+            keepRecordOf('ok', raw);
+            const state = raw.sharedState ??
+                raw.values ??
+                {};
+            // ── The walk ────────────────────────────────────────────────────────
+            const entries = walkRecorder.getEntries();
+            const projected = projectWalk(entries, walkCap);
+            const walk = await mintWalk(ctx, projected, {
+                toolName: opts.name,
+                toolCallId: ctx.toolCallId,
+                ...(ctx.runId !== undefined && { runId: ctx.runId }),
+                stepsExecuted: walkRecorder.stepCount,
+            });
+            // ── The projection (verdict kinds only) ─────────────────────────────
+            let rows;
+            let shown;
+            let declined;
+            if (isVerdictKind) {
+                rows = verdictRowsOf(state);
+                shown = rows.slice(0, maxRows);
+                declined = rows.filter((row) => row.verdict === DECLINED_VERDICT).length;
+            }
+            const meanings = identity !== undefined && harvest !== undefined
+                ? composeMeanings(identity, harvest.observed)
+                : undefined;
+            // ── The ledger ──────────────────────────────────────────────────────
+            // The procedure's display name: the chart's own root name (what the
+            // author called it) — the tool name is the fallback, never the
+            // auto-generated multi-line description.
+            const chartName = chart.buildTimeStructure?.name ?? opts.name;
+            const ledger = composeLedger(foldInnerCoverage(dispatch.records), chartCoverageOf(state), {
+                chartName,
+                stepsExecuted: walkRecorder.stepCount,
+                ...(opts.rules !== undefined && { rules: opts.rules }),
+                ...(rows !== undefined && { rowsTotal: rows.length }),
+                ...(declined !== undefined && { declinedRows: declined }),
+            });
+            // ── Provenance — re-emitted FIRST ───────────────────────────────────
+            const af_provenance = {
+                ...carriedProvenanceOf(dispatch.records),
+                tool: opts.name,
+                toolCallId: ctx.toolCallId,
+            };
+            const report = bagOf(state.report) ?? {};
+            const envelope = {
+                af_coverage: ledger,
+                result: {
+                    af_provenance,
+                    rule_version: opts.rules?.version ?? 'undeclared',
+                    ...report,
+                    ...(shown !== undefined &&
+                        rows !== undefined && {
+                        verdicts: shown,
+                        rows_shown: shown.length,
+                        rows_total: rows.length,
+                        rows_complete: shown.length === rows.length,
+                        table: renderVerdictTable(shown),
+                        render_note: VERDICT_RENDER_NOTE,
+                        ...(meanings !== undefined && { verdict_meanings: meanings }),
+                    }),
+                    walk,
+                },
+            };
+            return envelope;
+        },
+    });
+    if (store === undefined)
+        return tool;
+    const keepsRecords = { ...tool, [INNER_RUN_RECORDS]: store };
+    return keepsRecords;
+}
+//# sourceMappingURL=runbookAsTool.js.map

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

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

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

@@ -0,0 +1,196 @@
+/**
+ * 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>>;
+        /** Everything the chart put in its `report` state key — the app's own
+         *  result fields, spread here verbatim (spine keys win). */
+        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"}