@openlup/platform 0.0.0-stage → 0.15.0

package/dist/http/runtime.js

@@ -0,0 +1,199 @@
+// Native Node adapter for manifest-driven public routing and API topology.
+//
+// The request order is fixed: trailing-slash redirect, the CSP report entrypoint, deployment
+// exact-path entrypoints, the BFF router entrypoint, deployment path entrypoints, the BFF
+// dispatcher, robots.txt, declared scheduled routes, the API 404, legacy redirects, deployment
+// fallback path entrypoints, then static documents. Every deployment value (routes, entrypoints,
+// header policy, robots policy, deadlines) is supplied by the composition root.
+import { createServer } from "node:http";
+import { adaptRequest, decorateRequest, decorateResponse, NodeRequestAbortedError, NodeRequestBodyTooLargeError, } from "./requestAdapter.js";
+import { closeInputAfterResponse, runWithHttpDeadline } from "./deadline.js";
+import { applySecurityHeaders, serveSpaStatic, } from "./security.js";
+const SCHEDULED_PREFIX = "/api/cron/";
+const ROBOTS_CONTENT_TYPE = "text/plain; charset=utf-8";
+const EMPTY_ROUTING = { legacyRedirects: [], ssgPaths: [], csrFallback: { exactPaths: [], routeFamilies: [] } };
+function requestUrl(req) {
+    return new URL(req.url ?? "/", "http://node.local");
+}
+function capturesFor(source, pathname) {
+    const sourceParts = source.split("/").slice(1);
+    const pathParts = pathname.split("/").slice(1);
+    const captures = {};
+    let cursor = 0;
+    for (const sourcePart of sourceParts) {
+        if (!sourcePart.startsWith(":")) {
+            if (pathParts[cursor++] !== sourcePart)
+                return null;
+            continue;
+        }
+        const name = sourcePart.slice(1).replace(/\*$/, "");
+        if (sourcePart.endsWith("*")) {
+            captures[name] = pathParts.slice(cursor).join("/");
+            cursor = pathParts.length;
+            break;
+        }
+        const value = pathParts[cursor++];
+        if (!value)
+            return null;
+        captures[name] = value;
+    }
+    return cursor === pathParts.length ? captures : null;
+}
+function legacyRedirect(pathname, redirects) {
+    for (const redirect of redirects) {
+        const captures = capturesFor(redirect.source, pathname);
+        if (!captures)
+            continue;
+        return redirect.destination.replace(/:([A-Za-z][A-Za-z0-9_]*)\*?/g, (_match, name) => captures[name] ?? "");
+    }
+    return null;
+}
+function isCsrFallback(pathname, csrFallback) {
+    return csrFallback.exactPaths.includes(pathname)
+        || csrFallback.routeFamilies.some((path) => pathname === path || pathname.startsWith(`${path}/`));
+}
+function finalize(res) {
+    if (!res.writableEnded && !res.destroyed)
+        res.end();
+}
+function matchPathEntrypoint(entrypoints, pathname) {
+    for (const entrypoint of entrypoints ?? []) {
+        const query = entrypoint.match(pathname);
+        if (query)
+            return { entrypoint, query };
+    }
+    return null;
+}
+/** Build the runtime's request handler (exported for unit tests; wraps every dispatch path). */
+export function createRequestHandler(options) {
+    const onError = options.onError ?? ((ctx, err) => console.error(`[node-http] ${ctx}`, err));
+    const staticReader = options.staticReader;
+    const routing = options.routing ?? EMPTY_ROUTING;
+    const ssgPaths = new Set(routing.ssgPaths);
+    // Built once; a deployment can deliberately replace an inherited path.
+    const extra = new Map((options.extraEntrypoints ?? []).map((entry) => [entry.path, entry]));
+    return async function handle(req, res) {
+        const url = requestUrl(req);
+        const pathname = url.pathname;
+        const host = req.headers.host;
+        const bounded = (durationMs, run) => runWithHttpDeadline({ req, res, durationMs, run, onLateError: (error) => onError(`${pathname}:late`, error) });
+        const invoke = (loader, durationMs, rawStream, query) => bounded(durationMs, async () => {
+            const [mod, vreq] = await Promise.all([loader(), adaptRequest(req, pathname, rawStream)]);
+            if (query)
+                vreq.query = { ...vreq.query, ...query };
+            await mod.default(vreq, res);
+        });
+        try {
+            applySecurityHeaders(res, pathname, host, options.security);
+            if (pathname.length > 1 && pathname.endsWith("/")) {
+                res.statusCode = 308;
+                res.setHeader("location", `${pathname.replace(/\/+$/, "")}${url.search}`);
+                return finalize(res);
+            }
+            // 1. Standalone entrypoints (filesystem-parity with api/*.ts).
+            const cspReport = options.entrypoints?.cspReport;
+            if (pathname === "/api/csp-report" && cspReport) {
+                await invoke(cspReport, options.durations?.cspReport ?? 30_000);
+                return finalize(res);
+            }
+            // 1b. Deployment entrypoints: exact path, lazy load, owner-declared body policy.
+            const registered = extra.get(pathname);
+            if (registered) {
+                await invoke(registered.load, registered.maxDurationMs ?? 30_000, registered.rawStream);
+                return finalize(res);
+            }
+            const bffRouter = options.entrypoints?.bffRouter;
+            if (pathname === "/api/bff-router" && bffRouter) {
+                await invoke(bffRouter, options.durations?.bffRouter ?? 30_000);
+                return finalize(res);
+            }
+            // 1c. Deployment path-rule entrypoints, before the BFF dispatcher.
+            const routed = matchPathEntrypoint(options.pathEntrypoints, pathname);
+            if (routed) {
+                await invoke(routed.entrypoint.load, routed.entrypoint.maxDurationMs ?? 10_000, false, routed.query);
+                return finalize(res);
+            }
+            // 2. The BFF dispatcher (same routes + dispatch as the hosted entrypoint).
+            if (pathname === "/api/bff" || pathname.startsWith("/api/bff/")) {
+                await bounded(options.durations?.bff ?? 30_000, async () => options.dispatch(options.routes, await adaptRequest(req, pathname), res));
+                return finalize(res);
+            }
+            if (pathname === "/robots.txt" && options.robotsTxt) {
+                res.statusCode = 200;
+                res.setHeader("content-type", ROBOTS_CONTENT_TYPE);
+                res.setHeader("cache-control", "public, max-age=0, s-maxage=300, stale-while-revalidate=3600");
+                res.end(options.robotsTxt(host));
+                return;
+            }
+            // 3. Scheduled routes share the scheduler's single-source allowlist.
+            if (pathname.startsWith(SCHEDULED_PREFIX)) {
+                const jobId = pathname.slice(SCHEDULED_PREFIX.length);
+                const loader = options.scheduledEntrypoint?.(jobId);
+                if (loader) {
+                    await invoke(loader, options.durations?.scheduled?.(jobId) ?? 60_000);
+                    return finalize(res);
+                }
+            }
+            // 4. Unknown /api/* => 404 JSON (never fall through to the SPA).
+            if (pathname.startsWith("/api/")) {
+                res.statusCode = 404;
+                res.setHeader("content-type", "application/json; charset=utf-8");
+                res.end(JSON.stringify({ ok: false, error: { code: "NOT_FOUND", message: "Not found" } }));
+                return;
+            }
+            const legacyLocation = legacyRedirect(pathname, routing.legacyRedirects);
+            if (legacyLocation) {
+                res.statusCode = 308;
+                res.setHeader("location", `${legacyLocation}${url.search}`);
+                return finalize(res);
+            }
+            const fallback = matchPathEntrypoint(options.fallbackPathEntrypoints, pathname);
+            if (fallback) {
+                await invoke(fallback.entrypoint.load, fallback.entrypoint.maxDurationMs ?? 10_000, false, fallback.query);
+                return finalize(res);
+            }
+            // 5. Static documents and declared CSR fallback. Unknown extensionless routes are 404.
+            if (staticReader) {
+                await serveSpaStatic(req, res, pathname, staticReader, ssgPaths.has(pathname), isCsrFallback(pathname, routing.csrFallback));
+                return;
+            }
+            // No static reader configured (pure-API smoke): respond 404 rather than hang.
+            res.statusCode = 404;
+            res.end("Not Found");
+        }
+        catch (error) {
+            if (error instanceof NodeRequestAbortedError)
+                return;
+            onError(pathname, error);
+            const tooLarge = error instanceof NodeRequestBodyTooLargeError;
+            if (tooLarge)
+                closeInputAfterResponse(req, res);
+            if (!res.headersSent && !res.destroyed) {
+                res.statusCode = tooLarge ? 413 : 500;
+                res.setHeader("content-type", "application/json; charset=utf-8");
+            }
+            if (!res.writableEnded && !res.destroyed) {
+                res.end(JSON.stringify({ ok: false, error: {
+                        code: tooLarge ? "REQUEST_BODY_TOO_LARGE" : "NODE_HTTP_ERROR",
+                        message: tooLarge ? "Request body too large" : "Internal server error",
+                    } }));
+            }
+        }
+    };
+}
+/** Create the Node HttpRuntimePort: `handle` for one request, `listen` to bind the server. */
+export function createNodeHttpRuntime(options) {
+    const handle = createRequestHandler(options);
+    let server = null;
+    return {
+        server,
+        handle,
+        async listen({ port, host }) {
+            server = createServer((req, res) => {
+                void handle(decorateRequest(req), decorateResponse(res));
+            });
+            this.server = server;
+            await new Promise((resolve) => server.listen(port, host ?? "0.0.0.0", resolve));
+        },
+    };
+}

