@ixo/oracle-runtime 0.0.1

package/dist/bootstrap/create-oracle-app.js

@@ -0,0 +1,530 @@
+import { MatrixManager } from '@ixo/matrix';
+import { loadEncryptionKey, setupClaimSigningMnemonics, } from '@ixo/oracles-chain-client';
+import { SqliteSaver } from '@ixo/sqlite-saver';
+import { Logger, ValidationPipe, } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+import pkg from '../../package.json' with { type: 'json' };
+import { baseEnvSchema, validateLlmProviderKey, } from '../config/base-env-schema.js';
+import { getModelForRole, getProviderConfig } from '../llm/llm-provider.js';
+import { validateManifest } from '../manifest/validator.js';
+import { UserMatrixSqliteSyncService } from '../matrix/checkpointer/user-matrix-sqlite-sync-service.service.js';
+import { setFileProcessingProvider } from '../modules/messages/file-processing.service.js';
+import { OracleRuntimeBundleHolder } from '../modules/messages/oracle-runtime-bundle.js';
+import { SecretsService } from '../modules/secrets/secrets.service.js';
+import { UcanService } from '../modules/ucan/ucan.service.js';
+import { BUNDLED_PLUGINS } from '../plugins/index.js';
+import { buildPluginContext } from '../runtime-context/build-plugin.js';
+import { buildAmbientServices } from './ambient-factory.js';
+import { ConfigSchemaRegistry, ManifestRegistry, MiddlewareRegistry, SharedStateRegistry, SubAgentRegistry, ToolRegistry, } from '../registries/index.js';
+import { registerGracefulShutdown } from './graceful-shutdown.js';
+import { resolvePlugins, } from './plugin-loader.js';
+import { RuntimeAppModule } from './runtime-app-module.js';
+import { composeEnvSchema, validateEnv } from './schema-composer.js';
+function reportBootError(logger, message, hint) {
+    const body = hint ? `${message}\n            ${hint}` : message;
+    logger.error(`[boot-error] ${body}`);
+}
+/**
+ * Resolve plugins, validate env, populate registries, build the dynamic
+ * `RuntimeAppModule`, bootstrap NestJS (without listening) and return an
+ * `OracleApp` whose `listen()` runs `beforeListen` callbacks then starts
+ * the HTTP server.
+ *
+ * Matrix initialization runs in the background — the returned promise
+ * resolves as soon as Nest is built. Status flips via
+ * `onPluginStatusChange`.
+ */
+export async function createOracleApp(opts) {
+    validateConfig(opts.config);
+    const logger = opts.logger ?? new Logger('createOracleApp');
+    const env = opts.env ?? process.env;
+    const userPlugins = opts.plugins ?? [];
+    const bundled = opts.bundledPlugins ?? [...BUNDLED_PLUGINS];
+    // 1-3. Plugin resolution + topo + soft-dep logging
+    let resolved;
+    try {
+        resolved = resolvePlugins({
+            bundled,
+            userPlugins,
+            features: opts.features,
+            env,
+            logger,
+        });
+    }
+    catch (err) {
+        reportBootError(logger, err instanceof Error ? err.message : String(err));
+        throw err;
+    }
+    // 4. Manifest validation
+    const manifestErrors = [];
+    for (const plugin of resolved.loaded) {
+        const result = validateManifest(plugin.manifest, plugin.name);
+        if (!result.valid)
+            manifestErrors.push(...result.errors);
+    }
+    if (manifestErrors.length > 0) {
+        for (const err of manifestErrors)
+            reportBootError(logger, err);
+        throw new Error(`Plugin manifest validation failed (${manifestErrors.length} issues).`);
+    }
+    // 5. Schema merge + env validation
+    const composed = composeEnvSchema(resolved.loaded, baseEnvSchema, logger);
+    const validated = validateEnv(composed.schema, env, composed.pluginOwnership);
+    if (!validated.valid) {
+        for (const issue of validated.errors) {
+            reportBootError(logger, `Plugin '${issue.plugin}' env validation failed for '${issue.field}': ${issue.message}`, `Set '${issue.field}' or disable: features: { ${issue.plugin}: false }`);
+        }
+        throw new Error(`Env validation failed (${validated.errors.length} issues).`);
+    }
+    // Cross-field check the merged schema cannot express — the selected
+    // LLM_PROVIDER must have its API key set. Surfaced here so the message
+    // names the missing field exactly (`OPEN_ROUTER_API_KEY` / `NEBIUS_API_KEY`).
+    const llmKeyErrors = validateLlmProviderKey(validated.config);
+    if (llmKeyErrors.length > 0) {
+        for (const issue of llmKeyErrors) {
+            reportBootError(logger, `LLM provider env validation failed for '${issue.field}': ${issue.message}`);
+        }
+        throw new Error(`Env validation failed (${llmKeyErrors.length} issue${llmKeyErrors.length === 1 ? '' : 's'}).`);
+    }
+    // 5a. Build the internal identity from config + validated env. Defer until
+    // here so `ORACLE_ENTITY_DID` has been parsed by the base env schema —
+    // a missing/empty value fails validation above with a clear message.
+    const entityDid = String(validated.config.ORACLE_ENTITY_DID ?? '');
+    if (!entityDid) {
+        throw new Error('createOracleApp: ORACLE_ENTITY_DID env is required and was empty after validation.');
+    }
+    const identity = {
+        name: opts.config.name,
+        org: opts.config.org ?? '',
+        description: opts.config.description ?? '',
+        entityDid,
+        prompt: opts.config.prompt ?? {},
+    };
+    // 6. Registry population
+    const registries = {
+        tools: new ToolRegistry(),
+        subAgents: new SubAgentRegistry(),
+        middlewares: new MiddlewareRegistry(),
+        manifests: new ManifestRegistry(),
+        configSchema: new ConfigSchemaRegistry(),
+        sharedState: new SharedStateRegistry(),
+    };
+    for (const plugin of resolved.loaded) {
+        registries.tools.register(plugin);
+        registries.subAgents.register(plugin);
+        registries.middlewares.register(plugin);
+        registries.manifests.register(plugin);
+        registries.configSchema.register(plugin);
+        registries.sharedState.register(plugin);
+    }
+    // 7. NestJS bootstrap
+    const enableSubscription = resolved.loaded.some((p) => p.name === 'credits');
+    const loadedPluginNames = new Set(resolved.loaded.map((p) => p.name));
+    const pluginNestModules = resolved.loaded.flatMap((p) => {
+        const ctx = buildPluginContext({
+            config: validated.config,
+            identity,
+            availablePlugins: loadedPluginNames,
+            logger,
+            pluginName: p.name,
+        });
+        return p.getNestModules?.(ctx) ?? [];
+    });
+    // Merge plugin-declared exclusions with host-declared ones (from opts).
+    // Both flow into the same `RuntimeAppModule` configurer so the runtime
+    // doesn't care whose route is opted out — only that it is.
+    const pluginAuthExclusions = [
+        ...resolved.loaded.flatMap((p) => p.getAuthExcludedRoutes?.() ?? []),
+        ...(opts.authExcludedRoutes ?? []),
+    ];
+    const appModule = RuntimeAppModule.register({
+        validatedEnv: validated.config,
+        userNestModules: opts.nestModules,
+        pluginNestModules,
+        pluginAuthExclusions,
+        enableSubscriptionMiddleware: enableSubscription,
+    });
+    // Wire the file-processing LLM provider getter BEFORE Nest constructs
+    // `FileProcessingService`. The service's module-level getter throws on
+    // first call until this runs — has to happen pre-bootstrap.
+    // Uses the same OpenRouter / Nebius config + 'vision' role mapping the
+    // legacy apps/app wired up.
+    setFileProcessingProvider(() => {
+        const cfg = getProviderConfig();
+        return {
+            apiKey: cfg.apiKey,
+            baseURL: cfg.baseURL,
+            headers: cfg.headers,
+            model: getModelForRole('vision'),
+        };
+    });
+    const nestApp = await NestFactory.create(appModule, {
+        bufferLogs: false,
+    });
+    // Global validation — enforce every controller's `class-validator` DTO
+    // decorators. Without this, decorators like `@Matches`, `@ArrayMaxSize`,
+    // and `@IsNotEmpty` are inert and arbitrary body fields flow straight into
+    // graph state. `whitelist` strips unknown props, `forbidNonWhitelisted`
+    // rejects them outright, `transform` instantiates nested `@Type` DTOs so
+    // `@ValidateNested` actually runs. Guarded for the same reason as Swagger
+    // (lightweight test runtimes stub `NestFactory.create`).
+    if (typeof nestApp.useGlobalPipes === 'function') {
+        nestApp.useGlobalPipes(new ValidationPipe({
+            whitelist: true,
+            forbidNonWhitelisted: true,
+            transform: true,
+        }));
+    }
+    // CORS — auth flows from the browser need `x-ucan-delegation` allowed.
+    // `credentials: true` requires a specific origin (not `*`); when the
+    // host configures a wildcard we disable credentials so the browser
+    // doesn't reject the preflight. Guarded for the same reason as Swagger
+    // (test runtimes stub `NestFactory.create`).
+    if (typeof nestApp.enableCors === 'function') {
+        const corsOrigin = typeof validated.config.CORS_ORIGIN === 'string' &&
+            validated.config.CORS_ORIGIN.length > 0
+            ? validated.config.CORS_ORIGIN
+            : '*';
+        const useCredentials = corsOrigin !== '*';
+        nestApp.enableCors({
+            origin: corsOrigin,
+            credentials: useCredentials,
+            methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
+            allowedHeaders: [
+                'Content-Type',
+                'Authorization',
+                'x-ucan-delegation',
+                'x-matrix-access-token',
+                'x-matrix-homeserver',
+                'x-did',
+                'x-request-id',
+                'x-timezone',
+            ],
+            exposedHeaders: ['X-Request-Id'],
+        });
+    }
+    // Swagger UI at `/docs`. Auth middleware already excludes `/docs` and
+    // `/docs/(.*)`. Forks can replace by registering their own setup in a
+    // `beforeListen` hook.
+    //
+    // Guarded because lightweight test runtimes stub `NestFactory.create`
+    // with an object that lacks `getHttpAdapter` — Swagger introspects the
+    // adapter to know whether it's express/fastify. In production both are
+    // present.
+    try {
+        const swaggerDoc = SwaggerModule.createDocument(nestApp, new DocumentBuilder()
+            .setTitle(identity.name)
+            .setDescription(`${identity.description}\n\nQiForge runtime v${pkg.version}.`)
+            .setVersion(pkg.version)
+            .addApiKey({ type: 'apiKey', name: 'x-ucan-delegation', in: 'header' }, 'ucan')
+            .build());
+        SwaggerModule.setup('docs', nestApp, swaggerDoc);
+    }
+    catch (err) {
+        logger.warn?.(`[createOracleApp] Swagger setup skipped: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // 8. AmbientServices — built once Nest's DI container exists. Plugins reach
+    // this through `buildRuntimeContext(runConfig, ambient, state)`, wired by
+    // the messages controller on a per-request basis.
+    const ambient = buildAmbientServices({
+        nestApp,
+        config: validated.config,
+        identity,
+        availablePlugins: loadedPluginNames,
+        logger,
+    });
+    // 9. Warm the boot caches inside each registry so the per-request agent
+    // build only re-runs the request-time hooks (`getRequestTools`,
+    // `getRequestSubAgents`). Boot-time outputs are identical for every
+    // request and don't need to be recomputed.
+    const warmBuildCtx = buildPluginContext({
+        config: validated.config,
+        identity,
+        availablePlugins: loadedPluginNames,
+        logger,
+        pluginName: '__runtime__',
+    });
+    await registries.tools.collectBoot(warmBuildCtx);
+    registries.subAgents.collectBoot(warmBuildCtx);
+    registries.middlewares.collect(warmBuildCtx);
+    // Fail the boot if two plugins contribute the same tool name, sub-agent
+    // name, or shared-state key. Without this, a collision is silently
+    // resolved last-write-wins: the agent binds duplicate tools and the
+    // capability gate mis-attributes one of them, leaving it unreachable.
+    // Only the boot-time contributions are checked here — request-time tools
+    // (`getRequestTools`) are per-user and dynamic, so a static cross-plugin
+    // assertion can't cover them.
+    registries.tools.assertNoCollisions();
+    registries.subAgents.assertNoCollisions();
+    registries.sharedState.assertNoCollisions();
+    // 10. Build the merged hooks the agent build will use:
+    //   - default: per-user SQLite checkpointer backed by
+    //     `UserMatrixSqliteSyncService` (already DI-managed)
+    //   - override: anything the host passed in `opts.hooks` wins
+    //
+    // The merged hooks live inside the bundle so `agent-builder.ts` reads
+    // them through `bundle.hooks` without ever rewriting the contract.
+    const checkpointSync = nestApp.get(UserMatrixSqliteSyncService, {
+        strict: false,
+    });
+    const defaultHooks = checkpointSync
+        ? {
+            checkpointerForUser: async (userDid) => {
+                const db = await checkpointSync.getUserDatabase(userDid);
+                // Cross-package interop: SqliteSaver extends BaseCheckpointSaver
+                // from `@langchain/langgraph-checkpoint`; the hook return type
+                // pulls from `@langchain/langgraph`. pnpm hoists these into
+                // separate type identities even at the same version — they are
+                // structurally identical at runtime.
+                return SqliteSaver.fromDatabase(db);
+            },
+        }
+        : {};
+    const mergedHooks = { ...defaultHooks, ...opts.hooks };
+    // 11. Populate the OracleRuntimeBundleHolder so MessagesService (and any
+    // other Nest-managed consumer) can grab the boot-snapshot per request.
+    // `strict: false` so we get `undefined` instead of throwing when the
+    // holder isn't registered (lightweight test runtimes that skip
+    // MessagesModule). In that case the bundle is just not available.
+    const bundleHolder = nestApp.get(OracleRuntimeBundleHolder, {
+        strict: false,
+    });
+    if (bundleHolder) {
+        bundleHolder.populate({
+            ambient,
+            registries,
+            identity,
+            config: validated.config,
+            availablePlugins: loadedPluginNames,
+            hooks: mergedHooks,
+        });
+    }
+    // 12. Background Matrix init — fire-and-forget.
+    const beforeListenHooks = [];
+    const errorHandlers = [];
+    const statusHandlers = [];
+    const dispatchError = (err, source) => {
+        if (errorHandlers.length === 0) {
+            logger.error(`[${source}] ${err.message}`);
+            return;
+        }
+        for (const handler of errorHandlers) {
+            try {
+                handler(err, source);
+            }
+            catch (callbackErr) {
+                logger.error(`onError handler threw: ${String(callbackErr)}`);
+            }
+        }
+    };
+    const dispatchStatus = (evt) => {
+        for (const handler of statusHandlers) {
+            try {
+                handler(evt);
+            }
+            catch (callbackErr) {
+                logger.error(`onPluginStatusChange handler threw: ${String(callbackErr)}`);
+            }
+        }
+    };
+    if (!opts.skipMatrixInit) {
+        const matrixManager = MatrixManager.getInstance();
+        // Defer to the next macrotask so callers can attach
+        // `onPluginStatusChange` / `onError` handlers before the first event
+        // fires. The init itself is still asynchronous and does not block the
+        // returned promise.
+        setImmediate(() => {
+            dispatchStatus({ plugin: 'matrix', from: 'pending', to: 'pending' });
+            matrixManager
+                .init()
+                .then(async () => {
+                // Matrix is up. Load the UCAN signing mnemonic + (optional)
+                // user-secrets encryption key from the oracle's Matrix account
+                // room. Both rely on Matrix state events as the source of truth,
+                // so this MUST run after init.
+                //
+                // The signing mnemonic enables `UcanService.createServiceInvocation`
+                // → which the credits/subscription middleware needs on the very
+                // first authenticated request. Failing this step silently is the
+                // origin of "UCAN signing key not configured" errors mid-flight.
+                //
+                // Wrapped in try/catch so a key-setup failure (e.g. test env
+                // without real Matrix state events) doesn't block the
+                // `matrix:loaded` status dispatch — auth-requiring routes will
+                // 401 until the operator provisions the keys, but the rest of
+                // the app stays usable (health, docs, ws).
+                try {
+                    await wireSigningAndEncryptionKeys({
+                        nestApp,
+                        config: validated.config,
+                        logger,
+                    });
+                }
+                catch (err) {
+                    logger.error?.(`[boot] key setup failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                dispatchStatus({ plugin: 'matrix', from: 'pending', to: 'loaded' });
+            })
+                .catch((err) => {
+                const error = err instanceof Error ? err : new Error(String(err));
+                dispatchStatus({
+                    plugin: 'matrix',
+                    from: 'pending',
+                    to: 'failed',
+                    reason: error.message,
+                });
+                dispatchError(error, 'matrix-init');
+            });
+        });
+        if (!opts.skipGracefulShutdown) {
+            registerGracefulShutdown({ app: nestApp, matrixManager });
+        }
+    }
+    // Public surface
+    const statusReport = () => ({
+        loaded: resolved.loaded.map((p) => p.name),
+        excluded: resolved.excluded.map((e) => ({
+            plugin: e.plugin,
+            reason: e.reason,
+        })),
+        softDepGaps: resolved.softDepGaps.map((s) => ({
+            plugin: s.plugin,
+            missing: s.missing,
+        })),
+    });
+    let started = false;
+    return {
+        getNestApp() {
+            return nestApp;
+        },
+        ambient,
+        plugins: {
+            status: statusReport,
+        },
+        beforeListen(fn) {
+            beforeListenHooks.push(fn);
+        },
+        onError(handler) {
+            errorHandlers.push(handler);
+        },
+        onPluginStatusChange(handler) {
+            statusHandlers.push(handler);
+        },
+        async listen(port) {
+            if (started) {
+                throw new Error('OracleApp.listen called twice.');
+            }
+            started = true;
+            for (const hook of beforeListenHooks) {
+                await hook(nestApp);
+            }
+            const portValue = port ??
+                coercePort(validated.config.PORT) ??
+                coercePort(env.PORT) ??
+                5678;
+            await nestApp.listen(portValue, '0.0.0.0');
+            logger.log(`Oracle '${identity.name}' (runtime v${pkg.version}) listening on :${portValue}`);
+        },
+    };
+}
+function validateConfig(config) {
+    if (!config) {
+        throw new Error("createOracleApp: 'config' is required.");
+    }
+    if (!config.name) {
+        throw new Error("createOracleApp: 'config.name' is required.");
+    }
+}
+function coercePort(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.length > 0) {
+        const parsed = Number.parseInt(value, 10);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+/**
+ * After Matrix init succeeds, load the oracle's UCAN signing mnemonic and
+ * (optional) P-256 secrets encryption key from the oracle's Matrix account
+ * room, and seat them on the corresponding services.
+ *
+ * Without the signing mnemonic the credits/subscription middleware can't
+ * mint downstream invocations — every authenticated request would fail at
+ * the gate. Without the encryption key, the user-secrets read path skips
+ * silently and returns nothing (acceptable degraded mode).
+ */
+async function wireSigningAndEncryptionKeys(args) {
+    const { nestApp, config, logger } = args;
+    const need = (key) => {
+        const value = config[key];
+        if (typeof value !== 'string' || value.length === 0) {
+            throw new Error(`[boot] missing required env '${key}' for key setup`);
+        }
+        return value;
+    };
+    const matrixRoomId = typeof config.MATRIX_ACCOUNT_ROOM_ID === 'string'
+        ? config.MATRIX_ACCOUNT_ROOM_ID
+        : '';
+    const matrixAccessToken = need('MATRIX_ORACLE_ADMIN_ACCESS_TOKEN');
+    const walletMnemonic = need('SECP_MNEMONIC');
+    const pin = need('MATRIX_VALUE_PIN');
+    const signerDid = need('ORACLE_DID');
+    const network = need('NETWORK');
+    try {
+        logger.log?.('[boot] Loading UCAN signing mnemonic from Matrix...');
+        const signingMnemonic = await setupClaimSigningMnemonics({
+            matrixRoomId,
+            matrixAccessToken,
+            walletMnemonic,
+            pin,
+            signerDid,
+            network: network,
+        });
+        if (signingMnemonic) {
+            const ucan = nestApp.get(UcanService, { strict: false });
+            if (ucan) {
+                ucan.setSigningMnemonic(signingMnemonic, signerDid);
+                logger.log?.('[boot] UCAN signing mnemonic loaded.');
+            }
+            else {
+                logger.warn?.('[boot] UcanService not available — signing mnemonic dropped.');
+            }
+        }
+        else {
+            logger.warn?.('[boot] setupClaimSigningMnemonics returned null. ' +
+                'UCAN minting will be unavailable until the mnemonic is provisioned ' +
+                '(run `oracles-cli setup-claim-signing-mnemonics`).');
+        }
+    }
+    catch (error) {
+        logger.error?.(`[boot] Failed to set up claim signing mnemonics: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!matrixRoomId) {
+        logger.warn?.('[boot] No MATRIX_ACCOUNT_ROOM_ID; skipping encryption-key load. ' +
+            'User secrets will be unavailable.');
+        return;
+    }
+    try {
+        logger.log?.('[boot] Loading P-256 user-secrets encryption key...');
+        const result = await loadEncryptionKey({
+            matrixRoomId,
+            matrixAccessToken,
+            pin,
+            signerDid,
+        });
+        if (result) {
+            SecretsService.getInstance().setEncryptionKey(result.privateJwk);
+            logger.log?.('[boot] P-256 encryption key loaded.');
+        }
+        else {
+            logger.warn?.('[boot] No P-256 encryption key found. User secrets will be ' +
+                'unavailable. Provision one via `oracles-cli setup-encryption-key`.');
+        }
+    }
+    catch (error) {
+        logger.error?.(`[boot] Failed to load P-256 encryption key: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/bootstrap/graceful-shutdown.d.ts

@@ -0,0 +1,20 @@
+import { type INestApplication } from '@nestjs/common';
+import type { MatrixManager } from '@ixo/matrix';
+export interface GracefulShutdownOptions {
+    app: INestApplication;
+    matrixManager: MatrixManager;
+    /** Optional teardown callbacks run after Nest has stopped but before exit. */
+    teardown?: Array<() => Promise<void> | void>;
+    /** Signals to listen on; defaults to SIGTERM + SIGINT. */
+    signals?: NodeJS.Signals[];
+}
+/**
+ * Drain the running Nest app on SIGTERM/SIGINT: upload checkpoints to Matrix,
+ * close the HTTP server, then shut down the Matrix client. Mirrors today's
+ * boot flow so existing operators see no behaviour change when migrating.
+ *
+ * Each step is wrapped individually — an error in one step is logged and the
+ * remaining steps still run.
+ */
+export declare function registerGracefulShutdown(opts: GracefulShutdownOptions): () => void;
+//# sourceMappingURL=graceful-shutdown.d.ts.map

package/dist/bootstrap/graceful-shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graceful-shutdown.d.ts","sourceRoot":"","sources":["../../src/bootstrap/graceful-shutdown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAU,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,gBAAgB,CAAC;IACtB,aAAa,EAAE,aAAa,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;IAC7C,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;CAC5B;AAID;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,uBAAuB,GAC5B,MAAM,IAAI,CAmDZ"}

package/dist/bootstrap/graceful-shutdown.js

@@ -0,0 +1,61 @@
+import { Logger } from '@nestjs/common';
+import { UserMatrixSqliteSyncService } from '../matrix/checkpointer/user-matrix-sqlite-sync-service.service.js';
+const DEFAULT_SIGNALS = ['SIGTERM', 'SIGINT'];
+/**
+ * Drain the running Nest app on SIGTERM/SIGINT: upload checkpoints to Matrix,
+ * close the HTTP server, then shut down the Matrix client. Mirrors today's
+ * boot flow so existing operators see no behaviour change when migrating.
+ *
+ * Each step is wrapped individually — an error in one step is logged and the
+ * remaining steps still run.
+ */
+export function registerGracefulShutdown(opts) {
+    const context = 'GracefulShutdown';
+    const signals = opts.signals ?? DEFAULT_SIGNALS;
+    const handlers = new Map();
+    const shutdown = async (signal) => {
+        Logger.log(`${signal} received, starting graceful shutdown...`, context);
+        await runStep('Upload checkpoint to Matrix', async () => {
+            const syncService = opts.app.get(UserMatrixSqliteSyncService);
+            await syncService.uploadCheckpointToMatrixStorageTask();
+        });
+        await runStep('Stop Nest application', async () => {
+            await opts.app.close();
+        });
+        await runStep('Stop MatrixManager client', async () => {
+            await opts.matrixManager.shutdown();
+        });
+        for (const teardownFn of opts.teardown ?? []) {
+            await runStep('Run plugin teardown', () => teardownFn());
+        }
+        Logger.log('Graceful shutdown complete', context);
+        process.exit(0);
+    };
+    for (const signal of signals) {
+        const handler = (received) => {
+            shutdown(received).catch((err) => {
+                Logger.error('Error during graceful shutdown', err instanceof Error ? err.stack : String(err), context);
+                process.exit(1);
+            });
+        };
+        handlers.set(signal, handler);
+        process.once(signal, handler);
+    }
+    // Return a detach function for tests that need to remove the handlers.
+    return () => {
+        for (const [signal, handler] of handlers) {
+            process.off(signal, handler);
+        }
+    };
+}
+async function runStep(label, step) {
+    const context = 'GracefulShutdown';
+    Logger.log(`${label}...`, context);
+    try {
+        await step();
+        Logger.log(`${label} complete`, context);
+    }
+    catch (err) {
+        Logger.warn(`${label} failed (continuing anyway): ${err instanceof Error ? err.message : String(err)}`, context);
+    }
+}

package/dist/bootstrap/index.d.ts

@@ -0,0 +1,13 @@
+export { createOracleApp } from './create-oracle-app.js';
+export type { CreateOracleAppOptions, OracleApp, BundledFeatureName, PluginStatusReport, PluginStatusChangeEvent, } from './create-oracle-app.js';
+export { RuntimeAppModule } from './runtime-app-module.js';
+export type { RuntimeAppModuleOptions } from './runtime-app-module.js';
+export { registerGracefulShutdown } from './graceful-shutdown.js';
+export type { GracefulShutdownOptions } from './graceful-shutdown.js';
+export { resolvePlugins, topoSort } from './plugin-loader.js';
+export type { ResolvePluginsInput, ResolvePluginsResult, ExcludedPlugin, SoftDepGap, FeatureToggle, } from './plugin-loader.js';
+export { composeEnvSchema, validateEnv } from './schema-composer.js';
+export type { ComposeEnvSchemaResult, ValidateEnvResult, ValidateEnvError, } from './schema-composer.js';
+export { inspect } from './inspect.js';
+export type { InspectInput, InspectOutput, InspectPluginEntry, CollectedRegistries, } from './inspect.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bootstrap/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EACV,sBAAsB,EACtB,SAAS,EACT,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,UAAU,EACV,aAAa,GACd,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACrE,YAAY,EACV,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EACV,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,cAAc,CAAC"}

package/dist/bootstrap/index.js

@@ -0,0 +1,6 @@
+export { createOracleApp } from './create-oracle-app.js';
+export { RuntimeAppModule } from './runtime-app-module.js';
+export { registerGracefulShutdown } from './graceful-shutdown.js';
+export { resolvePlugins, topoSort } from './plugin-loader.js';
+export { composeEnvSchema, validateEnv } from './schema-composer.js';
+export { inspect } from './inspect.js';