@ixo/oracle-runtime 0.0.1

package/dist/bootstrap/inspect.d.ts

@@ -0,0 +1,74 @@
+import type { OracleIdentity } from '../plugin-api/types.js';
+import type { RegisteredConfigSchema, RegisteredManifest, RegisteredMiddleware, RegisteredSharedAccessor, RegisteredSubAgent, RegisteredTool } from '../registries/index.js';
+import type { ResolvePluginsResult } from './plugin-loader.js';
+/**
+ * Already-collected registry entries. The runtime calls each registry's
+ * `collect()` once at boot; `inspect()` consumes the cached lists rather
+ * than re-collecting (collection is async / context-bound).
+ */
+export interface CollectedRegistries {
+    tools: RegisteredTool[];
+    subAgents: RegisteredSubAgent[];
+    middlewares: RegisteredMiddleware[];
+    manifests: RegisteredManifest[];
+    configSchemas: RegisteredConfigSchema[];
+    sharedState: RegisteredSharedAccessor[];
+}
+export interface InspectInput {
+    resolved: ResolvePluginsResult;
+    collected: CollectedRegistries;
+    identity: OracleIdentity;
+    runtimeVersion: string;
+    /**
+     * Names of plugins shipped from the runtime package itself. Anything in
+     * `resolved.loaded` not present here is reported as `source: 'user'`.
+     * When omitted, every loaded plugin is treated as `'bundled'`.
+     */
+    bundledPluginNames?: ReadonlySet<string>;
+    /**
+     * Optional collision/warning lines to surface (e.g. config-schema
+     * later-wins warnings). Forwarded verbatim under `warnings`.
+     */
+    warnings?: string[];
+}
+export interface InspectPluginEntry {
+    name: string;
+    version: string;
+    source: 'bundled' | 'user';
+    dependsOn: string[];
+    softDependsOn: string[];
+    softDepsResolved: string[];
+    softDepsMissing: string[];
+    tools: {
+        name: string;
+        visibility?: string;
+    }[];
+    subAgents: {
+        name: string;
+    }[];
+    stateFields: string[];
+    configFields: string[];
+}
+export interface InspectOutput {
+    schema: 'qiforge.boot.v1';
+    runtime: {
+        version: string;
+        node: string;
+    };
+    identity: OracleIdentity;
+    plugins: InspectPluginEntry[];
+    topo: string[];
+    excluded: {
+        plugin: string;
+        reason: string;
+    }[];
+    collisions: string[];
+    warnings: string[];
+}
+/**
+ * Build the diagnostic JSON dump for `qiforge inspect` and the
+ * `/health/plugins` endpoint. Tier-1 prompt + token estimate are deferred
+ * to a later phase and intentionally omitted.
+ */
+export declare function inspect(input: InspectInput): InspectOutput;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/bootstrap/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../../src/bootstrap/inspect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EACV,sBAAsB,EACtB,kBAAkB,EAClB,oBAAoB,EACpB,wBAAwB,EACxB,kBAAkB,EAClB,cAAc,EACf,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,aAAa,EAAE,sBAAsB,EAAE,CAAC;IACxC,WAAW,EAAE,wBAAwB,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,SAAS,EAAE,mBAAmB,CAAC;IAC/B,QAAQ,EAAE,cAAc,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC/C,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC/C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,CAiD1D"}

package/dist/bootstrap/inspect.js

