@kontourai/flow-agents 3.12.0 → 4.0.0

package/dist/codex/build/src/cli/narrative-sources.js

@@ -0,0 +1,282 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { atomicWriteFile, ensureSafeDirectory } from "../lib/fs.js";
+import { parseArgs, flagBool, flagList, flagString } from "../lib/args.js";
+import { flowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
+import { queryCapability } from "../lib/capability-declarations.js";
+import { composeGroundedNarrative, validateGroundedNarrative, writeEnvelope, } from "../narrative/envelope.js";
+import { bindIntentAnnotation, captureIntent } from "../narrative/intent.js";
+import { appendIntentEconomics, readIntentEconomics, reduceIntentEconomics, } from "../narrative/intent-economics.js";
+import { NarrativeGroundingError, validateNarrativeGrounding, } from "../narrative/grounding-validator.js";
+import { effectiveNarrativeRedactionFields } from "../narrative/policy-filter.js";
+import { projectRuntimeNarrative, stableStringify, validateNarrativeRuntimeProjection } from "../narrative/projection.js";
+import { resolveManifestEntry, resolveSource, verifyManifest } from "../narrative/resolver.js";
+import { snapshotNarrative } from "../narrative/snapshot.js";
+import { parseSourceId } from "../narrative/source-ids.js";
+export const NARRATIVE_NAMESPACE_ROOT = path.join(".kontourai", "narrative");
+function packageVersion() {
+    try {
+        const packageFile = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../package.json");
+        return String(JSON.parse(fs.readFileSync(packageFile, "utf8")).version ?? "unknown");
+    }
+    catch {
+        return "unknown";
+    }
+}
+function usage() {
+    console.error(`usage: flow-agents narrative-sources <snapshot|resolve|verify|project|compose> [options]
+
+snapshot:
+  (--session-slug SLUG | --artifact-root PATH) --narrative-id ID --source FA1 [--source FA1 ...]
+  [--telemetry-root PATH] [--session-root PATH] [--flow-root PATH]
+  [--transcript-path FILE] [--repo-root PATH] [--redact-fields FIELD,...]
+  [--allow-transcript-content]  (transcript content is default-deny: without
+                                 this grant transcript sources are recorded
+                                 path_only as unavailable/redacted)
+  [--capture-completeness FILE]
+resolve:
+  --narrative-dir PATH --source-id FA1 (--out FILE | --json)
+project:
+  --narrative-dir PATH (--out FILE | --json) [--projected-at DATE-TIME]
+compose:
+  --narrative-dir PATH --compiled-at DATE-TIME (--out-dir DIR | --json) [--render]
+verify:
+  --narrative-dir PATH --json
+capture-intent:
+  --narrative-dir PATH --runtime ID --actor ID --action-ref FA1 --active-gate-ref FA1
+  [--purpose TEXT] [--objective-ref FA1] [--redact-fields FIELD,...]
+  [--capability-fixture supported|unsupported]  (fixture-only: inject a resolved
+                                 CapabilityStatus; default resolves via the
+                                 runtime's intent_annotation declaration)
+intent-economics:
+  --narrative-dir PATH
+  (--record --mode annotation_on|annotation_off --input-tokens N --output-tokens N
+     --wall-clock-ms N [--attempted-at DATE-TIME]
+   | --report)`);
+}
+function required(flags, name) {
+    const value = flagString(flags, name);
+    if (!value)
+        throw new Error(`--${name} is required`);
+    return value;
+}
+function readCaptureCompleteness(file) {
+    if (!file)
+        return { channels: {}, known_gaps: [] };
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("capture completeness must be a JSON object");
+    return parsed;
+}
+function snapshot(flags) {
+    const sessionSlug = flagString(flags, "session-slug");
+    const explicitArtifactRoot = flagString(flags, "artifact-root");
+    if (Boolean(sessionSlug) === Boolean(explicitArtifactRoot))
+        throw new Error("exactly one of --session-slug or --artifact-root is required");
+    if (sessionSlug && (sessionSlug.includes("/") || sessionSlug.includes("\\") || sessionSlug === "." || sessionSlug === ".."))
+        throw new Error("--session-slug must be a single path component");
+    const narrativeId = required(flags, "narrative-id");
+    if (narrativeId.includes("/") || narrativeId.includes("\\") || narrativeId === "." || narrativeId === "..")
+        throw new Error("--narrative-id must be a single path component");
+    const sourceTexts = flagList(flags, "source");
+    if (!sourceTexts.length)
+        throw new Error("at least one --source is required");
+    if (new Set(sourceTexts).size !== sourceTexts.length)
+        throw new Error("--source values must be unique");
+    const artifactRoot = explicitArtifactRoot ? path.resolve(explicitArtifactRoot) : flowAgentsArtifactRoot();
+    const sessionDir = sessionSlug ? path.join(artifactRoot, sessionSlug) : flagString(flags, "session-root");
+    const projectRoot = sessionSlug ? path.dirname(path.dirname(artifactRoot)) : artifactRoot;
+    const narrativeDir = sessionSlug
+        ? path.join(projectRoot, NARRATIVE_NAMESPACE_ROOT, sessionSlug, narrativeId)
+        : path.join(projectRoot, NARRATIVE_NAMESPACE_ROOT, narrativeId);
+    const roots = {
+        telemetryDir: flagString(flags, "telemetry-root"), sessionDir,
+        flowRoot: flagString(flags, "flow-root"), transcriptPath: flagString(flags, "transcript-path"),
+        repoRoot: flagString(flags, "repo-root"),
+    };
+    const narrativeFields = (flagString(flags, "redact-fields") ?? "").split(",").map((field) => field.trim()).filter(Boolean);
+    const redactionFields = effectiveNarrativeRedactionFields(narrativeFields);
+    const result = snapshotNarrative({
+        narrativeDir, narrativeId, requests: sourceTexts.map((source) => ({ source: parseSourceId(source), roots })), redactionFields,
+        compiler: {
+            name: "@kontourai/flow-agents", version: packageVersion(),
+            policy_hash: createHash("sha256").update(JSON.stringify(redactionFields)).digest("hex"),
+        },
+        captureCompleteness: readCaptureCompleteness(flagString(flags, "capture-completeness")),
+        allowTranscriptContent: flagBool(flags, "allow-transcript-content"),
+    });
+    console.log(JSON.stringify(result));
+    return 0;
+}
+function resolve(flags) {
+    const narrativeDir = required(flags, "narrative-dir");
+    const sourceId = required(flags, "source-id");
+    const out = flagString(flags, "out");
+    const json = flagBool(flags, "json");
+    if (Boolean(out) === json)
+        throw new Error("exactly one of --out or --json is required");
+    const result = resolveSource(narrativeDir, sourceId);
+    if (result.status === "unavailable") {
+        console.log(JSON.stringify(result));
+        return 2;
+    }
+    if (out)
+        atomicWriteFile(path.dirname(path.resolve(out)), path.resolve(out), Buffer.from(result.content));
+    const { content: _content, ...metadata } = result;
+    console.log(JSON.stringify(metadata));
+    return 0;
+}
+function verify(flags) {
+    const narrativeDir = required(flags, "narrative-dir");
+    if (!flagBool(flags, "json"))
+        throw new Error("--json is required");
+    const report = verifyManifest(narrativeDir);
+    console.log(JSON.stringify(report));
+    return report.ok ? 0 : 2;
+}
+function projectNarrative(flags) {
+    const narrativeDir = required(flags, "narrative-dir");
+    const out = flagString(flags, "out");
+    const json = flagBool(flags, "json");
+    if (Boolean(out) === json)
+        throw new Error("exactly one of --out or --json is required");
+    const projectedAt = flagString(flags, "projected-at") ?? new Date().toISOString();
+    const projection = projectRuntimeNarrative(narrativeDir, { projectedAt });
+    const issues = validateNarrativeRuntimeProjection(projection);
+    if (issues.length > 0) {
+        throw new Error(`narrative runtime projection validation failed: ${issues.map((issue) => `${issue.path} ${issue.message}`).join("; ")}`);
+    }
+    const serialized = `${stableStringify(projection)}\n`;
+    if (out)
+        atomicWriteFile(path.dirname(path.resolve(out)), path.resolve(out), Buffer.from(serialized));
+    else
+        process.stdout.write(serialized);
+    return 0;
+}
+function composeNarrative(flags) {
+    const narrativeDir = required(flags, "narrative-dir");
+    const compiledAt = required(flags, "compiled-at");
+    const outDir = flagString(flags, "out-dir");
+    const json = flagBool(flags, "json");
+    const render = flagBool(flags, "render");
+    if (Boolean(outDir) === json)
+        throw new Error("exactly one of --out-dir or --json is required");
+    if (render && !outDir)
+        throw new Error("--render requires --out-dir");
+    const envelope = composeGroundedNarrative(narrativeDir, { compiledAt });
+    const issues = validateGroundedNarrative(envelope);
+    if (issues.length > 0) {
+        throw new Error(`grounded execution narrative validation failed: ${issues.map((issue) => `${issue.path} ${issue.message}`).join("; ")}`);
+    }
+    const grounding = validateNarrativeGrounding(envelope, narrativeDir);
+    if (!grounding.ok)
+        throw new NarrativeGroundingError(grounding.violations);
+    if (outDir) {
+        const written = writeEnvelope(narrativeDir, envelope, { outDir, render });
+        process.stdout.write(`${stableStringify(written)}\n`);
+    }
+    else {
+        process.stdout.write(`${stableStringify(envelope)}\n`);
+    }
+    return 0;
+}
+function captureIntentVerb(flags) {
+    const narrativeDir = path.resolve(required(flags, "narrative-dir"));
+    const runtime = required(flags, "runtime");
+    const actor = required(flags, "actor");
+    const actionRef = required(flags, "action-ref");
+    const activeGateRef = required(flags, "active-gate-ref");
+    const purpose = flagString(flags, "purpose");
+    const objectiveRef = flagString(flags, "objective-ref");
+    const narrativeFields = (flagString(flags, "redact-fields") ?? "").split(",").map((field) => field.trim()).filter(Boolean);
+    const redactionFields = effectiveNarrativeRedactionFields(narrativeFields);
+    // The capability is caller-resolved. By default it comes from the runtime's
+    // programmatic declaration (queryCapability, #620); --capability-fixture lets a
+    // FIXTURE inject a resolved status directly (D2) — no real runtime feeds
+    // at-action annotations yet, so the supported path is exercised via a fixture.
+    const fixture = flagString(flags, "capability-fixture");
+    let capability;
+    if (fixture === "supported")
+        capability = { status: "supported" };
+    else if (fixture === "unsupported")
+        capability = { status: "unsupported", reason: "fixture-injected unsupported status" };
+    else if (fixture !== undefined)
+        throw new Error("--capability-fixture must be 'supported' or 'unsupported'");
+    else
+        capability = queryCapability(runtime, "intent_annotation");
+    ensureSafeDirectory(narrativeDir, narrativeDir);
+    // R1 (review HIGH): the action ref is co-bound to the frozen narrative manifest.
+    // captureIntent resolves it to its frozen manifest entry (existence + the action's
+    // own captured_at); a fabricated/nonexistent action ref is rejected (throws) before
+    // any annotation is written, and the annotation's captured_at derives from the
+    // resolved action entry rather than bind-time wall-clock.
+    const captured = captureIntent({
+        capability, actor, runtimeId: runtime, actionRef, activeGateRef, redactionFields,
+        ...(purpose !== undefined ? { purpose } : {}),
+        ...(objectiveRef !== undefined ? { objectiveRef } : {}),
+    }, { resolveAction: (ref) => resolveManifestEntry(narrativeDir, ref) });
+    const { path: annotationPath, annotation } = bindIntentAnnotation(narrativeDir, captured);
+    console.error(`captured ${annotation.mode} intent annotation at ${annotationPath}`);
+    console.log(JSON.stringify(annotation));
+    return 0;
+}
+function intentEconomicsVerb(flags) {
+    const narrativeDir = path.resolve(required(flags, "narrative-dir"));
+    const report = flagBool(flags, "report");
+    const record = flagBool(flags, "record");
+    if (report === record)
+        throw new Error("exactly one of --record or --report is required");
+    if (report) {
+        const summary = reduceIntentEconomics(readIntentEconomics(narrativeDir));
+        console.log(JSON.stringify(summary));
+        return 0;
+    }
+    const mode = flagString(flags, "mode");
+    if (mode !== "annotation_on" && mode !== "annotation_off")
+        throw new Error("--mode must be annotation_on or annotation_off");
+    const number = (name) => {
+        const raw = required(flags, name);
+        const value = Number(raw);
+        if (!Number.isFinite(value))
+            throw new Error(`--${name} must be a number`);
+        return value;
+    };
+    ensureSafeDirectory(narrativeDir, narrativeDir);
+    appendIntentEconomics(narrativeDir, {
+        mode: mode,
+        input_tokens: number("input-tokens"),
+        output_tokens: number("output-tokens"),
+        wall_clock_ms: number("wall-clock-ms"),
+        attempted_at: flagString(flags, "attempted-at") ?? new Date().toISOString(),
+    });
+    console.error(`recorded ${mode} intent-economics sample`);
+    return 0;
+}
+export function main(argv = process.argv.slice(2)) {
+    const args = parseArgs(argv);
+    const verb = args.positionals[0];
+    try {
+        if (verb === "snapshot")
+            return snapshot(args.flags);
+        if (verb === "resolve")
+            return resolve(args.flags);
+        if (verb === "project")
+            return projectNarrative(args.flags);
+        if (verb === "compose")
+            return composeNarrative(args.flags);
+        if (verb === "verify")
+            return verify(args.flags);
+        if (verb === "capture-intent")
+            return captureIntentVerb(args.flags);
+        if (verb === "intent-economics")
+            return intentEconomicsVerb(args.flags);
+        usage();
+        return 64;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : "narrative source command failed");
+        return 64;
+    }
+}

