@openlup/platform 0.0.0-stage → 0.15.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+Notable changes to this public-source workspace package are recorded here.
+“Unreleased” means no npm version carries the change yet; immutable OpenLup
+source previews may already ship some changes, and their release notes say
+which. Declaration snapshots track candidate drift, not a stable API or
+SemVer promise.
+
+## [Unreleased]
+
+## [0.15.0]
+
+- Publishable on the npm `latest` dist-tag as `0.15.0`, from tag
+  `openlup-platform-v0.15.0`.
+
+- First publication of `@openlup/platform`, the server substrate for an OpenLup application, with one module subpath each for `http`, `bff`, `scheduler`, `blob`, `data`, `migrations`, `job-ledger`, `kernel` and `composition`.
+- Transport-neutral scheduled jobs: a `run(context)` contract, an empty job registry, a lease-aware runner and an authenticated HTTP cron entry, with a constant-time cron secret comparison.
+- Per-capability bundle readiness that refuses an unknown bundle and reports every missing scheduler, lock and blob setting together.
+- Blob capability selection with filesystem, Vercel Blob, Supabase Storage and S3 bindings; `pg`, `@types/pg` and `@aws-sdk/client-s3` are optional peers, and an adapter refuses a missing peer with `OPENLUP_E_PEER_MISSING`.

package/LICENSE

