dsh-bettertaskgraphs 0.0.0-stage → 0.2.2

package/store.mjs

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: GPL-3.0-only
+import fs from 'node:fs'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { GraphError, LIMITS, canonical, copy, validateDocument } from './core.mjs'
+
+const reject = (code, message = code) => { throw new GraphError(code, message) }
+const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino
+function checkRevision(expectedRevision, previous) {
+  if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0) reject('INVALID_REVISION')
+  if ((previous?.revision ?? 0) !== expectedRevision) reject('CAS_CONFLICT')
+}
+function checkNext(previous, next) {
+  validateDocument(next)
+  if (next.revision !== (previous?.revision ?? 0) + 1 || next.events.length !== (previous?.events.length ?? 0) + 1)
+    reject('ONE_EVENT_PER_CAS_REQUIRED')
+  if (previous && canonical(next.events.slice(0, -1)) !== canonical(previous.events)) reject('HISTORY_IMMUTABLE')
+}
+function syncDirectory(directory) {
+  const fd = fs.openSync(directory, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY)
+  try { fs.fsyncSync(fd) } finally { fs.closeSync(fd) }
+}
+function regularBoundedJson(file, maximum = LIMITS.bytes) {
+  let fd
+  try { fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW) }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error }
+  try {
+    const before = fs.fstatSync(fd)
+    if (!before.isFile() || before.size > maximum || before.size < 1) reject('INVALID_STORE_FILE')
+    const buffer = Buffer.alloc(Math.min(before.size + 1, maximum + 1))
+    let count = 0
+    while (count < buffer.length) {
+      const read = fs.readSync(fd, buffer, count, buffer.length - count, null)
+      if (!read) break
+      count += read
+    }
+    const after = fs.fstatSync(fd)
+    if (!sameFile(before, after) || count !== before.size || after.size !== count || before.mtimeMs !== after.mtimeMs)
+      reject('STORE_CHANGED_DURING_READ')
+    return JSON.parse(buffer.subarray(0, count).toString('utf8'))
+  } finally { fs.closeSync(fd) }
+}
+
+export class MemoryGraphStore {
+  constructor(document = null) { if (document) validateDocument(document); this.document = document ? copy(document) : null }
+  read() { return this.document ? copy(this.document) : null }
+  compareAndSwap(expectedRevision, update) {
+    const previous = this.read()
+    checkRevision(expectedRevision, previous)
+    const next = update(previous ? copy(previous) : null)
+    checkNext(previous, next)
+    this.document = copy(next)
+    return this.read()
+  }
+}
+
+// Explicit projectRoot and a new/private directory are mandatory. No default DB.
+// All components below projectRoot must be real directories, never symlinks.
+// This is application path validation, not isolation from a hostile same-user OS.
+export class FileGraphStore {
+  constructor({ projectRoot, directory, fileName = 'transaction-graph.json', maximumBytes = LIMITS.bytes,
+    validator = validateDocument, updateValidator = checkNext, readOnly = false }) {
+    if (!/^[a-z][a-z0-9.-]{0,63}$/.test(fileName) || !Number.isSafeInteger(maximumBytes)
+        || maximumBytes < 1 || maximumBytes > 12 * 1024 * 1024 || typeof validator !== 'function' || typeof updateValidator !== 'function') reject('INVALID_STORE_POLICY')
+    this.maximumBytes = maximumBytes; this.validator = validator; this.updateValidator = updateValidator
+    this.readOnly = readOnly
+    if (typeof projectRoot !== 'string' || typeof directory !== 'string'
+        || !path.isAbsolute(projectRoot) || !path.isAbsolute(directory)) reject('EXPLICIT_ABSOLUTE_STORE_ROOT_REQUIRED')
+    this.projectRoot = path.resolve(projectRoot)
+    this.directory = path.resolve(directory)
+    if (fs.realpathSync(this.projectRoot) !== this.projectRoot || !fs.lstatSync(this.projectRoot).isDirectory()) reject('INVALID_PROJECT_ROOT')
+    const relative = path.relative(this.projectRoot, this.directory)
+    if (!relative || relative.startsWith('..' + path.sep) || relative === '..' || path.isAbsolute(relative)) reject('STORE_OUTSIDE_PROJECT')
+    let cursor = this.projectRoot
+    for (const component of relative.split(path.sep)) {
+      cursor = path.join(cursor, component)
+      if (!readOnly) {
+        try { fs.mkdirSync(cursor, { mode: 0o700 }); syncDirectory(path.dirname(cursor)) }
+        catch (error) { if (error.code !== 'EEXIST') throw error }
+      }
+      const info = fs.lstatSync(cursor)
+      if (info.isSymbolicLink() || !info.isDirectory()) reject('STORE_SYMLINK_OR_NOT_DIRECTORY')
+    }
+    this.rootIdentity = fs.lstatSync(this.projectRoot)
+    this.directoryIdentity = fs.lstatSync(this.directory)
+    this.file = path.join(this.directory, fileName)
+    this.lock = path.join(this.directory, '.transaction-graph.lock')
+    this.checkDirectory()
+  }
+  checkDirectory() {
+    const root = fs.lstatSync(this.projectRoot), directory = fs.lstatSync(this.directory)
+    if (!sameFile(root, this.rootIdentity) || !sameFile(directory, this.directoryIdentity)
+        || !root.isDirectory() || !directory.isDirectory() || directory.isSymbolicLink()
+        || fs.realpathSync(this.projectRoot) !== this.projectRoot || fs.realpathSync(this.directory) !== this.directory)
+      reject('STORE_DIRECTORY_IDENTITY_CHANGED')
+    let cursor = this.projectRoot
+    for (const part of path.relative(this.projectRoot, this.directory).split(path.sep)) {
+      cursor = path.join(cursor, part)
+      const info = fs.lstatSync(cursor)
+      if (info.isSymbolicLink() || !info.isDirectory()) reject('STORE_SYMLINK_OR_NOT_DIRECTORY')
+    }
+  }
+  read() {
+    this.checkDirectory()
+    const document = regularBoundedJson(this.file, this.maximumBytes)
+    this.checkDirectory()
+    if (document) this.validator(document)
+    return document
+  }
+  compareAndSwap(expectedRevision, update) {
+    if (this.readOnly) reject('READ_ONLY_TRANSACTION_STORE')
+    this.checkDirectory()
+    try { fs.mkdirSync(this.lock, { mode: 0o700 }) }
+    catch (error) { if (error.code === 'EEXIST') reject('CAS_LOCK_BUSY_NO_AUTOMATIC_STEAL'); throw error }
+    const lockIdentity = fs.lstatSync(this.lock), token = randomUUID()
+    const ownerFile = path.join(this.lock, 'owner.json')
+    let temporary = null, temporaryIdentity = null, ownerWritten = false
+    try {
+      const ownerFd = fs.openSync(ownerFile, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600)
+      try { fs.writeFileSync(ownerFd, JSON.stringify({ token })); fs.fsyncSync(ownerFd); ownerWritten = true } finally { fs.closeSync(ownerFd) }
+      syncDirectory(this.lock)
+      const previous = this.read()
+      checkRevision(expectedRevision, previous)
+      const next = update(previous ? copy(previous) : null)
+      if (next && typeof next.then === 'function') reject('ASYNC_STORE_UPDATE_FORBIDDEN')
+      this.validator(next)
+      this.updateValidator(previous, next)
+      const content = JSON.stringify(next) + '\n'
+      if (Buffer.byteLength(content) > this.maximumBytes) reject('STORE_BYTE_LIMIT')
+      temporary = path.join(this.directory, '.transaction-graph-' + randomUUID() + '.tmp')
+      const fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600)
+      try { temporaryIdentity = fs.fstatSync(fd); fs.writeFileSync(fd, content); fs.fsyncSync(fd) } finally { fs.closeSync(fd) }
+      this.checkDirectory()
+      if (!sameFile(lockIdentity, fs.lstatSync(this.lock)) || regularBoundedJson(ownerFile)?.token !== token) reject('LOCK_OWNERSHIP_CHANGED')
+      // One rename commits plan, state and events together; no separate stale snapshot.
+      fs.renameSync(temporary, this.file); temporary = null
+      syncDirectory(this.directory)
+      return copy(next)
+    } finally {
+      if (temporary && temporaryIdentity) {
+        try { if (sameFile(temporaryIdentity, fs.lstatSync(temporary))) fs.unlinkSync(temporary) }
+        catch (error) { if (error.code !== 'ENOENT') throw error }
+      }
+      // Never recursively remove a lock or infer that a previous owner is dead.
+      if (!sameFile(lockIdentity, fs.lstatSync(this.lock)) || (ownerWritten && regularBoundedJson(ownerFile)?.token !== token))
+        reject('LOCK_OWNERSHIP_CHANGED')
+      if (ownerWritten) fs.unlinkSync(ownerFile)
+      fs.rmdirSync(this.lock)
+      syncDirectory(this.directory)
+    }
+  }
+}

