@openlup/core 0.11.0 → 0.13.0

package/AGENTS.md

@@ -0,0 +1,103 @@
+# `@openlup/core` for agents
+
+## Purpose and kind
+
+Kind: `kernel`.
+
+`@openlup/core` holds the I/O-free contracts and logic that more than one
+`@openlup/*` package, or an application's composition, reads. Its only runtime
+dependency is `zod`. It performs no I/O, reads no environment and starts no
+process: an application binds its ports and composes it.
+
+## Subpath maturity
+
+| Export | Role | Maturity |
+| --- | --- | --- |
+| `./bundle` | kernel | candidate |
+| `./catalog` | kernel | candidate |
+| `./company-identity` | kernel | experimental |
+| `./fulfillment` | kernel | experimental |
+| `./inventory` | kernel | candidate |
+| `./marketing/research` | kernel | experimental |
+| `./partners` | kernel | experimental |
+| `./payment` | kernel | experimental |
+| `./platform-runtime` | kernel | experimental |
+| `./pricing` | kernel | candidate |
+| `./promo` | kernel | candidate |
+| `./risk` | kernel | candidate |
+| `./shipping` | kernel | candidate |
+| `./subscription` | kernel | candidate |
+| `./outbox` | kernel | experimental |
+| `./readiness` | kernel | experimental |
+| `./standard-schema` | kernel | experimental |
+| `./testing` | testing | testing |
+
+Any version may change an export, and each change is recorded in
+[the changelog](CHANGELOG.md).
+
+## Wiring example
+
+The application owns its composition. This example compiles in OpenLup's CI:
+
+```ts
+import {
+  createPlatformBundleRegistry,
+  platformEnvSchema,
+  type PlatformBundleReadiness,
+  type PlatformEnvInput,
+} from "@openlup/core/platform-runtime";
+
+// Application composition: the application, not the package, owns its bundles.
+const registry = createPlatformBundleRegistry({
+  defaultBundleId: "self-host",
+  descriptors: [
+    {
+      id: "self-host",
+      capabilities: {
+        http: "node-http",
+        scheduler: "cron",
+        blob: "filesystem",
+        data: "postgres",
+        migrations: "sql-files",
+        analytics: "none",
+        transactional: "smtp",
+      },
+      readReadiness: (env) =>
+        env.APP_BASE_URL ? { ok: true } : { ok: false, error: "APP_BASE_URL is not set" },
+    },
+  ] as const,
+});
+
+export function readPlatformReadiness(input: PlatformEnvInput): PlatformBundleReadiness {
+  const env = platformEnvSchema.parse(input);
+  return registry.getBundleDescriptor(registry.resolveBundleId(env)).readReadiness(input);
+}
+```
+
+## Sources and declarations
+
+The tarball ships its TypeScript sources under `src/` and its JavaScript and
+declarations under `dist/`. Each export's `types` condition names its
+declaration file, and its `core-source` condition names its source file. Read
+those before guessing at a contract.
+
+## Readiness codes
+
+The checker reports `OPENLUP_E_PORT_MISSING`, `OPENLUP_E_EVENT_UNHANDLED`,
+`OPENLUP_E_EVENT_DUPLICATE`, `OPENLUP_E_SCHEDULE_UNBOUND`, `OPENLUP_E_SCHEMA_BEHIND`,
+`OPENLUP_E_SET_MISMATCH` and `OPENLUP_E_ENV_MISSING`. Only a `ready` report admits
+its exact candidate. A host must provide complete installed metadata and selected-adapter
+observations; a report does not prove ACL, function bodies or recovery.
+
+## Using this package in an application
+
+- **Do not edit the installed package.** Do not change files under `node_modules/@openlup/`, and
+  do not patch it with `patch-package`, `overrides` or a fork.
+- **Change behaviour through seams.** Use this package's ports and options and your application's
+  own composition. If a seam is missing, raise an upstream issue.
+- **Copying source is ejection.** Copying this package's source into your application makes the
+  copy yours, including its upgrades.
+- **Upgrade every `@openlup/*` package together,** after reading each changelog's `Migration:`
+  blocks.
+- **Inside the OpenLup monorepo,** where this package is a workspace, the repository's root
+  `AGENTS.md` governs instead.

