@openlup/core 0.11.0 → 0.13.0

package/dist/readiness/declarations.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import type { ReadinessInput, ReadinessIssue } from "./contracts.js";
+export declare const schemaObjectShape: z.ZodObject<{
+    kind: z.ZodEnum<{
+        function: "function";
+        table: "table";
+        column: "column";
+    }>;
+    name: z.ZodString;
+    signature: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const manifestShape: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    kind: z.ZodEnum<{
+        kernel: "kernel";
+        rail: "rail";
+        capability: "capability";
+        implementation: "implementation";
+    }>;
+    emits: z.ZodArray<z.ZodString>;
+    handles: z.ZodArray<z.ZodString>;
+    schedules: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        cadenceSeconds: z.ZodNumber;
+    }, z.core.$strict>>;
+    routes: z.ZodArray<z.ZodString>;
+    requiredPorts: z.ZodArray<z.ZodString>;
+    env: z.ZodArray<z.ZodString>;
+    requiredSchema: z.ZodOptional<z.ZodObject<{
+        version: z.ZodString;
+        migration: z.ZodString;
+        objects: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                function: "function";
+                table: "table";
+                column: "column";
+            }>;
+            name: z.ZodString;
+            signature: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Validate declarations without invoking a handler, schedule, route or probe. */
+export declare function declarationIssues(input: ReadinessInput): ReadinessIssue[];

package/dist/readiness/declarations.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+const name = z.string().min(1).max(240).regex(/^[a-zA-Z0-9@_./:-]+$/);
+const version = z.string().regex(/^0\.\d+\.\d+$/);
+const list = z.array(name).refine((items) => new Set(items).size === items.length);
+const kind = z.enum(["kernel", "rail", "capability", "implementation"]);
+export const schemaObjectShape = z.object({ kind: z.enum(["table", "column", "function"]), name,
+    signature: z.string().max(1000).optional() }).strict().refine((o) => o.name.split(".").length === (o.kind === "column" ? 3 : 2) && (o.kind !== "function" || o.signature !== undefined));
+export const manifestShape = z.object({ name: name.regex(/^@openlup\/[a-z0-9-]+$/), version, kind,
+    emits: list, handles: list, schedules: z.array(z.object({ id: name, cadenceSeconds: z.number().finite().positive() }).strict()),
+    routes: list, requiredPorts: list, env: list,
+    requiredSchema: z.object({ version: name, migration: name, objects: z.array(schemaObjectShape) }).strict().optional(),
+}).strict();
+/** Validate declarations without invoking a handler, schedule, route or probe. */
+export function declarationIssues(input) {
+    const issues = [];
+    const issue = (subject, fix, code = "OPENLUP_E_SET_MISMATCH") => issues.push({ code, package: "@openlup/core", subject, fix });
+    if (!input || typeof input !== "object") {
+        issue("input", "Supply complete candidate observations.");
+        return issues;
+    }
+    if (!input.candidate || ![input.candidate.artifact, input.candidate.configuration, input.candidate.environment, input.candidate.database, input.candidate.schema].every((v) => typeof v === "string" && /^[a-zA-Z0-9_.:/-]{1,240}$/.test(v)))
+        issue("candidate", "Supply sanitized immutable artifact, configuration, environment and database identities.");
+    if (input.inventoryComplete !== true)
+        issue("inventory", "Observe the complete installed package inventory, including core.");
+    if (!Array.isArray(input.loadedPackages) || !Array.isArray(input.contributions)) {
+        issue("inventory", "Supply loaded packages and contributions as arrays.");
+        return issues;
+    }
+    for (const pkg of input.loadedPackages)
+        if (!z.object({ name, version, kind }).strict().safeParse(pkg).success)
+            issue("loaded-package", "Supply a valid observed package name, version and kind.");
+    for (const c of input.contributions) {
+        if (!manifestShape.safeParse(c?.manifest).success) {
+            issue("manifest", "Supply a valid complete manifest with unique declarations.");
+            continue;
+        }
+        if (!Array.isArray(c.handlers) || c.handlers.some((h) => !name.safeParse(h?.eventType).success || !Number.isFinite(h?.timeoutMs) || h?.timeoutMs <= 0))
+            issue(c.manifest.name, "Supply valid shared handler descriptors.", "OPENLUP_E_EVENT_UNHANDLED");
+        if (!Array.isArray(c.schedules) || c.schedules.some((s) => !name.safeParse(s?.id).success || !Number.isFinite(s?.cadenceSeconds) || s?.cadenceSeconds <= 0 || typeof s?.run !== "function"))
+            issue(c.manifest.name, "Supply actual runnable schedules.", "OPENLUP_E_SCHEDULE_UNBOUND");
+        if (!Array.isArray(c.routes) || c.routes.some((r) => !name.safeParse(r?.id).success || typeof r?.handle !== "function"))
+            issue(c.manifest.name, "Supply actual route registrations.", "OPENLUP_E_PORT_MISSING");
+        const objects = c.manifest.requiredSchema?.objects ?? [];
+        if (new Set(objects.map((o) => `${o.kind}:${o.name}:${o.signature ?? ""}`)).size !== objects.length)
+            issue(c.manifest.name, "Remove duplicate schema requirements.", "OPENLUP_E_SCHEMA_BEHIND");
+    }
+    if (!Array.isArray(input.vocabulary) || input.vocabulary.some((v) => !name.safeParse(v?.eventType).success || !name.safeParse(v?.owner).success))
+        issue("vocabulary", "Supply explicit vocabulary entries with owners.", "OPENLUP_E_EVENT_UNHANDLED");
+    if (!Array.isArray(input.exemptions) || input.exemptions.some((e) => !name.safeParse(e?.pattern).success || typeof e?.prefix !== "boolean" || !name.safeParse(e?.owner).success || typeof e?.reason !== "string" || !e?.reason.trim() || !["ignored", "dormant"].includes(e?.state)))
+        issue("exemptions", "Supply explicit owned exemptions with reasons.", "OPENLUP_E_EVENT_UNHANDLED");
+    if (!input.bindings || [input.bindings.ports, input.bindings.routes, input.bindings.triggers, input.bindings.env].some((v) => !v || typeof v !== "object" || Array.isArray(v)))
+        issue("bindings", "Supply actual host bindings.", "OPENLUP_E_PORT_MISSING");
+    if (!input.schemaProbe || typeof input.schemaProbe.observe !== "function")
+        issue("schemaProbe", "Bind a schema observation port.", "OPENLUP_E_SCHEMA_BEHIND");
+    if (input.probeTimeoutMs !== undefined && (!Number.isFinite(input.probeTimeoutMs) || input.probeTimeoutMs < 1 || input.probeTimeoutMs > 30000))
+        issue("probeTimeoutMs", "Use a bounded probe timeout from 1 to 30000 ms.", "OPENLUP_E_SCHEMA_BEHIND");
+    return issues;
+}

