pactwright 0.0.1

package/dist/config/config.js

@@ -0,0 +1,199 @@
+import { Checker, expectBoolean, expectEnum, expectRecord, expectString, expectVersion, rejectUnknownKeys, requireKeys, } from "../validation.js";
+import { parseYaml, readYamlFile } from "../yaml.js";
+import { EXTENSION_ID_PATTERN } from "./lock.js";
+export const CONFIG_VERSION = 1;
+export const ADAPTER_TYPES = ["claude-code"];
+export function parseConfig(raw, path) {
+    const c = new Checker(path);
+    const root = expectRecord(c, raw, "config");
+    if (root === undefined)
+        return { value: undefined, problems: c.problems };
+    requireKeys(c, root, "config", ["version", "agent_pack", "adapter", "github"]);
+    rejectUnknownKeys(c, root, "config", [
+        "version",
+        "agent_pack",
+        "adapter",
+        "extensions",
+        "github",
+    ]);
+    expectVersion(c, root["version"], "config.version", CONFIG_VERSION);
+    let source;
+    let packVersion;
+    const agentPack = expectRecord(c, root["agent_pack"], "config.agent_pack");
+    if (agentPack !== undefined) {
+        requireKeys(c, agentPack, "config.agent_pack", ["source"]);
+        rejectUnknownKeys(c, agentPack, "config.agent_pack", ["source", "version"]);
+        source = expectString(c, agentPack["source"], "config.agent_pack.source");
+        packVersion = expectString(c, agentPack["version"], "config.agent_pack.version");
+    }
+    let adapterType;
+    const adapter = expectRecord(c, root["adapter"], "config.adapter");
+    if (adapter !== undefined) {
+        requireKeys(c, adapter, "config.adapter", ["type"]);
+        rejectUnknownKeys(c, adapter, "config.adapter", ["type"]);
+        adapterType = expectEnum(c, adapter["type"], "config.adapter.type", ADAPTER_TYPES);
+    }
+    const extensions = Object.create(null);
+    if (root["extensions"] !== undefined) {
+        const raw = expectRecord(c, root["extensions"], "config.extensions");
+        if (raw !== undefined) {
+            for (const id of Object.keys(raw).sort()) {
+                if (!EXTENSION_ID_PATTERN.test(id)) {
+                    c.fail("invalid-extension-id", `config.extensions key "${id}" is not a valid extension id`);
+                    continue;
+                }
+                const label = `config.extensions.${id}`;
+                const entry = expectRecord(c, raw[id], label);
+                if (entry === undefined)
+                    continue;
+                requireKeys(c, entry, label, ["enabled", "source"]);
+                rejectUnknownKeys(c, entry, label, ["enabled", "source"]);
+                const extensionEnabled = expectBoolean(c, entry["enabled"], `${label}.enabled`);
+                const extensionSource = expectString(c, entry["source"], `${label}.source`);
+                if (extensionEnabled !== undefined && extensionSource !== undefined) {
+                    extensions[id] = { enabled: extensionEnabled, source: extensionSource };
+                }
+            }
+        }
+    }
+    let enabled;
+    const github = expectRecord(c, root["github"], "config.github");
+    if (github !== undefined) {
+        requireKeys(c, github, "config.github", ["enabled"]);
+        rejectUnknownKeys(c, github, "config.github", ["enabled"]);
+        enabled = expectBoolean(c, github["enabled"], "config.github.enabled");
+    }
+    if (!c.ok || source === undefined || adapterType === undefined || enabled === undefined) {
+        return { value: undefined, problems: c.problems };
+    }
+    return {
+        value: {
+            version: 1,
+            agentPack: packVersion === undefined ? { source } : { source, version: packVersion },
+            adapter: { type: adapterType },
+            // Copied to a plain object; callers guard dynamic id lookups with
+            // `Object.hasOwn` so an id like "constructor" cannot resolve to an
+            // Object.prototype member.
+            extensions: { ...extensions },
+            github: { enabled },
+        },
+        problems: [],
+    };
+}
+export function loadConfig(path) {
+    const read = readYamlFile(path);
+    if (read.problems.length > 0)
+        return { value: undefined, problems: read.problems };
+    return parseConfig(read.value, path);
+}
+/**
+ * A YAML double-quoted scalar holding `text`. JSON is a subset of YAML 1.2
+ * and the two share their double-quoted escape set, so `JSON.stringify` is a
+ * correct encoder here — and for an ordinary package name or relative path it
+ * emits exactly the bytes a hand-written config already has. Interpolating
+ * such values raw would let a `"`, `\` or newline in a source break out of
+ * the field and leave an unparseable config behind.
+ */
+function scalar(text) {
+    return JSON.stringify(text);
+}
+/** The canonical `extensions:` block, the only region the commands rewrite. */
+function extensionsBlock(config) {
+    const ids = Object.keys(config.extensions).sort();
+    if (ids.length === 0)
+        return ["extensions: {}"];
+    const lines = ["extensions:"];
+    ids.forEach((id, index) => {
+        const extension = config.extensions[id];
+        if (index > 0)
+            lines.push("");
+        lines.push(`  ${id}:`, `    enabled: ${extension.enabled}`, `    source: ${scalar(extension.source)}`);
+    });
+    return lines;
+}
+/**
+ * Serialises a configuration in the canonical `.pactwright/config.yml`
+ * shape — the exact bytes `pactwright init` writes for the default state.
+ * This is the fallback whenever the previous file cannot be edited in place;
+ * it re-emits from parsed values, so comments and incidental layout are not
+ * carried over. `rewriteConfig` is what the commands normally use.
+ */
+export function serialiseConfig(config) {
+    const lines = [
+        "version: 1",
+        "",
+        "agent_pack:",
+        `  source: ${scalar(config.agentPack.source)}`,
+    ];
+    if (config.agentPack.version !== undefined) {
+        lines.push(`  version: ${scalar(config.agentPack.version)}`);
+    }
+    // `adapter.type` is a validated enum and extension ids are validated
+    // kebab-case, so both are safe bare; quoting them would also change the
+    // bytes `init` writes.
+    lines.push("", "adapter:", `  type: ${config.adapter.type}`, "");
+    lines.push(...extensionsBlock(config));
+    lines.push("", "github:", `  enabled: ${config.github.enabled}`, "");
+    return lines.join("\n");
+}
+/** The line range of the top-level `extensions:` key, or `undefined`. */
+function extensionsRegion(lines) {
+    const start = lines.findIndex((line) => /^extensions:/.test(line));
+    if (start === -1)
+        return undefined;
+    if (lines.some((line) => line.includes("\t")))
+        return undefined;
+    // A flow mapping (`extensions: {}`) is the whole region. Anything else on
+    // the key line is a shape this editor does not claim to understand.
+    const inline = lines[start].slice("extensions:".length).trim();
+    if (inline !== "")
+        return inline === "{}" ? { start, end: start } : undefined;
+    let end = start;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (line.trim() === "")
+            continue;
+        if (!/^\s/.test(line))
+            break;
+        end = i;
+    }
+    return { start, end };
+}
+/**
+ * The previous configuration text with only its `extensions:` block replaced
+ * (Distribution §3). `extension add` and `remove` change nothing else, so
+ * every other byte — comments, key order, spacing a team chose — survives.
+ *
+ * Falls back to a full `serialiseConfig` rewrite whenever the edit cannot be
+ * made confidently, including when the spliced result does not parse back to
+ * the intended configuration. The fallback is today's behaviour, so the worst
+ * case is losing comments rather than corrupting the file — which matters
+ * because `removeExtension` never rolls its write back.
+ *
+ * Comments *inside* the extensions block are part of the replaced region and
+ * are not preserved.
+ */
+export function rewriteConfig(previous, config) {
+    const canonical = serialiseConfig(config);
+    const newline = previous.includes("\r\n") ? "\r\n" : "\n";
+    const lines = previous.split(/\r?\n/);
+    const block = [...extensionsBlock(config)];
+    const region = extensionsRegion(lines);
+    let spliced;
+    if (region !== undefined) {
+        spliced = [...lines.slice(0, region.start), ...block, ...lines.slice(region.end + 1)].join(newline);
+    }
+    else {
+        // No `extensions:` key at all: place it before `github:`, else append.
+        const github = lines.findIndex((line) => /^github:/.test(line));
+        const at = github === -1 ? lines.length : github;
+        spliced = [...lines.slice(0, at), ...block, "", ...lines.slice(at)].join(newline);
+    }
+    const read = parseYaml(spliced, "config.yml");
+    if (read.problems.length > 0)
+        return canonical;
+    const reparsed = parseConfig(read.value, "config.yml");
+    if (reparsed.value === undefined)
+        return canonical;
+    return serialiseConfig(reparsed.value) === canonical ? spliced : canonical;
+}

