pactwright 0.0.1

package/dist/extension/manage.js

@@ -0,0 +1,372 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { tempSibling } from "../atomic.js";
+import { loadConfig, rewriteConfig, } from "../config/config.js";
+import { EXTENSION_ID_PATTERN, loadLock } from "../config/lock.js";
+import { locatePackage } from "../pack/locate.js";
+import { resolveDesiredState, serialiseLock } from "../pack/resolve.js";
+import { projectPaths } from "../project.js";
+import { validateProject } from "../validate.js";
+import { loadExtensionManifest } from "./manifest.js";
+import { resolveExtensionsBestEffort } from "./resolve.js";
+const failure = (root, problems) => ({
+    ok: false,
+    root,
+    changes: [],
+    githubProfiles: [],
+    preserved: [],
+    problems,
+});
+/**
+ * `add project-intelligence` resolves `@pactwright/project-intelligence`;
+ * the explicit package form is also valid (Distribution §4).
+ */
+function parseSpec(spec) {
+    if (spec.startsWith("@")) {
+        const slash = spec.indexOf("/");
+        const id = slash === -1 ? "" : spec.slice(slash + 1);
+        if (!EXTENSION_ID_PATTERN.test(id)) {
+            return {
+                code: "invalid-extension-id",
+                message: `"${spec}" does not name an extension: the part after "/" must be a valid extension id`,
+            };
+        }
+        return { id, source: spec };
+    }
+    if (!EXTENSION_ID_PATTERN.test(spec)) {
+        return { code: "invalid-extension-id", message: `"${spec}" is not a valid extension id` };
+    }
+    return { id: spec, source: `@pactwright/${spec}` };
+}
+function withExtensions(config, extensions) {
+    return { ...config, extensions };
+}
+/**
+ * Writes config and lock atomically (temp sibling + rename, config first).
+ * `config` is `undefined` when only the lock changes, so desired state is
+ * left exactly as the user wrote it. Returns a Problem rather than throwing
+ * when either file is absent, keeping the result idiom the callers rely on.
+ */
+function writeDesiredState(root, config, lockText) {
+    const paths = projectPaths(root);
+    let previousConfig;
+    let previousLock;
+    try {
+        previousConfig = readFileSync(paths.config, "utf8");
+        previousLock = readFileSync(paths.lock, "utf8");
+    }
+    catch (error) {
+        const path = error.path ?? paths.lock;
+        return { code: "missing-file", message: "file not found", path };
+    }
+    const writeAll = (entries) => {
+        for (const [target, content] of entries) {
+            const temp = tempSibling(target);
+            writeFileSync(temp, content, "utf8");
+            renameSync(temp, target);
+        }
+    };
+    const written = [];
+    const previous = [];
+    if (config !== undefined) {
+        // Only the `extensions:` block ever changes, so the rest of the file —
+        // including whatever the team wrote in comments — is carried across.
+        written.push([paths.config, rewriteConfig(previousConfig, config)]);
+        previous.push([paths.config, previousConfig]);
+    }
+    written.push([paths.lock, lockText]);
+    previous.push([paths.lock, previousLock]);
+    writeAll(written);
+    return { restore: () => writeAll(previous) };
+}
+/**
+ * Enables an extension (Distribution §4): resolve the package, resolve and
+ * enable missing dependencies first, validate the complete required
+ * capability union, then record the exact state in config and lock. Fails
+ * before any write when compatibility is incomplete; rolls both files back
+ * if the resulting project state does not validate.
+ *
+ * "Missing" means not enabled, not merely absent: a dependency the
+ * configuration already names but has disabled is enabled too. So adding an
+ * extension that is itself already enabled still repairs a disabled
+ * dependency underneath it, at any depth, and reports what it enabled rather
+ * than `unchanged`.
+ *
+ * Because the walk crosses already-enabled dependencies to reach what is
+ * below them, an add whose enabled dependency is itself broken reports that
+ * problem rather than `unchanged`. The write would have failed on it anyway;
+ * saying so up front is the more truthful answer.
+ */
+export function addExtension(root, spec) {
+    const paths = projectPaths(root);
+    const parsed = parseSpec(spec);
+    if ("code" in parsed)
+        return failure(paths.root, [parsed]);
+    const config = loadConfig(paths.config);
+    if (config.value === undefined)
+        return failure(paths.root, config.problems);
+    const proposed = { ...config.value.extensions };
+    const added = [];
+    const problems = [];
+    // Enable the requested extension, then walk its manifest dependencies and
+    // enable every one that is not already enabled — whether it is absent from
+    // the configuration or configured and disabled (Distribution §4). A
+    // dependency the configuration already names is located by its recorded
+    // source, never by the conventional package name: sources may be paths,
+    // and resolution treats a divergence as `extension-package-mismatch`. An
+    // unconfigured dependency falls back to `@pactwright/<id>`.
+    //
+    // `visited` makes termination independent of the enabled flags, so a
+    // dependency cycle among configured extensions stops here; reporting the
+    // cycle stays with `resolveDesiredState` below.
+    const queue = [parsed];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const { id, source } = queue.shift();
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        const existing = Object.hasOwn(proposed, id) ? proposed[id] : undefined;
+        const located = locatePackage(paths.root, existing?.source ?? source, "extension");
+        if (typeof located !== "string") {
+            problems.push({
+                ...located,
+                code: located.code === "pack-not-exported" ? "extension-not-exported" : "extension-not-found",
+            });
+            continue;
+        }
+        const manifest = loadExtensionManifest(located);
+        if (manifest.value === undefined) {
+            problems.push(...manifest.problems);
+            continue;
+        }
+        if (existing === undefined) {
+            proposed[id] = { enabled: true, source };
+            added.push(id);
+        }
+        else if (!existing.enabled) {
+            proposed[id] = { ...existing, enabled: true };
+            added.push(id);
+        }
+        // Every dependency is enqueued, enabled or not: stopping at an enabled one
+        // would hide whatever sits beneath it, and a disabled dependency two hops
+        // down is exactly what needs repairing. `visited` is what bounds the walk.
+        for (const dep of manifest.value.dependencies) {
+            const configured = Object.hasOwn(proposed, dep) ? proposed[dep] : undefined;
+            queue.push({ id: dep, source: configured?.source ?? `@pactwright/${dep}` });
+        }
+    }
+    if (problems.length > 0)
+        return failure(paths.root, problems);
+    if (added.length === 0) {
+        return {
+            ok: true,
+            root: paths.root,
+            changes: [{ id: parsed.id, action: "unchanged" }],
+            githubProfiles: [],
+            preserved: [],
+            problems: [],
+        };
+    }
+    const desired = resolveDesiredState({
+        root: paths.root,
+        config: withExtensions(config.value, proposed),
+    });
+    if (desired.value === undefined)
+        return failure(paths.root, desired.problems);
+    const written = writeDesiredState(paths.root, withExtensions(config.value, proposed), serialiseLock(desired.value.lock));
+    if ("code" in written)
+        return failure(paths.root, [written]);
+    const report = validateProject({ root: paths.root });
+    if (!report.ok) {
+        written.restore();
+        return failure(paths.root, report.problems);
+    }
+    const byId = new Map(desired.value.extensions.map((e) => [e.id, e]));
+    return {
+        ok: true,
+        root: paths.root,
+        changes: added.sort().map((id) => ({
+            id,
+            action: "added",
+            ...(byId.get(id) === undefined ? {} : { version: byId.get(id).manifest.version }),
+        })),
+        githubProfiles: added
+            .map((id) => byId.get(id)?.manifest.githubProfile)
+            .filter((profile) => profile !== undefined)
+            .sort(),
+        preserved: [],
+        problems: [],
+    };
+}
+/**
+ * Removes an extension (Distribution §4). Blocked while an enabled
+ * extension still depends on it. Canonical graph data owned by the
+ * extension is never deleted — it is reported as preserved, and the user
+ * chooses separately whether to delete it.
+ *
+ * Removal is the remedy for a broken extension set, so nothing about that set
+ * being broken may block it: the dependant scan runs best effort, and when the
+ * remaining configuration still does not resolve the lock is derived from its
+ * previous contents rather than re-resolved. Both degradations are reported.
+ */
+export function removeExtension(root, id) {
+    const paths = projectPaths(root);
+    const config = loadConfig(paths.config);
+    if (config.value === undefined)
+        return failure(paths.root, config.problems);
+    if (!Object.hasOwn(config.value.extensions, id)) {
+        return failure(paths.root, [
+            { code: "extension-not-configured", message: `extension "${id}" is not configured` },
+        ]);
+    }
+    // Deliberately best effort: `remove` is the remedy for a broken extension
+    // set, so it must not be blocked by that set being broken. An extension
+    // left incompatible by a runtime bump, or whose package was uninstalled,
+    // fails every other command — including the remove that would fix it.
+    // Nothing here decides the write: the proposed `resolveDesiredState` below
+    // still refuses any state that does not resolve, so every blind spot in
+    // this scan fails closed.
+    const scan = resolveExtensionsBestEffort({ root: paths.root, config: config.value });
+    const removed = scan.extensions.find((e) => e.id === id);
+    const dependants = scan.extensions
+        .filter((e) => e.id !== id && e.config.enabled && e.manifest.dependencies.includes(id))
+        .map((e) => e.id)
+        .sort();
+    if (dependants.length > 0) {
+        return failure(paths.root, [
+            {
+                code: "extension-required-by",
+                message: `extension "${id}" cannot be removed: enabled extension${dependants.length === 1 ? "" : "s"} ${dependants.map((d) => `"${d}"`).join(", ")} still depend${dependants.length === 1 ? "s" : ""} on it`,
+            },
+        ]);
+    }
+    // Read before the write: `writeDesiredState` replaces the lock. When the
+    // manifest could not be loaded the lock still records the exact version
+    // that was resolved, so the report stays truthful.
+    const previousLock = loadLock(paths.lock);
+    const previousVersion = removed?.manifest.version ?? previousLock.value?.extensions[id]?.version;
+    const proposed = { ...config.value.extensions };
+    delete proposed[id];
+    const desired = resolveDesiredState({
+        root: paths.root,
+        config: withExtensions(config.value, proposed),
+    });
+    // Resolving afresh is the happy path. When the state left behind still does
+    // not resolve — a runtime bump breaks every extension at once, so removing
+    // one of them cannot fix the others — fall back to the lock already on
+    // disk, minus this entry. That lock is by definition the last state that
+    // did resolve, so nothing is recorded that was never resolvable, and the
+    // command that repairs a broken set stays available while the set is broken.
+    const degraded = [];
+    let lockText;
+    if (desired.value !== undefined) {
+        lockText = serialiseLock(desired.value.lock);
+    }
+    else if (previousLock.value !== undefined) {
+        const rest = { ...previousLock.value.extensions };
+        delete rest[id];
+        lockText = serialiseLock({ ...previousLock.value, extensions: rest });
+        degraded.push({
+            code: "lock-not-re-resolved",
+            message: `extension "${id}" was removed, but the remaining configuration does not resolve, so the lock was derived from its previous contents rather than re-resolved; fix the reported problems and run \`pactwright extension upgrade\` to re-lock`,
+        });
+    }
+    else {
+        return failure(paths.root, desired.problems);
+    }
+    const written = writeDesiredState(paths.root, withExtensions(config.value, proposed), lockText);
+    if ("code" in written)
+        return failure(paths.root, [written]);
+    // Preserved user-authored canonical data: records whose types the removed
+    // extension registered. `pactwright validate` reports them as unknown
+    // types until the user deletes them or re-enables the extension. The
+    // restore handle is deliberately unused: a removal is *expected* to leave
+    // records validate rejects, so `report.ok` is never consulted here.
+    const ownedTypes = new Set(removed === undefined ? [] : removed.manifest.nodeTypes);
+    const report = validateProject({ root: paths.root });
+    const preserved = removed === undefined
+        ? []
+        : report.problems
+            .map((p) => p.path)
+            .filter((p) => p !== undefined)
+            .filter((p) => [...ownedTypes].some((type) => p.includes(`/${type}-`)))
+            .sort();
+    // `preserved` is defined by attribution, so with no manifest there is no
+    // ownership fact and the only honest list is empty. A bare `[]` would read
+    // as "nothing was left behind", which cannot be supported, so the removal
+    // succeeds and says why the inventory is missing.
+    return {
+        ok: true,
+        root: paths.root,
+        changes: [
+            {
+                id,
+                action: "removed",
+                ...(previousVersion === undefined ? {} : { previousVersion }),
+            },
+        ],
+        githubProfiles: [],
+        preserved,
+        problems: [
+            ...(removed === undefined
+                ? [
+                    {
+                        code: "extension-manifest-unavailable",
+                        message: `extension "${id}" was removed, but its manifest could not be read, so the records it owned could not be listed; run \`pactwright validate\` to see records left without a registered type`,
+                    },
+                ]
+                : []),
+            ...degraded,
+        ],
+    };
+}
+/**
+ * Upgrades an extension (Distribution §15): re-resolves the configured
+ * package, validates the complete dependency graph and capability union,
+ * and updates the lock. The configuration is desired state and does not
+ * change; canonical Project Graph state is never reinterpreted.
+ */
+export function upgradeExtension(root, id) {
+    const paths = projectPaths(root);
+    const config = loadConfig(paths.config);
+    if (config.value === undefined)
+        return failure(paths.root, config.problems);
+    if (!Object.hasOwn(config.value.extensions, id)) {
+        return failure(paths.root, [
+            { code: "extension-not-configured", message: `extension "${id}" is not configured` },
+        ]);
+    }
+    const previousLock = loadLock(paths.lock);
+    const previousVersion = previousLock.value?.extensions[id]?.version;
+    const desired = resolveDesiredState({ root: paths.root, config: config.value });
+    if (desired.value === undefined)
+        return failure(paths.root, desired.problems);
+    const next = desired.value.extensions.find((e) => e.id === id);
+    // The configuration is desired state and cannot change on an upgrade, so
+    // only the lock is written. A lock that does not validate is rolled back:
+    // §15 requires an upgrade to satisfy every enabled dependant *before* the
+    // lock file changes, so a failed upgrade must leave no trace.
+    const written = writeDesiredState(paths.root, undefined, serialiseLock(desired.value.lock));
+    if ("code" in written)
+        return failure(paths.root, [written]);
+    const report = validateProject({ root: paths.root });
+    if (!report.ok) {
+        written.restore();
+        return failure(paths.root, report.problems);
+    }
+    return {
+        ok: true,
+        root: paths.root,
+        changes: [
+            {
+                id,
+                action: "upgraded",
+                ...(next === undefined ? {} : { version: next.manifest.version }),
+                ...(previousVersion === undefined ? {} : { previousVersion }),
+            },
+        ],
+        githubProfiles: [],
+        preserved: [],
+        problems: [],
+    };
+}

