@nifrajs/coding-agent 3.2.0

package/src/orchestration/host.ts

@@ -0,0 +1,445 @@
+/**
+ * The OrchestrationHost: the lifecycle owner for a compiled {@link RunPlan}. It does not schedule
+ * work itself - each top-level DAG layer is handed to a kernel {@link WorkflowRunner}, exactly as
+ * {@link compileRunPlan} would fold them into one `sequence`. Driving layer by layer gives a safe
+ * pause boundary (in-flight nodes finish; no new layer starts) and a cancellation seam (the layer's
+ * runner and any bounded subagent share the run's abort signal) without a second engine.
+ *
+ * Every transition is guarded by an explicit state machine: an illegal transition returns a stable
+ * code and mutates nothing. A terminal run is frozen - a late completion from an aborted layer
+ * cannot change its status, counters, or digest. Terminal results expose status, completed node ids,
+ * an order-independent evidence digest, artifact refs, counters, and a failure code only: never a
+ * step output, prompt, or payload.
+ */
+
+import type { CapabilityDescriptor } from "@nifrajs/agent/registry"
+import type {
+  ArtifactPort,
+  ArtifactRef,
+  NodeEffectKey,
+  RunNode,
+  RunNodeKind,
+  RunPlan,
+} from "@nifrajs/agent-protocol"
+import { parseRunPlan, RUN_PLAN_VERSION } from "@nifrajs/agent-protocol"
+import type { WorkflowStep } from "../workflows.ts"
+import { type WorkflowEvent, WorkflowRunner } from "../workflows.ts"
+import { noopArtifactPort } from "./artifact-port.ts"
+import type { StepCatalog } from "./catalog.ts"
+import { compileRunPlanLayers, digestRunPlan, type OrchestrationLimits } from "./compile.ts"
+import { type EvidenceCounters, type EvidenceStore, MemoryEvidenceStore } from "./evidence-store.ts"
+import { admitCapability, ChildVectorTracker, type HostPolicy } from "./policy.ts"
+
+export type RunState = "submitted" | "running" | "paused" | "succeeded" | "failed" | "cancelled"
+
+const TERMINAL: ReadonlySet<RunState> = new Set(["succeeded", "failed", "cancelled"])
+
+function isTerminal(state: RunState): boolean {
+  return TERMINAL.has(state)
+}
+
+/** Thrown on an illegal lifecycle transition or an unknown run. `code` is stable. */
+export class OrchestrationStateError extends Error {
+  constructor(
+    reason: string,
+    readonly code: string,
+  ) {
+    super(`orchestration host: ${reason}`)
+    this.name = "OrchestrationStateError"
+  }
+}
+
+/** Content-free progress view of a run. */
+export interface RunStatus {
+  readonly runId: string
+  readonly state: RunState
+  readonly planDigest: string
+  readonly layerIndex: number
+  readonly layerCount: number
+  readonly counters: EvidenceCounters
+}
+
+/** Deterministic terminal result. Outcome identity only - no step output, prompt, or payload. */
+export interface RunResult {
+  readonly runId: string
+  readonly status: "succeeded" | "failed" | "cancelled"
+  readonly planDigest: string
+  readonly completedNodeIds: readonly string[]
+  readonly evidenceDigest: string
+  readonly artifacts: readonly ArtifactRef[]
+  readonly counters: EvidenceCounters
+  readonly failureCode?: string
+}
+
+export interface SubmitOptions {
+  /** Caller-supplied for reproducibility; defaults to a per-host monotonic id (no clock, no random). */
+  readonly runId?: string
+  /** Caller-owned payload sink. Defaults to hash-and-discard. */
+  readonly artifactPort?: ArtifactPort
+  /** Evidence store for this run. Defaults to a bounded {@link MemoryEvidenceStore}. */
+  readonly store?: EvidenceStore
+}
+
+export interface OrchestrationHostOptions {
+  readonly catalog: StepCatalog
+  readonly limits?: OrchestrationLimits
+  /** Kernel step ceiling per layer. Generous by default so a full 256-node layer runs. */
+  readonly maxSteps?: number
+  readonly maxDepth?: number
+  /**
+   * Authoritative admission policy. When set, {@link OrchestrationHost.admit} refuses any capability
+   * descriptor that asks to run outside the policy's kinds, capability allowlist, isolation floor, or
+   * approval requirement. A descriptor, plan, model, or extension cannot override it.
+   */
+  readonly policy?: HostPolicy
+}
+
+const DEFAULT_MAX_STEPS = 100_000
+const DEFAULT_MAX_DEPTH = 64
+
+interface RunRecord {
+  readonly runId: string
+  readonly planDigest: string
+  readonly layers: readonly WorkflowStep[]
+  readonly store: EvidenceStore
+  readonly controller: AbortController
+  readonly kindById: ReadonlyMap<string, RunNodeKind>
+  readonly idempotentById: ReadonlyMap<string, boolean>
+  readonly nodeIds: ReadonlySet<string>
+  readonly effectKeys: Map<string, NodeEffectKey>
+  readonly artifacts: Map<string, ArtifactRef[]>
+  state: RunState
+  layerIndex: number
+  seq: number
+  cancelRequested: boolean
+  failureCode: string | undefined
+  gate: { readonly promise: Promise<void>; readonly resolve: () => void } | undefined
+  done: Promise<void>
+  finish: () => void
+}
+
+/** Owns run lifecycle and evidence projection over the kernel WorkflowRunner. */
+export class OrchestrationHost {
+  private readonly catalog: StepCatalog
+  private readonly limits: OrchestrationLimits | undefined
+  private readonly maxSteps: number
+  private readonly maxDepth: number
+  private readonly policy: HostPolicy | undefined
+  private readonly vectors = new ChildVectorTracker()
+  private readonly runs = new Map<string, RunRecord>()
+  private counter = 0
+
+  constructor(options: OrchestrationHostOptions) {
+    this.catalog = options.catalog
+    this.limits = options.limits
+    this.maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS
+    this.maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH
+    this.policy = options.policy
+  }
+
+  /**
+   * Admit a capability descriptor against the host policy before it can be invoked. Throws
+   * {@link OrchestrationStateError} (`E_POLICY_REJECTED`) carrying the admission reason when refused.
+   * With no policy configured this is a passthrough - the host admits nothing it is not told to gate.
+   */
+  admit(descriptor: CapabilityDescriptor): void {
+    if (this.policy === undefined) return
+    const admission = admitCapability(this.policy, descriptor)
+    if (!admission.ok)
+      throw new OrchestrationStateError(
+        `capability refused by host policy (${admission.code})`,
+        "E_POLICY_REJECTED",
+      )
+  }
+
+  /**
+   * Allocate the next monotonic child vector for a live run, addressing a decision boundary the run
+   * pauses on. Strictly increasing per run, so a decision carrying any other vector is provably stale.
+   */
+  openBoundaryVector(runId: string): number {
+    const run = this.require(runId)
+    if (isTerminal(run.state))
+      throw new OrchestrationStateError(
+        `run '${runId}' is terminal; no boundary opens`,
+        "E_NOT_TERMINAL",
+      )
+    return this.vectors.open(runId)
+  }
+
+  /**
+   * Parse, compile, and register a run in `submitted`. All structural ceilings and capability
+   * authority are enforced here (a `CompileError` with a stable code), so an over-limit or
+   * unauthorized plan never reaches `running`.
+   */
+  async submit(source: RunPlan | unknown, options: SubmitOptions = {}): Promise<string> {
+    const plan = parseRunPlan(source)
+    const planDigest = await digestRunPlan(plan)
+    const runId = options.runId ?? `run-${++this.counter}`
+    if (this.runs.has(runId))
+      throw new OrchestrationStateError(`run '${runId}' already exists`, "E_DUPLICATE_RUN")
+
+    const artifactPort = options.artifactPort ?? noopArtifactPort()
+    const effectKeys = new Map<string, NodeEffectKey>()
+    const artifacts = new Map<string, ArtifactRef[]>()
+    const layers = compileRunPlanLayers(plan, {
+      catalog: this.catalog,
+      planDigest,
+      artifactPort,
+      ...(this.limits !== undefined ? { limits: this.limits } : {}),
+      onNodeEffect: (nodeId, key) => effectKeys.set(nodeId, key),
+      collectArtifact: (nodeId, ref) => {
+        const list = artifacts.get(nodeId)
+        if (list === undefined) artifacts.set(nodeId, [ref])
+        else list.push(ref)
+      },
+    })
+
+    const { kindById, idempotentById, nodeIds } = this.indexPlan(plan)
+    let finish!: () => void
+    const done = new Promise<void>((resolve) => {
+      finish = resolve
+    })
+    this.runs.set(runId, {
+      runId,
+      planDigest,
+      layers,
+      store: options.store ?? new MemoryEvidenceStore(),
+      controller: new AbortController(),
+      kindById,
+      idempotentById,
+      nodeIds,
+      effectKeys,
+      artifacts,
+      state: "submitted",
+      layerIndex: 0,
+      seq: 0,
+      cancelRequested: false,
+      failureCode: undefined,
+      gate: undefined,
+      done,
+      finish,
+    })
+    return runId
+  }
+
+  /** Content-free progress view. Throws `E_NOT_FOUND` for an unknown run. */
+  inspect(runId: string): RunStatus {
+    const run = this.require(runId)
+    return {
+      runId,
+      state: run.state,
+      planDigest: run.planDigest,
+      layerIndex: run.layerIndex,
+      layerCount: run.layers.length,
+      counters: run.store.counters(),
+    }
+  }
+
+  /** `submitted` -> `running`. Begins the driver. */
+  start(runId: string): void {
+    const run = this.require(runId)
+    this.transition(run, "start", ["submitted"], "running")
+    void this.drive(run)
+  }
+
+  /** `running` -> `paused`. Takes effect at the next layer boundary; in-flight nodes finish. */
+  pause(runId: string): void {
+    const run = this.require(runId)
+    this.transition(run, "pause", ["running"], "paused")
+    let resolve!: () => void
+    const promise = new Promise<void>((r) => {
+      resolve = r
+    })
+    run.gate = { promise, resolve }
+  }
+
+  /** `paused` -> `running`. Releases the layer boundary. */
+  resume(runId: string): void {
+    const run = this.require(runId)
+    this.transition(run, "resume", ["paused"], "running")
+    run.gate?.resolve()
+    run.gate = undefined
+  }
+
+  /**
+   * Cancel from any non-terminal state. Aborts the in-flight layer and any bounded subagent, frees a
+   * paused gate, and freezes the run in `cancelled`. A late completion cannot revive it.
+   */
+  cancel(runId: string): void {
+    const run = this.require(runId)
+    if (isTerminal(run.state))
+      throw new OrchestrationStateError(
+        `run '${runId}' cannot cancel from terminal '${run.state}'`,
+        "E_ILLEGAL_TRANSITION",
+      )
+    run.cancelRequested = true
+    run.state = "cancelled"
+    run.failureCode = "E_CANCELLED"
+    run.controller.abort()
+    run.gate?.resolve()
+    run.gate = undefined
+    this.vectors.release(run.runId)
+    run.finish()
+  }
+
+  /** Terminal result. Throws `E_NOT_TERMINAL` while the run is still live. */
+  async result(runId: string): Promise<RunResult> {
+    const run = this.require(runId)
+    if (!isTerminal(run.state))
+      throw new OrchestrationStateError(
+        `run '${runId}' is '${run.state}', not terminal`,
+        "E_NOT_TERMINAL",
+      )
+    return this.buildResult(run)
+  }
+
+  /** Await the run reaching a terminal state, then return its result. */
+  async settled(runId: string): Promise<RunResult> {
+    const run = this.require(runId)
+    await run.done
+    return this.buildResult(run)
+  }
+
+  private require(runId: string): RunRecord {
+    const run = this.runs.get(runId)
+    if (run === undefined)
+      throw new OrchestrationStateError(`unknown run '${runId}'`, "E_NOT_FOUND")
+    return run
+  }
+
+  private transition(run: RunRecord, op: string, from: readonly RunState[], to: RunState): void {
+    if (!from.includes(run.state))
+      throw new OrchestrationStateError(
+        `cannot ${op} run '${run.runId}' from '${run.state}'`,
+        "E_ILLEGAL_TRANSITION",
+      )
+    run.state = to
+  }
+
+  private async buildResult(run: RunRecord): Promise<RunResult> {
+    const status = run.state as "succeeded" | "failed" | "cancelled"
+    return {
+      runId: run.runId,
+      status,
+      planDigest: run.planDigest,
+      completedNodeIds: run.store.completedNodeIds(),
+      evidenceDigest: await run.store.digest(),
+      artifacts: run.store.artifacts(),
+      counters: run.store.counters(),
+      ...(run.failureCode !== undefined ? { failureCode: run.failureCode } : {}),
+    }
+  }
+
+  private async drive(run: RunRecord): Promise<void> {
+    try {
+      for (; run.layerIndex < run.layers.length; run.layerIndex++) {
+        while (run.state === "paused") await run.gate?.promise
+        if (isTerminal(run.state)) return // cancelled while paused
+        const layer = run.layers[run.layerIndex] as WorkflowStep
+        const result = await new WorkflowRunner({
+          signal: run.controller.signal,
+          maxSteps: this.maxSteps,
+          maxDepth: this.maxDepth,
+          onEvent: (event) => this.project(run, event),
+        }).run(layer)
+        if (isTerminal(run.state)) return // cancelled mid-layer: ignore the late result
+        if (!result.ok) {
+          run.state = "failed"
+          run.failureCode = run.failureCode ?? "E_STEP_FAILED"
+          return
+        }
+      }
+      if (!isTerminal(run.state)) run.state = "succeeded"
+    } finally {
+      if (!isTerminal(run.state)) run.state = "failed"
+      this.vectors.release(run.runId)
+      run.finish()
+    }
+  }
+
+  /** Project one kernel event into a content-free evidence record. Frozen once the run is terminal. */
+  private async project(run: RunRecord, event: WorkflowEvent): Promise<void> {
+    if (isTerminal(run.state)) return // a late completion cannot mutate a terminal run
+    if (!("id" in event) || !run.nodeIds.has(event.id)) return
+    const base = {
+      version: RUN_PLAN_VERSION,
+      runId: run.runId,
+      planDigest: run.planDigest,
+      nodeId: event.id,
+      seq: run.seq++,
+      idempotent: run.idempotentById.get(event.id) ?? false,
+    } as const
+    const key = run.effectKeys.get(event.id)
+    const effect = key !== undefined ? { effectKey: key.digest } : {}
+
+    if (event.type === "step.started") {
+      await run.store.append({ ...base, status: "started" })
+      return
+    }
+    if (event.type === "step.completed") {
+      if (isGateRejection(run.kindById.get(event.id), event.output)) {
+        run.failureCode = "E_GATE_REJECTED"
+        await run.store.append({ ...base, status: "failed", errorCode: "GATE_REJECTED", ...effect })
+        return
+      }
+      const refs = run.artifacts.get(event.id)
+      await run.store.append({
+        ...base,
+        status: "completed",
+        ...effect,
+        ...(refs !== undefined && refs.length > 0 ? { artifacts: refs } : {}),
+      })
+      return
+    }
+    if (event.type === "step.failed") {
+      run.failureCode = "E_STEP_FAILED"
+      await run.store.append({ ...base, status: "failed", errorCode: "STEP_FAILED", ...effect })
+    }
+  }
+
+  /** Walk the plan tree once: node kinds, idempotency flags, and the full id set. */
+  private indexPlan(plan: RunPlan): {
+    readonly kindById: ReadonlyMap<string, RunNodeKind>
+    readonly idempotentById: ReadonlyMap<string, boolean>
+    readonly nodeIds: ReadonlySet<string>
+  } {
+    const kindById = new Map<string, RunNodeKind>()
+    const idempotentById = new Map<string, boolean>()
+    const nodeIds = new Set<string>()
+    const walk = (node: RunNode): void => {
+      nodeIds.add(node.id)
+      kindById.set(node.id, node.kind)
+      const step = "step" in node ? this.catalog.get(node.step) : undefined
+      idempotentById.set(node.id, step?.selectEffect !== undefined)
+      switch (node.kind) {
+        case "sequence":
+        case "parallel":
+          for (const child of node.children) walk(child)
+          break
+        case "retry":
+          walk(node.child)
+          break
+        case "branch":
+          walk(node.then)
+          if (node.otherwise !== undefined) walk(node.otherwise)
+          break
+      }
+    }
+    for (const node of plan.nodes) walk(node)
+    return { kindById, idempotentById, nodeIds }
+  }
+}
+
+/** A verify/approve node whose output is not a pass. Other kinds never gate. */
+function isGateRejection(kind: RunNodeKind | undefined, output: unknown): boolean {
+  if (kind === "verify") {
+    if (output === true) return false
+    return !(
+      typeof output === "object" &&
+      output !== null &&
+      (output as { ok?: unknown }).ok === true
+    )
+  }
+  if (kind === "approve") return output !== true
+  return false
+}