package/dist/config/lifecycle.d.ts

@@ -0,0 +1,34 @@
+import type { ParseResult } from "./config.js";
+/** The seven core Delivery lifecycle stages, in lifecycle order (Delivery Graph §17). */
+export declare const CORE_STAGES: readonly ["capture-intent", "propose-contracts", "approve-contract", "write-brief", "deliver-brief", "review", "prepare-evidence"];
+export type StageName = (typeof CORE_STAGES)[number];
+export declare const EXECUTION_MODES: readonly ["manual", "automatic"];
+export type ExecutionMode = (typeof EXECUTION_MODES)[number];
+export declare const ACTORS: readonly ["human", "agent"];
+export type Actor = (typeof ACTORS)[number];
+export interface StageConfig {
+    readonly execution: ExecutionMode;
+    readonly actor?: Actor;
+}
+/** `.pactwright/lifecycle.yml` — how the repository operates the lifecycle. */
+export interface LifecycleConfig {
+    readonly version: 1;
+    readonly stages: Readonly<Record<StageName, StageConfig>>;
+}
+export declare const LIFECYCLE_VERSION = 1;
+/** The stage whose configured actor authorises Decisions (Delivery Graph §8). */
+export declare const DECISION_STAGE: "approve-contract";
+export declare function parseLifecycle(raw: unknown, path: string): ParseResult<LifecycleConfig>;
+export declare function loadLifecycle(path: string): ParseResult<LifecycleConfig>;
+/** The actor authorised to make Decisions: `approve-contract`'s configured actor. */
+export declare function decisionActor(lifecycle: LifecycleConfig): Actor;
+/**
+ * A human gate is a stage that cannot proceed without a human: manual
+ * execution or a human actor. `lifecycle run` stops here and never skips one
+ * (Delivery Graph §20). In the §17 default example the gates are
+ * capture-intent and approve-contract; in the automated example only
+ * capture-intent remains.
+ */
+export declare function isHumanGate(stage: StageConfig): boolean;
+/** The human gates of a lifecycle, in stage order. */
+export declare function humanGates(lifecycle: LifecycleConfig): readonly StageName[];

