@sigrun/sigrun 0.0.0-stage → 0.1.0

package/dist/harness/loader.js

@@ -0,0 +1,1236 @@
+/**
+ * The extension loader (spec §3 boot order, §4.1 deploy-time list).
+ *
+ * Extensions are EXTERNAL packages (separate repos — the
+ * extension-separation ruling). `SIGRUN_EXTENSIONS` carries a comma-separated
+ * specifiers (npm package names or resolvable paths); the loader
+ * dynamic-imports each, resolves the sigrun extension-package contract, and
+ * installs the pi-durable `Extension` into the registry *before*
+ * `Harness.open` reads it.
+ *
+ * A failing extension is QUARANTINED: logged, reported as a degraded surface
+ * via the outcome list (which `GET /v1/meta`, Task 9, surfaces as
+ * `extensions[].status`), and boot continues — the loader never throws.
+ *
+ * Extension IDENTITY is the slug (spec §6): each resolved extension's
+ * declared name is sanitized ONCE at load (`slugifyName`,
+ * src/harness/stores.ts) and the slug replaces the name for everything
+ * downstream — the registry key, the seam host's identity, interaction/
+ * ambient records, worker names, and health correlation. A declared name
+ * that sanitizes to an empty slug, or a slug already claimed by another
+ * loaded extension this boot, fails the LOAD (quarantine naming the
+ * declared name(s)) — never the first store use mid-run.
+ *
+ * The sigrun extension-package contract: a package's default export is a
+ * factory returning an object with an `extension: Extension` field, plus an
+ * optional §3 `health` producer (spec §3 — the memory-backend form; Task
+ * 9e retains it for the §5 meta `health.memory` aggregation). A factory
+ * result may also carry a `providers` array (`ProviderContribution[]`,
+ * provider plugins Task 1): boot feeds every loaded contributor into
+ * `collectProviders` after the `options.extensions` seam — and a result
+ * carrying `providers` with NO `extension` is a valid PROVIDER-ONLY
+ * contributor (the model-plugin shape: no pi-durable surface, identified
+ * by its `name` field). A result may likewise carry a `webuiBundles`
+ * array (`{name, dir}[]`, build-and-webui Task 6): the loader validates it
+ * fail-loud, anchors each `dir` at the extension module's URL, and
+ * collects the entries attributed to the slug for boot's
+ * contributed-bundle registry — the same contributor-only form applies (a
+ * `webuiBundles` result with no `extension` needs a `name`). Factories may
+ * return a Promise (the plugins read their scoped settings store inside the
+ * factory); the loader awaits the result. Packages that predate the settled
+ * contract export a named `extension` directly, so the loader resolves,
+ * in order:
+ *
+ * 1. the default export, if it is a factory returning `{ extension,
+ *    health? }` or is itself an `Extension` (named `name`) — the supported
+ *    form,
+ * 2. a named `extension` export (DEPRECATED bridge — one warning per
+ *    load). The pre-contract `createMemory` named-factory bridge was
+ *    deleted in release-0.1 (its last consumer, the memory package, now
+ *    exports the factory as default).
+ *
+ * A factory result still carrying a `submit` pass-through (the retired
+ * pre-seam memory wiring) is IGNORED with one warning — never
+ * quarantined, so pre-seam packages keep loading.
+ *
+ * A factory MAY declare an arity-1 signature: the loader then passes the
+ * host context (src/harness/seam-host.ts — the interaction/ambient seam
+ * handles plus the scoped extension-stores handle `stores` (spec §5:
+ * get/set on the extension's OWN secrets section and settings file, and
+ * its own raw data/cache/state paths; src/harness/stores.ts). The host
+ * is passed only to factories with `factory.length > 0` — a length-0
+ * factory may carry a defaulted first parameter that would consume the
+ * host as a real dependency — and the factory-result
+ * `interactionKinds`/`ambientKinds` string arrays declare which seam
+ * kinds/keys the extension writes — validated fail-loud here and
+ * consumed by the seam host's write gate and the /v1/meta inventory.
+ * Only factory results can carry a health producer or kind declarations
+ * (the direct-`Extension` forms have no factory result to read one from).
+ * A `health` field that is present but not the expected shape, or kinds
+ * that are not string arrays, is a contract violation — quarantined,
+ * never silently ignored.
+ * A `providers` entry whose `provider` has no string `id` is the same class
+ * of violation (a plugin that THINKS it contributed a provider must not
+ * silently lose it).
+ *
+ * The contract is DOCUMENTED as one types-only type surface (W5 Task 1,
+ * spec §9.1): `src/extension.ts`, shipped as the `@sigrun/sigrun/extension`
+ * subpath (types-only — a runtime import of it fails loud by design).
+ * This loader's validated candidate shape is DERIVED from that contract
+ * (`CandidateFactoryResult` — reading a key the contract does not declare
+ * is a compile error here), and `LoaderReadKeys` compiles only while every
+ * factory-result key the loader reads is a key of `SigrunExtensionResult`.
+ * The implementation and the contract cannot drift silently.
+ */
+import { validateJobSpec } from "../jobs/spec.js";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { HOST_RUNTIME_MODULES, hostModuleVersion, readPackageName, readPackageVersion, resolveExtensionEntry, } from "./packages.js";
+import { RESERVED_CORE_SECTION_KEYS } from "./reserved-sections.js";
+import { slugifyName } from "./stores.js";
+/** Every lifecycle field name, in validation order (mirrors the contract doc). */
+const LIFECYCLE_FIELDS = [
+    "conversationCreated",
+    "conversationForked",
+    "conversationArchived",
+    "conversationIdle",
+    "harnessShutdown",
+    "userDeleted",
+];
+/**
+ * The reserved-key membership probe (spec §6.5 R11): a `Set` because the
+ * `as const` tuple's `includes` narrows its parameter to the literal
+ * union, which a section's `string` key can never satisfy.
+ */
+const RESERVED_SECTION_KEY_SET = new Set(RESERVED_CORE_SECTION_KEYS);
+/** A structural check for "looks like a pi-durable Extension". */
+function isExtension(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.name === "string");
+}
+/** Whether `dir` is an EXISTING directory (never throws). */
+function existingDirectory(dir) {
+    try {
+        return statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A kinds declaration must be an array of non-empty strings (or absent).
+ * The declaration drives the seam host's write gate and the /v1/meta
+ * inventory — a malformed one is a contract violation, not a shrug.
+ */
+function validateKinds(value) {
+    if (value === undefined)
+        return null;
+    if (!Array.isArray(value))
+        return "kinds declaration must be an array of strings";
+    if (value.some((k) => typeof k !== "string" || k.length === 0)) {
+        return "kinds declaration must be an array of non-empty strings";
+    }
+    return null;
+}
+/**
+ * The lifecycle event names a worker's `wakeOn` may declare (memory-seam
+ * Task 5): `harnessShutdown` is excluded — workers stop BEFORE the shutdown
+ * handlers run (spec §3 shutdown ordering), so waking on it is meaningless.
+ */
+const WAKE_EVENTS = new Set([
+    "conversationCreated",
+    "conversationForked",
+    "conversationArchived",
+    "conversationIdle",
+]);
+/**
+ * The `every` retirement message (ruling 12, jobs Task 3): jobs are the
+ * only time-based scheduler — an extension that needs a timer declares a
+ * job with a `task` action (spec §8.1a).
+ */
+const EVERY_RETIRED = "workers.every was retired — declare a job with a task action";
+/**
+ * Validate a factory result's `workers` declaration (memory-seam Task 5,
+ * the curator contract, post-`every`-retirement). Absent → undefined (no
+ * workers). Present but malformed → throw; the loader quarantines the
+ * extension with the thrown message (fail-loud: an extension that THINKS
+ * it declared a curator must not silently lose it). Validation order per
+ * worker: name, duplicate, run, every-retired, wakeOn,
+ * wakeOn-required-non-empty.
+ */
+function validateWorkers(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("extension factory returned a workers field that is not an array");
+    }
+    const seen = new Set();
+    for (const entry of value) {
+        const worker = entry;
+        const name = worker?.name;
+        if (typeof name !== "string" || name.length === 0) {
+            throw new Error("extension factory returned a worker without a name");
+        }
+        if (seen.has(name)) {
+            throw new Error(`extension factory returned a worker with a duplicate worker name "${name}"`);
+        }
+        seen.add(name);
+        if (typeof worker?.run !== "function") {
+            throw new Error(`extension factory returned a worker whose worker "${name}" has a run field that is not a function`);
+        }
+        // Ruling 12: `every` is RETIRED — a worker carrying it quarantines
+        // with the retirement message (jobs are the only timer).
+        if (worker?.every !== undefined) {
+            throw new Error(EVERY_RETIRED);
+        }
+        if (worker?.wakeOn === undefined ||
+            !Array.isArray(worker.wakeOn) ||
+            worker.wakeOn.length === 0 ||
+            worker.wakeOn.some((event) => typeof event !== "string" || !WAKE_EVENTS.has(event))) {
+            if (worker?.wakeOn !== undefined && Array.isArray(worker.wakeOn) && worker.wakeOn.length === 0) {
+                throw new Error(`extension factory returned a worker whose worker "${name}" has an empty wakeOn (declare at least one wake event)`);
+            }
+            if (worker?.wakeOn === undefined) {
+                throw new Error("extension factory returned a worker that declares a worker with neither every nor wakeOn");
+            }
+            throw new Error(`extension factory returned a worker whose worker "${name}" has an invalid wakeOn entry`);
+        }
+    }
+    return value;
+}
+/**
+ * Validate a factory result's `jobs` declaration (jobs §8.3 — the
+ * `extension` source). Absent → undefined (no jobs). Present but
+ * malformed → throw; the loader quarantines the extension with the
+ * thrown message (fail-loud: an extension that THINKS it declared a job
+ * must not silently lose it). Each entry is a full `validateJobSpec` run
+ * (the §8.2 grammar), and duplicate names within one extension are
+ * rejected (they would collide on the `ext:<slug>:<name>` id).
+ */
+function validateJobs(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("extension factory returned a jobs field that is not an array");
+    }
+    const seen = new Set();
+    const specs = [];
+    for (const entry of value) {
+        const result = validateJobSpec(entry);
+        if (!result.ok) {
+            throw new Error(`extension factory returned a job whose ${result.field} ${result.message}`);
+        }
+        if (seen.has(result.spec.name)) {
+            throw new Error(`extension factory returned a duplicate job name "${result.spec.name}"`);
+        }
+        seen.add(result.spec.name);
+        specs.push(result.spec);
+    }
+    return specs;
+}
+/**
+ * The `method`/`auth` vocabularies of a `routes` declaration (spec
+ * §9.2) — Sets because `includes` on a `const` tuple narrows to the
+ * literal union, which an `unknown` field value can never satisfy.
+ */
+const ROUTE_METHODS = new Set([
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+]);
+const ROUTE_AUTHS = new Set(["user", "admin", "public"]);
+/**
+ * Validate a factory result's `routes` declaration (core hardening W5
+ * Task 2, spec §9.2). Absent → undefined (no routes). Present but
+ * malformed → throw; the loader quarantines the extension with the
+ * thrown message (fail-loud: an extension that THINKS it mounted a
+ * webhook must not silently lose it). Per entry: `method` in the five
+ * verbs, `path` a non-empty RELATIVE string (no leading `/`, no `..` —
+ * nothing may escape the `/v1/ext/<slug>/` mount), `auth` one of the
+ * three values, `bodyLimit` a positive integer when present, and
+ * `handler` a function.
+ */
+function validateRoutes(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("extension factory returned a routes field that is not an array");
+    }
+    for (const entry of value) {
+        const route = entry;
+        const describe = () => `route "${typeof route?.path === "string" ? route.path : String(route?.path)}"`;
+        if (typeof route?.method !== "string" || !ROUTE_METHODS.has(route.method)) {
+            throw new Error(`extension factory returned a ${describe()} whose method is not one of GET, POST, PUT, PATCH, DELETE`);
+        }
+        if (typeof route?.path !== "string" ||
+            route.path === "" ||
+            route.path.startsWith("/") ||
+            route.path.includes("..")) {
+            throw new Error(`extension factory returned a route whose path must be a non-empty relative string (no leading "/", no "..")`);
+        }
+        if (typeof route?.auth !== "string" || !ROUTE_AUTHS.has(route.auth)) {
+            throw new Error(`extension factory returned a ${describe()} whose auth is not one of user, admin, public`);
+        }
+        if (route?.bodyLimit !== undefined &&
+            (typeof route.bodyLimit !== "number" ||
+                !Number.isInteger(route.bodyLimit) ||
+                route.bodyLimit <= 0)) {
+            throw new Error(`extension factory returned a ${describe()} whose bodyLimit is not a positive integer`);
+        }
+        if (typeof route?.handler !== "function") {
+            throw new Error(`extension factory returned a ${describe()} whose handler is not a function`);
+        }
+    }
+    return value;
+}
+/**
+ * The extension command NAME grammar (spec §9.3): `^[a-z][a-z0-9-]*$` —
+ * the same shape as every other extension-declared name (workers,
+ * bundles), so the composer's `/` menu renders one spelling of a name.
+ */
+const COMMAND_NAME = /^[a-z][a-z0-9-]*$/;
+/**
+ * Validate a factory result's `commands` declaration (core hardening W5
+ * Task 3, spec §9.3). Absent → undefined (no commands). Present but
+ * malformed → throw; the loader quarantines the extension with the
+ * thrown message (fail-loud: an extension that THINKS it declared a
+ * command must not silently lose it — the providers/health class). Per
+ * entry: `name` matching the grammar, `description` a string, optional
+ * `args` a string, and `run` a function. Core-name collisions are NOT a
+ * validation failure — the catalog builder drops those with a warning
+ * (they are a deployment choice, not a broken declaration).
+ */
+function validateCommands(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("extension factory returned a commands field that is not an array");
+    }
+    for (const entry of value) {
+        const command = entry;
+        const describe = () => `command "${typeof command?.name === "string" ? command.name : String(command?.name)}"`;
+        if (typeof command?.name !== "string" || !COMMAND_NAME.test(command.name)) {
+            throw new Error(`extension factory returned a ${describe()} whose name does not match ^[a-z][a-z0-9-]*$`);
+        }
+        if (typeof command?.description !== "string") {
+            throw new Error(`extension factory returned a ${describe()} whose description is missing or not a string`);
+        }
+        if (command?.args !== undefined && typeof command.args !== "string") {
+            throw new Error(`extension factory returned a ${describe()} whose args is not a string`);
+        }
+        if (typeof command?.run !== "function") {
+            throw new Error(`extension factory returned a ${describe()} whose run is not a function`);
+        }
+    }
+    return value;
+}
+/**
+ * Validate a factory result's `notifiers` declaration (core hardening W5
+ * Task 6, spec §9.6). Absent → undefined (no contributions). Present but
+ * malformed → throw; the loader quarantines the extension with the thrown
+ * message (fail-loud: an extension that THINKS it declared a transport
+ * must not silently lose it — the providers/health class). Per entry: a
+ * non-empty `name` and a `notify` function.
+ */
+function validateNotifiers(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("extension factory returned a notifiers field that is not an array");
+    }
+    for (const entry of value) {
+        const notifier = entry;
+        const describe = () => `notifier "${typeof notifier?.name === "string" ? notifier.name : String(notifier?.name)}"`;
+        if (typeof notifier?.name !== "string" || notifier.name.length === 0) {
+            throw new Error(`extension factory returned a ${describe()} whose name is missing or empty`);
+        }
+        if (typeof notifier?.notify !== "function") {
+            throw new Error(`extension factory returned a ${describe()} whose notify is not a function`);
+        }
+    }
+    return value;
+}
+/**
+ * Validate a factory result's `skills` declaration (core hardening W5
+ * Task 4, spec §9.4). Absent → undefined (no contributions). Present but
+ * malformed → throw; the loader quarantines the extension with the thrown
+ * message (fail-loud: an extension that THINKS it contributed skills must
+ * not silently lose them — the providers/health class). Per entry: an
+ * absolute path naming an EXISTING directory.
+ */
+function validateSkills(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("extension factory returned a skills field that is not an array");
+    }
+    for (const entry of value) {
+        if (typeof entry !== "string" || entry.length === 0) {
+            throw new Error("extension factory returned a skills entry that is not a non-empty string");
+        }
+        if (!isAbsolute(entry)) {
+            throw new Error(`extension factory returned a skills entry that is not an absolute directory: ${entry}`);
+        }
+        if (!existingDirectory(entry)) {
+            throw new Error(`extension factory returned a skills entry that is not an existing directory: ${entry}`);
+        }
+    }
+    return value;
+}
+/**
+ * Validate a factory result's `providers` declaration (provider plugins
+ * Task 1). Absent → undefined (no contributions). Present but malformed →
+ * throw; the loader quarantines the extension with the thrown message
+ * (fail-loud: a plugin that THINKS it contributed a provider must not
+ * silently lose it). Each entry must be a `ProviderContribution` — an
+ * object whose `provider` carries a string `id`, the key the collector
+ * merges by and the §5 ownership records read.
+ */
+function validateProviders(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("extension factory returned a providers field that is not an array");
+    }
+    for (const entry of value) {
+        const provider = entry?.provider;
+        if (typeof provider !== "object" ||
+            provider === null ||
+            typeof provider.id !== "string") {
+            throw new Error("extension factory returned a providers entry whose provider.id is missing or not a string");
+        }
+    }
+    return value;
+}
+/**
+ * The contributed-bundle NAME grammar (spec §4.1: `^[a-z][a-z0-9_-]*$` —
+ * a selector value matching it is a contributed-bundle NAME). Kept in
+ * sync with `BUNDLE_NAME` in src/server/static.ts by the spec grammar,
+ * not a shared import: this module must not pull the server's runtime
+ * graph (the loader has no fs/server coupling by contract).
+ */
+const WEBUI_BUNDLE_NAME = /^[a-z][a-z0-9_-]*$/;
+/**
+ * Validate a factory result's `webuiBundles` declaration (build-and-webui
+ * Task 6). Absent → undefined (no contributions). Present but malformed →
+ * throw; the loader quarantines the extension with the thrown message
+ * (fail-loud: an extension that THINKS it contributed a bundle must not
+ * silently lose it — the providers/health/submit class). Each entry must
+ * be a `{name, dir}` object whose `name` matches the contributed-bundle
+ * grammar and whose `dir` is a non-empty string; extra fields are inert.
+ */
+function validateWebuiBundles(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw new Error("extension factory returned a webuiBundles field that is not an array");
+    }
+    for (const entry of value) {
+        const bundle = entry;
+        if (typeof bundle?.name !== "string" ||
+            !WEBUI_BUNDLE_NAME.test(bundle.name)) {
+            throw new Error("extension factory returned a webuiBundles entry whose name is missing or does not match ^[a-z][a-z0-9_-]*$");
+        }
+        if (typeof bundle?.dir !== "string" || bundle.dir.length === 0) {
+            throw new Error(`extension factory returned a webuiBundles entry "${bundle?.name}" whose dir is missing or not a non-empty string`);
+        }
+    }
+    return value;
+}
+/**
+ * The one host module whose version must match the host EXACTLY (spec
+ * §6.4 R6): an extension's `Extension`/tool objects flow into the HOST's
+ * pi-durable registry under structural typing — a different pi-durable
+ * is the classic silent-breakage trap (identity never matches, hooks
+ * never fire), so any difference at all quarantines. Every other host
+ * module only shares the major (a minor/patch difference warns).
+ */
+const EXACT_HOST_MODULES = new Set([
+    "@earendil-works/pi-durable",
+]);
+/** The major segment of a semver-ish version string (`"1.2.0"` → `"1"`). */
+function majorSegment(version) {
+    return version.split(".")[0] ?? version;
+}
+/**
+ * The nearest `package.json` at or above `dir` (bounded walk) — the
+ * manifest owning a resolved module ENTRY file. `undefined` at the walk
+ * bound or filesystem root.
+ */
+function nearestManifest(dir) {
+    let current = dir;
+    for (let hops = 0; hops < 6; hops++) {
+        const candidate = join(current, "package.json");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+    return undefined;
+}
+/**
+ * The nearest `node_modules/<name>/package.json` walking up from `dir` —
+ * the package-directory form of Node's own lookup (which copy of `<name>`
+ * a module at `dir` resolves). Bounded like every walk here; `undefined`
+ * when no ancestor tree carries the package.
+ */
+function nearestModuleManifest(dir, name) {
+    let current = dir;
+    for (let hops = 0; hops < 10; hops++) {
+        const candidate = join(current, "node_modules", ...name.split("/"), "package.json");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+    return undefined;
+}
+/**
+ * The version of one host runtime module as an extension's tree resolves
+ * it, anchored at the extension ENTRY's directory — the exact resolution
+ * the extension's own bare imports use (a nested `node_modules` copy
+ * counts, and so does the host's copy when the walk finds nothing
+ * nearer). `undefined` when the extension's tree resolves no copy at
+ * all: the extension does not depend on the module, and the guard
+ * skips it.
+ *
+ * Two resolution forms, in order: `<name>/package.json` (explicit, and
+ * the only form for manifest-less trees), falling back to the module
+ * ENTRY + nearest manifest above it — some host modules' exports maps
+ * (pi-ai, typebox) do not expose the `./package.json` subpath, which
+ * `require.resolve("<name>/package.json")"` reports as
+ * ERR_PACKAGE_PATH_NOT_EXPORTED even though the package itself resolves
+ * fine; without the fallback those modules would be invisible to the
+ * guard, the exact R6 blind spot it exists to close.
+ */
+function moduleVersionFrom(moduleDir, name) {
+    // Node's ESM loader realpaths the referrer before resolving ITS bare
+    // imports (preserveSymlinks is off by default) — anchor the walk at the
+    // realpath'd dir so the tree examined is the tree the extension's own
+    // imports resolve from, not the symlink path that named it (a `file:`
+    // dir install symlinks node_modules/<pkg> → the checkout).
+    let anchor = moduleDir;
+    try {
+        anchor = realpathSync(moduleDir);
+    }
+    catch {
+        // Not realpath-able — the literal dir is the best anchor available.
+    }
+    const req = createRequire(join(anchor, "package.json"));
+    let manifestPath;
+    try {
+        manifestPath = req.resolve(`${name}/package.json`);
+    }
+    catch {
+        // No package.json subpath from here — either the exports map gates
+        // it or the tree carries no copy: the fallbacks below decide.
+    }
+    if (manifestPath === undefined) {
+        try {
+            manifestPath = nearestManifest(dirname(req.resolve(name)));
+        }
+        catch {
+            // The entry itself is not require-resolvable — pi-ai's exports
+            // map carries ONLY `import`/`types` conditions, so createRequire
+            // cannot resolve the package AT ALL even though extensions
+            // import it fine. Fall back to the node_modules DIRECTORY walk
+            // (the package-dir form of Node's lookup); without it pi-ai skew
+            // would be invisible to the guard — the exact R6 blind spot.
+            manifestPath = nearestModuleManifest(anchor, name);
+        }
+    }
+    if (manifestPath === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+        return typeof parsed.version === "string" ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The host-module version guard (spec §6.4 R6, core-hardening Task 5):
+ * every host runtime module the extension's tree RESOLVES must agree
+ * with the copy the host runs — `@earendil-works/pi-durable` EXACTLY
+ * (else quarantine), the others in the major (a minor/patch difference
+ * warns, a major difference quarantines). Runs at LOAD, immediately
+ * after the import and before anything is keyed, collected, or
+ * installed: a skewing extension quarantines with this message and
+ * leaves no trace in the registry, the seam hosts, or any binding.
+ *
+ * @param moduleDir the extension ENTRY's directory (the tree its bare
+ * imports resolve from — `extensionModuleDir` above).
+ * @throws the quarantine message on a disallowed difference.
+ */
+function checkHostModules(moduleDir) {
+    for (const name of HOST_RUNTIME_MODULES) {
+        const extVersion = moduleVersionFrom(moduleDir, name);
+        if (extVersion === undefined)
+            continue; // not a dependency of this extension
+        const hostVersion = hostModuleVersion(name);
+        if (hostVersion === undefined)
+            continue; // no host copy to compare against
+        if (extVersion === hostVersion)
+            continue;
+        if (EXACT_HOST_MODULES.has(name) ||
+            majorSegment(extVersion) !== majorSegment(hostVersion)) {
+            throw new Error(`host module skew: ${name} resolves to ${extVersion} from ${moduleDir}, host runs ${hostVersion}`);
+        }
+        console.warn(`host module minor skew: ${name} resolves to ${extVersion} from ${moduleDir}, ` +
+            `host runs ${hostVersion} (same major, allowed)`);
+    }
+}
+/**
+ * The extension module's DIRECTORY — the anchor a contributed bundle's
+ * relative `dir` resolves against (build-and-webui Task 6: an
+ * npm-installed extension's bundle lives in its own package, so the dir
+ * anchors where the MODULE loaded from, never the process cwd). Path-shaped
+ * specifiers (file:// URLs, POSIX absolutes — the packages-dir and
+ * pre-resolved flows) derive directly; bare specifiers resolve through
+ * the loader's own require anchor (the same mechanism
+ * `resolveExtensionEntry`'s fallback uses). `undefined` when nothing
+ * path-shaped derives — a contributed `dir` then passes through unchanged
+ * (absolute dirs always do; `resolve` keeps them verbatim).
+ */
+function extensionModuleDir(loaded) {
+    let path;
+    if (loaded.startsWith("file://")) {
+        try {
+            path = fileURLToPath(loaded);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    else if (loaded.startsWith("/")) {
+        path = loaded;
+    }
+    else {
+        try {
+            const resolved = createRequire(import.meta.url).resolve(loaded);
+            path = resolved.startsWith("file://")
+                ? fileURLToPath(resolved)
+                : resolved;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return path === undefined ? undefined : dirname(path);
+}
+/**
+ * Call an unknown-typed factory and validate the `{ extension, health? }`
+ * result. A `health` field that is present but not the expected shape is a
+ * contract violation — thrown, so the loader quarantines the extension
+ * (fail-loud: a package that THINKS it reports health must not read as
+ * healthy). A `submit` field is IGNORED with a flag (§6.7: the
+ * pass-through is retired; the loader warns, never quarantines — old
+ * packages keep loading).
+ *
+ * The factory result may be a Promise (provider plugins read their scoped
+ * settings store inside the factory) — awaited before validation. A result
+ * carrying `providers` with NO `extension` is a valid provider-only
+ * contributor (named by its `name` field); a result with neither is not
+ * this contract form at all (returns undefined, falling through to the
+ * next resolution candidate).
+ */
+async function resolvedFromFactory(factory, hostContext) {
+    if (typeof factory !== "function")
+        return undefined;
+    // Arity gate: the host context goes ONLY to factories that declare the
+    // arity-1 signature (factory.length > 0). A length-0 factory with a
+    // defaulted first parameter (createMemory(backend = new Backend()))
+    // consumes its first argument as a real dependency — passing the host
+    // unconditionally landed it in that slot and broke the extension at
+    // runtime (memory: every submit 500ed on `bindRecallSource is not a
+    // function`). Extra arguments are inert only for factories that read
+    // none; `length` is how the contract declares it.
+    const result = factory.length > 0
+        ? factory(hostContext)
+        : factory();
+    // Provider plugins may resolve asynchronously; `await` passes a
+    // synchronous result through unchanged.
+    const awaited = await result;
+    if (typeof awaited !== "object" || awaited === null)
+        return undefined;
+    // The candidate is keyed by the PUBLIC contract (CandidateFactoryResult):
+    // reading a field the contract does not declare is a compile error here,
+    // and the `LoaderReadKeys` assertion (above ResolvedExtension) pins the
+    // full read list to the contract's keys.
+    const candidate = awaited;
+    const providers = validateProviders(candidate.providers);
+    const webuiBundles = validateWebuiBundles(candidate.webuiBundles);
+    const jobs = validateJobs(candidate.jobs);
+    const routes = validateRoutes(candidate.routes);
+    const commands = validateCommands(candidate.commands);
+    const skills = validateSkills(candidate.skills);
+    const notifiers = validateNotifiers(candidate.notifiers);
+    const extension = isExtension(candidate.extension)
+        ? candidate.extension
+        : undefined;
+    if (extension === undefined) {
+        // Contributor-only result: valid when ANY contribution field is
+        // present (`providers`, `webuiBundles`); otherwise this factory
+        // result is not the contract form (fall through to the next
+        // resolution candidate). The contributor's name is its
+        // collision-record identity — without one there is nothing to
+        // attribute the contributions to, which is a contract violation.
+        if (providers === undefined && webuiBundles === undefined) {
+            return undefined;
+        }
+        if (typeof candidate.name !== "string" || candidate.name.length === 0) {
+            throw new Error("extension factory returned a contributor-only result without a name");
+        }
+    }
+    if (candidate.health !== undefined &&
+        typeof candidate.health !== "function") {
+        throw new Error("extension factory returned a health field that is not a function");
+    }
+    if (candidate.runSettled !== undefined &&
+        typeof candidate.runSettled !== "function") {
+        throw new Error("extension factory returned a runSettled field that is not a function");
+    }
+    // The five lifecycle fields (memory-seam Task 4) validate identically:
+    // present-but-not-a-function is a contract violation — the extension
+    // THINKS it listens to lifecycle events and must not silently miss them.
+    const lifecycle = {};
+    let anyLifecycle = false;
+    for (const field of LIFECYCLE_FIELDS) {
+        const value = candidate[field];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "function") {
+            throw new Error(`extension factory returned a ${field} field that is not a function`);
+        }
+        lifecycle[field] = value;
+        anyLifecycle = true;
+    }
+    const kindsProblem = validateKinds(candidate.interactionKinds) ??
+        validateKinds(candidate.ambientKinds);
+    if (kindsProblem !== null)
+        throw new Error(kindsProblem);
+    // `workers` is a contract key — the candidate read needs no cast.
+    const workers = validateWorkers(candidate.workers);
+    return {
+        // Identity: the extension when one was carried, else the
+        // provider-only contributor's validated `name`.
+        ...(extension !== undefined
+            ? { extension }
+            : { name: candidate.name }),
+        ...(candidate.health === undefined
+            ? {}
+            : { health: candidate.health }),
+        ...(candidate.submit === undefined
+            ? {}
+            : { retiredSubmit: true }),
+        ...(candidate.runSettled === undefined
+            ? {}
+            : { runSettled: candidate.runSettled }),
+        ...(anyLifecycle
+            ? {
+                // SAFETY: every value under `lifecycle` passed `typeof === "function"`
+                // against its LIFECYCLE_FIELDS key above, so the object matches
+                // ExtensionLifecycleHandlers key-for-key and value-for-value.
+                lifecycle: lifecycle,
+            }
+            : {}),
+        ...(candidate.interactionKinds === undefined
+            ? {}
+            : { interactionKinds: candidate.interactionKinds }),
+        ...(candidate.ambientKinds === undefined
+            ? {}
+            : { ambientKinds: candidate.ambientKinds }),
+        ...(workers === undefined ? {} : { workers }),
+        ...(providers === undefined ? {} : { providers }),
+        ...(webuiBundles === undefined ? {} : { webuiBundles }),
+        ...(jobs === undefined ? {} : { jobs }),
+        ...(routes === undefined ? {} : { routes }),
+        ...(commands === undefined ? {} : { commands }),
+        ...(skills === undefined ? {} : { skills }),
+        ...(notifiers === undefined ? {} : { notifiers }),
+    };
+}
+/**
+ * Resolve one imported module to the extension the loader installs, per the
+ * contract order documented on this module, retaining a factory-result §3
+ * health producer when one was carried. Async: the factory result may be a
+ * Promise (settings-reading provider plugins).
+ */
+export async function resolveExtension(module, hostContext = undefined) {
+    // 1. Default export: factory returning `{ extension, health? }`, or the
+    //    Extension itself — the supported forms.
+    const defaultExport = module.default;
+    if (isExtension(defaultExport))
+        return { extension: defaultExport };
+    const fromDefault = await resolvedFromFactory(defaultExport, hostContext);
+    if (fromDefault !== undefined)
+        return fromDefault;
+    // 2. Named `extension` export (DEPRECATED bridge for the pre-contract
+    // packages — one warning per load at the caller). The pre-contract
+    // `createMemory` named-factory bridge was deleted in release-0.1; its
+    // last consumer exports the factory as default now.
+    if (isExtension(module.extension)) {
+        return { extension: module.extension, resolvedVia: "extension" };
+    }
+    return undefined;
+}
+/**
+ * The PROVISIONAL host identity for the pre-import factory call
+ * (provider plugins Task 9, review P1): the slug derived from the LOAD
+ * SPECIFIER — the package's own manifest name when the entry is
+ * path-shaped (packages-dir installs, git checkouts, dev checkouts:
+ * the nearest `package.json` at or above the entry, never read across
+ * a `node_modules` boundary — the packages root's own manifest is not
+ * an extension's identity), else the specifier's name part
+ * (`slugifyName` folds scoped names and `@version`s; an `npm:` install
+ * prefix is stripped). `""` when nothing survives (the pre-fix
+ * placeholder shape — an absent settings file reads as `{}` either
+ * way, but `""` never invents a wrong-but-plausible scope).
+ *
+ * Why a provisional at all: a factory that reads scoped settings
+ * DURING its body (sigrun-pareto's `baseUrl` override) runs BEFORE the
+ * declared name is known; with the `""` placeholder its read hit
+ * `settings/.json` and the override was silently inert. Pre-keying on
+ * the specifier-derived slug makes the factory-time read resolve the
+ * real package's file whenever the extension's declared name matches
+ * its package name — the documented requirement for provider plugins
+ * that read settings at factory time. A mismatching declared name
+ * still re-keys to the declared slug after resolution; only its
+ * factory-time settings reads saw the provisional scope.
+ */
+function provisionalSlugFor(loaded) {
+    let absolute;
+    if (loaded.startsWith("file://")) {
+        try {
+            absolute = fileURLToPath(loaded);
+        }
+        catch {
+            // Not a usable file URL — fall through to the specifier form.
+        }
+    }
+    else if (loaded.startsWith("/") ||
+        loaded.startsWith("./") ||
+        loaded.startsWith("../")) {
+        absolute = resolve(loaded);
+    }
+    if (absolute !== undefined) {
+        // Bounded walk from the entry itself (a directory entry carries
+        // its manifest at the top) up its ancestors.
+        let dir = absolute;
+        for (let hops = 0; hops < 6; hops++) {
+            if (basename(dir) === "node_modules")
+                return "";
+            const name = readPackageName(dir);
+            if (name !== undefined) {
+                const slug = slugifyName(name);
+                if (slug !== "")
+                    return slug;
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                return "";
+            dir = parent;
+        }
+        return "";
+    }
+    return slugifyName(loaded.replace(/^npm:/, ""));
+}
+/**
+ * Scan the installed registry snapshot for tool names registered by more
+ * than one extension, and `console.warn` each collision (Task 7, spec
+ * slice 4): pi-durable resolves tools by NAME (`resolveAgent` composes a
+ * name→tool map in install order, so the LAST registration wins and the
+ * earlier one is shadowed silently). The scan changes nothing — last-wins
+ * is pi-durable's behavior — it only makes the shadowing visible at boot,
+ * which is the surface a deployer needs to notice a co-installed
+ * replacement extension (the slice-4 replacement contract is "do not
+ * co-install", so any collision here is a configuration mistake).
+ */
+function warnToolNameCollisions(registry) {
+    const byName = new Map();
+    for (const { extension, tool } of registry.snapshot().tools()) {
+        const owners = byName.get(tool.name) ?? [];
+        owners.push({ extension: extension.name });
+        byName.set(tool.name, owners);
+    }
+    for (const [toolName, owners] of byName) {
+        if (owners.length < 2)
+            continue;
+        const names = owners.map((owner) => owner.extension).join(", ");
+        console.warn(`sigrun: duplicate tool name "${toolName}" registered by extensions ` +
+            `[${names}]; the last-listed registration wins (pi-durable resolves ` +
+            `tool names last-selected-wins) — do not co-install extensions ` +
+            `that register the same tool name`);
+    }
+}
+/**
+ * Load and install every configured extension, quarantining failures.
+ *
+ * @param specifiers package specifiers from `SIGRUN_EXTENSIONS` (npm names,
+ * absolute/relative paths, or `file://` URLs) — or the test seam's explicit
+ * list.
+ * @param registry the application-owned registry; install publishes at once,
+ * so extensions land before `Harness.open` reads the registry.
+ * @returns the outcome list (one entry per specifier, in order — never
+ * empty-entry gaps; boot stores this for `GET /v1/meta`, Task 9) plus the
+ * §3 health producers and submit pass-throughs retained from factory
+ * results, paired with their extensions for identity correlation (Task 9e,
+ * Task 26a).
+ */
+export async function loadExtensions(specifiers, registry, options = {}) {
+    // Normalize: the caller may hand pre-resolved entries (the boot flow,
+    // syncPackages consumer) or raw specifiers (the test seam, env-only
+    // deploys). Each becomes {entry, label, skills} — label drives the warning
+    // name exactly as specifiers did; an ABSENT entry with skills is the
+    // skills-only resolution (§9.4).
+    const entries = specifiers.map((spec) => typeof spec === "string"
+        ? { name: undefined, entry: spec, skills: undefined, builtin: undefined, coreResolved: undefined, packageDir: undefined }
+        : { name: spec.name, entry: spec.entry, skills: spec.skills, builtin: spec.builtin, coreResolved: spec.coreResolved, packageDir: spec.packageDir });
+    const outcomes = [];
+    const providerContributors = [];
+    const webuiBundles = [];
+    const healthProducers = [];
+    const runSettledBindings = [];
+    const lifecycleBindings = [];
+    const workerBindings = [];
+    // Jobs Task 3: declared jobs, attributed to the extension slug (the
+    // `ext:<slug>:<name>` id's namespace).
+    const jobBindings = [];
+    // HTTP routes (W5 Task 2), attributed to the slug like the job bindings.
+    const routeBindings = [];
+    // Slash commands (W5 Task 3), attributed the same way.
+    const commandBindings = [];
+    // Notifier transports (W5 Task 6, spec §9.6), attributed the same way —
+    // the server's notifications surface delivers to every collected entry.
+    const notifierBindings = [];
+    // Skill roots (W5 Task 4, spec §9.4): every skill dir a loaded package
+    // contributed — skills-only resolutions, entry-bearing packages' manifest
+    // skills, and factory-result `skills` fields — in load order, attributed
+    // to the extension slug. Boot threads this to the skills section's
+    // package-roots option.
+    const skillRoots = [];
+    // Slug → declared name, for collision rejection at load (this boot's
+    // loaded set only — quarantined extensions never claim a slug).
+    const slugs = new Map();
+    for (const { name: label, entry, skills, builtin, coreResolved, packageDir } of entries) {
+        const display = label ?? entry ?? "skills-only";
+        try {
+            // Skills-only resolution (§9.4): the package declared skill dirs and
+            // has NO loadable entry — nothing is imported. The outcome records
+            // `ok` under the slug of the package name; the dirs (validated as
+            // existing directories — the sync filtered, a violation here is a
+            // contract break) append to skillRoots. Inside the per-entry try so
+            // a bad declaration QUARANTINES instead of aborting the boot.
+            if (entry === undefined) {
+                if (skills === undefined || skills.length === 0) {
+                    throw new Error("a pre-resolved input carried neither an entry nor skill directories");
+                }
+                const skillsOnlyName = label ?? "skills-only";
+                const slug = slugifyName(skillsOnlyName);
+                if (slug === "") {
+                    throw new Error(`skills-only package name "${skillsOnlyName}" sanitizes to an empty slug (nothing survives [a-z0-9_-] folding); refusing to load`);
+                }
+                for (const dir of skills) {
+                    if (!existingDirectory(dir)) {
+                        throw new Error(`skills: contributed directory ${dir} does not exist (or is not a directory)`);
+                    }
+                }
+                // All-or-nothing (the quarantined-contributions invariant): the
+                // dirs append only once every one validated.
+                for (const dir of skills) {
+                    skillRoots.push({ extension: slug, dir });
+                }
+                outcomes.push({ name: slug, status: "ok" });
+                continue;
+            }
+            // Pre-resolved entries (the boot flow) import verbatim;
+            // raw specifiers (the test seam) resolve through the
+            // packages dir first, then bare import resolution.
+            const loaded = coreResolved === true
+                ? entry
+                : label !== undefined
+                    ? entry
+                    : (options.packagesDir === undefined
+                        ? entry
+                        : (resolveExtensionEntry(entry, options.packagesDir) ?? entry));
+            // Resolution order (the packages-dir ruling): the deployment's
+            // packages dir FIRST (what `packages[]` installed wins over
+            // anything the image bundles), then bare import resolution
+            // (paths, file:// URLs, dev checkouts, app-tree packages). The
+            // packages dir is an unrelated node_modules tree — Node's
+            // upward walk never finds it from sigrun's own imports, so it
+            // must be consulted explicitly.
+            // A resolved entry ending in `.ts` is rejected BEFORE the import
+            // (build-and-webui Task 3, BREAKING): the built server ships no
+            // loader — a `.ts` entry is a from-source artifact whose behavior
+            // depends on the host node's type-stripping flags (newer node
+            // loads it, older node crashes with ERR_UNKNOWN_FILE_EXTENSION).
+            // Sources must ship a BUILT entry; the quarantine names it.
+            if (/\.ts$/.test(loaded)) {
+                throw new Error(`the resolved entry is a TypeScript source (${loaded}) — build the package and ship its built entry (dist/index.js); the built server loads JavaScript`);
+            }
+            const module = (await import(loaded));
+            // Host-module version guard (spec §6.4 R6): the module tree the
+            // extension's bare imports resolve from must agree with the copy
+            // the host runs — checked immediately after the import, BEFORE any
+            // host keying or contract resolution, so a skewing extension leaves
+            // no trace (no seam host, no bindings, no registry entry). A throw
+            // here rides the existing per-extension try (quarantine, boot
+            // continues) exactly like the reserved-section check below.
+            const moduleDir = extensionModuleDir(loaded);
+            if (moduleDir !== undefined)
+                checkHostModules(moduleDir);
+            // Two-phase host: the factory receives the host at CALL time, but
+            // the extension name and kinds it declares are only known from its
+            // RESULT. The loader therefore invokes the host factory TWICE with
+            // the SAME instance: once PRE-import with the PROVISIONAL identity
+            // (the slug derived from the load specifier — `provisionalSlugFor`;
+            // "" when nothing derives) so a factory that reads scoped settings
+            // during its body resolves the real package's store (provider
+            // plugins Task 9 P1 — the pre-fix "" placeholder made sigrun-pareto's
+            // `baseUrl` override silently inert), and once post-resolution with
+            // the declared name + kinds PLUS the captured instance — boot's
+            // factory re-keys that SAME host object IN PLACE (SeamHost.rekey),
+            // so the instance the factory captured becomes the final host and
+            // its write gate sees the declared kinds from then on. The
+            // provisional normally EQUALS the resolved slug (extension name ==
+            // package name); when it differs the re-key still corrects the
+            // scope — only factory-time settings reads of such an extension
+            // saw the provisional scope (documented: read scoped settings at
+            // factory time only when the plugin name matches its package name).
+            let host;
+            if (options.hostContextFactory !== undefined) {
+                host = options.hostContextFactory(provisionalSlugFor(loaded), {});
+            }
+            const resolved = await resolveExtension(module, host);
+            if (resolved === undefined) {
+                throw new Error(`does not satisfy the sigrun extension-package contract ` +
+                    `(expected a default-export factory returning { extension })`);
+            }
+            // Task 3 — the slug IS the extension identity from here down: ONE
+            // sanitization point, computed from the DECLARED name at load and
+            // applied before the seam host is re-keyed and before the registry
+            // install — every downstream surface (registry key, seam-host
+            // identity, interaction/ambient records, worker names, health
+            // correlation) sees the slug, never the declared name. Rejections
+            // ride the LOAD (Review Focus 2): an empty slug or a collision
+            // quarantines HERE naming the declared name(s), never the first
+            // store use mid-run.
+            const declared = resolved.extension !== undefined
+                ? resolved.extension.name
+                : resolved.name;
+            if (declared === undefined) {
+                // Unreachable by construction (provider-only results validate
+                // `name`; every other form carries an `extension`) — but the
+                // identity rule fails loud rather than slugifying `undefined`.
+                throw new Error("factory result carried neither an extension nor a contributor name");
+            }
+            const slug = slugifyName(declared);
+            if (slug === "") {
+                throw new Error(`extension name "${declared}" sanitizes to an empty slug ` +
+                    "(nothing survives [a-z0-9_-] folding); refusing to load");
+            }
+            const collides = slugs.get(slug);
+            if (collides !== undefined) {
+                throw new Error(`slug collision: extension "${declared}" sanitizes to ` +
+                    `"${slug}", already claimed by "${collides}" — extension ` +
+                    "identities must be unique after sanitization");
+            }
+            // Rename at the ONE point: a shallow copy with the slug as `name`
+            // (the Extension contract is readonly; the declared object is
+            // never mutated). Every binding below pairs with THIS object so
+            // boot's identity correlation (health/submit/memory-owner
+            // matching) stays exact.
+            const extension = resolved.extension === undefined
+                ? undefined
+                : { ...resolved.extension, name: slug };
+            // Reserved core section keys (spec §6.5 R11): a section under one
+            // of them is a LOAD-TIME quarantine, checked HERE — after the slug
+            // is final and BEFORE anything is collected. The registry would
+            // otherwise accept the duplicate (sections are last-writer-wins
+            // across extensions), silently replacing a core surface; the
+            // existing catch quarantines with this message instead, leaving
+            // nothing installed (no registry entry), no post-resolution host
+            // re-key (boot's seamHosts never files the entry), and no
+            // provider/health/submit/runSettled/lifecycle/worker/webui
+            // binding collected. Boot's post-install walk over
+            // RESERVED_CORE_SECTION_OWNERS stays as a core-only assertion.
+            const reservedSectionKey = extension?.sections?.find((section) => RESERVED_SECTION_KEY_SET.has(section.key))?.key;
+            if (reservedSectionKey !== undefined) {
+                throw new Error(`extension "${slug}" declares reserved core section "${reservedSectionKey}"`);
+            }
+            // Skill contributions (W5 Task 4), validated HERE — before the
+            // install/outcome, so a bad declaration quarantines with nothing
+            // installed and exactly one outcome (the same point as every
+            // other fail-loud contract check). The factory-result dirs were
+            // already validated at read time (validateSkills, all-or-nothing);
+            // the MANIFEST dirs (the sync's resolution, existing by
+            // construction) are re-checked because a hand-built pre-resolved
+            // input skips the sync.
+            const contributed = [...(resolved.skills ?? []), ...(skills ?? [])];
+            for (const dir of contributed) {
+                if (!existingDirectory(dir)) {
+                    throw new Error(`skills: contributed directory ${dir} does not exist (or is not a directory)`);
+                }
+            }
+            // The post-resolution call re-keys the captured host instance in
+            // place with the slug + declared kinds (boot's
+            // hostContextFactory; see src/harness/boot.ts) — the instance is
+            // handed back explicitly as `priorHost`, so even a provisional ≠
+            // resolved mismatch re-keys the SAME instance. No second host is
+            // ever created — a rebuilt instance would orphan every inbound
+            // handler the factory registered on the host it captured.
+            if (options.hostContextFactory !== undefined) {
+                const kinds = {
+                    ...(resolved.interactionKinds === undefined
+                        ? {}
+                        : { interaction: resolved.interactionKinds }),
+                    ...(resolved.ambientKinds === undefined
+                        ? {}
+                        : { ambient: resolved.ambientKinds }),
+                };
+                options.hostContextFactory(slug, kinds, host);
+            }
+            if (extension !== undefined) {
+                registry.install(extension);
+            }
+            // Only a LOADED extension or contributor claims its slug — a
+            // later stage's quarantine (never loaded) leaves the slug free
+            // for the next boot's specifier list.
+            slugs.set(slug, declared);
+            // The manifest version for the §7.7 inventory: read off the
+            // module's own directory (a bare entry with no manifest stays
+            // versionless — the field is optional by design).
+            const versionDir = packageDir ?? extensionModuleDir(loaded);
+            const version = versionDir === undefined ? undefined : readPackageVersion(versionDir);
+            outcomes.push({
+                name: slug,
+                status: "ok",
+                ...(version === undefined ? {} : { version }),
+                ...(builtin === true ? { builtin: true } : {}),
+            });
+            if (extension !== undefined && resolved.health !== undefined) {
+                healthProducers.push({
+                    extension,
+                    health: resolved.health,
+                });
+            }
+            // §6.7 retirements, warned ONCE at load (never quarantined): a
+            // result resolved through the named-export bridge, and a result still
+            // carrying the retired submit pass-through. Both keep loading —
+            // the pre-contract `createMemory` named-factory bridge was deleted
+            // in release-0.1 (its last consumer exports default now), and the
+            // submit is simply ignored (the memory seam owns capture now).
+            if (resolved.resolvedVia !== undefined) {
+                console.warn(`extension ${display}: named-export factory "${resolved.resolvedVia}" is deprecated — export it as default`);
+            }
+            if (resolved.retiredSubmit === true) {
+                console.warn(`extension "${slug}": the submit pass-through was retired; ignoring`);
+            }
+            if (extension !== undefined && resolved.runSettled !== undefined) {
+                runSettledBindings.push({
+                    extension,
+                    runSettled: resolved.runSettled,
+                });
+            }
+            if (extension !== undefined && resolved.lifecycle !== undefined) {
+                lifecycleBindings.push({
+                    extension,
+                    handlers: resolved.lifecycle,
+                });
+            }
+            if (extension !== undefined && resolved.workers !== undefined) {
+                workerBindings.push({
+                    extension,
+                    workers: resolved.workers,
+                });
+            }
+            if (resolved.jobs !== undefined) {
+                jobBindings.push({ extension: slug, jobs: resolved.jobs });
+            }
+            if (resolved.routes !== undefined) {
+                routeBindings.push({ extension: slug, routes: resolved.routes });
+            }
+            if (resolved.commands !== undefined) {
+                commandBindings.push({ extension: slug, commands: resolved.commands });
+            }
+            if (resolved.notifiers !== undefined) {
+                notifierBindings.push({ extension: slug, notifiers: resolved.notifiers });
+            }
+            if (resolved.providers !== undefined) {
+                providerContributors.push({
+                    name: slug,
+                    providers: resolved.providers,
+                    ...(resolved.health === undefined
+                        ? {}
+                        : { health: resolved.health }),
+                });
+            }
+            // Webui-bundle contributions (build-and-webui Task 6): each entry
+            // is attributed to the extension slug and its `dir` anchored at
+            // the MODULE's directory — resolved HERE, the one point the module
+            // URL is known (an npm-installed extension's bundle lives in its
+            // own package, never the server cwd). Absolute dirs pass through
+            // `resolve` verbatim; the server owns the index.html check at
+            // serve time (the loader has no fs coupling by contract).
+            if (resolved.webuiBundles !== undefined) {
+                const moduleDir = extensionModuleDir(loaded);
+                for (const entry of resolved.webuiBundles) {
+                    webuiBundles.push({
+                        name: entry.name,
+                        dir: moduleDir === undefined || isAbsolute(entry.dir)
+                            ? entry.dir
+                            : resolve(moduleDir, entry.dir),
+                        extension: slug,
+                    });
+                }
+            }
+            // Skill contributions (W5 Task 4): the validated combined list
+            // (factory-result + manifest dirs — validated above, before the
+            // install), attributed to the extension slug, in load order.
+            for (const dir of contributed) {
+                skillRoots.push({ extension: slug, dir });
+            }
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            console.warn(`extension quarantined: ${display} failed to load: ${message}`);
+            outcomes.push({
+                name: display,
+                status: "quarantined",
+                error: message,
+                ...(builtin === true ? { builtin: true } : {}),
+            });
+            // A quarantined extension contributes no health producer or submit
+            // binding: the §3 surfaces are reported through
+            // `extensions[].status`, never double-reported.
+        }
+    }
+    // After all installs: surface tool-name collisions across extensions
+    // (last-wins is pi-durable's resolution — unchanged, only warned).
+    warnToolNameCollisions(registry);
+    return {
+        outcomes,
+        providerContributors,
+        webuiBundles,
+        skillRoots,
+        healthProducers,
+        runSettledBindings,
+        lifecycleBindings,
+        workerBindings,
+        jobBindings,
+        routeBindings,
+        commandBindings,
+        notifierBindings,
+    };
+}