@@ -0,0 +1,111 @@
+/**
+ * Build the diagnostic JSON dump for `qiforge inspect` and the
+ * `/health/plugins` endpoint. Tier-1 prompt + token estimate are deferred
+ * to a later phase and intentionally omitted.
+ */
+export function inspect(input) {
+    const { resolved, collected, identity, runtimeVersion, bundledPluginNames, warnings = [], } = input;
+    const finalNames = new Set(resolved.loaded.map((p) => p.name));
+    const toolsByPlugin = groupBy(collected.tools, (e) => e.pluginName);
+    const subAgentsByPlugin = groupBy(collected.subAgents, (e) => e.pluginName);
+    const stateByPlugin = groupBy(collected.sharedState, (e) => e.pluginName);
+    const configByPlugin = groupBy(collected.configSchemas.flatMap((entry) => Object.keys(entry.schema.shape).map((key) => ({
+        pluginName: entry.pluginName,
+        key,
+    }))), (e) => e.pluginName);
+    const plugins = resolved.loaded.map((plugin) => buildPluginEntry({
+        plugin,
+        finalNames,
+        bundledPluginNames,
+        tools: toolsByPlugin.get(plugin.name) ?? [],
+        subAgents: subAgentsByPlugin.get(plugin.name) ?? [],
+        stateEntries: stateByPlugin.get(plugin.name) ?? [],
+        configEntries: configByPlugin.get(plugin.name) ?? [],
+    }));
+    const collisions = detectCollisions(plugins);
+    return {
+        schema: 'qiforge.boot.v1',
+        runtime: { version: runtimeVersion, node: process.version },
+        identity,
+        plugins,
+        topo: resolved.loaded.map((p) => p.name),
+        excluded: resolved.excluded,
+        collisions,
+        warnings,
+    };
+}
+function buildPluginEntry(args) {
+    const { plugin, finalNames, bundledPluginNames, tools, subAgents, stateEntries, configEntries, } = args;
+    const softDependsOn = plugin.softDependsOn ?? [];
+    const softDepsResolved = softDependsOn.filter((d) => finalNames.has(d));
+    const softDepsMissing = softDependsOn.filter((d) => !finalNames.has(d));
+    const source = bundledPluginNames === undefined || bundledPluginNames.has(plugin.name)
+        ? 'bundled'
+        : 'user';
+    return {
+        name: plugin.name,
+        version: plugin.version,
+        source,
+        dependsOn: [...(plugin.dependsOn ?? [])],
+        softDependsOn: [...softDependsOn],
+        softDepsResolved,
+        softDepsMissing,
+        tools: tools.map((t) => ({
+            name: t.tool.name,
+            visibility: t.tool.visibility,
+        })),
+        subAgents: subAgents.map((s) => ({ name: s.subAgent.name })),
+        stateFields: stateEntries.map((e) => e.key),
+        configFields: configEntries.map((e) => e.key),
+    };
+}
+function detectCollisions(plugins) {
+    const collisions = [];
+    const toolOwners = new Map();
+    const subAgentOwners = new Map();
+    const stateOwners = new Map();
+    for (const p of plugins) {
+        for (const t of p.tools) {
+            const prev = toolOwners.get(t.name);
+            if (prev !== undefined && prev !== p.name) {
+                collisions.push(`tool '${t.name}' registered by both '${prev}' and '${p.name}'`);
+            }
+            else {
+                toolOwners.set(t.name, p.name);
+            }
+        }
+        for (const s of p.subAgents) {
+            const prev = subAgentOwners.get(s.name);
+            if (prev !== undefined && prev !== p.name) {
+                collisions.push(`sub-agent '${s.name}' registered by both '${prev}' and '${p.name}'`);
+            }
+            else {
+                subAgentOwners.set(s.name, p.name);
+            }
+        }
+        for (const f of p.stateFields) {
+            const prev = stateOwners.get(f);
+            if (prev !== undefined && prev !== p.name) {
+                collisions.push(`shared-state key '${f}' registered by both '${prev}' and '${p.name}'`);
+            }
+            else {
+                stateOwners.set(f, p.name);
+            }
+        }
+    }
+    return collisions;
+}
+function groupBy(items, key) {
+    const out = new Map();
+    for (const item of items) {
+        const k = key(item);
+        const bucket = out.get(k);
+        if (bucket) {
+            bucket.push(item);
+        }
+        else {
+            out.set(k, [item]);
+        }
+    }
+    return out;
+}

package/dist/bootstrap/plugin-loader.d.ts