package/dist/http/security.d.ts

@@ -0,0 +1,44 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { HttpResponse } from "./types.js";
+/** Deployment-owned header policy applied to every response of the Node runtime. */
+export interface NodeSecurityHeaderPolicy {
+    /** Headers set on every response unless the handler already set them, in this order. */
+    readonly globalHeaders: ReadonlyArray<readonly [string, string]>;
+    /** Static-asset path prefixes that receive the long-lived asset Cache-Control. */
+    readonly assetCachePrefixes: readonly string[];
+    /** Path families (the path or anything below it) that receive `X-Robots-Tag: noindex, nofollow`. */
+    readonly noindexFamilies: readonly string[];
+    /** Exact paths that receive `X-Robots-Tag: noindex, nofollow`. */
+    readonly noindexExacts: readonly string[];
+    /** True for a production host; every other host receives the strict non-production X-Robots-Tag. */
+    readonly isProductionHost: (host: string | undefined) => boolean;
+}
+/** Apply the deployment's global and path-specific headers for this route. */
+export declare function applySecurityHeaders(res: ServerResponse, pathname: string, host: string | undefined, policy: NodeSecurityHeaderPolicy): void;
+/** Pluggable static reader so tests can inject an in-memory dist/ without touching the filesystem. */
+export interface StaticAssetReader {
+    /** Read a built asset (returns null if it does not exist). */
+    read(relativePath: string): Promise<{
+        body: Buffer;
+        contentType: string;
+    } | null>;
+    /** The SPA fallback document (dist/index.html). */
+    readIndex(): Promise<{
+        body: Buffer;
+        contentType: string;
+    }>;
+}
+export declare function contentTypeFor(pathname: string): string;
+/** A path "looks like" a built asset if it has a file extension (so we 404 missing assets, not SPA). */
+export declare function looksLikeAsset(pathname: string): boolean;
+/**
+ * Serve a built SPA asset if present, otherwise the document the build produced for this route,
+ * otherwise the declared CSR fallback for client routes. Missing real assets (a hashed bundle that
+ * does not exist) and unknown extensionless paths return 404 rather than the SPA shell.
+ *
+ * The middle step is not decoration. The build writes each pre-rendered route as
+ * `<route>/index.html` and writes the HOME document to `index.html`; skipping that lookup hands
+ * every pre-rendered URL the home document instead of its own. The hosted platform does the same
+ * thing declaratively, one rewrite per route, which is why this host had no equivalent code.
+ */
+export declare function serveSpaStatic(_req: IncomingMessage, res: HttpResponse, pathname: string, reader: StaticAssetReader, allowRouteDocument?: boolean, allowFallback?: boolean): Promise<void>;