@@ -0,0 +1,204 @@
+Copyright (c) 2026 Bartlomiej Roszkowski
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# @openlup/platform
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Development preview. This package joins core and outbox in the publishable set from the next set version; this configuration does not establish a registry release or a stable API. Its repository-directory publish command refuses publication; the authorized package-release workflow owns publication.
+
+It holds the runnable server substrate an OpenLup application composes: the Node HTTP runtime, BFF dispatch, scheduling and job leases, blob storage, data gateways, the node-postgres migration runner and bundle composition. Ports and their contracts stay in `@openlup/core/platform-runtime`.
+
+## Package surface
+
+`release-gates.json` declares kind `rail`: this foundation provides runtime infrastructure over core ports, matching the architecture's rail responsibility. Its nine experimental entries each bind a declaration snapshot and package-owned smoke tests. The API checker reads this same inventory.
+
+| Export | Contents |
+| --- | --- |
+| `./http` | Node request adaptation, deadlines, security headers and static documents, and `createNodeHttpRuntime` with its fixed request order |
+| `./bff` | `createBffDispatcher`, `lazyBffRoute`, the hosted router URL rewrite, the response envelope (`createBffResponder`), the observed request context and the health route |
+| `./scheduler` | Transport-neutral scheduled jobs (`ScheduledJob`, the job registry, the lease-aware runner and the authenticated HTTP cron entry), path-declared jobs from configuration, the node-cron scheduler with per-job advisory locks, hosted cron verification, the cron entrypoint guard (it compares the presented bearer token with `CRON_SECRET` in constant time) and direct job bindings |
+| `./blob` | Filesystem, S3-compatible, Supabase Storage and Vercel Blob adapters, and `bindBlobPort` |
+| `./data` | Supabase and node-postgres data gateways, the role-free transaction lane, the query builder and the data bindings |
+| `./migrations` | The node-postgres `MigrationRunnerPort` |
+| `./job-ledger` | The job-run ledger port, its PostgreSQL and managed (Supabase) adapters, the managed v2/v3 compatibility calls and the location of its SQL |
+| `./kernel` | The bundle identifiers, descriptors and readiness |
+| `./composition` | `createBundleComposer`, the Node HTTP binding helpers and `createNodeHost` |
+
+## Scheduled jobs
+
+A job is `{ id, schedule, lease?, run(context) }` with a UTC cron expression. Domains and packages contribute jobs to `createScheduledJobRegistry`, which refuses duplicate ids and ships empty. The Node host runs registry jobs on its own timers and calls `run` directly, with no HTTP request and no secret. `createScheduledJobHttpEntry` mounts the same job behind the cron guard for a hosted cron. A job that declares `lease` runs only after the injected job-lease port grants it; a lease held elsewhere skips the run, and a finish the port refuses fails the run. `scheduledJobsFromContribution` turns a contribution's cadence schedules into jobs and refuses a cadence that no cron expression matches exactly; a contribution run that reports a failed outcome fails the job.
+
+## Bundle readiness
+
+`PLATFORM_BUNDLE` selects `vercel-supabase` (the default when absent), `node-supabase` or `node-postgres`. A bundle's readiness refuses, before any traffic or timer: an unknown `PLATFORM_BUNDLE` (resolution itself still falls back to the default); a self-host bundle without `APP_BASE_URL`; and, reported together under `OPENLUP_E_ENV_MISSING`, every selected capability without its settings: the scheduler without `CRON_SECRET`, Node scheduling without `DATABASE_URL` for its cluster lock (never a silent single-instance lock), and the selected blob capability without its settings (see Blob storage). An unknown `PLATFORM_BLOB` is refused too. The Node host checks readiness at boot.
+
+## Blob storage
+
+`PLATFORM_BLOB` selects the blob capability; without it the bundle's own applies (filesystem for node-postgres, the local development default). `bindBlobPort` builds each one from the environment and the clients the application injects:
+
+- `filesystem`: `BLOB_FS_ROOT`, `BLOB_FS_BASE_URL`;
+- `s3`: `BLOB_S3_BUCKET`, `BLOB_S3_BASE_URL`, and a default client from `createS3ClientFromEnv` (`BLOB_S3_REGION`, `BLOB_S3_ENDPOINT`, `BLOB_S3_FORCE_PATH_STYLE`, `BLOB_S3_ACCESS_KEY_ID` with `BLOB_S3_SECRET_ACCESS_KEY`). `@aws-sdk/client-s3` is an optional peer loaded on first use, so only an application that selects S3 installs it;
+- `supabase`: `BLOB_SUPABASE_BUCKET` and `BlobBindingDeps.supabaseStorageClient`, a factory returning the structural `SupabaseStorageClient` declared in blob. Blob itself reads no data-gateway settings. The default composer supplies this factory from the data-gateway settings and its optional `createSupabaseClient` dependency, using the service-role key with `persistSession: false` and `autoRefreshToken: false`. For this binding, a blank `SUPABASE_URL` falls back to `VITE_SUPABASE_URL`, consistently with readiness;
+- `vercel-blob`: the injected `@vercel/blob` module and `BLOB_READ_WRITE_TOKEN`.
+
+The Node host passes the composed ports, blob storage included, to the HTTP runtime builder and to the jobs contributed to it. The reference repository's compose file starts a local S3-compatible service with `--profile local-storage`; missing storage credentials refuse at service startup, while an omitted `OBJECT_STORAGE_PORT` selects an ephemeral loopback port. The inactive profile requires no storage settings. A conformance test runs upload, read-back, delete and access refusal against that image; initialization failure with Docker available fails the test. Hosted S3 provider certification is not claimed.
+
+## What the application supplies
+
+The package carries no deployment identity. The application passes it every value that names a deployment or a domain:
+
+- the BFF route table, the not-found response, the request preflight and the per-request hook;
+- how a request reference is chosen, and the health payload with its strict contract;
+- the security header policy, including the content security policy, the production hosts and the robots.txt body;
+- its own entrypoints, by exact path or by path rule;
+- the job configuration file or object, the direct job bindings and the host admission check;
+- the migration catalogue, the migration lock name and the object-inventory projector;
+- the release correlation, default failure reason and read-failure messages that the job-run ledgers record;
+- the environment, passed explicitly, and the provider clients it needs (the Supabase `createClient`, the `@vercel/blob` module, optionally its own PostgreSQL gateway factory), so the package itself reads no environment variable (an injected SDK may read its own credentials; the static and migration roots default to the working directory). Its optional SDK peers are `pg`, whose types its PostgreSQL declarations use, and `@aws-sdk/client-s3`, loaded lazily by the default S3 client. Blob declarations use structural types and need no S3 SDK;
+- an optional scheduler profile for the Node host: a fenced projection of the declared jobs with its own bindings and validation hooks.
+
+`createBundleComposer` binds the blob slot by default; pass `createBundleComposer({ createSupabaseClient })` to enable its Supabase Storage binding when the data-gateway settings and bucket are present. Without that client Supabase Storage stays unbound. A custom `blob` binder still overrides the default. The HTTP, scheduler, data, migrations, analytics and transactional slots stay `null` until the application supplies their binders; `createDataBindings` builds the data binder from the application's database client factory.
+
+## Job-run ledger SQL
+
+`JOB_RUN_LEDGER_MIGRATIONS` lists the two files a fresh installation applies, in order, through its own migration chain:
+
+1. [`sql/20260809150000_job_run_ledger.sql`](sql/20260809150000_job_run_ledger.sql): the job controls, runs, and the v2 claim and finish; its bytes and migration identity equal the reference application's platform migration of that name.
+2. [`sql/20260809150001_job_run_ledger_v3.sql`](sql/20260809150001_job_run_ledger_v3.sql): the v3 claim and finish the PostgreSQL ledger calls, as `CREATE OR REPLACE`, with bodies byte-equal to the reference chain's definitions.
+
+The package SQL and the reference application's platform migration chain are alternative install paths, never applied together: the reference chain defines all four job-control functions itself, with plain `CREATE FUNCTION`, so it fails on a database where the package SQL already created them. The package file `20260809150001_job_run_ledger_v3` has a migration identity no reference migration uses. Importing the package never applies SQL.
+
+## Optional peers
+
+`pg`, `@types/pg` and `@aws-sdk/client-s3` are optional peers. Install `pg` and
+`@types/pg` alongside this package when selecting PostgreSQL adapters; install
+`@aws-sdk/client-s3` when selecting S3 blob storage. Loading an unselected adapter
+never installs or initializes its SDK. The PostgreSQL scheduler lock also loads
+`pg` only on its first operation.
+
+A selected capability whose SDK is absent rejects its first loading operation
+with `OPENLUP_E_PEER_MISSING: <package> is required by <capability>; install it
+alongside @openlup/platform`. The original module-resolution error is the cause.
+A broken SDK, a missing transitive dependency or a provider error propagates
+unchanged. Blob `exists` retains its boolean contract and returns false on a
+failed HEAD; use an upload or list operation to observe an S3 loading refusal.
+
+## Verification
+
+This package's tests are part of the repository's required test selection; from this directory, `npm test` runs them alone. The tests rewrite the originating application's characterization with neutral names and synthetic data, and a boundary test refuses any environment read or provider import in the package source.
+
+`npm run api:check` compares each of the nine declaration entry graphs with the
+committed `api/*.api.md` reports. After building, deliberately regenerate them
+with `node --experimental-strip-types ./scripts/api-contract.ts --update` from
+this package, and review the declaration changes.
+
+The source-checkout binding `npm run test:consumer` runs
+[`platform-cold-consumer.ts`](../../scripts/packages/platform-cold-consumer.ts).
+It requires the cold package producer's verified `OPENLUP_PACK_MANIFEST` and
+exact `OPENLUP_PACK_COMMIT`; it never substitutes a workspace build or repacks
+on refusal. `ci:required` invokes that proof; API checks remain in the shared
+cheap phase. The producer must include publishable core and platform tarballs;
+the package inventory includes both at the same set version. Cold packing requires a clean committed package tree; an uncommitted preparation cannot produce the manifest.
+
+The proof installs those tarballs, locked Zod and explicit Node type tooling
+offline from the default npm cache into an OS temporary directory outside the checkout.
+It verifies optional-peer absence physically and through both CommonJS and ESM
+resolution, refuses symlinks and ancestor package sources, checks the complete
+export classification, imports every nonadapter entry with an empty environment,
+and compiles its types in strict NodeNext and Bundler modes without skipping
+library checks. A type leak fails the proof even if runtime imports pass.
+
+It then checks actual missing-SDK refusals, installs the three peers at the root
+lockfile's exact versions using `npm install --prefer-offline --no-audit --fund=false`
+and the default npm cache, compiles all adapter declarations and runs the real SDKs against owned
+in-memory fixtures: S3 upload/HEAD/list/delete through the real SDK and
+deterministic invalid-URL refusals after the default SDK/driver loads.
+These fixtures contact no live provider. The PostgreSQL adapters then run their SQL conformance
+against a disposable database: the CI job's pinned PostgreSQL service when the job supplies its
+identity (`OPENLUP_PROOF_SERVICE_CONTAINER` and `OPENLUP_PROOF_SERVICE_PORT`), as the outbox proof
+uses it, or otherwise an owned, labelled container of the same pinned image. There is no skip:
+without either the proof fails. Temporary consumer files, the proof database and an owned container
+are removed on completion. Missing cached packages fail the initial offline installation;
+the SDK-present install can fetch missing registry metadata or packages. Neither
+phase redirects npm to an empty temporary cache.
+
+The composition declarations describe the injected Supabase factory structurally;
+they do not import the data entry or its PostgreSQL types. The cold proof still
+requires all five nonadapter entries to import in fresh processes and compile
+in both resolution modes with all three optional peers absent.
+
+<!-- openlup-doc-impact {"unit":"platform-substrate","digest":"sha256-00994d288cfec0c8dc0ae9aeae2ff542e2e9af2fedcb4dd2dfeb6c99523be92d","reason":"The manifest moves to the 0.15.0 set version with the exact @openlup/core 0.15.0 peer pin. The package surface, settings and verification described here are unchanged by this preparation delta."} -->