@@ -0,0 +1,50 @@
+import type { OraclePlugin } from '../plugin-api/oracle-plugin.js';
+import type { Logger } from '../plugin-api/types.js';
+/**
+ * Per-feature toggle:
+ *  - `true`   — explicit opt-in. If the plugin has an `autoDetect` and it
+ *               fails, boot fails.
+ *  - `false`  — explicit opt-out.
+ *  - `'auto'` — include only if the plugin's `autoDetect` returns true (or
+ *               the plugin has no `autoDetect`, in which case it loads).
+ */
+export type FeatureToggle = boolean | 'auto';
+export type ExclusionCause = 'feature_false' | 'auto_detect_missing' | 'cascaded';
+export interface ExcludedPlugin {
+    plugin: string;
+    reason: string;
+    cause: ExclusionCause;
+}
+export interface SoftDepGap {
+    plugin: string;
+    missing: string;
+}
+export interface ResolvePluginsInput {
+    features?: Partial<Record<string, FeatureToggle>>;
+    bundled: OraclePlugin[];
+    userPlugins?: OraclePlugin[];
+    env?: NodeJS.ProcessEnv;
+    logger?: Logger;
+}
+export interface ResolvePluginsResult {
+    loaded: OraclePlugin[];
+    excluded: ExcludedPlugin[];
+    softDepGaps: SoftDepGap[];
+}
+/**
+ * Resolve the final plugin list for boot.
+ *
+ *   1. Apply feature toggles + each plugin's `autoDetect` to the bundled list.
+ *   2. Combine with always-loaded user plugins.
+ *   3. Cascade hard-dep removals (transitive — fixed-point).
+ *   4. Topologically sort by `dependsOn`.
+ *   5. Log soft-dep gaps.
+ */
+export declare function resolvePlugins(input: ResolvePluginsInput): ResolvePluginsResult;
+/**
+ * Topologically sort plugins by `dependsOn`. Throws on unmet hard deps
+ * (`boot.plugin.dep_missing`) or cycles (`boot.plugin.cycle`, with the
+ * cycle path included in the message).
+ */
+export declare function topoSort(plugins: OraclePlugin[]): OraclePlugin[];
+//# sourceMappingURL=plugin-loader.d.ts.map

package/dist/bootstrap/plugin-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-loader.d.ts","sourceRoot":"","sources":["../../src/bootstrap/plugin-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7C,MAAM,MAAM,cAAc,GACtB,eAAe,GACf,qBAAqB,GACrB,UAAU,CAAC;AAEf,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,cAAc,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IAClD,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,YAAY,EAAE,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAQD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,mBAAmB,GACzB,oBAAoB,CAqFtB;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAsChE"}

package/dist/bootstrap/plugin-loader.js