package/CHANGELOG.md

@@ -6,13 +6,41 @@ source previews may already ship some changes, and their release notes say
 which. Declaration snapshots track candidate drift, not a stable API or
 SemVer promise.
 
-## Unreleased — checkout recovery contracts
+## [Unreleased]
 
-- Add neutral checkout recovery evidence, method, operation and action contracts
-  to the existing payment surface. They describe guidance only and do not change
-  payment admission, renewal classification or enabled payment methods.
+## [0.13.0]
 
-## [Unreleased]
+- Publishable on the npm `latest` dist-tag as `0.13.0`, from tag
+  `openlup-core-v0.13.0`.
+
+- Add experimental outbox envelope/handler descriptors, structural validation, job lease and candidate readiness contracts.
+- Check package inventory, event ownership/coverage, actual bindings and qualified schema observations before admitting a new candidate.
+
+Migration: existing exports remain; compose the selected rail and bind its schema probe before activation. Unknown observations refuse the new candidate and do not stop a serving version.
+
+
+### Changed
+
+- `AGENTS.md` gains a required "Using this package in an application" section: do not edit or
+  patch the installed package, change behaviour through its seams, and upgrade every
+  `@openlup/*` package together. `docs:check` refuses a guide without it.
+
+## [0.12.0]
+
+### Removed
+
+- **API REMOVAL: the `./checkout` subpath.** It held only an
+  `Idempotency-Key` header-shape helper that no checkout path used.
+
+  Migration: replace
+
+  ```ts
+  import { validateCheckoutIdempotencyHeader } from "@openlup/core/checkout";
+  ```
+
+  with an application-owned validator, or delete the call if, like the
+  reference checkout, your checkout carries its idempotency key in the
+  request body.
 
 ### Changed
 
@@ -36,6 +64,15 @@ SemVer promise.
   `dunning_not_exhausted`. An exhaustive `switch` over the union must handle
   both.
 
+- `release-gates.json` sets `packageRelease.versionRule` to `0.N.P`. Below
+  1.0 every `@openlup/*` package carries one set version: a minor set for any
+  API, behaviour or schema change, a patch set for a fix only.
+
+  Migration: a tool that reads `versionRule` expects the set rule. Before:
+  `"versionRule": "0.<n>.0"`. After: `"versionRule": "0.N.P"`.
+
+- Publishable on the npm `latest` dist-tag as `0.12.0`, from tag
+  `openlup-core-v0.12.0`.
 - Publishable on the npm `preview` dist-tag as `0.11.0`, for source preview
   `openlup-source-preview/11`.
 - Publishable on the npm `preview` dist-tag as `0.10.0`, for source preview
@@ -65,6 +102,22 @@ SemVer promise.
 
 ### Added
 
+- `AGENTS.md` ships in the tarball. It states the package's kind and each
+  subpath's maturity, gives one wiring example that compiles in CI, points to
+  the shipped sources and declarations, and lists the readiness codes the
+  package raises (none yet).
+- `release-gates.json` schema 5 declares the package kind (`"kind": "kernel"`)
+  and splits the pack budget. Code files (dist JavaScript, declarations and
+  shipped sources) and root documentation and metadata files each have their
+  own caps on packed bytes and files; the tarball total stays as a backstop.
+
+  Migration: a tool that reads `release-gates.json` checks `schemaVersion: 5`.
+  Before: `"pack": { "maxPackedBytes": …, "maxFiles": … }`. After: `"pack": {
+  "code": { "maxPackedBytes": …, "maxFiles": … }, "docs": { … },
+  "maxPackedBytes": …, "maxFiles": … }`.
+- Add neutral checkout recovery evidence, method, operation and action contracts
+  to the existing payment surface. They describe guidance only and do not change
+  payment admission, renewal classification or enabled payment methods.
 - Export neutral lookup normalization from `./company-identity` for extensions.
 
 - `SUBSCRIPTION_STATUS_TRANSITIONS`, the frozen status matrix, and
