@openlup/core 0.12.0 → 0.13.1

package/release-gates.json

@@ -34,7 +34,9 @@
       "role": "kernel",
       "maturity": "candidate",
       "compatibilityPolicy": "internal-candidate",
-      "packageSmokeEvidence": ["smoke/subscriptionBundleStandalone.test.ts"],
+      "packageSmokeEvidence": [
+        "smoke/subscriptionBundleStandalone.test.ts"
+      ],
       "entrypoint": "dist/subscription/index.d.ts",
       "snapshot": "api/subscription.api.md"
     },
@@ -42,7 +44,9 @@
       "role": "kernel",
       "maturity": "candidate",
       "compatibilityPolicy": "internal-candidate",
-      "packageSmokeEvidence": ["smoke/subscriptionBundleStandalone.test.ts"],
+      "packageSmokeEvidence": [
+        "smoke/subscriptionBundleStandalone.test.ts"
+      ],
       "entrypoint": "dist/bundle/contracts.d.ts",
       "snapshot": "api/bundle.api.md"
     },
@@ -50,7 +54,9 @@
       "role": "kernel",
       "maturity": "candidate",
       "compatibilityPolicy": "internal-candidate",
-      "packageSmokeEvidence": ["smoke/pricingStandalone.test.ts"],
+      "packageSmokeEvidence": [
+        "smoke/pricingStandalone.test.ts"
+      ],
       "entrypoint": "dist/pricing/index.d.ts",
       "snapshot": "api/pricing.api.md"
     },
@@ -58,7 +64,9 @@
       "role": "kernel",
       "maturity": "experimental",
       "compatibilityPolicy": "internal-candidate",
-      "packageSmokeEvidence": ["smoke/companyIdentityStandalone.test.ts"],
+      "packageSmokeEvidence": [
+        "smoke/companyIdentityStandalone.test.ts"
+      ],
       "entrypoint": "dist/company-identity/index.d.ts",
       "snapshot": "api/company-identity.api.md"
     },
@@ -66,7 +74,9 @@
       "role": "kernel",
       "maturity": "experimental",
       "compatibilityPolicy": "internal-candidate",
-      "packageSmokeEvidence": ["smoke/fulfillmentStandalone.test.ts"],
+      "packageSmokeEvidence": [
+        "smoke/fulfillmentStandalone.test.ts"
+      ],
       "entrypoint": "dist/fulfillment/index.d.ts",
       "snapshot": "api/fulfillment.api.md"
     },
@@ -74,7 +84,9 @@
       "role": "kernel",
       "maturity": "candidate",
       "compatibilityPolicy": "internal-candidate",
-      "packageSmokeEvidence": ["smoke/inventoryStandalone.test.ts"],
+      "packageSmokeEvidence": [
+        "smoke/inventoryStandalone.test.ts"
+      ],
       "entrypoint": "dist/inventory/index.d.ts",
       "snapshot": "api/inventory.api.md"
     },
@@ -82,7 +94,9 @@
       "role": "kernel",
       "maturity": "candidate",
       "compatibilityPolicy": "internal-candidate",
-      "packageSmokeEvidence": ["smoke/shippingStandalone.test.ts"],
+      "packageSmokeEvidence": [
+        "smoke/shippingStandalone.test.ts"
+      ],
       "entrypoint": "dist/shipping/index.d.ts",
       "snapshot": "api/shipping.api.md"
     },
@@ -90,7 +104,9 @@
       "role": "kernel",
       "maturity": "candidate",
       "compatibilityPolicy": "internal-candidate",
-      "packageSmokeEvidence": ["smoke/catalogStandalone.test.ts"],
+      "packageSmokeEvidence": [
+        "smoke/catalogStandalone.test.ts"
+      ],
       "entrypoint": "dist/catalog/index.d.ts",
       "snapshot": "api/catalog.api.md"
     },
@@ -98,7 +114,9 @@
       "role": "kernel",
       "maturity": "candidate",
       "compatibilityPolicy": "internal-candidate",
-      "packageSmokeEvidence": ["smoke/promoStandalone.test.ts"],
+      "packageSmokeEvidence": [
+        "smoke/promoStandalone.test.ts"
+      ],
       "entrypoint": "dist/promo/index.d.ts",
       "snapshot": "api/promo.api.md"
     },
@@ -106,7 +124,9 @@
       "role": "kernel",
       "maturity": "candidate",
       "compatibilityPolicy": "internal-candidate",
