@objectstack/runtime 6.5.1 → 6.7.0

package/dist/index.d.cts

@@ -71,6 +71,20 @@ declare class Runtime {
     getKernel(): ObjectKernel;
 }
 
+/**
+ * Resolve the ObjectStack home directory used to store cwd-independent
+ * runtime data (default sqlite database, downloaded marketplace apps,
+ * installed plugin cache).
+ *
+ * Resolution order:
+ *   1. `OS_HOME` env var (absolute path; `~` expanded)
+ *   2. `~/.objectstack` (cross-platform user-home default)
+ *
+ * The directory is created lazily by callers that actually write to it
+ * (e.g. the sqlite driver's `mkdirSync(...)`); this helper does not
+ * touch the filesystem.
+ */
+declare function resolveObjectStackHome(): string;
 declare const StandaloneStackConfigSchema: z.ZodObject<{
     databaseUrl: z.ZodOptional<z.ZodString>;
     databaseAuthToken: z.ZodOptional<z.ZodString>;
@@ -820,6 +834,30 @@ interface KernelManagerConfig {
         warn?: (...a: any[]) => void;
         error?: (...a: any[]) => void;
     };
+    /**
+     * Optional upstream-change detector. When set, every cache hit older
+     * than `staleCheckIntervalMs` triggers this probe before returning the
+     * cached kernel. Returning `true` evicts the kernel and forces a
+     * rebuild, so changes to the control-plane state that don't reach
+     * this process via push (marketplace installs, artifact republish,
+     * etc.) become visible without waiting for the LRU TTL to expire.
+     *
+     * The probe should be cheap (single small GET). Errors thrown here
+     * are caught and treated as "still fresh" so a brief upstream
+     * outage doesn't churn every cached kernel — the worst case is
+     * stale-by-`ttlMs`, which is what we had before adding the probe.
+     *
+     * `builtAtMs` is the kernel's `createdAt` time so the probe can
+     * compare against an upstream "last changed at" timestamp.
+     */
+    freshnessProbe?: (environmentId: string, builtAtMs: number) => Promise<boolean>;
+    /**
+     * Minimum gap between successive freshness probes for the same env.
+     * Defaults to 10 seconds — enough to avoid hammering the control
+     * plane on tight render loops while still keeping the user's
+     * post-install refresh perceived as immediate.
+     */
+    staleCheckIntervalMs?: number;
 }
 /**
  * LRU + TTL cache of per-project {@link ObjectKernel} instances.
@@ -837,6 +875,8 @@ declare class KernelManager {
     private readonly logger;
     private readonly cache;
     private readonly pending;
+    private readonly freshnessProbe?;
+    private readonly staleCheckIntervalMs;
     constructor(config: KernelManagerConfig);
     /** Returns the currently cached environmentIds (ordered by insertion). */
     keys(): string[];
@@ -1716,6 +1756,24 @@ declare class ArtifactApiClient {
         commitId: string;
         publishedAt?: string | null;
     } | null>;
+    /**
+     * Cheap freshness probe — returns the env's `last_published_at`
+     * (and best-effort current commit) without rebuilding the artifact.
+     * Used by `KernelManager` on cache hits to detect when a per-env
+     * kernel has been invalidated by an upstream change (marketplace
+     * install/uninstall, artifact publish) so it can be rebuilt
+     * without waiting for the 15-minute LRU TTL to expire.
+     *
+     * Returns `null` on definitive 404 / unknown env. Errors propagate
+     * (caller decides whether to treat unreachable cloud as fresh or
+     * stale — typically fresh, so a brief outage doesn't churn every
+     * cached kernel).
+     */
+    getFreshness(environmentId: string): Promise<{
+        environmentId: string;
+        lastPublishedAt: string | null;
+        commitId: string | null;
+    } | null>;
     /** Drop cached entries for a project (and any matching hostname). */
     invalidate(environmentId: string): void;
     /** Drop everything. Used on shutdown / hot-reload. */
@@ -1839,10 +1897,9 @@ declare function createObjectOSStack(config: ObjectOSStackConfig): Promise<Objec
  *
  * 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.
+ * 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
@@ -2049,9 +2106,9 @@ declare function resolveCloudUrl(explicit?: string | null): string;
  *   - 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.
+ * The contract lives in `@objectstack/runtime` so the runtime can
+ * express "fetch artifact + boot per-project kernel" without taking a
+ * dependency on the cloud control plane.
  */
 
 type IDataDriver$1 = Contracts.IDataDriver;