package/dist/http/security.js

@@ -0,0 +1,114 @@
+// Security headers + SPA static middleware for the Node HttpRuntimePort.
+//
+// Replicates, as Node middleware, a hosted response surface whose values the deployment owns:
+// the global headers (HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy,
+// Permissions-Policy, Reporting-Endpoints, the content security policy), the path-specific
+// Cache-Control and X-Robots-Tag rules, and which hosts are production. The caller supplies all of
+// them through `NodeSecurityHeaderPolicy`; this module only applies them in a fixed order.
+//
+// SPA fallback boundary: the runtime handles its API and entrypoint branches before static
+// serving, so those paths never fall through to a document.
+import { extname } from "node:path";
+const ASSET_CACHE_CONTROL = "public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800";
+function matchesNoindex(policy, pathname) {
+    if (policy.noindexExacts.includes(pathname))
+        return true;
+    return policy.noindexFamilies.some((path) => pathname === path || pathname.startsWith(`${path}/`));
+}
+/** Apply the deployment's global and path-specific headers for this route. */
+export function applySecurityHeaders(res, pathname, host, policy) {
+    for (const [key, value] of policy.globalHeaders) {
+        if (!res.hasHeader(key))
+            res.setHeader(key, value);
+    }
+    if (policy.assetCachePrefixes.some((p) => pathname.startsWith(p))) {
+        res.setHeader("Cache-Control", ASSET_CACHE_CONTROL);
+    }
+    if (pathname === "/.well-known/security.txt") {
+        res.setHeader("Content-Type", "text/plain; charset=utf-8");
+    }
+    if (pathname === "/ssg-manifest.json" || pathname === "/spa-fallback.html") {
+        res.setHeader("Cache-Control", "public, max-age=0, s-maxage=0, must-revalidate");
+    }
+    if (matchesNoindex(policy, pathname)) {
+        res.setHeader("X-Robots-Tag", "noindex, nofollow");
+    }
+    if (!policy.isProductionHost(host)) {
+        res.setHeader("X-Robots-Tag", "noindex, nofollow, noarchive, nosnippet, noimageindex");
+    }
+}
+const CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".ico": "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".txt": "text/plain; charset=utf-8",
+    ".webmanifest": "application/manifest+json",
+};
+export function contentTypeFor(pathname) {
+    return CONTENT_TYPES[extname(pathname).toLowerCase()] ?? "application/octet-stream";
+}
+/** A path "looks like" a built asset if it has a file extension (so we 404 missing assets, not SPA). */
+export function looksLikeAsset(pathname) {
+    return extname(pathname) !== "";
+}
+/**
+ * Serve a built SPA asset if present, otherwise the document the build produced for this route,
+ * otherwise the declared CSR fallback for client routes. Missing real assets (a hashed bundle that
+ * does not exist) and unknown extensionless paths return 404 rather than the SPA shell.
+ *
+ * The middle step is not decoration. The build writes each pre-rendered route as
+ * `<route>/index.html` and writes the HOME document to `index.html`; skipping that lookup hands
+ * every pre-rendered URL the home document instead of its own. The hosted platform does the same
+ * thing declaratively, one rewrite per route, which is why this host had no equivalent code.
+ */
+export async function serveSpaStatic(_req, res, pathname, reader, allowRouteDocument = false, allowFallback = false) {
+    const relative = pathname === "/" ? "/index.html" : pathname;
+    const asset = await reader.read(relative);
+    if (asset) {
+        if (!res.hasHeader("content-type"))
+            res.setHeader("content-type", asset.contentType);
+        res.statusCode = 200;
+        res.end(asset.body);
+        return;
+    }
+    if (looksLikeAsset(pathname)) {
+        // A concrete asset request that does not exist -> genuine 404 (not the SPA shell).
+        res.statusCode = 404;
+        res.setHeader("content-type", "text/plain; charset=utf-8");
+        res.end("Not Found");
+        return;
+    }
+    // A manifest-declared SSG route -> its own pre-rendered document.
+    if (allowRouteDocument) {
+        const document = await reader.read(`${pathname.replace(/\/+$/, "")}/index.html`);
+        if (document) {
+            if (!res.hasHeader("content-type"))
+                res.setHeader("content-type", document.contentType);
+            res.statusCode = 200;
+            res.end(document.body);
+            return;
+        }
+    }
+    if (!allowFallback) {
+        res.statusCode = 404;
+        res.setHeader("content-type", "text/plain; charset=utf-8");
+        res.end("Not Found");
+        return;
+    }
+    // Declared client route -> SPA fallback.
+    const index = await reader.readIndex();
+    res.statusCode = 200;
+    if (!res.hasHeader("content-type"))
+        res.setHeader("content-type", index.contentType);
+    res.end(index.body);
+}