-      "packageSmokeEvidence": ["smoke/riskStandalone.test.ts"],
+      "packageSmokeEvidence": [
+        "smoke/riskStandalone.test.ts"
+      ],
       "entrypoint": "dist/risk/index.d.ts",
       "snapshot": "api/risk.api.md"
     },
@@ -114,7 +134,9 @@
       "role": "kernel",
       "maturity": "experimental",
       "compatibilityPolicy": "internal-candidate",
-      "packageSmokeEvidence": ["smoke/marketingResearchStandalone.test.ts"],
+      "packageSmokeEvidence": [
+        "smoke/marketingResearchStandalone.test.ts"
+      ],
       "entrypoint": "dist/marketing/research/index.d.ts",
       "snapshot": "api/marketing-research.api.md"
     },
@@ -122,7 +144,9 @@
       "role": "kernel",
       "maturity": "experimental",
       "compatibilityPolicy": "internal-candidate",
-      "packageSmokeEvidence": ["smoke/partnersStandalone.test.ts"],
+      "packageSmokeEvidence": [
+        "smoke/partnersStandalone.test.ts"
+      ],
       "entrypoint": "dist/partners/index.d.ts",
       "snapshot": "api/partners.api.md"
     },
@@ -130,7 +154,9 @@
       "role": "kernel",
       "maturity": "experimental",
       "compatibilityPolicy": "internal-candidate",
-      "packageSmokeEvidence": ["smoke/paymentStandalone.test.ts"],
+      "packageSmokeEvidence": [
+        "smoke/paymentStandalone.test.ts"
+      ],
       "entrypoint": "dist/payment/index.d.ts",
       "snapshot": "api/payment.api.md"
     },
@@ -138,15 +164,49 @@
       "role": "kernel",
       "maturity": "experimental",
       "compatibilityPolicy": "internal-candidate",
-      "packageSmokeEvidence": ["smoke/platformRuntimeStandalone.test.ts"],
+      "packageSmokeEvidence": [
+        "smoke/platformRuntimeStandalone.test.ts"
+      ],
       "entrypoint": "dist/platform-runtime/index.d.ts",
       "snapshot": "api/platform-runtime.api.md"
     },
+    "./outbox": {
+      "role": "kernel",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "smoke/outboxStandalone.test.ts"
+      ],
+      "entrypoint": "dist/outbox/index.d.ts",
+      "snapshot": "api/outbox.api.md"
+    },
+    "./readiness": {
+      "role": "kernel",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "smoke/readinessStandalone.test.ts"
+      ],
+      "entrypoint": "dist/readiness/index.d.ts",
+      "snapshot": "api/readiness.api.md"
+    },
+    "./standard-schema": {
+      "role": "kernel",
+      "maturity": "experimental",
+      "compatibilityPolicy": "internal-candidate",
+      "packageSmokeEvidence": [
+        "smoke/standardSchemaStandalone.test.ts"
+      ],
+      "entrypoint": "dist/standard-schema/index.d.ts",
+      "snapshot": "api/standard-schema.api.md"
+    },
     "./testing": {
       "role": "testing",
       "maturity": "testing",
       "compatibilityPolicy": "testing-internal",
-      "packageSmokeEvidence": ["smoke/testingStandalone.test.ts"],
+      "packageSmokeEvidence": [
+        "smoke/testingStandalone.test.ts"
+      ],
       "entrypoint": "dist/testing.d.ts",
       "snapshot": "api/testing.api.md"
     }