package/dist/readiness/index.d.ts

@@ -0,0 +1,5 @@
+import type { ReadinessInput, ReadinessReport } from "./contracts.js";
+export * from "./contracts.js";
+export { schemaObjectKey, buildSchemaObjectProbe, createSchemaProbe } from "./schemaProbe.js";
+/** @beta Evaluates supplied facts; never performs migration or effect work. */
+export declare function checkReadiness(input: ReadinessInput): Promise<ReadinessReport>;

package/dist/readiness/index.js

@@ -0,0 +1,147 @@
+import { declarationIssues, manifestShape, schemaObjectShape } from "./declarations.js";
+import { schemaObjectKey } from "./schemaProbe.js";
+export * from "./contracts.js";
+export { schemaObjectKey, buildSchemaObjectProbe, createSchemaProbe } from "./schemaProbe.js";
+/** @beta Evaluates supplied facts; never performs migration or effect work. */
+export async function checkReadiness(input) {
+    const issues = declarationIssues(input);
+    let unknown = issues.some((i) => ["input", "candidate", "inventory", "loaded-package", "schemaProbe", "probeTimeoutMs"].includes(i.subject));
+    const add = (code, pkg, subject, fix, observation) => {
+        issues.push({ code, package: pkg, subject, fix, ...(observation ? { observation } : {}) });
+    };
+    const report = () => ({ state: unknown ? "unknown" : issues.length ? "unsatisfied" : "ready", candidate: input?.candidate,
+        loadedPackages: input?.loadedPackages ?? [], issues: issues.sort((a, b) => [a.code, a.package, a.subject, a.observation ?? ""].join("|").localeCompare([b.code, b.package, b.subject, b.observation ?? ""].join("|"))) });
+    if (!input || !Array.isArray(input.loadedPackages) || !Array.isArray(input.contributions))
+        return report();
+    const contributions = input.contributions.filter((c) => manifestShape.safeParse(c?.manifest).success && Array.isArray(c.handlers) && c.handlers.every((h) => h && typeof h.eventType === "string" && Number.isFinite(h.timeoutMs) && h.timeoutMs > 0) && Array.isArray(c.schedules) && c.schedules.every((s) => s && typeof s.id === "string" && typeof s.run === "function") && Array.isArray(c.routes) && c.routes.every((r) => r && typeof r.id === "string" && typeof r.handle === "function"));
+    const loaded = input.loadedPackages.filter((p) => p && typeof p.name === "string" && typeof p.version === "string");
+    const packages = new Map();
+    for (const p of loaded)
+        packages.set(p.name, (packages.get(p.name) ?? 0) + 1);
+    if (packages.get("@openlup/core") !== 1 || loaded.find((p) => p.name === "@openlup/core")?.kind !== "kernel")
+        add("OPENLUP_E_SET_MISMATCH", "@openlup/core", "kernel", "Observe exactly one core kernel.");
+    const set = loaded.find((p) => p.name === "@openlup/core")?.version;
+    const install = `Align the complete set: npm install ${[...new Set(loaded.map((p) => p.name))].sort().map((name) => `${name}@${set ?? "<set-version>"}`).join(" ")}`;
+    for (const [name, count] of packages)
+        if (count > 1)
+            add("OPENLUP_E_SET_MISMATCH", name, "inventory", "Observe each loaded package exactly once.");
+    for (const p of loaded) {
+        if (p.version !== set || (p.kind === "kernel" && p.name !== "@openlup/core"))
+            add("OPENLUP_E_SET_MISMATCH", p.name, "version", install);
+        if (p.kind !== "kernel" && contributions.filter((c) => c.manifest.name === p.name).length !== 1)
+            add("OPENLUP_E_SET_MISMATCH", p.name, "contribution", "Compose exactly one contribution for each loaded non-kernel package.");
+    }
+    const handlers = new Map();
+    const emitters = new Map();
+    const events = new Set();
+    for (const v of (Array.isArray(input.vocabulary) ? input.vocabulary : [])) {
+        if (v && typeof v.eventType === "string") {
+            if (events.has(v.eventType))
+                add("OPENLUP_E_EVENT_DUPLICATE", v.owner, v.eventType, "Declare each vocabulary identity once.");
+            events.add(v.eventType);
+        }
+    }
+    for (const c of contributions) {
+        const m = c.manifest;
+        const p = loaded.filter((p) => p.name === m.name);
+        if (p.length !== 1 || p[0]?.version !== m.version || p[0]?.kind !== m.kind)
+            add("OPENLUP_E_SET_MISMATCH", m.name, "manifest", "Match the contribution to its observed installed package.");
+        for (const type of m.emits) {
+            events.add(type);
+            if (m.kind !== "kernel")
+                emitters.set(type, [...(emitters.get(type) ?? []), m.name]);
+        }
+        const actual = c.handlers.map((h) => h?.eventType);
+        for (const type of new Set([...m.handles, ...actual])) {
+            if (m.handles.filter((x) => x === type).length !== 1 || actual.filter((x) => x === type).length !== 1)
+                add("OPENLUP_E_EVENT_DUPLICATE", m.name, type, "Match each declared consumer to exactly one composed handler descriptor.");
+            else
+                handlers.set(type, [...(handlers.get(type) ?? []), m.name]);
+            events.add(type);
+        }
+        for (const port of m.requiredPorts)
+            if (!isPort(input.bindings?.ports?.[`${m.name}:${port}`]))
+                add("OPENLUP_E_PORT_MISSING", m.name, port, "Bind the selected adapter port in composition.");
+        for (const env of m.env)
+            if (typeof input.bindings?.env?.[env] !== "string" || !input.bindings.env[env]?.trim())
+                add("OPENLUP_E_ENV_MISSING", m.name, env, "Supply the named environment variable without exposing its value.");
+        for (const id of new Set([...m.schedules.map((s) => s.id), ...c.schedules.map((s) => s?.id)])) {
+            const declarations = m.schedules.filter((s) => s.id === id), actual = c.schedules.filter((s) => s?.id === id);
+            if (declarations.length !== 1 || actual.length !== 1 || declarations[0]?.cadenceSeconds !== actual[0]?.cadenceSeconds || typeof actual[0]?.run !== "function" || input.bindings?.triggers?.[`${m.name}:${id}`] !== actual[0]?.run)
+                add("OPENLUP_E_SCHEDULE_UNBOUND", m.name, id, "Bind the actual schedule with its declared cadence to one host trigger.");
+        }
+        for (const id of new Set([...m.routes, ...c.routes.map((r) => r?.id)]))
+            if (m.routes.filter((r) => r === id).length !== 1 || c.routes.filter((r) => r?.id === id && typeof r.handle === "function").length !== 1 || input.bindings?.routes?.[`${m.name}:${id}`] !== c.routes.find((r) => r.id === id)?.handle)
+                add("OPENLUP_E_PORT_MISSING", m.name, id, "Bind the declared route to its actual host entry.");
+    }
+    for (const [type, owners] of [...emitters, ...handlers])
+        if (owners.length > 1)
+            add("OPENLUP_E_EVENT_DUPLICATE", owners.sort().join(","), type, "Use one non-kernel producer owner and one composed consumer per event.");
+    for (const type of events)
+        if (!handlers.has(type) && !(Array.isArray(input.exemptions) ? input.exemptions : []).some((e) => e && typeof e.reason === "string" && e.reason.trim() && typeof e.owner === "string" && typeof e.pattern === "string" && ["ignored", "dormant"].includes(e.state) && typeof e.prefix === "boolean" && (e.prefix ? type.startsWith(e.pattern) : type === e.pattern)))
+            add("OPENLUP_E_EVENT_UNHANDLED", "@openlup/core", type, "Register a handler or an explicit owned ignored/dormant declaration.");
+    for (const c of contributions) {
+        const req = c.manifest.requiredSchema;
+        if (!req)
+            continue;
+        if (issues.some((i) => ["schemaProbe", "probeTimeoutMs"].includes(i.subject))) {
+            unknown = true;
+            continue;
+        }
+        let observation;
+        try {
+            observation = await boundedObservation(input, req);
+        }
+        catch {
+            unknown = true;
+            add("OPENLUP_E_SCHEMA_BEHIND", c.manifest.name, req.version, `Observe the selected adapter and apply ${req.migration} through your migration chain.`, "probe_unavailable");
+            continue;
+        }
+        if (!validObservation(observation, req)) {
+            unknown = true;
+            add("OPENLUP_E_SCHEMA_BEHIND", c.manifest.name, req.version, "Return one valid observation for every requested schema object.", "probe_malformed_or_incomplete");
+            continue;
+        }
+        if (!observation.database || observation.database !== input.candidate?.database || observation.version === null) {
+            unknown = true;
+            add("OPENLUP_E_SCHEMA_BEHIND", c.manifest.name, req.version, "Observe the exact candidate database and applied migration identity.", "identity_or_version_unknown");
+        }
+        else if (observation.version !== req.version)
+            add("OPENLUP_E_SCHEMA_BEHIND", c.manifest.name, req.version, `Apply ${req.migration} and observe its version.`, "version_mismatch");
+        for (const { object, present } of observation.objects)
+            if (present !== true) {
+                unknown ||= present === null;
+                add("OPENLUP_E_SCHEMA_BEHIND", c.manifest.name, schemaObjectKey(object), `Apply ${req.migration} for the selected adapter.`, present === null ? "object_unknown" : "object_absent");
+            }
+    }
+    return report();
+}
+function validObservation(value, requirement) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    if (typeof v.database !== "string" || !(v.version === null || typeof v.version === "string") || !Array.isArray(v.objects))
+        return false;
+    const requested = new Set(requirement.objects.map(schemaObjectKey)), seen = new Set();
+    for (const item of v.objects) {
+        if (!item || !schemaObjectShape.safeParse(item.object).success || ![true, false, null].includes(item.present))
+            return false;
+        const key = schemaObjectKey(item.object);
+        if (!requested.has(key) || seen.has(key))
+            return false;
+        seen.add(key);
+    }
+    return seen.size === requested.size;
+}
+async function boundedObservation(input, requirement) {
+    const timers = globalThis;
+    let timer;
+    try {
+        return await Promise.race([input.schemaProbe.observe(requirement), new Promise((_, reject) => { timer = timers.setTimeout(() => reject(new Error("probe_timeout")), input.probeTimeoutMs ?? 3000); })]);
+    }
+    finally {
+        if (timer !== undefined)
+            timers.clearTimeout(timer);
+    }
+}
+function isPort(value) { return typeof value === "function" || (value !== null && typeof value === "object" && !Array.isArray(value)); }

