pactwright 0.0.1

package/dist/extension/resolve.js

@@ -0,0 +1,271 @@
+import { CORE_EDGE_SCHEMAS, CORE_EDGE_TYPES, createEdgeSchemaRegistry, } from "../graph/edge-schema.js";
+import { canonicalJson } from "../graph/revision.js";
+import { CORE_NODE_SCHEMAS, CORE_NODE_TYPES, createNodeSchemaRegistry, } from "../graph/schema.js";
+import { isPathSource, locatePackage, satisfiesRange, sha256 } from "../pack/locate.js";
+import { loadExtensionManifest } from "./manifest.js";
+import { runtimeVersion } from "../version.js";
+/**
+ * Command namespaces the runtime owns; no extension may register them.
+ * Includes commands that arrive in later checkpoints so an extension cannot
+ * squat on a future core surface.
+ */
+export const RESERVED_NAMESPACES = [
+    "agent-pack",
+    "context",
+    "eval",
+    "extension",
+    "github",
+    "help",
+    "init",
+    "lifecycle",
+    "sync",
+    "upgrade",
+    "validate",
+    "version",
+];
+function manifestHash(manifest) {
+    return sha256(canonicalJson({
+        id: manifest.id,
+        package: manifest.package,
+        version: manifest.version,
+        pactwright: manifest.pactwright,
+        dependencies: manifest.dependencies,
+        node_types: manifest.nodeTypes,
+        edge_types: manifest.edgeTypes,
+        namespaces: manifest.namespaces,
+        agent_capabilities: manifest.agentCapabilities,
+        github_profile: manifest.githubProfile,
+    }));
+}
+/** Reports every dependency cycle among the resolved manifests once. */
+function cycleProblems(byId) {
+    const problems = [];
+    const states = new Map();
+    const stack = [];
+    const visit = (id) => {
+        const state = states.get(id);
+        if (state === "done")
+            return;
+        if (state === "visiting") {
+            const cycle = [...stack.slice(stack.indexOf(id)), id];
+            problems.push({
+                code: "extension-dependency-cycle",
+                message: `extension dependencies form a cycle: ${cycle.join(" → ")}`,
+            });
+            return;
+        }
+        states.set(id, "visiting");
+        stack.push(id);
+        for (const dep of byId.get(id)?.dependencies ?? []) {
+            if (byId.has(dep))
+                visit(dep);
+        }
+        stack.pop();
+        states.set(id, "done");
+    };
+    for (const id of [...byId.keys()].sort())
+        visit(id);
+    return problems;
+}
+/**
+ * Resolves every configured extension (Distribution §§4–5): locate the
+ * package, load and validate its manifest, check runtime compatibility,
+ * dependency completeness, namespace registration and graph-type ownership.
+ * Disabled extensions resolve too — their graph types stay registered so
+ * existing records keep their meaning — but only enabled extensions
+ * contribute namespaces, capabilities and behaviour. Never throws; returns
+ * every problem found in one pass.
+ */
+export function resolveExtensions(options) {
+    const { extensions, problems } = resolveExtensionsBestEffort(options);
+    if (problems.length > 0)
+        return { value: undefined, problems };
+    return { value: extensions, problems: [] };
+}
+/**
+ * Resolution without the all-or-nothing gate: every extension that could be
+ * resolved, alongside every problem found. An entry here may itself be the
+ * subject of a reported problem (`incompatible-runtime`, a package mismatch,
+ * a duplicate type or a cycle), and an extension that could not be located,
+ * whose manifest failed to load, or whose declared id disagrees with its
+ * configuration key is absent entirely.
+ *
+ * Use it only for reporting and for decisions that fail closed elsewhere —
+ * never to decide behaviour. `removeExtension` needs it because the command
+ * that repairs a broken extension set must not be blocked by that set being
+ * broken.
+ */
+export function resolveExtensionsBestEffort(options) {
+    const { root, config } = options;
+    const runtime = options.runtimeVersion ?? runtimeVersion();
+    const problems = [];
+    const resolved = [];
+    const ids = Object.keys(config.extensions).sort();
+    for (const id of ids) {
+        const entry = config.extensions[id];
+        const located = locatePackage(root, entry.source, "extension");
+        if (typeof located !== "string") {
+            problems.push({
+                ...located,
+                code: located.code === "pack-not-exported" ? "extension-not-exported" : "extension-not-found",
+            });
+            continue;
+        }
+        const loaded = loadExtensionManifest(located);
+        if (loaded.value === undefined) {
+            problems.push(...loaded.problems);
+            continue;
+        }
+        const manifest = loaded.value;
+        const path = `${located}/extension.yml`;
+        if (manifest.id !== id) {
+            problems.push({
+                code: "extension-id-mismatch",
+                message: `config.extensions.${id} resolves a manifest declaring id "${manifest.id}"`,
+                path,
+            });
+            continue;
+        }
+        if (!isPathSource(entry.source) && manifest.package !== entry.source) {
+            problems.push({
+                code: "extension-package-mismatch",
+                message: `extension "${id}" manifest declares package "${manifest.package}" but config.extensions.${id}.source is "${entry.source}"`,
+                path,
+            });
+        }
+        if (!satisfiesRange(runtime, manifest.pactwright)) {
+            problems.push({
+                code: "incompatible-runtime",
+                message: `extension "${id}@${manifest.version}" requires pactwright ${manifest.pactwright}; this runtime is ${runtime}`,
+                path,
+            });
+        }
+        resolved.push({ id, dir: located, config: entry, manifest, hash: manifestHash(manifest) });
+    }
+    // Dependency completeness: every dependency must be configured, and an
+    // enabled extension's dependencies must themselves be enabled — the rule
+    // that makes disabling a dependency underneath a dependant a reported
+    // problem rather than silent breakage (Distribution §4).
+    for (const extension of resolved) {
+        for (const dep of extension.manifest.dependencies) {
+            const configured = Object.hasOwn(config.extensions, dep) ? config.extensions[dep] : undefined;
+            if (configured === undefined) {
+                problems.push({
+                    code: "extension-dependency-missing",
+                    message: `extension "${extension.id}" requires extension "${dep}", which is not configured`,
+                });
+            }
+            else if (extension.config.enabled && !configured.enabled) {
+                problems.push({
+                    code: "extension-dependency-disabled",
+                    message: `extension "${extension.id}" is enabled but its dependency "${dep}" is disabled`,
+                });
+            }
+        }
+    }
+    problems.push(...cycleProblems(new Map(resolved.map((e) => [e.id, e.manifest]))));
+    // Namespace registration: enabled extensions only (a disabled extension
+    // contributes no behaviour), checked against the runtime's own commands
+    // and against every other enabled extension.
+    const namespaceOwners = new Map();
+    for (const extension of resolved.filter((e) => e.config.enabled)) {
+        for (const namespace of extension.manifest.namespaces) {
+            if (RESERVED_NAMESPACES.includes(namespace)) {
+                problems.push({
+                    code: "reserved-namespace",
+                    message: `extension "${extension.id}" registers command namespace "${namespace}", which the runtime reserves`,
+                });
+                continue;
+            }
+            const owner = namespaceOwners.get(namespace);
+            if (owner !== undefined) {
+                problems.push({
+                    code: "duplicate-namespace",
+                    message: `extensions "${owner}" and "${extension.id}" both register command namespace "${namespace}"`,
+                });
+            }
+            else {
+                namespaceOwners.set(namespace, extension.id);
+            }
+        }
+    }
+    // Graph-type ownership: flat shared namespace; collisions with the core
+    // types or another extension are configuration errors, reported here
+    // rather than thrown at registry construction.
+    const nodeOwners = new Map(CORE_NODE_TYPES.map((t) => [t, "core"]));
+    const edgeOwners = new Map(CORE_EDGE_TYPES.map((t) => [t, "core"]));
+    for (const extension of resolved) {
+        for (const [owners, types, kind] of [
+            [nodeOwners, extension.manifest.nodeTypes, "node"],
+            [edgeOwners, extension.manifest.edgeTypes, "edge"],
+        ]) {
+            for (const type of types) {
+                const owner = owners.get(type);
+                if (owner !== undefined) {
+                    problems.push({
+                        code: `duplicate-${kind}-type`,
+                        message: `extension "${extension.id}" registers ${kind} type "${type}", already owned by "${owner}"`,
+                    });
+                }
+                else {
+                    owners.set(type, extension.id);
+                }
+            }
+        }
+    }
+    return { extensions: resolved, problems };
+}
+/** Manifests of the enabled extensions, the set that contributes behaviour. */
+export function enabledManifests(extensions) {
+    return extensions.filter((e) => e.config.enabled).map((e) => e.manifest);
+}
+/** The lock entries recording exactly this resolved extension set (Distribution §6). */
+export function extensionLockEntries(extensions) {
+    const versions = new Map(extensions.map((e) => [e.id, e.manifest.version]));
+    return Object.fromEntries([...extensions]
+        .sort((a, b) => a.id.localeCompare(b.id))
+        .map((extension) => {
+        const dependencies = Object.fromEntries([...extension.manifest.dependencies]
+            .sort()
+            .filter((dep) => versions.has(dep))
+            .map((dep) => [dep, versions.get(dep)]));
+        return [
+            extension.id,
+            {
+                package: extension.manifest.package,
+                version: extension.manifest.version,
+                hash: extension.hash,
+                ...(Object.keys(dependencies).length === 0 ? {} : { dependencies }),
+            },
+        ];
+    }));
+}
+/**
+ * Graph schemas contributed by the resolved extensions (enabled or not, so
+ * records owned by a disabled extension keep their meaning). The manifest
+ * registers type names only; contributed schemas are structural — permissive
+ * endpoints, no extra required fields — and owned by the extension id.
+ */
+export function extensionSchemas(extensions) {
+    const nodes = [];
+    const edges = [];
+    for (const extension of [...extensions].sort((a, b) => a.id.localeCompare(b.id))) {
+        for (const type of extension.manifest.nodeTypes) {
+            nodes.push({ type, requiredFields: [] });
+        }
+        for (const type of extension.manifest.edgeTypes) {
+            edges.push({ type, owner: extension.id, sourceTypes: "any", targetTypes: "any" });
+        }
+    }
+    return { nodes, edges };
+}
+/** The core registries extended with every type the resolved extensions register. */
+export function composedRegistries(extensions) {
+    if (extensions.length === 0)
+        return { nodes: CORE_NODE_SCHEMAS, edges: CORE_EDGE_SCHEMAS };
+    const contributed = extensionSchemas(extensions);
+    return {
+        nodes: createNodeSchemaRegistry([...Object.values(CORE_NODE_SCHEMAS), ...contributed.nodes]),
+        edges: createEdgeSchemaRegistry([...Object.values(CORE_EDGE_SCHEMAS), ...contributed.edges]),
+    };
+}