@@ -0,0 +1,119 @@
+const NOOP_LOGGER = {
+    log: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+/**
+ * Resolve the final plugin list for boot.
+ *
+ *   1. Apply feature toggles + each plugin's `autoDetect` to the bundled list.
+ *   2. Combine with always-loaded user plugins.
+ *   3. Cascade hard-dep removals (transitive — fixed-point).
+ *   4. Topologically sort by `dependsOn`.
+ *   5. Log soft-dep gaps.
+ */
+export function resolvePlugins(input) {
+    const env = input.env ?? process.env;
+    const logger = input.logger ?? NOOP_LOGGER;
+    const features = input.features ?? {};
+    const excluded = [];
+    const survivors = [];
+    for (const plugin of input.bundled) {
+        const toggle = features[plugin.name];
+        if (toggle === false) {
+            excluded.push({
+                plugin: plugin.name,
+                reason: 'feature flag set to false',
+                cause: 'feature_false',
+            });
+            continue;
+        }
+        const detectOk = plugin.autoDetect ? plugin.autoDetect(env) : true;
+        const hint = plugin.autoDetectHint ?? 'auto-detect predicate';
+        if (toggle === true && !detectOk) {
+            throw new Error(`boot.plugin.env_missing: plugin '${plugin.name}' enabled via features but precondition failed (${hint}). ` +
+                `Set the required env or disable: features: { ${plugin.name}: false }`);
+        }
+        if (!detectOk) {
+            excluded.push({
+                plugin: plugin.name,
+                reason: `auto-detect precondition not met (${hint})`,
+                cause: 'auto_detect_missing',
+            });
+            continue;
+        }
+        survivors.push(plugin);
+    }
+    const allLoaded = [...survivors, ...(input.userPlugins ?? [])];
+    // Transitive cascade — fixed-point. A plugin cascades off if any of its
+    // hard deps is excluded for any reason (explicit false, auto-detect, or
+    // a previous cascade).
+    const kept = new Map(allLoaded.map((p) => [p.name, p]));
+    const excludedNames = new Set(excluded.map((e) => e.plugin));
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const plugin of [...kept.values()]) {
+            for (const dep of plugin.dependsOn ?? []) {
+                if (kept.has(dep))
+                    continue;
+                if (!excludedNames.has(dep))
+                    continue;
+                const reason = `cascaded off via ${dep}`;
+                excluded.push({ plugin: plugin.name, reason, cause: 'cascaded' });
+                excludedNames.add(plugin.name);
+                kept.delete(plugin.name);
+                logger.warn(`[boot] plugin '${plugin.name}' ${reason} (event: boot.plugin.cascaded_off)`);
+                changed = true;
+                break;
+            }
+        }
+    }
+    const ordered = topoSort([...kept.values()]);
+    const finalNames = new Set(ordered.map((p) => p.name));
+    const softDepGaps = [];
+    for (const plugin of ordered) {
+        for (const soft of plugin.softDependsOn ?? []) {
+            if (finalNames.has(soft))
+                continue;
+            softDepGaps.push({ plugin: plugin.name, missing: soft });
+            logger.log(`[boot] plugin '${plugin.name}' soft-depends on '${soft}', which is not loaded (event: boot.plugin.soft_dep_missing)`);
+        }
+    }
+    return { loaded: ordered, excluded, softDepGaps };
+}
+/**
+ * Topologically sort plugins by `dependsOn`. Throws on unmet hard deps
+ * (`boot.plugin.dep_missing`) or cycles (`boot.plugin.cycle`, with the
+ * cycle path included in the message).
+ */
+export function topoSort(plugins) {
+    const byName = new Map(plugins.map((p) => [p.name, p]));
+    const visited = new Set();
+    const visiting = new Set();
+    const ordered = [];
+    const visit = (name, requiredBy, path) => {
+        if (visited.has(name))
+            return;
+        if (visiting.has(name)) {
+            const cycle = [...path.slice(path.indexOf(name)), name].join(' -> ');
+            throw new Error(`boot.plugin.cycle: dependency cycle detected: ${cycle}. ` +
+                `Break the cycle by removing one of the dependsOn links.`);
+        }
+        const plugin = byName.get(name);
+        if (!plugin) {
+            throw new Error(`boot.plugin.dep_missing: plugin '${requiredBy}' requires '${name}', which is not loaded. ` +
+                `Add '${name}' to features, or remove '${requiredBy}'.`);
+        }
+        visiting.add(name);
+        for (const dep of plugin.dependsOn ?? []) {
+            visit(dep, name, [...path, name]);
+        }
+        visiting.delete(name);
+        visited.add(name);
+        ordered.push(plugin);
+    };
+    for (const p of plugins)
+        visit(p.name, null, []);
+    return ordered;
+}

package/dist/bootstrap/runtime-app-module.d.ts

@@ -0,0 +1,38 @@
+import { type DynamicModule, type MiddlewareConsumer, type NestModule, type Type } from '@nestjs/common';
+import type { AuthExcludedRoute } from '../plugin-api/types.js';
+export interface RuntimeAppModuleOptions {
+    /** Pre-validated env values, fed straight into `ConfigModule`. */
+    validatedEnv: Record<string, unknown>;
+    /** Additional modules supplied by the fork at `createOracleApp`. */
+    userNestModules?: Array<Type | DynamicModule>;
+    /** Plugin-shipped NestJS modules collected from bundled plugins. */
+    pluginNestModules?: Array<Type | DynamicModule>;
+    /**
+     * Plugin-declared routes that must be excluded from `AuthHeaderMiddleware`.
+     * Aggregated from each loaded plugin's `getAuthExcludedRoutes()` and
+     * concatenated onto the runtime's own exclusion list (`/`, `/health`,
+     * `/docs`, `/docs/(.*)`).
+     */
+    pluginAuthExclusions?: AuthExcludedRoute[];
+    /**
+     * Whether to wire `SubscriptionMiddleware` ahead of the routes. The credits
+     * plugin owns that decision — when credits is disabled, only auth runs.
+     */
+    enableSubscriptionMiddleware: boolean;
+}
+/**
+ * The runtime's root NestJS module. Built dynamically per oracle so the
+ * fork-supplied `nestModules` and plugin-shipped modules can be folded
+ * into a single import list alongside the Tier-0 modules.
+ *
+ * `ConfigModule` is registered globally with the merged schema's parsed
+ * output — the schema itself ran in the boot composer so any failure
+ * already surfaced before this module loads.
+ */
+export declare class RuntimeAppModule implements NestModule {
+    private static enableSubscription;
+    private static authExcludedRoutes;
+    static register(opts: RuntimeAppModuleOptions): DynamicModule;
+    configure(consumer: MiddlewareConsumer): void;
+}
+//# sourceMappingURL=runtime-app-module.d.ts.map

