@kontourai/flow-agents 3.12.1 → 4.1.0

package/dist/pi/build/src/narrative/envelope.js

@@ -0,0 +1,590 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureSafeDirectory } from "../lib/fs.js";
+import { flowAgentsPackageVersion } from "../lib/package-version.js";
+import { projectRuntimeNarrative, stableStringify, } from "./projection.js";
+import { renderGroundedNarrative } from "./render.js";
+import { resolveSource, verifyManifest } from "./resolver.js";
+import { parseSourceId } from "./source-ids.js";
+import { validateNarrativeSourceManifest, } from "./snapshot.js";
+export const GROUNDED_EXECUTION_NARRATIVE_SCHEMA_VERSION = "grounded-execution-narrative/v1";
+export const GROUNDED_EXECUTION_NARRATIVE_COMPILER_NAME = "flow-agents-narrative-composer";
+export class GroundedNarrativeError extends Error {
+    code;
+    sourceId;
+    name = "GroundedNarrativeError";
+    constructor(code, message, sourceId) {
+        super(message);
+        this.code = code;
+        this.sourceId = sourceId;
+    }
+}
+const dateTimeRe = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function schemaPath() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../schemas/grounded-execution-narrative.schema.json");
+}
+function resolveSchemaRef(ref, root) {
+    if (!ref.startsWith("#/$defs/"))
+        return undefined;
+    return root.$defs?.[ref.slice("#/$defs/".length)];
+}
+function schemaMatches(value, schema, root) {
+    const issues = [];
+    validateSchemaValue(value, schema, "$", issues, root);
+    return issues.length === 0;
+}
+function validateSchemaValue(value, schema, loc, issues, root = schema) {
+    if (schema.$ref) {
+        const resolved = resolveSchemaRef(schema.$ref, root);
+        if (!resolved)
+            issues.push({ path: loc, message: `unsupported schema ref ${schema.$ref}` });
+        else
+            validateSchemaValue(value, resolved, loc, issues, root);
+        return;
+    }
+    if (schema.anyOf && !schema.anyOf.some((sub) => schemaMatches(value, sub, root)))
+        issues.push({ path: loc, message: "must match at least one allowed schema" });
+    if (schema.oneOf) {
+        const matches = schema.oneOf.filter((sub) => schemaMatches(value, sub, root)).length;
+        if (matches !== 1)
+            issues.push({ path: loc, message: "must match exactly one allowed schema" });
+    }
+    if (schema.not && schemaMatches(value, schema.not, root))
+        issues.push({ path: loc, message: "must not match forbidden schema" });
+    for (const sub of schema.allOf ?? [])
+        validateSchemaValue(value, sub, loc, issues, root);
+    if (schema.const !== undefined && value !== schema.const)
+        issues.push({ path: loc, message: `must equal ${String(schema.const)}` });
+    if (schema.enum && !schema.enum.includes(value))
+        issues.push({ path: loc, message: `must be one of ${schema.enum.join(", ")}` });
+    if (schema.type === "string") {
+        if (typeof value !== "string") {
+            issues.push({ path: loc, message: "must be string" });
+            return;
+        }
+        if (typeof schema.minLength === "number" && value.length < schema.minLength)
+            issues.push({ path: loc, message: "must not be empty" });
+        if (schema.pattern && !(new RegExp(schema.pattern)).test(value))
+            issues.push({ path: loc, message: "has invalid format" });
+        if (schema.format === "date-time" && (!dateTimeRe.test(value) || Number.isNaN(Date.parse(value))))
+            issues.push({ path: loc, message: "must be date-time" });
+        return;
+    }
+    if (schema.type === "integer") {
+        if (!Number.isInteger(value)) {
+            issues.push({ path: loc, message: "must be integer" });
+            return;
+        }
+        if (typeof schema.minimum === "number" && value < schema.minimum)
+            issues.push({ path: loc, message: `must be at least ${schema.minimum}` });
+        return;
+    }
+    if (schema.type === "array") {
+        if (!Array.isArray(value)) {
+            issues.push({ path: loc, message: "must be array" });
+            return;
+        }
+        if (typeof schema.minItems === "number" && value.length < schema.minItems)
+            issues.push({ path: loc, message: `must contain at least ${schema.minItems} item(s)` });
+        if (typeof schema.maxItems === "number" && value.length > schema.maxItems)
+            issues.push({ path: loc, message: `must contain at most ${schema.maxItems} item(s)` });
+        if (schema.uniqueItems && new Set(value.map((item) => JSON.stringify(item))).size !== value.length)
+            issues.push({ path: loc, message: "must contain unique items" });
+        if (schema.items)
+            value.forEach((item, index) => validateSchemaValue(item, schema.items, `${loc}[${index}]`, issues, root));
+        return;
+    }
+    if (schema.type === "object" || schema.required || schema.properties) {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            issues.push({ path: loc, message: "must be object" });
+            return;
+        }
+        const obj = value;
+        for (const key of schema.required ?? [])
+            if (!(key in obj))
+                issues.push({ path: `${loc}.${key}`, message: "is required" });
+        const properties = schema.properties ?? {};
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(obj))
+                if (!(key in properties))
+                    issues.push({ path: `${loc}.${key}`, message: "is not allowed" });
+        }
+        else if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+            for (const key of Object.keys(obj))
+                if (!(key in properties))
+                    validateSchemaValue(obj[key], schema.additionalProperties, `${loc}.${key}`, issues, root);
+        }
+        for (const [key, child] of Object.entries(properties))
+            if (key in obj)
+                validateSchemaValue(obj[key], child, `${loc}.${key}`, issues, root);
+    }
+}
+export function validateGroundedNarrative(value) {
+    let schema;
+    try {
+        schema = JSON.parse(fs.readFileSync(schemaPath(), "utf8"));
+    }
+    catch {
+        return [{ path: "$", message: "grounded execution narrative schema is unavailable" }];
+    }
+    const issues = [];
+    validateSchemaValue(value, schema, "$", issues, schema);
+    validateGroundingSemantics(value, issues);
+    return issues;
+}
+function resolveJsonPointer(value, pointer) {
+    if (!pointer.startsWith("/"))
+        return { found: false };
+    let current = value;
+    for (const encoded of pointer.slice(1).split("/")) {
+        const token = encoded.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (Array.isArray(current)) {
+            if (!/^(?:0|[1-9][0-9]*)$/.test(token))
+                return { found: false };
+            const index = Number(token);
+            if (index >= current.length)
+                return { found: false };
+            current = current[index];
+            continue;
+        }
+        const record = object(current);
+        if (!record || !Object.prototype.hasOwnProperty.call(record, token))
+            return { found: false };
+        current = record[token];
+    }
+    return { found: true, value: current };
+}
+function flowGateProposition(value) {
+    const gate = object(value);
+    const gateId = nonEmptyString(gate?.["gate_id"])
+        ?? nonEmptyString(gate?.["id"])
+        ?? nonEmptyString(gate?.["name"]);
+    const outcome = nonEmptyString(gate?.["status"])
+        ?? nonEmptyString(gate?.["outcome"]);
+    return gateId && outcome ? `Gate ${gateId} was ${outcome}.` : undefined;
+}
+function surfaceExplanationProposition(value, sourceRef) {
+    const explanation = object(value);
+    const status = nonEmptyString(explanation?.["status"]);
+    const claimValue = explanation?.["value"];
+    if (!status || typeof claimValue !== "string")
+        return undefined;
+    let parsed;
+    try {
+        parsed = parseSourceId(sourceRef);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.stream !== "surface-explanation")
+        return undefined;
+    return `Claim ${parsed.locator.claimId} was ${status}${claimValue.length > 0 ? ` with value ${JSON.stringify(claimValue)}` : ""}.`;
+}
+function validateGroundingSemantics(value, issues) {
+    const envelope = object(value);
+    if (!envelope || !Array.isArray(envelope["sections"]) || !Array.isArray(envelope["conclusions"]))
+        return;
+    const sections = envelope["sections"].flatMap((candidate) => object(candidate) ? [candidate] : []);
+    for (const [index, section] of sections.entries()) {
+        if (section["authority"] !== "flow" && section["authority"] !== "surface")
+            continue;
+        const embeddedBytes = nonEmptyString(section["embedded_bytes"]);
+        const declaredSha = nonEmptyString(section["sha256"]);
+        if (embeddedBytes && declaredSha && sha256(Buffer.from(embeddedBytes, "utf8")) !== declaredSha) {
+            issues.push({ path: `$.sections[${index}].embedded_bytes`, message: "must hash to the section sha256" });
+        }
+        if (embeddedBytes) {
+            try {
+                JSON.parse(embeddedBytes);
+            }
+            catch {
+                issues.push({ path: `$.sections[${index}].embedded_bytes`, message: "must contain valid JSON" });
+            }
+        }
+    }
+    for (const [index, candidate] of envelope["conclusions"].entries()) {
+        const conclusion = object(candidate);
+        const grounding = object(conclusion?.["grounding"]);
+        const kind = nonEmptyString(grounding?.["kind"]);
+        const sourceRef = nonEmptyString(grounding?.["source_ref"]);
+        if (!kind || !sourceRef)
+            continue;
+        const authority = kind === "flow_gate_derivation" ? "flow" : kind === "surface_explanation" ? "surface" : undefined;
+        if (!authority)
+            continue;
+        const matches = sections.filter((section) => section["authority"] === authority
+            && Array.isArray(section["source_refs"])
+            && section["source_refs"].includes(sourceRef));
+        if (matches.length !== 1) {
+            issues.push({ path: `$.conclusions[${index}].grounding.source_ref`, message: `must resolve to exactly one ${authority} section` });
+            continue;
+        }
+        const embeddedBytes = nonEmptyString(matches[0]["embedded_bytes"]);
+        if (!embeddedBytes)
+            continue;
+        let embedded;
+        try {
+            embedded = JSON.parse(embeddedBytes);
+        }
+        catch {
+            issues.push({ path: "$.sections", message: `${authority} section ${sourceRef} embedded_bytes must contain valid JSON` });
+            continue;
+        }
+        if (kind === "surface_explanation") {
+            const expected = surfaceExplanationProposition(embedded, sourceRef);
+            if (!expected) {
+                issues.push({ path: `$.conclusions[${index}].grounding.source_ref`, message: "must resolve to a typed surface explanation" });
+            }
+            else if (conclusion?.["proposition"] !== expected) {
+                issues.push({ path: `$.conclusions[${index}].proposition`, message: "must equal the proposition derived from the surface explanation" });
+            }
+            continue;
+        }
+        const pointer = nonEmptyString(grounding?.["pointer"]);
+        if (!pointer)
+            continue;
+        const resolved = resolveJsonPointer(embedded, pointer);
+        if (!resolved.found) {
+            issues.push({ path: `$.conclusions[${index}].grounding.pointer`, message: "must resolve inside the grounded flow section" });
+            continue;
+        }
+        const expected = flowGateProposition(resolved.value);
+        if (!expected) {
+            issues.push({ path: `$.conclusions[${index}].grounding.pointer`, message: "must resolve to a typed flow gate derivation" });
+        }
+        else if (conclusion?.["proposition"] !== expected) {
+            issues.push({ path: `$.conclusions[${index}].proposition`, message: "must equal the proposition derived from the flow gate" });
+        }
+    }
+}
+function readVerifiedManifest(narrativeDir) {
+    const manifestPath = path.join(narrativeDir, "source-manifest.json");
+    let bytes;
+    let parsed;
+    try {
+        bytes = fs.readFileSync(manifestPath);
+        parsed = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new GroundedNarrativeError("manifest_invalid", "narrative source manifest could not be read after verification");
+    }
+    if (validateNarrativeSourceManifest(parsed).length > 0) {
+        throw new GroundedNarrativeError("manifest_invalid", "narrative source manifest is invalid after verification");
+    }
+    return { manifest: parsed, bytes };
+}
+function parseEmbeddedJson(sourceId, content) {
+    try {
+        return JSON.parse(Buffer.from(content).toString("utf8"));
+    }
+    catch {
+        throw new GroundedNarrativeError("malformed_embedded_json", `${sourceId} does not contain valid JSON`, sourceId);
+    }
+}
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function correlationTimestamp(value) {
+    const record = object(value);
+    const raw = nonEmptyString(record?.["timestamp"])
+        ?? nonEmptyString(record?.["observed_at"])
+        ?? nonEmptyString(record?.["recorded_at"])
+        ?? nonEmptyString(record?.["at"]);
+    if (!raw)
+        return { kind: "missing" };
+    if (!/(?:Z|[+-][0-9]{2}:[0-9]{2})$/.test(raw))
+        return { kind: "no_timezone" };
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?(Z|([+-])(\d{2}):(\d{2}))$/.exec(raw);
+    if (!match)
+        return { kind: "invalid" };
+    const [, yearText, monthText, dayText, hourText, minuteText, secondText, fraction = "", zone, sign, offsetHourText = "0", offsetMinuteText = "0"] = match;
+    const [year, month, day, hour, minute, second, offsetHour, offsetMinute] = [yearText, monthText, dayText, hourText, minuteText, secondText, offsetHourText, offsetMinuteText].map(Number);
+    if (month < 1 || month > 12 || hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59)
+        return { kind: "invalid" };
+    const milliseconds = Number(fraction.padEnd(3, "0"));
+    const local = new Date(0);
+    local.setUTCFullYear(year, month - 1, day);
+    local.setUTCHours(hour, minute, second, milliseconds);
+    if (local.getUTCFullYear() !== year || local.getUTCMonth() !== month - 1 || local.getUTCDate() !== day
+        || local.getUTCHours() !== hour || local.getUTCMinutes() !== minute || local.getUTCSeconds() !== second)
+        return { kind: "invalid" };
+    const offset = zone === "Z" ? 0 : (offsetHour * 60 + offsetMinute) * (sign === "+" ? 1 : -1);
+    return { kind: "valid", value: local.getTime() - offset * 60_000 };
+}
+function correlationFor(narrativeDir, manifest, projection) {
+    const timestampsByRef = new Map();
+    for (const entry of manifest.sources) {
+        if (parseSourceId(entry.source_id).stream !== "telemetry")
+            continue;
+        const resolved = resolveSource(narrativeDir, entry.source_id);
+        if (resolved.status !== "resolved")
+            continue;
+        timestampsByRef.set(entry.source_id, correlationTimestamp(parseEmbeddedJson(entry.source_id, resolved.content)));
+    }
+    const windows = projection.turns.map((turn) => {
+        const sourceRefs = [...new Set(turn.statements.flatMap((statement) => statement.source_refs))]
+            .filter((sourceRef) => timestampsByRef.has(sourceRef));
+        const readings = sourceRefs.map((sourceRef) => ({ sourceRef, timestamp: timestampsByRef.get(sourceRef) }));
+        const valid = readings.flatMap(({ sourceRef, timestamp }) => timestamp.kind === "valid" ? [{ sourceRef, value: timestamp.value }] : []);
+        const timezoneInputRefs = readings.filter(({ timestamp }) => timestamp.kind === "no_timezone").map(({ sourceRef }) => sourceRef);
+        if (valid.length === 0)
+            return {
+                ordinal: turn.ordinal,
+                timezoneInputRefs,
+            };
+        const start = Math.min(...valid.map(({ value }) => value));
+        const end = Math.max(...valid.map(({ value }) => value));
+        return {
+            ordinal: turn.ordinal,
+            start,
+            end,
+            inputRefs: valid.filter(({ value }) => value === start || value === end).map(({ sourceRef }) => sourceRef),
+            timezoneInputRefs,
+        };
+    });
+    const turns = projection.turns.map((turn) => ({ turn_ordinal: turn.ordinal, placed: [] }));
+    const turnsByOrdinal = new Map(turns.map((turn) => [turn.turn_ordinal, turn]));
+    const unplaced = [];
+    for (const entry of manifest.sources) {
+        const parsedId = parseSourceId(entry.source_id);
+        if (parsedId.stream !== "flow-state")
+            continue;
+        const resolved = resolveSource(narrativeDir, entry.source_id);
+        if (resolved.status !== "resolved")
+            continue;
+        const state = object(parseEmbeddedJson(entry.source_id, resolved.content));
+        const transitions = Array.isArray(state?.["transitions"]) ? state["transitions"] : [];
+        for (const value of transitions) {
+            const transition = object(value);
+            const from = nonEmptyString(transition?.["from"]);
+            const to = nonEmptyString(transition?.["to"]);
+            if (!from || !to)
+                continue;
+            const at = nonEmptyString(transition?.["at"]);
+            const source_refs = [entry.source_id];
+            const record = {
+                kind: "flow-transition",
+                from,
+                to,
+                ...(at ? { at } : {}),
+                source_refs,
+                rule: { id: "flow-turn-correlation/v1", version: "v1", inputs: [...source_refs] },
+            };
+            if (windows.length === 0) {
+                unplaced.push({ ...record, reason: "no_turns" });
+                continue;
+            }
+            const timestamp = correlationTimestamp({ at });
+            if (timestamp.kind === "missing" || timestamp.kind === "invalid") {
+                unplaced.push({ ...record, reason: "no_timestamp" });
+                continue;
+            }
+            const timezoneInputs = [...new Set(windows.flatMap((window) => window.timezoneInputRefs))];
+            if (timestamp.kind === "no_timezone" || timezoneInputs.length > 0) {
+                unplaced.push({
+                    ...record,
+                    rule: { ...record.rule, inputs: [...new Set([entry.source_id, ...timezoneInputs])] },
+                    reason: "no_timezone",
+                });
+                continue;
+            }
+            const matches = windows.filter((window) => window.start !== undefined && window.end !== undefined
+                && timestamp.value > window.start && timestamp.value < window.end);
+            if (matches.length !== 1) {
+                const inputs = [...new Set([entry.source_id, ...matches.flatMap((window) => window.inputRefs ?? [])])];
+                unplaced.push({ ...record, rule: { ...record.rule, inputs }, reason: "ambiguous_window" });
+                continue;
+            }
+            const inputs = [...new Set([entry.source_id, ...(matches[0].inputRefs ?? [])])];
+            turnsByOrdinal.get(matches[0].ordinal).placed.push({ ...record, rule: { ...record.rule, inputs } });
+        }
+    }
+    return { turns, unplaced };
+}
+function conclusionsFor(sections) {
+    const conclusions = [];
+    for (const section of sections) {
+        if (section.authority === "flow") {
+            const report = object(parseEmbeddedJson(section.source_refs[0], Buffer.from(section.embedded_bytes, "utf8")));
+            const summaries = Array.isArray(report?.["gate_summaries"]) ? report["gate_summaries"] : [];
+            summaries.forEach((value, index) => {
+                const proposition = flowGateProposition(value);
+                if (proposition)
+                    conclusions.push({
+                        proposition,
+                        grounding: { kind: "flow_gate_derivation", source_ref: section.source_refs[0], pointer: `/gate_summaries/${index}` },
+                    });
+            });
+            continue;
+        }
+        if (section.authority === "surface") {
+            const explanation = object(parseEmbeddedJson(section.source_refs[0], Buffer.from(section.embedded_bytes, "utf8")));
+            const proposition = surfaceExplanationProposition(explanation, section.source_refs[0]);
+            if (proposition)
+                conclusions.push({
+                    proposition,
+                    grounding: { kind: "surface_explanation", source_ref: section.source_refs[0] },
+                });
+        }
+    }
+    return conclusions;
+}
+/** Compile exclusively from the frozen manifest and its content-addressed blobs. */
+export function composeGroundedNarrative(narrativeDir, config) {
+    const verification = verifyManifest(narrativeDir);
+    if (verification.perSource.some((entry) => entry.sourceId === "manifest")) {
+        throw new GroundedNarrativeError("manifest_invalid", "narrative source manifest verification failed");
+    }
+    const { manifest, bytes: manifestBytes } = readVerifiedManifest(narrativeDir);
+    const manifestById = new Map(manifest.sources.map((entry) => [entry.source_id, entry]));
+    for (const result of verification.perSource) {
+        if (result.status !== "unavailable")
+            continue;
+        const declared = manifestById.get(result.sourceId);
+        if (!declared || declared.status !== "unavailable" || declared.unavailable_reason !== result.reason) {
+            throw new GroundedNarrativeError("source_integrity_failed", `source verification failed for ${result.sourceId}`, result.sourceId);
+        }
+    }
+    const sections = [];
+    const unavailableSources = [];
+    let embeddedCount = 0;
+    for (const entry of manifest.sources) {
+        const resolved = resolveSource(narrativeDir, entry.source_id);
+        if (resolved.status === "unavailable") {
+            unavailableSources.push({ source_ref: entry.source_id, reason: resolved.reason });
+            continue;
+        }
+        const parsedId = parseSourceId(entry.source_id);
+        if (parsedId.stream !== "flow-report" && parsedId.stream !== "surface-explanation")
+            continue;
+        parseEmbeddedJson(entry.source_id, resolved.content);
+        const embeddedBytes = Buffer.from(resolved.content).toString("utf8");
+        const embeddedSha = sha256(Buffer.from(embeddedBytes, "utf8"));
+        if (embeddedSha !== resolved.sha256 || entry.status !== "snapshotted" || embeddedSha !== entry.sha256) {
+            throw new GroundedNarrativeError("embedded_integrity_failed", `embedded bytes for ${entry.source_id} do not reproduce the frozen manifest hash`, entry.source_id);
+        }
+        sections.push(parsedId.stream === "surface-explanation" ? {
+            authority: "surface",
+            kind: "claim-explanation",
+            source_refs: [entry.source_id],
+            sha256: embeddedSha,
+            embedded_bytes: embeddedBytes,
+        } : {
+            authority: "flow",
+            kind: "flow-process-projection",
+            source_refs: [entry.source_id],
+            sha256: embeddedSha,
+            embedded_bytes: embeddedBytes,
+        });
+        embeddedCount += 1;
+    }
+    const runtimeProjection = projectRuntimeNarrative(narrativeDir, { projectedAt: config.compiledAt });
+    sections.push({
+        authority: "flow-agents",
+        kind: "runtime-projection",
+        sha256: sha256(Buffer.from(stableStringify(runtimeProjection))),
+        embedded: runtimeProjection,
+    });
+    let schemaBytes;
+    let compilerBytes;
+    try {
+        schemaBytes = fs.readFileSync(schemaPath());
+    }
+    catch {
+        throw new GroundedNarrativeError("schema_unavailable", "grounded execution narrative schema is unavailable");
+    }
+    // This intentionally identifies the built module, not TypeScript source;
+    // compiler_sha256 is consequently stable within one build and build-dependent.
+    try {
+        compilerBytes = fs.readFileSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        throw new GroundedNarrativeError("compiler_unavailable", "built narrative compiler module is unavailable");
+    }
+    return {
+        schema_version: GROUNDED_EXECUTION_NARRATIVE_SCHEMA_VERSION,
+        narrative_id: manifest.narrative_id,
+        provenance: {
+            compiler: { name: GROUNDED_EXECUTION_NARRATIVE_COMPILER_NAME, version: flowAgentsPackageVersion() },
+            compiled_at: config.compiledAt,
+            manifest_sha256: sha256(manifestBytes),
+            schema_sha256: sha256(schemaBytes),
+            config_sha256: sha256(Buffer.from(stableStringify(config))),
+            compiler_sha256: sha256(compilerBytes),
+        },
+        capture_completeness: manifest.capture_completeness,
+        sections,
+        correlation: correlationFor(narrativeDir, manifest, runtimeProjection),
+        conclusions: conclusionsFor(sections),
+        coverage: { sources: manifest.sources.length, embedded: embeddedCount, unavailable: unavailableSources.length },
+        unavailable_sources: unavailableSources,
+    };
+}
+export function writeEnvelope(narrativeDir, envelope, options = {}) {
+    const bytes = Buffer.from(stableStringify(envelope));
+    const envelopeSha256 = sha256(bytes);
+    const envelopesDir = options.outDir ? path.resolve(options.outDir) : path.join(narrativeDir, "envelopes");
+    const envelopePath = path.join(envelopesDir, `${envelopeSha256}.json`);
+    const lineagePath = path.join(narrativeDir, "envelope-lineage.jsonl");
+    ensureSafeDirectory(options.outDir ? envelopesDir : narrativeDir, envelopesDir);
+    try {
+        fs.writeFileSync(envelopePath, bytes, { flag: "wx" });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        const stat = fs.lstatSync(envelopePath);
+        if (stat.isSymbolicLink() || !stat.isFile())
+            throw new Error(`refusing unsafe envelope target at ${envelopePath}`);
+        const existing = fs.readFileSync(envelopePath);
+        if (!existing.equals(bytes))
+            throw new Error(`content-addressed envelope collision at ${envelopePath}`);
+    }
+    const lineage = {
+        compiled_at: envelope.provenance.compiled_at,
+        envelope_sha256: envelopeSha256,
+        manifest_sha256: envelope.provenance.manifest_sha256,
+    };
+    if (fs.existsSync(lineagePath)) {
+        const stat = fs.lstatSync(lineagePath);
+        if (stat.isSymbolicLink() || !stat.isFile())
+            throw new Error(`refusing unsafe envelope lineage target at ${lineagePath}`);
+    }
+    // JSONL requires one compact record per line. The literal's insertion order
+    // is lexicographic, matching stableStringify's key discipline without its
+    // multi-line indentation.
+    const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+    const descriptor = fs.openSync(lineagePath, fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_WRONLY | noFollow, 0o600);
+    try {
+        fs.writeSync(descriptor, `${JSON.stringify(lineage)}\n`, undefined, "utf8");
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+    let renderPath;
+    if (options.render) {
+        renderPath = path.join(envelopesDir, `${envelopeSha256}.md`);
+        const rendered = renderGroundedNarrative(envelope);
+        try {
+            fs.writeFileSync(renderPath, rendered, { flag: "wx" });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const existing = fs.readFileSync(renderPath, "utf8");
+            if (existing !== rendered)
+                throw new Error(`content-addressed rendering collision at ${renderPath}`);
+        }
+    }
+    return { envelopePath, lineagePath, envelopeSha256, ...(renderPath ? { renderPath } : {}) };
+}

package/dist/pi/build/src/narrative/eval-result.d.ts

@@ -0,0 +1,60 @@
+export declare const NARRATIVE_EVAL_RESULT_SCHEMA_VERSION: "narrative-eval-result/v1";
+export type NarrativeEvalVerdict = "accept" | "reject" | "known_gap";
+export interface NarrativeEvalRawSourceLink {
+    source_id: string;
+    manifest_path: string;
+}
+export interface NarrativeEvalFixtureResult {
+    id: string;
+    case_class: string;
+    expected: NarrativeEvalVerdict;
+    actual: NarrativeEvalVerdict;
+    pass: boolean;
+    raw_source_links: NarrativeEvalRawSourceLink[];
+}
+export interface NarrativeEvalMetrics {
+    unsupported_claim_rate: number;
+    citation_precision: number;
+    citation_recall: number;
+    citation_resolvability: number;
+    material_claim_coverage: number;
+    omission_rate_by_class: Record<string, number>;
+    epistemic_classification_accuracy: number;
+}
+export interface NarrativeEvalMetricUncertainty {
+    sample_n: number;
+    /** Observed [lower, upper] bound for the metric; a deterministic corpus yields a point range. */
+    range: [number, number];
+    basis: string;
+}
+export interface NarrativeEvalCapabilityParity {
+    runtime: string;
+    capability: string;
+    declared_status: "supported" | "partial" | "unsupported";
+}
+export interface NarrativeEvalKnownGap {
+    code: string;
+    detail: string;
+    ref?: string;
+}
+export interface NarrativeEvalResult {
+    schema_version: typeof NARRATIVE_EVAL_RESULT_SCHEMA_VERSION;
+    work_item: string;
+    measurement_note: string;
+    results: NarrativeEvalFixtureResult[];
+    metrics: NarrativeEvalMetrics;
+    uncertainty: Record<string, NarrativeEvalMetricUncertainty>;
+    capability_parity: NarrativeEvalCapabilityParity[];
+    known_gaps: NarrativeEvalKnownGap[];
+}
+export type SchemaIssue = {
+    path: string;
+    message: string;
+};
+/**
+ * Validate a value against the shipped `narrative-eval-result/v1` schema. Returns
+ * an empty array for a conforming value; one `{path, message}` issue per defect
+ * otherwise (missing required field, wrong `schema_version`, extra property, an
+ * out-of-range rate, and so on).
+ */
+export declare function validateNarrativeEvalResult(value: unknown): SchemaIssue[];