package/tools.mjs

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: GPL-3.0-only
+import { createHash } from 'node:crypto'
+import { GraphError, copy } from './core.mjs'
+
+export const TOOL_NAMES = Object.freeze(['transaction_graph_read', 'transaction_graph_create',
+  'transaction_graph_begin', 'transaction_graph_finish', 'transaction_graph_skip'])
+const evidence = { type: 'array', items: { type: 'object', properties: {
+  kind: { type: 'string', required: true, enum: ['session_event', 'tool_result', 'artifact'] },
+  ref: { type: 'string', required: true }, sha256: { type: 'string' },
+}, additionalProperties: false } }
+const revision = { type: 'integer', required: true, description: 'Exact revision from the last program-generated read.' }
+const definition = { type: 'object', required: true, properties: {
+  title: { type: 'string', required: true },
+  nodes: { type: 'array', required: true, items: { type: 'object', properties: {
+    key: { type: 'string', required: true }, kind: { type: 'string', required: true, enum: ['container', 'leaf'] },
+    label: { type: 'string', required: true }, parent: { type: 'string' },
+    switchCases: { type: 'array', items: { type: 'string' } },
+  }, additionalProperties: false } },
+  edges: { type: 'array', required: true, items: { type: 'object', properties: {
+    kind: { type: 'string', required: true, enum: ['prerequisite', 'route', 'case'] },
+    from: { type: 'string', required: true }, to: { type: 'string', required: true },
+    outcome: { type: 'string', enum: ['complete', 'incomplete'] }, case: { type: 'string' },
+  }, additionalProperties: false } },
+}, additionalProperties: false }
+
+// Mandatory adapter port. No fallback infers successful tool execution from a ref.
+// Implementations must durably reserve one intent, commit only after real successful
+// tool/result AND every enclosing PTC parent, and CAS-check again at that boundary.
+// A restarted adapter must reconcile persisted pending intents, never replay them.
+export class UnconnectedHostPort {
+  authorize() { throw new GraphError('DSH_INTEGRATION_NOT_RUN') }
+  read() { throw new GraphError('DSH_INTEGRATION_NOT_RUN') }
+  stageMutation() { throw new GraphError('DSH_INTEGRATION_NOT_RUN') }
+}
+
+function operationId(scope, callId) {
+  if (typeof scope !== 'string' || !scope || scope.length > 512 || typeof callId !== 'string' || !callId || callId.length > 512)
+    throw new GraphError('HOST_SCOPE_AND_CALL_ID_REQUIRED')
+  return 'op_' + createHash('sha256').update(JSON.stringify([scope, callId])).digest('hex')
+}
+function toolArguments(operation, args) {
+  const allowed = { read: [], create: ['expectedRevision', 'definition'], begin: ['expectedRevision', 'choice'],
+    finish: ['expectedRevision', 'outcome', 'caseIndex', 'evidence', 'note', 'disposition'],
+    skip: ['expectedRevision', 'choice', 'evidence', 'note'] }[operation]
+  if (!args || typeof args !== 'object' || Array.isArray(args) || Object.keys(args).some(key => !allowed.includes(key)))
+    throw new GraphError('UNEXPECTED_TOOL_ARGUMENT')
+  if (operation !== 'read' && (!Number.isSafeInteger(args.expectedRevision) || args.expectedRevision < 0))
+    throw new GraphError('INVALID_REVISION')
+  if (['begin', 'skip'].includes(operation) && (!Number.isSafeInteger(args.choice) || args.choice < 0))
+    throw new GraphError('INVALID_CHOICE')
+  return copy(args)
+}
+
+export function createToolDefinitions({ defineTool, hostPort = new UnconnectedHostPort() }) {
+  if (typeof defineTool !== 'function') throw new GraphError('REAL_DSH_DEFINE_TOOL_REQUIRED')
+  const definitions = [
+    { name: TOOL_NAMES[0], operation: 'read', parameters: {},
+      description: 'Read program-generated transaction IDs, revision, legal begin/skip choices, active/recovery state and parent summaries. Completion is not Goal completion.' },
+    { name: TOOL_NAMES[1], operation: 'create', parameters: { expectedRevision: revision, definition },
+      description: 'Propose one immutable bounded transaction graph. Declare immediate prerequisites and keep independent conditions. Omit repeated prerequisites already implied by an unconditional chain of leaf tasks. Supply local node keys; the program generates durable IDs. Switch cases require explicit host policy. A staged proposal is not yet committed.' },
+    { name: TOOL_NAMES[2], operation: 'begin', parameters: { expectedRevision: revision, choice: { type: 'integer', required: true } },
+      description: 'Stage the displayed legal choice index as the sole active leaf. Do not copy IDs or invent a next transaction. Restarted ACTIVE requires host reconciliation.' },
+    { name: TOOL_NAMES[3], operation: 'finish', parameters: { expectedRevision: revision,
+      outcome: { type: 'string', required: true, enum: ['complete', 'incomplete'] }, caseIndex: { type: 'integer' },
+      disposition: { type: 'string', enum: ['SKIPPED_NOT_RUN', 'UNSATISFIED', 'FAILED'], description: 'Required for incomplete: explicit non-execution, unsatisfied outcome, or real known terminal failure. UNKNOWN never qualifies.' },
+      evidence, note: { type: 'string', required: true } },
+      description: 'Stage complete or explicit incomplete disposition for the active attempt. Any unresolved owned work blocks every finish, including empty references. FAILED requires real terminal failure evidence; SKIPPED_NOT_RUN preserves non-execution. Complete requires successful references. Goal success is independent.' },
+    { name: TOOL_NAMES[4], operation: 'skip', parameters: { expectedRevision: revision, choice: { type: 'integer', required: true },
+      evidence, note: { type: 'string', required: true } },
+      description: 'Stage a displayed pending skip choice when no leaf is active. A skip neither satisfies prerequisites nor activates completion/incompletion routes.' },
+  ]
+  return definitions.map(({ operation, ...tool }) => defineTool({ ...tool,
+    ...(operation === 'read' ? { projectPlanCapability: 'read_or_protocol' } : {}),
+    output: { schema: { type: 'object', properties: {}, additionalProperties: true },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }] },
+    execute: async (args, exec) => {
+      exec.signal?.throwIfAborted()
+      if (!exec.agent || typeof exec.callId !== 'string') throw new GraphError('REAL_AGENT_TOOL_EXECUTION_REQUIRED')
+      const checkedArguments = toolArguments(operation, args)
+      // The real port must verify current initiator, running agent, active session
+      // and permission scope using actual DSH APIs, not model-supplied fields.
+      const authority = await hostPort.authorize(exec, { operation })
+      if (!authority || authority.currentInitiatorVerified !== true || authority.agentId !== exec.agent.id)
+        throw new GraphError('HOST_OWNERSHIP_NOT_VERIFIED')
+      exec.signal?.throwIfAborted()
+      if (operation === 'read') return hostPort.read(authority, exec)
+      const result = await hostPort.stageMutation({ operation, arguments: checkedArguments,
+        operationId: operationId(authority.sessionScope, exec.callId), authority, execution: exec })
+      if (result?.state !== 'PENDING_HOST_COMMIT') throw new GraphError('HOST_MUST_STAGE_NOT_PRETEND_COMMIT')
+      return { ...result, goalReached: false,
+        instruction: 'Await the real successful tool/PTC commit boundary, then read the committed revision. Pending is not completion.' }
+    },
+  }))
+}

