@humwick/server 0.130.1 → 0.130.3

package/node_modules/@humwick/kernel/landing.ts

@@ -1,953 +0,0 @@
-import { z } from "zod";
-import { landingIncidentEntities, landingIncidentOps } from "./landing-incident";
-import { type EntityStore, type JsonValue, type ModuleCtx, type StepResult, OpError, defineModule } from "./contract";
-
-export const LANDING_STATES = [
-  "controller_wait",
-  "queued",
-  "supersession_wait",
-  "lane_wait",
-  "authorization_required",
-  "preparing",
-  "gating",
-  "gate_failed",
-  "publish_ready",
-  "publishing",
-  "verifying",
-  "cleanup",
-  "receipt_ready",
-  "external_retire_pending",
-  "retry_wait",
-  "reconciliation_required",
-  "supersede_pending",
-  "cancel_pending",
-  "landed",
-  "superseded",
-  "canceled",
-  "failed",
-] as const;
-
-const landingStateSchema = z.enum(LANDING_STATES);
-const terminalProcessProofSchema = z.enum(["never_started", "completed", "process_tree_dead"]);
-
-const workspaceHeadSchema = z.object({
-  id: z.string(),
-  workspaceId: z.string(),
-  currentRunId: z.string(),
-  generation: z.number().int(),
-  authorizationEventId: z.number().int(),
-  updatedAt: z.number().int(),
-});
-
-const runSchema = z.object({
-  id: z.string(),
-  workspaceId: z.string(),
-  laneKey: z.string().optional(),
-  generation: z.number().int(),
-  authorizationEventId: z.number().int(),
-  workflowInstanceId: z.string().optional(),
-  sourceRef: z.string(),
-  sourceHeadSha: z.string(),
-  repoRoot: z.string(),
-  remoteIdentity: z.string(),
-  baseRef: z.string(),
-  strategy: z.string(),
-  gateSnapshot: z.string(),
-  requesterSnapshot: z.string(),
-  baseHeadSha: z.string().optional(),
-  candidateHeadSha: z.string().optional(),
-  candidateTreeSha: z.string().optional(),
-  pushRemote: z.string().optional(),
-  selectedOrchestratorId: z.string().optional(),
-  selectedCapabilityDigest: z.string().optional(),
-  selectedSafetyDigest: z.string().optional(),
-  candidateWorktreePath: z.string().optional(),
-  executionTreeHandle: z.string().optional(),
-  controllerVersion: z.number().int().optional(),
-  controllerToken: z.string().optional(),
-  laneToken: z.string().optional(),
-  gateTreeSha: z.string().optional(),
-  gateConfigDigest: z.string().optional(),
-  gateAttestation: z.string().optional(),
-  receiptId: z.string().optional(),
-  receiptTargetSha: z.string().optional(),
-  receiptVerifiedAt: z.number().int().optional(),
-  receiptVerificationGeneration: z.number().int().optional(),
-  receiptKind: z.enum(["kernel", "external"]).optional(),
-  state: landingStateSchema,
-  stateVersion: z.number().int(),
-  stateSince: z.number().int(),
-  queuedAt: z.number().int(),
-  attempt: z.number().int(),
-  phaseOrdinal: z.number().int(),
-  commandGeneration: z.number().int(),
-  // Optional for migration safety: Phase 3 rows predate this dedicated legacy projection clock.
-  // commandGeneration remains reserved for the Phase 4 Kernel command fence.
-  legacyProgressSequence: z.number().int().optional(),
-  commandId: z.string().optional(),
-  lastDryRunCommandId: z.string().optional(),
-  nextRetryAt: z.number().int().optional(),
-  transientFailures: z.number().int(),
-  gateFailures: z.number().int(),
-  pushRaces: z.number().int(),
-  executorRecoveries: z.number().int(),
-  blockerCode: z.string().optional(),
-  blockerDetail: z.string().optional(),
-  blockedAt: z.number().int().optional(),
-  supersededBy: z.string().optional(),
-  landedSha: z.string().optional(),
-  landedAt: z.number().int().optional(),
-  terminalProcessProof: terminalProcessProofSchema.optional(),
-  legacyCommandId: z.string().optional(),
-  legacyStatus: z.string().optional(),
-  shadowVerdict: z.enum(["parity", "mismatch"]).optional(),
-  shadowSummaryDigest: z.string().optional(),
-  lastComparisonDigest: z.string().optional(),
-  lastComparisonVersion: z.number().int().optional(),
-  consecutiveStaleComparisons: z.number().int().optional(),
-  shadowDetail: z.string().optional(),
-  durableExitKind: z.enum(["command_wait", "event_wait", "sleep", "supervisor_reconcile", "explicit_action"]).optional(),
-  observationGeneration: z.number().int().optional(),
-  lastObservedAt: z.number().int().optional(),
-  nextObservationAt: z.number().int().optional(),
-  lastObservationDigest: z.string().optional(),
-  observationRepeatCount: z.number().int().optional(),
-  predictedOutcome: z.enum(["none", "external_retire", "reconciliation_required"]).optional(),
-  lastReconciledAt: z.number().int().optional(),
-  createdAt: z.number().int(),
-  updatedAt: z.number().int(),
-});
-
-const laneSchema = z.object({
-  id: z.string(),
-  laneKey: z.string(),
-  repoRoot: z.string(),
-  remoteIdentity: z.string(),
-  baseRef: z.string(),
-  identityDigest: z.string(),
-  currentRunId: z.string().optional(),
-  retiringRunId: z.string().optional(),
-  laneToken: z.string().optional(),
-  leaseExpiresAt: z.number().int().optional(),
-  activeCommandId: z.string().optional(),
-  activeExecutionGeneration: z.number().int().optional(),
-  drainEpochId: z.string().optional(),
-  lastTerminalProcessProof: terminalProcessProofSchema.optional(),
-  updatedAt: z.number().int(),
-});
-
-const noticeSchema = z.object({
-  id: z.string(),
-  runId: z.string(),
-  stateVersion: z.number().int(),
-  audience: z.string(),
-  kind: z.string(),
-  status: z.enum(["pending", "sent"]),
-  payload: z.string(),
-  createdAt: z.number().int(),
-  sentAt: z.number().int().optional(),
-});
-
-const effectSchema = z.object({
-  id: z.string(),
-  runId: z.string(),
-  stateVersion: z.number().int(),
-  kind: z.string(),
-  status: z.enum(["pending", "completed"]),
-  payload: z.string(),
-  createdAt: z.number().int(),
-  completedAt: z.number().int().optional(),
-  deliveryKey: z.string().optional(),
-  claimedAt: z.number().int().optional(),
-  attempts: z.number().int().optional(),
-});
-
-const comparisonSchema = z.object({
-  id: z.string(),
-  runId: z.string(),
-  generation: z.number().int(),
-  comparisonVersion: z.number().int(),
-  verdict: z.enum(["parity", "mismatch", "stale"]),
-  legacyState: z.string(),
-  shadowState: landingStateSchema,
-  summaryDigest: z.string(),
-  detail: z.string(),
-  createdAt: z.number().int(),
-});
-
-const targetObservationSchema = z.object({
-  id: z.string(),
-  runId: z.string(),
-  generation: z.number().int(),
-  observationGeneration: z.number().int(),
-  sourceHeadSha: z.string(),
-  candidateHeadSha: z.string().optional(),
-  targetRef: z.string(),
-  targetHeadSha: z.string().optional(),
-  sourceContained: z.boolean().optional(),
-  candidateContained: z.boolean().optional(),
-  containmentMethod: z.string().optional(),
-  status: z.enum(["positive", "negative", "unknown"]),
-  observedAt: z.number().int(),
-});
-
-const receiptSchema = z.object({
-  id: z.string(),
-  runId: z.string(),
-  workspaceId: z.string(),
-  generation: z.number().int(),
-  laneKey: z.string(),
-  kind: z.enum(["kernel", "external"]),
-  sourceRef: z.string(),
-  sourceHeadSha: z.string(),
-  targetRef: z.string(),
-  targetHeadSha: z.string(),
-  candidateHeadSha: z.string().optional(),
-  gateAttestation: z.string().optional(),
-  verificationGeneration: z.number().int(),
-  verifiedAt: z.number().int(),
-  createdAt: z.number().int(),
-});
-
-type LandingStores = {
-  workspaceHead: EntityStore<{ schema: typeof workspaceHeadSchema }>;
-  run: EntityStore<{ schema: typeof runSchema }>;
-  lane: EntityStore<{ schema: typeof laneSchema }>;
-  notice: EntityStore<{ schema: typeof noticeSchema }>;
-  effect: EntityStore<{ schema: typeof effectSchema }>;
-  targetObservation: EntityStore<{ schema: typeof targetObservationSchema }>;
-  comparison: EntityStore<{ schema: typeof comparisonSchema }>;
-  receipt: EntityStore<{ schema: typeof receiptSchema }>;
-};
-
-function stores(ctx: ModuleCtx): LandingStores {
-  return ctx.entities as unknown as LandingStores;
-}
-
-export function landingRunId(workspaceId: string, authorizationEventId: number): string {
-  return `land:${workspaceId}:event:${authorizationEventId}`;
-}
-
-const frozenIntentSchema = z.object({
-  repoRoot: z.string().min(1),
-  remoteIdentity: z.string().min(1),
-  baseRef: z.string().min(1),
-  strategy: z.string().min(1),
-  gateSnapshot: z.record(z.string(), z.unknown()),
-  requester: z.object({ actor: z.string().min(1), agentId: z.string().optional() }),
-});
-
-const admissionInputSchema = z.object({
-  authorizationEventId: z.number().int().positive(),
-  workspaceId: z.string().min(1),
-  laneKey: z.string().min(1).optional(),
-  sourceRef: z.string().min(1),
-  sourceHeadSha: z.string().min(1),
-  queuedAt: z.number().int(),
-  frozenIntent: frozenIntentSchema,
-});
-
-const dryRunTupleSchema = z.object({
-  runId: z.string(), generation: z.number().int(), commandGeneration: z.number().int(),
-  attempt: z.number().int(), phaseOrdinal: z.number().int(), stateVersion: z.number().int(),
-});
-
-const dryRunCommandResultInputSchema = z.object({
-  commandId: z.string().min(1),
-  type: z.enum(["landing.prepare", "landing.gate", "landing.publish", "landing.verify", "landing.observe-target", "landing.cleanup"]),
-  tuple: dryRunTupleSchema,
-  terminalProcessProof: z.literal("completed"),
-  result: z.record(z.string(), z.unknown()),
-});
-
-const admissionOutputSchema = z.object({
-  runId: z.string(),
-  generation: z.number().int(),
-  state: landingStateSchema,
-  current: z.boolean(),
-  workflowInstanceId: z.string().optional(),
-});
-
-const observationInputSchema = z.object({
-  runId: z.string(),
-  expectedGeneration: z.number().int(),
-  expectedStateVersion: z.number().int(),
-  observationGeneration: z.number().int().positive(),
-  factDigest: z.string().min(1).max(200),
-  sourceHeadSha: z.string(),
-  candidateHeadSha: z.string().optional(),
-  targetRef: z.string(),
-  targetHeadSha: z.string().optional(),
-  sourceContained: z.boolean().optional(),
-  candidateContained: z.boolean().optional(),
-  containmentMethod: z.string().optional(),
-  status: z.enum(["positive", "negative", "unknown"]),
-});
-
-const finalizeControlInputSchema = z.object({
-  runId: z.string(), expectedGeneration: z.number().int(), expectedStateVersion: z.number().int(),
-  commandId: z.string(), terminalProcessProof: terminalProcessProofSchema,
-});
-
-const landingHostCommandInputSchema = z.object({
-  type: z.enum(["landing.prepare", "landing.gate", "landing.publish", "landing.verify", "landing.cleanup"]),
-  params: z.record(z.string(), z.unknown()),
-});
-
-const LANDING_ADMIN_GRANT = "landing:admin" as const;
-
-type ControllerWaitState = { runId: string; commandId?: string };
-type LandingState = z.output<typeof landingStateSchema>;
-type LandingControlAction = "cancel" | "fail" | "supersede" | "retry" | "reconcile";
-
-const NONTERMINAL_LANDING_STATES = LANDING_STATES.filter(
-  (state): state is Exclude<LandingState, "landed" | "superseded" | "canceled" | "failed"> =>
-    state !== "landed" && state !== "superseded" && state !== "canceled" && state !== "failed",
-);
-
-export type LandingDurableExit = "command_wait" | "event_wait" | "sleep" | "supervisor_reconcile" | "explicit_action";
-
-// Persisted exit labels retained for historical landing command/control compatibility.
-export const LANDING_DURABLE_EXITS = Object.freeze({
-  controller_wait: "event_wait",
-  queued: "supervisor_reconcile",
-  supersession_wait: "event_wait",
-  lane_wait: "event_wait",
-  authorization_required: "sleep",
-  preparing: "supervisor_reconcile",
-  gating: "supervisor_reconcile",
-  gate_failed: "explicit_action",
-  publish_ready: "supervisor_reconcile",
-  publishing: "supervisor_reconcile",
-  verifying: "supervisor_reconcile",
-  cleanup: "supervisor_reconcile",
-  receipt_ready: "supervisor_reconcile",
-  external_retire_pending: "supervisor_reconcile",
-  retry_wait: "sleep",
-  reconciliation_required: "explicit_action",
-  supersede_pending: "supervisor_reconcile",
-  cancel_pending: "supervisor_reconcile",
-} satisfies Record<(typeof NONTERMINAL_LANDING_STATES)[number], LandingDurableExit>);
-
-const LANDING_OBSERVATION_BASE_MS = 30_000;
-const LANDING_OBSERVATION_MAX_MS = 30 * 60_000;
-
-function repeatedObservationDelayMs(repeats: number): number {
-  return Math.min(LANDING_OBSERVATION_MAX_MS, LANDING_OBSERVATION_BASE_MS * 2 ** Math.min(6, repeats));
-}
-
-function commandForRun(row: z.output<typeof runSchema>): z.input<typeof landingHostCommandInputSchema> | undefined {
-  if (!row.laneKey || !row.baseHeadSha || !row.controllerToken || !row.laneToken || !row.selectedOrchestratorId
-    || !row.selectedCapabilityDigest || !row.selectedSafetyDigest || !row.executionTreeHandle) return undefined;
-  const common = { workspaceId: row.workspaceId, laneKey: row.laneKey, repoRoot: row.repoRoot,
-    sourceRef: row.sourceRef, sourceHeadSha: row.sourceHeadSha, baseRef: row.baseRef,
-    baseHeadSha: row.baseHeadSha, laneToken: row.laneToken,
-    runTuple: { runId: row.id, generation: row.generation, commandGeneration: row.commandGeneration,
-      attempt: row.attempt, phaseOrdinal: row.phaseOrdinal, stateVersion: row.stateVersion },
-    selectedHost: { orchestratorId: row.selectedOrchestratorId,
-      capabilityDigest: row.selectedCapabilityDigest, safetyDigest: row.selectedSafetyDigest },
-    executionTreeHandle: row.executionTreeHandle };
-  if (row.state === "preparing" && row.candidateWorktreePath) return {
-    type: "landing.prepare", params: { ...common, candidateWorktreePath: row.candidateWorktreePath },
-  };
-  if (row.state === "gating" && row.candidateWorktreePath && row.candidateHeadSha) return {
-    type: "landing.gate", params: { ...common, candidateWorktreePath: row.candidateWorktreePath,
-      candidateHeadSha: row.candidateHeadSha, gates: [] },
-  };
-  if (row.state === "publish_ready" && (row.observationGeneration ?? 0) > 0
-    && row.candidateWorktreePath && row.candidateHeadSha
-    && row.pushRemote && row.gateTreeSha && row.gateConfigDigest && row.gateAttestation) return {
-    type: "landing.publish", params: { ...common, candidateWorktreePath: row.candidateWorktreePath,
-      pushRemote: row.pushRemote, candidateHeadSha: row.candidateHeadSha, gateTreeSha: row.gateTreeSha,
-      gateConfigDigest: row.gateConfigDigest, gateAttestationDigest: row.gateAttestation,
-      observationGeneration: row.observationGeneration ?? 0, expectedRestartEpoch: null,
-      pushAttemptId: `push:${row.id}:${row.commandGeneration}`,
-      timing: { pushTimeoutMs: 300_000, reapTimeoutMs: 60_000, reportTimeoutMs: 30_000,
-        refreshedLaneLeaseMs: 15 * 60_000 } },
-  };
-  if (row.state === "verifying" && row.pushRemote) return { type: "landing.verify",
-    params: { ...common, pushRemote: row.pushRemote,
-      ...(row.candidateHeadSha ? { candidateHeadSha: row.candidateHeadSha } : {}) } };
-  if (row.state === "cleanup" && row.candidateWorktreePath) return { type: "landing.cleanup",
-    params: { ...common, candidateWorktreePath: row.candidateWorktreePath,
-      ...(row.candidateHeadSha ? { candidateHeadSha: row.candidateHeadSha } : {}) } };
-  return undefined;
-}
-
-const LANDING_CONTROL_TRANSITIONS = {
-  cancel: { allowedFrom: new Set<LandingState>(NONTERMINAL_LANDING_STATES), target: "canceled", workflow: "cancel" },
-  fail: { allowedFrom: new Set<LandingState>(NONTERMINAL_LANDING_STATES), target: "failed", workflow: "fail" },
-  supersede: { allowedFrom: new Set<LandingState>(NONTERMINAL_LANDING_STATES), target: "superseded", workflow: "cancel" },
-  retry: { allowedFrom: new Set<LandingState>(["failed", "gate_failed", "retry_wait", "authorization_required"]), target: "controller_wait", workflow: "reopen" },
-  reconcile: { allowedFrom: new Set<LandingState>(["reconciliation_required"]), target: "controller_wait", workflow: "reopen" },
-} as const satisfies Record<LandingControlAction, {
-  allowedFrom: ReadonlySet<LandingState>;
-  target: LandingState;
-  workflow: "cancel" | "fail" | "reopen";
-}>;
-
-function landingControlTransition(action: LandingControlAction, source: LandingState) {
-  const transition = LANDING_CONTROL_TRANSITIONS[action];
-  return transition.allowedFrom.has(source) ? transition : undefined;
-}
-
-async function stageWorkflowControl(
-  ctx: ModuleCtx,
-  operation: "cancel" | "fail" | "reopen",
-  workflowInstanceId: string | undefined,
-  failure?: JsonValue,
-): Promise<void> {
-  if (!workflowInstanceId) throw new OpError("workflow_control_unavailable", 500, "landing run has no enlisted workflow instance");
-  if (!ctx.workflows.control) throw new OpError("workflow_control_unavailable", 500, "enlisted workflow controls are unavailable");
-  const workflow = await ctx.workflows.status(workflowInstanceId);
-  if (!workflow) throw new OpError("workflow_control_unavailable", 500,
-    `landing workflow instance '${workflowInstanceId}' was not found`);
-  // Terminal workflows are absorbing. For cancel/fail the desired convergence has already happened,
-  // even when its exact terminal status differs; staging another control would be refused during
-  // opCommit and roll the landing entity/event/comparison transaction back forever. Reopen remains
-  // strict because it is the one operation whose desired result is a live workflow.
-  if (operation !== "reopen" && ["done", "failed", "canceled"].includes(workflow.status)) return;
-  await ctx.workflows.control(operation, workflowInstanceId, failure);
-}
-
-async function transitionRun(
-  ctx: ModuleCtx,
-  input: { runId: string; expectedGeneration: number; expectedStateVersion: number; blockerCode?: string; blockerDetail?: string },
-  action: LandingControlAction,
-) {
-  const store = stores(ctx).run;
-  const row = await store.get(input.runId);
-  if (!row) throw new OpError("not_found", 404, `landing run '${input.runId}' was not found`);
-  if (row.generation !== input.expectedGeneration || row.stateVersion !== input.expectedStateVersion) {
-    throw new OpError("conflict", 409, `landing run '${input.runId}' fence mismatch`);
-  }
-  const transition = landingControlTransition(action, row.state);
-  if (!transition) {
-    throw new OpError(
-      "invalid_state_transition",
-      409,
-      `landing run '${input.runId}' cannot ${action} from state '${row.state}'`,
-    );
-  }
-  const now = ctx.clock.now();
-  const restart = action === "retry" || action === "reconcile";
-  if (restart && row.commandId && !row.terminalProcessProof) {
-    throw new OpError(
-      "retirement_required",
-      409,
-      `landing run '${input.runId}' cannot ${action} while command '${row.commandId}' is bound; cancel the landing to retire the active command before starting recovery`,
-    );
-  }
-  const retirementPending = Boolean(row.commandId) && !restart;
-  const target: LandingState = retirementPending
-    ? action === "supersede" ? "supersede_pending" : "cancel_pending"
-    : restart ? "queued" : transition.target;
-  const updated = await store.update(input.runId, {
-    state: target,
-    stateVersion: row.stateVersion + 1,
-    stateSince: now,
-    updatedAt: now,
-    ...(restart ? { attempt: row.attempt + 1, commandGeneration: row.commandGeneration + 1,
-      phaseOrdinal: 0, commandId: undefined, candidateHeadSha: undefined, candidateTreeSha: undefined,
-      gateTreeSha: undefined, gateConfigDigest: undefined, gateAttestation: undefined,
-      receiptId: undefined, receiptTargetSha: undefined, receiptVerifiedAt: undefined,
-      receiptVerificationGeneration: undefined, receiptKind: undefined,
-      laneToken: undefined, selectedOrchestratorId: undefined, selectedCapabilityDigest: undefined,
-      selectedSafetyDigest: undefined, candidateWorktreePath: undefined, executionTreeHandle: undefined,
-      blockerCode: undefined, blockerDetail: undefined, blockedAt: undefined } : {}),
-    ...(input.blockerCode ? { blockerCode: input.blockerCode, blockerDetail: input.blockerDetail, blockedAt: now } : {}),
-  });
-  if (!retirementPending && row.laneKey) {
-    const lane = await stores(ctx).lane.get(row.laneKey);
-    if (lane?.currentRunId === row.id) await stores(ctx).lane.update(lane.id, {
-      currentRunId: undefined, retiringRunId: undefined, laneToken: undefined,
-      leaseExpiresAt: undefined, activeCommandId: undefined, activeExecutionGeneration: undefined,
-      lastTerminalProcessProof: row.terminalProcessProof, updatedAt: now,
-    });
-  }
-  const workflow = restart && row.workflowInstanceId
-    ? await ctx.workflows.status(row.workflowInstanceId) : undefined;
-  if (!retirementPending && (!restart
-    || (workflow !== undefined && !["pending", "running", "waiting", "sleeping"].includes(workflow.status)))) {
-    await stageWorkflowControl(ctx, transition.workflow, row.workflowInstanceId,
-      input.blockerCode ? { code: input.blockerCode, detail: input.blockerDetail ?? "" } : undefined);
-  }
-  await ctx.events.emit("landing.run_transitioned", { runId: row.id, state: target, stateVersion: updated.stateVersion });
-  if (restart || retirementPending) {
-    await ctx.events.emit("landing.controller_activated", { runId: row.id, correlationId: row.id });
-  }
-  return updated;
-}
-
-export const landing = defineModule({
-  id: "landing",
-  title: "Durable landing controller",
-  description: "Kernel-owned durable landing authorization and controller state.",
-  entities: {
-    workspaceHead: { schema: workspaceHeadSchema, indexes: ["authorizationEventId"] },
-    run: { schema: runSchema, indexes: ["workspaceId", "authorizationEventId", "state", "blockerCode", "shadowVerdict", ["workspaceId", "state"]] },
-    lane: { schema: laneSchema, indexes: ["identityDigest", "currentRunId", "retiringRunId"] },
-    notice: { schema: noticeSchema, indexes: ["runId", "status", ["runId", "stateVersion"]] },
-    effect: { schema: effectSchema, indexes: ["runId", "status", ["runId", "stateVersion"]] },
-    targetObservation: { schema: targetObservationSchema, indexes: ["runId", ["runId", "observationGeneration"]] },
-    comparison: { schema: comparisonSchema, indexes: ["runId", "verdict", ["runId", "comparisonVersion"]] },
-    receipt: { schema: receiptSchema, indexes: ["runId", "workspaceId", ["laneKey", "createdAt"]] },
-    ...landingIncidentEntities,
-  },
-  events: {
-    "landing.authorization_admitted": z.object({ runId: z.string(), authorizationEventId: z.number().int(), current: z.boolean() }),
-    "landing.run_transitioned": z.object({ runId: z.string(), state: landingStateSchema, stateVersion: z.number().int() }),
-    "landing.controller_activated": z.object({ runId: z.string(), correlationId: z.string() }),
-    "landing.target_observed": z.object({ runId: z.string(), status: z.enum(["positive", "negative", "unknown"]), observationGeneration: z.number().int() }),
-    "landing.receipt_finalized": z.object({ runId: z.string(), receiptId: z.string(), targetHeadSha: z.string(), kind: z.enum(["kernel", "external"]) }),
-  },
-  commands: {
-    execute: {
-      input: landingHostCommandInputSchema,
-      result: z.record(z.string(), z.unknown()),
-      target: "host-agent",
-      grant: "command:landing",
-      idempotencyKey: (input) => {
-        const tuple = input.params.runTuple as Record<string, unknown> | undefined;
-        return `${input.type}:${String(tuple?.runId)}:${String(tuple?.generation)}:${String(tuple?.commandGeneration)}`;
-      },
-      timeoutMs: 15 * 60_000,
-      whenDegraded: "queue",
-    },
-  },
-  workflows: {
-    controller: {
-      input: z.object({ runId: z.string() }),
-      state: z.object({ runId: z.string(), commandId: z.string().optional() }),
-      init: (input): ControllerWaitState => ({ runId: input.runId }),
-      start: "controller_wait",
-      steps: {
-        controller_wait: {
-          run: async (ctx, state: ControllerWaitState): Promise<StepResult<ControllerWaitState>> => {
-            const run = await stores(ctx).run.get(state.runId);
-            if (run && ["landed", "superseded", "canceled", "failed"].includes(run.state)) {
-              return { state, next: "done", output: { runId: state.runId, state: run.state } };
-            }
-            const command = run ? commandForRun(run) : undefined;
-            if (run && command && run.selectedOrchestratorId) {
-              const issued = await ctx.commands.issue("execute", command, { host: run.selectedOrchestratorId });
-              return { state: { ...state, commandId: issued.id }, next: "command_wait",
-                waitFor: { kind: "command", commandId: issued.id } };
-            }
-            return { state, next: "controller_wait", waitFor: { kind: "event", topic: "landing.controller_activated", correlationId: state.runId } };
-          },
-        },
-        command_wait: {
-          run: async (_ctx, state: ControllerWaitState): Promise<StepResult<ControllerWaitState>> => ({
-            state: { runId: state.runId }, next: "controller_wait",
-          }),
-        },
-      },
-    },
-  },
-  ops: {
-    ...landingIncidentOps,
-    admitAuthorization: {
-      kind: "mutation",
-      idempotent: true,
-      grant: LANDING_ADMIN_GRANT,
-      summary: "Admit one immutable landing authorization in event order.",
-      expose: { http: false, mcp: false, cli: false },
-      emits: ["landing.authorization_admitted", "landing.run_transitioned"],
-      input: admissionInputSchema,
-      output: admissionOutputSchema,
-      handler: async (ctx, input) => {
-        const entity = stores(ctx);
-        const runId = landingRunId(input.workspaceId, input.authorizationEventId);
-        const existing = await entity.run.get(runId);
-        if (existing) {
-          const head = await entity.workspaceHead.get(input.workspaceId);
-          return {
-            runId,
-            generation: existing.generation,
-            state: existing.state,
-            current: head?.currentRunId === runId,
-            ...(existing.workflowInstanceId ? { workflowInstanceId: existing.workflowInstanceId } : {}),
-          };
-        }
-
-        const head = await entity.workspaceHead.get(input.workspaceId);
-        const isCurrent = !head || input.authorizationEventId > head.authorizationEventId;
-        const now = ctx.clock.now();
-        if (!isCurrent) {
-          await entity.run.create({
-            id: runId,
-            workspaceId: input.workspaceId,
-            laneKey: input.laneKey,
-            generation: input.authorizationEventId,
-            authorizationEventId: input.authorizationEventId,
-            sourceRef: input.sourceRef,
-            sourceHeadSha: input.sourceHeadSha,
-            repoRoot: input.frozenIntent.repoRoot,
-            remoteIdentity: input.frozenIntent.remoteIdentity,
-            baseRef: input.frozenIntent.baseRef,
-            strategy: input.frozenIntent.strategy,
-            gateSnapshot: JSON.stringify(input.frozenIntent.gateSnapshot),
-            requesterSnapshot: JSON.stringify(input.frozenIntent.requester),
-            state: "superseded",
-            stateVersion: 0,
-            stateSince: now,
-            queuedAt: input.queuedAt,
-            attempt: 0,
-            phaseOrdinal: 0,
-            commandGeneration: 0,
-            legacyProgressSequence: 0,
-            transientFailures: 0,
-            gateFailures: 0,
-            pushRaces: 0,
-            executorRecoveries: 0,
-            supersededBy: head!.currentRunId,
-            terminalProcessProof: "never_started",
-            createdAt: now,
-            updatedAt: now,
-          });
-          await ctx.events.emit("landing.authorization_admitted", { runId, authorizationEventId: input.authorizationEventId, current: false });
-          return { runId, generation: input.authorizationEventId, state: "superseded", current: false };
-        }
-
-        const workflow = await ctx.workflows.start("controller", { runId }, { idempotencyKey: runId, enlist: "op-commit" });
-        await entity.run.create({
-          id: runId,
-          workspaceId: input.workspaceId,
-          laneKey: input.laneKey,
-          generation: input.authorizationEventId,
-          authorizationEventId: input.authorizationEventId,
-          workflowInstanceId: workflow.id,
-          sourceRef: input.sourceRef,
-          sourceHeadSha: input.sourceHeadSha,
-          repoRoot: input.frozenIntent.repoRoot,
-          remoteIdentity: input.frozenIntent.remoteIdentity,
-          baseRef: input.frozenIntent.baseRef,
-          strategy: input.frozenIntent.strategy,
-          gateSnapshot: JSON.stringify(input.frozenIntent.gateSnapshot),
-          requesterSnapshot: JSON.stringify(input.frozenIntent.requester),
-          state: "controller_wait",
-          stateVersion: 0,
-          stateSince: now,
-          queuedAt: input.queuedAt,
-          attempt: 0,
-          phaseOrdinal: 0,
-          commandGeneration: 0,
-          legacyProgressSequence: 0,
-          transientFailures: 0,
-          gateFailures: 0,
-          pushRaces: 0,
-          executorRecoveries: 0,
-          createdAt: now,
-          updatedAt: now,
-        });
-        if (head) {
-          const prior = await entity.run.get(head.currentRunId);
-          const supersession = prior ? landingControlTransition("supersede", prior.state) : undefined;
-          if (prior && supersession) {
-            await entity.run.update(prior.id, {
-              state: supersession.target,
-              stateVersion: prior.stateVersion + 1,
-              stateSince: now,
-              supersededBy: runId,
-              terminalProcessProof: "never_started",
-              updatedAt: now,
-            });
-            await stageWorkflowControl(ctx, supersession.workflow, prior.workflowInstanceId);
-            await ctx.events.emit("landing.run_transitioned", { runId: prior.id, state: supersession.target, stateVersion: prior.stateVersion + 1 });
-          }
-          await entity.workspaceHead.update(input.workspaceId, {
-            currentRunId: runId,
-            generation: input.authorizationEventId,
-            authorizationEventId: input.authorizationEventId,
-            updatedAt: now,
-          });
-        } else {
-          await entity.workspaceHead.create({
-            id: input.workspaceId,
-            workspaceId: input.workspaceId,
-            currentRunId: runId,
-            generation: input.authorizationEventId,
-            authorizationEventId: input.authorizationEventId,
-            updatedAt: now,
-          });
-        }
-        await ctx.events.emit("landing.authorization_admitted", { runId, authorizationEventId: input.authorizationEventId, current: true });
-        return { runId, generation: input.authorizationEventId, state: "controller_wait", current: true, workflowInstanceId: workflow.id };
-      },
-    },
-    acceptDryRunCommandResult: {
-      kind: "mutation", idempotent: true, grant: LANDING_ADMIN_GRANT,
-      summary: "Atomically commit one fenced terminal landing command attestation into the current run.",
-      expose: { http: false, mcp: false, cli: false }, emits: ["landing.run_transitioned", "landing.controller_activated"],
-      input: dryRunCommandResultInputSchema, output: runSchema,
-      handler: async (ctx, input) => {
-        const entity = stores(ctx);
-        const row = await entity.run.get(input.tuple.runId);
-        if (!row) throw new OpError("not_found", 404, `landing run '${input.tuple.runId}' was not found`);
-        if (row.lastDryRunCommandId === input.commandId) return row;
-        const tuple = input.tuple;
-        if (row.generation !== tuple.generation || row.commandGeneration !== tuple.commandGeneration
-          || row.attempt !== tuple.attempt || row.phaseOrdinal !== tuple.phaseOrdinal
-          || row.stateVersion !== tuple.stateVersion) {
-          throw new OpError("conflict", 409, `landing run '${row.id}' command tuple is stale`);
-        }
-        const result = input.result;
-        const status = typeof result.status === "string" ? result.status : "";
-        const required = (name: string): string => {
-          const value = result[name];
-          if (typeof value !== "string" || !value) throw new OpError("invalid_input", 400, `${input.type} result.${name} is required`);
-          return value;
-        };
-        const now = ctx.clock.now();
-        let state: LandingState = row.state;
-        const patch: Record<string, string | number | undefined> = {
-          lastDryRunCommandId: input.commandId,
-          commandId: undefined,
-          terminalProcessProof: input.terminalProcessProof,
-          commandGeneration: row.commandGeneration + 1,
-          phaseOrdinal: row.phaseOrdinal + 1,
-          updatedAt: now,
-        };
-        if (input.type === "landing.prepare") {
-          if (status === "prepared") {
-            patch.baseHeadSha = required("baseHeadSha");
-            patch.candidateHeadSha = required("candidateHeadSha");
-            patch.candidateTreeSha = required("candidateTreeSha");
-            patch.pushRemote = required("pushRemote");
-            state = "gating";
-          } else state = status === "source-drift" ? "authorization_required" : "retry_wait";
-        } else if (input.type === "landing.gate") {
-          if (status === "passed") {
-            patch.candidateHeadSha = required("candidateHeadSha");
-            patch.gateTreeSha = required("gateTreeSha");
-            patch.gateConfigDigest = required("gateConfigDigest");
-            patch.gateAttestation = required("gateAttestationDigest");
-            state = "publish_ready";
-          } else if (status === "red") {
-            patch.gateFailures = row.gateFailures + 1;
-            state = "gate_failed";
-          } else {
-            patch.transientFailures = row.transientFailures + 1;
-            state = "retry_wait";
-          }
-        } else if (input.type === "landing.publish") {
-          if (status === "published" || status === "ambiguous") state = "verifying";
-          else if (status === "base-race") {
-            patch.pushRaces = row.pushRaces + 1;
-            state = "retry_wait";
-          } else state = "authorization_required";
-        } else if (input.type === "landing.verify") {
-          if (status === "contained") {
-            const targetHeadSha = required("targetHeadSha");
-            if (!row.candidateHeadSha || targetHeadSha !== row.candidateHeadSha) {
-              throw new OpError("conflict", 409, "Kernel verification did not prove the exact gated candidate");
-            }
-            patch.receiptTargetSha = targetHeadSha;
-            patch.receiptVerifiedAt = now;
-            patch.receiptVerificationGeneration = row.commandGeneration + 1;
-            patch.receiptKind = "kernel";
-            state = "cleanup";
-          } else state = status === "unknown" ? "reconciliation_required" : "retry_wait";
-        } else if (input.type === "landing.observe-target") {
-          state = status === "unknown" ? "reconciliation_required" : row.state;
-        } else if (input.type === "landing.cleanup") {
-          state = status === "removed" || status === "already-clean" ? "receipt_ready" : "reconciliation_required";
-        }
-        const changedState = state !== row.state;
-        patch.state = state;
-        patch.stateVersion = row.stateVersion + 1;
-        patch.stateSince = changedState ? now : row.stateSince;
-        const updated = await entity.run.update(row.id, patch);
-        const lane = row.laneKey ? await entity.lane.get(row.laneKey) : undefined;
-        if (lane && lane.activeCommandId === input.commandId) await entity.lane.update(lane.id, {
-          activeCommandId: undefined, activeExecutionGeneration: undefined,
-          lastTerminalProcessProof: input.terminalProcessProof, updatedAt: now,
-        });
-        if (changedState) await ctx.events.emit("landing.run_transitioned", { runId: row.id, state, stateVersion: updated.stateVersion });
-        if (!["landed", "superseded", "canceled", "failed"].includes(state)) {
-          await ctx.events.emit("landing.controller_activated", { runId: row.id, correlationId: row.id });
-        }
-        return updated;
-      },
-    },
-    cancelLanding: {
-      kind: "mutation", idempotent: false, grant: LANDING_ADMIN_GRANT, summary: "Cancel a fenced inert landing run.", expose: { http: false, mcp: false, cli: false },
-      emits: ["landing.run_transitioned"],
-      input: z.object({ runId: z.string(), expectedGeneration: z.number().int(), expectedStateVersion: z.number().int() }), output: runSchema,
-      handler: (ctx, input) => transitionRun(ctx, input, "cancel"),
-    },
-    failLanding: {
-      kind: "mutation", idempotent: false, grant: LANDING_ADMIN_GRANT, summary: "Fail a fenced landing run with a structured blocker.", expose: { http: false, mcp: false, cli: false },
-      emits: ["landing.run_transitioned"],
-      input: z.object({ runId: z.string(), expectedGeneration: z.number().int(), expectedStateVersion: z.number().int(), blockerCode: z.string(), blockerDetail: z.string().optional() }), output: runSchema,
-      handler: (ctx, input) => transitionRun(ctx, input, "fail"),
-    },
-    supersedeLanding: {
-      kind: "mutation", idempotent: false, grant: LANDING_ADMIN_GRANT, summary: "Supersede a fenced inert landing run.", expose: { http: false, mcp: false, cli: false },
-      emits: ["landing.run_transitioned"],
-      input: z.object({ runId: z.string(), expectedGeneration: z.number().int(), expectedStateVersion: z.number().int() }), output: runSchema,
-      handler: (ctx, input) => transitionRun(ctx, input, "supersede"),
-    },
-    retryLanding: {
-      kind: "mutation", idempotent: false, grant: LANDING_ADMIN_GRANT, summary: "Reopen a fenced failed run into inert controller wait.", expose: { http: false, mcp: false, cli: false },
-      emits: ["landing.run_transitioned", "landing.controller_activated"],
-      input: z.object({ runId: z.string(), expectedGeneration: z.number().int(), expectedStateVersion: z.number().int() }), output: runSchema,
-      handler: (ctx, input) => transitionRun(ctx, input, "retry"),
-    },
-    reconcileLanding: {
-      kind: "mutation", idempotent: false, grant: LANDING_ADMIN_GRANT, summary: "Re-arm a fenced reconciliation blocker for canonical controller recovery.", expose: { http: false, mcp: false, cli: false },
-      emits: ["landing.run_transitioned", "landing.controller_activated"],
-      input: z.object({ runId: z.string(), expectedGeneration: z.number().int(), expectedStateVersion: z.number().int() }), output: runSchema,
-      handler: (ctx, input) => transitionRun(ctx, input, "reconcile"),
-    },
-    finalizeControl: {
-      kind: "mutation", idempotent: true, grant: LANDING_ADMIN_GRANT,
-      summary: "Finalize cancel/fail/supersede only after the exact active process is positively retired.",
-      expose: { http: false, mcp: false, cli: false }, emits: ["landing.run_transitioned"],
-      input: finalizeControlInputSchema, output: runSchema,
-      handler: async (ctx, input) => {
-        const entity = stores(ctx);
-        const row = await entity.run.get(input.runId);
-        if (!row) throw new OpError("not_found", 404, `landing run '${input.runId}' was not found`);
-        if (row.generation !== input.expectedGeneration || row.stateVersion !== input.expectedStateVersion
-          || row.commandId !== input.commandId
-          || (row.state !== "cancel_pending" && row.state !== "supersede_pending")) {
-          throw new OpError("conflict", 409, "landing control finalization fence mismatch");
-        }
-        const terminal: LandingState = row.state === "supersede_pending" ? "superseded"
-          : row.blockerCode ? "failed" : "canceled";
-        const now = ctx.clock.now();
-        const lane = row.laneKey ? await entity.lane.get(row.laneKey) : undefined;
-        if (lane?.activeCommandId && lane.activeCommandId !== input.commandId) {
-          throw new OpError("conflict", 409, "landing control active-command fence changed");
-        }
-        const updated = await entity.run.update(row.id, { state: terminal,
-          stateVersion: row.stateVersion + 1, stateSince: now, commandId: undefined,
-          terminalProcessProof: input.terminalProcessProof, durableExitKind: "explicit_action", updatedAt: now });
-        if (lane && lane.currentRunId === row.id) await entity.lane.update(lane.id, { currentRunId: undefined,
-          retiringRunId: undefined, laneToken: undefined, leaseExpiresAt: undefined,
-          activeCommandId: undefined, activeExecutionGeneration: undefined,
-          lastTerminalProcessProof: input.terminalProcessProof, updatedAt: now });
-        await stageWorkflowControl(ctx, terminal === "failed" ? "fail" : "cancel", row.workflowInstanceId,
-          terminal === "failed" ? { code: row.blockerCode ?? "landing_failed", detail: row.blockerDetail ?? "" } : undefined);
-        await ctx.events.emit("landing.run_transitioned", { runId: row.id, state: terminal,
-          stateVersion: updated.stateVersion });
-        return updated;
-      },
-    },
-    acceptTargetObservation: {
-      kind: "mutation", idempotent: true, grant: LANDING_ADMIN_GRANT,
-      summary: "Persist one fenced three-valued dry target observation and its shadow-only prediction.",
-      expose: { http: false, mcp: false, cli: false },
-      emits: ["landing.run_transitioned", "landing.controller_activated", "landing.target_observed"],
-      input: observationInputSchema,
-      output: z.object({ run: runSchema, observation: targetObservationSchema.optional() }),
-      handler: async (ctx, input) => {
-        const entity = stores(ctx);
-        const observationId = `${input.runId}:observation:${input.observationGeneration}`;
-        const replay = await entity.targetObservation.get(observationId);
-        if (replay) {
-          const replayRun = await entity.run.get(input.runId);
-          if (!replayRun) throw new OpError("not_found", 404, `landing run '${input.runId}' was not found`);
-          return { run: replayRun, observation: replay };
-        }
-        const row = await entity.run.get(input.runId);
-        if (!row) throw new OpError("not_found", 404, `landing run '${input.runId}' was not found`);
-        if (row.generation !== input.expectedGeneration || row.stateVersion !== input.expectedStateVersion) {
-          throw new OpError("conflict", 409, `landing run '${input.runId}' fence mismatch`);
-        }
-        if (input.observationGeneration <= (row.observationGeneration ?? 0)) {
-          throw new OpError("conflict", 409, `landing run '${input.runId}' observation is stale`);
-        }
-        if (input.status === "positive" && input.sourceContained !== true && input.candidateContained !== true) {
-          throw new OpError("invalid_input", 400, "positive target observation requires positive remote containment evidence");
-        }
-        const now = ctx.clock.now();
-        if (row.lastObservationDigest === input.factDigest) {
-          const observationRepeatCount = (row.observationRepeatCount ?? 0) + 1;
-          const repeated = await entity.run.update(row.id, { observationGeneration: input.observationGeneration,
-            lastObservedAt: now, nextObservationAt: now + repeatedObservationDelayMs(observationRepeatCount),
-            observationRepeatCount, updatedAt: now });
-          return { run: repeated };
-        }
-        const observation = await entity.targetObservation.create({ id: observationId, runId: row.id,
-          generation: row.generation, observationGeneration: input.observationGeneration,
-          sourceHeadSha: input.sourceHeadSha, candidateHeadSha: input.candidateHeadSha,
-          targetRef: input.targetRef, targetHeadSha: input.targetHeadSha,
-          sourceContained: input.sourceContained, candidateContained: input.candidateContained,
-          containmentMethod: input.containmentMethod, status: input.status, observedAt: now });
-        const terminal = ["landed", "superseded", "canceled", "failed"].includes(row.state);
-        const targetState = terminal ? row.state : input.status === "positive" ? "external_retire_pending"
-          : input.status === "unknown" ? "reconciliation_required" : row.state;
-        const updated = await entity.run.update(row.id, {
-          state: targetState,
-          stateVersion: row.stateVersion + (targetState === row.state ? 0 : 1),
-          stateSince: targetState === row.state ? row.stateSince : now,
-          observationGeneration: input.observationGeneration,
-          lastObservedAt: now,
-          nextObservationAt: now + LANDING_OBSERVATION_BASE_MS,
-          lastObservationDigest: input.factDigest,
-          observationRepeatCount: 0,
-          predictedOutcome: input.status === "positive" ? "external_retire" : input.status === "unknown" ? "reconciliation_required" : "none",
-          durableExitKind: terminal ? row.durableExitKind : LANDING_DURABLE_EXITS[targetState as keyof typeof LANDING_DURABLE_EXITS],
-          lastReconciledAt: now,
-          updatedAt: now,
-        });
-        if (input.status === "unknown") {
-          const noticeId = `${row.id}:observation-unknown:${input.factDigest}`;
-          const payload = JSON.stringify({ targetRef: input.targetRef,
-            containmentMethod: input.containmentMethod ?? "unavailable", action: "reconcile_remote_evidence" });
-          if (!await entity.notice.get(noticeId)) await entity.notice.create({ id: noticeId, runId: row.id,
-            stateVersion: updated.stateVersion, audience: "landing-operator", kind: "observation-unknown",
-            status: "pending", payload, createdAt: now });
-          if (!await entity.effect.get(noticeId)) await entity.effect.create({ id: noticeId, runId: row.id,
-            stateVersion: updated.stateVersion, kind: "observation-unknown", status: "pending", payload,
-            deliveryKey: noticeId, attempts: 0, createdAt: now });
-        }
-        if (targetState !== row.state) await ctx.events.emit("landing.run_transitioned", { runId: row.id, state: targetState, stateVersion: updated.stateVersion });
-        await ctx.events.emit("landing.target_observed", { runId: row.id, status: input.status, observationGeneration: input.observationGeneration });
-        if (targetState !== row.state || (input.status === "negative" && row.state === "publish_ready")) {
-          await ctx.events.emit("landing.controller_activated", { runId: row.id, correlationId: row.id });
-        }
-        return { run: updated, observation };
-      },
-    },
-    reconcileTerminal: {
-      kind: "mutation", idempotent: true, grant: LANDING_ADMIN_GRANT,
-      summary: "Converge generic workflow and landing-domain terminal state without guessing.",
-      expose: { http: false, mcp: false, cli: false }, emits: ["landing.run_transitioned", "landing.controller_activated"],
-      input: z.object({ runId: z.string(), expectedGeneration: z.number().int(), expectedStateVersion: z.number().int(), workflowStatus: z.enum(["pending", "running", "waiting", "sleeping", "paused", "done", "failed", "canceled"]) }),
-      output: runSchema,
-      handler: async (ctx, input) => {
-        const row = await stores(ctx).run.get(input.runId);
-        if (!row) throw new OpError("not_found", 404, `landing run '${input.runId}' was not found`);
-        if (row.generation !== input.expectedGeneration || row.stateVersion !== input.expectedStateVersion) throw new OpError("conflict", 409, `landing run '${input.runId}' fence mismatch`);
-        const domainTerminal = ["landed", "superseded", "canceled", "failed"].includes(row.state);
-        const workflowTerminal = ["done", "failed", "canceled"].includes(input.workflowStatus);
-        if (domainTerminal && !workflowTerminal) {
-          if (row.state === "canceled" || row.state === "superseded") await stageWorkflowControl(ctx, "cancel", row.workflowInstanceId);
-          else if (row.state === "failed") await stageWorkflowControl(ctx, "fail", row.workflowInstanceId, { code: "landing_domain_failed" });
-          else await ctx.events.emit("landing.controller_activated", { runId: row.id, correlationId: row.id });
-          return row;
-        }
-        if (!domainTerminal && workflowTerminal) {
-          const now = ctx.clock.now();
-          const state: LandingState = input.workflowStatus === "canceled" ? "canceled"
-            : input.workflowStatus === "failed" ? "failed" : "reconciliation_required";
-          if (row.state === state) return row;
-          const updated = await stores(ctx).run.update(row.id, { state, stateVersion: row.stateVersion + 1,
-            stateSince: now, durableExitKind: state === "reconciliation_required" ? "explicit_action" : row.durableExitKind,
-            blockerCode: "workflow_domain_disagreement", blockerDetail: `workflow=${input.workflowStatus}; domain=${row.state}`,
-            blockedAt: now, updatedAt: now });
-          await ctx.events.emit("landing.run_transitioned", { runId: row.id, state, stateVersion: updated.stateVersion });
-          return updated;
-        }
-        return row;
-      },
-    },
-  },
-});
-
-export type LandingRun = z.output<typeof runSchema>;
-export type LandingWorkspaceHead = z.output<typeof workspaceHeadSchema>;