package/dist/bff/dispatch.d.ts

@@ -0,0 +1,27 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+export type RouteEntry = {
+    route: string;
+    pattern: RegExp;
+    params: string[];
+    handler: (req: HttpRequest, res: HttpResponse) => unknown;
+    /** Fail unsupported hosted bundles closed before auth without weakening direct-route auth. */
+    availability?: "direct-postgres";
+};
+/** Match `routes` against one request and run the handler, or answer not found. */
+export type BffDispatch = (routes: readonly RouteEntry[], req: HttpRequest, res: HttpResponse) => Promise<unknown>;
+export interface BffDispatcherOptions {
+    /** Environment read on each request to decide a route's bundle availability. */
+    env: () => Record<string, string | undefined>;
+    /** Writes the deployment's not-found response for an unmatched or unavailable path. */
+    notFound: (res: HttpResponse, pathname: string) => void;
+    /** Runs once per request before matching (for example, ambient request configuration). */
+    beforeDispatch?: () => void;
+    /**
+     * Runs after matching and before the handler, for example route authorization; resolving false
+     * means it already answered. Required, so no composition skips it by omission; a deployment
+     * without guarded routes passes `() => true`.
+     */
+    preflight: (req: HttpRequest, res: HttpResponse, route: string) => Promise<boolean> | boolean;
+}
+/** Build the dispatcher a deployment mounts on its hosted and Node entrypoints alike. */
+export declare function createBffDispatcher(options: BffDispatcherOptions): BffDispatch;