package/dist/http/staticAssets.d.ts

@@ -0,0 +1,3 @@
+import { type StaticAssetReader } from "./security.js";
+/** Read files below `distDir` (path-traversal safe; null for a missing file or a directory). */
+export declare function createDistStaticReader(distDir: string): StaticAssetReader;

package/dist/http/staticAssets.js

@@ -0,0 +1,42 @@
+// Filesystem reader for a built static site, used by the Node runtime's static branch.
+import { readFile, stat } from "node:fs/promises";
+import { join, normalize, resolve } from "node:path";
+import { contentTypeFor } from "./security.js";
+const SPA_FALLBACK_DOCUMENT = "spa-fallback.html";
+/** Read files below `distDir` (path-traversal safe; null for a missing file or a directory). */
+export function createDistStaticReader(distDir) {
+    const root = resolve(distDir);
+    const safe = (relative) => {
+        const full = normalize(join(root, relative));
+        return full.startsWith(root) ? full : null;
+    };
+    return {
+        async read(relative) {
+            const full = safe(relative);
+            if (!full)
+                return null;
+            try {
+                const info = await stat(full);
+                if (!info.isFile())
+                    return null;
+                const body = await readFile(full);
+                return { body, contentType: contentTypeFor(relative) };
+            }
+            catch {
+                return null;
+            }
+        },
+        async readIndex() {
+            // Prefer the client fallback document; a build without a pre-render step has only
+            // index.html, which then serves as the fallback.
+            try {
+                const body = await readFile(join(root, SPA_FALLBACK_DOCUMENT));
+                return { body, contentType: "text/html; charset=utf-8" };
+            }
+            catch {
+                const body = await readFile(join(root, "index.html"));
+                return { body, contentType: "text/html; charset=utf-8" };
+            }
+        },
+    };
+}

