@happyvertical/smrt-app-runtime 0.43.9 → 0.43.10

package/AGENTS.md

@@ -18,9 +18,40 @@ Application infrastructure composition for the validated runtime profiles in
 - 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.
+
 ## 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,6 +1,12 @@
+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';
@@ -14,6 +20,131 @@ 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;
+}
+
+/**
+ * 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 +263,8 @@ export declare interface LocalRuntimePaths {
     readonly applicationSecret: string;
 }
 
+export declare type PublicAuthenticationProvider = Exclude<AuthenticationProvider, 'owner-bootstrap'>;
+
 /**
  * Resolve deterministic user-owned paths and reject source-tree placement.
  */