@@ -202,18 +262,18 @@
     }
   },
   "pack": {
-    "$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.",
+    "$budgetReason": "2026-10-05, owner-approved shared-contract growth: seven new source files add 21 source/runtime/declaration artifacts. The measured contribution has 198 code files, 15 above the prior cap, and 127202 code gzip bytes. The code budget is 131072 bytes/198 files; documentation stays at 24576 bytes/12 files. The total budget is 155648 packed bytes/655360 unpacked bytes/211 files, including the shipped documentation outside the root-file class. These bounded increases cover the outbox envelope, candidate-readiness and Standard Schema contracts; later growth still requires a measured budget decision.",
     "code": {
-      "maxPackedBytes": 114688,
-      "maxFiles": 183
+      "maxPackedBytes": 131072,
+      "maxFiles": 198
     },
     "docs": {
       "maxPackedBytes": 24576,
       "maxFiles": 12
     },
-    "maxPackedBytes": 139264,
-    "maxUnpackedBytes": 614400,
-    "maxFiles": 195,
+    "maxPackedBytes": 155648,
+    "maxUnpackedBytes": 655360,
+    "maxFiles": 211,
     "requiredFiles": [
       "AGENTS.md",
       "CHANGELOG.md",

package/src/outbox/index.ts

@@ -0,0 +1,44 @@
+/** @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/src/outbox/vocabulary.ts

@@ -0,0 +1,38 @@
+/** @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 const PLATFORM_EVENT_VOCABULARY: readonly EventVocabularyEntry[] = [
+  { 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/src/platform-runtime/index.ts

@@ -34,3 +34,5 @@ export type {
   SchedulerPort,
   TransactionalRuntimePort,
 } from "./ports.js";
+
+export type { JobLeasePort, PlatformJobTriggerKind, PlatformJobInvocation, PlatformJobClaim, PlatformJobFinishStatus, PlatformJobFinishSummary } from "./ports.js";

package/src/platform-runtime/ports.ts

@@ -86,3 +86,46 @@ export interface AnalyticsPort {
 export interface TransactionalRuntimePort {
   invoke(functionName: string, payload: unknown): Promise<{ ok: boolean; 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/src/readiness/contracts.ts

@@ -0,0 +1,57 @@
+import type { OutboxHandlerDescriptor } from "../outbox/index.js";
+import type { EventVocabularyEntry } from "../outbox/vocabulary.js";
+/** @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"] as const;
+/** @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/src/readiness/declarations.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import type { ReadinessInput, ReadinessIssue, Contribution } from "./contracts.js";
+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: ReadinessInput): ReadinessIssue[] {
+  const issues: ReadinessIssue[] = [];
+  const issue = (subject: string, fix: string, code: ReadinessIssue["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 as readonly Contribution[]) {
+    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/src/readiness/index.ts

@@ -0,0 +1,97 @@
+import { declarationIssues, manifestShape, schemaObjectShape } from "./declarations.js";
+import { schemaObjectKey } from "./schemaProbe.js";
+import type { ReadinessInput, ReadinessIssue, ReadinessReport, RequiredSchema, SchemaObservation, Contribution } 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 async function checkReadiness(input: ReadinessInput): Promise<ReadinessReport> {
+  const issues = declarationIssues(input);
+  let unknown = issues.some((i) => ["input", "candidate", "inventory", "loaded-package", "schemaProbe", "probeTimeoutMs"].includes(i.subject));
+  const add = (code: ReadinessIssue["code"], pkg: string, subject: string, fix: string, observation?: string) => {
+    issues.push({ code, package: pkg, subject, fix, ...(observation ? { observation } : {}) });
+  };
+  const report = (): ReadinessReport => ({ 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: readonly Contribution[] = input.contributions.filter((c: Contribution) => 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<string, number>();
+  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<string,string[]>(); const emitters = new Map<string,string[]>();
+  const events = new Set<string>();
+  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: unknown;
+    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: unknown, requirement: RequiredSchema): value is SchemaObservation {
+  if (!value || typeof value !== "object") return false;
+  const v = value as SchemaObservation;
+  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<string>();
+  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: ReadinessInput, requirement: RequiredSchema): Promise<unknown> {
+  const timers = globalThis as unknown as { setTimeout(callback: () => void, ms: number): unknown; clearTimeout(handle: unknown): void };
+  let timer: unknown;
+  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: unknown): boolean { return typeof value === "function" || (value !== null && typeof value === "object" && !Array.isArray(value)); }

package/src/readiness/schemaProbe.ts

@@ -0,0 +1,24 @@
+import type { SchemaObject, SqlExecutor, SchemaProbePort, RequiredSchema } from "./contracts.js";
+/** @beta Identity distinguishes overloads and qualified columns. */
+export function schemaObjectKey(object: SchemaObject): string {
+  return `${object.kind}:${object.name}${object.kind === "function" ? `(${object.signature ?? ""})` : ""}`;
+}
+/** @beta Parameterized catalog queries; this builder performs no I/O. */
+export function buildSchemaObjectProbe(object: SchemaObject): { text: string; values: readonly unknown[] } {
+  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: SqlExecutor, identity: (requirement: RequiredSchema) => Promise<{ database: string; version: string | null }>): SchemaProbePort {
+  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/src/standard-schema/index.ts

@@ -0,0 +1,17 @@
+/** @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 })[];
+}