@happyvertical/smrt-app-runtime 0.43.9 → 0.44.0

package/AGENTS.md

@@ -5,6 +5,9 @@ Application infrastructure composition for the validated runtime profiles in
 
 ## Local profile
 
+- `validateApplicationId()` is the canonical strict validator for explicit app
+  IDs. `encodeApplicationId()` derives a length-bounded, collision-resistant
+  ID from package names; generated operational surfaces must share these APIs.
 - `initializeLocalApplicationRuntime()` owns user data paths, SQLite tuning,
   local application-secret creation, and the single-use owner bootstrap flow.
 - SQLite is acquired through `@happyvertical/sql`'s explicit
@@ -12,15 +15,69 @@ Application infrastructure composition for the validated runtime profiles in
   runtime establishes its user-owned mode-0700 data root.
 - Application migrations are explicit through `prepareDatabase`; runtime never
   creates application model tables implicitly.
+- Standalone migration commands must call `prepareLocalDatabaseStorage()`
+  before opening SQLite so custody is established without creating schema or
+  bootstrap records.
+- Read-only/copy/import operator commands must call
+  `validateLocalDatabaseStorage()` before opening SQLite; it verifies the
+  app-bound marker, source separation, real path chain, ownership, and mode
+  without creating or repairing storage.
 - Owner bootstrap creates normal `Person`, `User`, `Tenant`, owner `Role` /
   `Membership`, and `Session` records in one transaction.
 - Bootstrap is loopback-only. Only an HMAC of the short-lived token is stored.
 - Background jobs and application-defined paid capabilities are default-off.
 - The embedded runner reuses `TaskRunner`; it is not a second job contract.
 
+## Deployed profiles
+
+- `initializeDeployedApplicationRuntime()` composes only `self-hosted` and
+  `cloud`; it rejects local initialization and provider/binding mismatches.
+- Provider bindings own credentials, vendor clients, and readiness checks.
+  Runtime diagnostics contain selectors and status only.
+- The database binding must expose a provider-owned `close` callback before
+  `connect` can run. The runtime owns that cleanup boundary and runs the
+  application's explicit, idempotent `prepareDatabase` hook.
+- A failed startup cleanup throws `DeployedRuntimeCleanupError`; callers retain
+  and retry its idempotent `retryCleanup()` boundary until it succeeds.
+- Public authentication, asset storage, and secret bindings are mandatory and
+  readiness-checked before startup succeeds.
+- `createTaskWorker()` and `createScheduleWorker()` initialize the normal jobs
+  package runners against the shared PostgreSQL database. They are intended for
+  separate processes; the web process does not start them automatically.
+- `close()` drains in-flight readiness/session/worker initialization and
+  serialized runner start/stop operations, stops every runner returned by the
+  runtime, and then closes PostgreSQL. Returned runners must not be restarted
+  after runtime shutdown begins.
+- A tracked operation may await a re-entrant `close()` request without
+  deadlocking; external `close()` callers still await complete cleanup.
+- `health()` is process liveness. `readiness()` probes database/auth/assets/
+  secrets; it does not claim that an external worker fleet is running.
+- Database-provider readiness is additive; a PostgreSQL-specific server-version
+  probe always gates startup and live readiness.
+- Cloud must keep required tenant context and must never introduce a root or
+  unscoped tenant fallback. RLS remains an explicit deployment/migration choice.
+
+## Public runtime diagnostics
+
+- `projectRuntimeDiagnostics()` is the only public diagnostic projection. It
+  constructs the schema-version-1 allowlist and never serializes the private
+  local or deployed diagnostics objects.
+- The allowlist is limited to active profile/coarse health, schema and
+  migration readiness, six fixed capability statuses, a sorted/capped public
+  tool inventory plus digest, explicit operational topology differences,
+  coarse worker heartbeat state, and eight stable code/timestamp errors.
+- Callers supply an explicit clock and worker-heartbeat seam. A missing
+  heartbeat is `unknown`; web-process liveness never proves worker liveness.
+- Error ingestion maps unknown codes to `runtime_error`, truncates timestamps
+  to the minute, and ignores messages, stacks, logs, records, and nested state.
+- Authentication and diagnostics-read authorization belong before every call
+  to the projector or its runtime probes.
+
 ## Invariants
 
 - Never expose application-secret bytes or bootstrap token hashes in diagnostics.