package/dist/graph/edge-schema.d.ts

@@ -0,0 +1,55 @@
+import { type Problem } from "../errors.js";
+import { type Edge } from "./edges.js";
+import type { GraphNode } from "./nodes.js";
+/** Owner id of the core Delivery edge types; extensions use their extension id. */
+export declare const CORE_EDGE_OWNER = "core";
+/** The core Delivery edge types (Delivery Graph §13). */
+export declare const CORE_EDGE_TYPES: readonly ["resolves", "selects", "decomposes", "evidences", "supersedes"];
+export type CoreEdgeType = (typeof CORE_EDGE_TYPES)[number];
+/**
+ * An edge type schema in the shared typed-edge registry (Delivery Graph §13,
+ * §21). `"any"` endpoints accept every registered node type, which is how the
+ * shared `supersedes` relation is reused by extension node types instead of
+ * being redeclared (Distribution §7).
+ */
+export interface EdgeSchema {
+    readonly type: string;
+    /** Who registered and validates this type: `"core"` or an extension id. */
+    readonly owner: string;
+    readonly sourceTypes: readonly string[] | "any";
+    readonly targetTypes: readonly string[] | "any";
+    /** Source and target must be nodes of the same type. */
+    readonly sameType?: boolean;
+    /** No edge may point at its own source, and edges of this type must not form a cycle. */
+    readonly acyclic?: boolean;
+}
+/** Edge schemas keyed by edge type. */
+export type EdgeSchemaRegistry = Readonly<Record<string, EdgeSchema>>;
+/**
+ * Builds a frozen registry. Throws `duplicate-edge-type` when two schemas
+ * claim the same type; later extensions compose registries with
+ * `createEdgeSchemaRegistry([...Object.values(CORE_EDGE_SCHEMAS), ...own])`.
+ */
+export declare function createEdgeSchemaRegistry(schemas: readonly EdgeSchema[]): EdgeSchemaRegistry;
+/** Registered edge types, sorted. */
+export declare function edgeTypes(registry: EdgeSchemaRegistry): readonly string[];
+/**
+ * The core Delivery relations (Delivery Graph §13):
+ *
+ * ```text
+ * decision --resolves----> intent
+ * decision --selects-----> contract
+ * brief    --decomposes--> contract
+ * evidence --evidences---> brief
+ * node     --supersedes--> same node type
+ * ```
+ */
+export declare const CORE_EDGE_SCHEMAS: EdgeSchemaRegistry;
+/**
+ * Validates the shared typed-edge store against the node set and the edge
+ * registry (Delivery Graph §21, Edges): declared type, source exists, target
+ * exists, valid endpoint types, same-type supersession, no self-supersession,
+ * no supersession cycles. Field shape and unique tuples are already enforced
+ * by `parseEdges`. `path` is the edges file every problem is reported against.
+ */
+export declare function validateEdges(edges: readonly Edge[], nodes: readonly GraphNode[], registry: EdgeSchemaRegistry, path: string): readonly Problem[];