package/dist/http/types.d.ts

@@ -0,0 +1,23 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** A Node request decorated with the parsed query, cookies and body. */
+export interface HttpRequest extends IncomingMessage {
+    query: Record<string, string | string[] | undefined>;
+    cookies?: Record<string, string>;
+    body?: unknown;
+    /** Cooperative cancellation owned by the portable host adapter. */
+    abortSignal?: AbortSignal;
+}
+/** A Node response decorated with the helper methods hosted functions provide. */
+export interface HttpResponse extends ServerResponse {
+    status(code: number): this;
+    json(body: unknown): this;
+    send(body: string | Buffer | object): this;
+    redirect(url: string): this;
+    redirect(status: number, url: string): this;
+}
+/** A default-export handler shared by every physical API entrypoint. */
+export type HttpHandler = (req: HttpRequest, res: HttpResponse) => Promise<unknown> | unknown;
+/** A lazily loaded module exposing one default-export handler. */
+export type EntrypointLoader = () => Promise<{
+    default: HttpHandler;
+}>;

package/dist/http/types.js

@@ -0,0 +1,6 @@
+// Host-neutral request and response shapes for every HTTP entrypoint.
+//
+// They are defined over node:http so that a handler runs unchanged on a hosted
+// serverless function, the Node runtime of this package, or a test double.
+// No host SDK is required to name them.
+export {};

package/dist/job-ledger/index.d.ts

@@ -0,0 +1,5 @@
+export type { PlatformJobBackstopState, PlatformJobClaim, PlatformJobFinishStatus, PlatformJobFinishSummary, PlatformJobInvocation, PlatformJobRunLedgerPort, PlatformJobTriggerKind, } from "./ports.js";
+export type { PgQueryExecutor } from "../data/index.js";
+export { createPostgresPlatformJobRunLedger, type PostgresPlatformJobRunLedgerOptions, } from "./postgres.js";
+export { JOB_RUN_LEDGER_MIGRATIONS, JOB_RUN_LEDGER_SQL_URL, JOB_RUN_LEDGER_V3_SQL_URL } from "./sql.js";
+export { createManagedJobRunCalls, createSupabasePlatformJobRunLedger, platformJobInvocationForDriver, type ManagedJobRunOptions, type PlatformJobClient, type PlatformJobDriver, type PlatformJobSupabaseClient, type SupabasePlatformJobRunLedgerOptions, } from "./supabase.js";