package/view-model.mjs

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: GPL-3.0-only
+// Only reduce a prerequisite that is already implied by a chain of leaf
+// prerequisites. Entering a conditional task can change branch participation.
+function chainEdges(graph) {
+  const leaves = new Set(graph.nodes.filter(node => node.kind === 'leaf').map(node => node.id))
+  const prerequisites = new Map()
+  const conditional = new Set()
+  for (const edge of graph.edges) {
+    if (edge.kind !== 'prerequisite') {
+      conditional.add(edge.to)
+      continue
+    }
+    const sources = prerequisites.get(edge.to) ?? []
+    sources.push(edge.from)
+    prerequisites.set(edge.to, sources)
+  }
+  return graph.edges.filter(edge => {
+    if (edge.kind !== 'prerequisite' || !leaves.has(edge.from)) return true
+    const sources = prerequisites.get(edge.to)
+    if (sources.length < 2) return true
+    const pending = sources.filter(id => id !== edge.from)
+    const seen = new Set()
+    while (pending.length) {
+      const id = pending.pop()
+      if (id === edge.from) return false
+      if (!leaves.has(id) || conditional.has(id) || seen.has(id)) continue
+      seen.add(id)
+      pending.push(...(prerequisites.get(id) ?? []))
+    }
+    return true
+  })
+}
+
+// Host supplies legal choices. The browser only organizes them for display.
+export function graphPresentation(graph, selectedId) {
+  const nodes = new Map(graph.nodes.map(node => [node.id, node]))
+  const children = new Map()
+  for (const node of graph.nodes) {
+    const siblings = children.get(node.parent) ?? []
+    siblings.push(node)
+    children.set(node.parent, siblings)
+  }
+  const active = graph.active ? nodes.get(graph.active.nodeId) ?? null : null
+  const legal = new Set(graph.legalNext.map(choice => choice.id))
+  const selected = nodes.get(selectedId) ?? active ?? nodes.get(graph.legalNext[0]?.id) ?? children.get(null)?.[0] ?? null
+  const conditionIds = new Set(chainEdges(graph).filter(edge => edge.to === selected?.id).map(edge => edge.from))
+  const conditions = [...conditionIds].map(id => nodes.get(id)).filter(Boolean)
+  const allLeaves = graph.nodes.filter(node => node.kind === 'leaf')
+  const leaves = allLeaves.filter(node => node.branchState !== 'NOT_SELECTED')
+  const count = status => leaves.filter(node => node.status === status).length
+  return {
+    nodes, children, active, legal, selected, conditions,
+    progress: {
+      total: leaves.length, complete: count('COMPLETE'), incomplete: count('INCOMPLETE'),
+      skipped: count('SKIPPED'), inactive: count('INACTIVE'), excluded: allLeaves.length - leaves.length, ready: legal.size,
+    },
+  }
+}
+
+function branchEdgeState(edge, source, target) {
+  if (source.branchState === 'NOT_SELECTED' || target.branchState === 'NOT_SELECTED') return 'branchExcluded'
+  if (edge.kind === 'prerequisite') {
+    if (source.status === 'COMPLETE') return 'prerequisiteMet'
+    if (source.status === 'INCOMPLETE' || source.status === 'SKIPPED' || source.blocked) return 'blocked'
+    return 'edgeWaiting'
+  }
+  const selected = source.selectedBranch
+  if (selected?.targetId === edge.to && (edge.kind === 'route' ? selected.outcome === edge.outcome : selected.case === edge.case))
+    return 'branchChosen'
+  return selected || source.status === 'SKIPPED' ? 'branchExcluded' : 'edgeWaiting'
+}
+
+// Rank by explicit dependencies. Containers stay in the tree unless they
+// participate in a dependency. A leaf still shows which container it belongs to.
+export function branchLayout(graph) {
+  const nodesById = new Map(graph.nodes.map(node => [node.id, node]))
+  const edges = chainEdges(graph).filter(edge => nodesById.has(edge.from) && nodesById.has(edge.to))
+  const connected = new Set(edges.flatMap(edge => [edge.from, edge.to]))
+  const nodes = graph.nodes.filter(node => node.kind === 'leaf' || connected.has(node.id))
+  const outgoing = new Map(nodes.map(node => [node.id, []]))
+  const incoming = new Map(nodes.map(node => [node.id, []]))
+  for (const edge of edges) {
+    outgoing.get(edge.from).push(edge)
+    incoming.get(edge.to).push(edge)
+  }
+  const incomingCount = new Map(nodes.map(node => [node.id, incoming.get(node.id).length]))
+  const rank = new Map(nodes.map(node => [node.id, 0]))
+  const queue = nodes.filter(node => incomingCount.get(node.id) === 0).map(node => node.id)
+  for (const id of queue) {
+    for (const { to: target } of outgoing.get(id)) {
+      rank.set(target, Math.max(rank.get(target), rank.get(id) + 1))
+      const remaining = incomingCount.get(target) - 1
+      incomingCount.set(target, remaining)
+      if (remaining === 0) queue.push(target)
+    }
+  }
+  const columns = Array.from({ length: 1 + Math.max(0, ...rank.values()) }, () => [])
+  for (const node of nodes) columns[rank.get(node.id)].push(node)
+
+  const padding = 26, cardWidth = 194, cardHeight = 84, columnGap = 104, rowGap = 26
+  const rows = Math.max(1, ...columns.map(column => column.length))
+  const bodyHeight = rows * (cardHeight + rowGap) - rowGap
+  const cards = columns.flatMap((column, index) => column.map((node, row) => ({
+    node,
+    group: nodesById.get(node.parent)?.label,
+    column: index,
+    additionalPrerequisites: 0,
+    x: padding + index * (cardWidth + columnGap),
+    y: padding + (rows - column.length) * (cardHeight + rowGap) / 2 + row * (cardHeight + rowGap),
+  })))
+  const cardById = new Map(cards.map(card => [card.node.id, card]))
+  const drawnEdges = new Set(edges.filter(edge => {
+    const source = cardById.get(edge.from), target = cardById.get(edge.to)
+    if (edge.kind !== 'prerequisite' || target.column === source.column + 1) return true
+    // The entry list still shows independent prerequisites that skip a column.
+    target.additionalPrerequisites += 1
+    return false
+  }))
+  for (const [id, group] of outgoing)
+    outgoing.set(id, group.filter(edge => drawnEdges.has(edge)).sort((a, b) => cardById.get(a.to).y - cardById.get(b.to).y))
+  for (const [id, group] of incoming)
+    incoming.set(id, group.filter(edge => drawnEdges.has(edge)).sort((a, b) => cardById.get(a.from).y - cardById.get(b.from).y))
+  const portOffset = (group, edge) => (group.indexOf(edge) - (group.length - 1) / 2) * Math.min(13, 52 / group.length)
+  const bendOffset = (group, edge) => 12 + 28 * (group.indexOf(edge) + 1) / (group.length + 1)
+  const pairKey = edge => JSON.stringify([edge.from, edge.to])
+  const parallel = new Map()
+  for (const edge of drawnEdges) {
+    const pair = pairKey(edge)
+    parallel.set(pair, (parallel.get(pair) ?? 0) + 1)
+  }
+  let laneCount = 0
+  const wires = [...drawnEdges].map(edge => {
+    const from = cardById.get(edge.from), to = cardById.get(edge.to)
+    const exits = outgoing.get(edge.from), entries = incoming.get(edge.to)
+    const startX = from.x + cardWidth, endX = to.x - 2
+    const startY = from.y + cardHeight / 2 + portOffset(exits, edge)
+    const endY = to.y + cardHeight / 2 + portOffset(entries, edge)
+    const state = branchEdgeState(edge, from.node, to.node)
+    const wire = { edge, from: from.node, to: to.node, state,
+      key: JSON.stringify([edge.from, edge.to, edge.kind, edge.outcome ?? edge.case]),
+      showLabel: edge.kind !== 'prerequisite' && (parallel.get(pairKey(edge)) === 1 || state === 'branchChosen') }
+    if (to.column - from.column > 1) {
+      // Route rank-skipping edges below the cards so they do not cross a task.
+      const laneY = padding + bodyHeight + 22 + laneCount++ * 16
+      const exitX = startX + bendOffset(exits, edge), entryX = endX - bendOffset(entries, edge)
+      return { ...wire, path: `M ${startX} ${startY} H ${exitX} V ${laneY} H ${entryX} V ${endY} H ${endX}`,
+        labelX: (startX + endX) / 2, labelY: laneY - 5 }
+    }
+    return { ...wire, path: `M ${startX} ${startY} C ${startX + 40} ${startY}, ${endX - 40} ${endY}, ${endX} ${endY}`,
+      labelX: (startX + endX) / 2, labelY: (startY + endY) / 2 - 7 }
+  })
+  return {
+    cards, wires, cardWidth, cardHeight,
+    width: columns.length * (cardWidth + columnGap) - columnGap + 2 * padding,
+    height: bodyHeight + 2 * padding + laneCount * 16 + (laneCount ? 12 : 0),
+  }
+}