package/dist/bff/dispatch.js

@@ -0,0 +1,47 @@
+// BFF dispatch mechanism.
+//
+// The route table and its handlers belong to the deployment. This module owns the
+// platform-neutral matching loop, so every HttpRuntimePort adapter (a hosted function or the Node
+// runtime of this package) mounts the same route table without duplicating dispatch logic.
+//
+// Per request, in order: the deployment's `beforeDispatch` hook, path normalization, the first
+// matching route, its availability, its decoded path parameters, the deployment's `preflight`
+// hook, then the handler. An unmatched or unavailable path goes to the deployment's `notFound`.
+import { getBundleDescriptor, resolveBundleId } from "../kernel/index.js";
+// Only the pathname is read, and it does not depend on the URL base; this host only completes a
+// request that carries no Host header.
+const FALLBACK_HOST = "bff.invalid";
+function requestPath(req) {
+    const rawUrl = typeof req.url === "string" ? req.url : "/";
+    const host = typeof req.headers?.host === "string" ? req.headers.host : FALLBACK_HOST;
+    return new URL(rawUrl, "https://" + host).pathname.replace(/\/+$/, "") || "/";
+}
+/** Build the dispatcher a deployment mounts on its hosted and Node entrypoints alike. */
+export function createBffDispatcher(options) {
+    return async function dispatch(routes, req, res) {
+        options.beforeDispatch?.();
+        const pathname = requestPath(req);
+        for (const entry of routes) {
+            const match = entry.pattern.exec(pathname);
+            if (!match)
+                continue;
+            if (entry.availability === "direct-postgres"
+                && getBundleDescriptor(resolveBundleId(options.env())).capabilities.data !== "postgres") {
+                options.notFound(res, pathname);
+                return undefined;
+            }
+            if (entry.params.length > 0) {
+                const query = { ...(req.query ?? {}) };
+                entry.params.forEach((param, index) => {
+                    query[param] = decodeURIComponent(match[index + 1] ?? "");
+                });
+                req.query = query;
+            }
+            if (!(await options.preflight(req, res, entry.route)))
+                return undefined;
+            return entry.handler(req, res);
+        }
+        options.notFound(res, pathname);
+        return undefined;
+    };
+}