package/dist/extension/manifest.d.ts

@@ -0,0 +1,36 @@
+import type { ParseResult } from "../config/config.js";
+/** File name of an extension manifest at the extension package root. */
+export declare const EXTENSION_MANIFEST_FILE = "extension.yml";
+/**
+ * A versioned extension manifest (Distribution §5). The manifest declares
+ * runtime compatibility, extension dependencies, graph contribution, command
+ * namespaces, required agent capabilities and the GitHub profile. It
+ * contains no project-specific configuration.
+ */
+export interface ExtensionManifest {
+    readonly id: string;
+    readonly package: string;
+    readonly version: string;
+    /** Compatible runtime: an exact version or a `^x.y.z` caret range. */
+    readonly pactwright: string;
+    /** Ids of extensions this extension requires, in declaration order. */
+    readonly dependencies: readonly string[];
+    /** Node types this extension owns and registers in the Project Graph. */
+    readonly nodeTypes: readonly string[];
+    /** Edge types this extension owns; shared core relations are reused, not redeclared. */
+    readonly edgeTypes: readonly string[];
+    /** Command namespaces the extension registers (`runtime.namespace` or `runtime.namespaces`). */
+    readonly namespaces: readonly string[];
+    /** Agent capabilities the selected pack must provide while this extension is enabled. */
+    readonly agentCapabilities: readonly string[];
+    /**
+     * Declared GitHub profile: logical automation/projection requirements.
+     * Metadata only in this checkpoint — nothing acts on it until GitHub
+     * provisioning exists.
+     */
+    readonly githubProfile?: string;
+}
+/** Parses extension manifest data; structural checks only, no filesystem access. */
+export declare function parseExtensionManifest(raw: unknown, path: string): ParseResult<ExtensionManifest>;
+/** Loads and validates the manifest at `<dir>/extension.yml`. */
+export declare function loadExtensionManifest(dir: string): ParseResult<ExtensionManifest>;