package/src/orchestration/index.ts

@@ -0,0 +1,131 @@
+/**
+ * `@nifrajs/coding-agent/orchestration` - declarative RunPlans compiled onto the existing
+ * WorkflowRunner, with content-free evidence, a caller-owned artifact seam, and content-free
+ * idempotency keys. No second engine; no payload sink. See the P0 addendum for the design lock.
+ */
+
+export type {
+  ArtifactContext,
+  ArtifactPort,
+  ArtifactRef,
+  NodeEffectKey,
+  RunBranchNode,
+  RunEvidence,
+  RunEvidenceStatus,
+  RunLeafKind,
+  RunLeafNode,
+  RunNode,
+  RunNodeKind,
+  RunParallelNode,
+  RunPlan,
+  RunRetryNode,
+  RunRetryPolicy,
+  RunSequenceNode,
+  RunStructuralKind,
+} from "@nifrajs/agent-protocol"
+export {
+  assertEvidenceSize,
+  EVIDENCE_MAX_BYTES,
+  FORBIDDEN_CONTENT_KEYS,
+  parseArtifactRef,
+  parseRunEvidence,
+  parseRunPlan,
+  RUN_PLAN_VERSION,
+  RunContractError,
+} from "@nifrajs/agent-protocol"
+
+export {
+  type MemoryArtifactPort,
+  memoryArtifactPort,
+  noopArtifactPort,
+} from "./artifact-port.ts"
+export {
+  CatalogError,
+  type CatalogStep,
+  createStepCatalog,
+  mergeStepCatalogs,
+  type StepCatalog,
+  type StepEffectContext,
+  type StepRunContext,
+  stepVersion,
+} from "./catalog.ts"
+export {
+  CompileError,
+  type CompileOptions,
+  compileRunPlan,
+  compileRunPlanLayers,
+  digestRunPlan,
+  type OrchestrationLimits,
+} from "./compile.ts"
+export {
+  createRunDispatch,
+  DISPATCH_JOB_NAME,
+  type DispatchBoundary,
+  type DispatchInspection,
+  type DispatchResultCode,
+  type DispatchState,
+  type DispatchWriteResult,
+  type DurableDispatchAdapter,
+  deriveRunIdempotencyKey,
+  type InjectedClock,
+  MAX_DISPATCH_ATTEMPTS,
+  MAX_DISPATCH_STRING,
+  parseRunCheckpoint,
+  parseRunDispatch,
+  parseRunDispatchEvidence,
+  parseRunLease,
+  RUN_DISPATCH_VERSION,
+  type RunCheckpoint,
+  type RunDispatch,
+  type RunDispatchEvidence,
+  type RunDispatchStore,
+  type RunLease,
+  systemClock,
+} from "./dispatch.ts"
+export {
+  createDurableJobsStore,
+  createMemoryRunDispatchStore,
+  type DurableJobsStoreOptions,
+} from "./durable-jobs.ts"
+export { deriveNodeEffectKey, type EffectKeyMaterial } from "./effect-key.ts"
+export {
+  type EvidenceCounters,
+  type EvidenceStore,
+  FileEvidenceStore,
+  type FileEvidenceStoreOptions,
+  MemoryEvidenceStore,
+  type MemoryEvidenceStoreOptions,
+} from "./evidence-store.ts"
+export { canonicalJson, sha256Hex, sha256HexOf } from "./hash.ts"
+export {
+  OrchestrationHost,
+  type OrchestrationHostOptions,
+  OrchestrationStateError,
+  type RunResult,
+  type RunState,
+  type RunStatus,
+  type SubmitOptions,
+} from "./host.ts"
+export {
+  type Admission,
+  type AdmissionRejection,
+  admitCapability,
+  assertAdmitted,
+  ChildVectorTracker,
+  type HostPolicy,
+  PolicyError,
+} from "./policy.ts"
+export {
+  type CommittedEffect,
+  EffectRejectedError,
+  type IdempotencyProofStore,
+  MemoryIdempotencyProofStore,
+  RecoveryCrashError,
+  type RecoveryMachineOptions,
+  type RecoveryProcessResult,
+  type RunEffect,
+  type RunEffectContext,
+  RunRecoveryMachine,
+  TestClock,
+} from "./recovery.ts"
+export { type RunTraceOptions, type RunTraceResult, runTrace } from "./tracer.ts"

