@endora-commerce/cli 0.100.0

package/dist/rules/platform-surface.js

@@ -0,0 +1,749 @@
+/**
+ * CI check — a module reaches the platform only through what the platform
+ * publishes (feature 080, T042d; ruling **D-160.8**).
+ *
+ * ## Why it exists
+ *
+ * `specs/080-f4-real-scope/contracts/host-package.md` §1 classifies all 53
+ * platform files a module reaches as **P** (published API), **A** (accidental
+ * reach — host-internal, harness-only or orchestrator-only) or **O** (the
+ * module is reaching for a class where a sanctioned port exists). Three
+ * delivered rows now build on that classification, and **nothing in the
+ * repository enforced it**: `check:module-boundary` is module→module,
+ * `check:kernel-boundary` is ORM relations, and the `exports` map D-160.7 rules
+ * enforces nothing at all for the modules still in `backend/src` — which is all
+ * of them. A classification with no ratchet rots at the speed of the tree, and
+ * this one is load-bearing for the package split.
+ *
+ * ## The population, and what it misses
+ *
+ * Every import specifier written in a module's own sources — core under the
+ * application's module roots, packaged under `packages/modules/<id>`, overlay
+ * under `src/apps` — that names the platform. Two spellings, and they are the
+ * same reach:
+ *
+ *   * a **relative** specifier that resolves to a file outside the module tree.
+ *     "Outside the module tree" is the whole predicate: the host is everything
+ *     that is not a module, so a reach into `src/seeds` or `src/composition.ts`
+ *     is judged by the same rule as one into `src/kernel`, with no directory
+ *     list to keep current.
+ *   * a **bare** specifier into the host package — `<host>/kernel` — which is
+ *     the only spelling a module outside the application tree has (feature 080,
+ *     T060). It resolves through the host's own `exports` map to the same
+ *     barrel, so `@endora-commerce/platform/http` and `../../http/index.js` are
+ *     one answer. Neither the package name nor the subpath list is written
+ *     here: both are read off the manifest of the member declaring
+ *     `endora.type: "platform"`, so the D-161 scope rename and a sixth
+ *     published directory arrive by being authored once.
+ *
+ * A declared subpath lands on a **barrel**, and reaching a barrel is reaching
+ * the published surface entire — so a bare reach is counted, attributed and
+ * cleared, and the symbol-level verdicts below are the relative spelling's. That
+ * is not a weaker rule for a packaged module: a name the barrel does not carry
+ * is a `tsc` error at the import, which is the same answer sooner. What the bare
+ * spelling *can* be wrong about is the **subpath**, and that is the finding it
+ * gets.
+ *
+ * Every specifier shape `scripts/lib/specifiers.ts` knows is read, `import type`
+ * and the one type-position `import('…')` included (§0b: a `from '…'`-only scan
+ * does not see it, and a module would move with an unrewritten specifier that
+ * `tsc` resolves and `node` never sees).
+ *
+ * **The second bullet is T060 and it is a repair, not a widening.** The
+ * population was relative specifiers alone, on the reasoning — written into
+ * this header — that "there is no host package yet, and when there is, its
+ * `exports` map refuses a deep path at resolution time and this check's
+ * population shrinks to nothing on its own". Both halves were wrong by the time
+ * the first module moved. The map refuses a *deep* path and licenses everything
+ * a widened map would license, which is precisely the reach D-160.8 exists to
+ * refuse; and a population that shrinks as the sweep proceeds is a check that
+ * reports green because it stopped looking. Measured: batch one took **104**
+ * reaches out of the walk and modules #1–#5 another 112, while the recorded
+ * read size absorbed one module's worth of the fall inside its own floor. That
+ * is why {@link hostDependentCoverage} exists beside the resolution — the
+ * repair without the floor is one edit away from happening again.
+ *
+ * **What that misses, stated rather than discovered later.** A specifier is not
+ * the only way to reach something, and `check:module-boundary` learned it the
+ * expensive way — it had to grow a SQL-table predicate for 121 reaches that name
+ * no specifier at all. The same three doors are open here and none of them is
+ * this check's:
+ *
+ *   * **A container name.** `lazyPort('settingsReadPort')` reaches the platform
+ *     through a string. That edge is `check:port-dependencies`' and
+ *     `check:port-shape`'s, which between them own the port surface;
+ *     `PLATFORM_OWNED_NAMES` is where a platform-owned name is declared.
+ *   * **A platform-owned table.** `settings`, `audit_logs`,
+ *     `module_registrations` and `sales_channels` are the host's, and SQL naming
+ *     one names no specifier. That door is `check:module-boundary`'s and it is
+ *     **open**: its owner map attributes those four to `kernel` off the
+ *     platform-relative path of the file declaring them, so a module's SQL
+ *     naming one is reported like any other cross-owner reach. `catalog`'s
+ *     `sales_channel_products` join is ledgered under that attribution today,
+ *     and `admin_actions`' `module_registrations` join was until feature 080
+ *     retired it. This paragraph read *"a module→platform table reach is
+ *     currently nobody's"* and was measured false while that second entry was
+ *     being drained — it was written before the platform relocation taught the
+ *     other check to attribute a `packages/platform/…` path to the kernel.
+ *     What is still not this check's is the **verdict**: a table has no barrel,
+ *     so there is no published-symbol question to ask about one.
+ *   * **A module package's own layout.** Where inside a package a subpath
+ *     leads is that package's `exports` map, and this check reads only the
+ *     *host's*. A module that reached another module by bare specifier is
+ *     `check:module-boundary`'s, which resolves module package names for
+ *     exactly that reason.
+ *
+ * ## The granularity: per symbol, of a named file
+ *
+ * A finding is a **(module file, platform file, symbol)** triple, and the
+ * verdict is "does that platform file's barrel publish that name". Not per file,
+ * and the difference is not academic — !883 measured it: sixteen symbols of
+ * **P** files are reached by nobody and are deliberately unpublished, so
+ * "the file is P" licenses `SettingsCache`, `decryptSecretValue` and the LRU
+ * tuning constants along with the symbols the classification actually names.
+ *
+ * **What per-*file* granularity would catch that this will not.** A per-file
+ * check would refuse every reach into an **A** or **O** file outright, symbol or
+ * no symbol — so it would flag `SettingNotRegistered` imported from
+ * `settings.service.ts` (row 8, **O**), `parseHostMap` from
+ * `sales-channel-resolver.service.ts` (row 24, **O**) and
+ * `MembershipMutationResult` from `sales-channel-membership.service.ts` (row 15,
+ * **O**). Eight such symbols stand today and §8 rules every one of them
+ * *published* on purpose — a `@throws` a caller cannot name is a method a caller
+ * cannot call. So the per-file verdict would be eight false findings, and its
+ * one genuine catch is a different question: *is this symbol rightly on the
+ * barrel at all?* That question belongs to
+ * `test/unit/kernel/published-surface.test.ts`, which holds each barrel to
+ * §1.3's own symbol column in both directions. The two are deliberately not
+ * duplicates: that test asks whether the barrel is right, this check asks
+ * whether the tree obeys it, and both read the barrel through
+ * `scripts/lib/platform-surface.ts` so they cannot disagree about what it says.
+ *
+ * **That gap is closed** (T042f). It read, until then: `!883` prunes and
+ * ratchets three of the five barrels, and `tenancy/index.ts` and
+ * `commands/index.ts` are published surface by D-160.7 with no expected set at
+ * all — so for two of this check's five subpaths its authority was a barrel
+ * nothing held to §1.3. Both are now pruned to their **P** columns (§1.3 rows
+ * 2, 5, 12, 21, 28, 30, 33) and ratcheted two-way, and
+ * `published-surface.test.ts` derives its own population from
+ * {@link PUBLISHED_SUBPATHS} rather than a list, so a sixth published directory
+ * cannot arrive unratcheted the way these two did.
+ *
+ * Worth recording, because a green that moves nothing is the outcome most
+ * likely to be misread: closing it moved **no** ledger key and no finding. The
+ * 37 names the two barrels shed are reached by no module, and every name a
+ * module reaches stayed published — so nothing had been hiding behind the
+ * unratcheted barrels. The value bought is prospective: a 38th name added to
+ * either now has to move an expected set.
+ *
+ * ## Five findings
+ *
+ *   * `unpublished-symbol` — the rule itself.
+ *   * `whole-file-reach` — `import * as`, a side-effect import, `export *`, a
+ *     `require()` or a dynamic `import()` with no named binding, at a file that
+ *     is not a barrel. The symbol set is not knowable from the specifier, so the
+ *     reach is the file's *whole* surface, internals included.
+ *   * `unresolvable-reach` — a relative specifier that names no file the walk
+ *     found. It is a finding and not a skip: !879 found #215 one layer in, where
+ *     a walk of the right length had its *result* discarded downstream and
+ *     reported clean behind a full-length `read:` line.
+ *   * `unattributed-source` — a file under a module walk root that no module
+ *     owns. Same reason: a file walked and not judged is worse than one not
+ *     walked, because the `read:` line counts it.
+ *   * `unpublished-subpath` — a bare specifier into the host package naming a
+ *     subpath its `exports` map does not declare, the host's root among them
+ *     (D-160.7 publishes no root export). Today `node` and `tsc` refuse it too,
+ *     which is not a reason to leave it unjudged: what makes it a *finding* is
+ *     that widening the map is the obvious repair, and the whole of D-160.8 is
+ *     that widening the map is the thing an author must not do quietly.
+ *   * `host-internal-subpath` — a bare specifier naming a subpath the `exports`
+ *     map **does** declare and no barrel carries (D-160.14, feature 109). It is
+ *     a third state and not a shade of the two above, and it is the only one of
+ *     the six that `node` and `tsc` both accept: `./composition` resolves, so
+ *     nothing but this check stands between a module and 27 composition symbols
+ *     — `composeModules`, `createRootContainer`, `registerOrm` — that no module
+ *     may name, production source or test. A module's server-bound test composes
+ *     through the test kit's `composeTestServer`.
+ *
+ *     It could not be a sixth {@link PUBLISHED_SUBPATHS} entry, measured:
+ *     {@link PlatformSurface.published} is keyed by target file with no subpath
+ *     dimension, so that entry would publish `composeModules` out of
+ *     `kernel/compose.ts` for a module's *relative* reach as well — and, this
+ *     check reporting `violations=0`, would change nothing it prints. The two
+ *     lists answering differently is the mechanism, not a drift to reconcile:
+ *     {@link HostPackage.declaredSubpaths} is the manifest's answer,
+ *     {@link PUBLISHED_SUBPATHS} is the ruling's.
+ *
+ * ## One key space, and it is the repository's
+ *
+ * Every path here — a module source, a platform file, a barrel, a ledger key —
+ * is written relative to the **repository root**. That is more verbose than the
+ * `modules/blog/x.ts` shape the other ledgers use, and it is not a style
+ * choice: this check *resolves* specifiers, and a specifier resolves in exactly
+ * one namespace. `layout.keyOf` deliberately has two bases — an application
+ * file is keyed inside `backend/src`, a packaged module's file relative to the
+ * checkout, because there is no application prefix that would be true of the
+ * second — and a resolver straddling both is wrong for every reach that crosses
+ * between them. Measured on the split-tree fixture, where six modules live in
+ * `packages/modules/<id>/src`: 90 reaches resolved to nothing, and the whole
+ * point of that fixture is that a check keeps working while the layout moves.
+ *
+ * Plus the **refusals**, each over an input whose silent absence would narrow
+ * the answer rather than fail it:
+ *
+ *   * a barrel this parse cannot read in full (an `export *`, a namespace
+ *     re-export, an `export { … }` with no `from`) is exit 2, never a narrower
+ *     published set. A short surface turns correct reaches into findings, and
+ *     the obvious "repair" for one of those is to widen the barrel;
+ *   * a workspace with no platform member, or a platform member publishing
+ *     under no name — every bare reach would then be judged by nothing;
+ *   * a module package whose `package.json` will not parse, which is what says
+ *     whether it reaches the host at all;
+ *   * and {@link hostDependentCoverage}'s shortfall: a module package that
+ *     declares the host and contributed no host reach to this walk. That is
+ *     issue #215's predicate over the population T060 restored, and it is the
+ *     one derivation that would have caught T060's own defect — `manifest-index`
+ *     counts modules that produced a *file*, which a packaged module does
+ *     plentifully, and `platform-barrels` counts barrels, which a module move
+ *     does not touch.
+ *
+ * ## The second consumer population (feature 115, D115-5)
+ *
+ * The rule above is *a reach into the host names a published subpath or a
+ * declared host-internal one, never a file inside the package by relative path*,
+ * and it was asked of **modules** only. The **application** writes the same
+ * reach — 84 of them, every one of which resolves in this checkout and in no
+ * instance built from published packages, which is the defect D-207 names — and
+ * was outside the population by construction: `moduleIdOf` answers `null` for
+ * every one of its files, so a green was honest about a population that did not
+ * contain them. {@link scanApplicationReaches} is that half, `relative-host-reach`
+ * is its finding, and {@link LedgeredHostReach} is its ledger's entry.
+ *
+ * It is one rule with two populations and not two rules: this analysis already
+ * derives the four inputs a second one would re-derive, and two derivations of
+ * one population are two answers waiting to disagree (D-100). Normative:
+ * `specs/115-lifecycle-container-move/contracts/host-reach-check.md`.
+ *
+ * Usage: `tsx scripts/check-platform-surface.ts [--list]`
+ * Exit 0 = every reach into the platform is published, declared or ledgered;
+ * exit 1 = at least one is not, or a ledger entry is stale;
+ * exit 2 = the walk, the index, a barrel or the application tree could not be read.
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { moduleIdOf } from '../lib/module-population.js';
+import { resolutionCandidates, resolveHostSpecifier, resolveRelative, } from '../lib/platform-surface.js';
+import {} from '../lib/read-size.js';
+import { namedSpecifiers } from '../lib/specifiers.js';
+/** The symbol token recorded for a reach that names no symbol at all. */
+export const WHOLE_FILE = '*';
+/** The symbol token recorded for a finding that is about the file, not a name. */
+export const NO_SYMBOL = '?';
+/** The target token recorded for a source file no module owns. */
+export const NO_MODULE = '(unattributed)';
+/**
+ * The floor that follows the sweep: every module package whose manifest
+ * declares the host must have contributed a host reach to this walk.
+ *
+ * This is issue #215's predicate over the population T060 restored, and it is
+ * the one derivation that would have caught the defect. The other two cannot:
+ * `manifest-index` counts modules that produced a **file**, and a packaged
+ * module produces plenty; `platform-barrels` counts barrels, which the move
+ * does not touch. What fell was the *reaches*, and the number that recorded
+ * them was a snapshot in `test/helpers/check-read-sizes.ts` whose −10% floor
+ * absorbed one module's worth of the fall without a word.
+ *
+ * The declaration is a second author's, which is what makes it worth
+ * reconciling against: `manifests:generate` renders a module package's
+ * `peerDependencies` from the bare specifiers its sources import, and
+ * `manifests:check` fails on drift. So "the manifest says this package reaches
+ * the host" and "the walk read a reach from this package" are two derivations
+ * of one fact, and a walk that stopped reading bare specifiers makes them
+ * disagree in the same run.
+ *
+ * `null` rather than `expected: 0` for a tree with no module package that
+ * declares the host — every tree in this repository until !910, and every
+ * fixture workspace. An expectation of zero is itself a refusal in this
+ * grammar, and rightly: a floor that expects nothing is switched off.
+ */
+export function hostDependentCoverage(packages, hostReachModules) {
+    const declaring = packages.filter((pkg) => pkg.dependsOnHost);
+    if (declaring.length === 0)
+        return null;
+    return {
+        source: 'host-dependents',
+        expected: declaring.length,
+        covered: declaring.filter((pkg) => hostReachModules.has(pkg.moduleId)).length,
+    };
+}
+/** `<module file>|<platform file>` — the ledger key and the identity of a reach. */
+export function keyOf(finding) {
+    return `${finding.file}|${finding.target}`;
+}
+/** The file a specifier names, or `null` when the walk found no such file. */
+/**
+ * A specifier's target file, or `null`. Exported because both hosts build the
+ * platform's published surface with it and a second resolver would be a second
+ * answer to "which file does this name".
+ */
+export function resolveTarget(fromKey, specifier, files) {
+    const joined = resolveRelative(fromKey, specifier);
+    if (joined === null)
+        return null;
+    for (const candidate of resolutionCandidates(joined)) {
+        if (files.has(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Every module reach into the platform, judged against the published surface.
+ *
+ * Pure over source text, file keys and barrel-derived surface, so a fixture
+ * enters exactly where a run does — including the specifier extraction and the
+ * `.js` → `.ts` resolution, which is where a resolution bug would hide (issue
+ * #130).
+ */
+export function scanPlatformSurface(input) {
+    const attribute = input.moduleIdOf ?? moduleIdOf;
+    const canonical = input.canonicalTargetOf ?? ((key) => key);
+    const host = input.host ?? null;
+    const platformSourceRoot = input.platformSourceRoot ?? null;
+    const withinPlatform = (key) => platformSourceRoot !== null &&
+        (key === platformSourceRoot || key.startsWith(`${platformSourceRoot}/`));
+    const findings = [];
+    const hostReachModules = new Set();
+    let reaches = 0;
+    for (const [file, text] of [...input.sources].sort(([a], [b]) => a.localeCompare(b))) {
+        const moduleId = attribute(file);
+        if (moduleId === null) {
+            // A file the walk opened and could not attribute. Skipping it would leave
+            // it counted in `read: files=` and judged by nothing, which is #215 one
+            // layer in (!879).
+            findings.push({
+                kind: 'unattributed-source',
+                file,
+                line: 1,
+                moduleId: null,
+                target: NO_MODULE,
+                symbol: NO_SYMBOL,
+                specifier: '',
+            });
+            continue;
+        }
+        // Attributed, and then exempt: a module inside the host package reaches the
+        // platform by relative path within one package — see `platformSourceRoot`.
+        if (withinPlatform(file))
+            continue;
+        for (const specifier of namedSpecifiers(text, file)) {
+            // A bare specifier into the host package is the same reach a module in
+            // the application tree writes relatively (feature 080, T060). Asked
+            // first, because a specifier that names the host is never a relative one
+            // and the two answers must not both be consulted.
+            const hostReach = resolveHostSpecifier(specifier.text, host);
+            if (hostReach !== null)
+                hostReachModules.add(moduleId);
+            if (hostReach?.kind === 'undeclared-subpath' || hostReach?.kind === 'host-internal-subpath') {
+                findings.push({
+                    // The two are one branch and two verdicts on purpose: both are about
+                    // the *subpath* rather than a symbol, and only one of them names a
+                    // path the host's `exports` map resolves.
+                    kind: hostReach.kind === 'undeclared-subpath'
+                        ? 'unpublished-subpath'
+                        : 'host-internal-subpath',
+                    file,
+                    line: specifier.line,
+                    moduleId,
+                    target: specifier.text,
+                    symbol: NO_SYMBOL,
+                    specifier: specifier.text,
+                });
+                continue;
+            }
+            // Someone else's package: `zod`, `@mikro-orm/core`, another module's.
+            if (hostReach === null && !specifier.text.startsWith('.'))
+                continue;
+            const resolved = hostReach === null ? resolveTarget(file, specifier.text, input.files) : hostReach.target;
+            const target = resolved === null ? null : canonical(resolved);
+            if (target === null) {
+                findings.push({
+                    kind: 'unresolvable-reach',
+                    file,
+                    line: specifier.line,
+                    moduleId,
+                    target: specifier.text,
+                    symbol: NO_SYMBOL,
+                    specifier: specifier.text,
+                });
+                continue;
+            }
+            // Module → module is `check:module-boundary`'s rule, not this one's.
+            if (attribute(target) !== null)
+                continue;
+            const named = specifier.bindings.filter((binding) => !binding.startsWith('* as'));
+            const wholeFile = specifier.bindings.length === 0 || named.length < specifier.bindings.length;
+            if (wholeFile) {
+                reaches += 1;
+                // Reaching a barrel *is* reaching the published surface, whole or not.
+                if (!input.surface.barrels.has(target)) {
+                    findings.push({
+                        kind: 'whole-file-reach',
+                        file,
+                        line: specifier.line,
+                        moduleId,
+                        target,
+                        symbol: WHOLE_FILE,
+                        specifier: specifier.text,
+                    });
+                }
+            }
+            const published = input.surface.published.get(target) ?? new Set();
+            for (const name of named) {
+                reaches += 1;
+                if (input.surface.barrels.has(target))
+                    continue;
+                if (published.has(name))
+                    continue;
+                findings.push({
+                    kind: 'unpublished-symbol',
+                    file,
+                    line: specifier.line,
+                    moduleId,
+                    target,
+                    symbol: name,
+                    specifier: specifier.text,
+                });
+            }
+        }
+    }
+    findings.sort((a, b) => a.file === b.file
+        ? a.target === b.target
+            ? a.symbol.localeCompare(b.symbol)
+            : a.target.localeCompare(b.target)
+        : a.file.localeCompare(b.file));
+    return { reaches, findings, hostReachModules };
+}
+export function checkPlatformSurface(input, ledger) {
+    const scan = scanPlatformSurface(input);
+    const seen = new Map();
+    for (const finding of scan.findings) {
+        const symbols = seen.get(keyOf(finding)) ?? new Set();
+        symbols.add(finding.symbol);
+        seen.set(keyOf(finding), symbols);
+    }
+    const covers = (finding) => ledger[keyOf(finding)]?.symbols.includes(finding.symbol) === true;
+    const staleKeys = [];
+    const staleSymbols = [];
+    for (const [key, entry] of Object.entries(ledger)) {
+        const symbols = seen.get(key);
+        if (symbols === undefined) {
+            staleKeys.push(key);
+            continue;
+        }
+        for (const symbol of entry.symbols) {
+            if (!symbols.has(symbol))
+                staleSymbols.push(`${key}#${symbol}`);
+        }
+    }
+    return {
+        reaches: scan.reaches,
+        findings: scan.findings,
+        violations: scan.findings.filter((finding) => !covers(finding)),
+        ledgered: scan.findings.filter(covers),
+        staleKeys: staleKeys.sort(),
+        staleSymbols: staleSymbols.sort(),
+        unreadable: input.surface.unreadable,
+        hostReachModules: scan.hostReachModules,
+    };
+}
+/**
+ * The platform **source** file a specifier landing inside the member names, or
+ * `null`.
+ *
+ * The canonicalisation drops the member-relative path's **first segment** —
+ * whatever it is — and re-roots the remainder at the platform's source root. So
+ * `dist/lifecycle/manifest.js` and `src/lifecycle/manifest.ts` both canonicalise
+ * to `packages/platform/src/lifecycle/manifest.ts`, and the word `dist` appears
+ * nowhere: a build directory renamed in the package's own `tsconfig.build.json`
+ * arrives here by being renamed, not by anybody remembering this file (D-100).
+ *
+ * `null` for a specifier that lands inside the member and resolves to no source
+ * file. That is deliberate and is the contract's own ruling (§3): a relative
+ * specifier resolving to nothing inside the platform is not a host reach at all,
+ * and reporting it here would be this check answering `tsc`'s question. The
+ * risk it carries — a canonicalisation bug silently resolving everything to
+ * `null` — is not silent: the ledger is two-way, so a walk that stopped
+ * resolving reports every entry it holds as stale and exits 1.
+ */
+export function canonicalPlatformFile(joined, input) {
+    const prefix = `${input.platformMemberRoot}/`;
+    if (!joined.startsWith(prefix))
+        return null;
+    const withinMember = joined.slice(prefix.length);
+    const cut = withinMember.indexOf('/');
+    if (cut <= 0)
+        return null;
+    const rest = withinMember.slice(cut + 1);
+    if (rest.length === 0)
+        return null;
+    for (const candidate of resolutionCandidates(`${input.platformSourceRoot}/${rest}`)) {
+        if (input.files.has(candidate))
+            return candidate;
+    }
+    return null;
+}
+/** The bare specifier carrying a platform file, or `null` when none does. */
+function publishedSpecifierFor(target, input) {
+    const carriers = input.surface.publishedBy.get(target) ?? new Set();
+    for (const [subpath, barrel] of input.host.subpathTargets) {
+        // Reaching a barrel *is* reaching its subpath, whole or not.
+        if (barrel === target || carriers.has(barrel))
+            return `${input.host.name}/${subpath}`;
+    }
+    return null;
+}
+/**
+ * Every application reach into the platform written as a relative path.
+ *
+ * Pure over source text, file keys, barrel-derived surface and the two platform
+ * roots — so a fixture enters exactly where a run does, specifier extraction and
+ * `.js` → `.ts` resolution included (issue #130, and the `check-entry-scope`
+ * fixture that entered below its own classifier is the cautionary example).
+ *
+ * **A bare specifier into the host produces no finding here, and that is the
+ * discrimination the rule turns on.** `@endora-commerce/platform/kernel` and
+ * `@endora-commerce/platform/composition` are both correct from the application:
+ * the first is published and the second is the host-internal address the host is
+ * entitled to (D-160.14). The three-way answer for a bare specifier is a
+ * *module's* — `resolveHostSpecifier` in {@link scanPlatformSurface} — and asking
+ * it twice, with two populations and two verdicts, is two answers waiting to
+ * disagree.
+ */
+export function scanApplicationReaches(input) {
+    const findings = [];
+    let reaches = 0;
+    for (const [file, text] of [...input.sources].sort(([a], [b]) => a.localeCompare(b))) {
+        for (const specifier of namedSpecifiers(text, file)) {
+            if (!specifier.text.startsWith('.'))
+                continue;
+            const joined = resolveRelative(file, specifier.text);
+            if (joined === null)
+                continue;
+            const target = canonicalPlatformFile(joined, input);
+            if (target === null)
+                continue;
+            reaches += 1;
+            findings.push({
+                kind: 'relative-host-reach',
+                file,
+                line: specifier.line,
+                moduleId: null,
+                target,
+                symbol: NO_SYMBOL,
+                specifier: specifier.text,
+                publishedAs: publishedSpecifierFor(target, input),
+            });
+        }
+    }
+    findings.sort((a, b) => a.file === b.file ? a.target.localeCompare(b.target) : a.file.localeCompare(b.file));
+    return { reaches, findings };
+}
+/**
+ * The application's reaches, judged against the ledger — both directions
+ * (host-reach-check.md §4 R4.3).
+ *
+ * One reach may appear twice under one key when a file names the same platform
+ * file from two specifiers; the ledger is keyed `(file, target)` and covers
+ * both, which is right: the entry's subject is the coupling, not the line.
+ */
+export function checkApplicationReaches(input, ledger) {
+    const scan = scanApplicationReaches(input);
+    const seen = new Set(scan.findings.map(keyOf));
+    const covers = (finding) => ledger[keyOf(finding)] !== undefined;
+    return {
+        ...scan,
+        violations: scan.findings.filter((finding) => !covers(finding)),
+        ledgered: scan.findings.filter(covers),
+        staleKeys: Object.keys(ledger)
+            .filter((key) => !seen.has(key))
+            .sort(),
+    };
+}
+/**
+ * The coverage floor for the application half: the ledger's own still-on-disk
+ * file set, against what the walk opened of it.
+ *
+ * host-reach-check.md §5's fourth refusal, and it is `check:module-boundary`'s
+ * admin-host floor one package over — a floor derived from *the ledger* rather
+ * than from a count, so a walk that stopped reaching the files it is ledgered
+ * over is a refusal rather than a drained ledger. The ledger is a second
+ * author's answer to "which application files reach the platform": it was
+ * written by whoever measured the debt, and it goes stale loudly rather than
+ * quietly.
+ *
+ * `null` rather than `expected: 0` once the ledger empties, which is what this
+ * ledger is for: an expectation of zero is itself a refusal in this grammar
+ * (`readSizeRefusal`'s `no-expectation`), and rightly — a floor that expects
+ * nothing is switched off.
+ */
+export function hostReachCoverage(ledger, onDisk, opened) {
+    const ledgeredFiles = new Set(Object.keys(ledger).map((key) => key.split('|')[0] ?? ''));
+    const expected = [...ledgeredFiles].filter((file) => onDisk(file));
+    if (expected.length === 0)
+        return null;
+    return {
+        source: 'host-reaches',
+        expected: expected.length,
+        covered: expected.filter((file) => opened.has(file)).length,
+    };
+}
+/**
+ * Why this run may not report on the application's reaches, or `null`.
+ *
+ * Two of host-reach-check.md §5's four refusals — the two that are facts about
+ * *this* half's inputs. The first ("no platform root") is already this check's
+ * own first refusal and stays there; the fourth is the ledger-derived coverage
+ * floor and belongs to `read-size.ts`, which is the one place in the estate that
+ * owns a short walk.
+ *
+ * Both fail in the direction that produces a **clean** result, which is why they
+ * are exit 2 and not a finding. An empty canonical-target map reports every
+ * relative reach as reaching nothing; an application walk that opened no file
+ * reports no reach at all — and this check's module half would go on printing
+ * `files=2069` beside it, because 1364 of `backend/src`'s files are a module's
+ * and a broken *application* walk leaves every one of those numbers healthy
+ * (issue #215's shape over this population).
+ */
+export function applicationReachRefusal(input) {
+    if (input.canonicalTargets === 0) {
+        return ('the platform walk produced no source file — a relative reach into the platform is ' +
+            'canonicalised against that walk, so every one of them would resolve to nothing and ' +
+            'the application half would report clean over a population it never saw');
+    }
+    if (input.applicationFiles === 0) {
+        return ('the application walk opened no file — the module half of this check reads most of ' +
+            "`backend/src` and would keep printing a healthy `files=`, so a broken application " +
+            'walk is a silence rather than a number that moved (issue #215)');
+    }
+    return null;
+}
+/**
+ * Why this run may not judge a reach against the surface it read, or `null`.
+ *
+ * Pure over the two things that can be silently missing — a barrel that is not
+ * there, and a re-export the parse cannot enumerate — because both fail in the
+ * same direction and it is the wrong one: a **short** published set turns
+ * correct reaches into findings, and the obvious repair for one of those is to
+ * widen the barrel. So it is exit 2, in the idiom of `readSizeRefusal`, and a
+ * proof enters where a run enters (issue #130).
+ */
+export function platformSurfaceRefusal(input) {
+    if (input.missingBarrels.length > 0) {
+        return (`${input.missingBarrels.join(', ')} — a published subpath (D-160.7) whose barrel is ` +
+            'not there. The published surface would come back short and every reach into that ' +
+            'directory would read as a violation; refusing to report on it');
+    }
+    if (input.surface.unreadable.length > 0) {
+        const named = input.surface.unreadable
+            .map((entry) => `\n  - ${entry.barrel}:${entry.line}  ${entry.reason}`)
+            .join('');
+        return ('a published barrel holds a re-export this parse cannot enumerate, so the published ' +
+            'surface would come back short — and the obvious "repair" for a reach it wrongly ' +
+            `refused is to widen the barrel:${named}`);
+    }
+    return null;
+}
+/**
+ * Every TypeScript source under `dir`, with the rule's own prunes applied.
+ *
+ * Exported because the population is part of the rule: two hosts computing
+ * "which files this check reads" two ways is the shape that lets one of them go
+ * half-blind.
+ */
+export function collectPlatformSurfaceSources(dir, out = []) {
+    if (!existsSync(dir))
+        return out;
+    for (const name of readdirSync(dir)) {
+        const full = join(dir, name);
+        if (statSync(full).isDirectory()) {
+            if (name === 'node_modules' || name === 'dist')
+                continue;
+            collectPlatformSurfaceSources(full, out);
+        }
+        else if (
+        // `.tsx` since feature 091: a module package's `./admin` layer is React
+        // components, and a walk that cannot see them reports every relative
+        // reach into one as `unresolvable-reach` — a finding about the walk.
+        (name.endsWith('.ts') || name.endsWith('.tsx')) &&
+            !name.endsWith('.test.ts') &&
+            !name.endsWith('.test.tsx') &&
+            !name.endsWith('.d.ts')) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+/**
+ * A module package's own tooling configuration, which is not module source.
+ *
+ * `vitest.config.ts` is the first `.ts` file a module package holds that its
+ * build does not compile (feature 089, Phase 1): `tsconfig.build.json` roots the
+ * emit at `src/`, and the manifest's `files` ships `dist` and the asset
+ * directories, so nothing a consumer installs contains it and no `exports`
+ * subpath can name it. The other configurations a package carries are `.json`
+ * and were therefore never in this walk at all.
+ *
+ * It has to leave the population rather than be made to resolve, because the
+ * file exists to `mergeConfig` the repository root's `vitest.config.base.ts` —
+ * which is where issue #255's foreign-workspace-link refusal lives, so the reach
+ * is mandatory — and that root is in no module walk root and no source root. A
+ * reach the walk cannot resolve is `unresolvable-reach`, deliberately fail-closed
+ * (#215 one layer in), and the honest answer here is that this file is not a
+ * module reach at all.
+ *
+ * Narrow on purpose: only a `*.config.ts` sitting **directly** at a module walk
+ * root, which is a package's own root or a module directory. A `config.ts` under
+ * `src/` stays module source, and a directory named `config/` is untouched.
+ */
+export function isPackageToolingConfig(root, file) {
+    const within = relative(root, file).split('\\').join('/');
+    return !within.includes('/') && within.endsWith('.config.ts');
+}
+/** The remedy sentence a finding gets, by kind. */
+/**
+ * The remedy paragraph for a finding.
+ *
+ * Exported because the remedy is part of the rule and not part of a host: an
+ * author outside this checkout reads the same sentence this repository's run
+ * prints.
+ */
+export function remedyOf(finding) {
+    switch (finding.kind) {
+        case 'unpublished-symbol':
+            return `\`${finding.symbol}\` is not published out of ${finding.target}`;
+        case 'whole-file-reach':
+            return `reaches every export of ${finding.target}, internals included`;
+        case 'unresolvable-reach':
+            return `\`${finding.specifier}\` resolves to no file the walk found`;
+        case 'unattributed-source':
+            return 'the walk opened this file and no module owns it';
+        case 'unpublished-subpath':
+            return (`\`${finding.specifier}\` names no subpath the host publishes — its \`exports\` map ` +
+                'refuses the path at resolution time');
+        case 'relative-host-reach':
+            return (`\`${finding.specifier}\` names ${finding.target} by relative path. ` +
+                (finding.publishedAs === null || finding.publishedAs === undefined
+                    ? 'the platform declares no subpath carrying this file — the remedy is to declare ' +
+                        'one (host-internal unless a module needs it) or to stop reaching it'
+                    : `the address is \`${finding.publishedAs}\``) +
+                '. A relative path into the package resolves in this checkout and in no instance, ' +
+                'which is what stops a build made of published packages from working');
+        case 'host-internal-subpath':
+            return (`\`${finding.specifier}\` names a subpath the host declares for its own composition ` +
+                'and publishes to nobody (host-package.md §2.7). It resolves, which is why this is ' +
+                'the one finding here that neither `node` nor `tsc` would raise — and no module may ' +
+                'name it, production source or test alike. A server-bound test composes through the ' +
+                'test kit, never through `composeModules`');
+    }
+}
+//# sourceMappingURL=platform-surface.js.map