package/work-policy.mjs

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: GPL-3.0-only
+import { GraphError, canonical } from './core.mjs'
+const fail = code => { throw new GraphError(code) }
+export const workKey = row => `${row.rootCallId ?? row.callId}:${row.callSeq ?? row.seq}`
+// Only this protocol's exact five names are non-work for count/disposition.
+// UNKNOWN/PENDING tracking deliberately has no name-based exemption.
+const protocolNames = new Set(['transaction_graph_read', 'transaction_graph_create', 'transaction_graph_begin', 'transaction_graph_finish', 'transaction_graph_skip'])
+export const administrative = name => protocolNames.has(name)
+
+// ToolExecution.parent/token are registry-owned identities, never call-name guesses.
+export function ownedExecutionChain(exec, running) {
+  const rows = [...running], ancestors = new Set(), callIds = new Set()
+  let cursor = exec
+  for (let depth = 0; depth <= 32; depth++) {
+    const exact = rows.filter(row => row.token === cursor.token && row.callId === cursor.callId)
+    if (!cursor.token || exact.length !== 1 || exact[0].agent !== exec.agent || exact[0].rootCallId !== exec.rootCallId
+        || ancestors.has(cursor.token)) fail('OWNED_EXECUTION_ANCESTRY_UNAVAILABLE')
+    cursor = exact[0]; ancestors.add(cursor.token); callIds.add(cursor.callId)
+    if (cursor.parent === undefined) {
+      if (cursor.callId !== exec.rootCallId) fail('OWNED_EXECUTION_ROOT_MISMATCH')
+      const others = rows.filter(row => !ancestors.has(row.token))
+      return { ancestors, callIds, others }
+    }
+    const parent = rows.filter(row => row.token === cursor.parent)
+    if (parent.length !== 1) fail('OWNED_EXECUTION_PARENT_MISSING_OR_DUPLICATE')
+    cursor = parent[0]
+  }
+  fail('OWNED_EXECUTION_DEPTH_LIMIT')
+}
+
+export function unresolvedWork(state, activeProof, excludedCallIds = new Set()) {
+  if (!activeProof) return []
+  const acknowledged = new Set(state.acknowledgedWork.map(workKey)), result = new Map()
+  for (const row of state.uncertainties) {
+    if (!acknowledged.has(workKey(row)) && (row.rootResultSeq > activeProof.beginResultSeq || row.callSeq > activeProof.beginResultSeq))
+      result.set(workKey(row), { ...row, state: 'UNKNOWN' })
+  }
+  // A settled UNKNOWN child cannot hide inside the current read/finish root,
+  // whose own result has not yet committed. Do not wait for proof-index entry.
+  for (const row of state.dispatches) {
+    const root = state.calls[row.rootCallId]
+    if (root && row.outcome === 'UNKNOWN' && row.seq > activeProof.beginResultSeq) {
+      const work = { rootCallId: row.rootCallId, callSeq: root.seq, rootResultSeq: null, eventDigest: root.eventDigest }
+      if (!acknowledged.has(workKey(work))) result.set(workKey(work), { ...work, state: 'UNKNOWN' })
+    }
+  }
+  for (const [callId, row] of Object.entries(state.calls)) {
+    const work = { rootCallId: callId, callSeq: row.seq, rootResultSeq: null, eventDigest: row.eventDigest }
+    if (row.seq > activeProof.beginResultSeq && !excludedCallIds.has(callId) && !acknowledged.has(workKey(work)))
+      result.set(workKey(work), { ...work, state: 'PENDING' })
+  }
+  return [...result.values()]
+}
+
+const failedFact = fact => fact.outcome === 'FAIL' || fact.isError === true && fact.outcome === 'UNVERIFIED'
+export const knownFailure = proof => failedFact({ outcome: proof.ownOutcome, isError: proof.isError })
+  || proof.ancestorOutcomes.some(failedFact)
+export const notRunFact = proof => proof.ownOutcome === 'NOT_RUN' || proof.ancestorOutcomes.some(row => row.outcome === 'NOT_RUN')
+
+export function incompleteDisposition({ requested, state, activeProof, evidence }) {
+  if (!['SKIPPED_NOT_RUN', 'UNSATISFIED', 'FAILED'].includes(requested)) fail('EXPLICIT_INCOMPLETE_DISPOSITION_REQUIRED')
+  if (!activeProof) fail('ACTIVE_BEGIN_PROOF_REQUIRED')
+  const facts = evidence.filter(row => row.kind !== 'artifact')
+  if (facts.some(row => row.qualification === 'UNKNOWN' || row.ownOutcome === 'UNKNOWN')) fail('UNKNOWN_EVIDENCE_REQUIRES_TRUSTED_RECONCILIATION')
+  if (requested === 'FAILED' && !facts.some(knownFailure)) fail('FAILED_DISPOSITION_REQUIRES_KNOWN_TERMINAL_FAILURE')
+  if (requested === 'SKIPPED_NOT_RUN') {
+    const zeroWork = state.workStarted === activeProof.workStartedAtBegin
+    const noneExecuted = state.workExecuted === activeProof.workExecutedAtBegin
+    if (!noneExecuted || facts.some(knownFailure) || !zeroWork && !facts.some(notRunFact)) fail('NOT_RUN_DISPOSITION_CANNOT_HIDE_EXECUTED_WORK')
+  }
+  return requested
+}
+
+export function sameWorkSnapshot(a, b) { return canonical(a) === canonical(b) }