pactwright 0.0.1

package/dist/graph/lineage.js

@@ -0,0 +1,226 @@
+import { decisionFields } from "./schema.js";
+/**
+ * Derived Delivery lifecycle states (Delivery Graph §14). These are views of
+ * canonical graph structure, never stored node fields.
+ */
+export const DELIVERY_STATES = [
+    "open",
+    "deferred",
+    "rejected",
+    "contracted",
+    "delivering",
+    "done",
+];
+/**
+ * A record is current when nothing supersedes it (Delivery Graph §15).
+ * `isCurrent` for an id nothing points at is `true`; unknown ids are the
+ * caller's concern.
+ */
+export function isCurrent(id, edges) {
+    return !edges.some((edge) => edge.type === "supersedes" && edge.target === id);
+}
+/** Index of one graph, built once per derivation. */
+class GraphIndex {
+    byId;
+    superseded;
+    bySource = new Map();
+    byTarget = new Map();
+    constructor(nodes, edges) {
+        this.byId = new Map(nodes.map((node) => [node.id, node]));
+        this.superseded = new Set(edges.filter((edge) => edge.type === "supersedes").map((edge) => edge.target));
+        for (const edge of edges) {
+            push(this.bySource, edge.source, edge);
+            push(this.byTarget, edge.target, edge);
+        }
+    }
+    isCurrent(id) {
+        return !this.superseded.has(id);
+    }
+    /**
+     * Existing nodes of `type` that have an edge of `edgeType` pointing at
+     * `target`, sorted by id. Edges with a missing or wrongly typed source are
+     * ignored: `validateEdges` reports those.
+     */
+    sourcesOf(target, edgeType, type) {
+        return this.endpoints(this.byTarget.get(target), edgeType, (edge) => edge.source, type);
+    }
+    /** As `sourcesOf`, following edges the other way. */
+    targetsOf(source, edgeType, type) {
+        return this.endpoints(this.bySource.get(source), edgeType, (edge) => edge.target, type);
+    }
+    endpoints(edges, edgeType, pick, type) {
+        const found = [];
+        for (const edge of edges ?? []) {
+            if (edge.type !== edgeType)
+                continue;
+            const node = this.byId.get(pick(edge));
+            if (node !== undefined && node.type === type)
+                found.push(node);
+        }
+        return found.sort(byId);
+    }
+}
+function push(map, key, edge) {
+    const list = map.get(key);
+    if (list === undefined)
+        map.set(key, [edge]);
+    else
+        list.push(edge);
+}
+function byId(a, b) {
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+function ids(nodes) {
+    return nodes.map((node) => node.id).join(", ");
+}
+/**
+ * Global cardinality constraints (Delivery Graph §21): at most one current
+ * Brief decomposes each Contract, and at most one current Evidence record
+ * evidences each Brief — checked for every contract and brief in the graph,
+ * independently of any intent path and of the record's own currency.
+ */
+function checkGlobalCardinality(nodes, graph) {
+    const problems = [];
+    const ambiguous = new Set();
+    const of = (type) => nodes.filter((n) => n.type === type).sort(byId);
+    for (const contract of of("contract")) {
+        const briefs = graph
+            .sourcesOf(contract.id, "decomposes", "brief")
+            .filter((brief) => graph.isCurrent(brief.id));
+        if (briefs.length > 1) {
+            ambiguous.add(contract.id);
+            problems.push({
+                code: "ambiguous-brief",
+                message: `contract "${contract.id}" is decomposed by ${briefs.length} current briefs (${ids(briefs)}); supersede all but one`,
+                path: contract.path,
+            });
+        }
+    }
+    for (const brief of of("brief")) {
+        const evidences = graph
+            .sourcesOf(brief.id, "evidences", "evidence")
+            .filter((evidence) => graph.isCurrent(evidence.id));
+        if (evidences.length > 1) {
+            ambiguous.add(brief.id);
+            problems.push({
+                code: "ambiguous-evidence",
+                message: `brief "${brief.id}" is evidenced by ${evidences.length} current evidence records (${ids(evidences)}); supersede all but one`,
+                path: brief.path,
+            });
+        }
+    }
+    return { problems, ambiguous };
+}
+/**
+ * Derives the current lineage of one intent, reporting every ambiguity in it
+ * (Delivery Graph §21, Current-lineage ambiguity). Returns no lineage when the
+ * lineage is ambiguous.
+ */
+function derive(intent, graph, ambiguous) {
+    const problems = [];
+    const fail = (node, code, message) => {
+        problems.push({ code, message, path: node.path });
+    };
+    const superseded = !graph.isCurrent(intent.id);
+    const decisions = graph
+        .sourcesOf(intent.id, "resolves", "decision")
+        .filter((decision) => graph.isCurrent(decision.id));
+    if (decisions.length > 1) {
+        fail(intent, "ambiguous-decision", `intent "${intent.id}" is resolved by ${decisions.length} current decisions (${ids(decisions)}); supersede all but one`);
+        return { problems };
+    }
+    const decision = decisions[0];
+    if (decision === undefined)
+        return { lineage: { intent, state: "open", superseded }, problems };
+    // An invalid decision was already reported by validateNode; do not judge its lineage.
+    const fields = decisionFields(decision);
+    if (fields === undefined)
+        return { problems };
+    const outcome = fields.outcome;
+    const selected = graph.targetsOf(decision.id, "selects", "contract");
+    if (outcome !== "proceed") {
+        if (selected.length > 0) {
+            fail(decision, "unexpected-contract", `decision "${decision.id}" has outcome ${outcome} but selects a contract (${ids(selected)}); only proceed selects a contract`);
+            return { problems };
+        }
+        return {
+            lineage: {
+                intent,
+                decision,
+                state: outcome === "defer" ? "deferred" : "rejected",
+                superseded,
+            },
+            problems,
+        };
+    }
+    const contracts = selected.filter((contract) => graph.isCurrent(contract.id));
+    if (contracts.length === 0) {
+        const superseded = selected.length === 0 ? "" : ` (superseded: ${ids(selected)})`;
+        fail(decision, "missing-contract", `decision "${decision.id}" proceeds but selects no current contract${superseded}; proceed selects exactly one current contract`);
+        return { problems };
+    }
+    if (contracts.length > 1) {
+        fail(decision, "ambiguous-contract", `decision "${decision.id}" selects ${contracts.length} current contracts (${ids(contracts)}); proceed selects exactly one current contract`);
+        return { problems };
+    }
+    const contract = contracts[0];
+    // >1 current brief was already reported by the global cardinality pass.
+    if (ambiguous.has(contract.id))
+        return { problems };
+    const briefs = graph
+        .sourcesOf(contract.id, "decomposes", "brief")
+        .filter((brief) => graph.isCurrent(brief.id));
+    const brief = briefs[0];
+    if (brief === undefined) {
+        return { lineage: { intent, decision, contract, state: "contracted", superseded }, problems };
+    }
+    // >1 current evidence was already reported by the global cardinality pass.
+    if (ambiguous.has(brief.id))
+        return { problems };
+    const evidences = graph
+        .sourcesOf(brief.id, "evidences", "evidence")
+        .filter((evidence) => graph.isCurrent(evidence.id));
+    const evidence = evidences[0];
+    if (evidence === undefined) {
+        return {
+            lineage: { intent, decision, contract, brief, state: "delivering", superseded },
+            problems,
+        };
+    }
+    return {
+        lineage: { intent, decision, contract, brief, evidence, state: "done", superseded },
+        problems,
+    };
+}
+/**
+ * Derives the current Delivery lineage of every intent from graph structure
+ * alone (Delivery Graph §§14–15). Every intent is covered, superseded ones
+ * included: a superseded intent's lineage is frozen but must still be
+ * unambiguous. Edges with missing or wrongly typed endpoints are ignored,
+ * so this is safe to run on a graph `validateEdges` has already rejected.
+ */
+export function deriveLineages(nodes, edges) {
+    const graph = new GraphIndex(nodes, edges);
+    const global = checkGlobalCardinality(nodes, graph);
+    const lineages = [];
+    const problems = [...global.problems];
+    for (const intent of [...nodes].filter((node) => node.type === "intent").sort(byId)) {
+        const result = derive(intent, graph, global.ambiguous);
+        problems.push(...result.problems);
+        if (result.lineage !== undefined)
+            lineages.push(result.lineage);
+    }
+    return { lineages, problems };
+}
+/** The lineage of one intent; `undefined` when the id is not an intent or the lineage is ambiguous. */
+export function deriveLineage(intentId, nodes, edges) {
+    const intent = nodes.find((node) => node.id === intentId && node.type === "intent");
+    if (intent === undefined)
+        return undefined;
+    const graph = new GraphIndex(nodes, edges);
+    return derive(intent, graph, checkGlobalCardinality(nodes, graph).ambiguous).lineage;
+}
+/** Current-lineage ambiguity validation (Delivery Graph §21). */
+export function validateLineages(nodes, edges) {
+    return deriveLineages(nodes, edges).problems;
+}

package/dist/graph/mutations.d.ts

@@ -0,0 +1,108 @@
+import { type Project } from "../loader.js";
+import { type Edge } from "./edges.js";
+import { type GraphNode } from "./nodes.js";
+import { type DecisionOutcome } from "./schema.js";
+/**
+ * New canonical records to commit in one atomic mutation.
+ *
+ * Internal: this raw shape is produced only by the typed mutation functions
+ * below (`createIntent`, `recordDecision`, `createBrief`, `createEvidence`).
+ * It is deliberately not part of the public package surface — callers own
+ * semantic content; the runtime owns node construction, serialisation and
+ * destination paths.
+ */
+export interface GraphChange {
+    readonly addNodes: readonly GraphNode[];
+    readonly addEdges: readonly Edge[];
+}
+/** Internal: test-only hooks for the shared commit path. */
+export interface CommitOptions {
+    /** Runs after the atomic renames, before resulting-state validation. */
+    readonly postWrite?: () => void;
+}
+/** Serialises a node to Markdown + YAML frontmatter that `parseNodeFile` round-trips. */
+export declare function serialiseNode(node: GraphNode): string;
+/** Serialises the shared typed-edge store in the `edges.yml` fixture shape. */
+export declare function serialiseEdges(edges: readonly Edge[]): string;
+/**
+ * Internal shared mutation path (Implementation Guide, "Filesystem
+ * mutation"): plan → validate the complete proposed state against the
+ * current graph state → write atomically → validate the resulting state.
+ *
+ * Before anything else the selected agent pack is resolved and checked
+ * against the required capabilities (Distribution §7): an incomplete or
+ * unresolvable pack throws here, before any validation or write.
+ *
+ * Validation covers the full common node rules (derived path, id shape,
+ * frontmatter round-trip, body) plus type schemas, the typed-edge registry,
+ * global lineage constraints and id immutability. Every file is written to a
+ * temporary sibling and renamed into place, node files first, `edges.yml`
+ * last. After the writes the resulting repository state is reloaded through
+ * the canonical loader; if it fails, the new node files are removed and
+ * `edges.yml` is restored, so no partial graph state remains.
+ */
+export declare function commitGraphChange(project: Project, change: GraphChange, options?: CommitOptions): void;
+export interface CreateIntentInput {
+    readonly title: string;
+    readonly body: string;
+    readonly created?: string;
+}
+/**
+ * Creates an Intent (Delivery Graph §6). Like every typed mutation, it loads
+ * the current graph state itself at commit time, builds the node from that
+ * state in one synchronous sequence and validates the complete proposed and
+ * resulting states — a caller-held snapshot never reaches the filesystem.
+ */
+export declare function createIntent(root: string, input: CreateIntentInput): GraphNode;
+export interface RecordDecisionInput {
+    readonly intentId: string;
+    readonly outcome: DecisionOutcome;
+    /** The actual acting actor, recorded verbatim in `decided_by`, e.g. "human:samir". */
+    readonly decidedBy: string;
+    readonly title?: string;
+    readonly body: string;
+    /** The canonical contract; required for proceed, forbidden otherwise (§8, §9). */
+    readonly contract?: {
+        readonly title: string;
+        readonly body: string;
+    };
+    readonly created?: string;
+}
+export interface RecordedDecision {
+    readonly decision: GraphNode;
+    readonly contract?: GraphNode;
+}
+/**
+ * Records a Decision resolving an Intent (Delivery Graph §8) and, for
+ * proceed, creates the one canonical Contract it selects (§9, §19).
+ * The acting actor must be authorised for approve-contract by lifecycle.yml;
+ * authorisation is checked before anything is built or written. Re-deciding
+ * supersedes the previous current decision and its selected contract (§15).
+ * Current graph state is loaded at commit time; see `createIntent`.
+ */
+export declare function recordDecision(root: string, input: RecordDecisionInput): RecordedDecision;
+export interface CreateBriefInput {
+    readonly contractId: string;
+    readonly title: string;
+    readonly body: string;
+    readonly created?: string;
+}
+/**
+ * Creates the delivery Brief decomposing a Contract (§10). An existing
+ * current brief is superseded explicitly (§15, brief change). Current graph
+ * state is loaded at commit time; see `createIntent`.
+ */
+export declare function createBrief(root: string, input: CreateBriefInput): GraphNode;
+export interface CreateEvidenceInput {
+    readonly briefId: string;
+    readonly title: string;
+    readonly body: string;
+    readonly created?: string;
+}
+/**
+ * Creates the Evidence record for a Brief (§12), completing the core
+ * Delivery lifecycle. Existing current evidence is superseded explicitly
+ * (§15, evidence correction). Current graph state is loaded at commit time;
+ * see `createIntent`.
+ */
+export declare function createEvidence(root: string, input: CreateEvidenceInput): GraphNode;

package/dist/graph/mutations.js

@@ -0,0 +1,356 @@
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { dump } from "js-yaml";
+import { tempSibling } from "../atomic.js";
+import { PactwrightError } from "../errors.js";
+import { decisionActor } from "../config/lifecycle.js";
+import { loadProject } from "../loader.js";
+import { assertPackComplete } from "../pack/resolve.js";
+import { composedRegistries } from "../extension/resolve.js";
+import { validateEdges } from "./edge-schema.js";
+import { edgeKey } from "./edges.js";
+import { mintNodeId, slugify } from "./ids.js";
+import { validateLineages } from "./lineage.js";
+import { graphRevision } from "./revision.js";
+import { checkNodeIdImmutability, parseNodeFile } from "./nodes.js";
+import { parseDecidedBy, validateNodes, } from "./schema.js";
+function fail(code, message) {
+    throw new PactwrightError(code, message);
+}
+/** Serialises a node to Markdown + YAML frontmatter that `parseNodeFile` round-trips. */
+export function serialiseNode(node) {
+    const front = dump(node.frontmatter, { lineWidth: -1 });
+    return `---\n${front}---\n\n${node.body}\n`;
+}
+/** Serialises the shared typed-edge store in the `edges.yml` fixture shape. */
+export function serialiseEdges(edges) {
+    if (edges.length === 0)
+        return "edges: []\n";
+    const items = edges
+        .map((edge) => `  - source: ${edge.source}\n    type: ${edge.type}\n    target: ${edge.target}\n`)
+        .join("");
+    return `edges:\n${items}`;
+}
+const COMMON_FIELDS = ["id", "type", "title", "created"];
+/**
+ * Complete common validation of one proposed node, exactly as loading it
+ * back will judge it: the destination path is derived from the id (never
+ * caller-supplied), and the serialised file must round-trip through
+ * `parseNodeFile` to the same common fields.
+ */
+function checkProposedNode(project, node) {
+    const canonical = join(project.paths.nodesDir, `${node.id}.md`);
+    if (node.path !== canonical) {
+        return [
+            {
+                code: "invalid-path",
+                message: `node "${node.id}" must be committed to ${canonical}; committed paths are derived from the id, never supplied`,
+                path: node.path,
+            },
+        ];
+    }
+    const parsed = parseNodeFile(serialiseNode(node), canonical);
+    if (parsed.value === undefined)
+        return parsed.problems;
+    const problems = [];
+    for (const field of COMMON_FIELDS) {
+        if (parsed.value[field] !== node[field]) {
+            problems.push({
+                code: "field-mismatch",
+                message: `node "${node.id}" ${field} does not round-trip: frontmatter carries "${String(parsed.value[field])}" but the node declares "${String(node[field])}"`,
+                path: canonical,
+            });
+        }
+    }
+    return problems;
+}
+/**
+ * Internal shared mutation path (Implementation Guide, "Filesystem
+ * mutation"): plan → validate the complete proposed state against the
+ * current graph state → write atomically → validate the resulting state.
+ *
+ * Before anything else the selected agent pack is resolved and checked
+ * against the required capabilities (Distribution §7): an incomplete or
+ * unresolvable pack throws here, before any validation or write.
+ *
+ * Validation covers the full common node rules (derived path, id shape,
+ * frontmatter round-trip, body) plus type schemas, the typed-edge registry,
+ * global lineage constraints and id immutability. Every file is written to a
+ * temporary sibling and renamed into place, node files first, `edges.yml`
+ * last. After the writes the resulting repository state is reloaded through
+ * the canonical loader; if it fails, the new node files are removed and
+ * `edges.yml` is restored, so no partial graph state remains.
+ */
+export function commitGraphChange(project, change, options = {}) {
+    assertPackComplete(project);
+    const problems = [];
+    const nodes = [...project.graph.nodes];
+    const seenIds = new Set(nodes.map((node) => node.id));
+    for (const node of change.addNodes) {
+        if (seenIds.has(node.id)) {
+            problems.push({
+                code: "duplicate-id",
+                message: `node id "${node.id}" already exists in the graph`,
+                path: node.path,
+            });
+            continue;
+        }
+        seenIds.add(node.id);
+        nodes.push(node);
+        problems.push(...checkProposedNode(project, node));
+    }
+    const edges = [...project.graph.edges];
+    const seenEdges = new Set(edges.map(edgeKey));
+    for (const edge of change.addEdges) {
+        const key = edgeKey(edge);
+        if (seenEdges.has(key)) {
+            problems.push({ code: "duplicate-edge", message: `edge ${key} already exists` });
+            continue;
+        }
+        seenEdges.add(key);
+        edges.push(edge);
+    }
+    const registries = composedRegistries(project.extensions);
+    problems.push(...validateNodes(nodes, registries.nodes), ...validateEdges(edges, nodes, registries.edges, project.paths.edges), ...validateLineages(nodes, edges), ...checkNodeIdImmutability(project.graph.nodes, nodes));
+    if (problems.length > 0)
+        throw PactwrightError.fromProblems("mutation-invalid", problems);
+    // Compare-and-swap: the snapshot this change was planned against must
+    // still be the on-disk graph state, or a concurrent writer's records
+    // would be silently overwritten by the wholesale edges.yml rewrite.
+    const expected = graphRevision({ nodes: project.graph.nodes, edges: project.graph.edges });
+    const fresh = loadProject({ root: project.paths.root });
+    if (graphRevision({ nodes: fresh.graph.nodes, edges: fresh.graph.edges }) !== expected) {
+        throw new PactwrightError("concurrent-modification", "the graph changed since this mutation was planned; reload and retry");
+    }
+    // path → content, edges.yml last so the links land only after the records.
+    const previousEdges = readFileSync(project.paths.edges, "utf8");
+    const writes = [
+        ...change.addNodes.map((node) => ({ path: node.path, content: serialiseNode(node) })),
+        { path: project.paths.edges, content: serialiseEdges(edges) },
+    ];
+    const temps = [];
+    const restore = () => {
+        for (const node of change.addNodes) {
+            try {
+                unlinkSync(node.path);
+            }
+            catch {
+                /* rollback is best effort */
+            }
+        }
+        const temp = tempSibling(project.paths.edges);
+        writeFileSync(temp, previousEdges, "utf8");
+        renameSync(temp, project.paths.edges);
+    };
+    try {
+        for (const write of writes) {
+            const temp = tempSibling(write.path);
+            writeFileSync(temp, write.content, "utf8");
+            temps.push(temp);
+        }
+        writes.forEach((write, index) => {
+            renameSync(temps[index], write.path);
+            temps[index] = "";
+        });
+    }
+    catch (error) {
+        for (const temp of temps.filter((t) => t !== "")) {
+            try {
+                unlinkSync(temp);
+            }
+            catch {
+                /* rollback is best effort */
+            }
+        }
+        restore();
+        throw error;
+    }
+    // Validate the resulting repository state; roll back if it does not load.
+    try {
+        options.postWrite?.();
+        loadProject({ root: project.paths.root });
+    }
+    catch (error) {
+        restore();
+        if (error instanceof PactwrightError) {
+            throw PactwrightError.fromProblems("resulting-state-invalid", error.problems);
+        }
+        throw error;
+    }
+}
+/** Today's date in UTC — deliberately timezone-independent, since `created` feeds the id hash. */
+function today() {
+    return new Date().toISOString().slice(0, 10);
+}
+function requireNode(project, id, type) {
+    const node = project.graph.nodes.find((candidate) => candidate.id === id);
+    if (node === undefined || node.type !== type) {
+        fail("unknown-node", `"${id}" is not an existing ${type} node`);
+    }
+    if (isSuperseded(project, id)) {
+        fail("superseded-node", `${type} "${id}" is superseded; only current records take new work`);
+    }
+    return node;
+}
+function isSuperseded(project, id) {
+    return project.graph.edges.some((edge) => edge.type === "supersedes" && edge.target === id);
+}
+/** Current (unsuperseded) sources of `edgeType` edges into `target`. */
+function currentSources(project, target, edgeType) {
+    return project.graph.edges
+        .filter((edge) => edge.type === edgeType && edge.target === target)
+        .map((edge) => edge.source)
+        .filter((id) => !isSuperseded(project, id));
+}
+function buildNode(project, input) {
+    const title = input.title.trim();
+    const body = input.body.trim();
+    if (title.length === 0)
+        fail("invalid-title", "title must not be empty");
+    if (body.length === 0)
+        fail("missing-body", "node must have a Markdown body");
+    const slug = slugify(title);
+    if (slug === undefined)
+        fail("invalid-title", `cannot derive a slug from title "${input.title}"`);
+    const created = input.created ?? today();
+    const taken = new Set([...project.graph.nodes.map((node) => node.id), ...(input.taken ?? [])]);
+    const id = mintNodeId(input.type, slug, `${created}\n${title}\n${body}`, taken);
+    return {
+        id,
+        type: input.type,
+        title,
+        created,
+        frontmatter: { id, type: input.type, title, created, ...(input.extraFront ?? {}) },
+        body,
+        path: join(project.paths.nodesDir, `${id}.md`),
+    };
+}
+/**
+ * Creates an Intent (Delivery Graph §6). Like every typed mutation, it loads
+ * the current graph state itself at commit time, builds the node from that
+ * state in one synchronous sequence and validates the complete proposed and
+ * resulting states — a caller-held snapshot never reaches the filesystem.
+ */
+export function createIntent(root, input) {
+    const project = loadProject({ root });
+    const intent = buildNode(project, { type: "intent", ...input });
+    commitGraphChange(project, { addNodes: [intent], addEdges: [] });
+    return intent;
+}
+/** Which `decided_by` kinds the configured lifecycle actor authorises (§8, §17). */
+const AUTHORISED_KINDS = {
+    human: ["human"],
+    agent: ["agent", "automation"],
+};
+const DECISION_TITLES = {
+    proceed: "Proceed with",
+    reject: "Reject",
+    defer: "Defer",
+};
+/**
+ * Records a Decision resolving an Intent (Delivery Graph §8) and, for
+ * proceed, creates the one canonical Contract it selects (§9, §19).
+ * The acting actor must be authorised for approve-contract by lifecycle.yml;
+ * authorisation is checked before anything is built or written. Re-deciding
+ * supersedes the previous current decision and its selected contract (§15).
+ * Current graph state is loaded at commit time; see `createIntent`.
+ */
+export function recordDecision(root, input) {
+    const project = loadProject({ root });
+    const actor = parseDecidedBy(input.decidedBy);
+    if (actor === undefined) {
+        fail("invalid-actor", `decided_by "${input.decidedBy}" must be "<kind>:<name>"`);
+    }
+    const configured = decisionActor(project.lifecycle);
+    if (!AUTHORISED_KINDS[configured].includes(actor.kind)) {
+        fail("unauthorised-actor", `actor "${input.decidedBy}" is not authorised for approve-contract; lifecycle.yml authorises ${configured} (${AUTHORISED_KINDS[configured].join("/")}) actors`);
+    }
+    if ((input.outcome === "proceed") !== (input.contract !== undefined)) {
+        fail("invalid-outcome-input", input.outcome === "proceed"
+            ? "proceed requires a contract; one canonical contract is created with the decision"
+            : `${input.outcome} selects no contract`);
+    }
+    const intent = requireNode(project, input.intentId, "intent");
+    const decision = buildNode(project, {
+        type: "decision",
+        title: input.title ?? `${DECISION_TITLES[input.outcome]} ${intent.title}`,
+        body: input.body,
+        created: input.created,
+        extraFront: { decided_by: input.decidedBy, outcome: input.outcome },
+    });
+    const addNodes = [decision];
+    const addEdges = [{ source: decision.id, type: "resolves", target: intent.id }];
+    let contract;
+    if (input.contract !== undefined) {
+        contract = buildNode(project, {
+            type: "contract",
+            title: input.contract.title,
+            body: input.contract.body,
+            created: input.created,
+            taken: new Set([decision.id]),
+        });
+        addNodes.push(contract);
+        addEdges.push({ source: decision.id, type: "selects", target: contract.id });
+    }
+    // Supersede the previous current records explicitly (§15).
+    for (const previous of currentSources(project, intent.id, "resolves")) {
+        addEdges.push({ source: decision.id, type: "supersedes", target: previous });
+        const selected = project.graph.edges
+            .filter((edge) => edge.source === previous && edge.type === "selects")
+            .map((edge) => edge.target)
+            .filter((id) => !isSuperseded(project, id));
+        for (const oldContract of selected) {
+            if (contract !== undefined) {
+                addEdges.push({ source: contract.id, type: "supersedes", target: oldContract });
+            }
+            else {
+                fail("invalid-outcome-input", `intent "${intent.id}" has a current contract "${oldContract}"; a contract change needs a new proceed decision with a new canonical contract (§15)`);
+            }
+        }
+    }
+    commitGraphChange(project, { addNodes, addEdges });
+    return contract === undefined ? { decision } : { decision, contract };
+}
+/**
+ * Creates the delivery Brief decomposing a Contract (§10). An existing
+ * current brief is superseded explicitly (§15, brief change). Current graph
+ * state is loaded at commit time; see `createIntent`.
+ */
+export function createBrief(root, input) {
+    const project = loadProject({ root });
+    const contract = requireNode(project, input.contractId, "contract");
+    const brief = buildNode(project, {
+        type: "brief",
+        title: input.title,
+        body: input.body,
+        created: input.created,
+    });
+    const addEdges = [{ source: brief.id, type: "decomposes", target: contract.id }];
+    for (const previous of currentSources(project, contract.id, "decomposes")) {
+        addEdges.push({ source: brief.id, type: "supersedes", target: previous });
+    }
+    commitGraphChange(project, { addNodes: [brief], addEdges });
+    return brief;
+}
+/**
+ * Creates the Evidence record for a Brief (§12), completing the core
+ * Delivery lifecycle. Existing current evidence is superseded explicitly
+ * (§15, evidence correction). Current graph state is loaded at commit time;
+ * see `createIntent`.
+ */
+export function createEvidence(root, input) {
+    const project = loadProject({ root });
+    const brief = requireNode(project, input.briefId, "brief");
+    const evidence = buildNode(project, {
+        type: "evidence",
+        title: input.title,
+        body: input.body,
+        created: input.created,
+    });
+    const addEdges = [{ source: evidence.id, type: "evidences", target: brief.id }];
+    for (const previous of currentSources(project, brief.id, "evidences")) {
+        addEdges.push({ source: evidence.id, type: "supersedes", target: previous });
+    }
+    commitGraphChange(project, { addNodes: [evidence], addEdges });
+    return evidence;
+}