@openlup/core 0.15.0 → 0.17.0

package/AGENTS.md

@@ -89,6 +89,8 @@ The checker reports `OPENLUP_E_PORT_MISSING`, `OPENLUP_E_EVENT_UNHANDLED`,
 its exact candidate. A host must provide complete installed metadata and selected-adapter
 observations; a report does not prove ACL, function bodies or recovery.
 
+See [module readiness](README.md#module-readiness) for logical modules.
+
 ## Using this package in an application
 
 - **Do not edit the installed package.** Do not change files under `node_modules/@openlup/`, and

package/CHANGELOG.md

@@ -8,6 +8,27 @@ SemVer promise.
 
 ## [Unreleased]
 
+## [0.17.0]
+
+- Publishable on the npm `latest` dist-tag as `0.17.0`, from tag
+  `openlup-core-v0.17.0`.
+
+- Republish unchanged APIs, runtime behavior and shipped SQL as part of the
+  complete `0.17.0` package set.
+
+Baseline evidence (2026-10-20): published `0.16.0` tarball 161,232 packed bytes,
+SHA256 `48abf4ea8ddc446b8d6e2c610801e2cfcbe5575743bd5a61fbb8b8b50a2b36a3`.
+The initial `0.16.0` release-gates baseline is retained under S1 option B.
+
+## [0.16.0]
+
+- Publishable on the npm `latest` dist-tag as `0.16.0`, from tag
+  `openlup-core-v0.16.0`.
+
+- Add optional logical module selection, dependency/entry contracts, module-qualified bindings and module diagnostics to experimental `./readiness`. Each selected module retains an independent schema requirement within one artifact.
+
+Migration: additive API; existing manifests and loaded packages that omit module fields keep byte-identical readiness reports and binding keys. To opt an artifact in, observe `LoadedPackage.modules` and supply exactly one manifest `module` per selected id, with its logical kind, provided entries and in-artifact dependencies. Bind ports, triggers and routes as `package/module:id`; keep artifact kind/version and environment keys unchanged. Mixed modes, missing dependencies/entries and duplicate module/event/schedule/route ownership refuse using existing codes. Empty selections need no contributions; disabled modules need no bindings or schema probe. Inspect optional issue `module` when diagnosing module/schema failures. No release, publication or activation is performed by this change.
+
 ## [0.15.0]
 
 - Publishable on the npm `latest` dist-tag as `0.15.0`, from tag

package/CONTRIBUTING.md

@@ -17,7 +17,8 @@ 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. Root Vitest excludes this suite; CI's required test job runs it separately.
+publish controls. Root Vitest excludes this suite; CI's required `install-proof` job runs it separately through the shared package gate,
+independently of the required root `test` job.
 
 ## Scope
 

package/README.md

@@ -27,8 +27,8 @@ complete host inventory, actual schedule/route function bindings and a bounded
 schema probe. It never migrates, leases or sends. Only `ready` admits a candidate;
 `unknown` and `unsatisfied` retain the serving candidate. The host owns immutable
 artifact/configuration/schema identity and admission at every work entrance.
-Exactly one contribution per non-kernel package is required today; multiple
-capabilities per distribution need a future separately reviewed adaptation.
+Legacy artifacts require one contribution per non-kernel package; selected logical
+modules use [module readiness](#module-readiness).
 
 For PostgreSQL catalog inspection, import `buildGroupedPostgresSchemaProbe`,
 `decodeGroupedPostgresSchemaRows` and `PostgresSchemaCatalogEntry` from
@@ -76,8 +76,8 @@ standalone readiness suite. Actual installed-tarball SQL and shape-order proof
 runs in the existing Outbox disposable PostgreSQL tier in the source repository.
 
 Contributor package verification keeps the existing code/docs class and file
-ceilings. The grouped catalog addition uses the measured, owner-approved
-aggregate budgets in `release-gates.json`; later growth still needs its own
+ceilings. Its aggregate budgets in `release-gates.json` follow the measured
+decision its `$budgetReason` records; later growth still needs its own
 measured budget decision. Passing a local pack does not authorize publication.
 
 ## Package Surface Maturity
@@ -196,9 +196,8 @@ 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
 arguments still scans the UI source directory and refuses any forbidden hit.
 Published Tree CI runs the repository ratchet in required `self-check` and its
-CLI refusal tests separately in required `test`; unrestricted root diagnostics
-do not replace either gate. The independent core CI step retains this package's
-complete verification when root diagnostics are red.
+CLI refusal tests in required root `test`. This package's independent proof
+belongs to `install-proof`; see [repository testing](https://github.com/openlup/openlup/blob/main/CONTRIBUTING.md#test-scope-and-diagnostics).
 
 Together these interfaces let the repository measure existing findings without
 making one package import another package's internals. They provide source
@@ -206,9 +205,27 @@ neutrality evidence, not package activation or consumer compatibility evidence.
 
 ## Kernel Documentation
 
-<!-- openlup-doc-impact {"unit":"core","digest":"sha256-8e51804713ed34cae5286093c8036e24b5cf502a4e20bec243ce3a1481382b02","reason":"The manifest and own lockfile move from 0.14.0 to 0.15.0 for the set that first publishes @openlup/platform. API, runtime, dependency resolutions and package gates are unchanged in this preparation delta."} -->
-
 - [`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.
+
+### Module readiness
+
+Selected `./readiness` modules retain independent schema requirements.
+Dependencies use the same or an earlier layer:
+`kernel`, `rail`, `capability`, `implementation`.
+See [CHANGELOG migration guidance](CHANGELOG.md#0160) for selection,
+bindings, refusals and diagnostics, and the source checkout's
+`api/readiness.api.md` snapshot for declarations; the host owns inventory.
+
+## Package artifact limits
+
+The monorepo's package artifact checker enforces this package's
+`release-gates.json` caps and packed content allowlist. Only
+`--release-set <version>` checks compressed growth against the last released
+baseline, with explanations in the new set's changelog section and release body. See the
+[package artifact policy](https://github.com/openlup/openlup/blob/main/.github/VERSIONING_AND_EOL.md#package-artifact-limits)
+for measured sizes, current caps, the S1 baseline refresh and refusal remedies.
+Artifact checks require a clean package directory; `--manifest-only` supplies no
+artifact evidence.

package/dist/readiness/contracts.d.ts

@@ -11,6 +11,7 @@ export interface ReadinessIssue {
     subject: string;
     fix: string;
     observation?: string;
+    module?: string;
 }
 /** @beta */
 export interface SchemaObject {
@@ -38,6 +39,16 @@ export interface PackageManifest {
     routes: readonly string[];
     requiredPorts: readonly string[];
     env: readonly string[];
+    /** Selected logical module within this artifact; kind above remains the artifact kind. */
+    module?: {
+        id: string;
+        kind: PackageManifest["kind"];
+        provides: readonly string[];
+        dependsOn: readonly {
+            module: string;
+            entries: readonly string[];
+        }[];
+    };
     requiredSchema?: RequiredSchema;
 }
 /** @beta Run-bound handlers are represented by their shared inert descriptors. */
@@ -59,6 +70,7 @@ export interface LoadedPackage {
     name: string;
     version: string;
     kind: PackageManifest["kind"];
+    modules?: readonly string[];
 }
 /** @beta Candidate identity must change when configuration, schema or artifact changes. */
 export interface CandidateIdentity {

package/dist/readiness/declarations.d.ts

@@ -27,6 +27,20 @@ export declare const manifestShape: z.ZodObject<{
     routes: z.ZodArray<z.ZodString>;
     requiredPorts: z.ZodArray<z.ZodString>;
     env: z.ZodArray<z.ZodString>;
+    module: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            kernel: "kernel";
+            rail: "rail";
+            capability: "capability";
+            implementation: "implementation";
+        }>;
+        provides: z.ZodArray<z.ZodString>;
+        dependsOn: z.ZodArray<z.ZodObject<{
+            module: z.ZodString;
+            entries: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
     requiredSchema: z.ZodOptional<z.ZodObject<{
         version: z.ZodString;
         migration: z.ZodString;

package/dist/readiness/declarations.js

@@ -2,12 +2,18 @@ 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 moduleId = z.string().max(240).regex(/^[a-z0-9][a-z0-9-]*$/);
+const modules = z.array(moduleId).refine((items) => new Set(items).size === items.length);
+const entries = z.array(z.string().max(240).regex(/^(?:\.|\.(?:\/[a-zA-Z0-9_-]+)+)$/)).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,
+    module: z.object({ id: moduleId, kind, provides: entries,
+        dependsOn: z.array(z.object({ module: moduleId, entries }).strict()).refine((items) => new Set(items.map((item) => item.module)).size === items.length),
+    }).strict().optional(),
     requiredSchema: z.object({ version: name, migration: name, objects: z.array(schemaObjectShape) }).strict().optional(),
 }).strict();
 /** Validate declarations without invoking a handler, schedule, route or probe. */
@@ -27,13 +33,14 @@ export function declarationIssues(input) {
         return issues;
     }
     for (const pkg of input.loadedPackages)
-        if (!z.object({ name, version, kind }).strict().safeParse(pkg).success)
+        if (!z.object({ name, version, kind, modules: modules.optional() }).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;
         }
+        const start = issues.length;
         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"))
@@ -43,6 +50,9 @@ export function declarationIssues(input) {
         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 (c.manifest.module)
+            for (const diagnostic of issues.slice(start))
+                diagnostic.module = c.manifest.module.id;
     }
     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");

package/dist/readiness/index.js

@@ -6,9 +6,10 @@ export { schemaObjectKey, buildSchemaObjectProbe, createSchemaProbe, buildGroupe
 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 add = (code, pkg, subject, fix, observation, module) => {
+        issues.push({ code, package: pkg, subject, fix, ...(observation ? { observation } : {}), ...(module ? { module } : {}) });
     };
+    const addIssue = add;
     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))
@@ -28,9 +29,27 @@ export async function checkReadiness(input) {
     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)
+        if (p.modules !== undefined) {
+            for (const id of (Array.isArray(p.modules) ? p.modules : [])) {
+                if (contributions.filter((c) => c.manifest.name === p.name && c.manifest.module?.id === id).length !== 1)
+                    add("OPENLUP_E_SET_MISMATCH", p.name, "contribution", "Compose exactly one contribution for each selected module.", undefined, id);
+            }
+        }
+        else 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.");
     }
+    // Selection is observed per artifact. Refused mixed/unselected contributions
+    // do not introduce adapter, environment or schema obligations.
+    const selected = contributions.filter((c) => {
+        const m = c.manifest, p = loaded.find((p) => p.name === m.name);
+        if (m.module ? !Array.isArray(p?.modules) || !p.modules.includes(m.module.id) : p?.modules !== undefined) {
+            add("OPENLUP_E_SET_MISMATCH", m.name, "module-selection", "Match module contributions to the observed artifact selection.", undefined, m.module?.id);
+            return false;
+        }
+        return true;
+    });
+    const layers = { kernel: 0, rail: 1, capability: 2, implementation: 3 };
+    const bindings = new Map();
     const handlers = new Map();
     const emitters = new Map();
     const events = new Set();
@@ -41,46 +60,87 @@ export async function checkReadiness(input) {
             events.add(v.eventType);
         }
     }
-    for (const c of contributions) {
+    for (const c of selected) {
         const m = c.manifest;
+        const add = (code, pkg, subject, fix, observation) => addIssue(code, pkg, subject, fix, observation, m.module?.id);
+        const owner = m.module ? `${m.name}/${m.module.id}` : m.name;
+        if (m.module) {
+            for (const dependency of m.module.dependsOn) {
+                const target = selected.find((other) => other.manifest.name === m.name && other.manifest.module?.id === dependency.module)?.manifest.module;
+                if (!target)
+                    add("OPENLUP_E_SET_MISMATCH", m.name, `dependency:${dependency.module}`, "Select and compose the required module in the same artifact.");
+                else {
+                    if (layers[target.kind] > layers[m.module.kind])
+                        add("OPENLUP_E_SET_MISMATCH", m.name, `dependency:${dependency.module}`, "Depend only on modules in the same or an earlier layer.");
+                    for (const entry of dependency.entries)
+                        if (!target.provides.includes(entry))
+                            add("OPENLUP_E_SET_MISMATCH", m.name, `dependency:${dependency.module}:${entry}`, "Use an entry declared by the dependency's provides contract.");
+                }
+            }
+            for (const [type, ids] of [["schedule", m.schedules.map((s) => s.id)], ["route", m.routes]])
+                for (const id of ids) {
+                    const key = `${m.name}:${type}:${id}`, previous = bindings.get(key);
+                    if (previous !== undefined)
+                        add("OPENLUP_E_SET_MISMATCH", m.name, `${type}:${id}`, "Declare one module owner for each artifact schedule or route.", previous);
+                    else
+                        bindings.set(key, m.module.id);
+                }
+        }
         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]);
+                emitters.set(type, [...(emitters.get(type) ?? []), owner]);
         }
         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]);
+                handlers.set(type, [...(handlers.get(type) ?? []), owner]);
             events.add(type);
         }
         for (const port of m.requiredPorts)
-            if (!isPort(input.bindings?.ports?.[`${m.name}:${port}`]))
+            if (!isPort(input.bindings?.ports?.[`${owner}:${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)
+            if (declarations.length !== 1 || actual.length !== 1 || declarations[0]?.cadenceSeconds !== actual[0]?.cadenceSeconds || typeof actual[0]?.run !== "function" || input.bindings?.triggers?.[`${owner}:${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)
+            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?.[`${owner}:${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.");
+        if (owners.length > 1) {
+            const fix = "Use one non-kernel producer owner and one composed consumer per event.";
+            if (owners.some((owner) => selected.some((c) => c.manifest.module && `${c.manifest.name}/${c.manifest.module.id}` === owner))) {
+                for (const owner of new Set(owners)) {
+                    const m = selected.find((c) => c.manifest.module && `${c.manifest.name}/${c.manifest.module.id}` === owner)?.manifest;
+                    add("OPENLUP_E_EVENT_DUPLICATE", m?.name ?? owner, type, fix, [...owners].sort().join(","), m?.module?.id);
+                }
+            }
+            else
+                add("OPENLUP_E_EVENT_DUPLICATE", owners.sort().join(","), type, fix);
+        }
     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) {
+        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))) {
+            const owners = selected.filter((c) => c.manifest.module && c.manifest.emits.includes(type));
+            const fix = "Register a handler or an explicit owned ignored/dormant declaration.";
+            if (owners.length)
+                for (const c of owners)
+                    add("OPENLUP_E_EVENT_UNHANDLED", c.manifest.name, type, fix, undefined, c.manifest.module?.id);
+            else
+                add("OPENLUP_E_EVENT_UNHANDLED", "@openlup/core", type, fix);
+        }
+    for (const c of selected) {
+        const add = (code, pkg, subject, fix, observation) => addIssue(code, pkg, subject, fix, observation, c.manifest.module?.id);
         const req = c.manifest.requiredSchema;
         if (!req)
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlup/core",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Neutral D2C subscription and bundle commerce kernels; a development preview with no stable API.",
   "license": "Apache-2.0",
   "repository": {

package/release-gates.json

@@ -262,18 +262,17 @@
     }
   },
   "pack": {
-    "$budgetReason": "2026-10-12 owner-approved bounded decision: additive grouped PostgreSQL catalog probes preserve the native jsonb text contract. Public base380edbd measures154118 packed/652616 unpacked bytes; corrected contribution measures158572/666908. Aggregate155KiB packed/652KiB unpacked is the smallest KiB-aligned headroom that fits the measured contribution; code/docs class ceilings, all file ceilings, required artifacts and other controls remain unchanged. Re-measure the exact approved candidate before DCO/delivery; this proposal grants no release authority. Later growth still requires a measured budget decision.",
     "code": {
-      "maxPackedBytes": 131072,
-      "maxFiles": 198
+      "maxPackedBytes": 276480,
+      "maxFiles": 400
     },
     "docs": {
-      "maxPackedBytes": 24576,
-      "maxFiles": 12
+      "maxPackedBytes": 49152,
+      "maxFiles": 20
     },
-    "maxPackedBytes": 158720,
-    "maxUnpackedBytes": 667648,
-    "maxFiles": 211,
+    "maxPackedBytes": 327680,
+    "maxUnpackedBytes": 1392640,
+    "maxFiles": 420,
     "requiredFiles": [
       "AGENTS.md",
       "CHANGELOG.md",
@@ -285,7 +284,12 @@
       "SECURITY.md",
       "package.json",
       "release-gates.json"
-    ]
+    ],
+    "baseline": {
+      "version": "0.16.0",
+      "packedBytes": 161371
+    },
+    "browserEntries": {}
   },
   "publish": {
     "prepublishOnly": "node --experimental-strip-types ./scripts/refuse-publish.ts",

package/src/readiness/contracts.ts

@@ -5,7 +5,7 @@ export const READINESS_CODES = ["OPENLUP_E_PORT_MISSING", "OPENLUP_E_EVENT_UNHAN
 /** @beta */
 export type ReadinessCode = typeof READINESS_CODES[number];
 /** @beta */
-export interface ReadinessIssue { code: ReadinessCode; package: string; subject: string; fix: string; observation?: string }
+export interface ReadinessIssue { code: ReadinessCode; package: string; subject: string; fix: string; observation?: string; module?: 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. */
@@ -16,6 +16,11 @@ export interface PackageManifest {
   emits: readonly string[]; handles: readonly string[];
   schedules: readonly { id: string; cadenceSeconds: number }[];
   routes: readonly string[]; requiredPorts: readonly string[]; env: readonly string[];
+  /** Selected logical module within this artifact; kind above remains the artifact kind. */
+  module?: {
+    id: string; kind: PackageManifest["kind"]; provides: readonly string[];
+    dependsOn: readonly { module: string; entries: readonly string[] }[];
+  };
   requiredSchema?: RequiredSchema;
 }
 /** @beta Run-bound handlers are represented by their shared inert descriptors. */
@@ -26,7 +31,7 @@ export interface Contribution {
   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"] }
+export interface LoadedPackage { name: string; version: string; kind: PackageManifest["kind"]; modules?: readonly string[] }
 /** @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 */

package/src/readiness/declarations.ts

@@ -3,6 +3,9 @@ import type { ReadinessInput, ReadinessIssue, Contribution } from "./contracts.j
 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 moduleId = z.string().max(240).regex(/^[a-z0-9][a-z0-9-]*$/);
+const modules = z.array(moduleId).refine((items) => new Set(items).size === items.length);
+const entries = z.array(z.string().max(240).regex(/^(?:\.|\.(?:\/[a-zA-Z0-9_-]+)+)$/)).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) =>
@@ -10,6 +13,9 @@ export const schemaObjectShape = z.object({ kind: z.enum(["table", "column", "fu
 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,
+  module: z.object({ id: moduleId, kind, provides: entries,
+    dependsOn: z.array(z.object({ module: moduleId, entries }).strict()).refine((items) => new Set(items.map((item) => item.module)).size === items.length),
+  }).strict().optional(),
   requiredSchema: z.object({ version: name, migration: name, objects: z.array(schemaObjectShape) }).strict().optional(),
 }).strict();
 /** Validate declarations without invoking a handler, schedule, route or probe. */
@@ -20,14 +26,16 @@ export function declarationIssues(input: ReadinessInput): ReadinessIssue[] {
   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 pkg of input.loadedPackages) if (!z.object({ name, version, kind, modules: modules.optional() }).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; }
+    const start = issues.length;
     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 (c.manifest.module) for (const diagnostic of issues.slice(start)) diagnostic.module = c.manifest.module.id;
   }
   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");

package/src/readiness/index.ts

@@ -7,9 +7,10 @@ export { schemaObjectKey, buildSchemaObjectProbe, createSchemaProbe, buildGroupe
 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 add = (code: ReadinessIssue["code"], pkg: string, subject: string, fix: string, observation?: string, module?: string) => {
+    issues.push({ code, package: pkg, subject, fix, ...(observation ? { observation } : {}), ...(module ? { module } : {}) });
   };
+  const addIssue = add;
   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();
@@ -23,8 +24,24 @@ export async function checkReadiness(input: ReadinessInput): Promise<ReadinessRe
   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.");
+    if (p.modules !== undefined) {
+      for (const id of (Array.isArray(p.modules) ? p.modules : [])) {
+        if (contributions.filter((c) => c.manifest.name === p.name && c.manifest.module?.id === id).length !== 1) add("OPENLUP_E_SET_MISMATCH", p.name, "contribution", "Compose exactly one contribution for each selected module.", undefined, id);
+      }
+    } else 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.");
   }
+  // Selection is observed per artifact. Refused mixed/unselected contributions
+  // do not introduce adapter, environment or schema obligations.
+  const selected = contributions.filter((c) => {
+    const m = c.manifest, p = loaded.find((p) => p.name === m.name);
+    if (m.module ? !Array.isArray(p?.modules) || !p.modules.includes(m.module.id) : p?.modules !== undefined) {
+      add("OPENLUP_E_SET_MISMATCH", m.name, "module-selection", "Match module contributions to the observed artifact selection.", undefined, m.module?.id);
+      return false;
+    }
+    return true;
+  });
+  const layers = { kernel: 0, rail: 1, capability: 2, implementation: 3 };
+  const bindings = new Map<string, string>();
   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 : [])) {
@@ -33,31 +50,62 @@ export async function checkReadiness(input: ReadinessInput): Promise<ReadinessRe
       events.add(v.eventType);
     }
   }
-  for (const c of contributions) {
+  for (const c of selected) {
     const m = c.manifest;
+    const add: typeof addIssue = (code, pkg, subject, fix, observation) => addIssue(code, pkg, subject, fix, observation, m.module?.id);
+    const owner = m.module ? `${m.name}/${m.module.id}` : m.name;
+    if (m.module) {
+      for (const dependency of m.module.dependsOn) {
+        const target = selected.find((other) => other.manifest.name === m.name && other.manifest.module?.id === dependency.module)?.manifest.module;
+        if (!target) add("OPENLUP_E_SET_MISMATCH", m.name, `dependency:${dependency.module}`, "Select and compose the required module in the same artifact.");
+        else {
+          if (layers[target.kind] > layers[m.module.kind]) add("OPENLUP_E_SET_MISMATCH", m.name, `dependency:${dependency.module}`, "Depend only on modules in the same or an earlier layer.");
+          for (const entry of dependency.entries) if (!target.provides.includes(entry)) add("OPENLUP_E_SET_MISMATCH", m.name, `dependency:${dependency.module}:${entry}`, "Use an entry declared by the dependency's provides contract.");
+        }
+      }
+      for (const [type, ids] of [["schedule", m.schedules.map((s) => s.id)], ["route", m.routes]] as const) for (const id of ids) {
+        const key = `${m.name}:${type}:${id}`, previous = bindings.get(key);
+        if (previous !== undefined) add("OPENLUP_E_SET_MISMATCH", m.name, `${type}:${id}`, "Declare one module owner for each artifact schedule or route.", previous);
+        else bindings.set(key, m.module.id);
+      }
+    }
     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]);
+      if (m.kind !== "kernel") emitters.set(type, [...(emitters.get(type) ?? []), owner]);
     }
     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]);
+      else handlers.set(type, [...(handlers.get(type) ?? []), owner]);
       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 port of m.requiredPorts) if (!isPort(input.bindings?.ports?.[`${owner}:${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.");
+      if (declarations.length !== 1 || actual.length !== 1 || declarations[0]?.cadenceSeconds !== actual[0]?.cadenceSeconds || typeof actual[0]?.run !== "function" || input.bindings?.triggers?.[`${owner}:${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 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?.[`${owner}:${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) {
+    const fix = "Use one non-kernel producer owner and one composed consumer per event.";
+    if (owners.some((owner) => selected.some((c) => c.manifest.module && `${c.manifest.name}/${c.manifest.module.id}` === owner))) {
+      for (const owner of new Set(owners)) {
+        const m = selected.find((c) => c.manifest.module && `${c.manifest.name}/${c.manifest.module.id}` === owner)?.manifest;
+        add("OPENLUP_E_EVENT_DUPLICATE", m?.name ?? owner, type, fix, [...owners].sort().join(","), m?.module?.id);
+      }
+    } else add("OPENLUP_E_EVENT_DUPLICATE", owners.sort().join(","), type, fix);
+  }
+  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))) {
+    const owners = selected.filter((c) => c.manifest.module && c.manifest.emits.includes(type));
+    const fix = "Register a handler or an explicit owned ignored/dormant declaration.";
+    if (owners.length) for (const c of owners) add("OPENLUP_E_EVENT_UNHANDLED", c.manifest.name, type, fix, undefined, c.manifest.module?.id);
+    else add("OPENLUP_E_EVENT_UNHANDLED", "@openlup/core", type, fix);
   }
-  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) {
+  for (const c of selected) {
+    const add: typeof addIssue = (code, pkg, subject, fix, observation) => addIssue(code, pkg, subject, fix, observation, c.manifest.module?.id);
     const req = c.manifest.requiredSchema;
     if (!req) continue;
     if (issues.some((i) => ["schemaProbe", "probeTimeoutMs"].includes(i.subject))) { unknown = true; continue; }