@endora-commerce/cli 0.100.0

package/dist/lib/read-size.d.ts

@@ -0,0 +1,154 @@
+/**
+ * "What did this check actually read?" — the one line every check prints
+ * (issue #244).
+ *
+ * ## The defect family
+ *
+ * Seven times now a check has reported `violations=0` because it was not
+ * looking, not because the tree was clean:
+ *
+ *   * **#215** — the walk came back *short*. `files.length === 0` is the wrong
+ *     floor when 1364 of 1469 files live under `src/modules`: move that tree
+ *     out and eight checks read the other 105 files, find nothing, and report
+ *     clean.
+ *   * **#228** — the *population definition* excluded a live entry point, so
+ *     `unscoped=0` said nothing about `src/seeds/dev-catalog-seed.ts`.
+ *   * **#235 / #237** — a file in the population hid a *site* inside it: the
+ *     answer was per file while the rule is per call.
+ *   * **#238** — a spread bypassed excess-property checking, so the off-state
+ *     test stopped testing anything while `tsc` stayed green.
+ *   * **#241** — an input transform ate 41% of the file before matching.
+ *   * **#244** — the population is defined by the presence of the thing being
+ *     checked, so its *absence* is undetectable.
+ *
+ * They are one defect. **A check's output says what it found and never says
+ * what it read**, so "found nothing" and "read nothing" print the same green.
+ * Every repair so far has been per check and after the fact; this is the
+ * general answer, and it is deliberately not a new rule about correctness. It
+ * is a rule about *disclosure*: the size of the input is printed beside the
+ * count of findings, on every run, in one grammar, so that a reader — or the
+ * ratchet in `test/unit/scripts/check-read-size.test.ts` — can tell a clean
+ * tree from a check that stopped reading it.
+ *
+ * ## The grammar
+ *
+ * ```
+ * [entry-scope] read: files=1459 sites=47 sources=manifest-index:65/65,package-scripts:18/18
+ * [nul-bytes]   read: files=5163 sources=self-reported
+ * ```
+ *
+ *   * **`files`** — how many files the check *opened*. Not how many it had a
+ *     finding in, and not how many survived a filter it applied afterwards.
+ *     That distinction is the whole point and it is easy to get backwards:
+ *     `check-entry-scope` already printed `files=38`, which is the number of
+ *     files that hold an entry site, out of the 1459 it reads. A number that
+ *     moves with the findings cannot answer "did you read the tree".
+ *   * **`sites`** — the finer population, where the check has one: the calls,
+ *     nodes, entries, documents or records it examined *inside* those files.
+ *     Issues #235 and #237 are exactly the case where the file count is
+ *     unchanged and the examined-site count is what moved, so a check that
+ *     answers per site must print both. Omitted where the file is the unit.
+ *   * **`sources`** — how the two numbers above are corroborated. A check that
+ *     computes its own population and then reports it has not closed #215:
+ *     that is the same value twice. Where an *independent* derivation exists —
+ *     the generated manifest index for a module walk, `package.json` scripts
+ *     for a declared program — the reconciliation is printed as
+ *     `<source>:<covered>/<expected>` and a shortfall is refused. Where there
+ *     genuinely is none, the token is the literal `self-reported`: the honest
+ *     word, so that a reader can see which checks still rest on their own
+ *     answer, and so the inventory can require a reason for each.
+ *
+ * ## What it refuses
+ *
+ * Three shapes, all exit 2 — "nothing was read" is neither a pass (0) nor a
+ * violation (1):
+ *
+ *   1. `read-nothing` — `files=0`. The pre-existing floor, kept uniform.
+ *   2. `short-walk` — a declared source expected more than the walk covered.
+ *      This is #215's predicate, generalised past the module tree: any check
+ *      that can name an independent expectation gets the short case, not only
+ *      the empty one.
+ *   3. `no-expectation` — a declared source whose expectation is zero. An
+ *      independent derivation that derived nothing silently turns the floor off
+ *      while looking like a normal run, which is the same green this file
+ *      exists to break.
+ *
+ * The verdict is a pure function over the record so a red proof enters where a
+ * real run enters (issue #130); {@link reportReadSize} is the thin CLI half
+ * that prints it and exits.
+ */
+/** One independent derivation of what the check should have read. */
+export interface ReadCoverage {
+    /**
+     * Where the expectation came from — printed, so the reader can check it
+     * themselves. `manifest-index` and `package-scripts` are the two the tree
+     * has; the token is free text so a check with a third can name it.
+     */
+    readonly source: string;
+    /** How many units that source says exist. */
+    readonly expected: number;
+    /** How many of them the walk actually reached. */
+    readonly covered: number;
+}
+export interface ReadSizeInput {
+    /** The check's log prefix, e.g. `[entry-scope]` — brackets included. */
+    readonly prefix: string;
+    /** Files opened. Never files with a finding, never files after a filter. */
+    readonly files: number;
+    /** The finer population examined inside them, where the check has one. */
+    readonly sites?: number;
+    /**
+     * Independent corroboration, if any. An empty list prints `self-reported`,
+     * which is a statement rather than an omission: the inventory requires a
+     * reason for every check that prints it.
+     */
+    readonly coverage?: readonly ReadCoverage[];
+}
+export type ReadSizeRefusalKind = 'read-nothing' | 'short-walk' | 'no-expectation';
+export interface ReadSizeRefusal {
+    readonly kind: ReadSizeRefusalKind;
+    readonly message: string;
+}
+/** The literal printed where no independent derivation exists. */
+export declare const SELF_REPORTED = "self-reported";
+/** The `sources=` token: every derivation, or the honest word for none. */
+export declare function coverageToken(coverage?: readonly ReadCoverage[]): string;
+/**
+ * The line itself. One grammar for every check, so the ratchet parses one
+ * shape and a reader learns one.
+ */
+export declare function readSizeLine(input: ReadSizeInput): string;
+/**
+ * Why this run may not report on what it read, or `null`.
+ *
+ * Pure, and over the record the check hands in — the top of this helper's
+ * analysis. A proof that constructed the message instead would prove the
+ * string formatting and leave all three predicates unproven.
+ */
+export declare function readSizeRefusal(input: ReadSizeInput): ReadSizeRefusal | null;
+/**
+ * The CLI half: print the read size, or refuse and exit 2.
+ *
+ * One function rather than a copy per check, because a copy per check is a
+ * chance per check to write the one that prints a number nothing compares —
+ * which is the state this repository was in when the family reached seven.
+ */
+export declare function reportReadSize(input: ReadSizeInput): void;
+export interface ParsedReadSize {
+    readonly prefix: string;
+    readonly files: number;
+    /** `null` when the check declares no finer population. */
+    readonly sites: number | null;
+    readonly coverage: readonly ReadCoverage[];
+    /** True when the `sources=` token is the literal `self-reported`. */
+    readonly selfReported: boolean;
+}
+/**
+ * The line back out of a check's output, for the ratchet that spawns it.
+ *
+ * Returns `null` when the output holds no read line — which the ratchet reads
+ * as "this check does not disclose its read size", a failure rather than a
+ * skip.
+ */
+export declare function parseReadSize(output: string): ParsedReadSize | null;
+//# sourceMappingURL=read-size.d.ts.map

