@kontourai/flow-agents 3.12.1 → 4.1.0

package/build/src/narrative/grounding-validator.js

@@ -0,0 +1,472 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveSource, verifyManifest } from "./resolver.js";
+import { parseSourceId } from "./source-ids.js";
+import { buildTurnSpine } from "./turn-spine.js";
+export function entailmentIndependenceHolds(generator, validator) {
+    return generator.model !== validator.model || generator.config_hash !== validator.config_hash;
+}
+const PROHIBITED_ASSERTIONS = {
+    // Declared-but-dormant until #614/#622 add these classes to StatementClass.
+    summarizer_inferred: new Set(["gate_status", "observed_outcome", "authority", "hidden_alternative"]),
+    agent_stated: new Set(["gate_status", "observed_outcome", "authority", "hidden_alternative"]),
+};
+/** Generic (statement class, assertion kind) policy seam for current and future classes. */
+export function isAssertionProhibited(statementClass, assertionKind) {
+    return PROHIBITED_ASSERTIONS[statementClass]?.has(assertionKind) ?? false;
+}
+export class NarrativeGroundingError extends Error {
+    violations;
+    name = "NarrativeGroundingError";
+    code = "grounding_failed";
+    constructor(violations) {
+        super(`narrative grounding gate failed: ${violations.map(describeViolation).join("; ")}`);
+        this.violations = violations;
+    }
+}
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function string(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function integer(value) {
+    return Number.isSafeInteger(value) ? value : undefined;
+}
+function nested(record, key) {
+    return object(record[key]);
+}
+function firstString(...values) {
+    for (const value of values) {
+        const found = string(value);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+function eventType(record) {
+    return firstString(record["event_type"], record["kind"]);
+}
+function sessionId(record) {
+    return firstString(record["session_id"], record["sessionId"]);
+}
+function toolName(record, event) {
+    return firstString(nested(record, "tool")?.["name"], record["tool_name"], record["toolName"])
+        ?? (event.startsWith("session.") ? "session" : event === "turn.user" ? "turn" : "runtime");
+}
+// #623: the validator's material-event derivation must observe commands through the
+// SAME extraction projection.ts uses, or a real command failure emitted by projection
+// would have no derived event and could be omitted from a narrative undetected. This
+// mirrors projection.ts:commandFrom(record, tool) exactly — including the tool-gated
+// bare-input fallback — for telemetry-stream commands. Cmdlog commands use
+// record["command"] directly, matching projection.ts's cmdlog reader.
+function commandFrom(record, tool) {
+    const toolRecord = nested(record, "tool");
+    const input = toolRecord?.["input"];
+    return firstString(record["command"], toolRecord?.["command"], object(input)?.["command"], /(?:shell|bash|command|exec)/i.test(tool) ? input : undefined);
+}
+function exitCodeFrom(record) {
+    const tool = nested(record, "tool");
+    const result = nested(record, "result");
+    return integer(record["exit_code"])
+        ?? integer(record["exitCode"])
+        ?? integer(tool?.["exit_code"])
+        ?? integer(tool?.["exitCode"])
+        ?? integer(result?.["exit_code"])
+        ?? integer(result?.["exitCode"])
+        ?? null;
+}
+// Mirrors projection.ts:observedResultFrom's fail determination (including the
+// tool.status textual fallback) so the derived material event agrees with the
+// observed statement projection would emit.
+function isFailure(record) {
+    const exitCode = exitCodeFrom(record);
+    if (exitCode !== null)
+        return exitCode !== 0;
+    return /^(?:fail|failed|failure|error)$/i.test(firstString(record["result"], record["status"], record["outcome"], nested(record, "tool")?.["status"]) ?? "");
+}
+// Mirrors projection.ts:carriesTimeoutSignal exactly — including the tool.status textual
+// fallback — so a tool.status-only timeout projection would emit a statement for cannot be
+// omitted from a narrative undetected (parallel to the isFailure tool.status fallback above).
+function carriesTimeout(record) {
+    if (record["timed_out"] === true || record["timedOut"] === true)
+        return true;
+    const status = firstString(record["status"], record["result"], record["outcome"], nested(record, "tool")?.["status"]);
+    if (status && /^(?:timeout|timed_out|timed-out)$/i.test(status))
+        return true;
+    const error = nested(record, "error");
+    return /timeout/i.test(firstString(error?.["code"], error?.["name"]) ?? "");
+}
+function normalizeCommand(command) {
+    return command.trim().replace(/\s+/g, " ");
+}
+function parseRecord(bytes) {
+    try {
+        return object(JSON.parse(Buffer.from(bytes).toString("utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+function readVerifiedManifest(narrativeDir) {
+    const verification = verifyManifest(narrativeDir);
+    if (verification.perSource.some((entry) => entry.sourceId === "manifest")) {
+        throw new Error("narrative grounding validator could not verify the frozen source manifest");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(path.join(narrativeDir, "source-manifest.json"), "utf8"));
+    }
+    catch {
+        throw new Error("narrative grounding validator could not read the frozen source manifest");
+    }
+    return parsed;
+}
+function statementsFrom(envelope) {
+    const runtime = envelope.sections.find((section) => section.authority === "flow-agents" && section.kind === "runtime-projection");
+    if (!runtime || runtime.authority !== "flow-agents")
+        throw new Error("narrative grounding validator requires one runtime projection section");
+    return [...runtime.embedded.turns.flatMap((turn) => turn.statements), ...runtime.embedded.document_statements];
+}
+function citationViolations(statements, narrativeDir, resolver, declaredUnavailable) {
+    const violations = [];
+    for (const statement of statements) {
+        for (const sourceRef of statement.source_refs) {
+            const resolved = resolver(narrativeDir, sourceRef);
+            if (resolved.status === "unavailable") {
+                // An unavailable-source statement is a typed disclosure of frozen
+                // manifest status, not a claim about unavailable content. Preserve
+                // that established completeness contract only when the exact ref is
+                // manifest-declared unavailable; absent/fabricated refs still fail.
+                const declaredReason = declaredUnavailable.get(sourceRef);
+                const isExactDisclosure = declaredReason !== undefined
+                    && statement.class === "deterministic_derived"
+                    && statement.source_refs.length === 1
+                    && statement.rule?.id === "unavailable-source"
+                    && statement.rule.version === "v1"
+                    && statement.rule.inputs.length === 1
+                    && statement.rule.inputs[0] === sourceRef
+                    && statement.proposition === `Source ${sourceRef} was unavailable because ${declaredReason}`;
+                if (isExactDisclosure)
+                    continue;
+                violations.push({
+                    code: "unresolved_citation",
+                    statement_id: statement.id,
+                    source_ref: sourceRef,
+                    reason: resolved.reason,
+                    detail: resolved.detail,
+                });
+            }
+        }
+    }
+    return violations;
+}
+// #623 (review MEDIUM): this keyword heuristic is a BEST-EFFORT deterministic backstop,
+// not a security boundary. It reliably classifies the fixed-form propositions that today's
+// two deterministic classes emit (observed/deterministic_derived constructors). It is NOT a
+// robust check against free-form model prose — once summarizer_inferred prose ships, a
+// paraphrase ("did not succeed", "broke") evades these patterns. The authoritative check for
+// model prose is the model-entailment layer (R2/R3), which #614 activates; the prohibited-
+// assertion engine here is the dormant-class scaffolding, and #614/#622 must not treat this
+// regex as sufficient enforcement on its own.
+function assertionKinds(proposition) {
+    const kinds = [];
+    if (/\bgate\b.*\b(?:pass|fail|accept|reject)(?:ed)?\b/i.test(proposition))
+        kinds.push("gate_status");
+    if (/\b(?:observed|passed|failed|succeeded|timed out|created)\b/i.test(proposition))
+        kinds.push("observed_outcome");
+    if (/\b(?:authority|authoritative|approved|accepted)\b/i.test(proposition))
+        kinds.push("authority");
+    if (/\b(?:no other|only possible|hidden alternative)\b/i.test(proposition))
+        kinds.push("hidden_alternative");
+    return kinds;
+}
+function epistemicViolations(statements) {
+    const violations = [];
+    for (const statement of statements) {
+        const statementClass = statement.class;
+        if (statementClass === "observed" && statement.source_refs.length === 0) {
+            violations.push({
+                code: "prohibited_assertion",
+                statement_id: statement.id,
+                statement_class: statementClass,
+                assertion_kind: "observed_outcome",
+                detail: "observed statements require at least one resolvable source_ref",
+            });
+        }
+        if (statementClass === "observed" && statement.rule) {
+            violations.push({ code: "invalid_rule_binding", statement_id: statement.id, detail: "observed statements must not carry a derivation rule" });
+        }
+        if (statementClass === "deterministic_derived") {
+            if (!statement.rule) {
+                violations.push({ code: "invalid_rule_binding", statement_id: statement.id, detail: "deterministic_derived statements require a rule" });
+            }
+            else if (statement.rule.inputs.some((sourceRef) => !statement.source_refs.includes(sourceRef))) {
+                violations.push({ code: "invalid_rule_binding", statement_id: statement.id, detail: "rule inputs must be a subset of source_refs" });
+            }
+        }
+        // #622 (review HIGH R2): the prohibited-assertion scan must cover the `actor`
+        // too, not just the proposition. On agent_stated / summarizer_inferred an
+        // unbounded actor field could otherwise embed prohibited-assertion keywords
+        // ("observed", "authoritative", "approved") that the proposition-only scan would
+        // miss. Concatenating is inert for observed/deterministic_derived classes (they
+        // carry no prohibited-assertion policy) and for identifier-shaped actors.
+        const assertionSource = statement.actor ? `${statement.proposition} ${statement.actor}` : statement.proposition;
+        for (const kind of assertionKinds(assertionSource)) {
+            if (isAssertionProhibited(statementClass, kind)) {
+                violations.push({
+                    code: "prohibited_assertion",
+                    statement_id: statement.id,
+                    statement_class: statementClass,
+                    assertion_kind: kind,
+                    detail: `${statementClass} statements may not assert ${kind.replace(/_/g, " ")}`,
+                });
+            }
+        }
+    }
+    return violations;
+}
+// #614 (D3): the deterministic backstop for the model-assisted prose renderer's connective
+// class. A summarizer_inferred statement's fa1 source_refs must be a NON-EMPTY SUBSET of the
+// union of source_refs carried by the atomic (observed/deterministic_derived) statements
+// present alongside it -- i.e. it must cite >=1 real atomic statement and may never introduce
+// a fa1 ref that no atomic statement itself cites. This is a provenance-subset guard, not a
+// semantic-entailment check (that authoritative layer is R2/R3's model-entailment executor,
+// gated by entailmentIndependenceHolds); a summarizer citing a broad-but-real ref set while
+// asserting unsupported content is still caught by whichever layer runs, and this check never
+// substitutes for the other.
+function summaryViolations(statements) {
+    const atomicRefs = new Set(statements
+        .filter((statement) => statement.class === "observed" || statement.class === "deterministic_derived")
+        .flatMap((statement) => statement.source_refs));
+    const violations = [];
+    for (const statement of statements) {
+        if (statement.class !== "summarizer_inferred")
+            continue;
+        const unsupported = statement.source_refs.filter((sourceRef) => !atomicRefs.has(sourceRef));
+        if (statement.source_refs.length === 0 || unsupported.length > 0) {
+            violations.push({
+                code: "unsupported_summary",
+                statement_id: statement.id,
+                unsupported_refs: statement.source_refs.length === 0 ? [] : unsupported,
+                detail: statement.source_refs.length === 0
+                    ? "summarizer_inferred statements must cite at least one atomic (observed/deterministic_derived) statement"
+                    : `summarizer_inferred source_refs must be a subset of the cited atomic statements' source_refs (unsupported: ${unsupported.join(", ")})`,
+            });
+        }
+    }
+    return violations;
+}
+function deriveMaterialEvents(manifest, resolved) {
+    const events = [];
+    const commandFailureEvent = (entry, command) => {
+        const exitCode = exitCodeFrom(entry.record);
+        return {
+            kind: "command_failure",
+            sourceRef: entry.sourceId,
+            sourceRefs: [entry.sourceId],
+            expectedProposition: `Command \`${command}\` was observed to fail (exit ${exitCode === null ? "unknown" : String(exitCode)})`,
+        };
+    };
+    // Cmdlog stream: projection.ts reads record["command"] directly for cmdlog entries.
+    const cmdlog = resolved.filter((entry) => entry.stream === "cmdlog" && entry.record);
+    for (const entry of cmdlog) {
+        const command = string(entry.record["command"]);
+        if (command && isFailure(entry.record))
+            events.push(commandFailureEvent(entry, command));
+    }
+    let run = [];
+    const flushRun = () => {
+        if (run.length >= 2 && run[0]?.record && isFailure(run[0].record)) {
+            events.push({ kind: "retry_group", sourceRef: run[0].sourceId, sourceRefs: run.map((entry) => entry.sourceId) });
+        }
+        run = [];
+    };
+    for (const entry of cmdlog) {
+        const command = string(entry.record["command"]);
+        if (!command) {
+            flushRun();
+            continue;
+        }
+        const firstCommand = run[0]?.record ? string(run[0].record["command"]) : undefined;
+        if (firstCommand && normalizeCommand(firstCommand) !== normalizeCommand(command))
+            flushRun();
+        run.push(entry);
+        if (!isFailure(entry.record) && run.length === 1)
+            flushRun();
+    }
+    flushRun();
+    const telemetry = resolved.filter((entry) => entry.stream === "telemetry" && entry.record);
+    for (const entry of telemetry) {
+        // #623 (review HIGH): projection.ts also emits an observed command statement for
+        // commands captured via the telemetry stream (a tool.result event carrying a command
+        // + non-zero exit). Derive the matching command_failure event through the SAME
+        // tool-gated extraction so a telemetry-sourced failure cannot be omitted undetected.
+        const record = entry.record;
+        const event = eventType(record);
+        if (event) {
+            const command = commandFrom(record, toolName(record, event));
+            if (command && isFailure(record))
+                events.push(commandFailureEvent(entry, command));
+        }
+        if (carriesTimeout(record))
+            events.push({ kind: "timeout", sourceRef: entry.sourceId, sourceRefs: [entry.sourceId] });
+    }
+    for (const entry of resolved.filter((candidate) => candidate.stream === "file")) {
+        const parsed = parseSourceId(entry.sourceId);
+        if (parsed.stream === "file")
+            events.push({
+                kind: "file_creation",
+                sourceRef: entry.sourceId,
+                sourceRefs: [entry.sourceId],
+                expectedProposition: `File \`${parsed.scope.repoRelativePath}\` was observed to be created`,
+            });
+    }
+    // Normalize session_id/event_type aliases before building the turn spine, exactly as
+    // projection.ts:normalizedTelemetry does, so the validator's independently-rebuilt spine
+    // matches projection's turn assignment and cannot diverge on alias-keyed records.
+    const spine = buildTurnSpine(telemetry.map((entry) => ({
+        sourceId: entry.sourceId,
+        record: {
+            ...entry.record,
+            ...(sessionId(entry.record) ? { session_id: sessionId(entry.record) } : {}),
+            ...(eventType(entry.record) ? { event_type: eventType(entry.record) } : {}),
+        },
+    })));
+    const indexBySource = new Map(manifest.sources.map((entry, index) => [entry.source_id, index]));
+    const activeTurns = new Set();
+    for (const entry of telemetry) {
+        const event = eventType(entry.record);
+        if (!event || !commandFrom(entry.record, toolName(entry.record, event)))
+            continue;
+        const turn = spine.find((candidate) => candidate.sources.includes(entry.sourceId));
+        if (turn)
+            activeTurns.add(turn.ordinal);
+    }
+    const nearestTurn = (entry) => {
+        const session = firstString(entry.record?.["session_id"], entry.record?.["sessionId"]);
+        if (!session)
+            return undefined;
+        let best;
+        for (const turn of spine) {
+            if (turn.sessionId !== session)
+                continue;
+            for (const sourceId of turn.sources) {
+                const distance = Math.abs(entry.sourceIndex - (indexBySource.get(sourceId) ?? entry.sourceIndex));
+                if (!best || distance < best.distance || (distance === best.distance && turn.ordinal < best.ordinal))
+                    best = { ordinal: turn.ordinal, distance };
+            }
+        }
+        return best?.ordinal;
+    };
+    for (const entry of resolved.filter((candidate) => ["agent-event", "delegation", "file"].includes(candidate.stream))) {
+        const ordinal = nearestTurn(entry);
+        if (ordinal !== undefined)
+            activeTurns.add(ordinal);
+    }
+    for (const turn of spine) {
+        if (!activeTurns.has(turn.ordinal) && turn.sources.length > 0) {
+            events.push({ kind: "no_op_turn", sourceRef: turn.sources[0], sourceRefs: [...turn.sources] });
+        }
+    }
+    return events;
+}
+function eventIsCovered(event, statements) {
+    return statements.some((statement) => {
+        if (!event.sourceRefs.every((sourceRef) => statement.source_refs.includes(sourceRef)))
+            return false;
+        switch (event.kind) {
+            // Observed statements cannot carry rules. These two match their typed
+            // constructor output by class + atomic proposition + triggering source.
+            case "command_failure":
+            case "file_creation": return statement.class === "observed" && statement.proposition === event.expectedProposition;
+            case "retry_group": return statement.rule?.id === "retry-detection";
+            case "timeout": return statement.rule?.id === "timeout-detection";
+            case "no_op_turn": return statement.rule?.id === "no-op-turn";
+        }
+    });
+}
+function materialViolations(events, statements) {
+    return events.flatMap((event) => eventIsCovered(event, statements) ? [] : [{
+            code: "uncovered_material_event",
+            event_kind: event.kind,
+            source_ref: event.sourceRef,
+            detail: `${event.kind} from ${event.sourceRef} has no matching grounded statement`,
+        }]);
+}
+function describeViolation(violation) {
+    switch (violation.code) {
+        case "unresolved_citation": return `${violation.code} ${violation.source_ref} (${violation.reason}: ${violation.detail})`;
+        case "uncovered_material_event": return `${violation.code} ${violation.event_kind} ${violation.source_ref}`;
+        case "invalid_rule_binding": return `${violation.code} ${violation.statement_id}: ${violation.detail}`;
+        case "prohibited_assertion": return `${violation.code} ${violation.statement_id}/${violation.assertion_kind}: ${violation.detail}`;
+        case "unsupported_summary": return `${violation.code} ${violation.statement_id}: ${violation.detail}`;
+    }
+}
+// Single canonical resolution path shared by validateNarrativeGrounding and
+// materialEventCoverage — the eval layer (#612) must measure against the SAME
+// resolution the product's gate uses, never a parallel copy that could drift.
+function resolveManifestRecords(narrativeDir, opts) {
+    const manifest = readVerifiedManifest(narrativeDir);
+    const resolver = opts.resolver ?? resolveSource;
+    const resolved = [];
+    for (const [sourceIndex, entry] of manifest.sources.entries()) {
+        const result = resolver(narrativeDir, entry.source_id);
+        if (result.status !== "resolved")
+            continue;
+        const stream = parseSourceId(entry.source_id).stream;
+        // Foreign sections are already byte/hash checked by the composer and are
+        // deliberately not reinterpreted as runtime statement evidence here.
+        if (stream === "flow-report" || stream === "surface-explanation")
+            continue;
+        resolved.push({ sourceId: entry.source_id, sourceIndex, stream, record: parseRecord(result.content) });
+    }
+    return { manifest, resolved, resolver };
+}
+/**
+ * #612: the SAME canonical material-event extraction that
+ * validateNarrativeGrounding uses to derive `uncovered_material_event`
+ * violations, exposed as a coverage summary so the eval layer measures
+ * faithfulness against the real extraction (never a parallel one that could
+ * drift). `covered = total - sum(uncovered)`; `by_class` gives per-kind
+ * total/uncovered so the eval can report an honest omission rate per class.
+ */
+export function materialEventCoverage(envelope, narrativeDir, opts = {}) {
+    const statements = statementsFrom(envelope);
+    const { manifest, resolved } = resolveManifestRecords(narrativeDir, opts);
+    const events = deriveMaterialEvents(manifest, resolved);
+    const by_class = {};
+    let covered = 0;
+    for (const event of events) {
+        const bucket = (by_class[event.kind] ??= { total: 0, uncovered: 0 });
+        bucket.total += 1;
+        if (eventIsCovered(event, statements))
+            covered += 1;
+        else
+            bucket.uncovered += 1;
+    }
+    return { total: events.length, covered, by_class };
+}
+export function validateNarrativeGrounding(envelope, narrativeDir, opts = {}) {
+    const statements = statementsFrom(envelope);
+    const { manifest, resolved, resolver } = resolveManifestRecords(narrativeDir, opts);
+    const violations = [];
+    const declaredUnavailable = new Map(manifest.sources
+        .filter((entry) => entry.status === "unavailable")
+        .map((entry) => [entry.source_id, entry.unavailable_reason]));
+    /* grounding-check:citation */
+    violations.push(...citationViolations(statements, narrativeDir, resolver, declaredUnavailable));
+    /* grounding-check:material */
+    violations.push(...materialViolations(deriveMaterialEvents(manifest, resolved), statements));
+    /* grounding-check:epistemic */
+    violations.push(...epistemicViolations(statements));
+    /* grounding-check:summary */
+    violations.push(...summaryViolations(statements));
+    const known_gaps = [{
+            code: "contradiction_detection_unavailable",
+            detail: "the frozen source manifest has no raw contradiction signal; contradiction detection is sequenced to #568/#425",
+        }];
+    return violations.length === 0 ? { ok: true, known_gaps } : { ok: false, violations, known_gaps };
+}

package/build/src/narrative/integrity.d.ts

@@ -0,0 +1,17 @@
+import type { NarrativeSourceId, NarrativeSourceStream } from "./source-ids.js";
+export type IntegrityClass = "hash_chained" | "append_only_unhashed" | "rotatable" | "overwritten_in_place" | "path_only";
+export type UnavailableReason = "expired" | "redacted" | "unauthorized" | "not_captured" | "corrupt";
+export type CaptureChannelStatus = "active" | "inactive" | "unknown";
+export type KnownGapClass = "mcp_non_native_tools" | "actor_attribution_conflation" | "cross_session_event_contamination";
+export interface CaptureCompleteness {
+    channels: Record<string, CaptureChannelStatus>;
+    known_gaps: Array<{
+        class: KnownGapClass;
+        ref: string;
+        note?: string;
+    }>;
+}
+export declare const DEFAULT_INTEGRITY_CLASS: Readonly<Record<Exclude<NarrativeSourceStream, "file">, IntegrityClass>>;
+export declare const KNOWN_CAPTURE_GAPS: CaptureCompleteness["known_gaps"];
+export declare function integrityClassForSource(source: NarrativeSourceId): IntegrityClass;
+export declare function buildCaptureCompleteness(telemetryConf: Record<string, unknown> | null | undefined, channelNames?: readonly string[], additionalGaps?: CaptureCompleteness["known_gaps"]): CaptureCompleteness;

package/build/src/narrative/integrity.js

@@ -0,0 +1,39 @@
+export const DEFAULT_INTEGRITY_CLASS = {
+    telemetry: "rotatable",
+    cmdlog: "hash_chained",
+    "agent-event": "append_only_unhashed",
+    delegation: "append_only_unhashed",
+    "trust-claim": "overwritten_in_place",
+    "trust-evidence": "overwritten_in_place",
+    "flow-state": "overwritten_in_place",
+    "flow-report": "path_only",
+    "flow-transition": "overwritten_in_place",
+    // Derived from a rewritable trust.bundle at capture time; only the frozen
+    // explanation blob, not its origin path, is content-addressed thereafter.
+    "surface-explanation": "path_only",
+    transcript: "path_only",
+};
+export const KNOWN_CAPTURE_GAPS = [
+    { class: "mcp_non_native_tools", ref: "flow-agents#492" },
+    { class: "actor_attribution_conflation", ref: "flow-agents#423" },
+    { class: "cross_session_event_contamination", ref: "flow-agents#271" },
+];
+export function integrityClassForSource(source) {
+    if (source.stream === "cmdlog" && source.locator.kind === "legacy")
+        return "append_only_unhashed";
+    if (source.stream === "file")
+        return source.locator.hashKind === "git-blob" ? "hash_chained" : "overwritten_in_place";
+    return DEFAULT_INTEGRITY_CLASS[source.stream];
+}
+export function buildCaptureCompleteness(telemetryConf, channelNames = ["full", "analytics"], additionalGaps = []) {
+    const channels = {};
+    for (const channel of channelNames) {
+        if (telemetryConf === undefined || telemetryConf === null)
+            channels[channel] = "unknown";
+        else if (!Object.prototype.hasOwnProperty.call(telemetryConf, channel))
+            channels[channel] = "unknown";
+        else
+            channels[channel] = telemetryConf[channel] === false || telemetryConf[channel] === null ? "inactive" : "active";
+    }
+    return { channels, known_gaps: [...KNOWN_CAPTURE_GAPS, ...additionalGaps] };
+}

package/build/src/narrative/intent-economics.d.ts

@@ -0,0 +1,42 @@
+export declare const INTENT_ECONOMICS_FILE = "intent-economics.jsonl";
+export type IntentAnnotationMode = "annotation_on" | "annotation_off";
+export interface IntentEconomicsRecord {
+    mode: IntentAnnotationMode;
+    input_tokens: number;
+    output_tokens: number;
+    wall_clock_ms: number;
+    attempted_at: string;
+}
+export declare function appendIntentEconomics(dir: string, record: IntentEconomicsRecord): void;
+/**
+ * A mean delta reported WITH its uncertainty spread (never a bare point estimate).
+ *
+ * #622 (review MEDIUM A/B): an EMPTY window (no paired samples) reports
+ * `has_data:false` rather than a false-precise `{mean:0, sample_std:0, min:0,
+ * max:0}` — a consumer must not misread "we measured nothing" as "we measured and
+ * confirmed a null delta". `n` is retained in both shapes.
+ */
+export type IntentEconomicsDelta = {
+    has_data: false;
+    n: 0;
+} | {
+    has_data: true;
+    /** Number of paired (on,off) deltas contributing to this metric. */
+    n: number;
+    mean: number;
+    /** Sample standard deviation (Bessel-corrected); 0 for a single pair. */
+    sample_std: number;
+    min: number;
+    max: number;
+};
+export interface IntentEconomicsSummary {
+    pairs: number;
+    on_samples: number;
+    off_samples: number;
+    delta_input_tokens: IntentEconomicsDelta;
+    delta_output_tokens: IntentEconomicsDelta;
+    delta_wall_clock_ms: IntentEconomicsDelta;
+}
+export declare function reduceIntentEconomics(records: readonly IntentEconomicsRecord[]): IntentEconomicsSummary;
+/** Read + parse an intent-economics.jsonl sink into typed records (skips blank lines). */
+export declare function readIntentEconomics(dir: string): IntentEconomicsRecord[];

package/build/src/narrative/intent-economics.js

@@ -0,0 +1,82 @@
+/**
+ * #622 (R6/AC5): annotation-on/off A/B token measurement with uncertainty.
+ *
+ * `appendIntentEconomics` is an append-only local sink mirroring
+ * narrative-render.ts:appendEconomics (O_APPEND|O_CREAT|O_WRONLY, no-follow,
+ * 0600). `reduceIntentEconomics` is a NET-NEW pure paired-delta reducer: it
+ * pairs annotation_on/off samples in order and reports the MEAN delta together
+ * with an uncertainty spread (sample standard deviation + observed range) for
+ * each metric. No external stats dependency.
+ *
+ * This is the measurement MECHANISM + dry-run harness; scaled behavioral deltas
+ * across many real runs feed #612.
+ *
+ * @module
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const INTENT_ECONOMICS_FILE = "intent-economics.jsonl";
+export function appendIntentEconomics(dir, record) {
+    const file = path.join(dir, INTENT_ECONOMICS_FILE);
+    if (fs.existsSync(file)) {
+        const stat = fs.lstatSync(file);
+        if (stat.isSymbolicLink() || !stat.isFile())
+            throw new Error(`refusing unsafe intent economics target at ${file}`);
+    }
+    const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+    const descriptor = fs.openSync(file, fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_WRONLY | noFollow, 0o600);
+    try {
+        fs.writeSync(descriptor, `${JSON.stringify(record)}\n`, undefined, "utf8");
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function summarizeDeltas(values) {
+    const n = values.length;
+    // #622 (review MEDIUM A/B): an empty window is NOT a confirmed zero delta.
+    if (n === 0)
+        return { has_data: false, n: 0 };
+    const mean = values.reduce((sum, value) => sum + value, 0) / n;
+    // Bessel-corrected sample variance; a single pair has undefined spread -> 0.
+    const variance = n > 1 ? values.reduce((sum, value) => sum + (value - mean) ** 2, 0) / (n - 1) : 0;
+    return { has_data: true, n, mean, sample_std: Math.sqrt(variance), min: Math.min(...values), max: Math.max(...values) };
+}
+export function reduceIntentEconomics(records) {
+    const on = records.filter((record) => record.mode === "annotation_on");
+    const off = records.filter((record) => record.mode === "annotation_off");
+    const pairs = Math.min(on.length, off.length);
+    const inputDeltas = [];
+    const outputDeltas = [];
+    const wallDeltas = [];
+    // #622 (review LOW, disclosed mechanism-scope): pairs annotation_on/off samples
+    // by INDEX for the dry-run harness (not by attempted_at / matched conditions);
+    // scaled cross-run attribution is sequenced to #612.
+    for (let index = 0; index < pairs; index += 1) {
+        inputDeltas.push(on[index].input_tokens - off[index].input_tokens);
+        outputDeltas.push(on[index].output_tokens - off[index].output_tokens);
+        wallDeltas.push(on[index].wall_clock_ms - off[index].wall_clock_ms);
+    }
+    return {
+        pairs,
+        on_samples: on.length,
+        off_samples: off.length,
+        delta_input_tokens: summarizeDeltas(inputDeltas),
+        delta_output_tokens: summarizeDeltas(outputDeltas),
+        delta_wall_clock_ms: summarizeDeltas(wallDeltas),
+    };
+}
+/** Read + parse an intent-economics.jsonl sink into typed records (skips blank lines). */
+export function readIntentEconomics(dir) {
+    const file = path.join(dir, INTENT_ECONOMICS_FILE);
+    if (!fs.existsSync(file))
+        return [];
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile())
+        throw new Error(`refusing unsafe intent economics target at ${file}`);
+    return fs.readFileSync(file, "utf8")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .map((line) => JSON.parse(line));
+}