package/dist/codex/build/src/cli/public-contracts.d.ts

@@ -1,4 +1,180 @@
 export declare const WORKFLOW_CRITIQUE_STATUSES: readonly ["pass", "fail", "not_verified"];
+export declare const WORKFLOW_ACCEPTANCE_STATUSES: readonly ["pending", "pass", "fail", "not_verified", "accepted_gap"];
+export declare const EVIDENCE_REF_KINDS: readonly ["source", "command", "artifact", "provider", "external"];
+export declare const EVIDENCE_REF_FIELD_SCHEMAS: {
+    readonly kind: {
+        readonly type: "string";
+        readonly enum: readonly ["source", "command", "artifact", "provider", "external"];
+    };
+    readonly url: {
+        readonly type: "string";
+        readonly minLength: 1;
+    };
+    readonly file: {
+        readonly type: "string";
+        readonly minLength: 1;
+    };
+    readonly line_start: {
+        readonly type: "integer";
+        readonly minimum: 1;
+    };
+    readonly line_end: {
+        readonly type: "integer";
+        readonly minimum: 1;
+    };
+    readonly excerpt: {
+        readonly type: "string";
+        readonly minLength: 1;
+    };
+    readonly summary: {
+        readonly type: "string";
+        readonly minLength: 1;
+    };
+};
+export declare const EVIDENCE_REF_RULES: {
+    readonly source: readonly [{
+        readonly mode: "all";
+        readonly fields: readonly ["file", "line_start", "line_end", "excerpt"];
+    }];
+    readonly artifact: readonly [{
+        readonly mode: "any";
+        readonly fields: readonly ["file", "url"];
+    }, {
+        readonly mode: "any";
+        readonly fields: readonly ["summary", "excerpt"];
+    }];
+    readonly command: readonly [{
+        readonly mode: "any";
+        readonly fields: readonly ["summary", "excerpt", "url"];
+    }];
+    readonly provider: readonly [{
+        readonly mode: "all";
+        readonly fields: readonly ["url"];
+    }];
+    readonly external: readonly [{
+        readonly mode: "all";
+        readonly fields: readonly ["url"];
+    }];
+};
+export declare const EVIDENCE_REF_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["kind"];
+    readonly properties: {
+        readonly kind: {
+            readonly type: "string";
+            readonly enum: readonly ["source", "command", "artifact", "provider", "external"];
+        };
+        readonly url: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly file: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly line_start: {
+            readonly type: "integer";
+            readonly minimum: 1;
+        };
+        readonly line_end: {
+            readonly type: "integer";
+            readonly minimum: 1;
+        };
+        readonly excerpt: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly summary: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+    };
+    readonly allOf: Record<string, unknown>[];
+    readonly examples: readonly [{
+        readonly kind: "artifact";
+        readonly file: "<project-relative-artifact-path>";
+        readonly summary: "<what this artifact proves>";
+    }, {
+        readonly kind: "command";
+        readonly summary: "<command result and what it proves>";
+    }];
+};
+export declare const WORKFLOW_EVIDENCE_PARAMETERS: readonly [{
+    readonly name: "status";
+    readonly flag: "--status";
+    readonly required: true;
+    readonly allowed_values: readonly ["pass", "fail", "not_verified"];
+}, {
+    readonly name: "summary";
+    readonly flag: "--summary";
+    readonly required: true;
+}, {
+    readonly name: "evidence_ref_json";
+    readonly flag: "--evidence-ref-json";
+    readonly required: true;
+    readonly repeatable: true;
+    readonly value_schema_ref: "#/public_interfaces/schemas/evidence_ref_json";
+}, {
+    readonly name: "route_reason";
+    readonly flag: "--route-reason";
+    readonly required: false;
+}, {
+    readonly name: "criterion_json";
+    readonly flag: "--criterion-json";
+    readonly required: false;
+    readonly repeatable: true;
+}, {
+    readonly name: "accepted_gap_reason";
+    readonly flag: "--accepted-gap-reason";
+    readonly required: false;
+}, {
+    readonly name: "waived_by";
+    readonly flag: "--waived-by";
+    readonly required: false;
+}, {
+    readonly name: "command";
+    readonly flag: "--command";
+    readonly required: false;
+    readonly repeatable: true;
+}];
+export declare const WORKFLOW_CRITIQUE_PARAMETERS: readonly [{
+    readonly name: "id";
+    readonly flag: "--id";
+    readonly required: false;
+}, {
+    readonly name: "verdict";
+    readonly flag: "--verdict";
+    readonly required: true;
+    readonly allowed_values: readonly ["pass", "fail", "not_verified"];
+}, {
+    readonly name: "summary";
+    readonly flag: "--summary";
+    readonly required: true;
+}, {
+    readonly name: "lane_json";
+    readonly flag: "--lane-json";
+    readonly required: true;
+    readonly repeatable: true;
+}, {
+    readonly name: "artifact_ref";
+    readonly flag: "--artifact-ref";
+    readonly required: false;
+    readonly repeatable: true;
+    readonly required_when: {
+        readonly parameter: "verdict";
+        readonly equals: "pass";
+    };
+}, {
+    readonly name: "finding_json";
+    readonly flag: "--finding-json";
+    readonly required: false;
+    readonly repeatable: true;
+}, {
+    readonly name: "timestamp";
+    readonly flag: "--timestamp";
+    readonly required: false;
+}];
 export declare const PUBLISH_CHANGE_OPERATION: "publish-change";
 export declare const PUBLISH_CHANGE_OPERATION_PROTOCOL: {
     readonly schema_version: "1.0";
@@ -67,6 +243,47 @@ export declare const PUBLISH_CHANGE_OPERATION_PROTOCOL: {
         readonly completion_verification: "authenticated_change_provider_required";
     };
 };