package/dist/lib/read-size.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-size.d.ts","sourceRoot":"","sources":["../../src/lib/read-size.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AAGH,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC7C;AAED,MAAM,MAAM,mBAAmB,GAAG,cAAc,GAAG,YAAY,GAAG,gBAAgB,CAAC;AAEnF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,kEAAkE;AAClE,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAE7C,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,QAAQ,GAAE,SAAS,YAAY,EAAO,GAAG,MAAM,CAG5E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAGzD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,eAAe,GAAG,IAAI,CA8B5E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAOzD;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAKD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAyBnE"}

package/dist/lib/read-size.js

@@ -0,0 +1,182 @@
+/**
+ * "What did this check actually read?" — the one line every check prints
+ * (issue #244).
+ *
+ * ## The defect family
+ *
+ * Seven times now a check has reported `violations=0` because it was not
+ * looking, not because the tree was clean:
+ *
+ *   * **#215** — the walk came back *short*. `files.length === 0` is the wrong
+ *     floor when 1364 of 1469 files live under `src/modules`: move that tree
+ *     out and eight checks read the other 105 files, find nothing, and report
+ *     clean.
+ *   * **#228** — the *population definition* excluded a live entry point, so
+ *     `unscoped=0` said nothing about `src/seeds/dev-catalog-seed.ts`.
+ *   * **#235 / #237** — a file in the population hid a *site* inside it: the
+ *     answer was per file while the rule is per call.
+ *   * **#238** — a spread bypassed excess-property checking, so the off-state
+ *     test stopped testing anything while `tsc` stayed green.
+ *   * **#241** — an input transform ate 41% of the file before matching.
+ *   * **#244** — the population is defined by the presence of the thing being
+ *     checked, so its *absence* is undetectable.
+ *
+ * They are one defect. **A check's output says what it found and never says
+ * what it read**, so "found nothing" and "read nothing" print the same green.
+ * Every repair so far has been per check and after the fact; this is the
+ * general answer, and it is deliberately not a new rule about correctness. It
+ * is a rule about *disclosure*: the size of the input is printed beside the
+ * count of findings, on every run, in one grammar, so that a reader — or the
+ * ratchet in `test/unit/scripts/check-read-size.test.ts` — can tell a clean
+ * tree from a check that stopped reading it.
+ *
+ * ## The grammar
+ *
+ * ```
+ * [entry-scope] read: files=1459 sites=47 sources=manifest-index:65/65,package-scripts:18/18
+ * [nul-bytes]   read: files=5163 sources=self-reported
+ * ```
+ *
+ *   * **`files`** — how many files the check *opened*. Not how many it had a
+ *     finding in, and not how many survived a filter it applied afterwards.
+ *     That distinction is the whole point and it is easy to get backwards:
+ *     `check-entry-scope` already printed `files=38`, which is the number of
+ *     files that hold an entry site, out of the 1459 it reads. A number that
+ *     moves with the findings cannot answer "did you read the tree".
+ *   * **`sites`** — the finer population, where the check has one: the calls,
+ *     nodes, entries, documents or records it examined *inside* those files.
+ *     Issues #235 and #237 are exactly the case where the file count is
+ *     unchanged and the examined-site count is what moved, so a check that
+ *     answers per site must print both. Omitted where the file is the unit.
+ *   * **`sources`** — how the two numbers above are corroborated. A check that
+ *     computes its own population and then reports it has not closed #215:
+ *     that is the same value twice. Where an *independent* derivation exists —
+ *     the generated manifest index for a module walk, `package.json` scripts
+ *     for a declared program — the reconciliation is printed as
+ *     `<source>:<covered>/<expected>` and a shortfall is refused. Where there
+ *     genuinely is none, the token is the literal `self-reported`: the honest
+ *     word, so that a reader can see which checks still rest on their own
+ *     answer, and so the inventory can require a reason for each.
+ *
+ * ## What it refuses
+ *
+ * Three shapes, all exit 2 — "nothing was read" is neither a pass (0) nor a
+ * violation (1):
+ *
+ *   1. `read-nothing` — `files=0`. The pre-existing floor, kept uniform.
+ *   2. `short-walk` — a declared source expected more than the walk covered.
+ *      This is #215's predicate, generalised past the module tree: any check
+ *      that can name an independent expectation gets the short case, not only
+ *      the empty one.
+ *   3. `no-expectation` — a declared source whose expectation is zero. An
+ *      independent derivation that derived nothing silently turns the floor off
+ *      while looking like a normal run, which is the same green this file
+ *      exists to break.
+ *
+ * The verdict is a pure function over the record so a red proof enters where a
+ * real run enters (issue #130); {@link reportReadSize} is the thin CLI half
+ * that prints it and exits.
+ */
+/* eslint-disable no-console -- prints on behalf of the CLI checks: stdout is their interface. */
+/** The literal printed where no independent derivation exists. */
+export const SELF_REPORTED = 'self-reported';
+/** The `sources=` token: every derivation, or the honest word for none. */
+export function coverageToken(coverage = []) {
+    if (coverage.length === 0)
+        return SELF_REPORTED;
+    return coverage.map((c) => `${c.source}:${c.covered}/${c.expected}`).join(',');
+}
+/**
+ * The line itself. One grammar for every check, so the ratchet parses one
+ * shape and a reader learns one.
+ */
+export function readSizeLine(input) {
+    const sites = input.sites === undefined ? '' : ` sites=${input.sites}`;
+    return `${input.prefix} read: files=${input.files}${sites} sources=${coverageToken(input.coverage)}`;
+}
+/**
+ * Why this run may not report on what it read, or `null`.
+ *
+ * Pure, and over the record the check hands in — the top of this helper's
+ * analysis. A proof that constructed the message instead would prove the
+ * string formatting and leave all three predicates unproven.
+ */
+export function readSizeRefusal(input) {
+    if (input.files <= 0) {
+        return {
+            kind: 'read-nothing',
+            message: 'the walk opened no file at all — a finding count over an empty input is not a ' +
+                'clean tree; refusing to report a vacuous pass',
+        };
+    }
+    for (const coverage of input.coverage ?? []) {
+        if (coverage.expected <= 0) {
+            return {
+                kind: 'no-expectation',
+                message: `the independent derivation \`${coverage.source}\` expects nothing, so it ` +
+                    'corroborates nothing — the floor it exists to provide is switched off; ' +
+                    'refusing to report a vacuous pass',
+            };
+        }
+        if (coverage.covered < coverage.expected) {
+            return {
+                kind: 'short-walk',
+                message: `the walk opened ${input.files} file(s) and covered ${coverage.covered} of the ` +
+                    `${coverage.expected} unit(s) \`${coverage.source}\` derives — it is reading a ` +
+                    'residue of its population, not the population; refusing to report a vacuous pass',
+            };
+        }
+    }
+    return null;
+}
+/**
+ * The CLI half: print the read size, or refuse and exit 2.
+ *
+ * One function rather than a copy per check, because a copy per check is a
+ * chance per check to write the one that prints a number nothing compares —
+ * which is the state this repository was in when the family reached seven.
+ */
+export function reportReadSize(input) {
+    const refusal = readSizeRefusal(input);
+    if (refusal !== null) {
+        console.error(`${input.prefix} ${refusal.message}`);
+        process.exit(2);
+    }
+    console.log(readSizeLine(input));
+}
+const READ_LINE = /\[([^\]\n]+)\] read: files=(\d+)(?: sites=(\d+))? sources=(\S+)/;
+/**
+ * The line back out of a check's output, for the ratchet that spawns it.
+ *
+ * Returns `null` when the output holds no read line — which the ratchet reads
+ * as "this check does not disclose its read size", a failure rather than a
+ * skip.
+ */
+export function parseReadSize(output) {
+    const match = READ_LINE.exec(output);
+    if (match === null)
+        return null;
+    const token = match[4] ?? SELF_REPORTED;
+    const coverage = token === SELF_REPORTED
+        ? []
+        : token.split(',').flatMap((part) => {
+            const parsed = /^([^:]+):(\d+)\/(\d+)$/.exec(part);
+            if (parsed === null)
+                return [];
+            return [
+                {
+                    source: parsed[1],
+                    covered: Number(parsed[2]),
+                    expected: Number(parsed[3]),
+                },
+            ];
+        });
+    return {
+        prefix: match[1],
+        files: Number(match[2]),
+        sites: match[3] === undefined ? null : Number(match[3]),
+        coverage,
+        selfReported: token === SELF_REPORTED,
+    };
+}
+//# sourceMappingURL=read-size.js.map

