@hypercarrier/pi-team-durable 0.0.0-stage → 0.1.0-rc.2

package/dist/authority/graph-control.js

@@ -0,0 +1,1009 @@
+// Ported through the durable prototype; verified against Pi Team Bright 0.24.0-rc.7 (MIT).
+// Changes: injected clock, local imports, explicit constructor fields.
+import { createHash } from "node:crypto";
+import { taskVersionRef } from "./task-version-ref.js";
+/**
+ * Executable first contract for graph-native Task control.
+ *
+ * The upstream transition design lives in Pi Team Bright's
+ * docs/projects/dag-native/graph-control-transition-spec.json.
+ * This module has no Beads, Pi, delivery, or presentation dependency.
+ */
+export const GRAPH_CONTROL_MAX_FAILURE_TRAVERSALS = 8;
+export const GRAPH_CONTROL_TASK_STATES = [
+    "dependency_waiting",
+    "ready",
+    "in_progress",
+    "blocked",
+    "goal_failed",
+    "goal_achieved",
+    "cancelled",
+];
+export class GraphControlRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "GraphControlRefusal";
+    }
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, nested]) => [key, canonical(nested)]));
+}
+function digest(value) {
+    return createHash("sha256").update(JSON.stringify(canonical(value))).digest("hex");
+}
+function clone(value) {
+    return structuredClone(value);
+}
+function requireText(value, label) {
+    if (!value?.trim())
+        throw new GraphControlRefusal("evidence_required", `${label} must not be empty.`);
+    return value;
+}
+function graphVersion(value) {
+    return `g_${digest(value).slice(0, 16)}`;
+}
+function semanticDefinition(definition) {
+    return {
+        key: definition.key,
+        title: definition.title,
+        goal: definition.goal,
+        assignee: definition.assignee,
+        needs: definition.needs,
+        onGoalFailed: definition.onGoalFailed ?? null,
+    };
+}
+/**
+ * Small event-backed reference authority for deterministic Task graph control.
+ * External work is a transition command; all graph movement runs synchronously
+ * before that command returns.
+ */
+export class GraphTaskController {
+    graphRevisions;
+    events;
+    receipts;
+    commandRecordedAt;
+    derivedCache;
+    clock;
+    constructor(snapshot, clock = () => new Date()) {
+        this.clock = clock;
+        if (snapshot && snapshot.schema !== "pi-team-bright-graph-control/1") {
+            throw new GraphControlRefusal("invalid_graph", `Unsupported snapshot schema ${String(snapshot.schema)}.`);
+        }
+        this.graphRevisions = clone(snapshot?.graphRevisions ?? []);
+        this.events = clone(snapshot?.events ?? []);
+        this.receipts = new Map((snapshot?.receipts ?? []).map(receipt => [receipt.operationId, clone(receipt)]));
+    }
+    static recover(snapshot, clock) {
+        try {
+            validateSnapshot(snapshot, 0, validateGraphRevision);
+        }
+        catch (error) {
+            if (error instanceof GraphControlRefusal)
+                throw error;
+            throw new GraphControlRefusal("invalid_graph", `Graph authority snapshot is malformed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return new GraphTaskController(snapshot, clock);
+    }
+    snapshot() {
+        return {
+            schema: "pi-team-bright-graph-control/1",
+            graphRevisions: clone(this.graphRevisions),
+            events: clone(this.events),
+            receipts: [...this.receipts.values()].map(clone),
+        };
+    }
+    currentGraphVersion() {
+        return this.currentRevision()?.version;
+    }
+    hasOperationReceipt(operationId) {
+        return this.receipts.has(operationId);
+    }
+    applyGraph(input) {
+        return this.command(input.operationId, { command: "apply_graph", ...input }, () => {
+            const priorRevision = this.currentRevision();
+            if (!priorRevision && input.expectedGraphVersion !== undefined) {
+                throw new GraphControlRefusal("graph_version_conflict", "The first graph apply must not include an expected version.");
+            }
+            if (priorRevision && input.expectedGraphVersion !== priorRevision.version) {
+                throw new GraphControlRefusal("graph_version_conflict", `Graph changed; expected ${String(input.expectedGraphVersion)}, current ${priorRevision.version}.`);
+            }
+            const normalized = normalizeAndValidate(input.tasks);
+            const priorById = new Map((priorRevision?.tasks ?? []).map(task => [task.key, task]));
+            const revisionSequence = this.nextSequence();
+            const tasks = normalized.map(definition => {
+                const prior = priorById.get(definition.key);
+                const sameMeaning = prior && digest(semanticDefinition(prior)) === digest(semanticDefinition(definition));
+                return {
+                    ...definition,
+                    lineage: sameMeaning
+                        ? prior.lineage
+                        : digest({ task: semanticDefinition(definition), introducedAt: revisionSequence }),
+                };
+            });
+            const version = graphVersion({ previous: priorRevision?.version ?? null, tasks });
+            const attemptsBefore = this.readAttempts();
+            const activeBefore = new Map(attemptsBefore
+                .filter(attempt => attempt.state === "in_progress" || attempt.state === "blocked")
+                .map(attempt => [attempt.taskId, attempt.id]));
+            const nextById = new Map(tasks.map(task => [task.key, task]));
+            const directlyChanged = new Set();
+            for (const [taskId, prior] of priorById) {
+                if (nextById.get(taskId)?.lineage !== prior.lineage)
+                    directlyChanged.add(taskId);
+            }
+            for (const [taskId, next] of nextById) {
+                if (priorById.get(taskId)?.lineage !== next.lineage)
+                    directlyChanged.add(taskId);
+            }
+            const affected = new Set([
+                ...reverseClosure([...directlyChanged], priorRevision?.tasks ?? []),
+                ...reverseClosure([...directlyChanged], tasks),
+            ]);
+            this.graphRevisions.push({
+                sequence: revisionSequence,
+                version,
+                tasks,
+                ...(this.commandRecordedAt ? { recorded_at: this.commandRecordedAt } : {}),
+            });
+            for (const taskId of [...affected].sort()) {
+                const attemptId = activeBefore.get(taskId)
+                    ?? attemptsBefore.findLast(attempt => attempt.taskId === taskId && attempt.current)?.id;
+                if (attemptId)
+                    this.append({
+                        kind: "attempt_superseded",
+                        operationId: input.operationId,
+                        attemptId,
+                        reason: "graph_revised",
+                    });
+            }
+            const currentTasks = this.readTasks();
+            return {
+                kind: "graph_applied",
+                operationId: input.operationId,
+                graphVersion: version,
+                tasks: currentTasks,
+                readyTaskIds: readyIds(currentTasks),
+            };
+        });
+    }
+    transition(input) {
+        return this.command(input.operationId, { command: "transition", ...input }, () => {
+            const task = this.readTask(input.taskId);
+            if (task.version !== input.expectedVersion) {
+                throw new GraphControlRefusal("task_version_conflict", `Task ${task.id} changed; expected ${input.expectedVersion}, current ${task.version}.`);
+            }
+            if (!input.transition && !input.currentContext?.trim()) {
+                throw new GraphControlRefusal("invalid_transition", "A Task command requires a transition or nonempty current context.");
+            }
+            let failureTraversal;
+            switch (input.transition) {
+                case "claim":
+                    this.claim(task, input);
+                    break;
+                case "block":
+                    this.block(task, input);
+                    break;
+                case "resume":
+                    this.resume(task, input);
+                    break;
+                case "goal_achieved":
+                case "goal_failed":
+                    failureTraversal = this.complete(task, input);
+                    break;
+                case "cancel":
+                    this.cancel(task, input);
+                    break;
+            }
+            if (input.currentContext?.trim()) {
+                this.append({
+                    kind: "task_context_updated",
+                    operationId: input.operationId,
+                    taskId: task.id,
+                    taskLineage: this.definition(task.id).lineage,
+                    currentContext: input.currentContext,
+                });
+            }
+            const tasks = this.readTasks();
+            return {
+                kind: "task_transitioned",
+                operationId: input.operationId,
+                transition: input.transition ?? "context_updated",
+                task: tasks.find(candidate => candidate.id === input.taskId),
+                readyTaskIds: readyIds(tasks),
+                ...(failureTraversal ? { failureTraversal } : {}),
+            };
+        });
+    }
+    readTask(taskId) {
+        const derived = this.derivedGraph().get(taskId);
+        if (!derived)
+            throw new GraphControlRefusal("task_not_found", `Task ${taskId} is not in the current graph.`);
+        return this.toView(derived);
+    }
+    readTasks() {
+        return [...this.derivedGraph().values()].map(task => this.toView(task)).sort((left, right) => left.id.localeCompare(right.id));
+    }
+    readAttempts(taskId) {
+        const currentTaskIds = new Set(this.currentRevision()?.tasks.map(task => task.key) ?? []);
+        const currentAttemptIds = new Set(this.readTasks().flatMap(task => {
+            if (task.state.kind === "in_progress" || task.state.kind === "blocked" || task.state.kind === "goal_achieved") {
+                return [task.state.attemptId];
+            }
+            if (task.state.kind === "goal_failed" && "attemptId" in task.state)
+                return [task.state.attemptId];
+            return [];
+        }));
+        return [...this.attemptFolds().values()]
+            .filter(attempt => !taskId || attempt.started.taskId === taskId)
+            .sort((left, right) => left.started.sequence - right.started.sequence)
+            .map(attempt => {
+            const blocked = attempt.blocked && (!attempt.resumed || attempt.blocked.sequence > attempt.resumed.sequence);
+            const staleLineage = !currentTaskIds.has(attempt.started.taskId)
+                || this.definition(attempt.started.taskId).lineage !== attempt.started.taskLineage;
+            const state = attempt.completed
+                ? "completed"
+                : attempt.cancellation
+                    ? "cancelled"
+                    : attempt.superseded || staleLineage
+                        ? "superseded"
+                        : blocked
+                            ? "blocked"
+                            : "in_progress";
+            return {
+                id: attempt.started.attemptId,
+                taskId: attempt.started.taskId,
+                ordinal: attempt.started.ordinal,
+                graphVersion: attempt.started.graphVersion,
+                taskLineage: attempt.started.taskLineage,
+                activationKey: attempt.started.activationKey,
+                inputAttemptIds: clone(attempt.started.inputAttemptIds),
+                assignee: attempt.started.assignee,
+                state,
+                current: currentAttemptIds.has(attempt.started.attemptId),
+                ...(attempt.completed ? { outcome: attempt.completed.outcome, evidence: attempt.completed.evidence } : {}),
+                ...(blocked ? { evidence: attempt.blocked.evidence } : {}),
+            };
+        });
+    }
+    selectReadyFrontier() {
+        const occupied = new Set(this.readTasks().flatMap(task => task.state.kind === "in_progress" ? [task.assignee] : []));
+        const selected = [];
+        for (const task of this.readTasks()) {
+            if (task.state.kind !== "ready" || occupied.has(task.assignee))
+                continue;
+            selected.push(task);
+            occupied.add(task.assignee);
+        }
+        return selected;
+    }
+    trace() {
+        return {
+            graphRevisions: clone(this.graphRevisions),
+            tasks: this.readTasks(),
+            attempts: this.readAttempts(),
+            events: clone(this.events),
+        };
+    }
+    claim(task, input) {
+        if (task.state.kind !== "ready")
+            this.invalid(task, "claim");
+        this.assertWorker(task, input);
+        const occupied = this.readTasks().find(candidate => candidate.assignee === task.assignee && candidate.state.kind === "in_progress");
+        if (occupied) {
+            throw new GraphControlRefusal("worker_occupied", `Worker ${task.assignee} already has in-progress Task ${occupied.id}.`);
+        }
+        const derived = this.derivedGraph().get(task.id);
+        const revision = this.currentRevision();
+        const ordinal = derived.attemptsStarted + 1;
+        this.append({
+            kind: "attempt_started",
+            operationId: input.operationId,
+            attemptId: `${task.id}@${ordinal}`,
+            taskId: task.id,
+            ordinal,
+            graphVersion: revision.version,
+            taskLineage: derived.definition.lineage,
+            activationKey: derived.activationKey,
+            inputAttemptIds: clone(derived.inputAttemptIds),
+            assignee: task.assignee,
+        });
+    }
+    block(task, input) {
+        if (task.state.kind !== "in_progress")
+            this.invalid(task, "block");
+        this.assertWorker(task, input);
+        this.append({
+            kind: "attempt_blocked",
+            operationId: input.operationId,
+            attemptId: task.state.attemptId,
+            evidence: requireText(input.evidence, "Blocker evidence"),
+        });
+    }
+    resume(task, input) {
+        if (task.state.kind !== "blocked")
+            this.invalid(task, "resume");
+        this.assertWorker(task, input);
+        const occupied = this.readTasks().find(candidate => candidate.assignee === task.assignee && candidate.state.kind === "in_progress");
+        if (occupied) {
+            throw new GraphControlRefusal("worker_occupied", `Worker ${task.assignee} already has in-progress Task ${occupied.id}.`);
+        }
+        this.append({
+            kind: "attempt_resumed",
+            operationId: input.operationId,
+            attemptId: task.state.attemptId,
+        });
+    }
+    complete(task, input) {
+        if (task.state.kind !== "in_progress")
+            this.invalid(task, input.transition ?? "complete");
+        this.assertWorker(task, input);
+        const evidence = requireText(input.evidence, "Goal outcome evidence");
+        this.append({
+            kind: "attempt_completed",
+            operationId: input.operationId,
+            attemptId: task.state.attemptId,
+            outcome: input.transition,
+            evidence,
+        });
+        if (input.transition === "goal_achieved")
+            return undefined;
+        const definition = this.definition(task.id);
+        const edge = definition.onGoalFailed;
+        if (!edge)
+            return undefined;
+        const priorTraversals = this.events.filter((event) => event.kind === "failure_edge_traversed"
+            && event.sourceTaskId === task.id
+            && event.sourceTaskLineage === definition.lineage).length;
+        if (priorTraversals >= edge.maxTraversals) {
+            this.append({
+                kind: "failure_edge_exhausted",
+                operationId: input.operationId,
+                sourceTaskId: task.id,
+                sourceTaskLineage: definition.lineage,
+                sourceAttemptId: task.state.attemptId,
+                targetTaskId: edge.target,
+                traversals: priorTraversals,
+                reason: "limit_reached",
+            });
+            return undefined;
+        }
+        const target = this.definition(edge.target);
+        const targetCancelled = this.events.findLast((event) => event.kind === "task_cancelled"
+            && event.taskId === edge.target
+            && event.taskLineage === target.lineage);
+        if (targetCancelled) {
+            this.append({
+                kind: "failure_edge_exhausted",
+                operationId: input.operationId,
+                sourceTaskId: task.id,
+                sourceTaskLineage: definition.lineage,
+                sourceAttemptId: task.state.attemptId,
+                targetTaskId: edge.target,
+                traversals: priorTraversals,
+                reason: "target_cancelled",
+            });
+            return undefined;
+        }
+        const attemptsBefore = this.readAttempts();
+        const activeBefore = new Map(attemptsBefore
+            .filter(attempt => attempt.state === "in_progress" || attempt.state === "blocked")
+            .map(attempt => [attempt.taskId, attempt.id]));
+        const traversal = priorTraversals + 1;
+        this.append({
+            kind: "failure_edge_traversed",
+            operationId: input.operationId,
+            sourceTaskId: task.id,
+            sourceTaskLineage: definition.lineage,
+            sourceAttemptId: task.state.attemptId,
+            targetTaskId: edge.target,
+            targetTaskLineage: target.lineage,
+            traversal,
+        });
+        for (const affectedTaskId of reverseClosure([edge.target], this.currentRevision().tasks)) {
+            const attemptId = activeBefore.get(affectedTaskId)
+                ?? attemptsBefore.findLast(attempt => attempt.taskId === affectedTaskId && attempt.current)?.id;
+            if (attemptId && attemptId !== task.state.attemptId)
+                this.append({
+                    kind: "attempt_superseded",
+                    operationId: input.operationId,
+                    attemptId,
+                    reason: "repair_requested",
+                });
+        }
+        return { sourceTaskId: task.id, targetTaskId: edge.target, traversal };
+    }
+    cancel(task, input) {
+        if (!["dependency_waiting", "ready", "in_progress", "blocked"].includes(task.state.kind))
+            this.invalid(task, "cancel");
+        if (input.worker !== undefined)
+            this.assertWorker(task, input);
+        const reason = requireText(input.evidence, "Cancellation reason");
+        const attemptId = task.state.kind === "in_progress" || task.state.kind === "blocked" ? task.state.attemptId : undefined;
+        const activeBefore = new Map(this.readAttempts()
+            .filter(attempt => attempt.state === "in_progress" || attempt.state === "blocked")
+            .map(attempt => [attempt.taskId, attempt.id]));
+        this.append({
+            kind: "task_cancelled",
+            operationId: input.operationId,
+            taskId: task.id,
+            taskLineage: this.definition(task.id).lineage,
+            ...(attemptId ? { attemptId } : {}),
+            reason,
+        });
+        for (const affectedTaskId of reverseClosure([task.id], this.currentRevision().tasks)) {
+            const affectedAttemptId = activeBefore.get(affectedTaskId);
+            if (affectedAttemptId && affectedAttemptId !== attemptId)
+                this.append({
+                    kind: "attempt_superseded",
+                    operationId: input.operationId,
+                    attemptId: affectedAttemptId,
+                    reason: "dependency_cancelled",
+                });
+        }
+    }
+    assertWorker(task, input) {
+        if (input.worker !== task.assignee) {
+            throw new GraphControlRefusal("worker_mismatch", `Task ${task.id} is assigned to ${task.assignee}, not ${String(input.worker)}.`);
+        }
+        if (task.state.kind === "in_progress" || task.state.kind === "blocked") {
+            const attemptId = task.state.attemptId;
+            const attempt = this.readAttempts(task.id).find(candidate => candidate.id === attemptId);
+            if (attempt?.assignee !== input.worker) {
+                throw new GraphControlRefusal("worker_mismatch", `Attempt ${attemptId} belongs to Worker ${String(attempt?.assignee)}.`);
+            }
+        }
+    }
+    invalid(task, transition) {
+        throw new GraphControlRefusal("invalid_transition", `Task ${task.id} is ${task.state.kind}; ${transition} is not valid.`);
+    }
+    command(operationId, semantics, apply) {
+        if (!operationId.trim())
+            throw new GraphControlRefusal("operation_conflict", "Operation identity must not be empty.");
+        const fingerprint = digest(semantics);
+        const prior = this.receipts.get(operationId);
+        if (prior) {
+            if (prior.fingerprint !== fingerprint) {
+                throw new GraphControlRefusal("operation_conflict", `Operation ${operationId} was already used with different semantics.`);
+            }
+            try {
+                validateReceiptProjection(this.snapshot(), prior);
+            }
+            catch (error) {
+                if (error instanceof GraphControlRefusal)
+                    throw error;
+                throw new GraphControlRefusal("invalid_graph", `Operation ${operationId} receipt is malformed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            return { ...clone(prior.result), replayed: true };
+        }
+        const graphLength = this.graphRevisions.length;
+        const eventLength = this.events.length;
+        const receiptSize = this.receipts.size;
+        try {
+            this.commandRecordedAt = this.clock().toISOString();
+            const result = apply();
+            this.receipts.set(operationId, { operationId, fingerprint, result: clone(result) });
+            return { ...clone(result), replayed: false };
+        }
+        catch (error) {
+            this.graphRevisions.length = graphLength;
+            this.events.length = eventLength;
+            if (this.receipts.size !== receiptSize)
+                this.receipts.delete(operationId);
+            throw error;
+        }
+        finally {
+            this.commandRecordedAt = undefined;
+        }
+    }
+    append(event) {
+        this.events.push({
+            ...event,
+            sequence: this.nextSequence(),
+            ...(this.commandRecordedAt ? { recorded_at: this.commandRecordedAt } : {}),
+        });
+    }
+    nextSequence() {
+        return Math.max(0, ...this.graphRevisions.map(revision => revision.sequence), ...this.events.map(event => event.sequence)) + 1;
+    }
+    currentRevision() {
+        return this.graphRevisions.at(-1);
+    }
+    definition(taskId) {
+        const definition = this.currentRevision()?.tasks.find(task => task.key === taskId);
+        if (!definition)
+            throw new GraphControlRefusal("task_not_found", `Task ${taskId} is not in the current graph.`);
+        return definition;
+    }
+    attemptFolds() {
+        const attempts = new Map();
+        for (const event of this.events) {
+            if (event.kind === "attempt_started")
+                attempts.set(event.attemptId, { started: event });
+            else if ("attemptId" in event && event.attemptId) {
+                const attempt = attempts.get(event.attemptId);
+                if (!attempt)
+                    continue;
+                if (event.kind === "attempt_blocked")
+                    attempt.blocked = event;
+                else if (event.kind === "attempt_resumed")
+                    attempt.resumed = event;
+                else if (event.kind === "attempt_completed")
+                    attempt.completed = event;
+                else if (event.kind === "attempt_superseded")
+                    attempt.superseded = event;
+                else if (event.kind === "task_cancelled")
+                    attempt.cancellation = event;
+            }
+        }
+        return attempts;
+    }
+    // Revisions and events are append-only. Their exact tail identities also fence
+    // rollback, so a failed command cannot leave a reusable speculative derivation.
+    derivedGraph() {
+        const revision = this.currentRevision();
+        const event = this.events.at(-1);
+        if (this.derivedCache && this.derivedCache.revision === revision && this.derivedCache.event === event)
+            return this.derivedCache.value;
+        const value = this.derive();
+        this.derivedCache = { revision, event, value };
+        return value;
+    }
+    derive() {
+        const revision = this.currentRevision();
+        if (!revision)
+            return new Map();
+        const order = topologicalOrder(revision.tasks);
+        const attempts = [...this.attemptFolds().values()];
+        const result = new Map();
+        for (const taskId of order) {
+            const definition = revision.tasks.find(task => task.key === taskId);
+            const taskAttempts = attempts.filter(attempt => attempt.started.taskId === taskId);
+            const cancellation = this.events.findLast((event) => event.kind === "task_cancelled"
+                && event.taskId === taskId
+                && event.taskLineage === definition.lineage);
+            const failedPrerequisites = [];
+            const cancelledPrerequisites = [];
+            const waitingPrerequisites = [];
+            const inputAttempts = [];
+            for (const prerequisiteId of definition.needs) {
+                const prerequisite = result.get(prerequisiteId);
+                if (prerequisite.state.kind === "goal_achieved") {
+                    inputAttempts.push([prerequisiteId, prerequisite.state.attemptId]);
+                }
+                else if (prerequisite.state.kind === "cancelled") {
+                    cancelledPrerequisites.push(prerequisiteId);
+                }
+                else if (prerequisite.state.kind === "goal_failed") {
+                    failedPrerequisites.push(prerequisiteId);
+                }
+                else {
+                    waitingPrerequisites.push(prerequisiteId);
+                }
+            }
+            const inputAttemptIds = Object.fromEntries(inputAttempts);
+            const demand = this.events.filter((event) => event.kind === "failure_edge_traversed"
+                && event.targetTaskId === taskId
+                && event.targetTaskLineage === definition.lineage).length;
+            let state;
+            let activationKey;
+            let acceptedAttemptId;
+            if (cancellation) {
+                state = { kind: "cancelled", reason: cancellation.reason };
+            }
+            else if (cancelledPrerequisites.length) {
+                state = { kind: "goal_failed", reason: "dependency_cancelled", prerequisiteTaskIds: cancelledPrerequisites.sort() };
+            }
+            else if (failedPrerequisites.length) {
+                state = { kind: "goal_failed", reason: "dependency_failed", prerequisiteTaskIds: failedPrerequisites.sort() };
+            }
+            else if (waitingPrerequisites.length) {
+                state = { kind: "dependency_waiting", prerequisiteTaskIds: waitingPrerequisites.sort() };
+            }
+            else {
+                activationKey = digest({ taskLineage: definition.lineage, demand, inputAttemptIds });
+                const current = taskAttempts.findLast(attempt => attempt.started.taskLineage === definition.lineage
+                    && attempt.started.activationKey === activationKey
+                    && !attempt.superseded
+                    && !attempt.cancellation);
+                if (!current) {
+                    state = { kind: "ready" };
+                }
+                else if (!current.completed) {
+                    const blocked = current.blocked && (!current.resumed || current.blocked.sequence > current.resumed.sequence);
+                    state = blocked
+                        ? { kind: "blocked", attemptId: current.started.attemptId, evidence: current.blocked.evidence }
+                        : { kind: "in_progress", attemptId: current.started.attemptId };
+                }
+                else if (current.completed.outcome === "goal_achieved") {
+                    acceptedAttemptId = current.started.attemptId;
+                    state = { kind: "goal_achieved", attemptId: acceptedAttemptId };
+                }
+                else {
+                    const exhausted = this.events.findLast((event) => event.kind === "failure_edge_exhausted" && event.sourceAttemptId === current.started.attemptId);
+                    state = exhausted
+                        ? {
+                            kind: "goal_failed",
+                            reason: "failure_edge_exhausted",
+                            attemptId: current.started.attemptId,
+                            targetTaskId: exhausted.targetTaskId,
+                            traversals: exhausted.traversals,
+                            exhaustionReason: exhausted.reason,
+                        }
+                        : { kind: "goal_failed", reason: "criterion_failed", attemptId: current.started.attemptId };
+                }
+            }
+            result.set(taskId, {
+                definition,
+                state,
+                ...(activationKey ? { activationKey } : {}),
+                inputAttemptIds,
+                ...(acceptedAttemptId ? { acceptedAttemptId } : {}),
+                attemptsStarted: taskAttempts.length,
+            });
+        }
+        return result;
+    }
+    toView(task) {
+        const value = {
+            id: task.definition.key,
+            title: task.definition.title,
+            goal: task.definition.goal,
+            assignee: task.definition.assignee,
+            needs: clone(task.definition.needs),
+            ...(task.definition.onGoalFailed ? { onGoalFailed: clone(task.definition.onGoalFailed) } : {}),
+            state: clone(task.state),
+            currentContext: this.events.findLast((event) => event.kind === "task_context_updated"
+                && event.taskId === task.definition.key
+                && event.taskLineage === task.definition.lineage)?.currentContext ?? "Work has not started.",
+            ...(task.activationKey ? { activationKey: task.activationKey } : {}),
+            ...(task.acceptedAttemptId ? { acceptedAttemptId: task.acceptedAttemptId } : {}),
+            attemptsStarted: task.attemptsStarted,
+        };
+        return { ...value, version: taskVersionRef(JSON.stringify(canonical(value))) };
+    }
+}
+/** Read-only recovery owns revision reuse. Commit recovery always validates fully.
+ * Retain fingerprints only; changed prefixes and failures require full validation.
+ */
+export class GraphObservationRecovery {
+    accepted;
+    recover(snapshot) {
+        try {
+            let fingerprints;
+            if (Array.isArray(snapshot?.graphRevisions)) {
+                try {
+                    fingerprints = snapshot.graphRevisions.map(revision => this.revisionFingerprint(revision));
+                }
+                catch {
+                    this.accepted = undefined;
+                }
+            }
+            const prior = this.accepted;
+            const unchangedPrefix = fingerprints && prior && fingerprints.length >= prior.length
+                && prior.every((fingerprint, index) => fingerprint === fingerprints[index]);
+            validateSnapshot(snapshot, unchangedPrefix ? prior.length : 0, (revision, previous) => this.validateRevision(revision, previous));
+            const controller = new GraphTaskController(snapshot);
+            this.accepted = fingerprints;
+            return {
+                readTasks: () => controller.readTasks(),
+                readAttempts: () => controller.readAttempts(),
+                selectReadyFrontier: () => controller.selectReadyFrontier(),
+            };
+        }
+        catch (error) {
+            this.accepted = undefined;
+            if (error instanceof GraphControlRefusal)
+                throw error;
+            throw new GraphControlRefusal("invalid_graph", `Graph authority snapshot is malformed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    revisionFingerprint(revision) {
+        return createHash("sha256").update(JSON.stringify(revision) ?? "undefined").digest("hex");
+    }
+    validateRevision(revision, previousRevision) {
+        validateGraphRevision(revision, previousRevision);
+    }
+}
+function validateGraphRevision(revision, previousRevision) {
+    if (!revision || typeof revision.version !== "string" || !Array.isArray(revision.tasks)) {
+        throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has an invalid graph revision.");
+    }
+    const normalized = normalizeAndValidate(revision.tasks.map((task) => ({
+        key: task.key,
+        title: task.title,
+        goal: task.goal,
+        assignee: task.assignee,
+        needs: task.needs,
+        ...(task.onGoalFailed ? { onGoalFailed: task.onGoalFailed } : {}),
+    })));
+    if (normalized.length !== revision.tasks.length
+        || normalized.some((task) => !revision.tasks.find((stored) => stored.key === task.key)?.lineage?.trim())) {
+        throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has an invalid Task lineage.");
+    }
+    const previousTasks = new Map(previousRevision?.tasks.map((task) => [task.key, task]) ?? []);
+    for (const task of revision.tasks) {
+        const prior = previousTasks.get(task.key);
+        const sameMeaning = prior && digest(semanticDefinition(prior)) === digest(semanticDefinition(task));
+        const expectedLineage = sameMeaning
+            ? prior.lineage
+            : digest({ task: semanticDefinition(task), introducedAt: revision.sequence });
+        if (task.lineage !== expectedLineage) {
+            throw new GraphControlRefusal("invalid_graph", `Graph authority snapshot has invalid lineage for Task ${task.key}.`);
+        }
+    }
+    if (revision.version !== graphVersion({ previous: previousRevision?.version ?? null, tasks: revision.tasks })) {
+        throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has an invalid graph version.");
+    }
+}
+function validateSnapshot(snapshot, validatedPrefixLength, validateRevision) {
+    if (!snapshot || snapshot.schema !== "pi-team-bright-graph-control/1"
+        || !Array.isArray(snapshot.graphRevisions)
+        || !Array.isArray(snapshot.events)
+        || !Array.isArray(snapshot.receipts)) {
+        throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has an invalid top-level shape.");
+    }
+    const sequences = [
+        ...snapshot.graphRevisions.map((revision) => revision?.sequence),
+        ...snapshot.events.map((event) => event?.sequence),
+    ];
+    if (sequences.some((sequence) => !Number.isSafeInteger(sequence) || sequence < 1)
+        || new Set(sequences).size !== sequences.length) {
+        throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has invalid or duplicate event sequences.");
+    }
+    if (snapshot.graphRevisions.some((revision, index) => index > 0 && revision.sequence <= snapshot.graphRevisions[index - 1].sequence)
+        || snapshot.events.some((event, index) => index > 0 && event.sequence <= snapshot.events[index - 1].sequence)) {
+        throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has out-of-order records.");
+    }
+    if (new Set(snapshot.graphRevisions.map((revision) => revision.version)).size !== snapshot.graphRevisions.length) {
+        throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot repeats a graph version.");
+    }
+    let previousRevision;
+    for (const [index, revision] of snapshot.graphRevisions.entries()) {
+        if (index >= validatedPrefixLength)
+            validateRevision(revision, previousRevision);
+        previousRevision = revision;
+    }
+    const operations = new Set();
+    for (const receipt of snapshot.receipts) {
+        if (!receipt || !receipt.operationId?.trim() || !/^[0-9a-f]{64}$/.test(receipt.fingerprint) || !receipt.result
+            || receipt.result.operationId !== receipt.operationId) {
+            throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has an invalid operation receipt.");
+        }
+        if (operations.has(receipt.operationId)) {
+            throw new GraphControlRefusal("invalid_graph", `Graph authority snapshot repeats operation ${receipt.operationId}.`);
+        }
+        operations.add(receipt.operationId);
+    }
+    const attempts = new Map();
+    const completed = new Map();
+    const startsPerTask = new Map();
+    const traversalsPerSource = new Map();
+    const failureEventsPerAttempt = new Set();
+    for (const event of snapshot.events) {
+        if (!event || !event.operationId?.trim() || !operations.has(event.operationId)) {
+            throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has an event without an operation receipt.");
+        }
+        const revision = snapshot.graphRevisions.findLast((candidate) => candidate.sequence < event.sequence);
+        if (!revision)
+            throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has an event before the first graph revision.");
+        if (event.kind === "attempt_started") {
+            const task = revision.tasks.find((candidate) => candidate.key === event.taskId);
+            const nextOrdinal = (startsPerTask.get(event.taskId) ?? 0) + 1;
+            if (!task || task.lineage !== event.taskLineage || revision.version !== event.graphVersion
+                || task.assignee !== event.assignee || event.ordinal !== nextOrdinal
+                || event.attemptId !== `${event.taskId}@${event.ordinal}` || attempts.has(event.attemptId)
+                || !event.activationKey?.trim() || !event.inputAttemptIds || typeof event.inputAttemptIds !== "object"
+                || Array.isArray(event.inputAttemptIds)) {
+                throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has an invalid Attempt start.");
+            }
+            attempts.set(event.attemptId, event);
+            startsPerTask.set(event.taskId, nextOrdinal);
+        }
+        else if (event.kind === "attempt_blocked" || event.kind === "attempt_resumed"
+            || event.kind === "attempt_completed" || event.kind === "attempt_superseded") {
+            if (!attempts.has(event.attemptId)) {
+                throw new GraphControlRefusal("invalid_graph", `Graph authority snapshot refers to missing Attempt ${event.attemptId}.`);
+            }
+            if (event.kind === "attempt_completed") {
+                if (completed.has(event.attemptId) || !["goal_achieved", "goal_failed"].includes(event.outcome) || !event.evidence?.trim()) {
+                    throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has an invalid Attempt completion.");
+                }
+                completed.set(event.attemptId, event);
+            }
+            else if ((event.kind === "attempt_blocked" || event.kind === "attempt_resumed") && completed.has(event.attemptId)) {
+                throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot changes a completed Attempt.");
+            }
+        }
+        else if (event.kind === "task_cancelled" || event.kind === "task_context_updated") {
+            const task = revision.tasks.find((candidate) => candidate.key === event.taskId);
+            if (!task || task.lineage !== event.taskLineage
+                || (event.kind === "task_cancelled" && event.attemptId && attempts.get(event.attemptId)?.taskId !== event.taskId)) {
+                throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has an event for a missing Task lineage.");
+            }
+        }
+        else if (event.kind === "failure_edge_traversed" || event.kind === "failure_edge_exhausted") {
+            const source = revision.tasks.find((candidate) => candidate.key === event.sourceTaskId);
+            const completion = completed.get(event.sourceAttemptId);
+            if (!source || source.lineage !== event.sourceTaskLineage
+                || attempts.get(event.sourceAttemptId)?.taskId !== event.sourceTaskId
+                || completion?.outcome !== "goal_failed" || source.onGoalFailed?.target !== event.targetTaskId
+                || failureEventsPerAttempt.has(event.sourceAttemptId)) {
+                throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has an invalid failure-edge event.");
+            }
+            failureEventsPerAttempt.add(event.sourceAttemptId);
+            const sourceKey = `${event.sourceTaskId}\0${event.sourceTaskLineage}`;
+            const traversals = traversalsPerSource.get(sourceKey) ?? 0;
+            if (event.kind === "failure_edge_traversed"
+                && (revision.tasks.find((candidate) => candidate.key === event.targetTaskId)?.lineage !== event.targetTaskLineage
+                    || event.traversal !== traversals + 1 || event.traversal > source.onGoalFailed.maxTraversals)) {
+                throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has an invalid failure traversal.");
+            }
+            if (event.kind === "failure_edge_traversed")
+                traversalsPerSource.set(sourceKey, event.traversal);
+            else if (event.traversals !== traversals || !["limit_reached", "target_cancelled"].includes(event.reason)) {
+                throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has an invalid failure exhaustion.");
+            }
+        }
+        else {
+            throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has an unknown event kind.");
+        }
+    }
+}
+function validateReceiptProjection(snapshot, receipt) {
+    const result = receipt.result;
+    const operationEvents = snapshot.events.filter((event) => event.operationId === receipt.operationId);
+    const appliedRevision = result.kind === "graph_applied"
+        ? snapshot.graphRevisions.find((revision) => revision.version === result.graphVersion)
+        : undefined;
+    const lastSequence = Math.max(appliedRevision?.sequence ?? 0, ...operationEvents.map((event) => event.sequence));
+    if (!lastSequence || (result.kind !== "graph_applied" && result.kind !== "task_transitioned")
+        || (result.kind === "graph_applied" && !appliedRevision)
+        || (result.kind === "task_transitioned" && !operationEvents.length)) {
+        throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has a receipt without a committed command.");
+    }
+    const atCommit = new GraphTaskController({
+        schema: snapshot.schema,
+        graphRevisions: snapshot.graphRevisions.filter((revision) => revision.sequence <= lastSequence),
+        events: snapshot.events.filter((event) => event.sequence <= lastSequence),
+        receipts: [],
+    });
+    const tasks = atCommit.readTasks();
+    if (result.kind === "graph_applied") {
+        if (digest(result.tasks) !== digest(tasks) || digest(result.readyTaskIds) !== digest(readyIds(tasks))) {
+            throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has a graph receipt that differs from committed state.");
+        }
+    }
+    else {
+        const directEvent = operationEvents[0];
+        const transition = directEvent.kind === "attempt_started" ? "claim"
+            : directEvent.kind === "attempt_blocked" ? "block"
+                : directEvent.kind === "attempt_resumed" ? "resume"
+                    : directEvent.kind === "attempt_completed" ? directEvent.outcome
+                        : directEvent.kind === "task_cancelled" ? "cancel"
+                            : directEvent.kind === "task_context_updated" ? "context_updated"
+                                : undefined;
+        const taskId = "taskId" in directEvent ? directEvent.taskId
+            : "attemptId" in directEvent ? snapshot.events.find((event) => event.kind === "attempt_started" && event.attemptId === directEvent.attemptId)?.taskId
+                : undefined;
+        const expectedTask = tasks.find((task) => task.id === taskId);
+        const traversal = operationEvents.find((event) => event.kind === "failure_edge_traversed");
+        const expectedTraversal = traversal
+            ? { sourceTaskId: traversal.sourceTaskId, targetTaskId: traversal.targetTaskId, traversal: traversal.traversal }
+            : undefined;
+        if (!expectedTask || transition !== result.transition || digest(result.task) !== digest(expectedTask)
+            || digest(result.readyTaskIds) !== digest(readyIds(tasks))
+            || digest(result.failureTraversal ?? null) !== digest(expectedTraversal ?? null)) {
+            throw new GraphControlRefusal("invalid_graph", "Graph authority snapshot has a Task receipt that differs from committed state.");
+        }
+    }
+}
+function readyIds(tasks) {
+    return tasks.filter(task => task.state.kind === "ready").map(task => task.id).sort();
+}
+function normalizeAndValidate(input) {
+    if (!input.length)
+        throw new GraphControlRefusal("invalid_graph", "A graph requires at least one Task.");
+    const normalized = input.map(task => ({
+        key: task.key,
+        title: task.title,
+        goal: task.goal,
+        assignee: task.assignee,
+        needs: [...(task.needs ?? [])].sort(),
+        ...(task.onGoalFailed ? { onGoalFailed: { ...task.onGoalFailed } } : {}),
+    }));
+    const byId = new Map();
+    for (const task of normalized) {
+        if (!task.key.trim() || !task.title.trim() || !task.goal.trim() || !task.assignee.trim()) {
+            throw new GraphControlRefusal("invalid_graph", "Every Task requires nonempty key, title, goal, and assignee values.");
+        }
+        if (byId.has(task.key))
+            throw new GraphControlRefusal("invalid_graph", `Task key ${task.key} occurs more than once.`);
+        if (new Set(task.needs).size !== task.needs.length) {
+            throw new GraphControlRefusal("invalid_graph", `Task ${task.key} repeats a prerequisite.`);
+        }
+        byId.set(task.key, task);
+    }
+    for (const task of normalized) {
+        for (const prerequisite of task.needs) {
+            if (!byId.has(prerequisite))
+                throw new GraphControlRefusal("invalid_graph", `Task ${task.key} needs missing Task ${prerequisite}.`);
+            if (prerequisite === task.key)
+                throw new GraphControlRefusal("invalid_graph", `Task ${task.key} cannot need itself.`);
+        }
+        if (task.onGoalFailed) {
+            if (!Number.isInteger(task.onGoalFailed.maxTraversals)
+                || task.onGoalFailed.maxTraversals < 1
+                || task.onGoalFailed.maxTraversals > GRAPH_CONTROL_MAX_FAILURE_TRAVERSALS) {
+                throw new GraphControlRefusal("invalid_graph", `Task ${task.key} failure maxTraversals must be from 1 through ${GRAPH_CONTROL_MAX_FAILURE_TRAVERSALS}.`);
+            }
+            if (!byId.has(task.onGoalFailed.target)) {
+                throw new GraphControlRefusal("invalid_graph", `Task ${task.key} has missing failure target ${task.onGoalFailed.target}.`);
+            }
+        }
+    }
+    topologicalOrder(normalized);
+    for (const task of normalized) {
+        const target = task.onGoalFailed?.target;
+        if (target && target !== task.key && !ancestors(task.key, byId).has(target)) {
+            throw new GraphControlRefusal("invalid_graph", `Task ${task.key} failure target ${target} must be itself or a transitive success prerequisite.`);
+        }
+    }
+    return normalized;
+}
+function topologicalOrder(tasks) {
+    const byId = new Map(tasks.map(task => [task.key, task]));
+    const visiting = new Set();
+    const visited = new Set();
+    const order = [];
+    const visit = (taskId, path) => {
+        if (visiting.has(taskId)) {
+            throw new GraphControlRefusal("invalid_graph", `Success dependency cycle: ${[...path, taskId].join(" -> ")}.`);
+        }
+        if (visited.has(taskId))
+            return;
+        visiting.add(taskId);
+        for (const prerequisite of byId.get(taskId)?.needs ?? [])
+            visit(prerequisite, [...path, taskId]);
+        visiting.delete(taskId);
+        visited.add(taskId);
+        order.push(taskId);
+    };
+    for (const taskId of [...byId.keys()].sort())
+        visit(taskId, []);
+    return order;
+}
+function ancestors(taskId, tasks) {
+    const result = new Set();
+    const collect = (id) => {
+        for (const prerequisite of tasks.get(id)?.needs ?? []) {
+            if (result.has(prerequisite))
+                continue;
+            result.add(prerequisite);
+            collect(prerequisite);
+        }
+    };
+    collect(taskId);
+    return result;
+}
+function reverseClosure(seed, tasks) {
+    const result = new Set(seed);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const task of tasks) {
+            if (result.has(task.key) || !task.needs.some(prerequisite => result.has(prerequisite)))
+                continue;
+            result.add(task.key);
+            changed = true;
+        }
+    }
+    return result;
+}