package/dist/config/lifecycle.js

@@ -0,0 +1,81 @@
+import { Checker, expectEnum, expectRecord, expectVersion, rejectUnknownKeys, requireKeys, } from "../validation.js";
+import { readYamlFile } from "../yaml.js";
+/** The seven core Delivery lifecycle stages, in lifecycle order (Delivery Graph §17). */
+export const CORE_STAGES = [
+    "capture-intent",
+    "propose-contracts",
+    "approve-contract",
+    "write-brief",
+    "deliver-brief",
+    "review",
+    "prepare-evidence",
+];
+export const EXECUTION_MODES = ["manual", "automatic"];
+export const ACTORS = ["human", "agent"];
+export const LIFECYCLE_VERSION = 1;
+/** The stage whose configured actor authorises Decisions (Delivery Graph §8). */
+export const DECISION_STAGE = "approve-contract";
+export function parseLifecycle(raw, path) {
+    const c = new Checker(path);
+    const root = expectRecord(c, raw, "lifecycle");
+    if (root === undefined)
+        return { value: undefined, problems: c.problems };
+    requireKeys(c, root, "lifecycle", ["version", "stages"]);
+    rejectUnknownKeys(c, root, "lifecycle", ["version", "stages"]);
+    expectVersion(c, root["version"], "lifecycle.version", LIFECYCLE_VERSION);
+    const stages = {};
+    const rawStages = expectRecord(c, root["stages"], "lifecycle.stages");
+    if (rawStages !== undefined) {
+        requireKeys(c, rawStages, "lifecycle.stages", CORE_STAGES);
+        for (const key of Object.keys(rawStages)) {
+            if (!CORE_STAGES.includes(key)) {
+                c.fail("unknown-stage", `lifecycle.stages has unknown stage "${key}"; only core Delivery stages are configurable here`);
+            }
+        }
+        for (const name of CORE_STAGES) {
+            const label = `lifecycle.stages.${name}`;
+            const stage = expectRecord(c, rawStages[name], label);
+            if (stage === undefined)
+                continue;
+            requireKeys(c, stage, label, ["execution"]);
+            rejectUnknownKeys(c, stage, label, ["execution", "actor"]);
+            const execution = expectEnum(c, stage["execution"], `${label}.execution`, EXECUTION_MODES);
+            const actor = stage["actor"] === undefined
+                ? undefined
+                : expectEnum(c, stage["actor"], `${label}.actor`, ACTORS);
+            if (name === DECISION_STAGE && stage["actor"] === undefined) {
+                c.fail("missing-actor", `${label} must declare "actor"; Decisions must be authorised by lifecycle.yml (Delivery Graph §8)`);
+            }
+            if (execution !== undefined) {
+                stages[name] = actor === undefined ? { execution } : { execution, actor };
+            }
+        }
+    }
+    if (!c.ok)
+        return { value: undefined, problems: c.problems };
+    return { value: { version: 1, stages: stages }, problems: [] };
+}
+export function loadLifecycle(path) {
+    const read = readYamlFile(path);
+    if (read.problems.length > 0)
+        return { value: undefined, problems: read.problems };
+    return parseLifecycle(read.value, path);
+}
+/** The actor authorised to make Decisions: `approve-contract`'s configured actor. */
+export function decisionActor(lifecycle) {
+    return lifecycle.stages[DECISION_STAGE].actor;
+}
+/**
+ * A human gate is a stage that cannot proceed without a human: manual
+ * execution or a human actor. `lifecycle run` stops here and never skips one
+ * (Delivery Graph §20). In the §17 default example the gates are
+ * capture-intent and approve-contract; in the automated example only
+ * capture-intent remains.
+ */
+export function isHumanGate(stage) {
+    return stage.execution === "manual" || stage.actor === "human";
+}
+/** The human gates of a lifecycle, in stage order. */
+export function humanGates(lifecycle) {
+    return CORE_STAGES.filter((name) => isHumanGate(lifecycle.stages[name]));
+}