package/dist/lib/read-size.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-size.js","sourceRoot":"","sources":["../../src/lib/read-size.ts"],"names":[],"mappings":"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"}

package/dist/lib/registration-owners.d.ts

@@ -0,0 +1,79 @@
+/**
+ * "Which module registered this container name?" — the port→owner map, as one
+ * merge rule rather than two.
+ *
+ * `check:port-dependencies` has built this map since feature 080's T034, from
+ * three sources with a precedence between them, and the divergence report
+ * (`specs/107-override-report-and-ladder/contracts/divergence-report.md` §3.2)
+ * needs the same answer: a decoration or a port resolution names a subject, and
+ * the entry has to say who owns it. §3.2's own words are *"it is not recomputed
+ * here"*, and this file is what makes that true — the two checks share the merge
+ * as well as the syntactic primitives (`registeredNames`, `moduleOf`,
+ * `loadPackageDeclarations`), so they cannot come to disagree about who owns a
+ * name.
+ *
+ * The precedence is the rule and it is stated once, here:
+ *
+ *  1. **the host table** seeds the map — `HOST_REGISTERED_PORTS`, the names a
+ *     composition root registers on an unconverted module's behalf;
+ *  2. **the tree** overwrites it, last claim winning, because a module that
+ *     registers a name is its owner whatever a bridging table says;
+ *  3. **an installed package** claims only a name nothing above claimed. The
+ *     tree wins a collision for the reason `check:module-boundary`'s table map
+ *     gives: two registrations of one name is a `DuplicateRegistrationError` the
+ *     container raises for itself, and until it does, a stranger must not take a
+ *     core module's name away from it in the diagnosis.
+ *
+ * ## Three sources, and an instance has one of them
+ *
+ * It moved here from `backend/scripts/lib/` with the derivation it feeds
+ * (`specs/110-instance-repository/` T138a), because the divergence report now has
+ * a second host and the two must not come to disagree about who owns a name. The
+ * precedence above is unchanged and is what the two hosts differ **in the inputs
+ * to**, never in: this repository fills all three, and a client's instance fills
+ * only the third — it has no module sources and no composition root of its own,
+ * every module being an installed package and `composeApp` the platform's. So an
+ * instance's report attributes a name the platform's composition root registers
+ * on a module's behalf to *a composition root* rather than to that module, which
+ * is true of the instance and is said out loud in its report's `boundary`
+ * (`divergence-artefacts.ts`' `INSTANCE_BOUNDARY_NOTES`) rather than left to be
+ * noticed.
+ */
+/** One claim on a container name. */
+export interface OwnerClaim {
+    readonly name: string;
+    readonly moduleId: string;
+}
+export interface RegistrationOwnerInput {
+    /** The host bridging table — name → the module a root registers it for. */
+    readonly hostRegistered: Readonly<Record<string, string>>;
+    /** Claims read from this repository's own module sources, in walk order. */
+    readonly treeClaims: Iterable<OwnerClaim>;
+    /** Claims read from installed extension packages' `./backend` artefacts. */
+    readonly packageClaims: Iterable<OwnerClaim>;
+}
+/** The port→owner map, under the precedence above. */
+export declare function mergeRegistrationOwners(input: RegistrationOwnerInput): Map<string, string>;
+/**
+ * The names **no module owns** — what a composition root supplies.
+ *
+ * They matter to the divergence report for one reason: an overlay module's
+ * decoration of `commandBus`, `auditLogService`, `eventBus` or `emFactory` is
+ * legal and total (D-156.4), and a report that could not tell "a root registers
+ * it" from "nobody registers it" would file every one of them as
+ * `unowned-subject` — a finding about the run dressed as one about the tree.
+ *
+ * Derived, never listed (D-100, D-156.5): a name the container holds that no
+ * module claimed is exactly a name a composition root supplied, which is the
+ * same derivation `ForeignRegistrationError` rests on. The caller supplies the
+ * sources so a fixture enters at the top of this analysis.
+ */
+export declare function rootSuppliedNames(input: {
+    /** Every name a composition root writes, from `rootRegisteredNames`. */
+    readonly rootNames: Iterable<string>;
+    /** Every name the platform's own kernel registers. */
+    readonly kernelNames: Iterable<string>;
+    /** The owner map — a name a module owns is not root-supplied. */
+    readonly owners: ReadonlyMap<string, string>;
+}): Set<string>;
+//# sourceMappingURL=registration-owners.d.ts.map

