@happyvertical/smrt-app-runtime 0.53.2 → 0.53.4

package/AGENTS.md

@@ -68,6 +68,46 @@ Application infrastructure composition for the validated runtime profiles in
 - Cloud must keep required tenant context and must never introduce a root or
   unscoped tenant fallback. RLS remains an explicit deployment/migration choice.
 
+## SvelteKit entry (`./sveltekit`)
+
+- Server-only subpath; `@sveltejs/kit` is an optional peer and is externalized
+  in `vite.config.ts` (kit recognizes `redirect`/`fail` by class identity).
+  The root entry must never import kit or Svelte.
+- `createSmrtSvelteKitRuntime()` order is fixed: readiness gate → URL tenant
+  selection (`locals.selectedTenant*`, never tenant context, headers ignored) →
+  verified session (tenant context entered only when
+  `isSessionTenantAuthorized()` accepts it, else unauthenticated; never via
+  `createSessionHandler`, which re-runs `resolve` on downstream errors) →
+  publish `locals.tenantContext` only for that verified tenant.
+- `database-rls` isolation forces `postgresRls: true`, including on
+  `skipPaths` (anonymous principal). `resolve` runs at most once;
+  session-layer failure before it is a 500 with cleared locals.
+- In an RLS request `classOptions()`/`databaseConfig()` return the
+  transaction-bound request db (class `db` overrides win). Anything that
+  outlives a request (session service, tenant selector) must use the base
+  config, never these.
+- The writer lease, provider readiness, and onboarding file cleanup are
+  injected hooks. Apps pass the root entry's `acquireWriterLease` (over
+  `prepareApplicationStateRoot`) and `createProviderReadinessProbe`; deployed
+  startup fails closed without `providerReadiness`.
+- Owner setup re-checks loopback peer and loopback URL host per request and
+  returns only fixed `{ code, message }` failures.
+- `resolveApplicationId()` / `runtimeConfigurationFingerprint()` must stay
+  byte-compatible with process managers (golden vectors in tests).
+
+## Operator state (root entry)
+
+- One owner for the state shared by the web process and `smrt app`
+  (`@happyvertical/smrt-cli/app` re-exports these): `resolveApplicationStateRoot`
+  / `prepareApplicationStateRoot` (private app-bound mode-0700 root and
+  marker), `withOperationLock` (`operation.lock`), `acquireWriterLease` /
+  `readActiveWriterLease` (`writer.lease`), `reclaimStaleRecord`, and
+  `createProviderReadinessProbe` (`SMRT_*_READINESS_MODULE`, resolved from the
+  app root with Node's own ESM rules). File names, record formats, and
+  messages are a cross-process contract; never change them unilaterally.
+- Tests that hook `node:fs` interleavings must live in this package: from a
+  consumer the package is an externalized dependency a mock cannot reach.
+
 ## Public runtime diagnostics
 
 - `projectRuntimeDiagnostics()` is the only public diagnostic projection. It

package/README.md

@@ -102,6 +102,107 @@ 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.
 
+## SvelteKit entry
+
+`@happyvertical/smrt-app-runtime/sveltekit` composes the profile runtime,
+tenant selection, the signed session, and authorized-tenant locals so an app's
+server hooks are a few lines. `@sveltejs/kit` is an optional peer dependency;
+the root entry never imports it.
+
+```ts
+// src/hooks.server.ts
+import { createSmrtSvelteKitRuntime } from '@happyvertical/smrt-app-runtime/sveltekit';
+
+export const runtime = createSmrtSvelteKitRuntime({
+  prepareDatabase: runApplicationMigrations, // optional, idempotent
+});
+export const { handle, init } = runtime;
+```
+
+```ts
+// src/app.d.ts
+import type { SmrtRuntimeLocals } from '@happyvertical/smrt-app-runtime/sveltekit';
+declare global {
+  namespace App {
+    interface Locals extends SmrtRuntimeLocals {}
+  }
+}
+```
+
+`init` is the fail-closed startup gate (local runtime or deployed bindings) and
+`handle` waits for it, then runs, in order: URL tenant selection into
+`locals.selectedTenant*` (never tenant context; tenant headers are ignored),
+the signed session, and publication of `locals.tenantContext` only when the
+active context matches the verified session tenant. A session's tenant is
+accepted only for an active direct membership or a legitimately inherited
+one (`isSessionTenantAuthorized()`, the same rule deployed `restoreSession()`
+applies); otherwise the request is unauthenticated (no user, permissions,
+tenant, or tenant context). `database-rls` isolation always runs the request
+RLS transaction (`session.postgresRls` cannot disable it); a
+`session.skipPaths` prefix skips session loading only and still runs inside
+that transaction as an anonymous principal. During such a request
+`runtime.classOptions()` / `runtime.databaseConfig()` return the
+transaction-bound request database (unless the class has its own `db`
+override), so call them per request and never retain the result. Downstream code runs
+at most once: its error propagates unchanged, and a session-layer failure
+before it returns 500 with no authenticated locals. Defaults read `SMRT_APP_ID`, `SMRT_DATA_DIR`, `HOST`, `DATABASE_URL`,
+`TENANT_BASE_DOMAIN`, and `SMRT_BACKGROUND_JOBS`; `smrt.config` `runtime`
+selects the profile (local when absent). Deployed profiles additionally require
+`providerReadiness` probes and fail closed without them. Optional hooks:
+`acquireWriterLease` (local single-writer lease), `onBootstrapInvitation`
+(present a newly issued setup token), `selectTenant`, `session`, and
+`classOverrides`. `runtime.classOptions(className)` returns collection options
+for application code.
+
+Mountable routes:
+
+```ts
+// src/routes/api/_runtime/health/+server.ts
+export const GET = createRuntimeHealthHandler(runtime);
+// src/routes/api/_runtime/diagnostics/+server.ts
+export const GET = createRuntimeDiagnosticsHandler({ runtime, toolNames });
+// src/routes/setup/+page.server.ts
+export const { load, actions } = createOwnerSetupPage(runtime);
+// src/routes/+layout.server.ts
+export const load = createSessionLayoutLoad();
+```
+
+Diagnostics authorize (owner role or `runtime_diagnostics.read` on an active,
+session-matching membership) before reading the runtime and return only stable
+`{ schemaVersion: 1, error: { code } }` failures. Owner setup is local-only and
+re-checks on every request that both the peer address and the URL host are
+loopback; its `default` action reads `token`, `name`, `email`, and optional
+`tenantName`, sets the session cookie, and redirects 303, or returns
+`fail(status, { code, message })` with `setup_disabled` (404),
+`setup_unavailable` (403), `setup_invalid_input` (400), or `setup_invalid`
+(400). Claim error text is never returned.
+
+`resolveApplicationId()` and `runtimeConfigurationFingerprint()` (root entry)
+are the canonical app ID and secret-free configuration fingerprint shared by
+the web health route and process managers.
+
+The root entry also owns the operator state shared with `smrt app`:
+`prepareApplicationStateRoot()` (private, app-bound state directory),
+`withOperationLock()`, `acquireWriterLease()` / `readActiveWriterLease()`,
+and `createProviderReadinessProbe()`. A SvelteKit app wires the last two into
+its runtime without depending on the CLI:
+
+```ts
+import {
+  acquireWriterLease,
+  createProviderReadinessProbe,
+  prepareApplicationStateRoot,
+} from '@happyvertical/smrt-app-runtime';
+
+export const runtime = createSmrtSvelteKitRuntime({
+  acquireWriterLease: (context) =>
+    acquireWriterLease(prepareApplicationStateRoot(context), {
+      operationInstance: process.env.SMRT_OPERATION_INSTANCE,
+    }),
+  providerReadiness: createProviderReadinessProbe,
+});
+```
+
 ## Self-hosted and cloud applications
 
 The deployed initializer validates the selected profile against concrete,

package/dist/application-identity.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Canonical application identity shared by the web process, operator commands,
+ * and generated operational surfaces.
+ *
+ * Every process that manages the same application must derive the same app ID
+ * and the same configuration fingerprint, so these helpers live next to
+ * `validateApplicationId()` / `encodeApplicationId()` rather than in copied
+ * template scripts.
+ */
+export interface ResolveApplicationIdOptions {
+    /** Directory containing the application's `package.json`. Defaults to cwd. */
+    sourceRoot?: string;
+    /** Package name to encode instead of reading `package.json`. */
+    packageName?: string;
+    /** Explicit, strictly validated app ID (for example `SMRT_APP_ID`). */
+    explicitId?: string;
+}
+/**
+ * Resolve one stable application identity.
+ *
+ * An explicit ID is validated with {@link validateApplicationId}; otherwise
+ * the package name is encoded with {@link encodeApplicationId}.
+ */
+export declare function resolveApplicationId(options?: ResolveApplicationIdOptions): string;
+/**
+ * Runtime selection the fingerprint covers. Structural so operator tooling
+ * can fingerprint a resolved runtime it loaded itself; a
+ * {@link ResolvedApplicationRuntime} always satisfies it.
+ */
+export interface FingerprintRuntime {
+    readonly profile: string;
+    readonly providers: unknown;
+}
+/**
+ * Secret-safe identity used to reject stale managed processes after profile,
+ * provider, database-target, or listener configuration changes.
+ *
+ * Credentials, query strings, and fragments of `DATABASE_URL` are excluded;
+ * only `sslmode` survives. The digest is stable for identical inputs so a
+ * process manager and the web process can compare it.
+ */
+export declare function runtimeConfigurationFingerprint(runtime: FingerprintRuntime, environment?: Readonly<Record<string, string | undefined>>): string;
+//# sourceMappingURL=application-identity.d.ts.map

package/dist/application-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-identity.d.ts","sourceRoot":"","sources":["../src/application-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,MAAM,WAAW,2BAA2B;IAC1C,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,2BAAgC,GACxC,MAAM,CAeR;AAkBD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,kBAAkB,EAC3B,WAAW,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,GACtE,MAAM,CAyBR"}