+export declare const NARRATIVE_PROMOTE_OPERATION: "narrative.promote";
+export declare const NARRATIVE_PROMOTE_OPERATION_PROTOCOL: {
+    readonly schema_version: "1.0";
+    readonly operation: "narrative.promote";
+    readonly kind: "provider_capability";
+    readonly capability: "narrative.promote";
+    readonly parameters: readonly [{
+        readonly name: "narrative_id";
+        readonly required: true;
+        readonly type: "string";
+        readonly max_length: 255;
+    }, {
+        readonly name: "envelope_sha256";
+        readonly required: true;
+        readonly type: "string";
+        readonly pattern: "^[a-f0-9]{64}$";
+    }];
+    readonly result: {
+        readonly required: readonly ["provider", "completion_id", "evidence"];
+        readonly properties: {
+            readonly provider: {
+                readonly type: "string";
+                readonly max_length: 128;
+            };
+            readonly completion_id: {
+                readonly type: "string";
+                readonly max_length: 1024;
+            };
+            readonly evidence: {
+                readonly type: "object";
+            };
+        };
+        readonly persist_as: "evidence";
+    };
+    readonly availability: {
+        readonly status: "external_capability_required";
+        readonly executable_by_flow_agents: false;
+        readonly direct_write_allowed: false;
+        readonly completion_verification: "authenticated_narrative_provider_required";
+    };
+};
 export declare const PUBLIC_OPERATION_CONTRACTS: {
     readonly "publish-change": {
         readonly schema_version: "1.0";
@@ -135,5 +352,45 @@ export declare const PUBLIC_OPERATION_CONTRACTS: {
             readonly completion_verification: "authenticated_change_provider_required";
         };
     };
+    readonly "narrative.promote": {
+        readonly schema_version: "1.0";
+        readonly operation: "narrative.promote";
+        readonly kind: "provider_capability";
+        readonly capability: "narrative.promote";
+        readonly parameters: readonly [{
+            readonly name: "narrative_id";
+            readonly required: true;
+            readonly type: "string";
+            readonly max_length: 255;
+        }, {
+            readonly name: "envelope_sha256";
+            readonly required: true;
+            readonly type: "string";
+            readonly pattern: "^[a-f0-9]{64}$";
+        }];
+        readonly result: {
+            readonly required: readonly ["provider", "completion_id", "evidence"];
+            readonly properties: {
+                readonly provider: {
+                    readonly type: "string";
+                    readonly max_length: 128;
+                };
+                readonly completion_id: {
+                    readonly type: "string";
+                    readonly max_length: 1024;
+                };
+                readonly evidence: {
+                    readonly type: "object";
+                };
+            };
+            readonly persist_as: "evidence";
+        };
+        readonly availability: {
+            readonly status: "external_capability_required";
+            readonly executable_by_flow_agents: false;
+            readonly direct_write_allowed: false;
+            readonly completion_verification: "authenticated_narrative_provider_required";
+        };
+    };
 };
 export declare const PUBLIC_OPERATION_IDS: Set<string>;