package/dist/bootstrap/runtime-app-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-app-module.d.ts","sourceRoot":"","sources":["../../src/bootstrap/runtime-app-module.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,aAAa,EAElB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EAEf,KAAK,IAAI,EACV,MAAM,gBAAgB,CAAC;AAKxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAahE,MAAM,WAAW,uBAAuB;IACtC,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,oEAAoE;IACpE,eAAe,CAAC,EAAE,KAAK,CAAC,IAAI,GAAG,aAAa,CAAC,CAAC;IAC9C,oEAAoE;IACpE,iBAAiB,CAAC,EAAE,KAAK,CAAC,IAAI,GAAG,aAAa,CAAC,CAAC;IAChD;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC3C;;;OAGG;IACH,4BAA4B,EAAE,OAAO,CAAC;CACvC;AAyBD;;;;;;;;GAQG;AACH,qBACa,gBAAiB,YAAW,UAAU;IACjD,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAS;IAE1C,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAG0B;IAE3D,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,GAAG,aAAa;IA4C7D,SAAS,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;CAc9C"}

package/dist/bootstrap/runtime-app-module.js

@@ -0,0 +1,114 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var RuntimeAppModule_1;
+import { CacheModule } from '@nestjs/cache-manager';
+import { Module, RequestMethod, } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { APP_GUARD } from '@nestjs/core';
+import { ScheduleModule } from '@nestjs/schedule';
+import { ThrottlerGuard } from '@nestjs/throttler';
+import { AuthHeaderMiddleware } from '../modules/auth/auth-header.middleware.js';
+import { AuthModule } from '../modules/auth/auth.module.js';
+import { BlobStoreModule } from '../modules/blob-store/blob-store.module.js';
+import { HealthModule } from '../modules/health/health.module.js';
+import { MessagesModule } from '../modules/messages/messages.module.js';
+import { SessionsModule } from '../modules/sessions/sessions.module.js';
+import { SubscriptionMiddleware } from '../modules/subscription/subscription.middleware.js';
+import { SubscriptionModule } from '../modules/subscription/subscription.module.js';
+import { ThrottlerModule } from '../modules/throttler/throttler.module.js';
+import { UcanModule } from '../modules/ucan/ucan.module.js';
+import { WsModule } from '../modules/ws/ws.module.js';
+const AUTH_EXCLUDED_ROUTES = [
+    { path: '/', method: RequestMethod.ALL },
+    { path: '/health', method: RequestMethod.ALL },
+    { path: '/docs', method: RequestMethod.ALL },
+    { path: '/docs/(.*)', method: RequestMethod.ALL },
+];
+/**
+ * Normalize a plugin-declared route into the shape NestJS's
+ * `MiddlewareConsumer.exclude(...)` expects:
+ *  - default `method` to `RequestMethod.ALL`
+ *  - leave the leading-slash decision to the plugin author — Nest matches both
+ */
+function normalizeAuthExclusion(route) {
+    return {
+        path: route.path,
+        method: route.method ?? RequestMethod.ALL,
+    };
+}
+/**
+ * The runtime's root NestJS module. Built dynamically per oracle so the
+ * fork-supplied `nestModules` and plugin-shipped modules can be folded
+ * into a single import list alongside the Tier-0 modules.
+ *
+ * `ConfigModule` is registered globally with the merged schema's parsed
+ * output — the schema itself ran in the boot composer so any failure
+ * already surfaced before this module loads.
+ */
+let RuntimeAppModule = class RuntimeAppModule {
+    static { RuntimeAppModule_1 = this; }
+    static enableSubscription = false;
+    static authExcludedRoutes = [...AUTH_EXCLUDED_ROUTES.map(normalizeAuthExclusion)];
+    static register(opts) {
+        RuntimeAppModule_1.enableSubscription = opts.enableSubscriptionMiddleware;
+        const mergedExclusions = [
+            ...AUTH_EXCLUDED_ROUTES,
+            ...(opts.pluginAuthExclusions ?? []),
+        ].map(normalizeAuthExclusion);
+        RuntimeAppModule_1.authExcludedRoutes = mergedExclusions;
+        const validatedEnv = opts.validatedEnv;
+        const imports = [
+            ConfigModule.forRoot({
+                isGlobal: true,
+                ignoreEnvFile: true,
+                load: [() => validatedEnv],
+            }),
+            CacheModule.register({ isGlobal: true }),
+            ScheduleModule.forRoot(),
+            ThrottlerModule,
+            UcanModule,
+            BlobStoreModule,
+            AuthModule,
+            SubscriptionModule,
+            SessionsModule,
+            MessagesModule,
+            WsModule,
+            HealthModule,
+            ...(opts.pluginNestModules ?? []),
+            ...(opts.userNestModules ?? []),
+        ];
+        return {
+            module: RuntimeAppModule_1,
+            imports,
+            providers: [
+                {
+                    provide: APP_GUARD,
+                    useClass: ThrottlerGuard,
+                },
+            ],
+        };
+    }
+    configure(consumer) {
+        const excluded = RuntimeAppModule_1.authExcludedRoutes;
+        if (RuntimeAppModule_1.enableSubscription) {
+            consumer
+                .apply(AuthHeaderMiddleware, SubscriptionMiddleware)
+                .exclude(...excluded)
+                .forRoutes('*');
+        }
+        else {
+            consumer
+                .apply(AuthHeaderMiddleware)
+                .exclude(...excluded)
+                .forRoutes('*');
+        }
+    }
+};
+RuntimeAppModule = RuntimeAppModule_1 = __decorate([
+    Module({})
+], RuntimeAppModule);
+export { RuntimeAppModule };

