dsh-bettertaskgraphs 0.0.0-stage → 0.2.2

package/core.mjs

@@ -0,0 +1,432 @@
+// SPDX-License-Identifier: GPL-3.0-only
+import { createHash, randomUUID } from 'node:crypto'
+
+export const LIMITS = Object.freeze({ nodes: 128, edges: 512, depth: 16, cases: 8, events: 1024, bytes: 4 * 1024 * 1024, evidence: 32 })
+export class GraphError extends Error {
+  constructor(code, message = code) { super(message); this.name = 'GraphError'; this.code = code }
+}
+const fail = (code, message) => { throw new GraphError(code, message) }
+const own = (object, key) => Object.hasOwn(object, key)
+export const copy = value => structuredClone(value)
+export function canonical(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value)
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+  return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`
+}
+export const digest = value => createHash('sha256').update(canonical(value)).digest('hex')
+const identifier = value => typeof value === 'string' && /^[a-z][a-z0-9_-]{0,79}$/.test(value)
+function text(value, maximum, name) {
+  if (typeof value !== 'string' || !value.trim() || value.length > maximum) fail('INVALID_TEXT', name)
+  return value.trim()
+}
+function object(value, allowed, name) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+      || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) fail('INVALID_OBJECT', name)
+  if (Object.keys(value).some(key => !allowed.includes(key))) fail('UNKNOWN_FIELD', name)
+}
+function integer(value, minimum, name) {
+  if (!Number.isSafeInteger(value) || value < minimum) fail('INVALID_INTEGER', name)
+  return value
+}
+function noCycles(ids, pairs, code) {
+  const outgoing = new Map(ids.map(id => [id, []])), degree = new Map(ids.map(id => [id, 0]))
+  for (const [a, b] of pairs) { outgoing.get(a).push(b); degree.set(b, degree.get(b) + 1) }
+  const ready = ids.filter(id => degree.get(id) === 0)
+  let count = 0
+  for (let i = 0; i < ready.length; i++) {
+    const id = ready[i]; count++
+    for (const target of outgoing.get(id)) { degree.set(target, degree.get(target) - 1); if (degree.get(target) === 0) ready.push(target) }
+  }
+  if (count !== ids.length) fail(code)
+}
+export function evidenceRefs(value = []) {
+  if (!Array.isArray(value) || value.length > LIMITS.evidence) fail('EVIDENCE_LIMIT')
+  const used = new Set()
+  return value.map(ref => {
+    object(ref, ['kind', 'ref', 'sha256'], 'evidence reference')
+    if (!['session_event', 'tool_result', 'artifact'].includes(ref.kind)) fail('INVALID_EVIDENCE_KIND')
+    const result = { kind: ref.kind, ref: text(ref.ref, 512, 'ref') }
+    if (ref.sha256 !== undefined) {
+      if (typeof ref.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(ref.sha256)) fail('INVALID_EVIDENCE_SHA')
+      result.sha256 = ref.sha256
+    }
+    const key = canonical(result)
+    if (used.has(key)) fail('DUPLICATE_EVIDENCE')
+    used.add(key)
+    return result
+  })
+}
+
+// Durable IDs are generated by this program. Input keys are local plan labels.
+export function normalizePlan(definition, { enableSwitch = false, id = prefix => `${prefix}_${randomUUID()}` } = {}) {
+  object(definition, ['title', 'nodes', 'edges'], 'plan')
+  if (!Array.isArray(definition.nodes) || definition.nodes.length < 2 || definition.nodes.length > LIMITS.nodes) fail('NODE_LIMIT')
+  if (!Array.isArray(definition.edges) || definition.edges.length > LIMITS.edges) fail('EDGE_LIMIT')
+  const keys = new Map(), usedIds = new Set()
+  const generated = prefix => {
+    const value = id(prefix)
+    if (!identifier(value) || usedIds.has(value)) fail('INVALID_GENERATED_ID')
+    usedIds.add(value); return value
+  }
+  const nodes = definition.nodes.map(raw => {
+    object(raw, ['key', 'kind', 'label', 'parent', 'switchCases'], 'node')
+    if (!identifier(raw.key) || keys.has(raw.key)) fail('DUPLICATE_OR_INVALID_KEY')
+    if (!['container', 'leaf'].includes(raw.kind)) fail('INVALID_NODE_KIND')
+    const cases = raw.switchCases ?? []
+    if (!Array.isArray(cases) || cases.length > LIMITS.cases || (cases.length && (!enableSwitch || raw.kind !== 'leaf'))) fail('SWITCH_DISABLED_OR_LIMIT')
+    const switchCases = cases.map(value => text(value, 64, 'case'))
+    if (new Set(switchCases).size !== switchCases.length) fail('DUPLICATE_CASE')
+    const node = { id: generated('node'), key: raw.key, kind: raw.kind, label: text(raw.label, 512, 'label'),
+      parent: raw.parent ?? null, switchCases }
+    keys.set(raw.key, node); return node
+  })
+  for (const node of nodes) {
+    if (node.parent !== null) {
+      if (!keys.has(node.parent)) fail('UNKNOWN_PARENT')
+      node.parent = keys.get(node.parent).id
+    }
+  }
+  const edges = definition.edges.map(raw => {
+    object(raw, ['kind', 'from', 'to', 'outcome', 'case'], 'edge')
+    if (!keys.has(raw.from) || !keys.has(raw.to)) fail('UNKNOWN_EDGE_ENDPOINT')
+    const edge = { id: generated('edge'), kind: raw.kind, from: keys.get(raw.from).id, to: keys.get(raw.to).id }
+    if (raw.outcome !== undefined) edge.outcome = raw.outcome
+    if (raw.case !== undefined) edge.case = raw.case
+    return edge
+  })
+  const plan = { schema: 1, id: generated('graph'), title: text(definition.title, 512, 'title'), enableSwitch, nodes, edges }
+  validatePlan(plan)
+  return plan
+}
+
+export function validatePlan(plan) {
+  object(plan, ['schema', 'id', 'title', 'enableSwitch', 'nodes', 'edges'], 'normalized plan')
+  if (plan.schema !== 1 || !identifier(plan.id) || typeof plan.enableSwitch !== 'boolean') fail('INVALID_PLAN')
+  text(plan.title, 512, 'title')
+  if (!Array.isArray(plan.nodes) || plan.nodes.length < 2 || plan.nodes.length > LIMITS.nodes
+      || !Array.isArray(plan.edges) || plan.edges.length > LIMITS.edges) fail('GRAPH_LIMIT')
+  const nodes = new Map(), ids = new Set([plan.id]), keys = new Set()
+  for (const node of plan.nodes) {
+    object(node, ['id', 'key', 'kind', 'label', 'parent', 'switchCases'], 'normalized node')
+    if (!identifier(node.id) || ids.has(node.id) || !identifier(node.key) || keys.has(node.key)
+        || !['container', 'leaf'].includes(node.kind)) fail('INVALID_NODE')
+    text(node.label, 512, 'label'); ids.add(node.id); keys.add(node.key); nodes.set(node.id, node)
+    if (!Array.isArray(node.switchCases) || node.switchCases.length > LIMITS.cases
+        || (node.switchCases.length && (!plan.enableSwitch || node.kind !== 'leaf'))
+        || new Set(node.switchCases).size !== node.switchCases.length) fail('INVALID_SWITCH')
+    for (const label of node.switchCases) text(label, 64, 'case')
+  }
+  const roots = plan.nodes.filter(node => node.parent === null)
+  if (roots.length !== 1 || roots[0].kind !== 'container') fail('ONE_ROOT_CONTAINER_REQUIRED')
+  const containment = [], semantic = []
+  for (const node of plan.nodes) {
+    if (node.parent === null) continue
+    if (!nodes.has(node.parent) || nodes.get(node.parent).kind !== 'container' || node.parent === node.id) fail('INVALID_CONTAINMENT')
+    containment.push([node.parent, node.id]); semantic.push([node.id, node.parent])
+  }
+  noCycles([...nodes.keys()], containment, 'CONTAINMENT_CYCLE')
+  for (const node of plan.nodes) {
+    let cursor = node, depth = 1
+    while (cursor.parent !== null) { cursor = nodes.get(cursor.parent); if (++depth > LIMITS.depth) fail('DEPTH_LIMIT') }
+    if (node.kind === 'container' && !plan.nodes.some(child => child.parent === node.id)) fail('EMPTY_CONTAINER')
+  }
+  const duplicate = new Set(), routes = new Set()
+  for (const edge of plan.edges) {
+    object(edge, ['id', 'kind', 'from', 'to', 'outcome', 'case'], 'normalized edge')
+    if (!identifier(edge.id) || ids.has(edge.id) || !nodes.has(edge.from) || !nodes.has(edge.to) || edge.from === edge.to) fail('INVALID_EDGE')
+    ids.add(edge.id)
+    const from = nodes.get(edge.from), to = nodes.get(edge.to)
+    if (!['prerequisite', 'route', 'case'].includes(edge.kind) || to.kind !== 'leaf') fail('ILLEGAL_EDGE_KIND_OR_TARGET')
+    if (edge.kind === 'prerequisite') {
+      if (edge.outcome !== undefined || edge.case !== undefined) fail('PREREQUISITE_HAS_CONDITION')
+    } else {
+      if (from.kind !== 'leaf') fail('ROUTE_SOURCE_MUST_BE_LEAF')
+      if (edge.kind === 'route') {
+        if (!['complete', 'incomplete'].includes(edge.outcome) || edge.case !== undefined
+            || (edge.outcome === 'complete' && from.switchCases.length)) fail('INVALID_ROUTE')
+      } else if (!plan.enableSwitch || !from.switchCases.includes(edge.case) || edge.outcome !== undefined) fail('INVALID_CASE_ROUTE')
+      const routeKey = `${edge.from}:${edge.kind}:${edge.outcome ?? edge.case}`
+      if (routes.has(routeKey)) fail('MULTIPLE_TARGETS_FOR_ONE_ROUTE')
+      routes.add(routeKey)
+    }
+    const signature = canonical({ kind: edge.kind, from: edge.from, to: edge.to, outcome: edge.outcome ?? null, case: edge.case ?? null })
+    if (duplicate.has(signature)) fail('DUPLICATE_EDGE')
+    duplicate.add(signature); semantic.push([edge.from, edge.to])
+  }
+  if (containment.length + plan.edges.length > LIMITS.edges) fail('TOTAL_EDGE_LIMIT')
+  noCycles([...nodes.keys()], semantic, 'PREREQUISITE_ROUTE_OR_COMPLETION_CYCLE')
+  for (const route of plan.edges.filter(edge => edge.kind === 'route' && edge.outcome === 'incomplete')) {
+    if (plan.edges.some(edge => edge.kind === 'prerequisite' && edge.from === route.from && edge.to === route.to)) fail('INCOMPLETE_ROUTE_REQUIRES_SAME_COMPLETE_SOURCE')
+  }
+  return true
+}
+
+function graphProgress({ plan, leaves }) {
+  const nodes = new Map(plan.nodes.map(node => [node.id, node]))
+  const children = new Map(plan.nodes.map(node => [node.id, []]))
+  const prerequisites = new Map(plan.nodes.map(node => [node.id, []]))
+  const routeSources = new Map(plan.nodes.map(node => [node.id, []]))
+  const incompleteTargets = new Map()
+  for (const node of plan.nodes) {
+    if (node.parent !== null) children.get(node.parent).push(node)
+  }
+  for (const edge of plan.edges) {
+    if (edge.kind === 'prerequisite') {
+      prerequisites.get(edge.to).push(edge.from)
+    } else {
+      routeSources.get(edge.to).push(edge.from)
+      if (edge.outcome === 'incomplete') incompleteTargets.set(edge.from, edge.to)
+    }
+  }
+
+  const branches = new Map()
+  const terminal = new Set(['COMPLETE', 'INCOMPLETE', 'SKIPPED'])
+  const priority = ['SELECTED', 'WAITING', 'NOT_SELECTED']
+  const mergeBranches = markers => priority.find(marker => markers.includes(marker)) ?? null
+
+  // Containment, prerequisites and routes were validated together as a DAG.
+  // Keep these markers derived so recorded outcomes and checksums stay intact.
+  function branchState(id) {
+    if (branches.has(id)) return branches.get(id)
+    const node = nodes.get(id)
+    let marker
+    if (node.kind === 'container') {
+      const markers = children.get(id).map(child => branchState(child.id))
+      marker = markers.every(Boolean) ? mergeBranches(markers) : null
+    } else if (routeSources.get(id).length) {
+      if (leaves[id].status !== 'INACTIVE') {
+        marker = 'SELECTED'
+      } else {
+        const stillOpen = routeSources.get(id).some(source =>
+          !terminal.has(leaves[source].status) && branchState(source) !== 'NOT_SELECTED')
+        marker = stillOpen ? 'WAITING' : 'NOT_SELECTED'
+      }
+    } else {
+      // A continuation with both selected and excluded prerequisites remains
+      // required. Its original prerequisite checks still decide eligibility.
+      marker = mergeBranches(prerequisites.get(id).map(branchState))
+    }
+    branches.set(id, marker)
+    return marker
+  }
+
+  function descendantLeaves(node) {
+    return node.kind === 'leaf' ? [node] : children.get(node.id).flatMap(descendantLeaves)
+  }
+  function complete(id) {
+    const node = nodes.get(id)
+    if (node.kind === 'leaf') return leaves[id].status === 'COMPLETE'
+    const required = new Set(descendantLeaves(node).filter(leaf => branchState(leaf.id) !== 'NOT_SELECTED').map(leaf => leaf.id))
+    // A failed decision can be handled by its chosen continuation in this
+    // container. That continuation must itself complete or handle its outcome.
+    return required.size > 0 && [...required].every(leaf =>
+      leaves[leaf].status === 'COMPLETE' ||
+      (leaves[leaf].status === 'INCOMPLETE' && required.has(incompleteTargets.get(leaf))))
+  }
+  return {
+    branchState, complete, children,
+    unmetPrerequisites: id => prerequisites.get(id).filter(source => !complete(source)),
+    pending: plan.nodes.filter(node =>
+      leaves[node.id]?.status === 'PENDING' && branchState(node.id) !== 'NOT_SELECTED'),
+  }
+}
+
+export function legalNext(state, progress) {
+  if (!state || state.active) return []
+  const { pending, unmetPrerequisites } = progress ?? graphProgress(state)
+  return pending.filter(node => unmetPrerequisites(node.id).length === 0)
+}
+function matchesRoute(edge, outcome, selectedCase) {
+  return (edge.kind === 'route' && edge.outcome === outcome)
+    || (edge.kind === 'case' && outcome === 'complete' && edge.case === selectedCase)
+}
+function activate(state, source, outcome, selectedCase) {
+  for (const edge of state.plan.edges) {
+    if (edge.from !== source) continue
+    if (matchesRoute(edge, outcome, selectedCase) && state.leaves[edge.to].status === 'INACTIVE')
+      state.leaves[edge.to].status = 'PENDING'
+  }
+}
+function finishLeaf(state, data) {
+  const active = state.active
+  if (!active || data.nodeId !== active.nodeId || data.attemptId !== active.attemptId || data.owner !== active.owner) fail('ACTIVE_ATTEMPT_MISMATCH')
+  if (!['complete', 'incomplete'].includes(data.outcome)) fail('INVALID_OUTCOME')
+  const node = state.plan.nodes.find(node => node.id === active.nodeId)
+  if (data.outcome === 'complete' && node.switchCases.length) {
+    if (!node.switchCases.includes(data.selectedCase)) fail('EXPLICIT_SWITCH_CASE_REQUIRED')
+  } else if (data.selectedCase !== null) fail('UNEXPECTED_SWITCH_CASE')
+  const refs = evidenceRefs(data.evidence)
+  if (data.outcome === 'complete' && !refs.length) fail('COMPLETE_REQUIRES_TRACEABLE_REFERENCE')
+  const disposition = data.disposition ?? (data.outcome === 'complete' ? 'COMPLETED' : 'UNSATISFIED')
+  if (data.outcome === 'complete' ? disposition !== 'COMPLETED' : !['SKIPPED_NOT_RUN', 'UNSATISFIED', 'FAILED'].includes(disposition)) fail('INVALID_FINISH_DISPOSITION')
+  text(data.note, 1200, 'finish note')
+  state.leaves[active.nodeId] = { status: data.outcome === 'complete' ? 'COMPLETE' : 'INCOMPLETE',
+    attemptId: active.attemptId, evidence: refs, note: data.note, disposition, acceptance: 'UNVERIFIED_REFERENCE' }
+  state.active = null
+  activate(state, active.nodeId, data.outcome, data.selectedCase)
+}
+
+// Deterministic replay is authoritative; snapshots are checked against it.
+export function replay(events) {
+  if (!Array.isArray(events) || !events.length || events.length > LIMITS.events) fail('EVENT_LIMIT')
+  let state = null, previous = null
+  const operations = new Set(), eventIds = new Set()
+  for (const event of events) {
+    object(event, ['id', 'seq', 'operationId', 'type', 'data', 'previousHash', 'hash'], 'event')
+    const body = { ...event }; delete body.hash
+    if (!identifier(event.id) || eventIds.has(event.id) || !identifier(event.operationId) || operations.has(event.operationId)
+        || event.seq !== operations.size + 1 || event.previousHash !== previous || digest(body) !== event.hash) fail('EVENT_CHAIN_OR_REPLAY')
+    operations.add(event.operationId); eventIds.add(event.id)
+    if (!state) {
+      if (event.type !== 'CREATED') fail('FIRST_EVENT_MUST_CREATE')
+      object(event.data, ['plan'], 'created event')
+      validatePlan(event.data.plan)
+      const plan = copy(event.data.plan), incoming = new Set(plan.edges.filter(edge => edge.kind !== 'prerequisite').map(edge => edge.to))
+      const leaves = Object.fromEntries(plan.nodes.filter(node => node.kind === 'leaf').map(node => [node.id,
+        { status: incoming.has(node.id) ? 'INACTIVE' : 'PENDING', evidence: [], acceptance: 'UNVERIFIED_REFERENCE' }]))
+      state = { schema: 1, revision: 0, plan, leaves, active: null, operations: [] }
+    } else if (event.type === 'BEGUN') {
+      object(event.data, ['nodeId', 'attemptId', 'owner'], 'begin event')
+      if (state.active || !legalNext(state).some(node => node.id === event.data.nodeId)
+          || !identifier(event.data.attemptId) || !identifier(event.data.owner)) fail('BEGIN_NOT_LEGAL')
+      state.active = copy(event.data)
+      state.leaves[event.data.nodeId].status = 'ACTIVE'
+    } else if (event.type === 'FINISHED' || event.type === 'RECONCILED') {
+      object(event.data, ['nodeId', 'attemptId', 'owner', 'outcome', 'selectedCase', 'evidence', 'note', 'disposition'], 'finish event')
+      finishLeaf(state, event.data)
+    } else if (event.type === 'SKIPPED') {
+      object(event.data, ['nodeId', 'evidence', 'note'], 'skip event')
+      if (state.active || state.leaves[event.data.nodeId]?.status !== 'PENDING') fail('SKIP_NOT_LEGAL')
+      state.leaves[event.data.nodeId] = { status: 'SKIPPED', disposition: 'SKIPPED_NOT_RUN', evidence: evidenceRefs(event.data.evidence),
+        note: text(event.data.note, 1200, 'skip note'), acceptance: 'UNVERIFIED_REFERENCE' }
+      // A skip never fires a complete/incomplete route and never satisfies a prerequisite.
+    } else fail('UNKNOWN_EVENT_TYPE')
+    state.revision = event.seq; state.operations.push(event.operationId); previous = event.hash
+  }
+  return state
+}
+export function documentOf(events) {
+  const state = replay(events), document = { schema: 1, revision: state.revision, state, events: copy(events) }
+  if (Buffer.byteLength(canonical(document)) > LIMITS.bytes) fail('DOCUMENT_BYTE_LIMIT')
+  return { ...document, checksum: digest(document) }
+}
+export function validateDocument(document) {
+  object(document, ['schema', 'revision', 'state', 'events', 'checksum'], 'document')
+  if (document.schema !== 1 || Buffer.byteLength(canonical(document)) > LIMITS.bytes) fail('DOCUMENT_LIMIT')
+  const body = { ...document }; delete body.checksum
+  if (digest(body) !== document.checksum) fail('DOCUMENT_CHECKSUM')
+  const replayed = replay(document.events)
+  if (document.revision !== replayed.revision || canonical(document.state) !== canonical(replayed)) fail('SNAPSHOT_REPLAY_MISMATCH')
+  return true
+}
+export function view(document, owner) {
+  if (!document) return { revision: 0, graph: null, legalNext: [], active: null, goalReached: false }
+  validateDocument(document)
+  const state = document.state
+  const progress = graphProgress(state), ready = legalNext(state, progress)
+  const readyIds = new Set(ready.map(node => node.id))
+  const decisions = new Set(state.plan.edges.filter(edge => edge.kind !== 'prerequisite').map(edge => edge.from))
+  const selectedBranches = new Map()
+  for (const event of document.events) {
+    if (event.type !== 'FINISHED' && event.type !== 'RECONCILED') continue
+    const { nodeId, outcome, selectedCase } = event.data
+    if (!decisions.has(nodeId) && selectedCase === null) continue
+    const target = state.plan.edges.find(edge => edge.from === nodeId && matchesRoute(edge, outcome, selectedCase))
+    selectedBranches.set(nodeId, { outcome, ...(selectedCase === null ? {} : { case: selectedCase }),
+      ...(target ? { targetId: target.to } : {}) })
+  }
+  const rows = state.plan.nodes.map(node => {
+    const branchState = progress.branchState(node.id), selectedBranch = selectedBranches.get(node.id)
+    const row = { id: node.id, key: node.key, label: node.label, kind: node.kind, ...(branchState ? { branchState } : {}) }
+    if (node.kind === 'leaf') return { ...row, ...copy(state.leaves[node.id]), ...(selectedBranch ? { selectedBranch } : {}) }
+    const allChildrenComplete = progress.complete(node.id)
+    return { ...row, childCount: progress.children.get(node.id).length, allChildrenComplete,
+      status: allChildrenComplete ? 'COMPLETE' : 'CONTAINER_INCOMPLETE' }
+  })
+  return { revision: state.revision, graph: { id: state.plan.id, title: state.plan.title }, nodes: rows,
+    active: state.active ? { ...copy(state.active), recoveryRequired: state.active.owner !== owner,
+      caseChoices: state.plan.nodes.find(node => node.id === state.active.nodeId).switchCases.map((label, choice) => ({ choice, label })) } : null,
+    legalNext: ready.map((node, choice) => ({ choice, id: node.id, label: node.label, switchCases: node.switchCases })),
+    pendingButBlocked: progress.pending.filter(node => !readyIds.has(node.id)).map(node => ({ id: node.id,
+      reason: state.active ? 'ACTIVE_LEAF' : 'UNMET_PREREQUISITE',
+      unmetPrerequisites: progress.unmetPrerequisites(node.id) })),
+    skipChoices: state.active ? [] : progress.pending
+      .map((node, choice) => ({ choice, id: node.id, label: node.label })),
+    goalReached: false, evidenceMeaning: 'References are unverified. Transaction completion does not establish Goal completion.' }
+}
+
+export class TransactionGraph {
+  constructor(store, { enableSwitch = false, id = prefix => `${prefix}_${randomUUID()}`, verifyRecovery = async () => false } = {}) {
+    this.store = store; this.enableSwitch = enableSwitch; this.id = id; this.owner = id('owner'); this.verifyRecovery = verifyRecovery
+    if (!identifier(this.owner)) fail('INVALID_OWNER')
+  }
+  read() { return view(this.store.read(), this.owner) }
+  mutate(expectedRevision, operationId, type, makeData) {
+    integer(expectedRevision, 0, 'revision')
+    if (!identifier(operationId)) fail('INVALID_OPERATION_ID')
+    return this.store.compareAndSwap(expectedRevision, previous => {
+      if (previous) validateDocument(previous)
+      if (previous?.state.operations.includes(operationId)) fail('OPERATION_REPLAY')
+      if (previous && previous.state.plan.enableSwitch !== this.enableSwitch) fail('GRAPH_POLICY_CHANGED')
+      const data = makeData(previous?.state ?? null)
+      const event = { id: this.id('event'), seq: expectedRevision + 1, operationId, type, data,
+        previousHash: previous?.events.at(-1).hash ?? null }
+      event.hash = digest(event)
+      return documentOf([...(previous?.events ?? []), event])
+    })
+  }
+  create({ expectedRevision = 0, operationId, definition }) {
+    const result = this.mutate(expectedRevision, operationId, 'CREATED', state => {
+      if (state) fail('PLAN_IMMUTABLE_CREATE_ONCE')
+      return { plan: normalizePlan(definition, { enableSwitch: this.enableSwitch, id: this.id }) }
+    }); return view(result, this.owner)
+  }
+  begin({ expectedRevision, operationId, choice }) {
+    const result = this.mutate(expectedRevision, operationId, 'BEGUN', state => {
+      if (!state) fail('NO_PLAN')
+      if (state.active) fail(state.active.owner === this.owner ? 'ONE_ACTIVE_LEAF_ONLY' : 'RECOVERY_REQUIRED')
+      integer(choice, 0, 'choice')
+      const selected = legalNext(state)[choice]
+      if (!selected) fail('NO_SUCH_LEGAL_CHOICE')
+      return { nodeId: selected.id, attemptId: this.id('attempt'), owner: this.owner }
+    }); return view(result, this.owner)
+  }
+  finish({ expectedRevision, operationId, outcome, caseIndex, evidence = [], note, disposition = outcome === 'complete' ? 'COMPLETED' : 'UNSATISFIED' }) {
+    const result = this.mutate(expectedRevision, operationId, 'FINISHED', state => {
+      if (!state?.active) fail('NO_ACTIVE_LEAF')
+      if (state.active.owner !== this.owner) fail('RECOVERY_REQUIRED')
+      const node = state.plan.nodes.find(node => node.id === state.active.nodeId)
+      let selectedCase = null
+      if (caseIndex !== undefined) { integer(caseIndex, 0, 'caseIndex'); selectedCase = node.switchCases[caseIndex]; if (selectedCase === undefined) fail('NO_SUCH_CASE') }
+      return { ...state.active, outcome, selectedCase, disposition, evidence: evidenceRefs(evidence), note: text(note, 1200, 'note') }
+    }); return view(result, this.owner)
+  }
+  skip({ expectedRevision, operationId, choice, evidence = [], note }) {
+    const result = this.mutate(expectedRevision, operationId, 'SKIPPED', state => {
+      if (!state) fail('NO_PLAN')
+      if (state.active) fail(state.active.owner === this.owner ? 'ONE_ACTIVE_LEAF_ONLY' : 'RECOVERY_REQUIRED')
+      integer(choice, 0, 'choice')
+      const selected = graphProgress(state).pending[choice]
+      if (!selected) fail('NO_SUCH_SKIP_CHOICE')
+      return { nodeId: selected.id, evidence: evidenceRefs(evidence), note: text(note, 1200, 'note') }
+    }); return view(result, this.owner)
+  }
+  async reconcile({ expectedRevision, operationId, outcome, caseIndex, evidence = [], note }) {
+    const before = this.store.read()
+    if (!before) fail('NO_PLAN')
+    validateDocument(before)
+    if (before.revision !== expectedRevision || !before.state.active) fail('RECOVERY_STALE_OR_NO_ACTIVE')
+    if (before.state.active.owner === this.owner) fail('USE_NORMAL_FINISH')
+    const node = before.state.plan.nodes.find(node => node.id === before.state.active.nodeId)
+    let selectedCase = null
+    if (caseIndex !== undefined) { integer(caseIndex, 0, 'caseIndex'); selectedCase = node.switchCases[caseIndex]; if (selectedCase === undefined) fail('NO_SUCH_CASE') }
+    const data = { ...copy(before.state.active), outcome, selectedCase, disposition: outcome === 'complete' ? 'COMPLETED' : 'UNSATISFIED', evidence: evidenceRefs(evidence), note: text(note, 1200, 'note') }
+    // Freeze the exact route/outcome/refs before awaiting the external attestation.
+    const accepted = await this.verifyRecovery({ expectedRevision, ...copy(data) })
+    if (accepted !== true) fail('HOST_RECOVERY_ATTESTATION_REQUIRED')
+    const result = this.mutate(expectedRevision, operationId, 'RECONCILED', state => {
+      if (canonical(state.active) !== canonical(before.state.active)) fail('RECOVERY_ACTIVE_CHANGED')
+      return copy(data)
+    }); return view(result, this.owner)
+  }
+}