@@ -226,6 +279,9 @@ SemVer promise.
 
 ## Release Status
 
-No npm version has been released yet. A `preview` version establishes no
-stable package API or supported upgrade channel. Add a dated section only
-after a version is published.
+Versions up to `0.11.0` were published on the npm `preview` dist-tag without
+sections of their own, so the `0.12.0` section also lists the changes they
+carried. A release-preparation pull request turns the Unreleased section into
+the next version's section; its release tag and npm record when it is
+published. No version establishes a stable package API or supported upgrade
+channel.

package/CONTRIBUTING.md

@@ -1,8 +1,10 @@
 # Contributing
 
 Commerce Core is public source for framework-independent commerce kernels.
-Its npm versions ride on the source previews (`preview` dist-tag only) and
-activate no separate package product or stable API.
+Below 1.0 its npm versions are set versions `0.N.P`, shared by every
+`@openlup/*` package and published on the `latest` dist-tag; versions up to
+`0.11.0` rode on the source previews (`preview` dist-tag only). No version
+activates a separate package product or stable API.
 
 ## Set up and verify
 

package/MAINTAINERS.md

@@ -1,7 +1,8 @@
 # Maintainers
 
 `@openlup/core` is maintained in the phase-5 platform monorepo. It is not an
-independent product; its versions ride on the source previews.
+independent product. Below 1.0 its versions are set versions `0.N.P`, shared by
+every `@openlup/*` package; versions up to `0.11.0` rode on the source previews.
 
 ## Responsibilities
 

package/README.md

@@ -1,14 +1,27 @@
 # Commerce Core
 
-`@openlup/core` is a framework-independent TypeScript workspace package of
-subscription and bundle commerce kernels, not a separate library product.
-
-> [!IMPORTANT]
-> Version `0.<n>.0` is packed from source preview `openlup-source-preview/<n>`,
-> staged with provenance and approved with 2FA, on the `preview` dist-tag only.
-> `npm publish` from this directory is refused. No version implies a stable
-> API or supported consumer path. Build, pack, and isolated-import checks are
-> package smoke evidence only.
+`@openlup/core` is the kernel of the `@openlup/*` package family: the
+framework-independent TypeScript contracts and logic for subscription and
+bundle commerce that the other packages and an application's composition read.
+Agents start with [AGENTS.md](AGENTS.md). Its "Using this package in an
+application" section, which `docs:check` requires, tells an application's agent
+not to edit or patch the installed package and to upgrade every `@openlup/*`
+package together.
+
+## Channel and stability
+
+- **Channel:** npm, on the `latest` dist-tag. Each version is published with
+  provenance from its release tag `openlup-core-v<version>` after a protected
+  release approval. Versions up to `0.11.0` were published on the `preview`
+  dist-tag only. `npm publish` from this directory is refused.
+- **Versions:** below 1.0 every `@openlup/*` package shares one set version
+  `0.N.P`: a minor set for any API, behaviour or schema change, a patch set for
+  a fix only.
+- **Stability:** development preview. Any version may change an export, and
+  each change is recorded in [the changelog](CHANGELOG.md). Pin an exact
+  version and read the changelog when you upgrade.
+
+The experimental `./outbox`, `./standard-schema` and `./readiness` subpaths provide shared infrastructure contracts. `checkReadiness` evaluates inert contribution descriptors, the complete host-observed package set, actual host bindings (schedule/route function identity must match the contribution) and a bounded schema probe. It never migrates, leases or sends. Only `ready` admits a new candidate; `unknown` and `unsatisfied` leave the serving candidate in place. The host owns inventory completeness, immutable artifact/configuration/schema identity and admission at every work entrance. Catalog existence does not prove SQL bodies, permissions or provider recovery.
 
 ## Package Surface Maturity
 