package/dist/bff/envelope.d.ts

@@ -0,0 +1,46 @@
+import type { HttpResponse } from "../http/index.js";
+export declare const BFF_REQUEST_REFERENCE_HEADER = "x-request-id";
+export declare const BFF_ERROR_CODES: readonly ["BAD_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "METHOD_NOT_ALLOWED", "CONFLICT", "RATE_LIMITED", "UPSTREAM_UNAVAILABLE", "INTERNAL", "INVALID_RESPONSE"];
+export type BffErrorCode = (typeof BFF_ERROR_CODES)[number];
+export type BffMeta = {
+    requestId?: string;
+    contractVersion?: string;
+    [key: string]: unknown;
+};
+export type BffError = {
+    code: BffErrorCode;
+    message: string;
+    details?: unknown;
+};
+export type BffSuccessResponse<T> = {
+    ok: true;
+    data: T;
+    meta?: BffMeta;
+};
+export type BffErrorResponse = {
+    ok: false;
+    error: BffError;
+    meta?: BffMeta;
+};
+export type BffResponse<T> = BffSuccessResponse<T> | BffErrorResponse;
+/** The HTTP status each error code answers with unless the caller names another. */
+export declare const BFF_ERROR_STATUS: Readonly<Record<BffErrorCode, number>>;
+export interface BffErrorOptions {
+    status?: number;
+    details?: unknown;
+    meta?: BffMeta;
+}
+export interface BffSuccessOptions {
+    cacheControl?: string;
+}
+export interface BffResponderOptions {
+    /** The request reference observed for this response, if the deployment records one. */
+    responseRequestId?: (res: HttpResponse) => string | undefined;
+}
+export interface BffResponder {
+    sendBffSuccess<T>(res: HttpResponse, data: T, meta?: BffMeta, options?: BffSuccessOptions): void;
+    sendBffError(res: HttpResponse, code: BffErrorCode, message: string, options?: BffErrorOptions): void;
+    sendMethodNotAllowed(res: HttpResponse, allowedMethods: readonly string[]): void;
+}
+/** Build the envelope writers a deployment's handlers share. */
+export declare function createBffResponder(options?: BffResponderOptions): BffResponder;

package/dist/bff/envelope.js

@@ -0,0 +1,80 @@
+// BFF response envelope.
+//
+// Every BFF response is JSON `{ ok: true, data, meta? }` or `{ ok: false, error: { code, message,
+// details? }, meta? }`. A private response carries the request reference in the `x-request-id`
+// header and, for errors or responses with meta, in `meta.requestId`; a shared-cache response
+// (public or s-maxage) carries neither. `undefined` members are stripped before serialization.
+export const BFF_REQUEST_REFERENCE_HEADER = "x-request-id";
+export const BFF_ERROR_CODES = [
+    "BAD_REQUEST",
+    "UNAUTHORIZED",
+    "FORBIDDEN",
+    "NOT_FOUND",
+    "METHOD_NOT_ALLOWED",
+    "CONFLICT",
+    "RATE_LIMITED",
+    "UPSTREAM_UNAVAILABLE",
+    "INTERNAL",
+    "INVALID_RESPONSE",
+];
+/** The HTTP status each error code answers with unless the caller names another. */
+export const BFF_ERROR_STATUS = {
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    METHOD_NOT_ALLOWED: 405,
+    CONFLICT: 409,
+    RATE_LIMITED: 429,
+    UPSTREAM_UNAVAILABLE: 503,
+    INTERNAL: 500,
+    INVALID_RESPONSE: 502,
+};
+/** Build the envelope writers a deployment's handlers share. */
+export function createBffResponder(options = {}) {
+    function sendBffSuccess(res, data, meta, successOptions = {}) {
+        sendJson(res, 200, { ok: true, data, meta }, successOptions.cacheControl);
+    }
+    function sendBffError(res, code, message, errorOptions = {}) {
+        sendJson(res, errorOptions.status ?? BFF_ERROR_STATUS[code], {
+            ok: false,
+            error: { code, message, details: errorOptions.details },
+            meta: errorOptions.meta,
+        });
+    }
+    function sendMethodNotAllowed(res, allowedMethods) {
+        res.setHeader("Allow", allowedMethods.join(", "));
+        sendBffError(res, "METHOD_NOT_ALLOWED", "Method not allowed", { status: 405 });
+    }
+    function sendJson(res, status, body, cacheControl = "no-store") {
+        const shared = /(?:^|,)\s*(?:public\b|s-maxage\s*=)/i.test(cacheControl);
+        const requestId = shared ? undefined : options.responseRequestId?.(res);
+        const responseBody = withRequestReference(body, requestId, shared);
+        res.setHeader("Content-Type", "application/json");
+        res.setHeader("Cache-Control", cacheControl);
+        if (shared && typeof res.removeHeader === "function")
+            res.removeHeader(BFF_REQUEST_REFERENCE_HEADER);
+        else if (requestId)
+            res.setHeader(BFF_REQUEST_REFERENCE_HEADER, requestId);
+        res.status(status).json(stripUndefined(responseBody));
+    }
+    return { sendBffSuccess, sendBffError, sendMethodNotAllowed };
+}
+function withRequestReference(body, requestId, omitRequestId) {
+    if (requestId && (body.ok === false || body.meta)) {
+        return { ...body, meta: { ...body.meta, requestId } };
+    }
+    if (!omitRequestId || !body.meta || !("requestId" in body.meta))
+        return body;
+    const { requestId: _omitted, ...meta } = body.meta;
+    return { ...body, meta: Object.keys(meta).length > 0 ? meta : undefined };
+}
+function stripUndefined(value) {
+    if (Array.isArray(value))
+        return value.map(stripUndefined);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .map(([key, entryValue]) => [key, stripUndefined(entryValue)]));
+}