package/dist/bootstrap/schema-composer.d.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import type { OraclePlugin } from '../plugin-api/oracle-plugin.js';
+import type { Logger } from '../plugin-api/types.js';
+export interface ComposeEnvSchemaResult {
+    schema: z.ZodObject<any>;
+    /**
+     * Map of env field name -> the plugin that owns it. Used by
+     * {@link validateEnv} to attribute Zod issues to a plugin.
+     */
+    pluginOwnership: Map<string, string>;
+}
+export interface ValidateEnvError {
+    /** Plugin owning the failing field, or `'core'` if from a base schema. */
+    plugin: string;
+    /** Dotted field path from Zod's issue (e.g. `MEMORY_MCP_URL`). */
+    field: string;
+    /** Human-readable message from Zod. */
+    message: string;
+}
+export interface ValidateEnvResult {
+    valid: boolean;
+    /** Parsed config object — empty when `valid` is false. */
+    config: Record<string, unknown>;
+    errors: ValidateEnvError[];
+}
+/**
+ * Fold every plugin's `configSchema` into a single Zod object via
+ * `.extend()`. The returned `pluginOwnership` map records which plugin
+ * contributed each top-level field so {@link validateEnv} can attribute
+ * Zod issues by plugin.
+ *
+ * Conflict policy: later wins. When two plugins declare the same field,
+ * the later definition replaces the earlier one and a warning is emitted
+ * via the supplied logger naming both plugins.
+ */
+export declare function composeEnvSchema(plugins: OraclePlugin[], baseSchema?: z.ZodObject<any>, logger?: Logger): ComposeEnvSchemaResult;
+/**
+ * Validate `env` against the merged schema and produce structured errors
+ * naming the owning plugin per failing field.
+ *
+ * On success, `config` holds the parsed object (with any Zod
+ * coercions/defaults applied). On failure, `config` is empty and every
+ * Zod issue is mapped through `pluginOwnership` to find the owner.
+ */
+export declare function validateEnv(schema: z.ZodObject<any>, env: NodeJS.ProcessEnv, pluginOwnership: Map<string, string>): ValidateEnvResult;
+//# sourceMappingURL=schema-composer.d.ts.map

package/dist/bootstrap/schema-composer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-composer.d.ts","sourceRoot":"","sources":["../../src/bootstrap/schema-composer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD,MAAM,WAAW,sBAAsB;IAErC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACzB;;;OAGG;IACH,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAQD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,YAAY,EAAE,EAEvB,UAAU,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EAC7B,MAAM,GAAE,MAAoB,GAC3B,sBAAsB,CA2BxB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAEzB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,EACxB,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,iBAAiB,CAcnB"}

