@openlup/platform 0.28.0 → 0.30.0

package/README.md

@@ -10,8 +10,12 @@ Development preview. This package is part of the publishable set with core and o
 
 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`.
 
-For the prepared `0.28.0` set, read the [adjacent-release migration and known
-limitations](CHANGELOG.md#0280) before selecting optional services. Experimental
+For the prepared `0.30.0` set, read the [adjacent-release migration and known
+limitations](CHANGELOG.md#0300) before selecting optional services. Experimental
+M13 marketing uses browser-safe `./marketing`, type-only browser-safe
+`./marketing/contracts`, and Node-only `./marketing/server` and
+`./marketing/server/postgres`. Marketing contributions and bindings remain
+inert and default-off. Experimental
 account/support APIs use `./account-support` and the type-only
 `./account-support/contracts`; reference bindings remain inert and default-off.
 Apply the M12 support-authority forwards after complete same-rail predecessors
@@ -50,7 +54,7 @@ Adopters must not activate unselected or unready invoicing; installation and
 inert contributions register no runner, worker, route or schedule.
 M06 managed-host proof classes remain pending in the
 [M06 parity ledger](../../docs/platform/plans/oss-m06-stock-reservations-delivery.md#parity-pending-rows).
-Size comparison uses the published `0.27.0` tarball. Preparation and offline
+Size comparison uses the published `0.29.0` tarball. Preparation and offline
 adapter evidence grant no publication or provider-account certification.
 
 Longer module recipes live in the [platform package reference](../../docs/platform/PLATFORM_PACKAGE_REFERENCE.md).
@@ -64,12 +68,52 @@ alongside seconds/fractions, compact offsets and local timestamps. Calendar
 validation still rejects impossible dates; validation never rewrites the raw
 timestamp used in the webhook's idempotency key.
 
+The experimental migration source may supply `assertSession` to observe host
+facts once under the existing advisory lock, after exact ledger-prefix admission
+and before status, dry-run or pending SQL. Sources without it retain current
+execution. The [migration owner](../../docs/platform/DATA_AND_MIGRATIONS.md#module-catalogues-and-installed-histories)
+and [runner witness](test/migrations/postgresRunner.test.ts) define that boundary;
+this callback does not provision or qualify a hosted installation.
+
 ## Package surface
 
+The experimental Node-only `./lifecycle` entry plans and applies explicit
+application-file snapshots. It preserves unmanaged files and local edits in
+upstream-unchanged files, refuses divergent changed files before writes, and
+resumes exact completed replacements after interruption. The caller holds an
+exclusive maintenance window and supplies schema-range evidence; this entry
+runs no database migration, npm install or deployment. Read the
+[file-ownership boundary](../../docs/platform/ARCHITECTURE_AND_EXTENSIONS.md#application-file-upgrades)
+and [disposable app recipe](../../docs/platform/PLATFORM_PACKAGE_REFERENCE.md#application-file-upgrade).
+
+The same entry exports `inspectLegacyPostgresInstallRoles`, a read-only query
+through a caller-owned PostgreSQL handle. Its
+`legacy-fresh-bootstrap-role-prerequisites` report observes finite immutable
+legacy bootstrap role conditions; `rolePrerequisitesMet` does not establish
+install readiness, schema/ACL correctness or provider support. See the
+[legacy role boundary](../../docs/platform/DATA_AND_MIGRATIONS.md#legacy-fresh-bootstrap-role-observation).
+
+The experimental Node-only `./portability` entry copies a bounded, explicitly
+complete immutable/quiesced object inventory and captures/restores selected
+compatible PostgreSQL rows through injected transaction handles. Private
+filesystem objects publish bytes and metadata together, bind an explicit access
+label to the filesystem owner's private policy and resume by verified readback.
+Row replay preserves exact JSON/numeric/time values, refuses conflicts and every
+enabled user INSERT trigger, and copies no schema, migration ledger or grants.
+The host qualifies the canonical catalogue, credentials and source completeness.
+These helpers activate no executor and do not supply managed identity mapping,
+live changed-row catch-up or hosted old-worker fencing. Read the
+[transfer boundary](../../docs/platform/ARCHITECTURE_AND_EXTENSIONS.md#existing-store-transfer-and-recovery)
+and the retained [M14 obligations](../../docs/platform/plans/oss-m14-operations-portability.md).
+The provider-owned HTTP counterexample exercises an existing adapter's cached
+bearer; its local fixture establishes no hosted revocation guarantee.
+
 `release-gates.json` declares kind `rail`: this foundation provides runtime infrastructure over core ports, matching the architecture's rail responsibility. Its experimental entries each bind a declaration snapshot and package-owned smoke tests. The API checker reads this same inventory.
 
 | Export | Contents |
 | --- | --- |
+| `./lifecycle` | Experimental Node file-snapshot planning/apply and read-only legacy PostgreSQL role prerequisites; no install-readiness claim, optional SDK or activation |
+| `./portability` | Experimental server object copy/resume, private filesystem transfer store and compatible PostgreSQL row capture/restore; injected handles, explicit refusal and no activation |
 | `./http` | Generic capped raw-body reader, hex HMAC and constant-time token comparison; 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 |
@@ -93,6 +137,12 @@ timestamp used in the webhook's idempotency key.
 | `./inventory` | Experimental schemas/ports, handlers, native stores, projection, injected forecast and SQL descriptor; `./inventory/contracts` DTOs. |
 | `./catalog` | Experimental neutral catalog schemas, drafts, reads, media source packs and publication ports |
 | `./catalog/contracts` | Dependency-free catalog DTOs, media resolver, authority and canonicalization helpers |
+| `./marketing/server` | Node-only acquisition handlers, direct read/evidence factories and research orchestration without `pg`; host responder, authorization, binding and notification copy |
+| `./marketing/server/postgres` | Acquisition case and research evidence PostgreSQL port factories; requires the existing optional `pg` peer |
+| `./marketing/server` (analytics context) | Injected analytics context handler with host persistence, capability and identity bindings |
+| `./marketing`, `./marketing/contracts` | Browser-safe acquisition history, portable prelaunch, survey evidence and newsletter consent schemas; type-only DTOs and acquisition/research ports |
+| `./marketing`, `./marketing/contracts` (analytics) | Browser-safe acquisition and research schemas, injected analytics, paid purchase and consent-time facts; type-only DTOs and ports |
+| `./marketing`, `./marketing/contracts` (SEO and content slots) | Browser-safe JSON-LD serialization and graph builders, URL/hreflang helpers, ordered head data and contact/legal projections; type-only organization, contact, legal-document and privacy-processor content slots |
 | `./commerce`, `./commerce/contracts` | Browser-safe neutral commerce schema cores, generic ports and pure contract helpers |
 | `./commerce/server` | Node-only OMS, returns, native reviews/media and hosted-feedback handlers/adapters and order-detail composition, email consumers, dispatch registry, paid-fulfillment binding and checkout compensation, checkout handlers, runtime and shared paid-order saga |
 | `./pricing` | Experimental price authority, quote computation/handlers, offer projection/cache, readiness and policy tokens |
@@ -103,6 +153,135 @@ timestamp used in the webhook's idempotency key.
 | `./shipping` | Experimental delivery ports, injected-schema handlers, summary/evidence; native flat-rate port + Core schema readiness |
 | `./shipping/contracts` | Type-only delivery, pickup-point, summary and evidence DTOs |
 
+## Marketing contracts
+
+`./marketing` provides acquisition address references, historical case projections,
+list/count reads, portable prelaunch list/detail schemas, idempotency keys, survey submission/evidence/list schemas and
+newsletter consent events/responses. Reference compatibility shims forward the
+same schema objects and load the reference validation wrapper before package
+schemas. The marketing runtime entry configures the shared Zod instance in
+jitless mode before constructing schemas, preserving CSP-safe initialization
+for direct imports as well as reference facades, like the pricing, catalog and
+communications entries. The type-only `./marketing/contracts` entry has no
+runtime initialization. The rich prelaunch DTO and case submit/transition schemas remain application-owned
+and are excluded from the browser entries. The shared
+`acquisitionOpaqueReferenceSchema` lets those retained contracts reuse the exact
+reference syntax. No entry registers a route automatically.
+
+`./marketing/contracts` exports only types. Explicit acquisition DTO shapes are
+checked against the runtime schema inference by an executed TypeScript equality
+witness. Reachable case ports expose list, get, active count and close; the app
+uses the server-only compatibility port for its retired methods. Evidence ports retain survey submission,
+survey listing and consent application. Port types are also forwarded through
+the runtime entry, following the commerce boundary. Both entries forward research schemas or types from the compatibility
+owner, `@openlup/core/marketing/research`; runtime schemas retain object identity.
+Case locale remains `en|pl`, matching the persisted constraint. Widening it requires
+a separate migration. Historical wire values remain unchanged.
+
+The source and built entries have browser graph proofs. The root test runner
+selects `test/marketing/`; the installed consumer checks both public entries,
+compiles typed usage and refuses deep imports. Kiosk and research reference
+contracts/ports continue to consume the core export. The app owns its admin
+response client and host composition.
+
+`./marketing/server` owns acquisition case handlers, list/count and prelaunch
+list/detail factories, survey evidence submit/list and consent application,
+research submit/admin handlers and managed survey orchestration without loading
+`pg`. Select `./marketing/server/postgres` for the two PostgreSQL port factories
+after installing the existing optional `pg` peer. Hosts inject the BFF responder,
+authorization and binding resolvers. Direct case reads receive the host bundle
+predicate at their original guard; prelaunch and evidence dispatch stays in the
+host. Notification HTML and subject are injected separately, preserving
+HTML rendering before the subject clock read. The reference owns retired
+route refusals, raw signed consent ingress and notification copy. PostgreSQL
+SQL, role selection and transaction/pool handling remain unchanged. The
+server-only compatibility command types do not expose retired admission schemas.
+
+Analytics facts share these browser-safe entries. `createNoopAnalytics` implements
+Core's existing analytics port; deployment and advertising defaults remain inert.
+`AnalyticsEventMap<StepName>` retains the host's literal step vocabulary, with
+`string` as the neutral default. Private transport ownership fields and envelopes
+remain host extensions. Types are forwarded type-only by `./marketing/contracts`.
+
+`createAnalyticsDataLayer` owns loader readiness per instance and accepts the host's
+browser/storage access, consent key and change event, `consentSignalNames`, event
+prefix, container reader and deployment callback. `consentSignalNames` supplies
+one `analytics` wire name and the ordered `advertising` wire names. Without it,
+no consent command is pushed and optional event admission returns false, even
+with browser access, a container and stored consent; deployment attempts remain
+independent. Consent commands seed default before update and
+use array-like arguments; advertising grants read marketing consent at push time.
+Revocation denies every signal. Sinks are attempted independently with failure
+isolation and no replay of observations made before consent. Admission booleans
+mean synchronous local acceptance only, never delivery or business acknowledgement.
+
+`createAnalyticsRoutePolicy` requires public paths, redirect sources and all
+sensitive-path sets. Its optional-route predicate preserves broad eligibility;
+deployment URL sanitization admits exact public paths and safe campaign values.
+`projectPaidPurchase` consumes only structural paid-recap facts, preserving
+allocation/grouping, the item cap and ordered suppression reasons without an
+ambient currency policy. `selectMarketingHistoricalConsentTime` selects exact
+native chronology only after host authorization, without changing the local
+grant. The reference retains its narrower checkout-kind admission and all wire
+names. [Purchase equivalence](../../src/checkout/machine/purchasePayloadEquivalence.test.ts)
+and the package analytics witnesses pin these boundaries.
+
+`createAnalyticsContextHandler` in `./marketing/server` accepts a required BFF
+responder, enable reader, persistence resolver, access-token reader, trusted-subject
+resolver, capability mint/hash functions, historical cookie name and `clientIdField`.
+The host supplies the client-id wire field name through `clientIdField`; the strict
+request also keeps `granted` and `explicitGrant`. Grants require a client
+id and existing revoked contexts require an explicit new grant for replacement.
+Only token hashes reach persistence. Enrollment uses only the server-verified
+subject, and invalid bearer grants refuse before writes. Cookie attributes and
+method/flag/origin/schema refusal order are preserved. The host owns flag and
+RPC names, gateway authority, route mounting and observability. Persistence
+operations must reject on failure; null persistence refuses as unavailable.
+There is no default persistence, portable SQL or reference route for this handler.
+An `active` result is a local context fact, never delivery, and telemetry context
+failure never gates commerce. The [context witness](test/marketing/analyticsContext.test.ts)
+exercises the factory through synthetic host bindings.
+
+`./marketing` also provides browser-safe JSON-LD serialization and graph builders,
+route URL/hreflang helpers, an ordered head descriptor and plain contact/legal
+projections. Applications supply identity, origin, routes, locales, images and
+content; the descriptor is plain data for a host head manager. The type-only
+`./marketing/contracts` entry exports shared organization facts and contact,
+legal-document and privacy-processor shapes, also forwarded as types by the
+runtime entry. The package supplies no document wording, processor inventory or
+content policy. The [marketing recipe](../../docs/platform/PLATFORM_PACKAGE_REFERENCE.md#marketing-seo-and-content-slots)
+owns the mechanics and installed-artifact proof.
+
+## Marketing composition
+
+`./composition` exports `createMarketingContribution`, an inert descriptor for
+the `marketing` capability's `./marketing`, `./marketing/contracts` and
+`./marketing/server` entries, with a runtime dependency on `identity/contracts`
+for obligation validation.
+Supply already-bound operations and host schema requirements. Ports, routes and
+triggers share the supplied functions; null ports remain required for Core
+readiness, and handlers retain only registration descriptors. Duplicate handler,
+schedule or route identities refuse. Construction invokes no callable and
+installs no worker, route or schedule. See the
+[composition contract](../../docs/platform/ARCHITECTURE_AND_EXTENSIONS.md#contributions-seams-and-readiness)
+for the host admission boundary.
+
+`./marketing/server` also exports `createMarketingPrivacyContributor` and
+`createMarketingPrivacyBindings`. Explicit enablement and both complete owner
+ports select one contributor; its `exportPersonalData`, `assessErasure` and
+`eraseOrRetain` callables can be passed directly to `createMarketingContribution`.
+Missing ownership makes coverage unavailable and erasure unresolved. Identity
+owns assessment ordering, subscription vetoes, receipt replay and transaction
+rollback; the marketing fence runs only during `eraseOrRetain`. Provider request
+acceptance never proves deletion. The reference leaves marketing unselected,
+so its marketing privacy coverage remains an open gap. See the
+[privacy composition recipe](../../docs/platform/PLATFORM_PACKAGE_REFERENCE.md#marketing-server-composition).
+
+The contributor and binding declarations use identity contract types and local
+structural interfaces compatible with identity's `PersonalDataContributor`.
+They do not reference identity's main entry; `./marketing/server` compiles without
+`pg` or `@types/pg`. Select `./marketing/server/postgres` explicitly for those ports.
+
 ## Commerce contracts
 
 `./composition` exports the inert `createCommerceContribution` for the installed
@@ -256,7 +435,7 @@ SQL (class (b) retention): native uses 14 days and the contributed managed profi
 uses 21 days. There is no TypeScript delay parameter or SQL change.
 The reference browser contract facades initialize their shared Zod instance in
 jitless mode before loading package schemas, preserving CSP-safe construction.
-The package contracts add no global Zod configuration side effect. Browser
+The commerce package contracts add no global Zod configuration side effect. Browser
 conformance bundles the complete commerce entry and both reference facades
 without externals; the raw-upload source is a failing browser control, while
 the complete server entry bundles for Node.
@@ -584,6 +763,25 @@ both exported helpers and their signatures: `calculateIncludedVat` delegates to
 
 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.
 
+`NodeSchedulerAdapter.stopAll()` returns `Promise<void>`. It fences and stops the
+current registrations synchronously, then waits for callbacks already admitted,
+including pending lock acquisition and unlock. Await it before disposing their
+resources; custom scheduler implementations must return that drain promise.
+Later registrations remain supported. The Node host caches its `stop()` promise,
+closes its listener and retains the dedicated PostgreSQL lock session until the
+drain settles, including failure cleanup.
+
+The PostgreSQL lock adapter also reserves each numeric advisory key locally
+before acquisition. This prevents reentry on the same session, including pending
+acquisitions and colliding job IDs. Failed acquisition releases the reservation;
+failed unlock retains it until session disposal. The
+[disposable PostgreSQL witness](../../tests/postgres/nodeHostRuntimeDrain.test.ts)
+checks same-session exclusion and replacement-host admission after drain.
+This graceful-stop contract does not fence an old host at external provider I/O
+or settle an effect accepted before an acknowledgement; the
+[transfer boundary](../../docs/platform/ARCHITECTURE_AND_EXTENSIONS.md#existing-store-transfer-and-recovery)
+retains those separate duties.
+
 ## 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.
@@ -1144,3 +1342,21 @@ their owner meaning. Contribution descriptors install no routes, handlers,
 schedules or workers. See the
 [reference recipe](../../docs/platform/RUNTIME_AND_SELF_HOSTING.md#opt-in-disposable-subscription-reference)
 for the host's schema and transport obligations.
+
+## Operations and diagnostics
+
+The experimental `./operations` entry contains browser-safe operational schemas,
+alert projections and `createOperationsClients`, which binds an existing BFF
+requester. `./operations/contracts` contains DTOs and narrow ports only.
+`./operations/server` contains settings read/update, pipeline read, alert overview,
+control-plane handlers and the existing watchdog delivery mechanism. Authorization,
+SQL execution, evidence evaluation and alert transport are supplied by the host;
+importing these entries registers no route, schedule or provider.
+
+`runControlPlaneWatchdogTick` evaluates persisted neutral job failures and records
+an idempotent heartbeat unless `checkOnly` is true. The richer watchdog accepts a
+typed evaluator; the public reference binds its maintained domain evaluator.
+Settings preserve scalar values, and pipeline reads preserve the existing tester
+and email projection. Identity membership and tracking effects keep their owners.
+See the [operations architecture](../../docs/platform/ARCHITECTURE_AND_EXTENSIONS.md#operations-and-diagnostics)
+for refusal behavior, SQL prerequisites and the bounded preview scope.

package/dist/composition/index.d.ts

@@ -8,3 +8,4 @@ export { createFulfillmentContribution } from "./fulfillmentContribution.js";
 export { createSubscriptionContribution } from "./subscriptionContribution.js";
 export { createCommerceContribution } from "./commerceContribution.js";
 export { createAccountSupportContribution } from "./accountSupportContribution.js";
+export { createMarketingContribution } from "./marketingContribution.js";

package/dist/composition/index.js

@@ -9,3 +9,4 @@ export { createFulfillmentContribution } from "./fulfillmentContribution.js";
 export { createSubscriptionContribution } from "./subscriptionContribution.js";
 export { createCommerceContribution } from "./commerceContribution.js";
 export { createAccountSupportContribution } from "./accountSupportContribution.js";
+export { createMarketingContribution } from "./marketingContribution.js";

package/dist/composition/marketingContribution.d.ts

@@ -0,0 +1,21 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+/** Describe existing selected marketing callables; never install another executor. */
+export declare function createMarketingContribution(input: {
+    version: string;
+    requiredSchema: RequiredSchema;
+    marketing: Readonly<Record<string, ((...args: never[]) => unknown) | null>>;
+    handlers: Contribution["handlers"];
+    schedules: Contribution["schedules"];
+    routes: Contribution["routes"];
+}): {
+    contributions: Contribution[];
+    ports: {
+        [k: string]: ((...args: never[]) => unknown) | null;
+    };
+    routes: {
+        [k: string]: (...args: never[]) => unknown;
+    };
+    triggers: {
+        [k: string]: (...args: never[]) => unknown;
+    };
+};

package/dist/composition/marketingContribution.js

@@ -0,0 +1,29 @@
+/** Describe existing selected marketing callables; never install another executor. */
+export function createMarketingContribution(input) {
+    for (const [kind, names] of [
+        ["handler", input.handlers.map(handler => handler.eventType)],
+        ["schedule", input.schedules.map(schedule => schedule.id)],
+        ["route", input.routes.map(route => route.id)],
+    ]) {
+        if (new Set(names).size !== names.length)
+            throw new Error(`marketing_duplicate_${kind}`);
+    }
+    const contribution = {
+        manifest: {
+            name: "@openlup/platform", version: input.version, kind: "rail",
+            module: { id: "marketing", kind: "capability", provides: ["./marketing", "./marketing/contracts", "./marketing/server"],
+                // The server entry validates obligations with identity's runtime contract schema.
+                dependsOn: [{ module: "identity", entries: ["./identity/contracts"] }] },
+            emits: [], handles: input.handlers.map(handler => handler.eventType),
+            schedules: input.schedules.map(({ id, cadenceSeconds }) => ({ id, cadenceSeconds })), env: [],
+            requiredPorts: Object.keys(input.marketing), routes: input.routes.map(route => route.id), requiredSchema: input.requiredSchema,
+        },
+        handlers: input.handlers.map(({ eventType, timeoutMs }) => Object.freeze({ eventType, timeoutMs })), schedules: input.schedules, routes: input.routes,
+    };
+    return {
+        contributions: [contribution],
+        ports: Object.fromEntries(Object.entries(input.marketing).filter(([, fn]) => typeof fn === "function").map(([name, fn]) => [`@openlup/platform/marketing:${name}`, fn])),
+        routes: Object.fromEntries(input.routes.map(route => [`@openlup/platform/marketing:${route.id}`, route.handle])),
+        triggers: Object.fromEntries(input.schedules.map(schedule => [`@openlup/platform/marketing:${schedule.id}`, schedule.run])),
+    };
+}

package/dist/composition/nodeHost.d.ts

@@ -88,7 +88,7 @@ export interface ServeNodeResult {
     bundleId: string;
     httpRuntime: HttpRuntimePort;
     registeredJobs: string[];
-    /** Stop timers and the local listener after a host signal; safe to call repeatedly. */
+    /** Fence timers, drain admitted jobs, then close their lock session; also close the local listener. Safe to call repeatedly. */
     stop(): Promise<void>;
 }
 export interface NodeHost {

package/dist/composition/nodeHost.js

@@ -133,12 +133,13 @@ export function createNodeHost(deps) {
     return { assertBundleReady, serveNode };
 }
 async function stopNodeHost(scheduler, advisoryLock, httpRuntime) {
-    const timers = Promise.resolve().then(() => scheduler?.stopAll());
+    const timers = scheduler?.stopAll() ?? Promise.resolve();
     const server = httpRuntime.server;
     const listener = server
         ? new Promise((resolveClose, reject) => server.close((error) => error ? reject(error) : resolveClose()))
         : Promise.resolve();
-    const results = await Promise.allSettled([timers, advisoryLock?.close(), listener]);
+    const lock = timers.then(() => advisoryLock?.close(), () => advisoryLock?.close());
+    const results = await Promise.allSettled([timers, lock, listener]);
     const failures = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
     if (failures.length > 0)
         throw new AggregateError(failures, "node_host_shutdown_failed");

package/dist/lifecycle/appUpgrade.d.ts

@@ -0,0 +1,52 @@
+/** Exact UTF-8 scaffold files; every unlisted path remains application-owned. */
+export interface AppVersionSnapshot {
+    version: string;
+    schema: {
+        min: number;
+        max: number;
+    };
+    files: Readonly<Record<string, string>>;
+}
+export interface AppUpgradeInput {
+    /** Absolute canonical path (as returned by realpath) of an existing app directory. */
+    root: string;
+    from: AppVersionSnapshot;
+    to: AppVersionSnapshot;
+    /** Observed by the caller; planning and applying execute no database work. */
+    schemaVersion: number;
+}
+export type AppUpgradeAction = "create" | "replace" | "remove" | "unchanged" | "preserved" | "already-applied";
+export interface AppUpgradeConflict {
+    path: string;
+    reason: string;
+}
+export interface AppUpgradePlan {
+    fromVersion: string;
+    toVersion: string;
+    schemaVersion: number;
+    files: {
+        path: string;
+        action: AppUpgradeAction;
+    }[];
+    conflicts: AppUpgradeConflict[];
+}
+export declare class AppUpgradeConflictError extends Error {
+    readonly conflicts: readonly AppUpgradeConflict[];
+    constructor(conflicts: readonly AppUpgradeConflict[]);
+}
+/** Read-only comparison of explicit predecessor and candidate snapshots. */
+export declare function planAppUpgrade(input: AppUpgradeInput): Promise<AppUpgradePlan>;
+/**
+ * The caller must hold an exclusive maintenance window over the application tree.
+ * This is not a lock against concurrent editors or hostile filesystem mutation.
+ * All conflicts are checked before any writes. A later I/O failure can leave a
+ * partial upgrade: rerun the same snapshots to recognize exact completed bytes.
+ * Each replacement is atomic on a local filesystem; the complete upgrade is not.
+ * An abrupt process termination can leave a uniquely named temporary file; it is
+ * never treated as a managed app file or resumed operation.
+ * No SQL, dependency install, version marker, deployment or user hook is executed.
+ */
+export declare function applyAppUpgrade(input: AppUpgradeInput): Promise<{
+    plan: AppUpgradePlan;
+    applied: string[];
+}>;

package/dist/lifecycle/appUpgrade.js

@@ -0,0 +1,180 @@
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+export class AppUpgradeConflictError extends Error {
+    conflicts;
+    constructor(conflicts) {
+        super(`Application upgrade refused: ${conflicts.map(({ path, reason }) => `${path || "schema"}: ${reason}`).join("; ")}`);
+        this.conflicts = conflicts;
+        this.name = "AppUpgradeConflictError";
+    }
+}
+/** Read-only comparison of explicit predecessor and candidate snapshots. */
+export async function planAppUpgrade(input) {
+    return (await inspectUpgrade(input)).plan;
+}
+/**
+ * The caller must hold an exclusive maintenance window over the application tree.
+ * This is not a lock against concurrent editors or hostile filesystem mutation.
+ * All conflicts are checked before any writes. A later I/O failure can leave a
+ * partial upgrade: rerun the same snapshots to recognize exact completed bytes.
+ * Each replacement is atomic on a local filesystem; the complete upgrade is not.
+ * An abrupt process termination can leave a uniquely named temporary file; it is
+ * never treated as a managed app file or resumed operation.
+ * No SQL, dependency install, version marker, deployment or user hook is executed.
+ */
+export async function applyAppUpgrade(input) {
+    const { root, plan, target } = await inspectUpgrade(input);
+    if (plan.conflicts.length)
+        throw new AppUpgradeConflictError(plan.conflicts);
+    const applied = [];
+    for (const file of plan.files) {
+        const destination = join(root, file.path);
+        if (file.action === "remove") {
+            await fs.unlink(destination);
+        }
+        else if (file.action === "create" || file.action === "replace") {
+            await fs.mkdir(dirname(destination), { recursive: true });
+            const temporary = join(dirname(destination), `.openlup-${randomUUID()}.tmp`);
+            // Rename replaces this directory entry rather than modifying a possible hardlink.
+            const mode = file.action === "replace" ? (await fs.stat(destination)).mode & 0o777 : 0o600;
+            let handle;
+            try {
+                handle = await fs.open(temporary, "wx", mode);
+                if (file.action === "replace")
+                    await handle.chmod(mode);
+                await handle.writeFile(target.get(file.path), "utf8");
+                await handle.close();
+                await fs.rename(temporary, destination);
+            }
+            finally {
+                if (handle) {
+                    await handle.close();
+                    await fs.rm(temporary, { force: true });
+                }
+            }
+        }
+        else
+            continue;
+        applied.push(file.path);
+    }
+    return { plan, applied };
+}
+async function inspectUpgrade(input) {
+    const before = snapshotFiles(input.from), target = snapshotFiles(input.to);
+    const paths = [...new Set([...before.keys(), ...target.keys()])].sort();
+    const aliases = new Set();
+    for (const path of paths) {
+        const alias = path.normalize("NFC").toLowerCase().toUpperCase();
+        if (aliases.has(alias))
+            throw new Error(`Application upgrade path alias: ${path}`);
+        aliases.add(alias);
+    }
+    const directorySpellings = new Map();
+    for (const path of paths) {
+        const components = path.split("/");
+        while (components.length > 1) {
+            components.pop();
+            const directory = components.join("/"), alias = directory.normalize("NFC").toLowerCase().toUpperCase();
+            if (aliases.has(alias))
+                throw new Error(`Application upgrade file-parent collision: ${path}`);
+            // Parents may not exist yet; both snapshots must still agree on their spelling.
+            const spelling = directorySpellings.get(alias);
+            if (spelling !== undefined && spelling !== directory)
+                throw new Error(`Application upgrade path alias: ${path}`);
+            directorySpellings.set(alias, directory);
+        }
+    }
+    if (!Number.isSafeInteger(input.schemaVersion) || input.schemaVersion < 0)
+        throw new Error("Application schema version must be a nonnegative safe integer");
+    const plan = {
+        fromVersion: input.from.version, toVersion: input.to.version,
+        schemaVersion: input.schemaVersion, files: [], conflicts: [],
+    };
+    for (const snapshot of [input.from, input.to]) {
+        if (input.schemaVersion < snapshot.schema.min || input.schemaVersion > snapshot.schema.max) {
+            plan.conflicts.push({ path: "", reason: `schema ${input.schemaVersion} is outside ${snapshot.version} range ${snapshot.schema.min}..${snapshot.schema.max}` });
+        }
+    }
+    const requestedRoot = resolve(input.root), rootStat = await fs.lstat(requestedRoot);
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory())
+        throw new Error("Application upgrade root must be an ordinary directory");
+    const root = await fs.realpath(requestedRoot);
+    if (input.root !== root)
+        throw new Error("Application upgrade root must be an absolute canonical path");
+    for (const path of paths) {
+        const observed = await readFile(root, path);
+        if (typeof observed === "string") {
+            plan.conflicts.push({ path, reason: observed });
+            continue;
+        }
+        const oldBytes = before.has(path) ? Buffer.from(before.get(path), "utf8") : null;
+        const newBytes = target.has(path) ? Buffer.from(target.get(path), "utf8") : null;
+        const equal = (bytes) => observed === null ? bytes === null : bytes !== null && observed.equals(bytes);
+        let action;
+        if (oldBytes !== null && newBytes !== null && oldBytes.equals(newBytes)) {
+            // An upstream-unchanged file carries no write authority over local customization.
+            action = equal(oldBytes) ? "unchanged" : "preserved";
+        }
+        else if (equal(newBytes))
+            action = "already-applied";
+        else if (equal(oldBytes))
+            action = newBytes === null ? "remove" : oldBytes === null ? "create" : "replace";
+        else {
+            plan.conflicts.push({ path, reason: "current bytes match neither predecessor nor candidate" });
+            continue;
+        }
+        plan.files.push({ path, action });
+    }
+    return { root, plan, target };
+}
+function snapshotFiles(snapshot) {
+    if (!snapshot || typeof snapshot.version !== "string" || !snapshot.version.trim())
+        throw new Error("Application snapshot needs an explicit version");
+    const range = snapshot.schema;
+    if (!range || !Number.isSafeInteger(range.min) || !Number.isSafeInteger(range.max) || range.min < 0 || range.max < range.min)
+        throw new Error("Application snapshot needs an ordered nonnegative schema range");
+    if (!snapshot.files || typeof snapshot.files !== "object" || Array.isArray(snapshot.files))
+        throw new Error("Application snapshot files must be a record");
+    const result = new Map();
+    for (const [path, content] of Object.entries(snapshot.files)) {
+        const segments = path.split("/");
+        if (!path || Buffer.from(path, "utf8").toString("utf8") !== path || /[\\:]/u.test(path) || [...path].some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127) || segments.some(segment => !segment || segment === "." || segment === ".." || /[. ]$/u.test(segment)) || segments.some(segment => [".git", "node_modules"].includes(segment.toLowerCase()))) {
+            throw new Error(`Unsafe application upgrade path: ${path}`);
+        }
+        if (typeof content !== "string" || Buffer.from(content, "utf8").toString("utf8") !== content)
+            throw new Error(`Application upgrade content must be valid UTF-8: ${path}`);
+        result.set(path, content);
+    }
+    return result;
+}
+/** A string is a structural refusal; null means an absent path. Never follow links. */
+async function readFile(root, path) {
+    const segments = path.split("/");
+    let current = root;
+    for (const [index, segment] of segments.entries()) {
+        const parent = current;
+        current = join(current, segment);
+        let stat;
+        try {
+            stat = await fs.lstat(current);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
+        }
+        // A filesystem alias is not ownership of the differently spelled entry.
+        // Check only after lstat: ENOENT on a case-sensitive store stays absence.
+        if (!(await fs.readdir(parent)).includes(segment))
+            return "managed path spelling differs from directory entry";
+        if (stat.isSymbolicLink())
+            return "symlink in managed path";
+        const last = index === segments.length - 1;
+        if (last)
+            return stat.isFile() ? fs.readFile(current) : "managed path is not a regular file";
+        if (!stat.isDirectory())
+            return "managed parent is not a directory";
+    }
+    return null;
+}

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,2 @@
+export { planAppUpgrade, applyAppUpgrade, AppUpgradeConflictError, type AppVersionSnapshot, type AppUpgradeInput, type AppUpgradeAction, type AppUpgradeConflict, type AppUpgradePlan, } from "./appUpgrade.js";
+export { inspectLegacyPostgresInstallRoles, type PostgresInstallQuery, type LegacyPostgresInstallRequest, type PostgresInstallRoleObservation, type PostgresInstallMembershipObservation, type LegacyPostgresInstallBlocker, type LegacyPostgresInstallRoleReport, } from "./postgresInstallQualification.js";

package/dist/lifecycle/index.js

@@ -0,0 +1,2 @@
+export { planAppUpgrade, applyAppUpgrade, AppUpgradeConflictError, } from "./appUpgrade.js";
+export { inspectLegacyPostgresInstallRoles, } from "./postgresInstallQualification.js";