+- Never include provider error text, URLs, tokens, or credentials in deployed
+  errors, diagnostics, health, or readiness payloads.
 - Keep local data, assets, database, and secrets outside the source tree.
 - Do not reach into collection/database private fields. Add an upstream public
   API if composition cannot be expressed through exported surfaces.

package/README.md

@@ -90,3 +90,99 @@ Background jobs and application-defined paid capabilities remain disabled until
 explicitly enabled. With embedded job topology, `createEmbeddedJobRunner()`
 returns the normal s-m-r-t `TaskRunner`, so the application keeps one enqueue
 and execution contract without requiring a separate worker service.
+
+## Self-hosted and cloud applications
+
+The deployed initializer validates the selected profile against concrete,
+provider-owned bindings. Database URLs, OIDC credentials, storage keys, and
+secret-manager identifiers stay inside those adapters and are never copied into
+the runtime snapshot.
+
+```ts
+import {
+  initializeDeployedApplicationRuntime,
+} from '@happyvertical/smrt-app-runtime';
+import { getDatabase } from '@happyvertical/sql';
+
+const initialized = await initializeDeployedApplicationRuntime({
+  profile: 'self-hosted',
+  database: {
+    engine: 'postgres',
+    connect: () => getDatabase({
+      type: 'postgres',
+      url: requirePrivateSetting('DATABASE_URL'),
+    }),
+    close: async (db) => {
+      await db.close?.();
+    },
+  },
+  authentication: {
+    provider: 'oidc',
+    readiness: () => oidcProvider.assertReady(),
+  },
+  assets: {
+    provider: 's3-compatible',
+    readiness: () => assetProvider.assertReady(),
+  },
+  secrets: {
+    provider: 'environment',
+    readiness: () => secretProvider.assertReady(),
+  },
+  prepareDatabase: runApplicationMigrations,
+});
+```
+
+Startup validates every binding, including the provider-owned database cleanup
+boundary, before opening a connection. A missing public-auth or secret binding,
+a selector mismatch, an unavailable provider, a failed
+PostgreSQL probe, or a failed migration rejects startup. Provider failures are
+reported with stable component codes and omit the underlying provider message
+so credentials cannot leak into HTTP or orchestration payloads.
+A custom database readiness callback is additive; the runtime always runs its
+own PostgreSQL-specific server-version probe before startup or readiness can
+succeed.
+If cleanup after a startup failure also fails,
+`DeployedRuntimeCleanupError.retryCleanup()` retains the redacted, idempotent
+ownership path until the provider closes successfully.
+
+`health()` reports process liveness. `readiness()` rechecks PostgreSQL,
+authentication, assets, and secrets and returns only `ready` / `not-ready`
+component states. `diagnostics()` reports the resolved profile, explicit
+provider selectors, tenancy posture, and worker topology without secret values.
+
+Job producers keep using `SmrtObject.bg()` / `background().enqueue()` in every
+profile. Deployed worker entry points initialize the ordinary runners against
+the same PostgreSQL database:
+
+```ts
+const taskWorker = await initialized.createTaskWorker({ concurrency: 8 });
+await taskWorker.start();
+
+// Run this in a separate schedule-worker process, not beside the web server.
+const scheduleWorker = await initialized.createScheduleWorker();
+await scheduleWorker.start();
+```
+
+`initialized.close()` drains in-flight readiness/session/worker initialization
+and serialized runner start/stop operations, stops every runner returned by
+this runtime, and only then closes PostgreSQL.
+Callers may stop a runner earlier, but must not restart a returned runner after
+its runtime has begun shutdown; lifecycle-gated `start()` calls then reject.
+An awaited `close()` request made from inside a tracked provider or worker
+operation acknowledges shutdown so that operation can unwind; callers outside
+the operation continue to await complete worker and database cleanup.
+
+Self-hosted deployments may select OIDC or magic-link authentication, explicit
+single- or multi-tenancy, local or S3-compatible assets, and environment,
+local-file, or external secrets. Cloud requires hosted identity, PostgreSQL,
+multi-tenancy with required tenant context, managed/external secrets,
+managed/S3-compatible object storage, public TLS, and scalable workers. Cloud
+may select application isolation instead of PostgreSQL RLS, but it can never
+enable an unscoped/root-tenant fallback.
+
+The application runtime does not provision databases, buckets, identity
+providers, secret managers, worker fleets, TLS, billing, or a hosted control
+plane. Those remain operator/managed-platform responsibilities. Enabling the
+`database-rls` selector also requires the deployment migration to apply the
+documented s-m-r-t PostgreSQL policies; the selector does not grant or mutate
+database privileges at runtime.