package/dist/graph/edges.d.ts

@@ -0,0 +1,22 @@
+import type { Problem } from "../errors.js";
+/** One typed edge in the shared store (Delivery Graph §13). */
+export interface Edge {
+    readonly source: string;
+    readonly type: string;
+    readonly target: string;
+}
+export declare const EDGE_TYPE_PATTERN: RegExp;
+export interface EdgesParseResult {
+    /** Successfully parsed edges, in file order. */
+    readonly edges: readonly Edge[];
+    readonly problems: readonly Problem[];
+}
+export declare function edgeKey(edge: Edge): string;
+/**
+ * Parses `specs/graph/edges.yml`: `{ edges: [{source, type, target}, ...] }`.
+ * An empty document or `edges: []` is a valid empty store. Duplicate
+ * `(source, type, target)` tuples are reported and dropped. Semantic checks
+ * (registered type, endpoints, supersession) live in `validateEdges`.
+ */
+export declare function parseEdges(raw: unknown, path: string): EdgesParseResult;
+export declare function loadEdges(path: string): EdgesParseResult;

package/dist/graph/edges.js

@@ -0,0 +1,63 @@
+import { Checker, expectRecord, expectString, rejectUnknownKeys, requireKeys, } from "../validation.js";
+import { readYamlFile } from "../yaml.js";
+export const EDGE_TYPE_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+export function edgeKey(edge) {
+    return `${edge.source} --${edge.type}--> ${edge.target}`;
+}
+/**
+ * Parses `specs/graph/edges.yml`: `{ edges: [{source, type, target}, ...] }`.
+ * An empty document or `edges: []` is a valid empty store. Duplicate
+ * `(source, type, target)` tuples are reported and dropped. Semantic checks
+ * (registered type, endpoints, supersession) live in `validateEdges`.
+ */
+export function parseEdges(raw, path) {
+    const c = new Checker(path);
+    if (raw === null || raw === undefined)
+        return { edges: [], problems: [] };
+    const root = expectRecord(c, raw, "edges file");
+    if (root === undefined)
+        return { edges: [], problems: c.problems };
+    requireKeys(c, root, "edges file", ["edges"]);
+    rejectUnknownKeys(c, root, "edges file", ["edges"]);
+    const list = root["edges"];
+    if (list === null || list === undefined)
+        return { edges: [], problems: c.problems };
+    if (!Array.isArray(list)) {
+        c.fail("invalid-type", "edges must be a list");
+        return { edges: [], problems: c.problems };
+    }
+    const edges = [];
+    const seen = new Set();
+    list.forEach((item, index) => {
+        const label = `edges[${index}]`;
+        const record = expectRecord(c, item, label);
+        if (record === undefined)
+            return;
+        requireKeys(c, record, label, ["source", "type", "target"]);
+        rejectUnknownKeys(c, record, label, ["source", "type", "target"]);
+        const source = expectString(c, record["source"], `${label}.source`);
+        const type = expectString(c, record["type"], `${label}.type`);
+        const target = expectString(c, record["target"], `${label}.target`);
+        if (source === undefined || type === undefined || target === undefined)
+            return;
+        if (!EDGE_TYPE_PATTERN.test(type)) {
+            c.fail("invalid-value", `${label}.type "${type}" must be a lowercase kebab-case token`);
+            return;
+        }
+        const edge = { source, type, target };
+        const key = edgeKey(edge);
+        if (seen.has(key)) {
+            c.fail("duplicate-edge", `${label} repeats edge ${key}`);
+            return;
+        }
+        seen.add(key);
+        edges.push(edge);
+    });
+    return { edges, problems: c.problems };
+}
+export function loadEdges(path) {
+    const read = readYamlFile(path);
+    if (read.problems.length > 0)
+        return { edges: [], problems: read.problems };
+    return parseEdges(read.value, path);
+}