package/dist/codex/build/src/cli/public-contracts.js

@@ -1,4 +1,64 @@
 export const WORKFLOW_CRITIQUE_STATUSES = ["pass", "fail", "not_verified"];
+export const WORKFLOW_ACCEPTANCE_STATUSES = ["pending", "pass", "fail", "not_verified", "accepted_gap"];
+export const EVIDENCE_REF_KINDS = ["source", "command", "artifact", "provider", "external"];
+export const EVIDENCE_REF_FIELD_SCHEMAS = {
+    kind: { type: "string", enum: EVIDENCE_REF_KINDS },
+    url: { type: "string", minLength: 1 },
+    file: { type: "string", minLength: 1 },
+    line_start: { type: "integer", minimum: 1 },
+    line_end: { type: "integer", minimum: 1 },
+    excerpt: { type: "string", minLength: 1 },
+    summary: { type: "string", minLength: 1 },
+};
+export const EVIDENCE_REF_RULES = {
+    source: [{ mode: "all", fields: ["file", "line_start", "line_end", "excerpt"] }],
+    artifact: [
+        { mode: "any", fields: ["file", "url"] },
+        { mode: "any", fields: ["summary", "excerpt"] },
+    ],
+    command: [{ mode: "any", fields: ["summary", "excerpt", "url"] }],
+    provider: [{ mode: "all", fields: ["url"] }],
+    external: [{ mode: "all", fields: ["url"] }],
+};
+function evidenceRuleSchema(kind) {
+    const clauses = EVIDENCE_REF_RULES[kind].map((clause) => clause.mode === "all"
+        ? { required: [...clause.fields] }
+        : { anyOf: clause.fields.map((field) => ({ required: [field] })) });
+    return {
+        if: { properties: { kind: { const: kind } }, required: ["kind"] },
+        then: clauses.length === 1 ? clauses[0] : { allOf: clauses },
+    };
+}
+export const EVIDENCE_REF_JSON_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["kind"],
+    properties: EVIDENCE_REF_FIELD_SCHEMAS,
+    allOf: EVIDENCE_REF_KINDS.map((kind) => evidenceRuleSchema(kind)),
+    examples: [
+        { kind: "artifact", file: "<project-relative-artifact-path>", summary: "<what this artifact proves>" },
+        { kind: "command", summary: "<command result and what it proves>" },
+    ],
+};
+export const WORKFLOW_EVIDENCE_PARAMETERS = [
+    { name: "status", flag: "--status", required: true, allowed_values: ["pass", "fail", "not_verified"] },
+    { name: "summary", flag: "--summary", required: true },
+    { name: "evidence_ref_json", flag: "--evidence-ref-json", required: true, repeatable: true, value_schema_ref: "#/public_interfaces/schemas/evidence_ref_json" },
+    { name: "route_reason", flag: "--route-reason", required: false },
+    { name: "criterion_json", flag: "--criterion-json", required: false, repeatable: true },
+    { name: "accepted_gap_reason", flag: "--accepted-gap-reason", required: false },
+    { name: "waived_by", flag: "--waived-by", required: false },
+    { name: "command", flag: "--command", required: false, repeatable: true },
+];
+export const WORKFLOW_CRITIQUE_PARAMETERS = [
+    { name: "id", flag: "--id", required: false },
+    { name: "verdict", flag: "--verdict", required: true, allowed_values: WORKFLOW_CRITIQUE_STATUSES },
+    { name: "summary", flag: "--summary", required: true },
+    { name: "lane_json", flag: "--lane-json", required: true, repeatable: true },
+    { name: "artifact_ref", flag: "--artifact-ref", required: false, repeatable: true, required_when: { parameter: "verdict", equals: "pass" } },
+    { name: "finding_json", flag: "--finding-json", required: false, repeatable: true },
+    { name: "timestamp", flag: "--timestamp", required: false },
+];
 export const PUBLISH_CHANGE_OPERATION = "publish-change";
 export const PUBLISH_CHANGE_OPERATION_PROTOCOL = {
     schema_version: "1.0",
@@ -31,7 +91,34 @@ export const PUBLISH_CHANGE_OPERATION_PROTOCOL = {
         completion_verification: "authenticated_change_provider_required",
     },
 };