package/dist/bootstrap/schema-composer.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+const NOOP_LOGGER = {
+    log: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+/**
+ * Fold every plugin's `configSchema` into a single Zod object via
+ * `.extend()`. The returned `pluginOwnership` map records which plugin
+ * contributed each top-level field so {@link validateEnv} can attribute
+ * Zod issues by plugin.
+ *
+ * Conflict policy: later wins. When two plugins declare the same field,
+ * the later definition replaces the earlier one and a warning is emitted
+ * via the supplied logger naming both plugins.
+ */
+export function composeEnvSchema(plugins, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+baseSchema, logger = NOOP_LOGGER) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let merged = baseSchema ?? z.object({});
+    const pluginOwnership = new Map();
+    if (baseSchema) {
+        for (const key of Object.keys(baseSchema.shape)) {
+            pluginOwnership.set(key, 'core');
+        }
+    }
+    for (const plugin of plugins) {
+        if (!plugin.configSchema)
+            continue;
+        const shape = plugin.configSchema.shape;
+        for (const key of Object.keys(shape)) {
+            const previous = pluginOwnership.get(key);
+            if (previous !== undefined && previous !== plugin.name) {
+                logger.warn(`[boot] env key '${key}' is defined by both '${previous}' and '${plugin.name}'; '${plugin.name}' wins.`);
+            }
+            pluginOwnership.set(key, plugin.name);
+        }
+        merged = merged.extend(shape);
+    }
+    return { schema: merged, pluginOwnership };
+}
+/**
+ * Validate `env` against the merged schema and produce structured errors
+ * naming the owning plugin per failing field.
+ *
+ * On success, `config` holds the parsed object (with any Zod
+ * coercions/defaults applied). On failure, `config` is empty and every
+ * Zod issue is mapped through `pluginOwnership` to find the owner.
+ */
+export function validateEnv(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+schema, env, pluginOwnership) {
+    const result = schema.safeParse(env);
+    if (result.success) {
+        return { valid: true, config: result.data, errors: [] };
+    }
+    const errors = result.error.issues.map((issue) => {
+        const topField = issue.path.length > 0 ? String(issue.path[0]) : '<root>';
+        const fullField = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+        const plugin = pluginOwnership.get(topField) ?? 'unknown';
+        return { plugin, field: fullField, message: issue.message };
+    });
+    return { valid: false, config: {}, errors };
+}

package/dist/config/base-env-config.d.ts

@@ -0,0 +1,31 @@
+import { ConfigService } from '@nestjs/config';
+import { type BaseEnv } from './base-env-schema.js';
+/**
+ * Runtime config view used by Tier-0 services that need an env var
+ * before NestJS DI is available (e.g. the Matrix checkpointer initialises
+ * its singleton during module factory construction).
+ *
+ * Mirrors the `get` / `getOrThrow` accessors a `ConfigService<BaseEnv>`
+ * would expose so callers don't care which path they took. The plugin
+ * config schemas merge on top via the boot composer and remain reachable
+ * via the same `ConfigService` once Nest is up — but for the checkpointer
+ * we only ever need Tier-0 keys plus the derived `ORACLE_DID`.
+ */
+export type BaseEnvWithDerived = BaseEnv & {
+    ORACLE_DID: string;
+};
+export interface BaseEnvAccessor {
+    get<K extends keyof BaseEnvWithDerived>(key: K, defaultValue?: BaseEnvWithDerived[K]): BaseEnvWithDerived[K] | undefined;
+    getOrThrow<K extends keyof BaseEnvWithDerived>(key: K): BaseEnvWithDerived[K];
+}
+/**
+ * Returns a `BaseEnvAccessor` backed by the supplied `ConfigService`
+ * (when called from inside a Nest DI scope) or by the lazily-built
+ * singleton seeded from `process.env`.
+ *
+ * Test helpers can call `resetBaseEnvConfigForTesting()` to clear the
+ * singleton between cases.
+ */
+export declare function getBaseEnvConfig(configService?: ConfigService<BaseEnvWithDerived>): BaseEnvAccessor;
+export declare function resetBaseEnvConfigForTesting(): void;
+//# sourceMappingURL=base-env-config.d.ts.map