package/dist/lib/registration-owners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration-owners.d.ts","sourceRoot":"","sources":["../../src/lib/registration-owners.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,qCAAqC;AACrC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC1C,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;CAC9C;AAED,sDAAsD;AACtD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,sBAAsB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAO1F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrC,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACvC,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9C,GAAG,GAAG,CAAC,MAAM,CAAC,CAKd"}

package/dist/lib/registration-owners.js

@@ -0,0 +1,77 @@
+/**
+ * "Which module registered this container name?" — the port→owner map, as one
+ * merge rule rather than two.
+ *
+ * `check:port-dependencies` has built this map since feature 080's T034, from
+ * three sources with a precedence between them, and the divergence report
+ * (`specs/107-override-report-and-ladder/contracts/divergence-report.md` §3.2)
+ * needs the same answer: a decoration or a port resolution names a subject, and
+ * the entry has to say who owns it. §3.2's own words are *"it is not recomputed
+ * here"*, and this file is what makes that true — the two checks share the merge
+ * as well as the syntactic primitives (`registeredNames`, `moduleOf`,
+ * `loadPackageDeclarations`), so they cannot come to disagree about who owns a
+ * name.
+ *
+ * The precedence is the rule and it is stated once, here:
+ *
+ *  1. **the host table** seeds the map — `HOST_REGISTERED_PORTS`, the names a
+ *     composition root registers on an unconverted module's behalf;
+ *  2. **the tree** overwrites it, last claim winning, because a module that
+ *     registers a name is its owner whatever a bridging table says;
+ *  3. **an installed package** claims only a name nothing above claimed. The
+ *     tree wins a collision for the reason `check:module-boundary`'s table map
+ *     gives: two registrations of one name is a `DuplicateRegistrationError` the
+ *     container raises for itself, and until it does, a stranger must not take a
+ *     core module's name away from it in the diagnosis.
+ *
+ * ## Three sources, and an instance has one of them
+ *
+ * It moved here from `backend/scripts/lib/` with the derivation it feeds
+ * (`specs/110-instance-repository/` T138a), because the divergence report now has
+ * a second host and the two must not come to disagree about who owns a name. The
+ * precedence above is unchanged and is what the two hosts differ **in the inputs
+ * to**, never in: this repository fills all three, and a client's instance fills
+ * only the third — it has no module sources and no composition root of its own,
+ * every module being an installed package and `composeApp` the platform's. So an
+ * instance's report attributes a name the platform's composition root registers
+ * on a module's behalf to *a composition root* rather than to that module, which
+ * is true of the instance and is said out loud in its report's `boundary`
+ * (`divergence-artefacts.ts`' `INSTANCE_BOUNDARY_NOTES`) rather than left to be
+ * noticed.
+ */
+/** The port→owner map, under the precedence above. */
+export function mergeRegistrationOwners(input) {
+    const owners = new Map(Object.entries(input.hostRegistered));
+    for (const claim of input.treeClaims)
+        owners.set(claim.name, claim.moduleId);
+    for (const claim of input.packageClaims) {
+        if (!owners.has(claim.name))
+            owners.set(claim.name, claim.moduleId);
+    }
+    return owners;
+}
+/**
+ * The names **no module owns** — what a composition root supplies.
+ *
+ * They matter to the divergence report for one reason: an overlay module's
+ * decoration of `commandBus`, `auditLogService`, `eventBus` or `emFactory` is
+ * legal and total (D-156.4), and a report that could not tell "a root registers
+ * it" from "nobody registers it" would file every one of them as
+ * `unowned-subject` — a finding about the run dressed as one about the tree.
+ *
+ * Derived, never listed (D-100, D-156.5): a name the container holds that no
+ * module claimed is exactly a name a composition root supplied, which is the
+ * same derivation `ForeignRegistrationError` rests on. The caller supplies the
+ * sources so a fixture enters at the top of this analysis.
+ */
+export function rootSuppliedNames(input) {
+    const supplied = new Set();
+    for (const name of input.rootNames)
+        if (!input.owners.has(name))
+            supplied.add(name);
+    for (const name of input.kernelNames)
+        if (!input.owners.has(name))
+            supplied.add(name);
+    return supplied;
+}
+//# sourceMappingURL=registration-owners.js.map