package/dist/graph/ids.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Turns a title into the `<slug>` part of a node id: lowercase, runs of
+ * non-alphanumerics become single dashes, truncated to `MAX_SLUG_LENGTH`.
+ * `undefined` when nothing usable remains. Truncation never harms
+ * uniqueness: `mintNodeId` hashes the full creation input, not the slug.
+ */
+export declare function slugify(title: string): string | undefined;
+/**
+ * Mints a `<type>-<slug>-<short-hash>` node id (Delivery Graph §5). The
+ * short-hash is the first 8 hex digits of sha256 over type, slug and seed,
+ * so the same creation input always mints the same id; on a collision with
+ * an existing id more digits are taken.
+ */
+export declare function mintNodeId(type: string, slug: string, seed: string, taken: ReadonlySet<string>): string;

package/dist/graph/ids.js

@@ -0,0 +1,38 @@
+import { createHash } from "node:crypto";
+/**
+ * The longest slug a node id may carry. The id adds the type, a dash and up
+ * to 64 hash digits, and the filename adds `.md`; 180 keeps the whole name
+ * comfortably under the common 255-byte filesystem limit.
+ */
+const MAX_SLUG_LENGTH = 180;
+/**
+ * Turns a title into the `<slug>` part of a node id: lowercase, runs of
+ * non-alphanumerics become single dashes, truncated to `MAX_SLUG_LENGTH`.
+ * `undefined` when nothing usable remains. Truncation never harms
+ * uniqueness: `mintNodeId` hashes the full creation input, not the slug.
+ */
+export function slugify(title) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, MAX_SLUG_LENGTH)
+        .replace(/-+$/, "");
+    return slug.length === 0 ? undefined : slug;
+}
+/**
+ * Mints a `<type>-<slug>-<short-hash>` node id (Delivery Graph §5). The
+ * short-hash is the first 8 hex digits of sha256 over type, slug and seed,
+ * so the same creation input always mints the same id; on a collision with
+ * an existing id more digits are taken.
+ */
+export function mintNodeId(type, slug, seed, taken) {
+    const digest = createHash("sha256").update(`${type}\n${slug}\n${seed}`, "utf8").digest("hex");
+    for (let length = 8; length <= digest.length; length += 1) {
+        const id = `${type}-${slug}-${digest.slice(0, length)}`;
+        if (!taken.has(id))
+            return id;
+    }
+    // 64 hex digits colliding means the identical node already exists.
+    return `${type}-${slug}-${digest}`;
+}

