@kontourai/flow-agents 3.12.1 → 4.0.0

package/build/src/cli/workflow.js

@@ -73,7 +73,7 @@ export async function main(argv) {
 }
 async function drive(sessionDir, argv, json) {
     const parsed = parseArgs(argv);
-    assertOnlyFlags(parsed.flags, new Set(["artifact-root", "session-dir", "json", "adapter-command-file", "evidence-signing-key-file", "max-turns", "turn-timeout-ms", "barrier-wait-ms", "barrier-poll-ms"]), "workflow drive");
+    assertOnlyFlags(parsed.flags, new Set(["artifact-root", "session-dir", "json", "adapter-command-file", "evidence-signing-key-file", "max-turns", "turn-timeout-ms", "barrier-wait-ms", "barrier-poll-ms", "context-policy"]), "workflow drive");
     const adapterCommandFile = flagString(parsed.flags, "adapter-command-file");
     if (!adapterCommandFile)
         throw new Error("workflow drive requires --adapter-command-file <path>");
@@ -84,6 +84,7 @@ async function drive(sessionDir, argv, json) {
     const turnTimeoutMs = integerFlag(parsed.flags, "turn-timeout-ms", 900_000, 1, 86_400_000);
     const barrierWaitMs = integerFlag(parsed.flags, "barrier-wait-ms", 300_000, 0, 86_400_000);
     const barrierPollMs = integerFlag(parsed.flags, "barrier-poll-ms", 1_000, 1, 60_000);
+    const contextPolicy = enumFlag(parsed.flags, "context-policy", ["warm", "fresh"], "warm");
     const { slug, projectRoot } = readBoundSession(sessionDir);
     assertOrdinaryMatchingAssignmentActor(sessionDir, slug);
     const adapterCommand = loadContinuationAdapterCommand(adapterCommandFile);
@@ -98,6 +99,7 @@ async function drive(sessionDir, argv, json) {
             store: continuationStore,
             maxTurns,
             adapterCommandIdentity: adapterCommand.identity,
+            contextPolicy,
             authorizeTurn: async () => { assertOrdinaryMatchingAssignmentActor(sessionDir, slug); },
             issueTurnAuthority: async (request) => {
                 const currentAssignment = assertOrdinaryMatchingAssignmentActor(sessionDir, slug);
@@ -815,6 +817,14 @@ function integerFlag(flags, name, fallback, min, max) {
         throw new Error(`workflow drive --${name} must be an integer from ${min} through ${max}`);
     return value;
 }
+function enumFlag(flags, name, allowed, fallback) {
+    const raw = flagString(flags, name);
+    if (raw === undefined)
+        return fallback;
+    if (!allowed.includes(raw))
+        throw new Error(`workflow drive --${name} must be one of: ${allowed.join(", ")}`);
+    return raw;
+}
 function isWithin(candidate, root) {
     const relative = path.relative(root, candidate);
     return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));

package/build/src/cli.js

@@ -11,12 +11,15 @@ import { main as init } from "./cli/init.js";
 import { main as promoteWorkflowArtifact } from "./cli/promote-workflow-artifact.js";
 import { main as publishChange } from "./cli/publish-change-helper.js";
 import { main as pullWorkProvider } from "./cli/pull-work-provider.js";
+import { main as narrativeRender } from "./cli/narrative-render.js";
+import { main as narrativeSources } from "./cli/narrative-sources.js";
 import { main as telemetryDoctor } from "./cli/telemetry-doctor.js";
 import { main as usageFeedback } from "./cli/usage-feedback.js";
 import { main as veritasGovernance } from "./cli/veritas-governance.js";
 import { main as workflowArtifactCleanupAudit } from "./cli/workflow-artifact-cleanup-audit.js";
 import { main as workflow } from "./cli/workflow.js";
 import { main as buildBundles } from "./tools/build-universal-bundles.js";
+import { main as capabilityMatrix } from "./tools/generate-capability-matrix.js";
 import { main as contextMap } from "./tools/generate-context-map.js";
 import { main as validateSource } from "./tools/validate-source-tree.js";
 import { main as validatePackage } from "./tools/validate-package.js";
@@ -28,6 +31,7 @@ import { main as verify } from "./cli/verify.js";
 const availableCommands = new Map([
     ["build-bundles", () => buildBundles()],
     ["builder-run", builderRun],
+    ["capability-matrix", capabilityMatrix],
     ["console-learning-projection", consoleLearningProjection],
     ["context-map", contextMap],
     ["assignment-provider", assignmentProvider],
@@ -35,6 +39,8 @@ const availableCommands = new Map([
     ["effective-backlog-settings", effectiveBacklogSettings],
     ["fixture-retirement-audit", fixtureRetirementAudit],
     ["kit", kit],
+    ["narrative-render", narrativeRender],
+    ["narrative-sources", narrativeSources],
     ["init", init],
     ["promote-workflow-artifact", promoteWorkflowArtifact],
     ["publish-change", publishChange],
@@ -54,6 +60,7 @@ const availableCommands = new Map([
 ]);
 const aliases = new Map([
     ["flow-agents-build-bundles", "build-bundles"],
+    ["flow-agents-capability-matrix", "capability-matrix"],
     ["flow-agents-console-learning-projection", "console-learning-projection"],
     ["flow-agents-context-map", "context-map"],
     ["flow-agents-assignment-provider", "assignment-provider"],
@@ -61,6 +68,7 @@ const aliases = new Map([
     ["flow-agents-effective-backlog-settings", "effective-backlog-settings"],
     ["flow-agents-fixture-retirement-audit", "fixture-retirement-audit"],
     ["flow-agents-kit", "kit"],
+    ["flow-agents-narrative-render", "narrative-render"],
     ["flow-agents-promote-workflow-artifact", "promote-workflow-artifact"],
     ["flow-agents-publish-change", "publish-change"],
     ["flow-agents-pull-work-provider", "pull-work-provider"],

package/build/src/continuation-driver.d.ts

@@ -30,6 +30,14 @@ export type ContinuationTurnRequest = {
     next_action: Record<string, unknown> | null;
     /** Additive schema-1.0 field; older external adapters remain valid. */
     gate_action_envelope?: GateActionEnvelope;
+    /** Product-owned context routing; adapters must not infer this from model names. */
+    context_strategy?: ContinuationContextStrategy;
+};
+export type ContinuationContextPolicy = "warm" | "fresh";
+export type ContinuationContextStrategy = {
+    thread: "new" | "resume";
+    handoff: "canonical";
+    reason: "mission_start" | "configured_policy";
 };
 export type ContinuationTurnResult = {
     status: "completed";
@@ -50,6 +58,8 @@ export type ContinuationDriverState = {
     definition_id: string;
     max_turns: number;
     adapter_command_identity: string | null;
+    /** Additive to schema 1.0. Missing legacy values mean warm. */
+    context_policy?: ContinuationContextPolicy;
     status: "active" | "waiting" | "done" | "failed" | "budget_exhausted";
     turns_started: number;
     active_turn_step?: string | null;
@@ -130,6 +140,7 @@ export type ContinuationDriverOutcome = {
 export interface RunContinuationDriverInput {
     maxTurns: number;
     adapterCommandIdentity?: string;
+    contextPolicy?: ContinuationContextPolicy;
     runtime: ContinuationRuntimePort;
     store: ContinuationStateStore;
     waitForBarrier?: (barrier: ContinuationBarrier) => Promise<"ready" | "pending">;
@@ -143,6 +154,7 @@ export interface DriveBuilderFlowSessionInput {
     sessionDir: string;
     maxTurns: number;
     adapterCommandIdentity?: string;
+    contextPolicy?: ContinuationContextPolicy;
     execute: ContinuationRuntimePort["execute"];
     waitForBarrier?: RunContinuationDriverInput["waitForBarrier"];
     authorizeTurn?: RunContinuationDriverInput["authorizeTurn"];

package/build/src/continuation-driver.js

@@ -16,12 +16,15 @@ export async function runContinuationDriver(input) {
     assertMaxTurns(input.maxTurns);
     const now = input.now ?? (() => new Date());
     const adapterCommandIdentity = input.adapterCommandIdentity ?? null;
+    const contextPolicy = input.contextPolicy ?? "warm";
     const inspected = validateSnapshot(await input.runtime.inspect());
-    let state = loadOrCreateState(input.store, inspected, input.maxTurns, adapterCommandIdentity, now);
+    let state = loadOrCreateState(input.store, inspected, input.maxTurns, adapterCommandIdentity, contextPolicy, now);
     if (state.max_turns !== input.maxTurns)
         throw new Error(`continuation maxTurns ${input.maxTurns} does not match the persisted mission budget ${state.max_turns}`);
     if (state.adapter_command_identity !== adapterCommandIdentity)
         throw new Error("continuation adapter command identity does not match the persisted mission adapter");
+    if ((state.context_policy ?? "warm") !== contextPolicy)
+        throw new Error("continuation context policy does not match the persisted mission policy");
     let settled = await settleMissionStart(input, state, now);
     if (settled.outcome)
         return settled.outcome;
@@ -115,8 +118,17 @@ function continuationTurnRequest(input, state, snapshot) {
         max_turns: input.maxTurns,
         next_action: snapshot.next_action ? structuredClone(snapshot.next_action) : null,
         ...(envelope ? { gate_action_envelope: envelope } : {}),
+        context_strategy: contextStrategy(input.contextPolicy ?? "warm", state.turns_started + 1),
     });
 }
+function contextStrategy(policy, iteration) {
+    const missionStart = iteration === 1;
+    return {
+        thread: missionStart || policy === "fresh" ? "new" : "resume",
+        handoff: "canonical",
+        reason: missionStart ? "mission_start" : "configured_policy",
+    };
+}
 function beginContinuationTurn(store, state, snapshot, iteration, now) {
     let started = saveState(store, state, {
         status: "active", turns_started: iteration, active_turn_step: snapshot.current_step,
@@ -262,6 +274,7 @@ export async function driveBuilderFlowSession(input) {
     return runContinuationDriver({
         maxTurns: input.maxTurns,
         ...(input.adapterCommandIdentity ? { adapterCommandIdentity: input.adapterCommandIdentity } : {}),
+        ...(input.contextPolicy ? { contextPolicy: input.contextPolicy } : {}),
         runtime,
         store: input.store ?? createFileContinuationStore(sessionDir),
         ...(input.waitForBarrier ? { waitForBarrier: input.waitForBarrier } : {}),
@@ -287,7 +300,7 @@ function builderSessionSnapshot(result) {
         ...(result.gateActionEnvelope ? { gate_action_envelope: structuredClone(result.gateActionEnvelope) } : {}),
     });
 }
-function loadOrCreateState(store, snapshot, maxTurns, adapterCommandIdentity, now) {
+function loadOrCreateState(store, snapshot, maxTurns, adapterCommandIdentity, contextPolicy, now) {
     const existing = store.load();
     if (existing) {
         validateState(existing);
@@ -300,6 +313,7 @@ function loadOrCreateState(store, snapshot, maxTurns, adapterCommandIdentity, no
         definition_id: snapshot.definition_id,
         max_turns: maxTurns,
         adapter_command_identity: adapterCommandIdentity,
+        context_policy: contextPolicy,
         status: "active",
         turns_started: 0,
         active_turn_step: null,

package/build/src/continuation-validation.js

@@ -1,4 +1,8 @@
+import { isDeepStrictEqual } from "node:util";
 import { MAX_CONTINUATION_TURNS } from "./continuation-persistence.js";
+import { installedBuilderGateActionAuthority, } from "./builder-gate-action-envelope.js";
+import { EVIDENCE_REF_JSON_SCHEMA, PUBLIC_OPERATION_CONTRACTS, WORKFLOW_CRITIQUE_PARAMETERS, WORKFLOW_EVIDENCE_PARAMETERS, } from "./cli/public-contracts.js";
+import { flowAgentsPackageVersion } from "./lib/package-version.js";
 export const MAX_CONTINUATION_ADAPTER_EVIDENCE_BYTES = 65_536;
 export const MAX_CONTINUATION_TURN_RESULT_BYTES = 74_000;
 export function validateSnapshot(value) {
@@ -12,38 +16,314 @@ export function validateSnapshot(value) {
     if (value.next_action !== null && (typeof value.next_action !== "object" || Array.isArray(value.next_action)))
         throw new Error("continuation snapshot next_action must be an object or null");
     if (value.gate_action_envelope !== undefined)
-        validateGateActionEnvelope(value.gate_action_envelope);
+        validateGateActionEnvelope(value.gate_action_envelope, value);
     if (value.progress_snapshot !== undefined)
         validateProgressSnapshot(value.progress_snapshot);
     return structuredClone(value);
 }
-function validateGateActionEnvelope(value) {
-    if (!value || typeof value !== "object" || value.schema_version !== "2.0" || !value.flow || typeof value.flow.current_step !== "string"
+function validateGateActionEnvelope(value, snapshot) {
+    if (!value || typeof value !== "object" || value.schema_version !== "3.0" || !value.flow || typeof value.flow.current_step !== "string"
         || !value.progress || !Array.isArray(value.progress.canonical_evidence) || !Array.isArray(value.progress.observed_artifacts))
         throw new Error("continuation snapshot gate-action envelope is malformed");
-    if (value.gate !== undefined)
-        validateGateRequirementBindings(value);
+    if (!hasExactKeys(value, ["schema_version", "flow", "gate", "action", "public_interfaces", "stop_condition", "progress"])) {
+        throw new Error("continuation snapshot gate-action envelope has unsupported root fields");
+    }
+    if (!value.gate || !value.action || !Array.isArray(value.action.declared_artifacts) || !Array.isArray(value.action.artifact_bindings)
+        || !value.stop_condition?.required || !Array.isArray(value.stop_condition.required.artifact_refs)
+        || !value.public_interfaces?.schemas?.evidence_ref_json)
+        throw new Error("continuation snapshot gate-action envelope is missing typed public interfaces");
+    if (!isDeepStrictEqual(value.public_interfaces.schemas.evidence_ref_json, EVIDENCE_REF_JSON_SCHEMA))
+        throw new Error("continuation snapshot gate-action evidence schema is not canonical");
+    if (!safeTaskSlug(value.flow.run_id))
+        throw new Error("continuation snapshot gate-action run id is not a safe task slug");
+    if (value.flow.run_id !== snapshot.run_id || value.flow.definition_id !== snapshot.definition_id
+        || value.flow.current_step !== snapshot.current_step || value.flow.status !== snapshot.status)
+        throw new Error("continuation snapshot gate-action identity does not match the canonical snapshot");
+    if (!value.stop_condition.scope || value.stop_condition.scope.run_id !== snapshot.run_id
+        || value.stop_condition.scope.current_step !== snapshot.current_step || value.stop_condition.scope.current_gate_only !== true
+        || !isDeepStrictEqual(value.stop_condition.scope.gate_ids, value.flow.gate_ids))
+        throw new Error("continuation snapshot gate-action scope does not match the canonical snapshot");
+    validateFixedEnvelopeShape(value);
+    if (!Array.isArray(value.action.skills) || !Array.isArray(value.action.operations) || !Array.isArray(value.action.declared_evidence)
+        || !Array.isArray(value.public_interfaces.mutations))
+        throw new Error("continuation snapshot gate-action action bindings are malformed");
+    const sessionArgument = `.kontourai/flow-agents/${value.flow.run_id}`;
+    const packageIdentity = validateStatusInterface(value, sessionArgument);
+    const authority = installedBuilderGateActionAuthority(value.flow.definition_id, value.flow.current_step, value.flow.run_id);
+    if (value.flow.definition_version !== authority.definition_version) {
+        throw new Error("continuation snapshot gate-action definition version does not match installed Builder authority");
+    }
+    if (!isDeepStrictEqual(value.stop_condition.external_capability, authority.external_capability)) {
+        throw new Error("continuation snapshot gate-action external capability does not match installed Builder authority");
+    }
+    const declaredSkillIds = value.action.skills.map((skill) => skill.id);
+    const declaredOperations = value.action.operations;
+    if (!sameUniqueStrings(declaredSkillIds) || !sameUniqueStrings(declaredOperations) || !sameUniqueStrings(value.action.declared_evidence)) {
+        throw new Error("continuation snapshot gate-action declarations contain invalid or duplicate ids");
+    }
+    for (const skill of value.action.skills) {
+        if (!skill || !hasExactKeys(skill, ["id", "package", "path", "sha256"]) || !safeIdentifier(skill.id)
+            || !authority.action.skills.some((installed) => isDeepStrictEqual(skill, installed))) {
+            throw new Error("continuation snapshot gate-action skill binding is malformed");
+        }
+    }
+    const mutationInterfaces = validateMutations(value, sessionArgument, packageIdentity);
+    if (!isDeepStrictEqual(value.public_interfaces.mutations, authority.mutations)) {
+        throw new Error("continuation snapshot gate-action mutations do not match installed Builder authority");
+    }
+    const operationMutations = new Set(value.public_interfaces.mutations.flatMap((mutation) => mutation.interface === "operation" ? [mutation.operation] : []));
+    if (declaredOperations.some((operation) => !operationMutations.has(operation))) {
+        throw new Error("continuation snapshot gate-action declared operation has no canonical mutation");
+    }
+    const declaredByRef = new Map();
+    for (const artifact of value.action.declared_artifacts) {
+        validateArtifactTarget(artifact, value.flow.run_id, declaredSkillIds, declaredOperations, operationMutations, mutationInterfaces);
+        if (declaredByRef.has(artifact.ref))
+            throw new Error("continuation snapshot gate-action artifact targets contain duplicate refs");
+        declaredByRef.set(artifact.ref, artifact);
+    }
+    const boundRefs = new Set();
+    for (const binding of value.action.artifact_bindings) {
+        if (!binding || !hasExactKeys(binding, ["target", "expectation_ids"])
+            || !Array.isArray(binding.expectation_ids) || !sameUniqueStrings(binding.expectation_ids)
+            || binding.expectation_ids.some((id) => !value.action.declared_evidence.includes(id))
+            || !binding.target || !isDeepStrictEqual(declaredByRef.get(binding.target.ref), binding.target)
+            || boundRefs.has(binding.target.ref)) {
+            throw new Error("continuation snapshot gate-action artifact binding is malformed");
+        }
+        boundRefs.add(binding.target.ref);
+    }
+    if (boundRefs.size !== declaredByRef.size || [...declaredByRef.keys()].some((ref) => !boundRefs.has(ref))) {
+        throw new Error("continuation snapshot gate-action artifact bindings are incomplete");
+    }
+    for (const artifact of value.stop_condition.required.artifact_refs) {
+        validateArtifactTarget(artifact, value.flow.run_id, declaredSkillIds, declaredOperations, operationMutations, mutationInterfaces);
+        if (!isDeepStrictEqual(declaredByRef.get(artifact.ref), artifact))
+            throw new Error("continuation snapshot gate-action required artifact is not a declared target");
+    }
+    if (!isDeepStrictEqual(value.action, authority.action) || !isDeepStrictEqual(value.flow.gate_ids, [authority.gate_id])) {
+        throw new Error("continuation snapshot gate-action action does not match installed Builder authority");
+    }
+    validateGateRequirementBindings(value, authority);
     if (Buffer.byteLength(JSON.stringify(value), "utf8") > 65_536)
         throw new Error("continuation snapshot gate-action envelope exceeds 65536 bytes");
 }
-function validateGateRequirementBindings(value) {
+function validateArtifactTarget(artifact, runId, declaredSkillIds, declaredOperations, operationMutations, mutationInterfaces) {
+    if (!artifact || typeof artifact !== "object")
+        throw new Error("continuation snapshot gate-action artifact target is malformed");
+    if (artifact.kind === "file") {
+        const prefix = `.kontourai/flow-agents/${runId}/`;
+        const resolvedRef = typeof artifact.ref === "string" ? artifact.ref.replaceAll("<slug>", runId) : "";
+        if (!hasExactKeys(artifact, ["kind", "ref", "path", "direct_write_allowed", "produced_via"])
+            || typeof artifact.ref !== "string" || artifact.ref.length === 0 || artifact.ref.includes("#") || resolvedRef.includes("<") || resolvedRef.includes(">")
+            || resolvedRef.includes("\\") || resolvedRef.includes("\0") || resolvedRef.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
+            || forbiddenFileTarget(resolvedRef) || artifact.path !== `${prefix}${resolvedRef}`
+            || !artifact.produced_via || (artifact.direct_write_allowed === true
+            ? artifact.produced_via.interface !== "skill" || !hasExactKeys(artifact.produced_via, ["interface", "skill_ids"])
+                || !safeDeclaredSubset(artifact.produced_via.skill_ids, declaredSkillIds)
+            : artifact.direct_write_allowed === false
+                ? artifact.produced_via.interface !== "operation" || !hasExactKeys(artifact.produced_via, ["interface", "operations"])
+                    || !safeDeclaredSubset(artifact.produced_via.operations, declaredOperations)
+                    || artifact.produced_via.operations.some((operation) => !operationMutations.has(operation))
+                : true))
+            throw new Error("continuation snapshot gate-action file target is malformed");
+    }
+    else if (artifact.kind === "trust_slice") {
+        if (!hasExactKeys(artifact, ["kind", "ref", "bundle_file", "slice_id", "direct_write_allowed", "record_via"])
+            || artifact.bundle_file !== "trust.bundle" || !/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/.test(artifact.slice_id)
+            || artifact.ref !== `trust.bundle#${artifact.slice_id}` || artifact.direct_write_allowed !== false
+            || !Array.isArray(artifact.record_via) || artifact.record_via.length === 0 || new Set(artifact.record_via).size !== artifact.record_via.length
+            || artifact.record_via.some((entry) => (entry !== "workflow.evidence" && entry !== "workflow.critique") || !mutationInterfaces.has(entry)))
+            throw new Error("continuation snapshot gate-action trust slice is malformed");
+    }
+    else {
+        throw new Error("continuation snapshot gate-action artifact target kind is invalid");
+    }
+}
+function safeDeclaredSubset(value, declared) {
+    const allowed = new Set(declared);
+    return Array.isArray(value) && value.length > 0 && new Set(value).size === value.length
+        && value.every((entry) => typeof entry === "string" && safeIdentifier(entry) && allowed.has(entry));
+}
+function validateStatusInterface(value, sessionArgument) {
+    const status = value.public_interfaces.status;
+    if (!status || !hasExactKeys(status, ["package", "command", "argv"]) || status.command !== "flow-agents" || !isPackageIdentity(status.package)
+        || status.package.version !== flowAgentsPackageVersion()
+        || !isDeepStrictEqual(status.argv, ["workflow", "status", "--session-dir", sessionArgument, "--json"])) {
+        throw new Error("continuation snapshot gate-action status interface is not canonical");
+    }
+    return status.package;
+}
+function validateMutations(value, sessionArgument, packageIdentity) {
+    const expectationIds = [];
+    const interfaces = new Set();
+    for (const mutation of value.public_interfaces.mutations) {
+        if (!mutation || !safeIdentifier(mutation.expectation_id))
+            throw new Error("continuation snapshot gate-action mutation expectation is malformed");
+        expectationIds.push(mutation.expectation_id);
+        interfaces.add(mutation.interface);
+        if (mutation.interface === "workflow.evidence") {
+            if (!hasExactKeys(mutation, ["expectation_id", "interface", "package", "command", "argv", "parameters"])
+                || !isDeepStrictEqual(mutation.package, packageIdentity) || mutation.command !== "flow-agents"
+                || !isDeepStrictEqual(mutation.argv, ["workflow", "evidence", "--session-dir", sessionArgument, "--expectation", mutation.expectation_id, "--json"])
+                || !isDeepStrictEqual(mutation.parameters, WORKFLOW_EVIDENCE_PARAMETERS)) {
+                throw new Error("continuation snapshot gate-action evidence mutation is not canonical");
+            }
+        }
+        else if (mutation.interface === "workflow.critique") {
+            if (!hasExactKeys(mutation, ["expectation_id", "interface", "package", "command", "argv", "parameters"])
+                || !isDeepStrictEqual(mutation.package, packageIdentity) || mutation.command !== "flow-agents"
+                || !isDeepStrictEqual(mutation.argv, ["workflow", "critique", "--session-dir", sessionArgument, "--json"])
+                || !isDeepStrictEqual(mutation.parameters, WORKFLOW_CRITIQUE_PARAMETERS)) {
+                throw new Error("continuation snapshot gate-action critique mutation is not canonical");
+            }
+        }
+        else if (mutation.interface === "operation") {
+            const expected = PUBLIC_OPERATION_CONTRACTS[mutation.operation];
+            if (!hasExactKeys(mutation, ["expectation_id", "interface", "operation", "protocol", "completion"])
+                || !expected || !value.action.operations.includes(mutation.operation) || !isDeepStrictEqual(mutation.protocol, expected)
+                || !isDeepStrictEqual(mutation.completion, { status: "external_verification_required", executable_by_flow_agents: false, gate_evidence_interface: null })) {
+                throw new Error("continuation snapshot gate-action operation mutation is not canonical");
+            }
+        }
+        else {
+            throw new Error("continuation snapshot gate-action mutation interface is invalid");
+        }
+    }
+    if (!sameSet(expectationIds, value.action.declared_evidence)) {
+        throw new Error("continuation snapshot gate-action mutations do not match declared evidence");
+    }
+    return interfaces;
+}
+function isPackageIdentity(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value)
+        && hasExactKeys(value, ["name", "version"])
+        && value.name === "@kontourai/flow-agents"
+        && typeof value.version === "string"
+        && /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(value.version);
+}
+function safeTaskSlug(value) {
+    return value.length <= 128 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+}
+function safeIdentifier(value) {
+    return /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/.test(value);
+}
+function sameUniqueStrings(value) {
+    return Array.isArray(value) && new Set(value).size === value.length && value.every((entry) => typeof entry === "string" && safeIdentifier(entry));
+}
+function sameSet(left, right) {
+    return left.length === right.length && new Set(left).size === left.length && left.every((entry) => right.includes(entry));
+}
+function forbiddenFileTarget(ref) {
+    const segments = ref.split("/");
+    return ref === "state.json" || ref === "trust.bundle"
+        || segments.some((segment) => segment.startsWith(".") || segment === "continuation-driver");
+}
+function hasExactKeys(value, expected) {
+    const keys = Object.keys(value).sort();
+    return isDeepStrictEqual(keys, [...expected].sort());
+}
+function validateFixedEnvelopeShape(value) {
+    if (!hasExactKeys(value.flow, ["run_id", "definition_id", "definition_version", "status", "current_step", "gate_ids"])
+        || typeof value.flow.definition_version !== "string" || value.flow.definition_version.length === 0
+        || !Array.isArray(value.flow.gate_ids) || !sameUniqueGateIds(value.flow.gate_ids)) {
+        throw new Error("continuation snapshot gate-action flow binding is malformed");
+    }
+    if (!hasExactKeys(value.gate, ["requirements", "unresolved_requirement_ids", "accepted_exceptions"])
+        || !Array.isArray(value.gate.requirements) || !Array.isArray(value.gate.unresolved_requirement_ids)
+        || !Array.isArray(value.gate.accepted_exceptions)) {
+        throw new Error("continuation snapshot gate-action gate binding is malformed");
+    }
+    if (!hasExactKeys(value.action, ["skills", "operations", "declared_artifacts", "artifact_bindings", "declared_evidence", "implementation_allowed"])
+        || typeof value.action.implementation_allowed !== "boolean") {
+        throw new Error("continuation snapshot gate-action action policy is malformed");
+    }
+    if (!hasExactKeys(value.public_interfaces, ["status", "schemas", "mutations"])
+        || !hasExactKeys(value.public_interfaces.schemas, ["evidence_ref_json"])) {
+        throw new Error("continuation snapshot gate-action public interfaces are malformed");
+    }
+    if (!hasExactKeys(value.stop_condition.scope, ["run_id", "current_step", "gate_ids", "current_gate_only"])) {
+        throw new Error("continuation snapshot gate-action stop scope is malformed");
+    }
+    const required = value.stop_condition.required;
+    if (!hasExactKeys(required, ["skill_ids", "artifact_refs", "unresolved_evidence_ids"])
+        || value.stop_condition.kind !== "one_turn" || value.stop_condition.after !== "return_adapter_result"
+        || value.stop_condition.synchronize_canonical_flow !== true || value.stop_condition.adapter_evidence_is_gate_evidence !== false
+        || !isDeepStrictEqual(value.stop_condition.sequence, ["activate_required_skills", "produce_declared_artifacts", "record_bound_evidence", "synchronize_canonical_flow", "return_adapter_result"])
+        || !Array.isArray(required.skill_ids) || !Array.isArray(required.unresolved_evidence_ids)) {
+        throw new Error("continuation snapshot gate-action stop condition is malformed");
+    }
+    const allowedStopKeys = ["kind", "scope", "required", "sequence", "after", "synchronize_canonical_flow", "adapter_evidence_is_gate_evidence"];
+    if (value.stop_condition.external_capability !== undefined)
+        allowedStopKeys.push("external_capability");
+    if (!hasExactKeys(value.stop_condition, allowedStopKeys))
+        throw new Error("continuation snapshot gate-action stop condition is malformed");
+    if (value.stop_condition.external_capability !== undefined) {
+        const capability = value.stop_condition.external_capability;
+        const protocol = PUBLIC_OPERATION_CONTRACTS[capability.operation];
+        if (!hasExactKeys(capability, ["status", "operation", "capability", "completion"])
+            || capability.status !== "waiting" || capability.completion !== "external_verification_required"
+            || !protocol || !value.action.operations.includes(capability.operation) || capability.capability !== protocol.capability) {
+            throw new Error("continuation snapshot gate-action external capability is malformed");
+        }
+    }
+    const progressKeys = ["canonical_evidence", "observed_artifacts"];
+    if (value.progress.prior_turn !== undefined)
+        progressKeys.push("prior_turn");
+    if (!hasExactKeys(value.progress, progressKeys)
+        || !value.progress.canonical_evidence.every((entry) => typeof entry === "string")
+        || !value.progress.observed_artifacts.every((entry) => typeof entry === "string")) {
+        throw new Error("continuation snapshot gate-action progress is malformed");
+    }
+    if (value.progress.prior_turn !== undefined)
+        validatePriorProgress(value.progress.prior_turn);
+}
+function sameUniqueGateIds(value) {
+    return Array.isArray(value) && new Set(value).size === value.length && value.every((entry) => typeof entry === "string"
+        && entry.split(":").every((part) => safeIdentifier(part)));
+}
+function validateGateRequirementBindings(value, authority) {
     if (!Array.isArray(value.flow.gate_ids) || !Array.isArray(value.gate.requirements) || !Array.isArray(value.gate.accepted_exceptions)) {
         throw new Error("continuation snapshot gate-action envelope has malformed gate bindings");
     }
     const activeGates = new Set(value.flow.gate_ids);
+    const requirementIds = [];
+    const unresolvedIds = [];
+    const unresolvedRequiredIds = [];
     const acceptedGates = new Set();
     for (const exception of value.gate.accepted_exceptions) {
-        if (!exception || typeof exception.gate_id !== "string" || typeof exception.exception_id !== "string"
+        if (!exception || !hasExactKeys(exception, ["gate_id", "exception_id"])
+            || typeof exception.gate_id !== "string" || typeof exception.exception_id !== "string" || exception.exception_id.length === 0
             || !activeGates.has(exception.gate_id) || acceptedGates.has(exception.gate_id)) {
             throw new Error("continuation snapshot gate-action envelope has invalid accepted exceptions");
         }
         acceptedGates.add(exception.gate_id);
     }
     const gatesWithRequirements = new Set();
+    const authorityRequirements = new Map(authority.requirements.map((requirement) => [requirement.id, requirement]));
     for (const requirement of value.gate.requirements) {
-        if (!requirement || typeof requirement.gate_id !== "string" || !activeGates.has(requirement.gate_id)) {
+        if (!requirement || !hasExactKeys(requirement, ["id", "gate_id", "required", "description", "claim_type", "subject_type", "status"])
+            || !safeIdentifier(requirement.id) || typeof requirement.gate_id !== "string" || !activeGates.has(requirement.gate_id)
+            || typeof requirement.required !== "boolean" || typeof requirement.description !== "string" || requirement.description.length === 0
+            || typeof requirement.claim_type !== "string" || requirement.claim_type.length === 0
+            || (requirement.subject_type !== null && (typeof requirement.subject_type !== "string" || requirement.subject_type.length === 0))
+            || !new Set(["satisfied", "accepted_exception", "unresolved"]).has(requirement.status)) {
             throw new Error("continuation snapshot gate-action envelope has an invalid requirement gate binding");
         }
+        const { status: _status, required: _required, ...shape } = requirement;
+        const authoritative = authorityRequirements.get(requirement.id);
+        if (!authoritative)
+            throw new Error("continuation snapshot gate-action requirement does not match installed Flow authority");
+        const { required: _authoritativeRequired, ...authoritativeShape } = authoritative;
+        if (!isDeepStrictEqual(shape, authoritativeShape)) {
+            throw new Error("continuation snapshot gate-action requirement does not match installed Flow authority");
+        }
+        requirementIds.push(requirement.id);
+        if (requirement.status === "unresolved") {
+            unresolvedIds.push(requirement.id);
+            if (requirement.required)
+                unresolvedRequiredIds.push(requirement.id);
+        }
         gatesWithRequirements.add(requirement.gate_id);
         if ((requirement.status === "accepted_exception") !== acceptedGates.has(requirement.gate_id)
             && requirement.status !== "satisfied") {
@@ -53,6 +333,28 @@ function validateGateRequirementBindings(value) {
     if ([...acceptedGates].some((gateId) => !gatesWithRequirements.has(gateId))) {
         throw new Error("continuation snapshot gate-action envelope exception has no bound requirements");
     }
+    if (!sameUniqueStrings(requirementIds) || !sameSet(requirementIds, value.action.declared_evidence)
+        || !sameSet(unresolvedIds, value.gate.unresolved_requirement_ids)
+        || !sameSet(unresolvedRequiredIds, value.stop_condition.required.unresolved_evidence_ids)) {
+        throw new Error("continuation snapshot gate-action requirement projections are inconsistent");
+    }
+    const expectedSkillIds = unresolvedRequiredIds.length > 0 ? value.action.skills.map((skill) => skill.id) : [];
+    if (!sameSet(expectedSkillIds, value.stop_condition.required.skill_ids)) {
+        throw new Error("continuation snapshot gate-action required skills are inconsistent");
+    }
+    const unresolvedRequired = new Set(unresolvedRequiredIds);
+    const expectedArtifacts = value.action.artifact_bindings
+        .filter((binding) => binding.expectation_ids.some((id) => unresolvedRequired.has(id)))
+        .map((binding) => binding.target);
+    if (!sameArtifactTargets(expectedArtifacts, value.stop_condition.required.artifact_refs)) {
+        throw new Error("continuation snapshot gate-action required artifacts are inconsistent");
+    }
+}
+function sameArtifactTargets(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const rightByRef = new Map(right.map((target) => [target.ref, target]));
+    return rightByRef.size === right.length && left.every((target) => isDeepStrictEqual(target, rightByRef.get(target.ref)));
 }
 export function validateTurnResult(value) {
     if (!value || typeof value !== "object" || (value.status !== "completed" && value.status !== "wait"))
@@ -112,6 +414,8 @@ export function validateState(state) {
     assertMaxTurns(state.max_turns);
     if (state.adapter_command_identity !== null && (typeof state.adapter_command_identity !== "string" || state.adapter_command_identity.length === 0))
         throw new Error("continuation driver adapter_command_identity must be a non-empty string or null");
+    if (state.context_policy !== undefined && !new Set(["warm", "fresh"]).has(state.context_policy))
+        throw new Error("continuation driver context_policy must be warm or fresh");
     if (!Number.isSafeInteger(state.turns_started) || state.turns_started < 0 || state.turns_started > state.max_turns)
         throw new Error("continuation driver turns_started is outside its mission budget");
     if (state.active_turn_step !== undefined && state.active_turn_step !== null && (typeof state.active_turn_step !== "string" || state.active_turn_step.length === 0))
@@ -142,9 +446,21 @@ function validateAcceptedTurn(value) {
         || value.iteration < 1 || value.request?.iteration !== value.iteration || typeof value.captured_at !== "string" || !Number.isFinite(Date.parse(value.captured_at)))
         throw new Error("continuation accepted-turn capture is malformed");
     validateTurnResult(value.result);
+    if (value.request.context_strategy !== undefined)
+        validateContextStrategy(value.request.context_strategy);
     if (value.progress !== null)
         validatePriorProgress(value.progress);
 }
+function validateContextStrategy(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("continuation context strategy is malformed");
+    const strategy = value;
+    if (strategy.handoff !== "canonical" || !new Set(["new", "resume"]).has(String(strategy.thread))
+        || !new Set(["mission_start", "configured_policy"]).has(String(strategy.reason))
+        || Object.keys(strategy).some((key) => !new Set(["thread", "handoff", "reason"]).has(key))) {
+        throw new Error("continuation context strategy is malformed");
+    }
+}
 function validateProgressSnapshot(value) {
     if (!value || typeof value !== "object" || typeof value.current_step !== "string" || value.current_step.length === 0
         || (value.canonical_status !== undefined && (typeof value.canonical_status !== "string" || value.canonical_status.length === 0))

package/build/src/flow-kit/action-metadata.js

@@ -68,7 +68,9 @@ function parseFlowStepActionEntry(raw, manifestPath, index, errors) {
         return null;
     }
     const artifactBindings = parseArtifactBindings(record.artifact_bindings ?? [], lists.artifacts, lists.expectation_ids, manifestPath, index, errors);
-    return artifactBindings ? { flow_id: record.flow_id, step_id: record.step_id, ...lists, implementation_allowed: record.implementation_allowed, expectation_bindings: expectationBindings, artifact_bindings: artifactBindings } : null;
+    if (!artifactBindings || !validateArtifactProducers(artifactBindings, expectationBindings, lists.skills, manifestPath, index, errors))
+        return null;
+    return { flow_id: record.flow_id, step_id: record.step_id, ...lists, implementation_allowed: record.implementation_allowed, expectation_bindings: expectationBindings, artifact_bindings: artifactBindings };
 }
 function parseFlowStepActionLists(record, manifestPath, index, errors) {
     const skills = record.skills;
@@ -142,12 +144,30 @@ function parseArtifactBindings(value, artifacts, expectationIds, manifestPath, a
         if (Object.keys(record).some((key) => key !== "artifact" && key !== "expectation_ids") || typeof record.artifact !== "string" || !artifacts.includes(record.artifact)
             || !Array.isArray(record.expectation_ids) || !record.expectation_ids.every((id) => typeof id === "string" && expectationIds.includes(id)) || new Set(record.expectation_ids).size !== record.expectation_ids.length)
             return fail(errors, `${manifestPath}: flow_step_actions[${actionIndex}].artifact_bindings[${bindingIndex}] must bind one declared artifact to declared expectation_ids`);
+        if (record.artifact.startsWith("trust.bundle#") && record.expectation_ids.length === 0)
+            return fail(errors, `${manifestPath}: flow_step_actions[${actionIndex}].artifact_bindings[${bindingIndex}] trust slice must own at least one expectation to derive its recording interface`);
         bindings.push({ artifact: record.artifact, expectation_ids: record.expectation_ids });
     }
     if (!sameStringSet(bindings.map((binding) => binding.artifact), artifacts))
         return fail(errors, `${manifestPath}: flow_step_actions[${actionIndex}].artifact_bindings must bind every artifact exactly once`);
     return bindings;
 }
+function validateArtifactProducers(bindings, expectationBindings, skills, manifestPath, actionIndex, errors) {
+    const expectationById = new Map(expectationBindings.map((binding) => [binding.expectation_id, binding]));
+    for (const [bindingIndex, binding] of bindings.entries()) {
+        const owners = binding.expectation_ids.map((id) => expectationById.get(id));
+        const operationOwners = owners.filter((owner) => owner.interface === "operation");
+        if (binding.artifact.startsWith("trust.bundle#") && operationOwners.length > 0) {
+            errors.push(`${manifestPath}: flow_step_actions[${actionIndex}].artifact_bindings[${bindingIndex}] trust slice cannot own an operation expectation`);
+            return false;
+        }
+        if (!binding.artifact.includes("#") && operationOwners.length === 0 && skills.length === 0) {
+            errors.push(`${manifestPath}: flow_step_actions[${actionIndex}].artifact_bindings[${bindingIndex}] file has no skill or operation producer`);
+            return false;
+        }
+    }
+    return true;
+}
 export function isSafeBuilderArtifactRef(value) {
     if (typeof value !== "string" || value.length === 0 || value.includes("\0") || value.includes("\\"))
         return false;