@openlup/core 0.14.0 → 0.16.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,22 @@ SemVer promise.
 
 ## [Unreleased]
 
+## [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
+  `openlup-core-v0.15.0`.
+
+- Republished unchanged.
+
 ## [0.14.0]
 
 - Publishable on the npm `latest` dist-tag as `0.14.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

@@ -21,7 +21,14 @@ package together.
   each change is recorded in [the changelog](CHANGELOG.md). Pin an exact
   version and read the changelog when you upgrade.
 
-The experimental `./outbox`, `./standard-schema` and `./readiness` subpaths provide shared infrastructure contracts. `checkReadiness` evaluates inert contribution descriptors, the complete host-observed package set, actual host bindings (schedule/route function identity must match the contribution) and a bounded schema probe. It never migrates, leases or sends. Only `ready` admits a new candidate; `unknown` and `unsatisfied` leave the serving candidate in place. The host owns inventory completeness, immutable artifact/configuration/schema identity and admission at every work entrance. Catalog existence does not prove SQL bodies, permissions or provider recovery.
+The experimental `./outbox`, `./standard-schema` and `./readiness` subpaths
+provide infrastructure contracts. `checkReadiness` checks inert contributions,
+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.
+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
@@ -69,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
@@ -199,9 +206,16 @@ neutrality evidence, not package activation or consumer compatibility evidence.
 
 ## Kernel Documentation
 
-<!-- openlup-doc-impact {"unit":"core","digest":"sha256-09e3df57d5021bc7edebe553c8811ffd94436bf3e0c70d981b9cedbd36782e3a","reason":"The manifest and own lockfile move from 0.13.1 to 0.14.0 for the coherent MINOR set. API, runtime, dependency resolutions and package gates are unchanged in this preparation delta; the grouped schema helpers are already documented here."} -->
-
 - [`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/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.14.0",
+  "version": "0.16.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,17 +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.",
+    "$budgetReason": "2026-10-18 M03 bounded decision: base code 129991 packed, aggregate 158715 packed/667249 unpacked bytes; B0 before trimming 132250, 162482/681852; final 132250, 161344/678531. B0 is core's only growth for programme module M03; identity ships in @openlup/platform. Code 132KiB, aggregates 162KiB/672KiB; docs class, file ceilings, required files and other controls unchanged. Set bumps grow only the changelog; docs stays the first binding limit for set notes. Later growth still requires a measured budget decision. Grants no release authority.",
     "code": {
-      "maxPackedBytes": 131072,
+      "maxPackedBytes": 135168,
       "maxFiles": 198
     },
     "docs": {
       "maxPackedBytes": 24576,
       "maxFiles": 12
     },
-    "maxPackedBytes": 158720,
-    "maxUnpackedBytes": 667648,
+    "maxPackedBytes": 165888,
+    "maxUnpackedBytes": 688128,
     "maxFiles": 211,
     "requiredFiles": [
       "AGENTS.md",

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; }