package/dist/extension/manifest.js

@@ -0,0 +1,164 @@
+import { existsSync } from "node:fs";
+import { join as joinPath } from "node:path";
+import { EXTENSION_ID_PATTERN } from "../config/lock.js";
+import { CAPABILITY_PATTERN } from "../pack/capabilities.js";
+import { COMPAT_PATTERN, PACKAGE_NAME_PATTERN, VERSION_PATTERN } from "../pack/manifest.js";
+import { Checker, expectRecord, expectString, rejectUnknownKeys, requireKeys, } from "../validation.js";
+import { readYamlFile } from "../yaml.js";
+/** File name of an extension manifest at the extension package root. */
+export const EXTENSION_MANIFEST_FILE = "extension.yml";
+function parseTokenList(c, raw, label, pattern, kind) {
+    const out = [];
+    if (raw === undefined)
+        return out;
+    if (!Array.isArray(raw)) {
+        c.fail("invalid-type", `${label} must be a list`);
+        return out;
+    }
+    raw.forEach((item, index) => {
+        const text = expectString(c, item, `${label}[${index}]`);
+        if (text === undefined)
+            return;
+        if (!pattern.test(text)) {
+            c.fail("invalid-value", `${label}[${index}] "${text}" is not a valid ${kind}`);
+        }
+        else if (out.includes(text)) {
+            c.fail("duplicate-value", `${label} lists "${text}" more than once`);
+        }
+        else {
+            out.push(text);
+        }
+    });
+    return out;
+}
+/** Parses extension manifest data; structural checks only, no filesystem access. */
+export function parseExtensionManifest(raw, path) {
+    const c = new Checker(path);
+    const root = expectRecord(c, raw, "extension");
+    if (root === undefined) {
+        c.fail("invalid-type", "extension manifest must be a mapping");
+        return { value: undefined, problems: c.problems };
+    }
+    requireKeys(c, root, "extension", ["id", "package", "version", "pactwright"]);
+    rejectUnknownKeys(c, root, "extension", [
+        "id",
+        "package",
+        "version",
+        "pactwright",
+        "dependencies",
+        "graph",
+        "runtime",
+        "agent_capabilities",
+        "github",
+    ]);
+    const id = expectString(c, root["id"], "extension.id");
+    if (id !== undefined && !EXTENSION_ID_PATTERN.test(id)) {
+        c.fail("invalid-extension-id", `extension.id "${id}" is not a valid extension id`);
+    }
+    const pkg = expectString(c, root["package"], "extension.package");
+    if (pkg !== undefined && (pkg.length > 214 || !PACKAGE_NAME_PATTERN.test(pkg))) {
+        c.fail("invalid-value", `extension.package must be a lowercase npm package name (optionally scoped), found "${pkg}"`);
+    }
+    const version = expectString(c, root["version"], "extension.version");
+    if (version !== undefined && !VERSION_PATTERN.test(version)) {
+        c.fail("invalid-value", `extension.version must be x.y.z, found "${version}"`);
+    }
+    const pactwright = expectString(c, root["pactwright"], "extension.pactwright");
+    if (pactwright !== undefined && !COMPAT_PATTERN.test(pactwright)) {
+        c.fail("invalid-value", `extension.pactwright must be x.y.z or ^x.y.z, found "${pactwright}"`);
+    }
+    let dependencies = [];
+    if (root["dependencies"] !== undefined) {
+        const record = expectRecord(c, root["dependencies"], "extension.dependencies");
+        if (record !== undefined) {
+            requireKeys(c, record, "extension.dependencies", ["extensions"]);
+            rejectUnknownKeys(c, record, "extension.dependencies", ["extensions"]);
+            dependencies = parseTokenList(c, record["extensions"], "extension.dependencies.extensions", EXTENSION_ID_PATTERN, "extension id");
+        }
+    }
+    let nodeTypes = [];
+    let edgeTypes = [];
+    if (root["graph"] !== undefined) {
+        const record = expectRecord(c, root["graph"], "extension.graph");
+        if (record !== undefined) {
+            rejectUnknownKeys(c, record, "extension.graph", ["node_types", "edge_types"]);
+            nodeTypes = parseTokenList(c, record["node_types"], "extension.graph.node_types", EXTENSION_ID_PATTERN, "node type");
+            edgeTypes = parseTokenList(c, record["edge_types"], "extension.graph.edge_types", EXTENSION_ID_PATTERN, "edge type");
+        }
+    }
+    // Distribution §5 uses both `runtime.namespace: x` and `runtime.namespaces: [x, y]`.
+    let namespaces = [];
+    if (root["runtime"] !== undefined) {
+        const record = expectRecord(c, root["runtime"], "extension.runtime");
+        if (record !== undefined) {
+            rejectUnknownKeys(c, record, "extension.runtime", ["namespace", "namespaces"]);
+            if (record["namespace"] !== undefined && record["namespaces"] !== undefined) {
+                c.fail("invalid-value", "extension.runtime declares both namespace and namespaces; use one form");
+            }
+            else if (record["namespace"] !== undefined) {
+                const namespace = expectString(c, record["namespace"], "extension.runtime.namespace");
+                if (namespace !== undefined && !EXTENSION_ID_PATTERN.test(namespace)) {
+                    c.fail("invalid-value", `extension.runtime.namespace "${namespace}" is not a valid command namespace`);
+                }
+                else if (namespace !== undefined) {
+                    namespaces = [namespace];
+                }
+            }
+            else {
+                namespaces = parseTokenList(c, record["namespaces"], "extension.runtime.namespaces", EXTENSION_ID_PATTERN, "command namespace");
+            }
+        }
+    }
+    const agentCapabilities = parseTokenList(c, root["agent_capabilities"], "extension.agent_capabilities", CAPABILITY_PATTERN, "capability name");
+    let githubProfile;
+    if (root["github"] !== undefined) {
+        const record = expectRecord(c, root["github"], "extension.github");
+        if (record !== undefined) {
+            requireKeys(c, record, "extension.github", ["profile"]);
+            rejectUnknownKeys(c, record, "extension.github", ["profile"]);
+            githubProfile = expectString(c, record["profile"], "extension.github.profile");
+        }
+    }
+    if (!c.ok ||
+        id === undefined ||
+        pkg === undefined ||
+        version === undefined ||
+        pactwright === undefined) {
+        return { value: undefined, problems: c.problems };
+    }
+    return {
+        value: {
+            id,
+            package: pkg,
+            version,
+            pactwright,
+            dependencies,
+            nodeTypes,
+            edgeTypes,
+            namespaces,
+            agentCapabilities,
+            ...(githubProfile === undefined ? {} : { githubProfile }),
+        },
+        problems: [],
+    };
+}
+/** Loads and validates the manifest at `<dir>/extension.yml`. */
+export function loadExtensionManifest(dir) {
+    const manifestPath = joinPath(dir, EXTENSION_MANIFEST_FILE);
+    if (!existsSync(manifestPath)) {
+        return {
+            value: undefined,
+            problems: [
+                {
+                    code: "extension-not-found",
+                    message: `no ${EXTENSION_MANIFEST_FILE} found`,
+                    path: manifestPath,
+                },
+            ],
+        };
+    }
+    const read = readYamlFile(manifestPath);
+    if (read.problems.length > 0)
+        return { value: undefined, problems: read.problems };
+    return parseExtensionManifest(read.value, manifestPath);
+}