package/dist/index.d.ts

@@ -1,10 +1,22 @@
+import { ApplicationRuntimeProfile } from '@happyvertical/smrt-config';
+import { AssetStorageProvider } from '@happyvertical/smrt-config';
+import { AuthenticationProvider } from '@happyvertical/smrt-config';
 import { DatabaseInterface } from '@happyvertical/sql';
 import { ResolvedApplicationRuntime } from '@happyvertical/smrt-config';
 import { RuntimeProviderOverrides } from '@happyvertical/smrt-config';
+import { ScheduleRunner } from '@happyvertical/smrt-jobs';
+import { ScheduleRunnerConfig } from '@happyvertical/smrt-jobs';
+import { SecretProvider } from '@happyvertical/smrt-config';
 import { SessionService } from '@happyvertical/smrt-users';
 import { TaskRunner } from '@happyvertical/smrt-jobs';
 import { TaskRunnerConfig } from '@happyvertical/smrt-jobs';
 
+declare const CAPABILITY_IDS: readonly ["asset-storage", "authentication", "background-jobs", "database", "paid-capabilities", "secret-storage"];
+
+declare type CapabilityId = (typeof CAPABILITY_IDS)[number];
+
+declare type CapabilityStatus = 'available' | 'disabled' | 'unavailable' | 'unknown';
+
 export declare interface ClaimLocalOwnerInput {
     token: string;
     name: string;
@@ -14,6 +26,136 @@ export declare interface ClaimLocalOwnerInput {
     ipAddress?: string;
 }
 
+export declare interface DeployedApplicationRuntime {
+    readonly db: DatabaseInterface;
+    readonly resolvedRuntime: ResolvedApplicationRuntime;
+    restoreSession(sessionId: string): ReturnType<SessionService['loadSessionContext']>;
+    createTaskWorker(config?: TaskRunnerConfig): Promise<TaskRunner>;
+    createScheduleWorker(config?: ScheduleRunnerConfig): Promise<ScheduleRunner>;
+    diagnostics(): DeployedRuntimeDiagnostics;
+    health(): DeployedRuntimeHealth;
+    readiness(): Promise<DeployedRuntimeReadiness>;
+    close(): Promise<void>;
+}
+
+export declare interface DeployedApplicationRuntimeOptions {
+    readonly profile: DeployedApplicationRuntimeProfile;
+    /** Validated selector overrides; never put credentials in this object. */
+    readonly providers?: RuntimeProviderOverrides;
+    readonly database: DeployedDatabaseBinding;
+    readonly authentication: DeployedProviderBinding<PublicAuthenticationProvider>;
+    readonly assets: DeployedProviderBinding<AssetStorageProvider>;
+    readonly secrets: DeployedProviderBinding<SecretProvider>;
+    /** Explicit, idempotent application migration hook. */
+    readonly prepareDatabase?: (db: DatabaseInterface) => Promise<void>;
+}
+
+export declare type DeployedApplicationRuntimeProfile = Exclude<ApplicationRuntimeProfile, 'local'>;
+
+export declare interface DeployedComponentReadiness {
+    readonly status: 'ready' | 'not-ready';
+}
+
+/** PostgreSQL connection factory. URLs and credentials stay in this adapter. */
+export declare interface DeployedDatabaseBinding {
+    readonly engine: 'postgres';
+    readonly connect: () => Promise<DatabaseInterface>;
+    readonly readiness?: (db: DatabaseInterface) => Promise<void>;
+    /**
+     * Provider-owned cleanup boundary, required before a connection is opened.
+     * Keeping cleanup on the binding also covers malformed connection handles.
+     */
+    readonly close: (db: DatabaseInterface) => Promise<void>;
+}
+
+/**
+ * A provider-owned readiness boundary.
+ *
+ * The callback should prove that required configuration is present and that
+ * the provider is usable. It must not return credentials or secret values.
+ */
+export declare interface DeployedProviderBinding<Provider extends string> {
+    readonly provider: Provider;
+    readonly readiness: () => Promise<void>;
+}
+
+export declare interface DeployedProviderDiagnostic {
+    readonly provider: string;
+    readonly configured: true;
+}
+
+/** Startup failure that retains the only safe retry path for database cleanup. */
+export declare class DeployedRuntimeCleanupError extends DeployedRuntimeError {
+    private readonly cleanup;
+    private cleaned;
+    private cleanupAttempt?;
+    constructor(cleanup: () => Promise<void>);
+    retryCleanup(): Promise<void>;
+}
+
+export declare type DeployedRuntimeComponent = 'database' | 'authentication' | 'assets' | 'secrets';
+
+export declare interface DeployedRuntimeDiagnostics {
+    readonly schemaVersion: 1;
+    readonly runtime: ResolvedApplicationRuntime;
+    readonly providers: {
+        readonly database: DeployedProviderDiagnostic;
+        readonly authentication: DeployedProviderDiagnostic;
+        readonly assets: DeployedProviderDiagnostic;
+        readonly secrets: DeployedProviderDiagnostic;
+    };
+    readonly tenancy: {
+        readonly mode: 'single-tenant' | 'multi-tenant';
+        readonly context: 'defaulted' | 'required';
+        readonly isolation: 'application' | 'database-rls';
+        readonly rootTenantFallback: 'disabled';
+    };
+    readonly workers: {
+        readonly topology: 'external' | 'scalable';
+        readonly taskProcess: 'separate';
+        readonly scheduleProcess: 'separate';
+        readonly replicas: 'operator-managed' | 'horizontal';
+    };
+    readonly secretValuesIncluded: false;
+}
+
+/** Stable failure that never includes a provider's underlying error text. */
+export declare class DeployedRuntimeError extends Error {
+    readonly code: DeployedRuntimeErrorCode;
+    readonly component?: DeployedRuntimeComponent | undefined;
+    constructor(code: DeployedRuntimeErrorCode, message: string, component?: DeployedRuntimeComponent | undefined);
+}
+
+export declare type DeployedRuntimeErrorCode = 'invalid_configuration' | 'provider_mismatch' | 'provider_unavailable' | 'tenant_context_required' | 'tenant_context_unauthorized' | 'runtime_stopped';
+
+export declare interface DeployedRuntimeHealth {
+    readonly schemaVersion: 1;
+    readonly profile: DeployedApplicationRuntimeProfile;
+    readonly status: 'healthy' | 'stopped';
+}
+
+export declare interface DeployedRuntimeReadiness {
+    readonly schemaVersion: 1;
+    readonly profile: DeployedApplicationRuntimeProfile;
+    readonly status: 'ready' | 'not-ready';
+    readonly components: Readonly<Record<DeployedRuntimeComponent, DeployedComponentReadiness>>;
+    readonly secretValuesIncluded: false;
+}
+
+/** Encode a package/project identity into a collision-resistant runtime ID. */
+export declare function encodeApplicationId(value: string): string;
+
+declare const ERROR_CODES: readonly ["authentication_unavailable", "database_unavailable", "migration_required", "provider_unavailable", "runtime_stopped", "worker_stale"];
+
+/**
+ * Initialize a self-hosted or cloud application composition.
+ *
+ * Configuration and provider identity are validated before a connection is
+ * opened. Provider readiness and database migrations complete before the
+ * runtime is returned. A failed initialization closes the acquired connection.
+ */
+export declare function initializeDeployedApplicationRuntime(options: DeployedApplicationRuntimeOptions): Promise<DeployedApplicationRuntime>;
+
 /**
  * Initialize or reopen a local application runtime.
  *
@@ -132,6 +274,25 @@ export declare interface LocalRuntimePaths {
     readonly applicationSecret: string;
 }
 
+export declare const MAX_RUNTIME_DIAGNOSTIC_ERRORS = 8;
+
+export declare const MAX_RUNTIME_DIAGNOSTIC_TOOLS = 64;
+
+/**
+ * Claim the secure local database root before a standalone migration command
+ * opens SQLite. This does not create application schema or bootstrap records.
+ */
+export declare function prepareLocalDatabaseStorage(options: ResolveLocalRuntimePathsOptions): Promise<LocalRuntimePaths>;
+
+/**
+ * Project private local/deployed state into the deterministic public contract.
+ * Unknown, oversized, nested, accessor-backed, or prohibited values are never
+ * copied. Invalid error codes become `runtime_error` at ingestion.
+ */
+export declare function projectRuntimeDiagnostics(input: RuntimeDiagnosticsProjectionInput): RuntimeDiagnostics;
+
+export declare type PublicAuthenticationProvider = Exclude<AuthenticationProvider, 'owner-bootstrap'>;
+
 /**
  * Resolve deterministic user-owned paths and reject source-tree placement.
  */
@@ -152,4 +313,72 @@ export declare interface ResolveLocalRuntimePathsOptions {
     env?: NodeJS.ProcessEnv;
 }
 
+export declare const RUNTIME_DIAGNOSTICS_SCHEMA_VERSION: 1;
+
+export declare const RUNTIME_WORKER_FRESHNESS_SECONDS = 120;
+
+declare type RuntimeDiagnosticErrorCode = (typeof ERROR_CODES)[number] | 'runtime_error';
+
+/**
+ * Versioned public diagnostics returned only after application authorization.
+ * Every field is a fixed allowlist projection; this is intentionally not a
+ * cleaned or serialized form of either private runtime diagnostics object.
+ */
+export declare interface RuntimeDiagnostics {
+    readonly schemaVersion: 1;
+    readonly profile: ApplicationRuntimeProfile | 'unknown';
+    readonly health: 'healthy' | 'degraded' | 'stopped' | 'unknown';
+    readonly schema: {
+        readonly status: 'ready' | 'not-ready' | 'unknown';
+        readonly migrations: 'current' | 'failed' | 'pending' | 'unknown';
+    };
+    readonly capabilities: readonly {
+        readonly id: CapabilityId;
+        readonly status: CapabilityStatus;
+    }[];
+    readonly tools: {
+        readonly names: readonly string[];
+        readonly count: number;
+        readonly digest: string;
+    };
+    readonly operationalDifferences: {
+        readonly backgroundJobs: 'disabled' | 'enabled';
+        readonly workerTopology: WorkerTopology;
+    };
+    readonly worker: {
+        readonly topology: WorkerTopology;
+        readonly liveness: 'alive' | 'not-required' | 'stale' | 'unknown';
+        readonly heartbeatAt: string | null;
+        readonly observedAt: string;
+    };
+    readonly recentErrors: readonly {
+        readonly code: RuntimeDiagnosticErrorCode;
+        readonly at: string;
+    }[];
+}
+
+export declare interface RuntimeDiagnosticsProjectionInput {
+    readonly profile?: unknown;
+    readonly health?: unknown;
+    readonly schema?: unknown;
+    readonly capabilities?: unknown;
+    readonly toolNames?: unknown;
+    readonly worker?: unknown;
+    readonly recentErrors?: unknown;
+    /** Required explicit clock seam; the projector never reads the process clock. */
+    readonly observedAt?: unknown;
+}
+
+/** Validate an explicit runtime identity. */
+export declare function validateApplicationId(value: string): string;
+
+/**
+ * Verify an already-initialized local database root without creating or
+ * changing any filesystem/database artifact. Operator read/copy/import paths
+ * use this boundary before opening SQLite outside the runtime bootstrap.
+ */
+export declare function validateLocalDatabaseStorage(options: ResolveLocalRuntimePathsOptions): Promise<LocalRuntimePaths>;
+
+declare type WorkerTopology = 'embedded' | 'external' | 'inline' | 'scalable';
+
 export { }