@@ -2521,4 +2578,4 @@ declare function actionBodyRunnerFactory(runner: ScriptRunner, opts: FactoryOpti
     timeoutMs?: number;
 }) => ((actionCtx: any) => Promise<unknown>) | undefined;
 
-export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, DEFAULT_CLOUD_URL, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentArtifactResponse, type EnvironmentDriverRegistry, type EnvironmentKernelFactory, type EnvironmentRuntimeConfig, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, MarketplaceInstallLocalPlugin, type MarketplaceInstallLocalPluginConfig, MarketplaceProxyPlugin, type MarketplaceProxyPluginConfig, MiddlewareManager, type ObjectOSStackConfig, type ObjectOSStackResult, ObservabilityServicePlugin, type ObservabilityServicePluginOptions, PLATFORM_SSO_PROVIDER_ID, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, RuntimeConfigPlugin, type RuntimeConfigPluginConfig, SYSTEM_ENVIRONMENT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemEnvironmentPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemEnvironmentPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveCloudUrl, resolveDefaultArtifactPath, resolveErrorReporter, resolveMetrics, 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, RuntimeConfigPlugin, type RuntimeConfigPluginConfig, SYSTEM_ENVIRONMENT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemEnvironmentPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemEnvironmentPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveCloudUrl, resolveDefaultArtifactPath, resolveErrorReporter, resolveMetrics, resolveObjectStackHome, resolveRequestId, seedPlatformSsoClient };

package/dist/index.d.ts

@@ -71,6 +71,20 @@ declare class Runtime {
     getKernel(): ObjectKernel;
 }
 
+/**
+ * Resolve the ObjectStack home directory used to store cwd-independent
+ * runtime data (default sqlite database, downloaded marketplace apps,
+ * installed plugin cache).
+ *
+ * Resolution order:
+ *   1. `OS_HOME` env var (absolute path; `~` expanded)
+ *   2. `~/.objectstack` (cross-platform user-home default)
+ *
+ * The directory is created lazily by callers that actually write to it
+ * (e.g. the sqlite driver's `mkdirSync(...)`); this helper does not
+ * touch the filesystem.
+ */
+declare function resolveObjectStackHome(): string;
 declare const StandaloneStackConfigSchema: z.ZodObject<{
     databaseUrl: z.ZodOptional<z.ZodString>;
     databaseAuthToken: z.ZodOptional<z.ZodString>;
@@ -820,6 +834,30 @@ interface KernelManagerConfig {
         warn?: (...a: any[]) => void;
         error?: (...a: any[]) => void;
     };
+    /**
+     * Optional upstream-change detector. When set, every cache hit older
+     * than `staleCheckIntervalMs` triggers this probe before returning the
+     * cached kernel. Returning `true` evicts the kernel and forces a
+     * rebuild, so changes to the control-plane state that don't reach
+     * this process via push (marketplace installs, artifact republish,
+     * etc.) become visible without waiting for the LRU TTL to expire.
+     *
+     * The probe should be cheap (single small GET). Errors thrown here
+     * are caught and treated as "still fresh" so a brief upstream
+     * outage doesn't churn every cached kernel — the worst case is
+     * stale-by-`ttlMs`, which is what we had before adding the probe.
+     *
+     * `builtAtMs` is the kernel's `createdAt` time so the probe can
+     * compare against an upstream "last changed at" timestamp.
+     */
+    freshnessProbe?: (environmentId: string, builtAtMs: number) => Promise<boolean>;
+    /**
+     * Minimum gap between successive freshness probes for the same env.
+     * Defaults to 10 seconds — enough to avoid hammering the control
+     * plane on tight render loops while still keeping the user's
+     * post-install refresh perceived as immediate.
+     */
+    staleCheckIntervalMs?: number;
 }
 /**
  * LRU + TTL cache of per-project {@link ObjectKernel} instances.
@@ -837,6 +875,8 @@ declare class KernelManager {
     private readonly logger;
     private readonly cache;
     private readonly pending;
+    private readonly freshnessProbe?;
+    private readonly staleCheckIntervalMs;
     constructor(config: KernelManagerConfig);
     /** Returns the currently cached environmentIds (ordered by insertion). */
     keys(): string[];
@@ -1716,6 +1756,24 @@ declare class ArtifactApiClient {
         commitId: string;
         publishedAt?: string | null;
     } | null>;