package/dist/readiness/schemaProbe.d.ts

@@ -0,0 +1,13 @@
+import type { SchemaObject, SqlExecutor, SchemaProbePort, RequiredSchema } from "./contracts.js";
+/** @beta Identity distinguishes overloads and qualified columns. */
+export declare function schemaObjectKey(object: SchemaObject): string;
+/** @beta Parameterized catalog queries; this builder performs no I/O. */
+export declare function buildSchemaObjectProbe(object: SchemaObject): {
+    text: string;
+    values: readonly unknown[];
+};
+/** @beta Explicit adapter. Host supplies independently observed database and migration identity. */
+export declare function createSchemaProbe(executor: SqlExecutor, identity: (requirement: RequiredSchema) => Promise<{
+    database: string;
+    version: string | null;
+}>): SchemaProbePort;

package/dist/readiness/schemaProbe.js

@@ -0,0 +1,25 @@
+/** @beta Identity distinguishes overloads and qualified columns. */
+export function schemaObjectKey(object) {
+    return `${object.kind}:${object.name}${object.kind === "function" ? `(${object.signature ?? ""})` : ""}`;
+}
+/** @beta Parameterized catalog queries; this builder performs no I/O. */
+export function buildSchemaObjectProbe(object) {
+    if (object.kind === "function")
+        return { text: "select to_regprocedure($1)::oid is not null as present", values: [`${object.name}(${object.signature ?? ""})`] };
+    if (object.kind === "table")
+        return { text: "select exists (select 1 from pg_catalog.pg_class c where c.oid = to_regclass($1) and c.relkind in ('r','p')) as present", values: [object.name] };
+    const parts = object.name.split(".");
+    return { text: "select exists (select 1 from pg_catalog.pg_attribute where attrelid = to_regclass($1) and attname = $2 and attnum > 0 and not attisdropped) as present", values: [parts.slice(0, -1).join("."), parts.at(-1)] };
+}
+/** @beta Explicit adapter. Host supplies independently observed database and migration identity. */
+export function createSchemaProbe(executor, identity) {
+    return { async observe(requirement) {
+            const observed = await identity(requirement);
+            const objects = await Promise.all(requirement.objects.map(async (object) => {
+                const query = buildSchemaObjectProbe(object);
+                const { rows } = await executor.query(query.text, query.values);
+                return { object, present: rows.length === 1 && typeof rows[0]?.present === "boolean" ? rows[0].present : null };
+            }));
+            return { ...observed, objects };
+        } };
+}