package/src/orchestration/policy.ts

@@ -0,0 +1,116 @@
+/**
+ * Host policy admission for the orchestration host (REG-06) and the monotonic child-vector allocator
+ * (REG-07).
+ *
+ * A {@link HostPolicy} is the authority: it declares which capability kinds may run, an allowlist of
+ * required capabilities, an isolation floor, and whether every capability must be approved. A
+ * {@link CapabilityDescriptor} is only a request - {@link admitCapability} lets the descriptor tighten
+ * nothing it did not already promise and, crucially, cannot loosen the policy. A descriptor asking for
+ * weaker isolation than the floor, declaring a capability outside the allowlist, or offering `none`
+ * approval where the host requires approval is refused with a stable code. Descriptors, plans, models,
+ * extensions, and clients therefore cannot override host policy.
+ *
+ * The {@link ChildVectorTracker} hands each newly opened decision boundary a strictly increasing
+ * per-run vector. A decision must later carry the exact vector its boundary opened with, so a replayed
+ * or superseded decision cannot resume work. The tracker never allocates a non-advancing vector.
+ */
+
+import type {
+  ApprovalClass,
+  CapabilityDescriptor,
+  CapabilityKind,
+  IsolationClass,
+} from "@nifrajs/agent/registry"
+
+/** The authoritative admission policy. Empty allowlists deny everything of that kind. */
+export interface HostPolicy {
+  /** Capability kinds the host will admit. A descriptor of any other kind is refused. */
+  readonly allowedKinds: readonly CapabilityKind[]
+  /** Required-capability allowlist. Every `requiredCapabilities` entry must be present. */
+  readonly allowedCapabilities: readonly string[]
+  /** Isolation floor. A descriptor offering weaker isolation than this is refused. */
+  readonly minIsolation: IsolationClass
+  /** When true, a descriptor whose approval class is `none` is refused as a downgrade. */
+  readonly requireApproval: boolean
+}
+
+/** Stable, content-free reasons the host refuses to admit a capability. */
+export type AdmissionRejection =
+  | "kind_not_allowed"
+  | "capability_not_allowed"
+  | "isolation_too_weak"
+  | "approval_downgrade"
+
+export type Admission =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly code: AdmissionRejection }
+
+/** Thrown when the host refuses admission and the caller wants an exception rather than a result. */
+export class PolicyError extends Error {
+  readonly code: AdmissionRejection
+
+  constructor(code: AdmissionRejection) {
+    super(`host policy: ${code}`)
+    this.code = code
+    this.name = "PolicyError"
+  }
+}
+
+// Isolation is a total order: a higher rank is stronger and satisfies any lower floor.
+const ISOLATION_RANK: Readonly<Record<IsolationClass, number>> = {
+  inherit: 0,
+  process: 1,
+  sandbox: 2,
+}
+
+function approvalIsNone(approval: ApprovalClass): boolean {
+  return approval.kind === "none"
+}
+
+/**
+ * Admit a capability descriptor against the host policy. The policy is the floor; the descriptor can
+ * only meet or exceed it. Returns the first failing reason, or `{ ok: true }` when every gate passes.
+ */
+export function admitCapability(policy: HostPolicy, descriptor: CapabilityDescriptor): Admission {
+  if (!policy.allowedKinds.includes(descriptor.kind)) return { ok: false, code: "kind_not_allowed" }
+  const allowed = new Set(policy.allowedCapabilities)
+  for (const capability of descriptor.requiredCapabilities)
+    if (!allowed.has(capability)) return { ok: false, code: "capability_not_allowed" }
+  if (ISOLATION_RANK[descriptor.isolation] < ISOLATION_RANK[policy.minIsolation])
+    return { ok: false, code: "isolation_too_weak" }
+  if (policy.requireApproval && approvalIsNone(descriptor.approval))
+    return { ok: false, code: "approval_downgrade" }
+  return { ok: true }
+}
+
+/** Admit or throw {@link PolicyError}. Use at the host boundary where a refusal must stop the run. */
+export function assertAdmitted(policy: HostPolicy, descriptor: CapabilityDescriptor): void {
+  const admission = admitCapability(policy, descriptor)
+  if (!admission.ok) throw new PolicyError(admission.code)
+}
+
+/**
+ * Per-run monotonic child-vector allocator. `open` returns the next strictly increasing vector for a
+ * run; `last` reports the high-water mark (`-1` before the first boundary). A vector is never reused,
+ * so a decision carrying anything other than its boundary's opened vector is provably stale.
+ */
+export class ChildVectorTracker {
+  private readonly highWater = new Map<string, number>()
+
+  /** Allocate the next vector for a run. Strictly greater than every previously allocated vector. */
+  open(runId: string): number {
+    const next = (this.highWater.get(runId) ?? -1) + 1
+    this.highWater.set(runId, next)
+    return next
+  }
+
+  /** The last allocated vector for a run, or `-1` when none has opened. */
+  last(runId: string): number {
+    return this.highWater.get(runId) ?? -1
+  }
+
+  /** Forget a run's vectors once it is terminal. Idempotent. */
+  release(runId: string): void {
+    this.highWater.delete(runId)
+  }
+}