@objectstack/runtime 4.0.5 → 4.1.1

package/dist/index.d.ts

@@ -2,10 +2,12 @@ import { ObjectKernel, IHttpServer, ObjectKernelConfig, Plugin, PluginContext, R
 export * from '@objectstack/core';
 export { ObjectKernel } from '@objectstack/core';
 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 { ExecutionContext } from '@objectstack/spec/kernel';
 import { MiddlewareConfig, MiddlewareType } from '@objectstack/spec/system';
+import { ProjectArtifact } from '@objectstack/spec/cloud';
 export { RestApiPluginConfig, RestServer, RouteEntry, RouteGroupBuilder, RouteManager, createRestApiPlugin } from '@objectstack/rest';
 
 interface RuntimeConfig {
@@ -73,9 +75,55 @@ interface StandaloneStackResult {
         enableProjectScoping: false;
         projectResolution: 'none';
     };
+    /**
+     * Top-level metadata copied from the loaded artifact bundle (when an
+     * artifact was successfully loaded). These are surfaced so callers
+     * that wrap this result as a `defineStack()`-shaped config (e.g. the
+     * CLI's `serve` command without a host `objectstack.config.ts`) can
+     * still drive tier resolution, capability detection and driver
+     * auto-registration off the artifact's declarations.
+     */
+    requires?: string[];
+    objects?: any[];
+    manifest?: any;
 }
 declare function createStandaloneStack(config?: StandaloneStackConfig): Promise<StandaloneStackResult>;
 
+interface DefaultHostConfigOptions extends StandaloneStackConfig {
+    /**
+     * When true (the default), throws if no artifact source can be
+     * resolved (no explicit `artifactPath`, no `OS_ARTIFACT_PATH` env,
+     * and `<cwd>/dist/objectstack.json` does not exist).
+     *
+     * Set to false to allow booting an empty kernel — useful for tests
+     * that want to assemble plugins manually after the stack is built.
+     */
+    requireArtifact?: boolean;
+}
+type DefaultHostConfigResult = StandaloneStackResult;
+/**
+ * Resolve the artifact source for a default-host boot.
+ *
+ * Returns the explicit override, then `OS_ARTIFACT_PATH`, then the
+ * canonical `<cwd>/dist/objectstack.json` if it exists on disk.
+ * Returns `undefined` if none of these are available.
+ *
+ * URLs (`http(s)://`) are returned as-is — they are validated lazily by
+ * the loader, since we cannot stat a remote resource cheaply.
+ */
+declare function resolveDefaultArtifactPath(explicitPath?: string, cwd?: string): string | undefined;
+/**
+ * Build a `defineStack()`-shaped config from an `objectstack build`
+ * artifact, with no `objectstack.config.ts` required.
+ *
+ * @example
+ *   // packages/cli/src/commands/serve.ts
+ *   if (!fs.existsSync(absolutePath)) {
+ *       config = await createDefaultHostConfig();
+ *   }
+ */
+declare function createDefaultHostConfig(options?: DefaultHostConfigOptions): Promise<DefaultHostConfigResult>;
+
 /**
  * Driver Plugin
  *
@@ -247,6 +295,337 @@ declare class SeedLoaderService implements ISeedLoaderService {
     private buildResult;
 }
 
+/**
+ * Security response headers builder.
+ *
+ * Returns the conservative defaults every production API server should
+ * send on every response. Designed to be merged with route-specific
+ * headers by the dispatcher (`sendResult`) so all adapters (Hono,
+ * Fastify, Express, Next.js, …) get them uniformly without each one
+ * re-implementing helmet.
+ *
+ * What we DO opinionate:
+ *   - Content-Security-Policy (api-default: deny everything but self)
+ *   - Strict-Transport-Security (HSTS, prod-only — TLS is the caller's
+ *     responsibility; we just emit the header)
+ *   - X-Content-Type-Options: nosniff
+ *   - X-Frame-Options: DENY (anti clickjacking)
+ *   - Referrer-Policy: no-referrer
+ *   - Permissions-Policy: geolocation=(), camera=(), microphone=()
+ *   - Cross-Origin-Resource-Policy: same-origin
+ *
+ * What we DON'T opinionate:
+ *   - X-XSS-Protection (deprecated)
+ *   - CORS — that's an app concern, configure separately
+ *   - CSP for HTML pages — set a different CSP at the SPA host
+ *
+ * Every header can be overridden or disabled by config.
+ */
+interface SecurityHeadersOptions {
+    /**
+     * Enable HSTS. Set to `true` in production behind TLS. When `false`
+     * the Strict-Transport-Security header is omitted.
+     * @default false
+     */
+    hsts?: boolean | {
+        /** Max-age in seconds. @default 15552000 (180 days) */
+        maxAge?: number;
+        includeSubDomains?: boolean;
+        preload?: boolean;
+    };
+    /**
+     * Override the Content-Security-Policy header. Pass `false` to omit.
+     * @default "default-src 'none'; frame-ancestors 'none'"
+     */
+    contentSecurityPolicy?: string | false;
+    /**
+     * Override X-Frame-Options. @default 'DENY'
+     */
+    frameOptions?: 'DENY' | 'SAMEORIGIN' | false;
+    /**
+     * Override Referrer-Policy. @default 'no-referrer'
+     */
+    referrerPolicy?: string | false;
+    /**
+     * Override Permissions-Policy. Pass `false` to omit.
+     * @default 'geolocation=(), camera=(), microphone=(), payment=()'
+     */
+    permissionsPolicy?: string | false;
+    /**
+     * Override Cross-Origin-Resource-Policy. @default 'same-origin'
+     */
+    corp?: 'same-origin' | 'same-site' | 'cross-origin' | false;
+    /**
+     * Free-form extra headers merged last.
+     */
+    extra?: Record<string, string>;
+}
+/**
+ * Build a header map ready to be `Object.assign`'d into a response.
+ * Idempotent and synchronous — safe to call per-request.
+ */
+declare function buildSecurityHeaders(opts?: SecurityHeadersOptions): Record<string, string>;
+
+/**
+ * In-memory token-bucket rate limiter.
+ *
+ * Designed to be adapter-agnostic — the dispatcher calls `consume(key)`
+ * with a request fingerprint (IP, IP+route bucket, or user id) and
+ * short-circuits with 429 if the bucket is empty.
+ *
+ * For production multi-instance deploys, swap the in-memory store via
+ * `RateLimitStore`. The shape is intentionally narrow so a Redis-backed
+ * implementation is straightforward.
+ */
+interface RateLimitDecision {
+    allowed: boolean;
+    /** Remaining tokens in the bucket after this consume. */
+    remaining: number;
+    /** Wall-clock ms until next token is available (when not allowed). */
+    retryAfterMs: number;
+    /** UNIX ms when the limit window resets. */
+    resetAt: number;
+}
+interface RateLimitBucketConfig {
+    /** Max tokens (bucket capacity). */
+    capacity: number;
+    /** Tokens added per second. */
+    refillPerSec: number;
+    /** Optional cost override for the consume operation. @default 1 */
+    defaultCost?: number;
+}
+interface BucketState {
+    tokens: number;
+    /** Last refill timestamp (ms). */
+    lastRefill: number;
+}
+/**
+ * Storage interface — swap for Redis/Memcached in clustered deploys.
+ * Implementations MUST be safe under concurrent access.
+ */
+interface RateLimitStore {
+    get(key: string): BucketState | undefined;
+    set(key: string, state: BucketState): void;
+    /** Cleanup hint — implementations may evict idle entries. */
+    prune?(olderThanMs: number): void;
+}
+declare class RateLimiter {
+    private config;
+    private store;
+    private now;
+    constructor(config: RateLimitBucketConfig, opts?: {
+        store?: RateLimitStore;
+        now?: () => number;
+    });
+    /**
+     * Attempt to consume `cost` tokens for `key`. Returns a decision
+     * describing whether the request should proceed and, if not, how
+     * long the caller should wait before retrying.
+     */
+    consume(key: string, cost?: number): RateLimitDecision;
+    /** Force-reset a key (e.g. after a successful auth flow). */
+    reset(key: string): void;
+}
+/**
+ * Curated default buckets for the three traffic classes ObjectStack
+ * dispatches. Conservative — tune via `DispatcherPluginConfig.rateLimit`
+ * for your deployment.
+ *
+ *   - auth: 10 req / minute / IP — guards /auth/* against credential
+ *     stuffing and password-spray.
+ *   - write: 60 req / minute / IP — POST/PUT/PATCH/DELETE.
+ *   - read:  600 req / minute / IP — GET, including discovery and
+ *     metadata.
+ *
+ * "Per-IP" is just the suggested key shape; the dispatcher constructs
+ * the key from `${ip}:${bucket}` so a single noisy IP can saturate
+ * one bucket without blocking the others.
+ */
+interface RateLimitDefaults {
+    auth: RateLimitBucketConfig;
+    write: RateLimitBucketConfig;
+    read: RateLimitBucketConfig;
+}
+declare const DEFAULT_RATE_LIMITS: RateLimitDefaults;
+
+/**
+ * Extract a request id from incoming headers, validating shape. If
+ * the header is missing or malformed, returns `undefined` and the
+ * caller should mint one via {@link generateRequestId}.
+ *
+ * Header lookup is case-insensitive — adapters normalize differently.
+ */
+declare function extractRequestId(headers: unknown): string | undefined;
+/**
+ * Mint a fresh request id. Uses `crypto.randomUUID()` when available
+ * (Node 16+, modern browsers, edge runtimes); falls back to a
+ * timestamp+random suffix otherwise so the function is universally
+ * callable.
+ *
+ * Format is `req_<hex>`; the prefix makes it obvious in logs that the
+ * id was minted by this layer (vs. propagated from a client).
+ */
+declare function generateRequestId(): string;
+/**
+ * Return the incoming request id if valid, otherwise mint one.
+ */
+declare function resolveRequestId(headers: unknown, generate?: () => string): string;
+/**
+ * Parsed W3C Trace Context. `sampled` reflects the lowest flag bit.
+ */
+interface TraceContext {
+    traceId: string;
+    spanId: string;
+    sampled: boolean;
+}
+/**
+ * Parse a `traceparent` header value into its W3C fields. Returns
+ * `undefined` for malformed input, the all-zero trace/span ids
+ * (spec-mandated invalid), or unknown versions.
+ */
+declare function parseTraceparent(value: unknown): TraceContext | undefined;
+/**
+ * Build the response header equivalent so downstream services
+ * continue the trace.
+ */
+declare function formatTraceparent(ctx: TraceContext): string;
+
+/**
+ * Metrics registry contract.
+ *
+ * The runtime emits metrics via this interface so the host application
+ * can plug in whatever metrics backend it wants (Prometheus via
+ * `prom-client`, OTel via `@opentelemetry/api-metrics`, StatsD,
+ * CloudWatch, etc.) without the framework taking a hard dep on any of
+ * them.
+ *
+ * Naming follows Prometheus conventions:
+ *   - snake_case names
+ *   - unit suffix (`_ms`, `_seconds`, `_bytes`, `_total` for counters)
+ *
+ * Labels are arbitrary string maps; backends should map them to their
+ * native label/tag concept. Keep cardinality low — never label by raw
+ * url path or user id.
+ *
+ * All methods are fire-and-forget; implementations MUST NOT throw on
+ * the hot path. Use {@link NoopMetricsRegistry} when metrics are
+ * disabled.
+ */
+interface MetricsRegistry {
+    /** Monotonic counter. `value` defaults to 1. */
+    counter(name: string, labels?: Record<string, string>, value?: number): void;
+    /** Histogram / timing in arbitrary units (typically ms). */
+    histogram(name: string, value: number, labels?: Record<string, string>): void;
+    /** Point-in-time gauge. */
+    gauge(name: string, value: number, labels?: Record<string, string>): void;
+}
+/**
+ * No-op metrics registry — the default. Discards every observation.
+ * Production deployments should swap this for a real registry; tests
+ * can use {@link InMemoryMetricsRegistry} to assert emissions.
+ */
+declare class NoopMetricsRegistry implements MetricsRegistry {
+    counter(): void;
+    histogram(): void;
+    gauge(): void;
+}
+/** Recorded metric sample (in-memory registry). */
+interface MetricSample {
+    name: string;
+    kind: 'counter' | 'histogram' | 'gauge';
+    value: number;
+    labels: Record<string, string>;
+    /** Wall-clock timestamp; useful for ordering assertions in tests. */
+    at: number;
+}
+/**
+ * In-memory registry used for tests and local inspection. Stores
+ * every observation in insertion order; query via the helpers below
+ * or read {@link samples} directly.
+ *
+ * Not intended for production — unbounded growth.
+ */
+declare class InMemoryMetricsRegistry implements MetricsRegistry {
+    readonly samples: MetricSample[];
+    counter(name: string, labels?: Record<string, string>, value?: number): void;
+    histogram(name: string, value: number, labels?: Record<string, string>): void;
+    gauge(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Sum of all counter increments matching `name` (and optionally a
+     * label subset). Useful in tests: `metrics.totalCounter('http_requests_total', { status: '500' })`.
+     */
+    totalCounter(name: string, labelMatch?: Record<string, string>): number;
+    /**
+     * All histogram observations matching `name` (and optionally a
+     * label subset), as raw values.
+     */
+    histogramValues(name: string, labelMatch?: Record<string, string>): number[];
+    /** Clear all recorded samples. */
+    reset(): void;
+}
+/**
+ * Canonical metric names emitted by the runtime. Hosts may rely on
+ * these (e.g., to wire alerts) so they are listed here for reference
+ * rather than being string literals scattered through call sites.
+ */
+declare const RUNTIME_METRICS: {
+    /** Counter, labels: method, route, status. */
+    readonly httpRequestsTotal: "http_requests_total";
+    /** Histogram (ms), labels: method, route. */
+    readonly httpRequestDurationMs: "http_request_duration_ms";
+    /** Counter, labels: method, route. Incremented when an in-flight handler throws (after the response is sent). */
+    readonly httpRequestErrorsTotal: "http_request_errors_total";
+};
+
+/**
+ * Error reporter contract.
+ *
+ * Production deployments wire this to Sentry, Datadog APM, Rollbar,
+ * etc. The runtime calls {@link ErrorReporter.captureException} when a
+ * route handler results in a 5xx response so the host's APM gets the
+ * stack trace without each plugin/route needing to import the SDK.
+ *
+ * Implementations MUST NOT throw — error reporting failures should be
+ * swallowed (or at most logged) so the original error reaches the
+ * client unmolested.
+ *
+ * 4xx responses are intentionally NOT captured here. Client errors
+ * (validation failures, auth, not-found) flood APM systems with noise
+ * and obscure real bugs. If a deployment wants to track them, do it
+ * via the metrics counter (`http_requests_total{status="4xx"}`),
+ * not error reporting.
+ */
+interface ErrorReporter {
+    /**
+     * Capture a thrown error with optional context. Context typically
+     * includes `requestId`, `method`, `route`, `userId`, `orgId`.
+     *
+     * The reporter is responsible for redacting sensitive fields from
+     * `context` (the runtime does not know what is sensitive in the
+     * caller's deployment).
+     */
+    captureException(error: unknown, context?: Record<string, unknown>): void;
+}
+/** No-op reporter — the default. */
+declare class NoopErrorReporter implements ErrorReporter {
+    captureException(): void;
+}
+/** Recorded report (in-memory reporter). */
+interface CapturedError {
+    error: unknown;
+    context: Record<string, unknown>;
+    at: number;
+}
+/**
+ * In-memory reporter used in tests to assert that error capture was
+ * (or was not) invoked for a given request.
+ */
+declare class InMemoryErrorReporter implements ErrorReporter {
+    readonly captured: CapturedError[];
+    captureException(error: unknown, context?: Record<string, unknown>): void;
+    reset(): void;
+}
+
 interface DispatcherPluginConfig {
     /**
      * API path prefix for all endpoints.
@@ -278,6 +657,46 @@ interface DispatcherPluginConfig {
      * where membership has not been seeded.
      */
     enforceProjectMembership?: boolean;
+    /**
+     * Security response headers. When provided, every response routed
+     * through this plugin gets the headers merged in (route-specific
+     * headers still win on conflict).
+     *
+     * Pass `false` to disable. Pass `true` (or omit) to enable with
+     * conservative API-server defaults (CSP=deny-all, XCTO=nosniff,
+     * X-Frame-Options=DENY, etc.). Pass an object to customize — see
+     * {@link SecurityHeadersOptions}.
+     *
+     * @default true
+     */
+    securityHeaders?: boolean | SecurityHeadersOptions;
+    /**
+     * Observability wiring. All fields optional; defaults are noop
+     * (zero overhead, no behavior change).
+     *
+     *   - `metrics`: registry receiving `http_requests_total`,
+     *     `http_request_duration_ms`, `http_request_errors_total` for
+     *     every route this plugin mounts. Plug in `prom-client` /
+     *     `@opentelemetry/api-metrics` / your own adapter.
+     *
+     *   - `errorReporter`: invoked on 5xx responses with the thrown
+     *     error and `{ requestId, method, route }`. Plug in Sentry /
+     *     Datadog / Rollbar.
+     *
+     *   - `generateRequestId`: customize the format of minted request
+     *     ids (default: `req_<uuid>` via `crypto.randomUUID`). The
+     *     incoming `X-Request-Id` header is honored when present and
+     *     well-formed, regardless of this setting.
+     *
+     *   - `requestIdHeader`: response header name to echo the id back
+     *     on. Defaults to `X-Request-Id`.
+     */
+    observability?: {
+        metrics?: MetricsRegistry;
+        errorReporter?: ErrorReporter;
+        generateRequestId?: () => string;
+        requestIdHeader?: string;
+    };
 }
 /**
  * Dispatcher Plugin
@@ -423,58 +842,6 @@ declare class HttpServer implements IHttpServer {
     getMiddlewares(): Middleware[];
 }
 
-/**
- * ProjectScopeManager
- *
- * Replaces KernelManager in shared-kernel mode. Instead of managing full
- * ObjectKernel instances per project, it manages TTL/LRU eviction of
- * SCOPED service instances inside a single shared kernel.
- *
- * The kernel's PluginLoader already stores scoped instances in:
- *   scopedServices: Map<scopeId, Map<serviceName, instance>>
- *
- * This class tracks last-access timestamps and calls kernel.clearScope()
- * to release driver connections and metadata caches for idle projects.
- */
-
-interface ProjectScopeManagerConfig {
-    /** Shared kernel whose scoped services this manager evicts. */
-    kernel: ObjectKernel;
-    /** Idle TTL in ms. Scopes not accessed within this window are evicted. Default: 15 min. */
-    ttlMs?: number;
-    /** Max number of active scopes. LRU eviction when exceeded. Default: 200. */
-    maxSize?: number;
-    /** Eviction check interval in ms. Default: 5 min. */
-    checkIntervalMs?: number;
-}
-declare class ProjectScopeManager {
-    private readonly kernel;
-    private readonly ttlMs;
-    private readonly maxSize;
-    private readonly lastAccess;
-    private timer?;
-    constructor(config: ProjectScopeManagerConfig);
-    /**
-     * Touch a scope to reset its idle TTL. Call this on every request.
-     */
-    touch(scopeId: string): void;
-    /**
-     * Evict all scopes not accessed within ttlMs.
-     */
-    evictIdle(): void;
-    /**
-     * Evict a specific scope immediately.
-     */
-    evict(scopeId: string): void;
-    /**
-     * Evict all scopes (e.g. on shutdown).
-     */
-    evictAll(): void;
-    destroy(): void;
-    get activeCount(): number;
-    private evictLRU;
-}
-
 /**
  * Factory contract for instantiating a per-project {@link ObjectKernel}.
  *
@@ -543,6 +910,10 @@ declare class KernelManager {
     private enforceMaxSize;
 }
 
+/** Minimal local interface — full ProjectScopeManager was removed in Phase R. */
+interface ProjectScopeManager {
+    touch(projectId: string): void;
+}
 interface HttpProtocolContext {
     request: any;
     response?: any;
@@ -1037,6 +1408,12 @@ declare class HttpDispatcher {
      * Physical database addressing (database_url, database_driver, etc.)
      * is stored directly on the sys_project row.
      */
+    /**
+     * Resolve the calling user id from the request session, if any.
+     * Returns `undefined` for anonymous calls or when auth is not wired up.
+     */
+    private resolveActiveOrganizationId;
+    private resolveCallerUserId;
     handleCloud(path: string, method: string, body: any, query: any, _context: HttpProtocolContext): Promise<HttpDispatcherResult>;
     /**
      * Cascade-delete a project: cred / member / package_installation rows,
@@ -1254,6 +1631,506 @@ 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}
+ *     → { projectId: string, organizationId?: string, runtime?: ProjectRuntimeConfig }
+ *
+ *   GET {controlPlaneUrl}/api/v1/cloud/projects/:projectId/artifact
+ *     → ProjectArtifactResponse  (ProjectArtifact + 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 ProjectRuntimeConfig {
+    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 {
+    projectId: string;
+    organizationId?: string;
+    /** Optional runtime config — when present, callers can skip the artifact fetch's runtime block. */
+    runtime?: ProjectRuntimeConfig;
+}
+/**
+ * Artifact response wrapping the spec's `ProjectArtifact` envelope plus
+ * an optional `runtime` block carrying the project's database
+ * connection details.
+ */
+interface ProjectArtifactResponse extends ProjectArtifact {
+    runtime?: ProjectRuntimeConfig;
+}
+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(projectId: string, opts?: {
+        commit?: string;
+    }): Promise<ProjectArtifactResponse | null>;
+    /**
+     * Resolve an 8-hex project short id (first 8 hex chars of the UUID,
+     * dashes stripped) to the full projectId. 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<{
+        projectId: 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/projects/:id/branches` endpoint.
+     */
+    fetchBranchHead(projectId: string, branchName: string): Promise<{
+        commitId: string;
+        publishedAt?: string | null;
+    } | null>;
+    /** Drop cached entries for a project (and any matching hostname). */
+    invalidate(projectId: 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_PROJECT_ID` or `'proj_local'`.
+     */
+    projectId?: 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/<projectId>.db`.
+     */
+    runtime?: ProjectRuntimeConfig;
+    /**
+     * 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 projectId;
+    private readonly organizationId;
+    private readonly overrideRuntime?;
+    private readonly watch;
+    private readonly logger;
+    private cached?;
+    constructor(config?: FileArtifactApiClientConfig);
+    resolveHostname(_host: string): Promise<ResolvedHostname | null>;
+    fetchArtifact(_projectId: string, _opts?: {
+        commit?: string;
+    }): Promise<ProjectArtifactResponse | null>;
+    lookupProjectByShortId(_shortId: string): Promise<{
+        projectId: string;
+        organizationId?: string;
+    } | null>;
+    fetchBranchHead(_projectId: string, _branchName: string): Promise<{
+        commitId: string;
+        publishedAt?: string | null;
+    } | null>;
+    invalidate(_projectId: string): void;
+    clear(): void;
+    private loadArtifact;
+    private readRuntimeFromArtifact;
+    private deriveRuntimeFromMetadata;
+    private defaultLocalSqliteRuntime;
+}
+
+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;
+}
+interface ObjectOSStackResult {
+    plugins: any[];
+    api: {
+        enableProjectScoping: true;
+        projectResolution: 'auto';
+        requireAuth: true;
+    };
+}
+declare function createObjectOSStack(config: ObjectOSStackConfig): Promise<ObjectOSStackResult>;
+
+/**
+ * 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 was extracted from `@objectstack/service-cloud` in Phase R
+ * 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<{
+        projectId: string;
+        driver: IDataDriver$1;
+    } | null>;
+    /** Resolve a project's driver by ID. Returns `null` when unknown. */
+    resolveById(projectId: 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(projectId: string): {
+        projectId: string;
+        driver: IDataDriver$1;
+        project: any;
+    } | null;
+    /** Drop cached entries for the given project. */
+    invalidate(projectId: 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 →
+ * projectId 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_project` 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<{
+        projectId: string;
+        driver: IDataDriver;
+    } | null>;
+    resolveById(projectId: string): Promise<IDataDriver | null>;
+    peekById(projectId: string): {
+        projectId: string;
+        driver: IDataDriver;
+        project: any;
+    } | null;
+    invalidate(projectId: 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, projectId). Falls back to
+     * `process.env.OS_AUTH_SECRET` / `AUTH_SECRET` at construction time.
+     */
+    authBaseSecret?: string;
+}
+declare class ArtifactKernelFactory implements ProjectKernelFactory {
+    private readonly client;
+    private readonly envRegistry;
+    private readonly logger;
+    private readonly kernelConfig?;
+    private readonly authBaseSecret;
+    constructor(config: ArtifactKernelFactoryConfig);
+    create(projectId: 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(projectId: string): string;
+/**
+ * Derive the per-project OAuth client_secret deterministically from the
+ * shared master secret. HMAC-SHA256(baseSecret, 'oauth-client:' + projectId)
+ * 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, projectId: 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). */
+    projectId: string;
+    /**
+     * Project hostname (e.g. `acme-crm.objectos.app`). 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 `projectId` 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_project` 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<{
+        projectId: string;
+        error: string;
+    }>;
+}>;
+
 /**
  * # Hook & Action Body Sandbox
  *
@@ -1484,4 +2361,4 @@ declare function actionBodyRunnerFactory(runner: ScriptRunner, opts: FactoryOpti
     timeoutMs?: number;
 }) => ((actionCtx: any) => Promise<unknown>) | undefined;
 
-export { AppPlugin, type DispatcherPluginConfig, DriverPlugin, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, type LoadArtifactBundleOptions, MiddlewareManager, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, Runtime, type RuntimeConfig, SYSTEM_PROJECT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, SeedLoaderService, type StandaloneStackConfig, type StandaloneStackResult, type SystemProjectPluginConfig, UnimplementedScriptRunner, actionBodyRunnerFactory, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDispatcherPlugin, createStandaloneStack, createSystemProjectPlugin, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, readArtifactSource };
+export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, type CapturedError, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentDriverRegistry, type ErrorReporter, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, InMemoryErrorReporter, InMemoryMetricsRegistry, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, type MetricSample, type MetricsRegistry, MiddlewareManager, NoopErrorReporter, NoopMetricsRegistry, type ObjectOSStackConfig, type ObjectOSStackResult, PLATFORM_SSO_PROVIDER_ID, type ProjectArtifactResponse, type ProjectKernelFactory, type ProjectRuntimeConfig, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, RUNTIME_METRICS, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, SYSTEM_PROJECT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemProjectPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemProjectPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveDefaultArtifactPath, resolveRequestId, seedPlatformSsoClient };