package/dist/config/lock.d.ts

@@ -0,0 +1,43 @@
+import type { ParseResult } from "./config.js";
+/**
+ * One locked extension: the exact package and version it resolved to, and a
+ * hash of its manifest (Distribution §6).
+ */
+export interface LockExtension {
+    readonly package: string;
+    readonly version: string;
+    /**
+     * Hash of the extension's declared manifest — its id, package, version,
+     * runtime range, dependencies, graph types, namespaces, capabilities and
+     * GitHub profile. It pins what the extension declares, not the bytes of
+     * the code it ships.
+     */
+    readonly hash: string;
+    /** Extension id → exact version of a required peer extension. Omitted when empty. */
+    readonly dependencies?: Readonly<Record<string, string>>;
+}
+/** `.pactwright/lock.yml` — the exact resolved setup (Distribution §6). */
+export interface LockFile {
+    readonly runtime: {
+        readonly version: string;
+    };
+    readonly agentPack: {
+        readonly name: string;
+        readonly version: string;
+        readonly hash: string;
+    };
+    /** Agent name → content hash. */
+    readonly agents: Readonly<Record<string, string>>;
+    /** Skill name → content hash. A runtime addition relative to the §6 shape. */
+    readonly skills: Readonly<Record<string, string>>;
+    /**
+     * Extension id → locked extension (Distribution §6). Empty only when no
+     * extension is configured.
+     */
+    readonly extensions: Readonly<Record<string, LockExtension>>;
+}
+export declare const HASH_PATTERN: RegExp;
+/** Extension ids are kebab-case identifiers, like `project-intelligence`. */
+export declare const EXTENSION_ID_PATTERN: RegExp;
+export declare function parseLock(raw: unknown, path: string): ParseResult<LockFile>;
+export declare function loadLock(path: string): ParseResult<LockFile>;

package/dist/config/lock.js