+export const NARRATIVE_PROMOTE_OPERATION = "narrative.promote";
+export const NARRATIVE_PROMOTE_OPERATION_PROTOCOL = {
+    schema_version: "1.0",
+    operation: NARRATIVE_PROMOTE_OPERATION,
+    kind: "provider_capability",
+    capability: NARRATIVE_PROMOTE_OPERATION,
+    parameters: [
+        { name: "narrative_id", required: true, type: "string", max_length: 255 },
+        { name: "envelope_sha256", required: true, type: "string", pattern: "^[a-f0-9]{64}$" },
+    ],
+    result: {
+        required: ["provider", "completion_id", "evidence"],
+        properties: {
+            provider: { type: "string", max_length: 128 },
+            completion_id: { type: "string", max_length: 1_024 },
+            evidence: { type: "object" },
+        },
+        persist_as: "evidence",
+    },
+    availability: {
+        status: "external_capability_required",
+        executable_by_flow_agents: false,
+        direct_write_allowed: false,
+        completion_verification: "authenticated_narrative_provider_required",
+    },
+};
 export const PUBLIC_OPERATION_CONTRACTS = {
     [PUBLISH_CHANGE_OPERATION]: PUBLISH_CHANGE_OPERATION_PROTOCOL,
+    [NARRATIVE_PROMOTE_OPERATION]: NARRATIVE_PROMOTE_OPERATION_PROTOCOL,
 };
 export const PUBLIC_OPERATION_IDS = new Set(Object.keys(PUBLIC_OPERATION_CONTRACTS));