@openlup/core 0.10.0 → 0.12.0

package/AGENTS.md

@@ -0,0 +1,83 @@
+# `@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 |
+| `./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
+
+This version raises no `OPENLUP_E_*` readiness code.

package/CHANGELOG.md

@@ -6,13 +6,24 @@ 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.12.0]
 
-## [Unreleased]
+### 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 +47,17 @@ 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
   `openlup-source-preview/10`.
 - Publishable on the npm `preview` dist-tag as `0.9.0`, for source preview
@@ -63,6 +85,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
@@ -224,6 +262,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
 
@@ -15,7 +17,7 @@ npm run ci
 
 The gate builds every export, runs standalone tests and isolated package smoke,
 verifies declaration snapshots, and checks license, SBOM, audit, pack, and
-publish controls. Neither the root test script nor root CI runs it.
+publish controls. Root Vitest excludes this suite; CI's required test job runs it separately.
 
 ## Scope
 

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,22 @@
 # 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).
+
+## 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.
 
 ## Package Surface Maturity
 
@@ -20,7 +28,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` |
@@ -55,8 +62,7 @@ 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.
+`npm run test:consumer`. The root test script skips this suite.
 
 Repository neutrality checks reuse the existing source scanner through
 [the tree counting interface](./scripts/neutrality-tree-counts.ts). This
