@objectstack/runtime 7.9.0 → 8.0.1

package/dist/index.d.cts

@@ -6,12 +6,11 @@ import { ClusterCapabilityConfigInput, ExecutionContext } from '@objectstack/spe
 import { z } from 'zod';
 import * as Contracts from '@objectstack/spec/contracts';
 import { ISeedLoaderService, IDataEngine, IMetadataService } from '@objectstack/spec/contracts';
-import { SeedLoaderRequest, SeedLoaderResult, ObjectDependencyGraph, Dataset, SeedLoaderConfigInput, ExpressionBody, ScriptBody, HookBody, Hook } from '@objectstack/spec/data';
+import { SeedLoaderRequest, SeedLoaderResult, ObjectDependencyGraph, Seed, SeedLoaderConfigInput, ExpressionBody, ScriptBody, HookBody, Hook } from '@objectstack/spec/data';
 import { SchemaDiffEntry } from '@objectstack/spec/shared';
 import { MetricsRegistry, ErrorReporter } from '@objectstack/observability';
 export { CapturedError, ErrorReporter, InMemoryErrorReporter, InMemoryMetricsRegistry, MetricSample, MetricsRegistry, NoopErrorReporter, NoopMetricsRegistry, OBSERVABILITY_ERRORS_SERVICE, OBSERVABILITY_METRICS_SERVICE, RUNTIME_METRICS } from '@objectstack/observability';
 import { MiddlewareConfig, MiddlewareType } from '@objectstack/spec/system';
-import { EnvironmentArtifact } from '@objectstack/spec/cloud';
 export { RestApiPluginConfig, RestServer, RouteEntry, RouteGroupBuilder, RouteManager, createRestApiPlugin } from '@objectstack/rest';
 export { _resetEnvDeprecationWarnings, readEnvWithDeprecation } from '@objectstack/types';
 