@@ -0,0 +1,141 @@
+import { Checker, expectRecord, expectString, rejectUnknownKeys, requireKeys, } from "../validation.js";
+import { readYamlFile } from "../yaml.js";
+export const HASH_PATTERN = /^sha256:[0-9a-f]{64}$/;
+/** Extension ids are kebab-case identifiers, like `project-intelligence`. */
+export const EXTENSION_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/** The lock records exact resolved state, so versions are never ranges. */
+const EXACT_VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+function expectHash(c, value, label) {
+    const text = expectString(c, value, label);
+    if (text === undefined)
+        return undefined;
+    if (!HASH_PATTERN.test(text))
+        return c.fail("invalid-hash", `${label} must match sha256:<64 hex>`);
+    return text;
+}
+function expectExactVersion(c, value, label) {
+    const text = expectString(c, value, label);
+    if (text === undefined)
+        return undefined;
+    if (!EXACT_VERSION_PATTERN.test(text)) {
+        return c.fail("invalid-version", `${label} must be an exact x.y.z version, found "${text}"`);
+    }
+    return text;
+}
+function parseExtension(c, raw, label) {
+    const record = expectRecord(c, raw, label);
+    if (record === undefined)
+        return undefined;
+    requireKeys(c, record, label, ["package", "version", "hash"]);
+    rejectUnknownKeys(c, record, label, ["package", "version", "hash", "dependencies"]);
+    const pkg = expectString(c, record["package"], `${label}.package`);
+    const version = expectExactVersion(c, record["version"], `${label}.version`);
+    const hash = expectHash(c, record["hash"], `${label}.hash`);
+    let dependencies;
+    if (record["dependencies"] !== undefined) {
+        const deps = expectRecord(c, record["dependencies"], `${label}.dependencies`);
+        if (deps !== undefined) {
+            dependencies = {};
+            for (const id of Object.keys(deps).sort()) {
+                if (!EXTENSION_ID_PATTERN.test(id)) {
+                    c.fail("invalid-extension-id", `${label}.dependencies key "${id}" is not a valid extension id`);
+                    continue;
+                }
+                const wanted = expectExactVersion(c, deps[id], `${label}.dependencies.${id}`);
+                if (wanted !== undefined)
+                    dependencies[id] = wanted;
+            }
+        }
+    }
+    if (pkg === undefined || version === undefined || hash === undefined)
+        return undefined;
+    return {
+        package: pkg,
+        version,
+        hash,
+        ...(dependencies === undefined || Object.keys(dependencies).length === 0
+            ? {}
+            : { dependencies }),
+    };
+}
+function parseExtensions(c, raw) {
+    const out = {};
+    if (raw === undefined)
+        return out;
+    const record = expectRecord(c, raw, "lock.extensions");
+    if (record === undefined)
+        return out;
+    for (const id of Object.keys(record).sort()) {
+        if (!EXTENSION_ID_PATTERN.test(id)) {
+            c.fail("invalid-extension-id", `lock.extensions key "${id}" is not a valid extension id`);
+            continue;
+        }
+        const extension = parseExtension(c, record[id], `lock.extensions.${id}`);
+        if (extension !== undefined)
+            out[id] = extension;
+    }
+    return out;
+}
+function parseHashMap(c, raw, label) {
+    const out = {};
+    if (raw === undefined)
+        return out;
+    const record = expectRecord(c, raw, label);
+    if (record === undefined)
+        return out;
+    for (const key of Object.keys(record).sort()) {
+        const hash = expectHash(c, record[key], `${label}.${key}`);
+        if (hash !== undefined)
+            out[key] = hash;
+    }
+    return out;
+}
+export function parseLock(raw, path) {
+    const c = new Checker(path);
+    const root = expectRecord(c, raw, "lock");
+    if (root === undefined)
+        return { value: undefined, problems: c.problems };
+    requireKeys(c, root, "lock", ["runtime", "agent_pack"]);
+    rejectUnknownKeys(c, root, "lock", ["runtime", "agent_pack", "agents", "skills", "extensions"]);
+    let runtimeVersion;
+    const runtime = expectRecord(c, root["runtime"], "lock.runtime");
+    if (runtime !== undefined) {
+        requireKeys(c, runtime, "lock.runtime", ["version"]);
+        rejectUnknownKeys(c, runtime, "lock.runtime", ["version"]);
+        runtimeVersion = expectString(c, runtime["version"], "lock.runtime.version");
+    }
+    let pack;
+    const agentPack = expectRecord(c, root["agent_pack"], "lock.agent_pack");
+    if (agentPack !== undefined) {
+        requireKeys(c, agentPack, "lock.agent_pack", ["name", "version", "hash"]);
+        rejectUnknownKeys(c, agentPack, "lock.agent_pack", ["name", "version", "hash"]);
+        const name = expectString(c, agentPack["name"], "lock.agent_pack.name");
+        const version = expectString(c, agentPack["version"], "lock.agent_pack.version");
+        const hash = expectHash(c, agentPack["hash"], "lock.agent_pack.hash");
+        if (name !== undefined && version !== undefined && hash !== undefined) {
+            pack = { name, version, hash };
+        }
+    }
+    const agents = parseHashMap(c, root["agents"], "lock.agents");
+    const skills = parseHashMap(c, root["skills"], "lock.skills");
+    const extensions = parseExtensions(c, root["extensions"]);
+    if (!c.ok || runtimeVersion === undefined || pack === undefined) {
+        return { value: undefined, problems: c.problems };
+    }
+    return {
+        value: {
+            runtime: { version: runtimeVersion },
+            agentPack: pack,
+            agents,
+            skills,
+            extensions,
+        },
+        problems: [],
+    };
+}
+export function loadLock(path) {
+    const read = readYamlFile(path);
+    if (read.problems.length > 0)
+        return { value: undefined, problems: read.problems };
+    return parseLock(read.value, path);
+}

