@kontourai/flow-agents 3.12.0 → 4.0.0

package/src/builder-flow-runtime.ts

@@ -16,7 +16,7 @@ import {
   type FlowRunState,
   type JsonObject,
 } from "@kontourai/flow";
-import { assertAuthorizationUnused, loadBuilderLifecycleAuthorization, readAuthorizationConsumption, recordAuthorizationConsumed } from "./builder-lifecycle-authority.js";
+import { assertAuthorizationUnused, buildUnsignedLifecycleAuthorization, loadBuilderLifecycleAuthorization, readAuthorizationConsumption, recordAuthorizationConsumed, type BuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
 import { assignmentFilePath, performLocalReleaseUnderLock, readLocalAssignmentStatus, resolveCurrentAssignmentActor, withSubjectLock, type ActorStruct } from "./cli/assignment-provider.js";
 import {
   BUILDER_BUILD_FLOW_ID,
@@ -199,6 +199,107 @@ export async function cancelBuilderFlowSession(input: BuilderFlowAuthorizedLifec
   });
 }
 
+export interface BuilderCancelRequestInput extends BuilderFlowSessionInput {
+  /** Free-text reason recorded in the authorization request. */
+  reason?: string;
+  /** Human/operator identity recorded as request.authority.actor. */
+  requestActor?: string;
+  /** Validity window for the emitted authorization (default 24h). */
+  expiresInHours?: number;
+  /** Override the request timestamp (tests); defaults to now. */
+  now?: string;
+  /** Override the nonce (tests); defaults to a fresh unique value. */
+  nonce?: string;
+}
+
+export interface BuilderCancelRequestResult {
+  runId: string;
+  subject: string;
+  runStatus: string;
+  /** True when the run is already terminal (cancel would be idempotent/no-op). */
+  alreadyTerminal: boolean;
+  /** The unsigned, ready-to-sign authorization (schema-valid, canonical order). */
+  authorization: Omit<BuilderLifecycleAuthorization, "signature">;
+  /** The exact bytes the operator must sign; a signature over these verifies. */
+  signingPayload: string;
+  /** Where the CLI writes the unsigned authorization by default. */
+  suggestedOutFile: string;
+}
+
+/**
+ * Generate a ready-to-sign cancel authorization for a run (#659 Slice C).
+ *
+ * READ-ONLY: this mints the *unsigned* payload (correct run identity, active
+ * assignment holder, fresh nonce/expiry) so an operator no longer has to
+ * hand-assemble the JSON. It does NOT sign, cancel, or mutate anything — the
+ * ed25519 signature lock is fully preserved; the operator still signs
+ * `signingPayload` with their key, and `builder-run cancel --authorization-file`
+ * verifies it as before.
+ */
+export async function prepareBuilderCancelRequest(input: BuilderCancelRequestInput): Promise<BuilderCancelRequestResult> {
+  const context = resolveSessionContext(input.sessionDir);
+  const sidecarSnapshot = readSidecarSnapshot(context);
+  const subject = workflowSubject(sidecarSnapshot.state);
+  const canonicalRun = await loadBuilderFlowRun({ cwd: context.projectRoot, runId: context.slug });
+  const terminalStatuses = ["canceled", "completed", "archived"];
+  const alreadyTerminal = terminalStatuses.includes(canonicalRun.state.status);
+
+  const activeAssignment = readLocalAssignmentStatus(context.artifactRoot, context.slug).record;
+  const assignmentFile = assignmentFilePath(context.artifactRoot, context.slug);
+  const persistedAssignment = pathExistsNoFollow(assignmentFile)
+    ? JSON.parse(fs.readFileSync(assignmentFile, "utf8")) as AnyRecord
+    : null;
+  // When the run is already canceled, its assignment is released — accept the
+  // persisted holder so an operator can still mint a (recovery) authorization.
+  // Mirror prepareAuthorizedLifecycleChange's redemption gate EXACTLY so we never
+  // mint an authorization the real cancel would reject: a cancel may reuse a
+  // released assignment only when the run is already `canceled` (idempotent
+  // recovery) and the persisted record's status is `released`. A completed or
+  // archived run with no active holder is not cancel-redeemable, so refuse.
+  const acceptsReleasedAssignment = canonicalRun.state.status === "canceled";
+  const assignment = activeAssignment
+    ?? (acceptsReleasedAssignment && persistedAssignment?.status === "released" ? persistedAssignment : null);
+  if (!assignment || !assignment.actor_key || !assignment.actor) {
+    throw new BuilderBuildRunInputError("assignment", "the run has no assignment holder to authorize a cancel against");
+  }
+
+  const now = input.now ? new Date(input.now) : new Date();
+  if (!Number.isFinite(now.getTime())) throw new BuilderBuildRunInputError("now", "must be a valid date-time");
+  const requestedAt = now.toISOString();
+  const hours = input.expiresInHours && input.expiresInHours > 0 ? input.expiresInHours : 24;
+  const expiresAt = new Date(now.getTime() + hours * 3_600_000).toISOString();
+  const nonce = input.nonce ?? `cancel-request-${context.slug}-${now.getTime()}-${randomBytes(6).toString("hex")}`;
+
+  const { unsigned, signingPayload } = buildUnsignedLifecycleAuthorization({
+    operation: "cancel",
+    run_id: context.slug,
+    subject,
+    assignment_actor_key: assignment.actor_key as string,
+    assignment_actor: assignment.actor,
+    nonce,
+    expires_at: expiresAt,
+    request: {
+      reason: (input.reason && input.reason.trim()) || `Operator-requested cancellation of run ${context.slug}.`,
+      authority: {
+        kind: "user_request",
+        actor: (input.requestActor && input.requestActor.trim()) || "operator",
+        request_ref: `flow-agents://cancel-request/${context.slug}/${now.getTime()}`,
+        requested_at: requestedAt,
+      },
+    },
+  });
+
+  return {
+    runId: context.slug,
+    subject,
+    runStatus: canonicalRun.state.status,
+    alreadyTerminal,
+    authorization: unsigned,
+    signingPayload,
+    suggestedOutFile: path.join(context.sessionDir, "cancel.authorization.unsigned.json"),
+  };
+}
+
 export async function releaseBuilderFlowAssignment(input: BuilderFlowAgentLifecycleInput): Promise<BuilderFlowSessionResult & { assignmentReleased: boolean }> {
   const context = resolveSessionContext(input.sessionDir);
   return await withSubjectLock(context.artifactRoot, context.slug, async () => {

package/src/builder-gate-action-envelope.ts

@@ -4,9 +4,14 @@ import * as path from "node:path";
 import { createHash } from "node:crypto";
 import { evaluateGate, expectationsForGate, openGates, type FlowExpectation, type FlowGate, type FlowRunState } from "@kontourai/flow";
 import { parseKitFlowStepActions, type KitFlowStepActionEntry, type KitFlowStepExpectationBinding } from "./flow-kit/validate.js";
-import { PUBLIC_OPERATION_CONTRACTS, WORKFLOW_CRITIQUE_STATUSES } from "./cli/public-contracts.js";
+import {
+  EVIDENCE_REF_JSON_SCHEMA,
+  PUBLIC_OPERATION_CONTRACTS,
+  WORKFLOW_CRITIQUE_PARAMETERS,
+  WORKFLOW_EVIDENCE_PARAMETERS,
+} from "./cli/public-contracts.js";
+import { resolveEffectiveFlowDefinition } from "./lib/flow-resolver.js";
 import { flowAgentsPackageRoot } from "./lib/package-version.js";
-import { pinnedFlowAgentsCommand } from "./lib/pinned-cli-command.js";
 
 const MAX_METADATA_BYTES = 1_048_576;
 const MAX_ENVELOPE_BYTES = 65_536;
@@ -24,9 +29,39 @@ export type GateActionInterfaceParameter = {
   name: string;
   flag: string;
   required: boolean;
-  allowed_values?: string[];
+  allowed_values?: readonly string[];
   repeatable?: boolean;
   required_when?: { parameter: string; equals: string };
+  value_schema_ref?: "#/public_interfaces/schemas/evidence_ref_json";
+};
+
+export type GateActionArtifactTarget =
+  | {
+      kind: "file";
+      ref: string;
+      path: string;
+      direct_write_allowed: true;
+      produced_via: { interface: "skill"; skill_ids: string[] };
+    }
+  | {
+      kind: "file";
+      ref: string;
+      path: string;
+      direct_write_allowed: false;
+      produced_via: { interface: "operation"; operations: string[] };
+    }
+  | {
+      kind: "trust_slice";
+      ref: string;
+      bundle_file: "trust.bundle";
+      slice_id: string;
+      direct_write_allowed: false;
+      record_via: Array<"workflow.evidence" | "workflow.critique">;
+    };
+
+export type GateActionArtifactBinding = {
+  target: GateActionArtifactTarget;
+  expectation_ids: string[];
 };
 
 export type GateActionWorkflowMutation = {
@@ -35,7 +70,7 @@ export type GateActionWorkflowMutation = {
       package: { name: "@kontourai/flow-agents"; version: string };
       command: "flow-agents";
       argv: string[];
-      parameters: GateActionInterfaceParameter[];
+      parameters: readonly GateActionInterfaceParameter[];
     };
 
 export type GateActionPublicMutation =
@@ -53,7 +88,7 @@ export type GateActionPublicMutation =
     };
 
 export type GateActionEnvelope = {
-  schema_version: "1.0";
+  schema_version: "3.0";
   flow: {
     run_id: string;
     definition_id: string;
@@ -65,6 +100,7 @@ export type GateActionEnvelope = {
   gate: {
     requirements: Array<{
       id: string;
+      gate_id: string;
       required: boolean;
       description: string;
       claim_type: string;
@@ -83,12 +119,20 @@ export type GateActionEnvelope = {
       sha256: string;
     }>;
     operations: string[];
-    declared_artifacts: string[];
+    declared_artifacts: GateActionArtifactTarget[];
+    artifact_bindings: GateActionArtifactBinding[];
     declared_evidence: string[];
     implementation_allowed: boolean;
   };
   public_interfaces: {
-    status: { command: string };
+    status: {
+      package: { name: "@kontourai/flow-agents"; version: string };
+      command: "flow-agents";
+      argv: string[];
+    };
+    schemas: {
+      evidence_ref_json: AnyRecord;
+    };
     mutations: GateActionPublicMutation[];
   };
   stop_condition: {
@@ -101,7 +145,7 @@ export type GateActionEnvelope = {
     };
     required: {
       skill_ids: string[];
-      artifact_refs: string[];
+      artifact_refs: GateActionArtifactTarget[];
       unresolved_evidence_ids: string[];
     };
     sequence: ["activate_required_skills", "produce_declared_artifacts", "record_bound_evidence", "synchronize_canonical_flow", "return_adapter_result"];
@@ -122,6 +166,8 @@ export type GateActionEnvelope = {
   };
 };
 
+export { EVIDENCE_REF_JSON_SCHEMA } from "./cli/public-contracts.js";
+
 export type GateActionProgressSnapshot = Pick<GateActionEnvelope["progress"], "canonical_evidence" | "observed_artifacts"> & {
   current_step: string;
   /** Optional for compatibility with snapshots persisted before terminal status capture. */
@@ -168,6 +214,98 @@ type DerivedGateRequirements = {
   acceptedExceptions: GateActionEnvelope["gate"]["accepted_exceptions"];
 };
 
+export function installedBuilderSkillIdentity(skill: string): GateActionEnvelope["action"]["skills"][number] {
+  const packageRoot = flowAgentsPackageRoot();
+  const packageMetadata = readBoundedJson(packageRoot, "package.json", "flow-agents package metadata");
+  if (typeof packageMetadata.version !== "string" || !packageMetadata.version) throw new Error("flow-agents package metadata has no version");
+  const kit = readBoundedJson(packageRoot, path.join("kits", "builder", "kit.json"), "Builder kit metadata");
+  return skillIdentity(kit, packageRoot, packageMetadata.version, skill);
+}
+
+export function installedBuilderImplementationAllowed(definitionId: string, currentStep: string): boolean {
+  const packageRoot = flowAgentsPackageRoot();
+  const kit = readBoundedJson(packageRoot, path.join("kits", "builder", "kit.json"), "Builder kit metadata");
+  const parsed = parseKitFlowStepActions(kit, "kits/builder/kit.json");
+  if (parsed.errors.length) throw new Error(`Builder gate-action metadata is invalid: ${parsed.errors.join("; ")}`);
+  const selected = parsed.entries.filter((entry) => entry.flow_id === definitionId && entry.step_id === currentStep);
+  if (selected.length !== 1) throw new Error(`Builder gate-action metadata must declare exactly one action for ${definitionId}/${currentStep}`);
+  return selected[0]!.implementation_allowed;
+}
+
+export function installedBuilderGateActionAuthority(definitionId: string, currentStep: string, runId: string): {
+  definition_version: string;
+  gate_id: string;
+  requirements: Array<Omit<GateActionEnvelope["gate"]["requirements"][number], "status">>;
+  action: GateActionEnvelope["action"];
+  mutations: GateActionPublicMutation[];
+  artifact_bindings: GateActionArtifactBinding[];
+  external_capability?: NonNullable<GateActionEnvelope["stop_condition"]["external_capability"]>;
+} {
+  const packageRoot = flowAgentsPackageRoot();
+  const packageMetadata = readBoundedJson(packageRoot, "package.json", "flow-agents package metadata");
+  if (typeof packageMetadata.version !== "string" || !packageMetadata.version) throw new Error("flow-agents package metadata has no version");
+  const packageVersion = packageMetadata.version;
+  const kit = readBoundedJson(packageRoot, path.join("kits", "builder", "kit.json"), "Builder kit metadata");
+  const parsed = parseKitFlowStepActions(kit, "kits/builder/kit.json");
+  if (parsed.errors.length) throw new Error(`Builder gate-action metadata is invalid: ${parsed.errors.join("; ")}`);
+  const selected = parsed.entries.filter((entry) => entry.flow_id === definitionId && entry.step_id === currentStep);
+  if (selected.length !== 1) throw new Error(`Builder gate-action metadata must declare exactly one action for ${definitionId}/${currentStep}`);
+  const action = selected[0]!;
+  const definition = resolveEffectiveFlowDefinition(definitionId, packageRoot, { allowOverride: false });
+  if (typeof definition?.version !== "string" || definition.version.length === 0) {
+    throw new Error(`Installed Builder Flow has no version for ${definitionId}`);
+  }
+  const gates: Array<[string, AnyRecord]> = isRecord(definition?.gates) ? Object.entries(definition.gates)
+    .flatMap(([gateId, gate]) => isRecord(gate) && gate.step === currentStep ? [[gateId, gate]] : []) : [];
+  if (gates.length !== 1) throw new Error(`Installed Builder Flow must declare exactly one gate for ${definitionId}/${currentStep}`);
+  const [gateId, gate] = gates[0]!;
+  const expects = Array.isArray(gate.expects) ? gate.expects : [];
+  const requirements = expects.map((expectation) => {
+    if (!isRecord(expectation)) throw new Error("Installed Builder gate expectation is malformed");
+    const requirement = requirementFromExpectation(gateId, expectation as unknown as FlowExpectation, new Set<string>(), false);
+    const { status: _status, ...shape } = requirement;
+    return shape;
+  });
+  if (!sameSet(action.expectation_ids, requirements.map((requirement) => requirement.id))) {
+    throw new Error(`Installed Builder action evidence does not match ${definitionId}/${currentStep}`);
+  }
+  const sessionArgument = `.kontourai/flow-agents/${runId}`;
+  const declaredArtifacts = action.artifacts.filter((artifact) => !isControlArtifact(artifact))
+    .map((artifact) => artifactTarget(artifact, runId, sessionArgument, action));
+  const artifactBindings = action.artifact_bindings
+    .filter((binding) => !isControlArtifact(binding.artifact))
+    .map((binding) => ({
+      target: artifactTarget(binding.artifact, runId, sessionArgument, action),
+      expectation_ids: [...binding.expectation_ids],
+    }));
+  const operation = action.operations[0];
+  const protocol = operation ? PUBLIC_OPERATION_CONTRACTS[operation as keyof typeof PUBLIC_OPERATION_CONTRACTS] : undefined;
+  const actionEnvelope: GateActionEnvelope["action"] = {
+    skills: action.skills.map((skill) => skillIdentity(kit, packageRoot, packageVersion, skill)),
+    operations: [...action.operations],
+    declared_artifacts: declaredArtifacts,
+    artifact_bindings: artifactBindings,
+    declared_evidence: [...action.expectation_ids],
+    implementation_allowed: action.implementation_allowed,
+  };
+  return {
+    definition_version: definition.version,
+    gate_id: gateId,
+    requirements,
+    action: actionEnvelope,
+    mutations: action.expectation_bindings.map((binding) => publicMutation(binding, sessionArgument, packageVersion)),
+    artifact_bindings: artifactBindings,
+    ...(protocol?.availability.status === "external_capability_required" ? {
+      external_capability: {
+        status: "waiting" as const,
+        operation: protocol.operation,
+        capability: protocol.capability,
+        completion: "external_verification_required" as const,
+      },
+    } : {}),
+  };
+}
+
 /** Derive bounded adapter context without trusting adapter telemetry. */
 export function deriveBuilderGateActionEnvelope(input: BuilderGateActionEnvelopeInput): GateActionEnvelope {
   const loaded = loadGateAction(input);
@@ -222,7 +360,7 @@ function deriveFlowRequirements(input: BuilderGateActionEnvelopeInput, action: K
     const matched = new Set((Array.isArray(outcome.matched_expectations) ? outcome.matched_expectations : [])
       .flatMap((entry) => isRecord(entry) && typeof entry.expectation_id === "string" ? [entry.expectation_id] : []));
     return (expectationsForGate(gate, input.run.config) as FlowExpectation[])
-      .map((expectation) => requirementFromExpectation(expectation, matched, typeof outcome.accepted_exception_id === "string"));
+      .map((expectation) => requirementFromExpectation(gate.id, expectation, matched, typeof outcome.accepted_exception_id === "string"));
   });
   if (requirements.length > MAX_REQUIREMENTS) throw new Error("Builder gate-action envelope requirements exceed the supported bound");
   if (!sameSet(action.expectation_ids, requirements.map((requirement) => requirement.id))) {
@@ -238,12 +376,11 @@ function assembleGateActionEnvelope(input: BuilderGateActionEnvelopeInput, loade
   const { gates, requirements, unresolved, unresolvedRequired, acceptedExceptions } = derived;
   const sessionDir = path.resolve(input.sessionDir);
   const sessionArgument = sessionPathForPublicCommand(input.projectRoot, sessionDir);
-  const statusCommand = pinnedFlowAgentsCommand(packageVersion, ["workflow", "status", "--session-dir", sessionArgument, "--json"]);
   const requiredArtifacts = action.artifact_bindings
     .filter((binding) => !isControlArtifact(binding.artifact) && binding.expectation_ids.some((id) => unresolvedRequired.includes(id)))
-    .map((binding) => binding.artifact);
+    .map((binding) => artifactTarget(binding.artifact, sessionDir, sessionArgument, action));
   const envelope: GateActionEnvelope = {
-    schema_version: "1.0",
+    schema_version: "3.0",
     flow: {
       run_id: input.run.runId,
       definition_id: input.run.definitionId,
@@ -253,9 +390,14 @@ function assembleGateActionEnvelope(input: BuilderGateActionEnvelopeInput, loade
       gate_ids: gates.map((gate) => gate.id),
     },
     gate: { requirements, unresolved_requirement_ids: unresolved, accepted_exceptions: acceptedExceptions },
-    action: envelopeAction(action, actionableArtifacts, kit, packageRoot, packageVersion),
+    action: envelopeAction(action, actionableArtifacts, sessionDir, sessionArgument, kit, packageRoot, packageVersion),
     public_interfaces: {
-      status: { command: statusCommand },
+      status: {
+        package: { name: "@kontourai/flow-agents", version: packageVersion },
+        command: "flow-agents",
+        argv: ["workflow", "status", "--session-dir", sessionArgument, "--json"],
+      },
+      schemas: { evidence_ref_json: structuredClone(EVIDENCE_REF_JSON_SCHEMA) },
       mutations: action.expectation_bindings.map((binding) => publicMutation(binding, sessionArgument, packageVersion)),
     },
     stop_condition: envelopeStopCondition(input, gates, action, requiredArtifacts, unresolvedRequired),
@@ -267,11 +409,18 @@ function assembleGateActionEnvelope(input: BuilderGateActionEnvelopeInput, loade
   return envelope;
 }
 
-function envelopeAction(action: KitFlowStepActionEntry, artifacts: string[], kit: AnyRecord, packageRoot: string, packageVersion: string): GateActionEnvelope["action"] {
+function envelopeAction(action: KitFlowStepActionEntry, artifacts: string[], sessionDir: string, sessionArgument: string, kit: AnyRecord, packageRoot: string, packageVersion: string): GateActionEnvelope["action"] {
+  const declaredArtifacts = artifacts.map((artifact) => artifactTarget(artifact, sessionDir, sessionArgument, action));
   return {
     skills: action.skills.map((skill) => skillIdentity(kit, packageRoot, packageVersion, skill)),
     operations: [...action.operations],
-    declared_artifacts: [...artifacts],
+    declared_artifacts: declaredArtifacts,
+    artifact_bindings: action.artifact_bindings
+      .filter((binding) => !isControlArtifact(binding.artifact))
+      .map((binding) => ({
+        target: artifactTarget(binding.artifact, sessionDir, sessionArgument, action),
+        expectation_ids: [...binding.expectation_ids],
+      })),
     declared_evidence: [...action.expectation_ids],
     implementation_allowed: action.implementation_allowed,
   };
@@ -281,7 +430,7 @@ function envelopeStopCondition(
   input: BuilderGateActionEnvelopeInput,
   gates: Array<FlowGate & { id: string }>,
   action: KitFlowStepActionEntry,
-  artifactRefs: string[],
+  artifactRefs: GateActionArtifactTarget[],
   unresolvedEvidenceIds: string[],
 ): GateActionEnvelope["stop_condition"] {
   const operation = action.operations[0];
@@ -345,15 +494,7 @@ function publicMutation(binding: KitFlowStepExpectationBinding, sessionArgument:
       package: { name: "@kontourai/flow-agents", version: packageVersion },
       command: "flow-agents",
       argv: ["workflow", "critique", "--session-dir", sessionArgument, "--json"],
-      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 },
-      ],
+      parameters: structuredClone(WORKFLOW_CRITIQUE_PARAMETERS),
     };
   }
   return workflowEvidenceMutation(binding.expectation_id, sessionArgument, packageVersion);
@@ -366,20 +507,57 @@ function workflowEvidenceMutation(expectationId: string, sessionArgument: string
     package: { name: "@kontourai/flow-agents", version: packageVersion },
     command: "flow-agents",
     argv: ["workflow", "evidence", "--session-dir", sessionArgument, "--expectation", expectationId, "--json"],
-    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 },
-      { 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 },
-    ],
+    parameters: structuredClone(WORKFLOW_EVIDENCE_PARAMETERS),
+  };
+}
+
+function artifactTarget(artifact: string, sessionDir: string, sessionArgument: string, action: KitFlowStepActionEntry): GateActionArtifactTarget {
+  if (!artifact.includes("#")) {
+    const fileName = artifact.replaceAll("<slug>", path.basename(sessionDir));
+    const expectationIds = new Set(action.artifact_bindings
+      .filter((binding) => binding.artifact === artifact)
+      .flatMap((binding) => binding.expectation_ids));
+    const operations = action.expectation_bindings
+      .filter((binding) => expectationIds.has(binding.expectation_id) && binding.interface === "operation")
+      .flatMap((binding) => binding.operation ? [binding.operation] : []);
+    if (operations.length > 0) {
+      return {
+        kind: "file",
+        ref: artifact,
+        path: path.join(sessionArgument, fileName).split(path.sep).join("/"),
+        direct_write_allowed: false,
+        produced_via: { interface: "operation", operations: [...new Set(operations)] },
+      };
+    }
+    if (action.skills.length === 0) throw new Error(`Builder gate-action file '${artifact}' has no skill or operation producer`);
+    return {
+      kind: "file",
+      ref: artifact,
+      path: path.join(sessionArgument, fileName).split(path.sep).join("/"),
+      direct_write_allowed: true,
+      produced_via: { interface: "skill", skill_ids: [...action.skills] },
+    };
+  }
+  const match = /^trust\.bundle#([a-z0-9]+(?:[.-][a-z0-9]+)*)$/.exec(artifact);
+  if (!match) throw new Error(`Builder gate-action artifact '${artifact}' is not a supported trust slice`);
+  const expectationIds = new Set(action.artifact_bindings
+    .filter((binding) => binding.artifact === artifact)
+    .flatMap((binding) => binding.expectation_ids));
+  const recordVia = [...new Set(action.expectation_bindings
+    .filter((binding) => expectationIds.has(binding.expectation_id))
+    .flatMap((binding) => binding.interface === "workflow.evidence" || binding.interface === "workflow.critique" ? [binding.interface] : []))];
+  if (recordVia.length === 0) throw new Error(`Builder gate-action trust slice '${artifact}' has no public recording interface`);
+  return {
+    kind: "trust_slice",
+    ref: artifact,
+    bundle_file: "trust.bundle",
+    slice_id: match[1]!,
+    direct_write_allowed: false,
+    record_via: recordVia,
   };
 }
 
-function requirementFromExpectation(expectation: FlowExpectation, satisfied: Set<string>, acceptedException: boolean): GateActionEnvelope["gate"]["requirements"][number] {
+function requirementFromExpectation(gateId: string, expectation: FlowExpectation, satisfied: Set<string>, acceptedException: boolean): GateActionEnvelope["gate"]["requirements"][number] {
   const record = expectation as unknown as AnyRecord;
   const claim = isRecord(record.bundle_claim) ? record.bundle_claim : null;
   if (typeof record.id !== "string" || typeof record.description !== "string" || !claim || typeof claim.claimType !== "string") {
@@ -387,6 +565,7 @@ function requirementFromExpectation(expectation: FlowExpectation, satisfied: Set
   }
   return {
     id: record.id,
+    gate_id: gateId,
     required: record.required === true,
     description: record.description,
     claim_type: claim.claimType,

package/src/builder-lifecycle-authority.ts

@@ -66,6 +66,54 @@ export function builderLifecycleAuthorizationPayload(value: Omit<BuilderLifecycl
   return JSON.stringify(value);
 }
 
+/**
+ * Build the canonical UNSIGNED authorization for a lifecycle operation, plus the
+ * exact bytes an operator must sign (#659 Slice C — "friendly cancel").
+ *
+ * The whole point is signing-payload parity: `verifyAuthorizationSignature`
+ * recomputes the signed bytes from the *loaded* authorization, after normalizing
+ * `assignment_actor`/`request` through `validateActor`/`validateRequest` and
+ * re-assembling the top-level keys in a fixed order. So we build the unsigned
+ * object here through the *same* validators and the *same* key order, and derive
+ * `signingPayload` from it — guaranteeing that a signature produced over
+ * `signingPayload` will verify. (The validators are idempotent, so re-running
+ * them on this already-canonical object at load time yields identical bytes.)
+ */
+export function buildUnsignedLifecycleAuthorization(fields: {
+  operation: AuthorizedBuilderLifecycleOperation;
+  run_id: string;
+  subject: string;
+  assignment_actor_key: string;
+  assignment_actor: unknown;
+  nonce: string;
+  expires_at: string;
+  request: unknown;
+}): { unsigned: Omit<BuilderLifecycleAuthorization, "signature">; signingPayload: string } {
+  boundedText(fields.run_id, "run_id", 256);
+  boundedText(fields.subject, "subject", 2048);
+  boundedText(fields.assignment_actor_key, "assignment_actor_key", 256);
+  boundedText(fields.nonce, "nonce", 256);
+  const assignment_actor = validateActor(fields.assignment_actor);
+  const request = validateRequest(fields.request);
+  const expiresAt = dateTime(fields.expires_at, "expires_at");
+  const requestedAt = Date.parse(request.authority.requested_at);
+  if (expiresAt < requestedAt) {
+    throw new Error("lifecycle authorization expires_at must not precede request.authority.requested_at");
+  }
+  const unsigned = {
+    schema_version: "1.0",
+    operation: fields.operation,
+    run_id: fields.run_id,
+    subject: fields.subject,
+    assignment_actor_key: fields.assignment_actor_key,
+    assignment_actor,
+    nonce: fields.nonce,
+    expires_at: fields.expires_at,
+    request,
+  } satisfies Omit<BuilderLifecycleAuthorization, "signature">;
+  return { unsigned, signingPayload: builderLifecycleAuthorizationPayload(unsigned) };
+}
+
 export function assertAuthorizationUnused(artifactRoot: string, authorization: BuilderLifecycleAuthorization): void {
   if (!readAuthorizationConsumption(artifactRoot, authorization)) return;
   throw new Error("lifecycle authorization nonce has already been consumed");