@@ -316,7 +315,7 @@ interface Logger {
  * - Topological dependency ordering (parents before children)
  * - Multi-pass loading for circular references
  * - Dry-run validation mode
- * - Upsert support honoring DatasetSchema mode
+ * - Upsert support honoring SeedSchema mode
  * - Actionable error reporting
  */
 declare class SeedLoaderService implements ISeedLoaderService {
@@ -326,7 +325,7 @@ declare class SeedLoaderService implements ISeedLoaderService {
     constructor(engine: IDataEngine, metadata: IMetadataService, logger: Logger);
     load(request: SeedLoaderRequest): Promise<SeedLoaderResult>;
     buildDependencyGraph(objectNames: string[]): Promise<ObjectDependencyGraph>;
-    validate(datasets: Dataset[], config?: SeedLoaderConfigInput): Promise<SeedLoaderResult>;
+    validate(datasets: Seed[], config?: SeedLoaderConfigInput): Promise<SeedLoaderResult>;
     private loadDataset;
     private resolveFromDatabase;
     private resolveDeferredUpdates;
@@ -893,97 +892,54 @@ declare class HttpServer implements IHttpServer {
 }
 
 /**
- * Factory contract for instantiating a per-project {@link ObjectKernel}.
+ * Per-project driver registry contract.
+ *
+ * Resolves a project (by hostname or ID) and produces an instantiated
+ * `IDataDriver` bound to that project's physical database. Concrete
+ * implementations sit on top of either:
+ *   - the ObjectStack Cloud HTTP API (see {@link ArtifactEnvironmentRegistry})
+ *   - a local file artifact (see {@link FileArtifactApiClient} +
+ *     {@link ArtifactEnvironmentRegistry})
  *
- * Given a `environmentId`, the factory is expected to:
- * 1. Read control-plane metadata (`sys_environment` + credentials + subscribed packages).
- * 2. Construct a fresh `ObjectKernel` with project-scoped driver + plugins + Apps.
- * 3. Return a **bootstrapped** kernel ready to serve requests.
+ * The contract lives in `@objectstack/runtime` so the runtime can
+ * express "fetch artifact + boot per-project kernel" without taking a
+ * dependency on the cloud control plane.
  */
-interface EnvironmentKernelFactory {
-    create(environmentId: string): Promise<ObjectKernel>;
-}
-interface KernelManagerConfig {
-    factory: EnvironmentKernelFactory;
-    /** Maximum number of kernels to keep resident. Defaults to 32. */
-    maxSize?: number;
-    /**
-     * Time-to-live (ms). Kernels idle longer than this are evicted on next
-     * access. `0` disables TTL expiry. Defaults to 15 minutes.
-     */
-    ttlMs?: number;
-    /**
-     * Optional logger (duck-typed). Falls back to `console` when omitted.
-     */
-    logger?: {
-        info?: (...a: any[]) => void;
-        warn?: (...a: any[]) => void;
-        error?: (...a: any[]) => void;
-    };
-    /**
-     * Optional upstream-change detector. When set, every cache hit older
-     * than `staleCheckIntervalMs` triggers this probe before returning the
-     * cached kernel. Returning `true` evicts the kernel and forces a
-     * rebuild, so changes to the control-plane state that don't reach
-     * this process via push (marketplace installs, artifact republish,
-     * etc.) become visible without waiting for the LRU TTL to expire.
-     *
-     * The probe should be cheap (single small GET). Errors thrown here
-     * are caught and treated as "still fresh" so a brief upstream
-     * outage doesn't churn every cached kernel — the worst case is
-     * stale-by-`ttlMs`, which is what we had before adding the probe.
-     *
-     * `builtAtMs` is the kernel's `createdAt` time so the probe can
-     * compare against an upstream "last changed at" timestamp.
-     */
-    freshnessProbe?: (environmentId: string, builtAtMs: number) => Promise<boolean>;
-    /**
-     * Minimum gap between successive freshness probes for the same env.
-     * Defaults to 10 seconds — enough to avoid hammering the control
-     * plane on tight render loops while still keeping the user's
-     * post-install refresh perceived as immediate.
-     */
-    staleCheckIntervalMs?: number;
-}
+
+type IDataDriver = Contracts.IDataDriver;
 /**
- * LRU + TTL cache of per-project {@link ObjectKernel} instances.
+ * Multi-tenant kernel router contract.
  *
- * Implements ADR-0003 multi-kernel scheduling: each project gets an
- * isolated kernel (App/plugin/metadata namespaces) that is lazily built
- * on first request and evicted under memory / idle pressure. Concurrent
- * `getOrCreate()` calls for the same environmentId share a single in-flight
- * factory invocation (singleflight).
+ * The HTTP dispatcher uses this optional seam to resolve a per-environment
+ * kernel when serving a multi-tenant runtime. The framework only depends on
+ * the *interface* — the concrete LRU/TTL implementation (and everything else
+ * multi-tenant: hostname resolution, artifact fetching, per-env kernel
+ * construction) lives in the cloud distribution
+ * (`@objectstack/objectos-runtime`), not here.
  */
-declare class KernelManager {
-    private readonly factory;
-    private readonly maxSize;
-    private readonly ttlMs;
-    private readonly logger;
-    private readonly cache;
-    private readonly pending;
-    private readonly freshnessProbe?;
-    private readonly staleCheckIntervalMs;
-    constructor(config: KernelManagerConfig);
-    /** Returns the currently cached environmentIds (ordered by insertion). */
-    keys(): string[];
-    /** Cache size for diagnostics. */
-    get size(): number;
-    /**
-     * Resolve or construct the kernel for `environmentId`.
-     *
-     * - Cache hit (fresh): bumps `lastAccess` and returns immediately.
-     * - Cache hit (TTL expired): evicts then falls through to factory.
-     * - Cache miss: dedupes concurrent callers through `pending`.
-     */
+interface KernelManager {
+    /** Resolve (building + caching on first use) the kernel for an environment. */
     getOrCreate(environmentId: string): Promise<ObjectKernel>;
+}
+interface EnvironmentDriverRegistry {
+    /** Resolve a project by hostname. Returns `null` when unknown. */
+    resolveByHostname(host: string): Promise<{
+        environmentId: string;
+        driver: IDataDriver;
+    } | null>;
+    /** Resolve a project's driver by ID. Returns `null` when unknown. */
+    resolveById(environmentId: string): Promise<IDataDriver | null>;
     /**
-     * Evict the kernel for `environmentId` and invoke `kernel.shutdown()`.
-     * No-op when the entry is absent.
+     * Look up the cached project row + driver by ID without triggering a
+     * remote/file fetch. Returns the full cached entry when fresh.
      */
-    evict(environmentId: string): Promise<void>;
-    /** Evict all resident kernels. Used on runtime shutdown. */
-    evictAll(): Promise<void>;
-    private enforceMaxSize;
+    peekById(environmentId: string): {
+        environmentId: string;
+        driver: IDataDriver;
+        project: any;
+    } | null;
+    /** Drop cached entries for the given project. */
+    invalidate(environmentId: string): void;
 }
 
 /** Minimal local interface — full EnvironmentScopeManager was removed in Phase R. */
@@ -1083,6 +1039,62 @@ declare class HttpDispatcher {
      * @param scopeId - Optional project ID for scoped service resolution (SharedProjectPlugin mode)
      */
     private callData;
+    /**
+     * Handle an MCP request over the Streamable HTTP transport (`/mcp`).
+     *
+     * Gating + auth (fail-closed):
+     *  - **opt-in**: only served when `OS_MCP_SERVER_ENABLED=true` (single-env
+     *    runtime). Multi-tenant cloud overrides this gate per env. When off we
+     *    return 404 so the surface isn't advertised.
+     *  - **auth**: requires a principal already resolved by
+     *    `resolveExecutionContext` (the `sys_api_key` Bearer/header path or a
+     *    session). Anonymous → 401.
+     *
+     * Execution: the MCP runtime builds a stateless per-request server whose
+     * object-CRUD tools run through {@link callData} bound to THIS request's
+     * ExecutionContext — i.e. the exact permission + RLS path the REST API
+     * uses. An external agent can never exceed the key's authority.
+     */
+    handleMcp(body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /** Whether the MCP HTTP surface is opted in for this single-env runtime. */
+    private static isMcpEnabled;
+    /**
+     * Normalise the inbound request into a Web-standard `Request` for the MCP
+     * transport. Accepts an already-Web `Request`, or a node/Hono-style req
+     * (plain `headers` object, path-only `url`). Returns undefined only if the
+     * shape is unusable. The body is carried separately via `parsedBody`, so a
+     * GET/DELETE (no body) and a POST (JSON-RPC) both normalise cleanly.
+     */
+    private toMcpWebRequest;
+    /**
+     * Build a principal-bound {@link McpDataBridge}: every method runs AS the
+     * request's ExecutionContext through {@link callData} (RLS/permissions) and
+     * the per-env metadata service. Keeps the MCP tool layer free of any direct
+     * engine access.
+     */
+    private buildMcpBridge;
+    /**
+     * Generate a `sys_api_key` and return the raw secret EXACTLY ONCE
+     * (`POST /keys`). This is the only mint path — the raw key is never stored
+     * (only its sha256 hash) and never re-displayable.
+     *
+     * Security (zero-tolerance):
+     *  - Requires an authenticated principal; `user_id` is PINNED to that
+     *    caller and is NEVER read from the request body (no impersonation).
+     *  - Body is whitelisted to `name` (+ optional `expires_at`); any
+     *    `key` / `id` / `user_id` / `revoked` in the body is ignored, so a
+     *    caller cannot forge a known-secret or escalate.
+     *  - `scopes` are intentionally NOT accepted from the body in v1: the
+     *    verify path ADDS scopes to the principal's permissions, so honouring
+     *    arbitrary body scopes would be an escalation vector. A generated key
+     *    therefore acts exactly AS the caller (via `user_id` resolution).
+     *    Narrowing/scoped keys need subset-enforcement — deferred.
+     *  - The raw key and its hash never enter logs or error messages.
+     *  - The row is written with an elevated `{ isSystem: true }` context
+     *    because `sys_api_key` is protection-locked; safe because the row's
+     *    contents are fully server-controlled (user_id pinned to caller).
+     */
+    handleKeys(method: string, body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
     /**
      * Parse a project UUID out of a scoped URL path such as
      * `/api/v1/environments/abc-123/data/task` or `/projects/abc-123/meta`.
@@ -1158,6 +1170,7 @@ declare class HttpDispatcher {
             notifications: string | undefined;
             ai: string | undefined;
             i18n: string | undefined;
+            mcp: string | undefined;
         };
         endpoints: {
             data: string;
@@ -1174,6 +1187,7 @@ declare class HttpDispatcher {
             notifications: string | undefined;
             ai: string | undefined;
             i18n: string | undefined;
+            mcp: string | undefined;
         };
         features: {
             graphql: boolean;
@@ -1523,6 +1537,18 @@ declare class HttpDispatcher {
      * Physical database addressing (database_url, database_driver, etc.)
      * is stored directly on the sys_environment row.
      */
+    /**
+     * Apply just-published `seed` metadata: load each seed's rows into its
+     * target object so publishing a seed draft makes the data live (the runtime
+     * counterpart to staging it). Reads each seed body via the protocol, then
+     * runs the {@link SeedLoaderService} for the active org. Best-effort and
+     * idempotent (upsert) — callers must never let this fail the publish.
+     *
+     * Lives at the runtime layer (not in the objectql publish primitive)
+     * because the seed loader needs the data engine + metadata service, which
+     * objectql cannot depend on without a layering cycle.
+     */
+    private applyPublishedSeeds;
     /**
      * Resolve the calling user id from the request session, if any.
      * Returns `undefined` for anonymous calls or when auth is not wired up.
@@ -1737,316 +1763,6 @@ declare function readArtifactSource(pathOrUrl: string, opts?: {
 declare function loadArtifactBundle(absArtifactPath: string, opts?: LoadArtifactBundleOptions): Promise<any | null>;
 declare function mergeRuntimeModule(bundle: any, artifactAbsPath: string, tag?: string): Promise<void>;
 
-/**
- * Artifact API client.
- *
- * HTTP client that talks to the ObjectStack control plane (e.g.
- * `apps/cloud`) to resolve hostnames to projects and to download a
- * project's compiled artifact.
- *
- * The control plane is expected to expose two endpoints:
- *
- *   GET {controlPlaneUrl}/api/v1/cloud/resolve-hostname?host={hostname}
- *     → { environmentId: string, organizationId?: string, runtime?: EnvironmentRuntimeConfig }
- *
- *   GET {controlPlaneUrl}/api/v1/cloud/environments/:environmentId/artifact
- *     → EnvironmentArtifactResponse  (EnvironmentArtifact + optional `runtime` block)
- *
- * Both endpoints accept an optional `Authorization: Bearer <apiKey>`.
- *
- * Responses are cached in-memory with a TTL so each kernel-manager
- * miss does not produce an extra HTTP round trip. Concurrent callers
- * for the same key share a single in-flight promise (singleflight).
- */
-
-/**
- * Per-project runtime config injected by the control plane alongside
- * the artifact. Carries the physical database URL the runtime should
- * connect to (this is *not* part of the developer-authored compiled
- * artifact — the control plane mints it when serving the API).
- */
-interface EnvironmentRuntimeConfig {
-    organizationId?: string;
-    hostname?: string;
-    /** Driver type — e.g. `sqlite`, `postgres`, `turso`, `memory`. */
-    databaseDriver: string;
-    /** Driver-specific connection URL. */
-    databaseUrl: string;
-    /** Optional auth token (e.g. for libSQL/Turso). */
-    databaseAuthToken?: string;
-    /**
-     * Project-level metadata captured by the control plane at create time
-     * (e.g. `ownerSeed`, `orgSeed`). Forwarded to the runtime so cold-boot
-     * seed replay can mirror the cloud org + owner into the project DB
-     * before the user's first SSO callback arrives.
-     */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Hostname resolution response.
- */
-interface ResolvedHostname {
-    environmentId: string;
-    organizationId?: string;
-    /** Optional runtime config — when present, callers can skip the artifact fetch's runtime block. */
-    runtime?: EnvironmentRuntimeConfig;
-}
-/**
- * Artifact response wrapping the spec's `EnvironmentArtifact` envelope plus
- * an optional `runtime` block carrying the project's database
- * connection details.
- */
-interface EnvironmentArtifactResponse extends EnvironmentArtifact {
-    runtime?: EnvironmentRuntimeConfig;
-}
-interface ArtifactApiClientConfig {
-    /** Control-plane base URL (no trailing slash). */
-    controlPlaneUrl: string;
-    /** Optional bearer token. */
-    apiKey?: string;
-    /** Cache TTL in ms. Default: 5 min. */
-    cacheTtlMs?: number;
-    /** Timeout for control-plane HTTP calls in ms. Default: 10s. */
-    requestTimeoutMs?: number;
-    /** Optional fetch override (testing). */
-    fetch?: typeof fetch;
-    /** Optional logger. */
-    logger?: {
-        info?: (...a: any[]) => void;
-        warn?: (...a: any[]) => void;
-        error?: (...a: any[]) => void;
-    };
-}
-declare class ArtifactApiClient {
-    private readonly base;
-    private readonly apiKey?;
-    private readonly cacheTtlMs;
-    private readonly requestTimeoutMs;
-    private readonly fetchImpl;
-    private readonly logger;
-    private readonly hostnameCache;
-    private readonly artifactCache;
-    private readonly pendingHostname;
-    private readonly pendingArtifact;
-    constructor(config: ArtifactApiClientConfig);
-    /**
-     * Resolve a hostname to its project. Returns `null` on 404 or
-     * malformed responses. Errors (network / 5xx) are thrown so
-     * upstream callers can retry.
-     */
-    resolveHostname(host: string): Promise<ResolvedHostname | null>;
-    /**
-     * Fetch the compiled artifact for a project.
-     *
-     * When `opts.commit` is set, requests that specific revision via the
-     * existing `?commit=` query param. Different commits are cached
-     * independently (the cache key includes the commit id) so the preview
-     * runtime can hold multiple versions in memory simultaneously.
-     */
-    fetchArtifact(environmentId: string, opts?: {
-        commit?: string;
-    }): Promise<EnvironmentArtifactResponse | null>;
-    /**
-     * Resolve an 8-hex project short id (first 8 hex chars of the UUID,
-     * dashes stripped) to the full environmentId. Used by the preview
-     * runtime, which encodes project ids in subdomains.
-     *
-     * Returns `null` on 404 or ambiguity (the control plane returns 409
-     * if the prefix matches more than one project).
-     */
-    lookupProjectByShortId(shortId: string): Promise<{
-        environmentId: string;
-        organizationId?: string;
-    } | null>;
-    /**
-     * Fetch the head commit of a branch. Returns the commit id (and the
-     * matching revision row's `published_at` for cache-validity checks).
-     * Reuses the existing `GET /cloud/environments/:id/branches` endpoint.
-     */
-    fetchBranchHead(environmentId: string, branchName: string): Promise<{
-        commitId: string;
-        publishedAt?: string | null;
-    } | null>;
-    /**
-     * Cheap freshness probe — returns the env's `last_published_at`
-     * (and best-effort current commit) without rebuilding the artifact.
-     * Used by `KernelManager` on cache hits to detect when a per-env
-     * kernel has been invalidated by an upstream change (marketplace
-     * install/uninstall, artifact publish) so it can be rebuilt
-     * without waiting for the 15-minute LRU TTL to expire.
-     *
-     * Returns `null` on definitive 404 / unknown env. Errors propagate
-     * (caller decides whether to treat unreachable cloud as fresh or
-     * stale — typically fresh, so a brief outage doesn't churn every
-     * cached kernel).
-     */
-    getFreshness(environmentId: string): Promise<{
-        environmentId: string;
-        lastPublishedAt: string | null;
-        commitId: string | null;
-    } | null>;
-    /** Drop cached entries for a project (and any matching hostname). */
-    invalidate(environmentId: string): void;
-    /** Drop everything. Used on shutdown / hot-reload. */
-    clear(): void;
-    private request;
-    private buildHeaders;
-}
-
-interface FileArtifactApiClientConfig {
-    /**
-     * Path to a compiled artifact JSON file (`dist/objectstack.json`).
-     * Resolved against `process.cwd()` when relative. Defaults to
-     * `<cwd>/dist/objectstack.json`.
-     */
-    artifactPath?: string;
-    /**
-     * Project id every hostname maps to. Defaults to
-     * `process.env.OS_ENVIRONMENT_ID` or `'proj_local'`.
-     */
-    environmentId?: string;
-    /**
-     * Organization id surfaced alongside the project. Defaults to
-     * `process.env.OS_ORGANIZATION_ID` or `'org_local'`.
-     */
-    organizationId?: string;
-    /**
-     * Override runtime config. When unset, the client tries to derive
-     * one from the artifact's `datasources` array; if that fails it
-     * falls back to a local-file SQLite DB at
-     * `<cwd>/.objectstack/data/<environmentId>.db`.
-     */
-    runtime?: EnvironmentRuntimeConfig;
-    /**
-     * Reload the artifact on every fetch instead of caching the first
-     * read. Useful when iterating on a project's metadata without
-     * restarting objectos. Defaults to `true` for dev ergonomics.
-     */
-    watch?: boolean;
-    /** Optional logger. */
-    logger?: {
-        info?: (...a: any[]) => void;
-        warn?: (...a: any[]) => void;
-        error?: (...a: any[]) => void;
-    };
-}
-declare class FileArtifactApiClient {
-    private readonly artifactPath;
-    private readonly environmentId;
-    private readonly organizationId;
-    private readonly overrideRuntime?;
-    private readonly watch;
-    private readonly logger;
-    private cached?;
-    constructor(config?: FileArtifactApiClientConfig);
-    resolveHostname(_host: string): Promise<ResolvedHostname | null>;
-    fetchArtifact(_environmentId: string, _opts?: {
-        commit?: string;
-    }): Promise<EnvironmentArtifactResponse | null>;
-    lookupProjectByShortId(_shortId: string): Promise<{
-        environmentId: string;
-        organizationId?: string;
-    } | null>;
-    fetchBranchHead(_environmentId: string, _branchName: string): Promise<{
-        commitId: string;
-        publishedAt?: string | null;
-    } | null>;
-    invalidate(_environmentId: string): void;
-    clear(): void;
-    private loadArtifact;
-    private readRuntimeFromArtifact;
-    private deriveRuntimeFromMetadata;
-    private defaultLocalSqliteRuntime;
-}
-
-/**
- * createObjectOSStack
- *
- * ObjectOS pure-runtime stack — no control-plane database, no auth /
- * security / audit / tenant plugins. The host kernel registers:
- *
- *   - A minimal engine triplet (ObjectQL + in-memory DriverPlugin +
- *     MetadataPlugin) so CLI auto-injected plugins (Setup, Studio,
- *     Dispatcher, REST) and the runtime can boot. The host kernel itself
- *     never reads or writes business data — every record query is routed
- *     to a per-project kernel built from a remote artifact.
- *   - The `env-registry` and `kernel-manager` services, so the runtime's
- *     HTTP dispatcher can resolve hostnames and dispatch every request
- *     to the matching project kernel.
- *
- * Invoked by `createRuntimeStack()` whenever `OS_CLOUD_URL`
- * (or `config.controlPlaneUrl`) is set. The same plugin shape is returned
- * as `createCloudStack()` so host configs can swap stacks transparently.
- */
-
-interface ObjectOSStackConfig {
-    /**
-     * Control-plane base URL (HTTP) or a sentinel of `'file'` for the
-     * local file-backed dev mode. Required unless `client` is supplied.
-     *
-     * - `http(s)://…`  — talk to a real ObjectStack Cloud control plane
-     *   over HTTP and resolve hostnames via its `/cloud/*` API.
-     * - `'file'`       — load a single project from a local
-     *   `dist/objectstack.json` (or `fileConfig.artifactPath`). Every
-     *   request, regardless of hostname, resolves to the same project.
-     *   Intended for `pnpm dev` / smoke tests where standing up a
-     *   separate control plane is overkill.
-     */
-    controlPlaneUrl?: string;
-    /** Optional bearer token for the control-plane API. */
-    controlPlaneApiKey?: string;
-    /**
-     * Override the artifact client entirely. When supplied,
-     * `controlPlaneUrl` is ignored — useful for tests or custom transports.
-     */
-    client?: ArtifactApiClient | FileArtifactApiClient;
-    /** Config for the file-backed mode (used when `controlPlaneUrl === 'file'`). */
-    fileConfig?: FileArtifactApiClientConfig;
-    /** KernelManager LRU size. Default: 32. */
-    kernelCacheSize?: number;
-    /** KernelManager idle TTL (ms). Default: 15 min. */
-    kernelTtlMs?: number;
-    /** EnvironmentDriverRegistry cache TTL (ms). Default: 5 min. */
-    envCacheTtlMs?: number;
-    /** Artifact / hostname response cache TTL (ms). Default: 5 min. */
-    artifactCacheTtlMs?: number;
-    /** API prefix (carried for parity with cloud-stack). Default: /api/v1. */
-    apiPrefix?: string;
-    /**
-     * Host-supplied runtime plugins appended to the stack's default plugin
-     * list. This is the official seam for a host (e.g. the ObjectStack Cloud
-     * repo) to add **product/policy** plugins — marketplace install, cloud-
-     * account binding, set-initial-password — to the otherwise-neutral
-     * framework runtime, WITHOUT a framework release and without reaching into
-     * the returned array by hand.
-     *
-     * They are appended last, so they mount their routes after the framework
-     * plugins and can override/augment behaviour (e.g. supply a credentialled
-     * install path that the browse-only MarketplaceProxyPlugin deliberately
-     * does not). See docs/design/cloud-account-binding-marketplace-install.md
-     * (ADR §5.2 — "framework exposes seams; cloud supplies metadata + policy").
-     */
-    extraPlugins?: Plugin[];
-    /**
-     * Capability tokens force-mounted on EVERY per-environment kernel, in
-     * addition to whatever the app artifact declares in `requires`. Merged and
-     * de-duped with `bundle.requires` before the capability loader runs. This
-     * is the host seam for a cloud operator to make a capability ubiquitous
-     * across all tenants without editing each app — e.g. `['ai','aiStudio']`
-     * so every cloud environment supports AI-driven online development.
-     */
-    defaultRequires?: string[];
-}
-interface ObjectOSStackResult {
-    plugins: any[];
-    api: {
-        enableProjectScoping: true;
-        projectResolution: 'auto';
-        requireAuth: true;
-    };
-}
-declare function createObjectOSStack(config: ObjectOSStackConfig): Promise<ObjectOSStackResult>;
-
 /**
  * MarketplaceProxyPlugin
  *
@@ -2315,265 +2031,6 @@ declare const DEFAULT_CLOUD_URL = "https://cloud.objectos.ai";
  */
 declare function resolveCloudUrl(explicit?: string | null): string;
 
-/**
- * Per-project driver registry contract.
- *
- * Resolves a project (by hostname or ID) and produces an instantiated
- * `IDataDriver` bound to that project's physical database. Concrete
- * implementations sit on top of either:
- *   - the ObjectStack Cloud HTTP API (see {@link ArtifactEnvironmentRegistry})
- *   - a local file artifact (see {@link FileArtifactApiClient} +
- *     {@link ArtifactEnvironmentRegistry})
- *
- * The contract lives in `@objectstack/runtime` so the runtime can
- * express "fetch artifact + boot per-project kernel" without taking a
- * dependency on the cloud control plane.
- */
-
-type IDataDriver$1 = Contracts.IDataDriver;
-interface EnvironmentDriverRegistry {
-    /** Resolve a project by hostname. Returns `null` when unknown. */
-    resolveByHostname(host: string): Promise<{
-        environmentId: string;
-        driver: IDataDriver$1;
-    } | null>;
-    /** Resolve a project's driver by ID. Returns `null` when unknown. */
-    resolveById(environmentId: string): Promise<IDataDriver$1 | null>;
-    /**
-     * Look up the cached project row + driver by ID without triggering a
-     * remote/file fetch. Returns the full cached entry when fresh.
-     */
-    peekById(environmentId: string): {
-        environmentId: string;
-        driver: IDataDriver$1;
-        project: any;
-    } | null;
-    /** Drop cached entries for the given project. */
-    invalidate(environmentId: string): void;
-}
-
-/**
- * EnvironmentDriverRegistry implementation that talks to the control plane
- * over HTTP via {@link ArtifactApiClient}.
- *
- * Mirrors {@link DefaultEnvironmentDriverRegistry} from `environment-registry.ts`
- * but does **not** read from a local control-plane database. Hostname →
- * environmentId resolution and per-project runtime config (database URL /
- * driver) come from the control plane API.
- *
- * The cached `project` payload exposed by `peekById()` is shaped to look
- * like a `sys_environment` row so callers downstream (notably
- * `ArtifactKernelFactory`) can read `id`, `organization_id`,
- * `database_url` and `database_driver` without branching.
- */
-
-type IDataDriver = Contracts.IDataDriver;
-interface ArtifactEnvironmentRegistryConfig {
-    client: ArtifactApiClient;
-    /** Cache TTL for resolved drivers in ms. Default: 5 min. */
-    cacheTtlMs?: number;
-    /** Optional logger. */
-    logger?: {
-        info?: (...a: any[]) => void;
-        warn?: (...a: any[]) => void;
-        error?: (...a: any[]) => void;
-    };
-}
-declare class ArtifactEnvironmentRegistry implements EnvironmentDriverRegistry {
-    private readonly client;
-    private readonly cacheTTL;
-    private readonly logger;
-    private readonly hostnameCache;
-    private readonly idCache;
-    private readonly pending;
-    constructor(config: ArtifactEnvironmentRegistryConfig);
-    resolveByHostname(host: string): Promise<{
-        environmentId: string;
-        driver: IDataDriver;
-    } | null>;
-    resolveById(environmentId: string): Promise<IDataDriver | null>;
-    peekById(environmentId: string): {
-        environmentId: string;
-        driver: IDataDriver;
-        project: any;
-    } | null;
-    invalidate(environmentId: string): void;
-    private buildCacheEntry;
-}
-
-interface ArtifactKernelFactoryConfig {
-    client: ArtifactApiClient;
-    envRegistry: EnvironmentDriverRegistry;
-    /** Optional logger. */
-    logger?: {
-        info?: (...a: any[]) => void;
-        warn?: (...a: any[]) => void;
-        error?: (...a: any[]) => void;
-    };
-    /** Optional kernel constructor config. */
-    kernelConfig?: ConstructorParameters<typeof ObjectKernel>[0];
-    /**
-     * Base secret used to derive per-project AuthPlugin secrets via
-     * HKDF-style HMAC-SHA256(baseSecret, environmentId). Falls back to
-     * `process.env.OS_AUTH_SECRET` / `AUTH_SECRET` at construction time.
-     */
-    authBaseSecret?: string;
-    /**
-     * Capability tokens force-mounted on every per-environment kernel, merged
-     * (and de-duped by the loader) with the artifact's own `requires`. Lets a
-     * host make a capability ubiquitous across tenants — e.g. `['ai','aiStudio']`.
-     */
-    defaultRequires?: string[];
-}
-declare class ArtifactKernelFactory implements EnvironmentKernelFactory {
-    private readonly client;
-    private readonly envRegistry;
-    private readonly logger;
-    private readonly kernelConfig?;
-    private readonly authBaseSecret;
-    private readonly defaultRequires;
-    constructor(config: ArtifactKernelFactoryConfig);
-    create(environmentId: string): Promise<ObjectKernel>;
-}
-
-/**
- * AuthProxyPlugin
- *
- * Mounts a single `/api/v1/auth/*` wildcard route on the host's Hono server
- * that forwards every request to the per-project `AuthManager` registered
- * by `ArtifactKernelFactory`.
- *
- * Why a dedicated plugin: AuthPlugin (better-auth) registers its routes by
- * grabbing the host's `http-server` service from its own `PluginContext`.
- * In objectos runtime mode AuthPlugin lives on a per-project kernel — it
- * has no access to the host's HTTP server, so its `kernel:ready` route
- * registration is a no-op. The dispatcher plugin's wildcard registration
- * via `IHttpServer.post('/auth/*', …)` proved unreliable in practice,
- * so this plugin uses Hono's raw app directly (same path AuthPlugin took
- * historically) which is rock solid.
- *
- * Routing:
- *   1. Resolve the project from the request hostname via `env-registry`.
- *   2. Acquire the project's kernel via `kernel-manager`.
- *   3. Look up the `auth` service on that kernel — this is the better-auth
- *      handler injected by `ArtifactKernelFactory`.
- *   4. Build a Web `Request` using the project's canonical baseUrl and
- *      hand it to the better-auth handler.
- *   5. Stream the response back through Hono.
- */
-
-declare class AuthProxyPlugin implements Plugin {
-    readonly name = "com.objectstack.runtime.auth-proxy";
-    readonly version = "1.0.0";
-    init: (_ctx: PluginContext) => Promise<void>;
-    start: (ctx: PluginContext) => Promise<void>;
-}
-
-/**
- * Provider id used in better-auth's `genericOAuth` and as part of the
- * callback URL: `/api/v1/auth/oauth2/callback/<PROVIDER_ID>`. Keep stable —
- * changing it invalidates every registered redirect_uri.
- */
-declare const PLATFORM_SSO_PROVIDER_ID = "objectstack-cloud";
-/**
- * Derive the per-project OAuth client_id used in `sys_oauth_application`
- * (cloud side) and {@link genericOAuth} config (project side).
- */
-declare function derivePlatformSsoClientId(environmentId: string): string;
-/**
- * Derive the per-project OAuth client_secret deterministically from the
- * shared master secret. HMAC-SHA256(baseSecret, 'oauth-client:' + environmentId)
- * yields a 64-char hex string that is:
- *   - stable across container cold-starts (no DB lookup needed)
- *   - independent per project (compromising one does not compromise others)
- *   - rotatable via OS_AUTH_SECRET rotation (invalidates all SSO clients)
- *
- * This is the **plaintext** value the RP must present at the token endpoint.
- * The cloud-side `sys_oauth_application.client_secret` column instead stores
- * {@link hashPlatformSsoClientSecret}(plaintext) — better-auth's oauth-provider
- * defaults to `storeClientSecret: 'hashed'` (SHA-256 + base64url) when the JWT
- * plugin is enabled, and looks up the row by hashing the presented secret.
- */
-declare function derivePlatformSsoClientSecret(baseSecret: string, environmentId: string): string;
-/**
- * Build the redirect_uri better-auth's `genericOAuth` plugin will use
- * when the project kernel mounts the provider with id
- * {@link PLATFORM_SSO_PROVIDER_ID}. MUST be one of the URIs registered
- * on the cloud-side oauth client or the authorization server will reject
- * the callback with `invalid_request`.
- */
-declare function buildPlatformSsoRedirectUri(hostname: string, basePath?: string): string;
-interface SeedPlatformSsoClientOptions {
-    /**
-     * Cloud control-plane ObjectQL engine. Must expose `find(object, query)`,
-     * `insert(object, data)`, and `update(object, data, {where})`. Both the
-     * `apps/cloud` boot kernel (via `kernel.getService('objectql')`) and the
-     * dispatcher's local `ql` reference satisfy this shape.
-     */
-    ql: {
-        find: (object: string, query: any, opts?: any) => Promise<any>;
-        insert: (object: string, data: any, opts?: any) => Promise<any>;
-        update: (object: string, data: any, where: any, opts?: any) => Promise<any>;
-    };
-    /** Project id (also used to derive client_id + client_secret). */
-    environmentId: string;
-    /**
-     * Project hostname (e.g. `acme-crm.objectos.ai`). Optional — projects
-     * may be created before a hostname is assigned, in which case no
-     * redirect_uri is registered yet and the row is upserted with an
-     * empty `redirect_uris` array. Calling this function again once the
-     * hostname is known will merge the new URI in.
-     */
-    hostname?: string | null;
-    /** Master secret shared between cloud and project containers. */
-    baseSecret: string;
-    /** Optional logger for diagnostics. */
-    logger?: {
-        info?: (...a: any[]) => void;
-        warn?: (...a: any[]) => void;
-        error?: (...a: any[]) => void;
-    };
-    /** When true, rethrow insert/update errors instead of swallowing them.
-     * Backfill uses this to surface real failures via the admin endpoint. */
-    throwOnError?: boolean;
-}
-/**
- * Idempotently upsert a `sys_oauth_application` row for the given project.
- * Re-running with the same `environmentId` is a no-op (the deterministic
- * `client_id` is uniquely indexed and the secret derivation is stable).
- * Re-running with a new `hostname` adds the new redirect_uri to the
- * existing row's JSON array.
- */
-declare function seedPlatformSsoClient(opts: SeedPlatformSsoClientOptions): Promise<void>;
-interface BackfillPlatformSsoClientsOptions {
-    ql: SeedPlatformSsoClientOptions['ql'];
-    baseSecret: string;
-    logger?: {
-        info?: (...a: any[]) => void;
-        warn?: (...a: any[]) => void;
-        error?: (...a: any[]) => void;
-    };
-    /** Hard cap on rows scanned (default: 1000). */
-    limit?: number;
-}
-/**
- * Scan `sys_environment` and ensure every active project has a corresponding
- * `sys_oauth_application` row. Intended to run once at cloud boot — the
- * happy path is dominated by the project-create hook
- * ({@link seedPlatformSsoClient}); the backfill exists so projects
- * created before this feature shipped also get SSO support without an
- * out-of-band migration.
- */
-declare function backfillPlatformSsoClients(opts: BackfillPlatformSsoClientsOptions): Promise<{
-    scanned: number;
-    seeded: number;
-    alreadyExisted: number;
-    failures: Array<{
-        environmentId: string;
-        error: string;
-    }>;
-}>;
-
 /**
  * # Hook & Action Body Sandbox
  *
@@ -2804,4 +2261,4 @@ declare function actionBodyRunnerFactory(runner: ScriptRunner, opts: FactoryOpti
     timeoutMs?: number;
 }) => ((actionCtx: any) => Promise<unknown>) | undefined;
 
-export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, DEFAULT_CLOUD_URL, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentArtifactResponse, type EnvironmentDriverRegistry, type EnvironmentKernelFactory, type EnvironmentRuntimeConfig, type ExternalSchemaDriftEvent, ExternalValidationPlugin, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, MarketplaceInstallLocalPlugin, type MarketplaceInstallLocalPluginConfig, MarketplaceProxyPlugin, type MarketplaceProxyPluginConfig, MiddlewareManager, type ObjectOSStackConfig, type ObjectOSStackResult, ObservabilityServicePlugin, type ObservabilityServicePluginOptions, PLATFORM_SSO_PROVIDER_ID, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, RuntimeConfigPlugin, type RuntimeConfigPluginConfig, SYSTEM_ENVIRONMENT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemEnvironmentPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createExternalValidationPlugin, createObjectOSStack, createStandaloneStack, createSystemEnvironmentPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveCloudUrl, resolveDefaultArtifactPath, resolveErrorReporter, resolveMetrics, resolveObjectStackHome, resolveRequestId, seedPlatformSsoClient };
+export { AppPlugin, DEFAULT_CLOUD_URL, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentDriverRegistry, type ExternalSchemaDriftEvent, ExternalValidationPlugin, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, type KernelManager, type LoadArtifactBundleOptions, MarketplaceInstallLocalPlugin, type MarketplaceInstallLocalPluginConfig, MarketplaceProxyPlugin, type MarketplaceProxyPluginConfig, MiddlewareManager, ObservabilityServicePlugin, type ObservabilityServicePluginOptions, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, Runtime, type RuntimeConfig, RuntimeConfigPlugin, type RuntimeConfigPluginConfig, SYSTEM_ENVIRONMENT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type StandaloneStackConfig, type StandaloneStackResult, type SystemEnvironmentPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createExternalValidationPlugin, createStandaloneStack, createSystemEnvironmentPlugin, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveCloudUrl, resolveDefaultArtifactPath, resolveErrorReporter, resolveMetrics, resolveObjectStackHome, resolveRequestId };