package/dist/graph/lineage.d.ts

@@ -0,0 +1,48 @@
+import type { Problem } from "../errors.js";
+import type { Edge } from "./edges.js";
+import type { GraphNode } from "./nodes.js";
+/**
+ * Derived Delivery lifecycle states (Delivery Graph §14). These are views of
+ * canonical graph structure, never stored node fields.
+ */
+export declare const DELIVERY_STATES: readonly ["open", "deferred", "rejected", "contracted", "delivering", "done"];
+export type DeliveryState = (typeof DELIVERY_STATES)[number];
+/**
+ * The current Delivery lineage of one intent: the current records that hang
+ * off it, one per type, plus the lifecycle state derived from which of them
+ * exist. Records that are missing simply are not there yet.
+ */
+export interface Lineage {
+    readonly intent: GraphNode;
+    readonly decision?: GraphNode;
+    readonly contract?: GraphNode;
+    readonly brief?: GraphNode;
+    readonly evidence?: GraphNode;
+    readonly state: DeliveryState;
+    /** The intent itself is superseded: the lineage is frozen (§15). */
+    readonly superseded: boolean;
+}
+export interface LineageResult {
+    /** One lineage per unambiguous intent, sorted by intent id. */
+    readonly lineages: readonly Lineage[];
+    /** Current-lineage ambiguity problems (Delivery Graph §21). */
+    readonly problems: readonly Problem[];
+}
+/**
+ * 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 declare function isCurrent(id: string, edges: readonly Edge[]): boolean;
+/**
+ * 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 declare function deriveLineages(nodes: readonly GraphNode[], edges: readonly Edge[]): LineageResult;
+/** The lineage of one intent; `undefined` when the id is not an intent or the lineage is ambiguous. */
+export declare function deriveLineage(intentId: string, nodes: readonly GraphNode[], edges: readonly Edge[]): Lineage | undefined;
+/** Current-lineage ambiguity validation (Delivery Graph §21). */
+export declare function validateLineages(nodes: readonly GraphNode[], edges: readonly Edge[]): readonly Problem[];