@@ -88,5 +94,3 @@ neutrality evidence, not package activation or consumer compatibility evidence.
   `./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-074e25741bf9bc6c0c2717eaa0af20b26a5d219c4a082397b702bfc12e2e245f","reason":"Against the integrated main base, the core manifest and lockfile still advance only the lockstep version from 0.9.0 to 0.10.0. Exports, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlup/core",
-  "version": "0.10.0",
+  "version": "0.12.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",
@@ -74,16 +75,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",

package/release-gates.json

@@ -1,5 +1,6 @@
 {
-  "schemaVersion": 4,
+  "schemaVersion": 5,
+  "kind": "kernel",
   "compatibilityPolicies": {
     "internal-candidate": "Candidate package surfaces may change until the platform phase-5 activation explicitly freezes a public API.",
     "testing-internal": "Test-support surfaces may change and are not runtime compatibility promises."
@@ -8,7 +9,7 @@
     "phase": "platform-monorepo-phase-5",
     "publicStability": "not-claimed",
     "artifactChannel": "npm-staged-preview",
-    "versionRule": "0.<n>.0"
+    "versionRule": "0.N.P"
   },
   "evidence": {
     "packageSmokeEvidence": {
@@ -53,14 +54,6 @@
       "entrypoint": "dist/pricing/index.d.ts",
       "snapshot": "api/pricing.api.md"
     },
-    "./checkout": {
-      "role": "kernel",
-      "maturity": "experimental",
-      "compatibilityPolicy": "internal-candidate",
-      "packageSmokeEvidence": ["smoke/checkoutStandalone.test.ts"],
-      "entrypoint": "dist/checkout/index.d.ts",
-      "snapshot": "api/checkout.api.md"
-    },
     "./company-identity": {
       "role": "kernel",
       "maturity": "experimental",
@@ -209,11 +202,20 @@
     }
   },
   "pack": {
-    "$raiseReason": "2026-09-27, owner-approved: the subscription status matrix, the win-back and the exhausted-ladder pause and resume add four functions, one predicate and two constants with their JSDoc, including the host duties the managed SQL restarts keep, JavaScript and declaration outputs, plus their changelog entry. Measured, not estimated: clean origin/main packs 122809 packed bytes, 534452 unpacked bytes and 192 files; this change packs about 130.3 thousand packed and 569.7 thousand unpacked bytes (rounded, because this note's own text moves the last digits) and 192 files. Packed allowance increases by 8192 bytes and unpacked by 38912 bytes; maxFiles stays 192. The package export map, dependencies and all other release gates are unchanged; the ./subscription entry gains named exports. The previous raise, 2026-09-11 and owner-approved, moved packed by 2048 and unpacked by 6144 bytes for checkout refusal recovery.",
-    "maxPackedBytes": 131072,
-    "maxUnpackedBytes": 573440,
-    "maxFiles": 192,
+    "$budgetReason": "2026-10-02, owner-approved at the patch read: the pack budget splits into classes so that documentation and metadata cannot crowd out code, and code growth stays visible. Code counts dist JavaScript, declarations and src TypeScript; docs counts the documentation and metadata files at the package root; anything else counts only toward the total. A class's packed bytes are its files gzipped together. Measured, not estimated: clean origin/main packs 131062 packed bytes, 572032 unpacked bytes and 192 files against caps of 131072, 573440 and 192. With AGENTS.md this change packs about 132.1 thousand packed and 575.7 thousand unpacked bytes and 193 files: code exactly 113573 packed bytes in 183 files, docs about 17.9 thousand packed bytes in 10 files (rounded, because this note's own text moves the last digits). The code caps of 114688 bytes and 183 files admit no new code file without a raise. The docs caps are 24576 bytes and 12 files. The total backstop is the sum of the class caps, 139264 packed bytes and 195 files, with 614400 unpacked bytes.",
+    "code": {
+      "maxPackedBytes": 114688,
+      "maxFiles": 183
+    },
+    "docs": {
+      "maxPackedBytes": 24576,
+      "maxFiles": 12
+    },
+    "maxPackedBytes": 139264,
+    "maxUnpackedBytes": 614400,
+    "maxFiles": 195,
     "requiredFiles": [
+      "AGENTS.md",
       "CHANGELOG.md",
       "CODE_OF_CONDUCT.md",
       "CONTRIBUTING.md",

package/dist/checkout/idempotency.d.ts

@@ -1,29 +0,0 @@
-/**
- * Reference checkout idempotency-key contract.
- *
- * This module validates the shape of a header-bound idempotency key only. The
- * current product checkout validates body `intent.idempotencyKey`, not this
- * header contract; downstream checkout runtimes must explicitly wire this
- * helper before treating the header as authoritative.
- *
- * Callers own any persistence workflow for inserting, replaying, or completing
- * a checkout idempotency record.
- */
-/** @beta */
-export declare const CHECKOUT_IDEMPOTENCY_KEY_HEADER = "idempotency-key";
-/** @beta */
-export type CheckoutIdempotencyRejection = {
-    reason: "missing";
-    message: string;
-} | {
-    reason: "malformed";
-    message: string;
-};
-/** @beta */
-export declare function validateCheckoutIdempotencyHeader(headerValue: string | undefined | null): {
-    ok: true;
-    key: string;
-} | {
-    ok: false;
-    rejection: CheckoutIdempotencyRejection;
-};

package/dist/checkout/idempotency.js

@@ -1,37 +0,0 @@
-/**
- * Reference checkout idempotency-key contract.
- *
- * This module validates the shape of a header-bound idempotency key only. The
- * current product checkout validates body `intent.idempotencyKey`, not this
- * header contract; downstream checkout runtimes must explicitly wire this
- * helper before treating the header as authoritative.
- *
- * Callers own any persistence workflow for inserting, replaying, or completing
- * a checkout idempotency record.
- */
-/** @beta */
-export const CHECKOUT_IDEMPOTENCY_KEY_HEADER = "idempotency-key";
-const UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-/** @beta */
-export function validateCheckoutIdempotencyHeader(headerValue) {
-    if (headerValue === undefined || headerValue === null || headerValue.trim().length === 0) {
-        return {
-            ok: false,
-            rejection: {
-                reason: "missing",
-                message: `Missing required ${CHECKOUT_IDEMPOTENCY_KEY_HEADER} header.`,
-            },
-        };
-    }
-    const trimmed = headerValue.trim();
-    if (!UUID_V4_PATTERN.test(trimmed)) {
-        return {
-            ok: false,
-            rejection: {
-                reason: "malformed",
-                message: `${CHECKOUT_IDEMPOTENCY_KEY_HEADER} must be a UUID v4.`,
-            },
-        };
-    }
-    return { ok: true, key: trimmed };
-}

package/dist/checkout/index.d.ts

@@ -1,2 +0,0 @@
-/** @beta */
-export * from "./idempotency.js";

package/dist/checkout/index.js

@@ -1,2 +0,0 @@
-/** @beta */
-export * from "./idempotency.js";

package/src/checkout/idempotency.ts

@@ -1,49 +0,0 @@
-/**
- * Reference checkout idempotency-key contract.
- *
- * This module validates the shape of a header-bound idempotency key only. The
- * current product checkout validates body `intent.idempotencyKey`, not this
- * header contract; downstream checkout runtimes must explicitly wire this
- * helper before treating the header as authoritative.
- *
- * Callers own any persistence workflow for inserting, replaying, or completing
- * a checkout idempotency record.
- */
-
-/** @beta */
-export const CHECKOUT_IDEMPOTENCY_KEY_HEADER = "idempotency-key";
-
-const UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-
-/** @beta */
-export type CheckoutIdempotencyRejection =
-  | { reason: "missing"; message: string }
-  | { reason: "malformed"; message: string };
-
-/** @beta */
-export function validateCheckoutIdempotencyHeader(
-  headerValue: string | undefined | null,
-): { ok: true; key: string } | { ok: false; rejection: CheckoutIdempotencyRejection } {
-  if (headerValue === undefined || headerValue === null || headerValue.trim().length === 0) {
-    return {
-      ok: false,
-      rejection: {
-        reason: "missing",
-        message: `Missing required ${CHECKOUT_IDEMPOTENCY_KEY_HEADER} header.`,
-      },
-    };
-  }
-
-  const trimmed = headerValue.trim();
-  if (!UUID_V4_PATTERN.test(trimmed)) {
-    return {
-      ok: false,
-      rejection: {
-        reason: "malformed",
-        message: `${CHECKOUT_IDEMPOTENCY_KEY_HEADER} must be a UUID v4.`,
-      },
-    };
-  }
-
-  return { ok: true, key: trimmed };
-}

package/src/checkout/index.ts

@@ -1,2 +0,0 @@
-/** @beta */
-export * from "./idempotency.js";