package/dist/standard-schema/index.d.ts

@@ -0,0 +1,26 @@
+/** @beta Structural Standard Schema v1 interface; no validator dependency required. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    };
+}
+/** @beta */
+export type Result<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: readonly Issue[];
+};
+/** @beta */
+export interface Issue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | {
+        readonly key: PropertyKey;
+    })[];
+}

package/dist/standard-schema/index.js

@@ -0,0 +1 @@
+export {};

package/docs/SUBSCRIPTION_ENGINE.md

@@ -0,0 +1,235 @@
+# Subscription engine
+
+Owns: the pure subscription lifecycle kernel exported as `@openlup/core/subscription`.
+Watches: `src/subscription/**`
+Verified against: repository state `735d5d7` plus the lifecycle-parity change
+(2026-09-26) — every exported name below was read out of the eight source files
+in `src/subscription/`, the status matrix out of `subscriptionEngineLifecycle.ts`
+and the managed SQL guard it mirrors, the
+payment semantics out of `src/subscription/subscriptionEnginePayment.ts`, and
+the shipped retry class plus fail-open boundary out of `cycleHardening.ts` and
+its exact unit/parity tests.
+
+All `src/subscription/` paths and unprefixed commands in this document are
+relative to this package root.
+
+`src/subscription/` is the engine. Nothing else in the platform decides when a
+subscription's next cycle falls, whether an edit window is still open, or what a
+recorded payment does to the schedule. A host application that re-exports these
+functions is a caller, not a second engine — see **Consuming it from a host
+application** at the end.
+
+## What this package owns
+
+Eight files under `src/subscription/`, one barrel (`index.ts`), four groups of
+exports.
+
+| Group | File | Exports |
+| --- | --- | --- |
+| Cycle planning | `subscriptionEngineCore.ts` | `createInitialSubscriptionCheckoutModel`, `planSubscriptionCycle`, `isRenewalDue`, `findDueSubscriptions`, `isEditWindowOpen`, `editCutoffAt` |
+| Lifecycle transitions | `subscriptionEngineLifecycle.ts` | `SUBSCRIPTION_STATUS_TRANSITIONS`, `canTransitionSubscriptionStatus`, `pauseSubscription`, `resumeSubscription`, `cancelSubscription`, `completeSubscription`, `reactivateSubscription`, `pauseSubscriptionForExpiredDunning`, `resumeSubscriptionFromExpiredDunning`, `RESTART_LEAD_DAYS`, `skipNextCycle`, `slideNextCycle`, `swapTemplateLine`, `addPermanentAddon` |
+| Payment recording | `subscriptionEnginePayment.ts` | `recordPaymentSuccess`, `recordPaymentFailure` |
+| Retry ladder | `cycleHardening.ts` | `DEFAULT_CYCLE_RETRY_CADENCE`, `nextRetryAttemptAt`, `shouldScheduleRetry`, `maxRetryAttempts`, `ladderTerminatedByClass`, `isDunningLadderExhausted` |
+
+`subscriptionEngineTypes.ts` and `types.ts` carry the shapes
+(`EngineSubscription`, `EngineCycle`, `EngineEvent`, the status unions, the
+template snapshot) and `subscriptionEngineUtils.ts` the small pure helpers the
+groups above share (`addCadenceDays`, `parseIso`, `validateTemplate`,
+`isTerminalCycle`, `touchSubscription`, `makeEvent`, `success`, `failure`, …).
+
+Every mutating function returns the same discriminated result rather than
+throwing:
+
+```ts
+type SubscriptionEngineResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: { code: SubscriptionEngineErrorCode; message: string } };
+```
+
+`SubscriptionEngineErrorCode` is a closed union of eleven neutral codes
+(`invalid_timestamp`, `invalid_template`, `inactive_subscription`,
+`edit_window_closed`, `line_not_found`, `duplicate_line`,
+`invalid_slide_target`, `invalid_transition`, `terminal_cycle`,
+`missing_payment_method`, `dunning_not_exhausted`). Refusals are
+values; add a code rather than an exception.
+
+Mutations also return the events they imply (`EngineEvent[]`), each already
+carrying an `idempotencyKey` derived from the cycle's own
+`engineIdempotencyKey`. The engine does not publish them — the host writes them
+to whatever outbox it has, and the stable key is what makes that write
+replay-safe.
+
+## No I/O, and no ambient clock
+
+Two rules make `src/subscription/` portable, and both are mechanical rather than
+aspirational.
+
+1. **No I/O.** No database handle, no HTTP client, no filesystem, no scheduler,
+   no settlement adapter. The only import that leaves `src/subscription/` is
+   the sibling `paymentFailureTaxonomyContracts` module, another pure kernel.
+2. **No ambient clock.** There is no `Date.now()` and no `new Date()` without an
+   argument anywhere in these eight files. Every function that needs the current
+   instant takes it as an ISO-8601 string parameter (`now`, `recordedAt`,
+   `failedAt`, `firstCycleAt`). `grep -rn "Date.now\|new Date()" src/subscription`
+   returns nothing, and it must keep returning nothing.
+
+The consequence is that the same inputs always produce the same outputs, so the
+whole engine is testable without a fake clock, a container, or a network.
+
+`DEFAULT_TIMEZONE` here is `"UTC"`. The engine does not know which market it
+serves; the composition root names the zone. A caller that has a market zone
+should pass it explicitly rather than rely on the default.
+
+## The deterministic-clock contract on `recordPaymentSuccess`
+
+`recordPaymentSuccess` takes **two** instants, and both are required:
+
+```ts
+recordPaymentSuccess({ subscription, cycle, paidAt, recordedAt })
+```
+
+- `paidAt` is when the money moved, as the settlement service reports it.
+- `recordedAt` is when this deployment observed that fact. The caller supplies
+  it; the engine has no clock of its own to fall back on.
+
+Lateness is measured to the **earlier of the two**. A settlement timestamp from
+the future therefore cannot inflate the schedule shift and push the next charge
+out past what the subscriber actually owes, and a delayed observation cannot
+shorten it either. Both instants must parse, or the call answers
+`invalid_timestamp`.
+
+## A late payment shifts the cycle; it never compresses it
+
+This is the load-bearing rule of the whole engine, and the one most likely to be
+"optimised" away by someone who reads it as defensive arithmetic.
+
+The next cycle is computed from the **cycle's own** `scheduledAt` plus its
+cadence — not from the moment the money arrived. A late payment must not silently
+shorten the interval the subscriber bought. The whole days the payment was late
+are then **added**:
+
+```
+shiftedByDays = max(0, floor((min(paidAt, recordedAt) - cycle.scheduledAt) / 1 day))
+nextCycleAt   = max(subscription.nextCycleAt, onTimeNextCycleAt + shiftedByDays days)
+```
+
+The outer `max` is a **monotonic clamp**: `nextCycleAt` may only ever move later,
+never earlier. Without it a replayed webhook, an out-of-order settlement, or a
+correction applied against an older cycle could compute an earlier instant and
+pull a charge forward into a window the subscriber has already been billed for.
+That is the one failure mode this rail must never have. A deployment whose
+durable schedule enforces the same rule in SQL will spell the clamp `GREATEST`;
+the two are one rule with two spellings, and they must move together.
+
+`shiftedByDays` is reported on the emitted
+`subscription.next_cycle_at_updated` event alongside `basedOnScheduledAt` and
+`basedOnPaidAt`, so the shift is auditable after the fact rather than inferred.
+
+A shift that pushes the instant past the representable timestamp range answers
+`invalid_timestamp` rather than returning an invalid date.
+
+## The retry ladder terminates; it does not cap
+
+`cycleHardening.ts` is the single authority on what a refused charge does next.
+`nextRetryAttemptAt` answers the instant of the next attempt, or `null` when
+there is none. `DEFAULT_CYCLE_RETRY_CADENCE` ships `backoffHours: [24, 72, 168]`
+— one day, three days, seven days — frozen so nothing can mutate the shipped
+ladder in place, and injectable so a deployment can publish its own.
+
+Asking for the next slot **is** the decision. `null` means only that no next
+retry is scheduled; it is a pause signal only after the rung budget is
+exhausted. Class termination before exhaustion leaves the subscription active
+and must not be treated as exhaustion. The function never answers "the last
+slot again". Callers must not add their own
+`attempt <= maxRetryAttempts()` guard — a second copy of the budget check is
+exactly how two rails drift apart.
+
+`terminatingFailureClasses` lets a refusal's *class*, rather than the rung it
+reached, end the ladder. `DEFAULT_CYCLE_RETRY_CADENCE` ships exactly one member:
+`["hard_do_not_retry"]`. That class says the issuer refused the instrument, not
+only this charge, so no retry rung can change the answer; every other shipped
+failure class keeps the full ladder.
+
+`ladderTerminatedByClass` fails open at every configuration uncertainty. An
+absent or unlisted class does not terminate. A class explicitly listed by a
+custom cadence still does not terminate when the payment taxonomy does not
+recognise it, or when `failureClassDecision` says retry remains allowed. Only a
+listed, recognised class that the decision table already refuses can shorten
+the ladder. The SQL retry rail publishes the same singleton, and the parity test
+fails if those two spellings drift.
+
+## The status matrix, and the one non-payment pause
+
+`SUBSCRIPTION_STATUS_TRANSITIONS` is the whole status matrix, frozen:
+
+| From | To |
+| --- | --- |
+| `active` | `paused`, `cancelled`, `completed` |
+| `paused` | `active`, `cancelled` |
+| `cancelled` | `active` |
+| `completed` | none; terminal |
+
+It mirrors the managed SQL guard `public.subscription_guard_status_transition`
+over the engine's four statuses. The guard's remaining edges belong to the
+activation flow, which this engine never drives. `canTransitionSubscriptionStatus`
+answers from the matrix and nothing else.
+
+Each operation takes only its own edge. `resumeSubscription` leaves `paused`
+only. `cancelled` -> `active` is the win-back, and only `reactivateSubscription`
+takes it. It needs a stored payment method, because a win-back charges again,
+and it restarts the schedule. The managed SQL `reactivate` action also clears
+the end instant and cancellation reason, requires the customer's confirmation of
+the charge timing, refuses while a cycle is locked and bumps the template
+version. Those durable duties stay with the host.
+
+**The sanctioned non-payment rule.** Nothing in this engine suspends an active
+subscription for a reason its owner did not choose, except a renewal that
+exhausted the retry ladder. `isDunningLadderExhausted(cycle, cadence?)` holds
+only when the cycle is `payment_failed`, has no `nextRetryAt`, and its
+`retryAttempt` is past `maxRetryAttempts(cadence)`. A deployment with its own
+ladder passes the same cadence to `recordPaymentFailure` and to both dunning
+functions, or they disagree about exhaustion. Both halves are required: a
+class-terminated refusal on rung one also leaves nothing scheduled, and it must
+leave the subscription active. `pauseSubscriptionForExpiredDunning` pauses an
+active subscription when that predicate holds. It records `subscription.paused`
+with reason `payment_failed_expired` and never touches `nextCycleAt`. It refuses
+every other cycle as `dunning_not_exhausted`, and returns a subscription that is
+not active unchanged with no event, so a replay is harmless.
+
+`resumeSubscriptionFromExpiredDunning` is the customer's recovery. It needs a
+paused subscription, the exhausted cycle and a payment method, stored or
+supplied. The given cycle becomes `skipped` rather than being charged late.
+Whether the method is chargeable unattended is the host's check, and so is
+skipping any other uncollected cycle the host holds; the SQL boundary does both.
+A subscription this rule paused must not go through plain `resumeSubscription`,
+which neither skips the cycle nor moves a stale `nextCycleAt`.
+
+Both restarts put `nextCycleAt` `RESTART_LEAD_DAYS` (two) days out, but never
+earlier than the instant already stored. The monotonic clamp on
+`recordPaymentSuccess` applies here too: a restart cannot pull a charge into a
+window already paid for. The managed SQL restarts assign `now + 2 days` without
+the clamp, so the two differ exactly when the stored instant is later than
+that. Examples are a win-back of a subscription paid through a later date, or a
+schedule skipped or slid while the ladder was still running. There the SQL side
+charges earlier than the engine would.
+
+## Consuming it from a host application
+
+A host application should import from the package entry point and keep its own
+module a **re-export shim**:
+
+```ts
+// host/src/subscription/subscriptionEnginePayment.ts
+export { recordPaymentSuccess, recordPaymentFailure } from "@openlup/core/subscription";
+```
+
+The shim exists so host-side call sites keep a stable local import path while the
+engine lives here. The rule is one line long: **never add logic to a shim.**
+A behaviour change belongs in `src/subscription/`, where it is covered by the
+pure tests and shared by every consumer. A shim may narrow a type or require a
+parameter the engine defaults (making a market timezone mandatory, for example),
+and it must say so in a comment; anything beyond that is a second engine.
+
+What the host still owns: persistence, the outbox write, settlement execution and
+mandate storage, scheduling, notification copy, and the clock it passes in. This
+package owns none of them and must never acquire one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlup/core",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Neutral D2C subscription and bundle commerce kernels; a development preview with no stable API.",
   "license": "Apache-2.0",
   "repository": {
@@ -22,6 +22,7 @@
   "files": [
     "dist/**",
     "src/**",
+    "AGENTS.md",
     "CHANGELOG.md",
     "CODE_OF_CONDUCT.md",
     "CONTRIBUTING.md",
@@ -29,6 +30,7 @@
     "MAINTAINERS.md",
     "README.md",
     "SECURITY.md",
+    "docs/SUBSCRIPTION_ENGINE.md",
     "release-gates.json"
   ],
   "scripts": {
@@ -74,16 +76,6 @@
       "import": "./dist/bundle/contracts.js",
       "default": "./dist/bundle/contracts.js"
     },
-    "./checkout": {
-      "core-source": "./src/checkout/index.ts",
-      "types": "./dist/checkout/index.d.ts",
-      "module": "./dist/checkout/index.js",
-      "node": "./dist/checkout/index.js",
-      "development": "./dist/checkout/index.js",
-      "production": "./dist/checkout/index.js",
-      "import": "./dist/checkout/index.js",
-      "default": "./dist/checkout/index.js"
-    },
     "./company-identity": {
       "core-source": "./src/company-identity/index.ts",
       "types": "./dist/company-identity/index.d.ts",
@@ -223,6 +215,36 @@
       "production": "./dist/testing.js",
       "import": "./dist/testing.js",
       "default": "./dist/testing.js"
+    },
+    "./outbox": {
+      "core-source": "./src/outbox/index.ts",
+      "types": "./dist/outbox/index.d.ts",
+      "module": "./dist/outbox/index.js",
+      "node": "./dist/outbox/index.js",
+      "development": "./dist/outbox/index.js",
+      "production": "./dist/outbox/index.js",
+      "import": "./dist/outbox/index.js",
+      "default": "./dist/outbox/index.js"
+    },
+    "./readiness": {
+      "core-source": "./src/readiness/index.ts",
+      "types": "./dist/readiness/index.d.ts",
+      "module": "./dist/readiness/index.js",
+      "node": "./dist/readiness/index.js",
+      "development": "./dist/readiness/index.js",
+      "production": "./dist/readiness/index.js",
+      "import": "./dist/readiness/index.js",
+      "default": "./dist/readiness/index.js"
+    },
+    "./standard-schema": {
+      "core-source": "./src/standard-schema/index.ts",
+      "types": "./dist/standard-schema/index.d.ts",
+      "module": "./dist/standard-schema/index.js",
+      "node": "./dist/standard-schema/index.js",
+      "development": "./dist/standard-schema/index.js",
+      "production": "./dist/standard-schema/index.js",
+      "import": "./dist/standard-schema/index.js",
+      "default": "./dist/standard-schema/index.js"
     }
   }
 }