@objectstack/runtime 5.1.0 → 6.0.0

package/dist/index.d.ts

@@ -1,15 +1,16 @@
 import { ObjectKernel, IHttpServer, ObjectKernelConfig, Plugin, PluginContext, RouteHandler, Middleware } from '@objectstack/core';
 export * from '@objectstack/core';
 export { ObjectKernel } from '@objectstack/core';
+import { ClusterServicePluginOptions } from '@objectstack/service-cluster';
+import { ClusterCapabilityConfigInput, ExecutionContext } from '@objectstack/spec/kernel';
 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 { MetricsRegistry, ErrorReporter } from '@objectstack/observability';
-export { CapturedError, ErrorReporter, InMemoryErrorReporter, InMemoryMetricsRegistry, MetricSample, MetricsRegistry, NoopErrorReporter, NoopMetricsRegistry, RUNTIME_METRICS } from '@objectstack/observability';
-import { ExecutionContext } from '@objectstack/spec/kernel';
+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 { ProjectArtifact } from '@objectstack/spec/cloud';
+import { EnvironmentArtifact } from '@objectstack/spec/cloud';
 export { RestApiPluginConfig, RestServer, RouteEntry, RouteGroupBuilder, RouteManager, createRestApiPlugin } from '@objectstack/rest';
 
 interface RuntimeConfig {
@@ -23,6 +24,18 @@ interface RuntimeConfig {
      * Kernel Configuration
      */
     kernel?: ObjectKernelConfig;
+    /**
+     * Cluster service configuration.
+     *
+     * - Omit (default): a single-node `memory` cluster is auto-registered.
+     * - `false`: skip auto-registration entirely. Register your own
+     *   `ClusterServicePlugin` if you need it later.
+     * - `ClusterCapabilityConfigInput`: forwarded to `defineCluster()`.
+     * - `{ cluster: IClusterService }`: bring your own instance.
+     *
+     * See `content/docs/concepts/cluster-semantics.mdx` for driver options.
+     */
+    cluster?: false | ClusterCapabilityConfigInput | ClusterServicePluginOptions;
 }
 /**
  * ObjectStack Runtime
@@ -41,6 +54,7 @@ interface RuntimeConfig {
 declare class Runtime {
     readonly kernel: ObjectKernel;
     constructor(config?: RuntimeConfig);
+    private normalizeClusterOptions;
     /**
      * Register a plugin
      */
@@ -61,13 +75,14 @@ declare const StandaloneStackConfigSchema: z.ZodObject<{
     databaseUrl: z.ZodOptional<z.ZodString>;
     databaseAuthToken: z.ZodOptional<z.ZodString>;
     databaseDriver: z.ZodOptional<z.ZodEnum<{
-        sqlite: "sqlite";
-        turso: "turso";
         memory: "memory";
         postgres: "postgres";
+        sqlite: "sqlite";
+        "sqlite-wasm": "sqlite-wasm";
+        turso: "turso";
         mongodb: "mongodb";
     }>>;
-    projectId: z.ZodOptional<z.ZodString>;
+    environmentId: z.ZodOptional<z.ZodString>;
     artifactPath: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type StandaloneStackConfig = z.input<typeof StandaloneStackConfigSchema>;
@@ -171,7 +186,7 @@ declare class DriverPlugin implements Plugin {
  * usages may omit this — no catalog hooks are emitted in that case.
  */
 interface AppPluginProjectContext {
-    projectId: string;
+    environmentId: string;
     organizationId: string;
     projectName?: string;
     /** When the app comes from a package installation, the source package id. */
@@ -492,6 +507,75 @@ declare function parseTraceparent(value: unknown): TraceContext | undefined;
  */
 declare function formatTraceparent(ctx: TraceContext): string;
 
+/**
+ * Options for {@link ObservabilityServicePlugin}.
+ *
+ * Either or both backends can be omitted; the omitted one resolves to
+ * the corresponding no-op exporter so consumers can always rely on the
+ * service being present.
+ */
+interface ObservabilityServicePluginOptions {
+    /** Metrics backend (e.g. `ConsoleMetricsRegistry`, `OtlpHttpMetricsRegistry`). */
+    metrics?: MetricsRegistry;
+    /** Error reporter backend (e.g. Sentry adapter). */
+    errors?: ErrorReporter;
+}
+/**
+ * `ObservabilityServicePlugin` — registers the host's
+ * {@link MetricsRegistry} and {@link ErrorReporter} in the kernel
+ * service registry under the canonical names so any other plugin can
+ * look them up without each host having to thread observability config
+ * through every plugin constructor.
+ *
+ * Resolution chain other plugins should follow:
+ *
+ *   1. Explicit option on the plugin's own options object (escape
+ *      hatch for tests / explicit wiring).
+ *   2. `ctx.getService(OBSERVABILITY_METRICS_SERVICE)`.
+ *   3. `NoopMetricsRegistry()` — never null.
+ *
+ * Register this plugin **before** any plugin that wants to consume the
+ * services (cache, storage, dispatcher), otherwise the consumer's
+ * `init` will fall through to the no-op default.
+ *
+ * @example
+ * ```ts
+ * import { ObjectKernel } from '@objectstack/core';
+ * import {
+ *   ObservabilityServicePlugin,
+ *   CacheServicePlugin,
+ * } from '@objectstack/runtime';
+ * import { ConsoleMetricsRegistry } from '@objectstack/observability';
+ *
+ * const kernel = new ObjectKernel();
+ * kernel.use(new ObservabilityServicePlugin({
+ *   metrics: new ConsoleMetricsRegistry(),
+ * }));
+ * kernel.use(new CacheServicePlugin()); // picks metrics up automatically
+ * ```
+ */
+declare class ObservabilityServicePlugin implements Plugin {
+    name: string;
+    version: string;
+    type: string;
+    private readonly options;
+    constructor(options?: ObservabilityServicePluginOptions);
+    init(ctx: PluginContext): Promise<void>;
+}
+/**
+ * Helper used by consumer plugins to resolve a metrics backend with
+ * the canonical fallback chain. Never throws; always returns a usable
+ * `MetricsRegistry`.
+ *
+ * @param ctx        the consuming plugin's `PluginContext`
+ * @param override   explicit option set on the consuming plugin (wins)
+ */
+declare function resolveMetrics(ctx: PluginContext, override?: MetricsRegistry): MetricsRegistry;
+/**
+ * Sibling of {@link resolveMetrics} for {@link ErrorReporter}.
+ */
+declare function resolveErrorReporter(ctx: PluginContext, override?: ErrorReporter): ErrorReporter;
+
 interface DispatcherPluginConfig {
     /**
      * API path prefix for all endpoints.
@@ -504,16 +588,16 @@ interface DispatcherPluginConfig {
      * routes stay in lockstep with /data and /meta.
      *
      * When `enableProjectScoping` is true and `projectResolution` is:
-     *   - `required` — only `/projects/:projectId/...` variants are registered.
+     *   - `required` — only `/environments/:environmentId/...` variants are registered.
      *   - `optional` / `auto` — both unscoped and scoped variants are registered
-     *     (the scoped handler forwards `req.params.projectId` into context).
+     *     (the scoped handler forwards `req.params.environmentId` into context).
      */
     scoping?: {
         enableProjectScoping?: boolean;
         projectResolution?: 'required' | 'optional' | 'auto';
     };
     /**
-     * Enforce per-project membership (`sys_project_member`) on scoped
+     * Enforce per-project membership (`sys_environment_member`) on scoped
      * data-plane routes. Returns 403 for non-members unless they are
      * staff (platform org) or the project is the well-known system
      * project.
@@ -588,10 +672,10 @@ declare function createDispatcherPlugin(config?: DispatcherPluginConfig): Plugin
 
 /**
  * The well-known UUID for the built-in system project.
- * Kept in lockstep with `ProjectProvisioningService.provisionSystemProject`.
+ * Kept in lockstep with `ProjectProvisioningService.provisionSystemEnvironment`.
  */
-declare const SYSTEM_PROJECT_ID = "00000000-0000-0000-0000-000000000001";
-interface SystemProjectPluginConfig {
+declare const SYSTEM_ENVIRONMENT_ID = "00000000-0000-0000-0000-000000000001";
+interface SystemEnvironmentPluginConfig {
     /**
      * Service name that resolves to a `ProjectProvisioningService`-shaped
      * object. Defaults to `tenant.provisioning` (convention used by
@@ -609,8 +693,8 @@ interface SystemProjectPluginConfig {
  * System Project Bootstrap Plugin
  *
  * Ensures the built-in system project (well-known UUID
- * {@link SYSTEM_PROJECT_ID}) exists on the control plane the first time the
- * runtime starts. Calls are idempotent — `provisionSystemProject()` returns
+ * {@link SYSTEM_ENVIRONMENT_ID}) exists on the control plane the first time the
+ * runtime starts. Calls are idempotent — `provisionSystemEnvironment()` returns
  * the existing row when the project has already been created.
  *
  * Register AFTER the tenant service is available so the provisioning service
@@ -619,10 +703,10 @@ interface SystemProjectPluginConfig {
  * @example
  * ```ts
  * kernel.use(tenantPlugin);
- * kernel.use(createSystemProjectPlugin());
+ * kernel.use(createSystemEnvironmentPlugin());
  * ```
  */
-declare function createSystemProjectPlugin(config?: SystemProjectPluginConfig): Plugin;
+declare function createSystemEnvironmentPlugin(config?: SystemEnvironmentPluginConfig): Plugin;
 
 /**
  * HttpServer - Unified HTTP Server Abstraction
@@ -711,16 +795,16 @@ declare class HttpServer implements IHttpServer {
 /**
  * Factory contract for instantiating a per-project {@link ObjectKernel}.
  *
- * Given a `projectId`, the factory is expected to:
- * 1. Read control-plane metadata (`sys_project` + credentials + subscribed packages).
+ * 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.
  */
-interface ProjectKernelFactory {
-    create(projectId: string): Promise<ObjectKernel>;
+interface EnvironmentKernelFactory {
+    create(environmentId: string): Promise<ObjectKernel>;
 }
 interface KernelManagerConfig {
-    factory: ProjectKernelFactory;
+    factory: EnvironmentKernelFactory;
     /** Maximum number of kernels to keep resident. Defaults to 32. */
     maxSize?: number;
     /**
@@ -743,7 +827,7 @@ interface KernelManagerConfig {
  * 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 projectId share a single in-flight
+ * `getOrCreate()` calls for the same environmentId share a single in-flight
  * factory invocation (singleflight).
  */
 declare class KernelManager {
@@ -754,36 +838,36 @@ declare class KernelManager {
     private readonly cache;
     private readonly pending;
     constructor(config: KernelManagerConfig);
-    /** Returns the currently cached projectIds (ordered by insertion). */
+    /** Returns the currently cached environmentIds (ordered by insertion). */
     keys(): string[];
     /** Cache size for diagnostics. */
     get size(): number;
     /**
-     * Resolve or construct the kernel for `projectId`.
+     * 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`.
      */
-    getOrCreate(projectId: string): Promise<ObjectKernel>;
+    getOrCreate(environmentId: string): Promise<ObjectKernel>;
     /**
-     * Evict the kernel for `projectId` and invoke `kernel.shutdown()`.
+     * Evict the kernel for `environmentId` and invoke `kernel.shutdown()`.
      * No-op when the entry is absent.
      */
-    evict(projectId: string): Promise<void>;
+    evict(environmentId: string): Promise<void>;
     /** Evict all resident kernels. Used on runtime shutdown. */
     evictAll(): Promise<void>;
     private enforceMaxSize;
 }
 
-/** Minimal local interface — full ProjectScopeManager was removed in Phase R. */
-interface ProjectScopeManager {
-    touch(projectId: string): void;
+/** Minimal local interface — full EnvironmentScopeManager was removed in Phase R. */
+interface EnvironmentScopeManager {
+    touch(environmentId: string): void;
 }
 interface HttpProtocolContext {
     request: any;
     response?: any;
-    projectId?: string;
+    environmentId?: string;
     dataDriver?: any;
     /**
      * Identity envelope resolved by `resolveExecutionContext` and threaded
@@ -810,17 +894,17 @@ interface HttpDispatcherOptions {
     enforceProjectMembership?: boolean;
     /**
      * Optional {@link KernelManager}. When present, the dispatcher resolves
-     * `context.projectId` first and then routes the request against the
-     * project's dedicated kernel via `kernelManager.getOrCreate(projectId)`.
-     * Requests that fail to resolve a projectId fall through to the
+     * `context.environmentId` first and then routes the request against the
+     * project's dedicated kernel via `kernelManager.getOrCreate(environmentId)`.
+     * Requests that fail to resolve a environmentId fall through to the
      * constructor-supplied kernel (self-hosted / legacy behavior).
      */
     kernelManager?: KernelManager;
     /**
-     * Optional {@link ProjectScopeManager}. When present, `touch(projectId)` is
+     * Optional {@link EnvironmentScopeManager}. When present, `touch(environmentId)` is
      * called on every scoped request so idle projects are evicted after TTL.
      */
-    scopeManager?: ProjectScopeManager;
+    scopeManager?: EnvironmentScopeManager;
 }
 /**
  * @deprecated Use `createDispatcherPlugin()` from `@objectstack/runtime` instead.
@@ -839,22 +923,22 @@ declare class HttpDispatcher {
     private scopeManager?;
     /**
      * When `true`, scoped data-plane routes enforce a
-     * `sys_project_member` lookup and return 403 for non-members.
-     * Defaults to `true` when a projectId is resolvable — legacy callers
+     * `sys_environment_member` lookup and return 403 for non-members.
+     * Defaults to `true` when a environmentId is resolvable — legacy callers
      * can opt out via the third constructor argument (see
      * `DispatcherConfig.enforceProjectMembership`).
      */
     private enforceMembership;
     /**
      * In-memory cache of positive membership checks, keyed by
-     * `${projectId}:${userId}`. Entries expire 60 seconds after insertion
+     * `${environmentId}:${userId}`. Entries expire 60 seconds after insertion
      * — a short TTL is acceptable because a user whose access was just
      * revoked sees stale access for at most one minute.
      */
     private membershipCache;
     private static readonly MEMBERSHIP_CACHE_TTL_MS;
     /** Well-known system project id — bypassed for any authenticated user. */
-    private static readonly SYSTEM_PROJECT_ID;
+    private static readonly SYSTEM_ENVIRONMENT_ID;
     /** Well-known platform org id — members bypass project membership. */
     private static readonly PLATFORM_ORG_ID;
     constructor(kernel: ObjectKernel, envRegistry?: any, options?: HttpDispatcherOptions);
@@ -875,22 +959,27 @@ declare class HttpDispatcher {
     private callData;
     /**
      * Parse a project UUID out of a scoped URL path such as
-     * `/api/v1/projects/abc-123/data/task` or `/projects/abc-123/meta`.
+     * `/api/v1/environments/abc-123/data/task` or `/projects/abc-123/meta`.
+     * Returns `undefined` when the path does not match the scoped pattern.
+     */
+    /**
+     * Parse an environment UUID out of a scoped URL path such as
+     * `/api/v1/environments/abc-123/data/task` or `/environments/abc-123/meta`.
      * Returns `undefined` when the path does not match the scoped pattern.
      */
-    private extractProjectIdFromPath;
+    private extractEnvironmentIdFromPath;
     /**
      * Resolve environment context for incoming request.
      *
      * Precedence:
-     * 0. URL path matches `/projects/:projectId/...` OR request.params.projectId set by router
+     * 0. URL path matches `/environments/:environmentId/...` OR request.params.environmentId set by router
      *    → envRegistry.resolveById(id)
      * 1. request.headers.host → envRegistry.resolveByHostname(host)
-     * 2. request.headers['x-project-id'] → envRegistry.resolveById(id)
+     * 2. request.headers['x-environment-id'] → envRegistry.resolveById(id)
      * 3. session.activeEnvironmentId → envRegistry.resolveById(id)
      * 4. session.activeOrganizationId → find default project → envRegistry.resolveById(id)
-     * 5. single-project default (registered by `createSingleProjectPlugin`)
-     *    → envRegistry.resolveById(defaultProject.projectId). Lets bare
+     * 5. single-environment default (registered by `createSingleEnvironmentPlugin`)
+     *    → envRegistry.resolveById(defaultProject.environmentId). Lets bare
      *    `/api/v1/data/...` URLs resolve to the lone project in
      *    `cloudUrl: 'local'` deployments.
      *
@@ -900,13 +989,13 @@ declare class HttpDispatcher {
     private resolveEnvironmentContext;
     /**
      * Check whether the authenticated user is a member of
-     * `context.projectId`. Runs after {@link resolveEnvironmentContext}
+     * `context.environmentId`. Runs after {@link resolveEnvironmentContext}
      * and is a no-op when:
      *
      *   - Membership enforcement is disabled via the constructor.
      *   - The route is control-plane (`/auth/*`, `/cloud/*`, `/health`,
      *     `/discovery`) — already skipped upstream.
-     *   - No `projectId` was resolved (e.g. unscoped legacy routes).
+     *   - No `environmentId` was resolved (e.g. unscoped legacy routes).
      *   - The project is the well-known system project (bypassed so any
      *     authenticated user can read platform metadata).
      *   - The user's active organization is the platform org (staff).
@@ -1240,23 +1329,23 @@ declare class HttpDispatcher {
      * Cloud / Environment Control-Plane routes.
      *
      *  - GET    /cloud/drivers                                 → list registered ObjectQL drivers (for env provisioning)
-     *  - GET    /cloud/projects                            → list
-     *  - POST   /cloud/projects                            → provision (driver: memory | turso | <any registered driver>)
-     *  - GET    /cloud/projects/:id                        → detail (+ db, credential, membership)
-     *  - PATCH  /cloud/projects/:id                        → update displayName / plan / status / isDefault / metadata
-     *  - DELETE /cloud/projects/:id[?force=1]              → cascade-delete the project (cred/member/package install rows + physical DB)
+     *  - GET    /cloud/environments                            → list
+     *  - POST   /cloud/environments                            → provision (driver: memory | turso | <any registered driver>)
+     *  - GET    /cloud/environments/:id                        → detail (+ db, credential, membership)
+     *  - PATCH  /cloud/environments/:id                        → update displayName / plan / status / isDefault / metadata
+     *  - DELETE /cloud/environments/:id[?force=1]              → cascade-delete the project (cred/member/package install rows + physical DB)
      *  - DELETE /cloud/organizations/:id                   → cascade-delete every project (and its DB) for the org, then drop the org
-     *  - POST   /cloud/projects/:id/retry                  → re-run provisioning for a failed environment
-     *  - POST   /cloud/projects/:id/activate               → mark as active for session (stub)
-     *  - POST   /cloud/projects/:id/credentials/rotate     → rotate credential
-     *  - GET    /cloud/projects/:id/members                → list members
-     *  - GET    /cloud/projects/:id/packages               → list installed packages
-     *  - POST   /cloud/projects/:id/packages               → install package into env
-     *  - GET    /cloud/projects/:id/packages/:pkgId        → get installation detail
-     *  - PATCH  /cloud/projects/:id/packages/:pkgId/enable  → enable package
-     *  - PATCH  /cloud/projects/:id/packages/:pkgId/disable → disable package
-     *  - DELETE /cloud/projects/:id/packages/:pkgId        → uninstall (scope=platform forbidden)
-     *  - POST   /cloud/projects/:id/packages/:pkgId/upgrade → upgrade to newer version
+     *  - POST   /cloud/environments/:id/retry                  → re-run provisioning for a failed environment
+     *  - POST   /cloud/environments/:id/activate               → mark as active for session (stub)
+     *  - POST   /cloud/environments/:id/credentials/rotate     → rotate credential
+     *  - GET    /cloud/environments/:id/members                → list members
+     *  - GET    /cloud/environments/:id/packages               → list installed packages
+     *  - POST   /cloud/environments/:id/packages               → install package into env
+     *  - GET    /cloud/environments/:id/packages/:pkgId        → get installation detail
+     *  - PATCH  /cloud/environments/:id/packages/:pkgId/enable  → enable package
+     *  - PATCH  /cloud/environments/:id/packages/:pkgId/disable → disable package
+     *  - DELETE /cloud/environments/:id/packages/:pkgId        → uninstall (scope=platform forbidden)
+     *  - POST   /cloud/environments/:id/packages/:pkgId/upgrade → upgrade to newer version
      *
      * Driver binding
      * --------------
@@ -1268,11 +1357,11 @@ declare class HttpDispatcher {
      * If `driver` is omitted, the dispatcher auto-selects the first available
      * in preference order: turso → memory → any other registered driver.
      *
-     * Backed by ObjectQL sys_project / sys_project_credential /
-     * sys_project_member tables (registered by
+     * Backed by ObjectQL sys_environment / sys_environment_credential /
+     * sys_environment_member tables (registered by
      * `@objectstack/service-tenant`'s `createTenantPlugin`).
      * Physical database addressing (database_url, database_driver, etc.)
-     * is stored directly on the sys_project row.
+     * is stored directly on the sys_environment row.
      */
     /**
      * Resolve the calling user id from the request session, if any.
@@ -1284,7 +1373,7 @@ declare class HttpDispatcher {
     /**
      * Cascade-delete a project: cred / member / package_installation rows,
      * then the physical database via the provisioning adapter, then the
-     * `sys_project` row itself. Used by both `DELETE /cloud/projects/:id`
+     * `sys_environment` row itself. Used by both `DELETE /cloud/environments/:id`
      * and the org-cascade in `DELETE /cloud/organizations/:id`.
      *
      * Idempotent and best-effort: missing rows / unreachable adapters
@@ -1507,10 +1596,10 @@ declare function mergeRuntimeModule(bundle: any, artifactAbsPath: string, tag?:
  * The control plane is expected to expose two endpoints:
  *
  *   GET {controlPlaneUrl}/api/v1/cloud/resolve-hostname?host={hostname}
- *     → { projectId: string, organizationId?: string, runtime?: ProjectRuntimeConfig }
+ *     → { environmentId: string, organizationId?: string, runtime?: EnvironmentRuntimeConfig }
  *
- *   GET {controlPlaneUrl}/api/v1/cloud/projects/:projectId/artifact
- *     → ProjectArtifactResponse  (ProjectArtifact + optional `runtime` block)
+ *   GET {controlPlaneUrl}/api/v1/cloud/environments/:environmentId/artifact
+ *     → EnvironmentArtifactResponse  (EnvironmentArtifact + optional `runtime` block)
  *
  * Both endpoints accept an optional `Authorization: Bearer <apiKey>`.
  *
@@ -1525,7 +1614,7 @@ declare function mergeRuntimeModule(bundle: any, artifactAbsPath: string, tag?:
  * connect to (this is *not* part of the developer-authored compiled
  * artifact — the control plane mints it when serving the API).
  */
-interface ProjectRuntimeConfig {
+interface EnvironmentRuntimeConfig {
     organizationId?: string;
     hostname?: string;
     /** Driver type — e.g. `sqlite`, `postgres`, `turso`, `memory`. */
@@ -1546,18 +1635,18 @@ interface ProjectRuntimeConfig {
  * Hostname resolution response.
  */
 interface ResolvedHostname {
-    projectId: string;
+    environmentId: string;
     organizationId?: string;
     /** Optional runtime config — when present, callers can skip the artifact fetch's runtime block. */
-    runtime?: ProjectRuntimeConfig;
+    runtime?: EnvironmentRuntimeConfig;
 }
 /**
- * Artifact response wrapping the spec's `ProjectArtifact` envelope plus
+ * Artifact response wrapping the spec's `EnvironmentArtifact` envelope plus
  * an optional `runtime` block carrying the project's database
  * connection details.
  */
-interface ProjectArtifactResponse extends ProjectArtifact {
-    runtime?: ProjectRuntimeConfig;
+interface EnvironmentArtifactResponse extends EnvironmentArtifact {
+    runtime?: EnvironmentRuntimeConfig;
 }
 interface ArtifactApiClientConfig {
     /** Control-plane base URL (no trailing slash). */
@@ -1603,32 +1692,32 @@ declare class ArtifactApiClient {
      * independently (the cache key includes the commit id) so the preview
      * runtime can hold multiple versions in memory simultaneously.
      */
-    fetchArtifact(projectId: string, opts?: {
+    fetchArtifact(environmentId: string, opts?: {
         commit?: string;
-    }): Promise<ProjectArtifactResponse | null>;
+    }): Promise<EnvironmentArtifactResponse | 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
+     * 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<{
-        projectId: string;
+        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/projects/:id/branches` endpoint.
+     * Reuses the existing `GET /cloud/environments/:id/branches` endpoint.
      */
-    fetchBranchHead(projectId: string, branchName: string): Promise<{
+    fetchBranchHead(environmentId: string, branchName: string): Promise<{
         commitId: string;
         publishedAt?: string | null;
     } | null>;
     /** Drop cached entries for a project (and any matching hostname). */
-    invalidate(projectId: string): void;
+    invalidate(environmentId: string): void;
     /** Drop everything. Used on shutdown / hot-reload. */
     clear(): void;
     private request;
@@ -1644,9 +1733,9 @@ interface FileArtifactApiClientConfig {
     artifactPath?: string;
     /**
      * Project id every hostname maps to. Defaults to
-     * `process.env.OS_PROJECT_ID` or `'proj_local'`.
+     * `process.env.OS_ENVIRONMENT_ID` or `'proj_local'`.
      */
-    projectId?: string;
+    environmentId?: string;
     /**
      * Organization id surfaced alongside the project. Defaults to
      * `process.env.OS_ORGANIZATION_ID` or `'org_local'`.
@@ -1656,9 +1745,9 @@ interface FileArtifactApiClientConfig {
      * 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`.
+     * `<cwd>/.objectstack/data/<environmentId>.db`.
      */
-    runtime?: ProjectRuntimeConfig;
+    runtime?: EnvironmentRuntimeConfig;
     /**
      * Reload the artifact on every fetch instead of caching the first
      * read. Useful when iterating on a project's metadata without
@@ -1674,7 +1763,7 @@ interface FileArtifactApiClientConfig {
 }
 declare class FileArtifactApiClient {
     private readonly artifactPath;
-    private readonly projectId;
+    private readonly environmentId;
     private readonly organizationId;
     private readonly overrideRuntime?;
     private readonly watch;
@@ -1682,18 +1771,18 @@ declare class FileArtifactApiClient {
     private cached?;
     constructor(config?: FileArtifactApiClientConfig);
     resolveHostname(_host: string): Promise<ResolvedHostname | null>;
-    fetchArtifact(_projectId: string, _opts?: {
+    fetchArtifact(_environmentId: string, _opts?: {
         commit?: string;
-    }): Promise<ProjectArtifactResponse | null>;
+    }): Promise<EnvironmentArtifactResponse | null>;
     lookupProjectByShortId(_shortId: string): Promise<{
-        projectId: string;
+        environmentId: string;
         organizationId?: string;
     } | null>;
-    fetchBranchHead(_projectId: string, _branchName: string): Promise<{
+    fetchBranchHead(_environmentId: string, _branchName: string): Promise<{
         commitId: string;
         publishedAt?: string | null;
     } | null>;
-    invalidate(_projectId: string): void;
+    invalidate(_environmentId: string): void;
     clear(): void;
     private loadArtifact;
     private readRuntimeFromArtifact;
@@ -1745,6 +1834,155 @@ interface ObjectOSStackResult {
 }
 declare function createObjectOSStack(config: ObjectOSStackConfig): Promise<ObjectOSStackResult>;
 
+/**
+ * MarketplaceProxyPlugin
+ *
+ * Forwards `GET /api/v1/marketplace/*` from a tenant ObjectOS runtime to
+ * the configured ObjectStack Cloud control-plane URL. The cloud endpoint
+ * (`packages/service-cloud/src/routes/marketplace.ts`) is unauthenticated
+ * and only exposes packages whose owner has opted in to the public catalog
+ * (`sys_package.marketplace_listed = true`) — so the proxy passes through
+ * without any credentials.
+ *
+ * Why proxy instead of direct browser → cloud:
+ *   - The Console SPA stays on the tenant origin, so no CORS configuration
+ *     is required on the cloud side.
+ *   - Local-dev `os serve` works regardless of whether the developer's
+ *     browser has cookies for cloud.objectos.app.
+ *   - Adds a single, easily auditable network seam between tenant and
+ *     control plane.
+ *
+ * Install is NOT proxied here. Installing a package mutates control-plane
+ * state and requires a cloud session + active organization context — the
+ * Console SPA performs install by opening the cloud's install dialog in a
+ * new tab so the user authenticates against cloud directly. A future
+ * iteration may introduce a delegated install token; until then, browse
+ * here and install on cloud.
+ */
+
+interface MarketplaceProxyPluginConfig {
+    /**
+     * Control-plane base URL (e.g. https://cloud.objectos.app). When the
+     * caller passes nothing AND the runtime has no OS_CLOUD_URL set, the
+     * plugin falls back to the public ObjectStack-operated cloud so that
+     * `objectstack dev` can browse the marketplace out of the box. Set
+     * OS_CLOUD_URL=off (or `local`) to opt out — the plugin then mounts
+     * a stub that responds 503 and the SPA renders an empty-state
+     * explaining marketplace is unavailable in this runtime.
+     */
+    controlPlaneUrl?: string;
+}
+declare class MarketplaceProxyPlugin implements Plugin {
+    readonly name = "com.objectstack.runtime.marketplace-proxy";
+    readonly version = "1.0.0";
+    private readonly cloudUrl;
+    constructor(config?: MarketplaceProxyPluginConfig);
+    init: (_ctx: PluginContext) => Promise<void>;
+    start: (ctx: PluginContext) => Promise<void>;
+}
+
+interface MarketplaceInstallLocalPluginConfig {
+    /** Cloud control-plane base URL. When unset, falls back to OS_CLOUD_URL
+     *  and then to the public ObjectStack cloud so a fresh `objectstack dev`
+     *  can install from the marketplace without configuration. Set
+     *  OS_CLOUD_URL=off to disable (the install endpoint then returns 503). */
+    controlPlaneUrl?: string;
+    /** Override the on-disk cache directory. Defaults to
+     *  `<cwd>/.objectstack/installed-packages`. */
+    storageDir?: string;
+}
+declare class MarketplaceInstallLocalPlugin implements Plugin {
+    readonly name = "com.objectstack.runtime.marketplace-install-local";
+    readonly version = "1.0.0";
+    private readonly cloudUrl;
+    private readonly storageDir;
+    constructor(config?: MarketplaceInstallLocalPluginConfig);
+    init: (_ctx: PluginContext) => Promise<void>;
+    start: (ctx: PluginContext) => Promise<void>;
+    /**
+     * Re-register every cached manifest with the kernel's manifest service.
+     * Safe to call on a kernel that already has the same manifest_id (the
+     * underlying ObjectQL registry overwrites by id, but we still warn so
+     * a developer can spot the dev-time clash between their config.ts and
+     * a marketplace package).
+     */
+    private rehydrate;
+    private handleInstall;
+    private handleList;
+    private handleUninstall;
+    /**
+     * Detect whether `manifestId` is already known to the kernel and classify
+     * the source so we can refuse vs upgrade gracefully.
+     *
+     *   'none'         — fresh install
+     *   'marketplace'  — previously installed by this plugin (allow upgrade)
+     *   'user-code'    — defined by AppPlugin from objectstack.config.ts
+     *                    (refuse to avoid silently overwriting authored code)
+     */
+    private findConflict;
+    /**
+     * Pull a userId out of the request's better-auth session, if any.
+     * Returns null when there is no signed-in user. v1 does not check
+     * admin role — UI gating + the auth requirement is sufficient for
+     * dev / single-tenant runtimes. Stricter checks can be layered on
+     * via a middleware in cloud-hosted multi-tenant deployments.
+     */
+    /**
+     * Replicate the start-time side-effects that AppPlugin runs for
+     * statically-declared apps but the `manifest` service does NOT:
+     *
+     *   1. Load `manifest.translations` (array of `Record<locale, data>`)
+     *      into the i18n service — auto-creating an in-memory fallback if
+     *      none is registered, matching AppPlugin's behaviour.
+     *
+     *   2. Merge `manifest.data` (an array of seed datasets) into the
+     *      kernel's `seed-datasets` service so SecurityPlugin's per-org
+     *      replay middleware picks them up on every future
+     *      sys_organization insert.
+     *
+     *   3. When `seedNow=true`, also run the seed immediately so the user
+     *      sees demo data without having to create a new org:
+     *        • single-tenant: run SeedLoaderService inline (mirrors
+     *          AppPlugin single-tenant branch)
+     *        • multi-tenant: invoke `seed-replayer` for the caller's
+     *          active org (resolved from the request session)
+     *
+     * Errors are logged but never thrown — install succeeds even if
+     * post-register side-effects partially fail (the manifest itself is
+     * already registered + cached). Returns a small summary for the
+     * response envelope.
+     */
+    private applySideEffects;
+    /**
+     * Best-effort active-org resolution. Reads the better-auth session
+     * (same path as requireAuthenticatedUser) and returns
+     * `session.activeOrganizationId`, falling back to the user's first
+     * org membership.
+     */
+    private resolveActiveOrgId;
+    private requireAuthenticatedUser;
+    private readAll;
+}
+
+/**
+ * Shared marketplace / cloud control-plane defaults.
+ *
+ * Centralised so every plugin + the CLI auto-inject path agree on
+ * "what cloud URL do we mean when the user didn't set OS_CLOUD_URL?".
+ * Until we have a competing public hosted cloud, this points at the
+ * ObjectStack-operated control plane so a vanilla `objectstack dev` can
+ * browse the marketplace out of the box.
+ */
+declare const DEFAULT_CLOUD_URL = "https://cloud.objectos.app";
+/**
+ * Resolve the effective control-plane URL from an explicit constructor
+ * value, the OS_CLOUD_URL env var, or the default. Returns an empty
+ * string when the caller explicitly disabled cloud with
+ * `OS_CLOUD_URL=off` / `local` — callers should treat that as
+ * "marketplace unavailable on this runtime".
+ */
+declare function resolveCloudUrl(explicit?: string | null): string;
+
 /**
  * Per-project driver registry contract.
  *
@@ -1764,22 +2002,22 @@ type IDataDriver$1 = Contracts.IDataDriver;
 interface EnvironmentDriverRegistry {
     /** Resolve a project by hostname. Returns `null` when unknown. */
     resolveByHostname(host: string): Promise<{
-        projectId: string;
+        environmentId: string;
         driver: IDataDriver$1;
     } | null>;
     /** Resolve a project's driver by ID. Returns `null` when unknown. */
-    resolveById(projectId: string): Promise<IDataDriver$1 | null>;
+    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(projectId: string): {
-        projectId: string;
+    peekById(environmentId: string): {
+        environmentId: string;
         driver: IDataDriver$1;
         project: any;
     } | null;
     /** Drop cached entries for the given project. */
-    invalidate(projectId: string): void;
+    invalidate(environmentId: string): void;
 }
 
 /**
@@ -1788,11 +2026,11 @@ interface EnvironmentDriverRegistry {
  *
  * 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 /
+ * 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_project` row so callers downstream (notably
+ * like a `sys_environment` row so callers downstream (notably
  * `ArtifactKernelFactory`) can read `id`, `organization_id`,
  * `database_url` and `database_driver` without branching.
  */
@@ -1818,16 +2056,16 @@ declare class ArtifactEnvironmentRegistry implements EnvironmentDriverRegistry {
     private readonly pending;
     constructor(config: ArtifactEnvironmentRegistryConfig);
     resolveByHostname(host: string): Promise<{
-        projectId: string;
+        environmentId: string;
         driver: IDataDriver;
     } | null>;
-    resolveById(projectId: string): Promise<IDataDriver | null>;
-    peekById(projectId: string): {
-        projectId: string;
+    resolveById(environmentId: string): Promise<IDataDriver | null>;
+    peekById(environmentId: string): {
+        environmentId: string;
         driver: IDataDriver;
         project: any;
     } | null;
-    invalidate(projectId: string): void;
+    invalidate(environmentId: string): void;
     private buildCacheEntry;
 }
 
@@ -1844,19 +2082,19 @@ interface ArtifactKernelFactoryConfig {
     kernelConfig?: ConstructorParameters<typeof ObjectKernel>[0];
     /**
      * Base secret used to derive per-project AuthPlugin secrets via
-     * HKDF-style HMAC-SHA256(baseSecret, projectId). Falls back to
+     * HKDF-style HMAC-SHA256(baseSecret, environmentId). Falls back to
      * `process.env.OS_AUTH_SECRET` / `AUTH_SECRET` at construction time.
      */
     authBaseSecret?: string;
 }
-declare class ArtifactKernelFactory implements ProjectKernelFactory {
+declare class ArtifactKernelFactory implements EnvironmentKernelFactory {
     private readonly client;
     private readonly envRegistry;
     private readonly logger;
     private readonly kernelConfig?;
     private readonly authBaseSecret;
     constructor(config: ArtifactKernelFactoryConfig);
-    create(projectId: string): Promise<ObjectKernel>;
+    create(environmentId: string): Promise<ObjectKernel>;
 }
 
 /**
@@ -1902,10 +2140,10 @@ 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;
+declare function derivePlatformSsoClientId(environmentId: string): string;
 /**
  * Derive the per-project OAuth client_secret deterministically from the
- * shared master secret. HMAC-SHA256(baseSecret, 'oauth-client:' + projectId)
+ * 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)
@@ -1917,7 +2155,7 @@ declare function derivePlatformSsoClientId(projectId: string): string;
  * 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;
+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
@@ -1939,7 +2177,7 @@ interface SeedPlatformSsoClientOptions {
         update: (object: string, data: any, where: any, opts?: any) => Promise<any>;
     };
     /** Project id (also used to derive client_id + client_secret). */
-    projectId: string;
+    environmentId: string;
     /**
      * Project hostname (e.g. `acme-crm.objectos.app`). Optional — projects
      * may be created before a hostname is assigned, in which case no
@@ -1962,7 +2200,7 @@ interface SeedPlatformSsoClientOptions {
 }
 /**
  * Idempotently upsert a `sys_oauth_application` row for the given project.
- * Re-running with the same `projectId` is a no-op (the deterministic
+ * 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.
@@ -1980,7 +2218,7 @@ interface BackfillPlatformSsoClientsOptions {
     limit?: number;
 }
 /**
- * Scan `sys_project` and ensure every active project has a corresponding
+ * 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
@@ -1992,7 +2230,7 @@ declare function backfillPlatformSsoClients(opts: BackfillPlatformSsoClientsOpti
     seeded: number;
     alreadyExisted: number;
     failures: Array<{
-        projectId: string;
+        environmentId: string;
         error: string;
     }>;
 }>;
@@ -2227,4 +2465,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_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentDriverRegistry, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, MiddlewareManager, type ObjectOSStackConfig, type ObjectOSStackResult, PLATFORM_SSO_PROVIDER_ID, type ProjectArtifactResponse, type ProjectKernelFactory, type ProjectRuntimeConfig, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, 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 };
+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, 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, 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, createObjectOSStack, createStandaloneStack, createSystemEnvironmentPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveCloudUrl, resolveDefaultArtifactPath, resolveErrorReporter, resolveMetrics, resolveRequestId, seedPlatformSsoClient };