package/dist/job-ledger/index.js

@@ -0,0 +1,3 @@
+export { createPostgresPlatformJobRunLedger, } from "./postgres.js";
+export { JOB_RUN_LEDGER_MIGRATIONS, JOB_RUN_LEDGER_SQL_URL, JOB_RUN_LEDGER_V3_SQL_URL } from "./sql.js";
+export { createManagedJobRunCalls, createSupabasePlatformJobRunLedger, platformJobInvocationForDriver, } from "./supabase.js";

package/dist/job-ledger/ports.d.ts

@@ -0,0 +1,10 @@
+import type { JobLeasePort } from "@openlup/core/platform-runtime";
+export type { PlatformJobClaim, PlatformJobFinishStatus, PlatformJobFinishSummary, PlatformJobInvocation, PlatformJobTriggerKind, } from "@openlup/core/platform-runtime";
+export type PlatformJobBackstopState = {
+    lastStatus: string | null;
+    lastSuccessAt: string | null;
+};
+export interface PlatformJobRunLedgerPort extends JobLeasePort {
+    readJobBackstopState(jobName: string): Promise<PlatformJobBackstopState | null>;
+    readLatestTerminalRunMetadata(jobName: string): Promise<Record<string, unknown> | null>;
+}

package/dist/job-ledger/ports.js

@@ -0,0 +1,7 @@
+// Persistence-neutral scheduled-job lease and attempt ledger port.
+//
+// The claim and finish contract is core's `JobLeasePort`. A job-run ledger adds the two reads a
+// scheduled job uses for its backstop and checkpoint. Invocation is deployment evidence supplied by
+// the composition root; a job never sees a database client, SDK query, RPC name, vendor driver or
+// environment configuration.
+export {};

package/dist/job-ledger/postgres.d.ts

@@ -0,0 +1,10 @@
+import type { PgQueryExecutor } from "../data/index.js";
+import type { PlatformJobRunLedgerPort } from "./ports.js";
+export interface PostgresPlatformJobRunLedgerOptions {
+    /** Release and deployment identity merged into every claim and finish row's metadata. */
+    releaseCorrelation: () => Record<string, string | null>;
+    /** Failure reason recorded when a failed run's summary carries none. */
+    defaultFailureReason: string;
+}
+/** Direct PostgreSQL adapter for the public neutral-vocabulary job-control rail. */
+export declare function createPostgresPlatformJobRunLedger(executor: PgQueryExecutor, options: PostgresPlatformJobRunLedgerOptions): PlatformJobRunLedgerPort;

package/dist/job-ledger/postgres.js