package/dist/lib/registration-owners.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration-owners.js","sourceRoot":"","sources":["../../src/lib/registration-owners.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAiBH,sDAAsD;AACtD,MAAM,UAAU,uBAAuB,CAAC,KAA6B;IACnE,MAAM,MAAM,GAAG,IAAI,GAAG,CAAiB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;IAC7E,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,UAAU;QAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC7E,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAOjC;IACC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS;QAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpF,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,WAAW;QAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtF,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/lib/release-index.d.ts

@@ -0,0 +1,53 @@
+/** The file's name under the CLI's `dist`. */
+export declare const RELEASE_INDEX_FILE = "release-index.json";
+/** One publishable workspace package, with its directory and declared version. */
+export interface PublishablePackage {
+    readonly name: string;
+    readonly dir: string;
+    /** Absent when the manifest declares none; the index refuses such a package. */
+    readonly version: string | undefined;
+}
+/** One entry of the index. */
+export interface ReleaseIndexEntry {
+    readonly name: string;
+    readonly version: string;
+}
+/** The whole index: this CLI's release, sorted by name. */
+export interface ReleaseIndex {
+    readonly packages: readonly ReleaseIndexEntry[];
+}
+/**
+ * Every publishable workspace package under `packagesRoot`, with its directory.
+ *
+ * A directory holding a `package.json` is a package and is not descended
+ * into; one without is a grouping directory (`packages/modules/`) and is. A
+ * manifest declaring `private: true`, or no `name`, is not publishable.
+ */
+export declare function publishablePackages(packagesRoot: string): readonly PublishablePackage[];
+/**
+ * The index over `packagesRoot`, narrowed to `scope` (`@endora-commerce/`).
+ *
+ * A publishable package that declares no version is a throw rather than a
+ * skip: an index short by a package is a host short by a module, and the
+ * module set derived from it would be silently smaller than the release.
+ */
+export declare function releaseIndexOf(packagesRoot: string, scope: string): ReleaseIndex;
+/** Read an index back, refusing anything that is not one. `source` names the file. */
+export declare function parseReleaseIndex(text: string, source: string): ReleaseIndex;
+/**
+ * Where this CLI's own index is: `dist/` of the nearest package root above
+ * this module — the same file from `src/` in a checkout and from `dist/` in an
+ * installed tarball.
+ */
+export declare function ownReleaseIndexPath(moduleUrl?: string): string;
+/**
+ * The build step: derive the index for the CLI package at `cliDir` and write
+ * it into its `dist`.
+ *
+ * The workspace is found by walking up to `pnpm-workspace.yaml`, and the
+ * scope comes off the CLI's own name — nothing here is written down. Called by
+ * `scripts/write-release-index.mjs`, which the package's `build` runs after
+ * `tsc`; a failure fails the build rather than shipping a CLI with no index.
+ */
+export declare function writeReleaseIndex(cliDir: string): ReleaseIndex;
+//# sourceMappingURL=release-index.d.ts.map

package/dist/lib/release-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-index.d.ts","sourceRoot":"","sources":["../../src/lib/release-index.ts"],"names":[],"mappings":"AA+BA,8CAA8C;AAC9C,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD,kFAAkF;AAClF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED,8BAA8B;AAC9B,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACjD;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,kBAAkB,EAAE,CA2BvF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAchF;AAED,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,CA0B5E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,GAAE,MAAwB,GAAG,MAAM,CAQ/E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAsB9D"}