package/dist/extension/resolve.d.ts

@@ -0,0 +1,77 @@
+import type { ConfigExtension, PactwrightConfig } from "../config/config.js";
+import type { LockFile } from "../config/lock.js";
+import type { Problem } from "../errors.js";
+import { type EdgeSchema, type EdgeSchemaRegistry } from "../graph/edge-schema.js";
+import { type NodeSchema, type NodeSchemaRegistry } from "../graph/schema.js";
+import { type ExtensionManifest } from "./manifest.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 declare const RESERVED_NAMESPACES: readonly ["agent-pack", "context", "eval", "extension", "github", "help", "init", "lifecycle", "sync", "upgrade", "validate", "version"];
+/** One extension resolved from configuration to exact state. */
+export interface ResolvedExtension {
+    readonly id: string;
+    /** Absolute extension package root: where `extension.yml` lives. */
+    readonly dir: string;
+    readonly config: ConfigExtension;
+    readonly manifest: ExtensionManifest;
+    /** Hash of the resolved manifest, recorded in the lock. */
+    readonly hash: string;
+}
+export interface ResolveExtensionsOptions {
+    readonly root: string;
+    readonly config: PactwrightConfig;
+    /** Defaults to the running runtime's version. */
+    readonly runtimeVersion?: string;
+}
+/**
+ * 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 declare function resolveExtensions(options: ResolveExtensionsOptions): {
+    value: readonly ResolvedExtension[] | undefined;
+    problems: readonly Problem[];
+};
+/**
+ * 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 declare function resolveExtensionsBestEffort(options: ResolveExtensionsOptions): {
+    readonly extensions: readonly ResolvedExtension[];
+    readonly problems: readonly Problem[];
+};
+/** Manifests of the enabled extensions, the set that contributes behaviour. */
+export declare function enabledManifests(extensions: readonly ResolvedExtension[]): readonly ExtensionManifest[];
+/** The lock entries recording exactly this resolved extension set (Distribution §6). */
+export declare function extensionLockEntries(extensions: readonly ResolvedExtension[]): LockFile["extensions"];
+/**
+ * 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 declare function extensionSchemas(extensions: readonly ResolvedExtension[]): {
+    readonly nodes: readonly NodeSchema[];
+    readonly edges: readonly EdgeSchema[];
+};
+/** The core registries extended with every type the resolved extensions register. */
+export declare function composedRegistries(extensions: readonly ResolvedExtension[]): {
+    readonly nodes: NodeSchemaRegistry;
+    readonly edges: EdgeSchemaRegistry;
+};