@@ -0,0 +1,101 @@
+// Direct PostgreSQL adapter for the public job-run ledger (claim, finish, backstop, checkpoint).
+//
+// The RPCs and tables come from the package's job-run ledger SQL. Every claim and finish row
+// carries the invocation and the deployment's release correlation in its metadata.
+const CLAIM_SQL = `
+  SELECT acquired, run_id, reason
+  FROM public.platform_claim_job_run_v3($1, $2, $3, $4, $5::jsonb)`;
+const FINISH_SQL = `
+  SELECT public.platform_finish_job_run_v3(
+    $1, $2::uuid, $3, $4, $5, $6, $7, $8::jsonb
+  ) AS released`;
+const BACKSTOP_SQL = `
+  SELECT last_status, last_success_at
+  FROM public.platform_job_controls
+  WHERE job_name = $1`;
+const LATEST_TERMINAL_METADATA_SQL = `
+  SELECT metadata
+  FROM public.platform_job_runs
+  WHERE job_name = $1
+    AND status IN ('success', 'failed')
+    AND finished_at IS NOT NULL
+  ORDER BY started_at DESC
+  LIMIT 1`;
+/** Direct PostgreSQL adapter for the public neutral-vocabulary job-control rail. */
+export function createPostgresPlatformJobRunLedger(executor, options) {
+    return {
+        async claimJobRun(jobName, invocation, leaseSeconds = 900) {
+            const invocationSource = requiredInvocationSource(invocation.invocationSource);
+            const result = await executor.query(CLAIM_SQL, [
+                jobName,
+                invocation.triggerKind,
+                invocationSource,
+                leaseSeconds,
+                {
+                    triggerKind: invocation.triggerKind,
+                    invocationSource,
+                    ...options.releaseCorrelation(),
+                },
+            ]);
+            const row = plainRecord(result.rows[0]);
+            return {
+                acquired: row?.acquired === true,
+                runId: typeof row?.run_id === "string" ? row.run_id : null,
+                reason: typeof row?.reason === "string" ? row.reason : "unknown",
+            };
+        },
+        async finishJobRun(jobName, runId, invocation, status, summary, extraMetadata) {
+            const invocationSource = requiredInvocationSource(invocation.invocationSource);
+            const result = await executor.query(FINISH_SQL, [
+                jobName,
+                runId,
+                status,
+                summary.checked,
+                summary.updated,
+                status === "failed" ? summary.reason ?? options.defaultFailureReason : null,
+                null,
+                {
+                    failures: summary.failures,
+                    skipped: summary.skipped,
+                    reason: summary.reason ?? null,
+                    ...options.releaseCorrelation(),
+                    ...(extraMetadata ?? {}),
+                    triggerKind: invocation.triggerKind,
+                    invocationSource,
+                    driver: invocationSource,
+                },
+            ]);
+            return plainRecord(result.rows[0])?.released === true;
+        },
+        async readJobBackstopState(jobName) {
+            const result = await executor.query(BACKSTOP_SQL, [jobName]);
+            const row = plainRecord(result.rows[0]);
+            return row ? {
+                lastStatus: typeof row.last_status === "string" ? row.last_status : null,
+                lastSuccessAt: timestampString(row.last_success_at),
+            } : null;
+        },
+        async readLatestTerminalRunMetadata(jobName) {
+            const result = await executor.query(LATEST_TERMINAL_METADATA_SQL, [jobName]);
+            return plainRecord(plainRecord(result.rows[0])?.metadata);
+        },
+    };
+}
+function plainRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    return { ...value };
+}
+function timestampString(value) {
+    if (typeof value === "string")
+        return value;
+    if (value instanceof Date)
+        return value.toISOString();
+    return null;
+}
+function requiredInvocationSource(value) {
+    const source = value.trim();
+    if (!source)
+        throw new Error("platform_job_invocation_source_required");
+    return source;
+}

package/dist/job-ledger/sql.d.ts

@@ -0,0 +1,7 @@
+export declare const JOB_RUN_LEDGER_SQL_URL: URL;
+export declare const JOB_RUN_LEDGER_V3_SQL_URL: URL;
+/** Every job-run ledger migration, ordered by migration identity. */
+export declare const JOB_RUN_LEDGER_MIGRATIONS: ReadonlyArray<{
+    readonly id: string;
+    readonly url: URL;
+}>;

package/dist/job-ledger/sql.js

@@ -0,0 +1,10 @@
+// The job-run ledger SQL a fresh installation applies through its own migration chain, in order.
+// The first file's bytes and migration identity equal the reference application's platform
+// migration of the same name; the second adds the v3 claim and finish entry points.
+export const JOB_RUN_LEDGER_SQL_URL = new URL("../../sql/20260809150000_job_run_ledger.sql", import.meta.url);
+export const JOB_RUN_LEDGER_V3_SQL_URL = new URL("../../sql/20260809150001_job_run_ledger_v3.sql", import.meta.url);
+/** Every job-run ledger migration, ordered by migration identity. */
+export const JOB_RUN_LEDGER_MIGRATIONS = [
+    { id: "20260809150000_job_run_ledger", url: JOB_RUN_LEDGER_SQL_URL },
+    { id: "20260809150001_job_run_ledger_v3", url: JOB_RUN_LEDGER_V3_SQL_URL },
+];