package/dist/context.d.ts

@@ -0,0 +1,59 @@
+import type { Edge } from "./graph/edges.js";
+import { type DeliveryState, type Lineage } from "./graph/lineage.js";
+import type { GraphNode } from "./graph/nodes.js";
+import type { Project } from "./loader.js";
+/** A superseded record of the lineage's history (`--history` only). */
+export interface HistoryRecord {
+    readonly node: GraphNode;
+    /** Ids of the records that supersede this one. */
+    readonly supersededBy: readonly string[];
+}
+/** One namespaced extension contribution (Delivery Graph §22). */
+export interface ExtensionContext {
+    readonly namespace: string;
+    readonly context: unknown;
+}
+/**
+ * The extension-context seam. Enabled extensions contribute after the core
+ * lineage is resolved; they receive it read-only and can only add one
+ * namespaced entry, so extension context never alters the Delivery lineage.
+ * No core contributor exists in this checkpoint.
+ */
+export type ContextContributor = (input: {
+    readonly project: Project;
+    readonly lineage: Lineage;
+    readonly history: boolean;
+}) => ExtensionContext | undefined;
+/** `pactwright context <node-id>` result (Delivery Graph §22). */
+export interface DeliveryContext {
+    /** The node id that was asked for. */
+    readonly requested: string;
+    readonly intent: string;
+    readonly state: DeliveryState;
+    /** Current core lineage in stage order; only existing stages. */
+    readonly lineage: readonly GraphNode[];
+    /** False when the requested node is superseded (it is then not in `lineage`). */
+    readonly requestedIsCurrent: boolean;
+    /** Superseded records of this intent's tree, sorted by id; only with `history`. */
+    readonly history?: readonly HistoryRecord[];
+    /** Namespaced extension context; empty in this checkpoint. */
+    readonly extensions: Readonly<Record<string, unknown>>;
+}
+export interface ContextOptions {
+    readonly history?: boolean;
+    readonly contributors?: readonly ContextContributor[];
+}
+/**
+ * The intent a core Delivery node belongs to, found by walking structural
+ * edges (superseded records included). `undefined` when the node is not
+ * linked to any intent.
+ */
+export declare function findIntentOf(nodeId: string, nodes: readonly GraphNode[], edges: readonly Edge[]): GraphNode | undefined;
+/**
+ * Resolves the current core Delivery lineage the node belongs to (§22).
+ * Only the five core node types exist in the graph, so rejected
+ * alternatives, review transcripts, obsolete reasoning and execution
+ * provenance can never appear; superseded records appear only under
+ * `history` when asked for.
+ */
+export declare function loadContext(project: Project, nodeId: string, options?: ContextOptions): DeliveryContext;

package/dist/context.js