package/dist/bff/health.d.ts

@@ -0,0 +1,24 @@
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import type { BffResponder } from "./envelope.js";
+export interface HealthContract<T extends {
+    contractVersion: string;
+}> {
+    safeParse(value: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+    };
+}
+export interface HealthHandlerOptions<T extends {
+    contractVersion: string;
+}> {
+    responder: BffResponder;
+    /** The deployment's strict health contract. */
+    contract: HealthContract<T>;
+    /** Builds this request's health payload: service identity, release provenance and the rest. */
+    read: () => unknown;
+}
+export declare function createHealthHandler<T extends {
+    contractVersion: string;
+}>(options: HealthHandlerOptions<T>): (req: HttpRequest, res: HttpResponse) => void;

package/dist/bff/health.js

@@ -0,0 +1,19 @@
+// BFF health route.
+//
+// GET answers the deployment's health payload, validated by the deployment's strict contract, with
+// the payload's contract version in `meta`; any other method answers 405 with `Allow: GET`. A
+// payload that fails its own contract answers INTERNAL rather than an unchecked body.
+export function createHealthHandler(options) {
+    return function health(req, res) {
+        if (req.method !== "GET") {
+            options.responder.sendMethodNotAllowed(res, ["GET"]);
+            return;
+        }
+        const result = options.contract.safeParse(options.read());
+        if (!result.success) {
+            options.responder.sendBffError(res, "INTERNAL", "Health contract is invalid");
+            return;
+        }
+        options.responder.sendBffSuccess(res, result.data, { contractVersion: result.data.contractVersion });
+    };
+}