@@ -20,7 +33,6 @@ promise.
 | --- | --- | --- | --- |
 | `./bundle` | kernel | candidate | `smoke/subscriptionBundleStandalone.test.ts` |
 | `./catalog` | kernel | candidate | `smoke/catalogStandalone.test.ts` |
-| `./checkout` | kernel | experimental | `smoke/checkoutStandalone.test.ts` |
 | `./company-identity` | kernel | experimental | `smoke/companyIdentityStandalone.test.ts` |
 | `./fulfillment` | kernel | experimental | `smoke/fulfillmentStandalone.test.ts` |
 | `./inventory` | kernel | candidate | `smoke/inventoryStandalone.test.ts` |
@@ -33,6 +45,9 @@ promise.
 | `./risk` | kernel | candidate | `smoke/riskStandalone.test.ts` |
 | `./shipping` | kernel | candidate | `smoke/shippingStandalone.test.ts` |
 | `./subscription` | kernel | candidate | `smoke/subscriptionBundleStandalone.test.ts` |
+| `./outbox` | kernel | experimental | `smoke/outboxStandalone.test.ts` |
+| `./readiness` | kernel | experimental | `smoke/readinessStandalone.test.ts` |
+| `./standard-schema` | kernel | experimental | `smoke/standardSchemaStandalone.test.ts` |
 | `./testing` | testing | testing | `smoke/testingStandalone.test.ts` |
 
 `release-gates.json` records four distinct evidence classes:
@@ -45,9 +60,26 @@ promise.
 - `externalConsumerEvidence`: not yet evaluated; a first-party packed consumer
   remains package smoke, not external adoption.
 