@@ -0,0 +1,111 @@
+import { PactwrightError } from "./errors.js";
+import { deriveLineage } from "./graph/lineage.js";
+/** Structural edge from a core node towards its intent, regardless of currency. */
+const TOWARDS_INTENT = {
+    evidence: { type: "evidences", direction: "out" }, // evidence --evidences--> brief
+    brief: { type: "decomposes", direction: "out" }, // brief --decomposes--> contract
+    contract: { type: "selects", direction: "in" }, // decision --selects--> contract
+    decision: { type: "resolves", direction: "out" }, // decision --resolves--> intent
+};
+/**
+ * The intent a core Delivery node belongs to, found by walking structural
+ * edges (superseded records included). `undefined` when the node is not
+ * linked to any intent.
+ */
+export function findIntentOf(nodeId, nodes, edges) {
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const seen = new Set();
+    let current = byId.get(nodeId);
+    while (current !== undefined && !seen.has(current.id)) {
+        if (current.type === "intent")
+            return current;
+        seen.add(current.id);
+        const step = TOWARDS_INTENT[current.type];
+        if (step === undefined)
+            return undefined;
+        const id = current.id;
+        const link = edges.find((edge) => step.direction === "out"
+            ? edge.type === step.type && edge.source === id
+            : edge.type === step.type && edge.target === id);
+        current =
+            link === undefined
+                ? undefined
+                : byId.get(step.direction === "out" ? link.target : link.source);
+    }
+    return undefined;
+}
+/** Every core node in the intent's tree, current or not, sorted by id. */
+function lineageTree(intent, nodes, edges) {
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const collect = (targets, type, direction, nodeType) => edges
+        .filter((edge) => edge.type === type &&
+        targets.includes(direction === "sources" ? edge.target : edge.source))
+        .map((edge) => byId.get(direction === "sources" ? edge.source : edge.target))
+        .filter((node) => node !== undefined && node.type === nodeType);
+    const decisions = collect([intent.id], "resolves", "sources", "decision");
+    const contracts = collect(decisions.map((d) => d.id), "selects", "targets", "contract");
+    const briefs = collect(contracts.map((c) => c.id), "decomposes", "sources", "brief");
+    const evidence = collect(briefs.map((b) => b.id), "evidences", "sources", "evidence");
+    return [intent, ...decisions, ...contracts, ...briefs, ...evidence].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+}
+/**
+ * Resolves the current core Delivery lineage the node belongs to (§22).
+ * Only the five core node types exist in the graph, so rejected
+ * alternatives, review transcripts, obsolete reasoning and execution
+ * provenance can never appear; superseded records appear only under
+ * `history` when asked for.
+ */
+export function loadContext(project, nodeId, options = {}) {
+    const { nodes, edges } = project.graph;
+    const node = nodes.find((candidate) => candidate.id === nodeId);
+    if (node === undefined) {
+        throw new PactwrightError("unknown-node", `"${nodeId}" is not a node in this project`);
+    }
+    const intent = findIntentOf(nodeId, nodes, edges);
+    if (intent === undefined) {
+        throw new PactwrightError("unlinked-node", `${node.type} "${nodeId}" is not linked to any intent; it has no Delivery lineage`);
+    }
+    const lineage = deriveLineage(intent.id, nodes, edges);
+    if (lineage === undefined) {
+        // The loader rejects ambiguous lineages, so this cannot happen for a loaded project.
+        throw new PactwrightError("ambiguous-lineage", `intent "${intent.id}" has an ambiguous lineage`);
+    }
+    const current = [
+        lineage.intent,
+        lineage.decision,
+        lineage.contract,
+        lineage.brief,
+        lineage.evidence,
+    ].filter((record) => record !== undefined);
+    const currentIds = new Set(current.map((record) => record.id));
+    const extensions = {};
+    for (const contribute of options.contributors ?? []) {
+        const contribution = contribute({ project, lineage, history: options.history === true });
+        if (contribution === undefined)
+            continue;
+        if (contribution.namespace in extensions) {
+            throw new PactwrightError("duplicate-context-namespace", `extension context namespace "${contribution.namespace}" was contributed twice`);
+        }
+        extensions[contribution.namespace] = contribution.context;
+    }
+    const base = {
+        requested: nodeId,
+        intent: intent.id,
+        state: lineage.state,
+        lineage: current,
+        requestedIsCurrent: currentIds.has(nodeId),
+        extensions,
+    };
+    if (options.history !== true)
+        return base;
+    const history = lineageTree(intent, nodes, edges)
+        .filter((record) => !currentIds.has(record.id))
+        .map((record) => ({
+        node: record,
+        supersededBy: edges
+            .filter((edge) => edge.type === "supersedes" && edge.target === record.id)
+            .map((edge) => edge.source)
+            .sort(),
+    }));
+    return { ...base, history };
+}