+    /**
+     * Cheap freshness probe — returns the env's `last_published_at`
+     * (and best-effort current commit) without rebuilding the artifact.
+     * Used by `KernelManager` on cache hits to detect when a per-env
+     * kernel has been invalidated by an upstream change (marketplace
+     * install/uninstall, artifact publish) so it can be rebuilt
+     * without waiting for the 15-minute LRU TTL to expire.
+     *
+     * Returns `null` on definitive 404 / unknown env. Errors propagate
+     * (caller decides whether to treat unreachable cloud as fresh or
+     * stale — typically fresh, so a brief outage doesn't churn every
+     * cached kernel).
+     */
+    getFreshness(environmentId: string): Promise<{
+        environmentId: string;
+        lastPublishedAt: string | null;
+        commitId: string | null;
+    } | null>;
     /** Drop cached entries for a project (and any matching hostname). */
     invalidate(environmentId: string): void;
     /** Drop everything. Used on shutdown / hot-reload. */
@@ -1839,10 +1897,9 @@ declare function createObjectOSStack(config: ObjectOSStackConfig): Promise<Objec
  *
  * 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.
+ * 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
@@ -2049,9 +2106,9 @@ declare function resolveCloudUrl(explicit?: string | null): string;
  *   - 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.
+ * The contract lives in `@objectstack/runtime` so the runtime can
+ * express "fetch artifact + boot per-project kernel" without taking a
+ * dependency on the cloud control plane.
  */
 
 type IDataDriver$1 = Contracts.IDataDriver;
@@ -2521,4 +2578,4 @@ declare function actionBodyRunnerFactory(runner: ScriptRunner, opts: FactoryOpti
     timeoutMs?: number;
 }) => ((actionCtx: any) => Promise<unknown>) | undefined;
 
-export { AppPlugin, ArtifactApiClient, type ArtifactApiClientConfig, ArtifactEnvironmentRegistry, type ArtifactEnvironmentRegistryConfig, ArtifactKernelFactory, type ArtifactKernelFactoryConfig, AuthProxyPlugin, type BackfillPlatformSsoClientsOptions, DEFAULT_CLOUD_URL, DEFAULT_RATE_LIMITS, type DefaultHostConfigOptions, type DefaultHostConfigResult, type DispatcherPluginConfig, DriverPlugin, type EnvironmentArtifactResponse, type EnvironmentDriverRegistry, type EnvironmentKernelFactory, type EnvironmentRuntimeConfig, FileArtifactApiClient, type FileArtifactApiClientConfig, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, KernelManager, type KernelManagerConfig, type LoadArtifactBundleOptions, MarketplaceInstallLocalPlugin, type MarketplaceInstallLocalPluginConfig, MarketplaceProxyPlugin, type MarketplaceProxyPluginConfig, MiddlewareManager, type ObjectOSStackConfig, type ObjectOSStackResult, ObservabilityServicePlugin, type ObservabilityServicePluginOptions, PLATFORM_SSO_PROVIDER_ID, QuickJSScriptRunner, type QuickJSScriptRunnerOptions, type RateLimitBucketConfig, type RateLimitDecision, type RateLimitDefaults, type RateLimitStore, RateLimiter, type ResolvedHostname, Runtime, type RuntimeConfig, RuntimeConfigPlugin, type RuntimeConfigPluginConfig, SYSTEM_ENVIRONMENT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemEnvironmentPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemEnvironmentPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveCloudUrl, resolveDefaultArtifactPath, resolveErrorReporter, resolveMetrics, 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, RuntimeConfigPlugin, type RuntimeConfigPluginConfig, SYSTEM_ENVIRONMENT_ID, SandboxError, type ScriptContext, type ScriptOrigin, type ScriptResult, type ScriptRunOptions, type ScriptRunner, type SecurityHeadersOptions, SeedLoaderService, type SeedPlatformSsoClientOptions, type StandaloneStackConfig, type StandaloneStackResult, type SystemEnvironmentPluginConfig, type TraceContext, UnimplementedScriptRunner, actionBodyRunnerFactory, backfillPlatformSsoClients, buildPlatformSsoRedirectUri, buildSecurityHeaders, collectBundleActions, collectBundleFunctions, collectBundleHooks, createDefaultHostConfig, createDispatcherPlugin, createObjectOSStack, createStandaloneStack, createSystemEnvironmentPlugin, derivePlatformSsoClientId, derivePlatformSsoClientSecret, extractRequestId, formatTraceparent, generateRequestId, hookBodyRunnerFactory, isHttpUrl, loadArtifactBundle, mergeRuntimeModule, parseTraceparent, readArtifactSource, resolveCloudUrl, resolveDefaultArtifactPath, resolveErrorReporter, resolveMetrics, resolveObjectStackHome, resolveRequestId, seedPlatformSsoClient };