package/dist/bff/index.d.ts

@@ -0,0 +1,6 @@
+export { createBffDispatcher, type BffDispatch, type BffDispatcherOptions, type RouteEntry } from "./dispatch.js";
+export { lazyBffRoute } from "./lazyRoute.js";
+export { rewriteBffRouterRequestUrl } from "./routerRewrite.js";
+export { BFF_ERROR_CODES, BFF_ERROR_STATUS, BFF_REQUEST_REFERENCE_HEADER, createBffResponder, type BffError, type BffErrorCode, type BffErrorOptions, type BffErrorResponse, type BffMeta, type BffResponder, type BffResponderOptions, type BffResponse, type BffSuccessOptions, type BffSuccessResponse, } from "./envelope.js";
+export { createHealthHandler, type HealthContract, type HealthHandlerOptions, } from "./health.js";
+export { createRequestContextStore, type ObservedRequestContext, type RequestContextOptions, type RequestContextStore, } from "./requestContext.js";

package/dist/bff/index.js

@@ -0,0 +1,6 @@
+export { createBffDispatcher } from "./dispatch.js";
+export { lazyBffRoute } from "./lazyRoute.js";
+export { rewriteBffRouterRequestUrl } from "./routerRewrite.js";
+export { BFF_ERROR_CODES, BFF_ERROR_STATUS, BFF_REQUEST_REFERENCE_HEADER, createBffResponder, } from "./envelope.js";
+export { createHealthHandler, } from "./health.js";
+export { createRequestContextStore, } from "./requestContext.js";

package/dist/bff/lazyRoute.d.ts

@@ -0,0 +1,4 @@
+import type { RouteEntry } from "./dispatch.js";
+export declare function lazyBffRoute(load: () => Promise<{
+    default: RouteEntry["handler"];
+}>): RouteEntry["handler"];

package/dist/bff/lazyRoute.js

@@ -0,0 +1,13 @@
+export function lazyBffRoute(load) {
+    let handler;
+    let loading;
+    return (req, res) => {
+        if (handler)
+            return handler(req, res);
+        loading ??= load().then((module) => (handler = module.default), (error) => {
+            loading = undefined;
+            throw error;
+        });
+        return loading.then((loaded) => loaded(req, res));
+    };
+}