-## Local verification
+## Use in an application
+
+From your application's root, with Node 24 and npm 11.19.0:
+
+```sh
+npm install --save-exact @openlup/core@0.12.0
+```
+
+Read the installed `AGENTS.md`, then compose the [typed wiring example](AGENTS.md#wiring-example)
+with your application's own ports and options. Inspect the shipped sources and
+declarations for the exact version you installed. A missing seam needs an
+upstream proposal under your application's submission authority; the dependency
+guide grants no permission to publish an issue or change your application.
+Keep every installed `@openlup/*` package on the same exact set version.
+
+## Local verification from source
 
-From this package directory:
+The following developer commands require a source checkout of this package;
+the npm tarball omits its development scripts and tests. From the source package
+directory:
 
 ```sh
 npm ci
@@ -55,12 +87,18 @@ npm run ci
 ```
 
 Focused proofs are `npm run api:check`, `npm run release:check`, and
-`npm run test:consumer`. The root test script skips this suite. A `preview`
-install is evaluation, not a supported install.
-
-Repository neutrality checks reuse the existing source scanner through
-[the tree counting interface](./scripts/neutrality-tree-counts.ts). This
-process interface reads JSON containing source paths, contents and a policy
+`npm run test:consumer`. The root test script skips this suite.
+`npm run docs:check` requires relative links in shipped Markdown to resolve to
+files actually packed in the tarball; a target present only in source refuses.
+Ambiguous destinations refuse explicitly: use literal punctuation or
+percent-encoded filenames, with ASCII whitespace before an optional title.
+Raw ampersands, angle characters and Unicode whitespace in local destinations
+require a canonical rewrite rather than passing an incomplete link check.
+
+The [repository neutrality checks](https://github.com/openlup/openlup/blob/openlup-core-v0.12.0/CONTRIBUTING.md#development-preview-checks)
+reuse the source scanner through `./scripts/neutrality-tree-counts.ts` relative
+to this source package. This process interface reads JSON containing source paths,
+contents and a policy
 from standard input, then emits finding counts for each path. Shell sources
 retain the scanner's existing shell handling. The interface adds no package
 export and changes no matcher or kernel behavior.
@@ -68,7 +106,7 @@ export and changes no matcher or kernel behavior.
 Repository lint keeps this package's production source independent of configured
 provider SDKs and explicit industry contract names. Adopter adapters compose
 providers; generic ports can forward opaque extension data. See the
-[syntax scope and exceptions](https://github.com/openlup/openlup/blob/main/CONTRIBUTING.md#development-preview-checks).
+[syntax scope and exceptions](https://github.com/openlup/openlup/blob/openlup-core-v0.12.0/CONTRIBUTING.md#development-preview-checks).
 
 The repository checker also calls the UI neutrality counting process with
 `--counts-json` to count its existing patterns over the supplied sources. Running that checker without
@@ -84,9 +122,9 @@ neutrality evidence, not package activation or consumer compatibility evidence.
 
 ## Kernel Documentation
 
+<!-- openlup-doc-impact {"unit":"core","digest":"sha256-bf338e121135843e55d78dab92d8620fd1dcd67be34e9302aef01ea893d361ba","reason":"Release preparation changes only the core manifest and its lockfile version from 0.12.0 to 0.13.0. Exports, dependencies, API snapshots, implementation, package gates and the installation and verification guidance remain unchanged; the changelog identifies the prepared set."} -->
+
 - [`docs/SUBSCRIPTION_ENGINE.md`](docs/SUBSCRIPTION_ENGINE.md) — what the
   `./subscription` kernel owns, its deterministic-clock contract, the
   late-payment cycle-shift rule and its monotonic clamp, and how a host
   application consumes it.
-
-<!-- openlup-doc-impact {"unit":"core","digest":"sha256-fbf1589b7a2c49f656a295c102b1076d8beaa5180bdc369ba575c462f39ec96f","reason":"The core manifest and lockfile advance only the lockstep version from 0.10.0 to 0.11.0. Exports, dependencies, package smoke, publication settings, and development-preview maturity remain unchanged."} -->

package/SECURITY.md

@@ -2,10 +2,10 @@
 
 ## Release Support
 
-No package version is supported. A `0.<n>.0` version on the `preview`
-dist-tag is development-preview evaluation, not a supported public release. A
-future support policy belongs to phase-5 public platform governance, not to a
-separate package release channel.
+No package version is supported. A `0.N.P` version, on the `preview` dist-tag
+up to `0.11.0` or on `latest` after it, is development-preview evaluation, not a
+supported public release. A future support policy belongs to phase-5 public
+platform governance, not to a separate package release channel.
 
 ## Vulnerability Reporting
 

package/dist/outbox/index.d.ts

@@ -0,0 +1,55 @@
+/** @beta Shared event envelope. Storage and execution policy belong to the rail. */
+export interface OutboxEventRow {
+    id: string;
+    created_at: string;
+    available_at: string;
+    processed_at: string | null;
+    aggregate_type: string;
+    aggregate_id: string;
+    event_type: string;
+    idempotency_key: string;
+    status: string;
+    attempts: number;
+    payload: Record<string, unknown>;
+    error: string | null;
+    metadata: Record<string, unknown>;
+}
+/** @beta */
+export type OutboxHandlerOutcome = {
+    kind: "processed";
+    detail?: Record<string, unknown>;
+} | {
+    kind: "retry";
+    reason: string;
+} | {
+    kind: "discard";
+    reason: string;
+    benign?: boolean;
+} | {
+    kind: "snooze";
+    reason: string;
+};
+/** @beta Phase observations are transient; never put payloads or credentials here. */
+export interface OutboxHandlerExecutionContext {
+    setPhase(phase: string): void;
+}
+/** @beta Inert registration shared by preflight and the run-bound builder. */
+export interface OutboxHandlerDescriptor {
+    readonly eventType: string;
+    readonly timeoutMs: number;
+}
+/** @beta Structural abort signal, shared by browser and server implementations. */
+export interface OutboxAbortSignal {
+    readonly aborted: boolean;
+    readonly reason: unknown;
+    addEventListener(type: "abort", listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    removeEventListener(type: "abort", listener: () => void): void;
+}
+/** @beta Effects must be idempotent and honor the abort signal. */
+export interface OutboxHandler<Signal extends OutboxAbortSignal = OutboxAbortSignal> extends OutboxHandlerDescriptor {
+    handle(row: OutboxEventRow, signal: Signal, execution?: OutboxHandlerExecutionContext): Promise<OutboxHandlerOutcome>;
+}
+export { PLATFORM_EVENT_VOCABULARY } from "./vocabulary.js";
+export type { EventVocabularyEntry } from "./vocabulary.js";

package/dist/outbox/index.js

@@ -0,0 +1 @@
+export { PLATFORM_EVENT_VOCABULARY } from "./vocabulary.js";

package/dist/outbox/vocabulary.d.ts

@@ -0,0 +1,7 @@
+/** @beta Vocabulary ownership is separate from consumer registration. */
+export interface EventVocabularyEntry {
+    eventType: string;
+    owner: string;
+}
+/** @beta Applications supply their complete ordered persisted vocabulary separately. */
+export declare const PLATFORM_EVENT_VOCABULARY: readonly EventVocabularyEntry[];

package/dist/outbox/vocabulary.js

@@ -0,0 +1,36 @@
+/** @beta Applications supply their complete ordered persisted vocabulary separately. */
+export const PLATFORM_EVENT_VOCABULARY = [
+    { eventType: "commerce.order_draft.created", owner: "@openlup/core" },
+    { eventType: "commerce.order.paid", owner: "@openlup/core" },
+    { eventType: "commerce.order.paid.email", owner: "@openlup/core" },
+    { eventType: "commerce.payment.failed", owner: "@openlup/core" },
+    { eventType: "commerce.checkout.expired", owner: "@openlup/core" },
+    { eventType: "commerce.order.canceled", owner: "@openlup/core" },
+    { eventType: "commerce.order.refunded", owner: "@openlup/core" },
+    { eventType: "commerce.shipment.dispatched", owner: "@openlup/core" },
+    { eventType: "commerce.shipment.delivered", owner: "@openlup/core" },
+    { eventType: "commerce.shipment.exception", owner: "@openlup/core" },
+    { eventType: "commerce.return.approved", owner: "@openlup/core" },
+    { eventType: "commerce.return.rejected", owner: "@openlup/core" },
+    { eventType: "commerce.order.review_request", owner: "@openlup/core" },
+    { eventType: "commerce.order.review_effects", owner: "@openlup/core" },
+    { eventType: "commerce.product.back_in_stock", owner: "@openlup/core" },
+    { eventType: "commerce.order_draft.abandoned.1h", owner: "@openlup/core" },
+    { eventType: "commerce.order_draft.abandoned.24h", owner: "@openlup/core" },
+    { eventType: "commerce.order_draft.abandoned.72h", owner: "@openlup/core" },
+    { eventType: "commerce.order.reorder_reminder", owner: "@openlup/core" },
+    { eventType: "commerce.checkout_recovery", owner: "@openlup/core" },
+    { eventType: "subscription.cancelled", owner: "@openlup/core" },
+    { eventType: "subscription.created", owner: "@openlup/core" },
+    { eventType: "subscription.activation_action_required", owner: "@openlup/core" },
+    { eventType: "subscription.pause_reminder_due", owner: "@openlup/core" },
+    { eventType: "subscription.paused", owner: "@openlup/core" },
+    { eventType: "subscription.resumed", owner: "@openlup/core" },
+    { eventType: "subscription.delivery_rescheduled", owner: "@openlup/core" },
+    { eventType: "subscription.cycle_skipped", owner: "@openlup/core" },
+    { eventType: "subscription.address_changed", owner: "@openlup/core" },
+    { eventType: "subscription.package_changed", owner: "@openlup/core" },
+    { eventType: "subscription.renewal_upcoming", owner: "@openlup/core" },
+    { eventType: "accounting.order.reversal_requested", owner: "@openlup/core" },
+    { eventType: "commerce.fulfillment.handed_over", owner: "@openlup/core" },
+];

package/dist/platform-runtime/index.d.ts

@@ -8,3 +8,4 @@ export { createPlatformBundleRegistry, platformEnvSchema, } from "./platformKern
 export type { CreatePlatformBundleRegistryInput, PlatformBundleDescriptor, PlatformBundleRegistry, PlatformBundleReadiness, PlatformEnv, PlatformEnvInput, } from "./platformKernel.js";
 /** @beta */
 export type { AnalyticsPort, BlobStoragePort, DataGatewayPort, HttpRuntimePort, MigrationRunnerPort, PlatformHttpRequest, PlatformHttpResponse, SchedulerPort, TransactionalRuntimePort, } from "./ports.js";
+export type { JobLeasePort, PlatformJobTriggerKind, PlatformJobInvocation, PlatformJobClaim, PlatformJobFinishStatus, PlatformJobFinishSummary } from "./ports.js";

package/dist/platform-runtime/ports.d.ts

@@ -98,3 +98,27 @@ export interface TransactionalRuntimePort {
         status: number;
     }>;
 }
+/** @beta Invocation evidence and claim/finish contract shared by infrastructure rails. */
+export type PlatformJobTriggerKind = "worker" | "scheduler" | "operator";
+export type PlatformJobInvocation = {
+    triggerKind: PlatformJobTriggerKind;
+    /** Observational adapter evidence; it never grants execution authority. */
+    invocationSource: string;
+};
+export type PlatformJobClaim = {
+    acquired: boolean;
+    runId: string | null;
+    reason: string;
+};
+export type PlatformJobFinishStatus = "success" | "failed";
+export type PlatformJobFinishSummary = {
+    checked: number;
+    updated: number;
+    failures: number;
+    skipped: boolean;
+    reason?: string;
+};
+export interface JobLeasePort {
+    claimJobRun(jobName: string, invocation: PlatformJobInvocation, leaseSeconds?: number): Promise<PlatformJobClaim>;
+    finishJobRun(jobName: string, runId: string, invocation: PlatformJobInvocation, status: PlatformJobFinishStatus, result: PlatformJobFinishSummary, extraMetadata?: Record<string, unknown>): Promise<boolean>;
+}

package/dist/readiness/contracts.d.ts

@@ -0,0 +1,121 @@
+import type { OutboxHandlerDescriptor } from "../outbox/index.js";
+import type { EventVocabularyEntry } from "../outbox/vocabulary.js";
+/** @beta */
+export declare const READINESS_CODES: readonly ["OPENLUP_E_PORT_MISSING", "OPENLUP_E_EVENT_UNHANDLED", "OPENLUP_E_EVENT_DUPLICATE", "OPENLUP_E_SCHEDULE_UNBOUND", "OPENLUP_E_SCHEMA_BEHIND", "OPENLUP_E_SET_MISMATCH", "OPENLUP_E_ENV_MISSING"];
+/** @beta */
+export type ReadinessCode = typeof READINESS_CODES[number];
+/** @beta */
+export interface ReadinessIssue {
+    code: ReadinessCode;
+    package: string;
+    subject: string;
+    fix: string;
+    observation?: string;
+}
+/** @beta */
+export interface SchemaObject {
+    kind: "table" | "column" | "function";
+    name: string;
+    signature?: string;
+}
+/** @beta Version is an adapter-specific migration identity, not inferred from object existence. */
+export interface RequiredSchema {
+    version: string;
+    migration: string;
+    objects: readonly SchemaObject[];
+}
+/** @beta */
+export interface PackageManifest {
+    name: string;
+    version: string;
+    kind: "kernel" | "rail" | "capability" | "implementation";
+    emits: readonly string[];
+    handles: readonly string[];
+    schedules: readonly {
+        id: string;
+        cadenceSeconds: number;
+    }[];
+    routes: readonly string[];
+    requiredPorts: readonly string[];
+    env: readonly string[];
+    requiredSchema?: RequiredSchema;
+}
+/** @beta Run-bound handlers are represented by their shared inert descriptors. */
+export interface Contribution {
+    manifest: PackageManifest;
+    handlers: readonly OutboxHandlerDescriptor[];
+    schedules: readonly {
+        id: string;
+        cadenceSeconds: number;
+        run: (...args: never[]) => unknown;
+    }[];
+    routes: readonly {
+        id: string;
+        handle: (...args: never[]) => unknown;
+    }[];
+}
+/** @beta Host-observed inventory, including core. The loader owns completeness. */
+export interface LoadedPackage {
+    name: string;
+    version: string;
+    kind: PackageManifest["kind"];
+}
+/** @beta Candidate identity must change when configuration, schema or artifact changes. */
+export interface CandidateIdentity {
+    artifact: string;
+    configuration: string;
+    environment: string;
+    database: string;
+    schema: string;
+}
+/** @beta */
+export interface EventExemption {
+    pattern: string;
+    prefix: boolean;
+    owner: string;
+    reason: string;
+    state: "ignored" | "dormant";
+}
+/** @beta */
+export interface ReadinessInput {
+    candidate: CandidateIdentity;
+    inventoryComplete: boolean;
+    loadedPackages: readonly LoadedPackage[];
+    contributions: readonly Contribution[];
+    vocabulary: readonly EventVocabularyEntry[];
+    exemptions: readonly EventExemption[];
+    bindings: {
+        ports: Readonly<Record<string, unknown>>;
+        triggers: Readonly<Record<string, unknown>>;
+        routes: Readonly<Record<string, unknown>>;
+        env: Readonly<Record<string, string | undefined>>;
+    };
+    schemaProbe: SchemaProbePort;
+    probeTimeoutMs?: number;
+}
+/** @beta A bounded catalog observation, not proof of SQL bodies, ACL or recovery. */
+export interface SchemaObservation {
+    database: string;
+    version: string | null;
+    objects: readonly {
+        object: SchemaObject;
+        present: boolean | null;
+    }[];
+}
+/** @beta */
+export interface SchemaProbePort {
+    observe(requirement: RequiredSchema): Promise<SchemaObservation>;
+}
+/** @beta Each operation commits before resolving; never lend a producer transaction to dispatch. */
+export interface SqlExecutor {
+    query<Row extends Record<string, unknown> = Record<string, unknown>>(text: string, values?: readonly unknown[]): Promise<{
+        rows: Row[];
+    }>;
+}
+/** @beta */
+export interface ReadinessReport {
+    state: "ready" | "unsatisfied" | "unknown";
+    candidate: CandidateIdentity;
+    loadedPackages: readonly LoadedPackage[];
+    issues: readonly ReadinessIssue[];
+}

package/dist/readiness/contracts.js

@@ -0,0 +1,2 @@
+/** @beta */
+export const READINESS_CODES = ["OPENLUP_E_PORT_MISSING", "OPENLUP_E_EVENT_UNHANDLED", "OPENLUP_E_EVENT_DUPLICATE", "OPENLUP_E_SCHEDULE_UNBOUND", "OPENLUP_E_SCHEMA_BEHIND", "OPENLUP_E_SET_MISMATCH", "OPENLUP_E_ENV_MISSING"];