@event4u/agent-config 16.2.0 → 16.4.0

package/dist/scripts/_lib/installed_layer.js

@@ -0,0 +1,704 @@
+/**
+ * What a host actually loads, measured in the host's own unit (step 0.1 of
+ * `road-to-a-rule-carrier-that-works-outside-the-repo`).
+ *
+ * THE QUESTION NOTHING IN THIS TREE COULD ANSWER. Every existing figure for the
+ * installed layer counts raw bytes of whole files: `censusRuleDir` sums
+ * `statSync().size`, `charsAtRoot` does the same for a directory, and
+ * `check_preamble_payload_budget` reads both. A host does not load frontmatter
+ * as instruction — it is the routing surface, which the router has already
+ * read — and it does not render HTML comments, which are authoring scaffolding.
+ * So the number a reader wants when they ask "how much instruction is this
+ * consumer under" has never been computed here.
+ *
+ * THE NUMBER IS THEREFORE NOT COMPARABLE WITH ANY PUBLISHED BASELINE, and that
+ * is stated here rather than discovered by someone holding the two side by
+ * side. `chars` below is strictly smaller than the byte figures in
+ * `budgets.yml`, `rule-activation-census.json` or the payload ratchet, and the
+ * gap is not a constant — it is whatever that particular corpus spends on
+ * frontmatter and comments.
+ *
+ * ONE LIBRARY, FOUR CONSUMERS. The report CLI is the only one wired in this
+ * change (Phase 0 makes no behavior change), and the shape is the reason the
+ * other three named in step 0.1 — CI, `doctor`, the upgrade receipt — can use
+ * it without a second reader: every input is a PARAMETER. `home`, `projectRoot`
+ * and `manifestPath` are supplied by the caller, never read off the process, so
+ * a test, a temporary `HOME` and a real machine are the same call with
+ * different arguments. That is also what makes the step's "install into a
+ * temporary HOME" reachable at all, and it is the fact that refutes
+ * `check_standing_rule_delivery`'s header: a user-scope install IS observable
+ * from CI, because the installer takes `HOME` from the environment.
+ *
+ * WHAT `package_owned` AND `foreign` MEAN, because the honest answer is three
+ * valued and the report has two columns. `recordedOwnership` distinguishes
+ * `recorded-unchanged`, `recorded-modified` and `unknown`, where `unknown` is
+ * explicitly "this tree cannot say" rather than "foreign". The report folds the
+ * first two into `package_owned` — both are files the manifest claims — and
+ * reports the third as `foreign`, which therefore reads "not claimed by this
+ * install", never "written by someone else". A machine with no manifest reports
+ * every file foreign, which is the correct reading of no evidence and is why
+ * {@link InstalledLayerReport.manifest_present} is in the output.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { GLOBAL_RULE_DIRS, PROJECT_RULE_DIRS, globalRuleLayerPath, } from '../../install/globalRuleLayers.js';
+import { NO_RECORDED_HASHES, readRecordedHashes } from '../../install/recordedOwnership.js';
+import { INVENTORY_BASENAME, inventory_path, load_inventory, recorded_absolute_files, } from './global_deploy_inventory.js';
+import { DEFAULT_EVENT4U_ROOT_RELATIVE } from './user_global_paths.js';
+import { ruleBody, splitFrontmatter } from './rule_law_section.js';
+/** How many files the per-directory ranking carries. Step 0.1 fixes it at 20. */
+export const TOP_FILES = 20;
+/**
+ * The fraction of a published limit at which the report warns.
+ *
+ * 0.8 is step 1.4's number, not a tuned one. It is a WARNING threshold and
+ * never a gate: crossing it changes what the report says and nothing else, so
+ * no install fails here.
+ */
+export const LIMIT_WARN_FRACTION = 0.8;
+/**
+ * Whether the host loads this file on every session rather than on a path match.
+ *
+ * `paths:` at the start of a line IN THE FRONTMATTER is the whole test, and it
+ * is the host's own convention rather than this package's: `claudeRuleRewrite`
+ * states it from the emitting side — "with it a rule loads on a path match,
+ * without it the rule loads unconditionally".
+ *
+ * SCOPED TO THE FRONTMATTER, which it was not until 2026-10-06. The predicate
+ * tested the whole unstripped file while the characters it partitions come
+ * from `ruleBody` — predicate and measure read different strings. That was
+ * survivable while it only moved a file COUNT; since the when-loaded character
+ * split it decides which bucket a whole file's characters land in, and
+ * `unconditional_chars` is the figure the ceiling argument is read in. One body
+ * line beginning `paths:` — a YAML trigger example quoted inside a kernel or
+ * `no_stub` rule, which is ordinary prose — would have moved that rule's entire
+ * character count from standing to path-scoped, silently.
+ *
+ * Measured before the change: of the 105 files on a real opted-in install, two
+ * are path-scoped by either reading and none carries a body-only mention, so
+ * the fix moves no published figure. It is hardening against a case that does
+ * not exist yet rather than a correction of one that does, and it is worth
+ * making precisely because the failure would be silent.
+ *
+ * `check_single_delivery` already slices the frontmatter before this test, so
+ * this now AGREES with it. `rule_activation_census.projection_reading` still
+ * scans the whole file; that reader counts files rather than characters, so the
+ * divergence costs it nothing today, and changing a census's reading belongs to
+ * that census rather than here. Named so the next reader finds a known
+ * difference instead of discovering an unexplained one.
+ *
+ * SOURCE-SIDE CLASSIFICATION IS A DIFFERENT QUESTION and deliberately not used.
+ * `classify_rule` reads `alwaysApply` and `type: always` to tell `always` from
+ * `unconditional`, which matters when you are deciding what to emit. This
+ * reads what WAS emitted, where the distinction has already been spent: an
+ * Iron-Law rule and an untriggered tier-2 rule both arrive without `paths:` and
+ * both load every session, which is the only property the host acts on.
+ */
+export function isUnconditional(text) {
+    // THE SAME FUNCTION that produces the characters being partitioned, not the
+    // same arithmetic re-implemented. An earlier version scanned for
+    // `'\n---'` while `ruleBody` -> `splitFrontmatter` scans for `'\n---\n'`,
+    // so the two disagreed about where the frontmatter stops, and the
+    // predicate's early stop could hide a later `paths:` key.
+    const [frontmatter] = splitFrontmatter(text);
+    // AND THE BLIND SPOT THAT SCOPING OPENS, CLOSED HERE. `splitFrontmatter`
+    // returns `''` for anything that does not begin exactly `---\n` — a BOM, a
+    // leading blank line, CRLF, a block that never closes — and scoping to `''`
+    // reads every such file as unconditional even when its frontmatter carries
+    // `paths:`. `readLayer` measures every `.md` in a host directory, foreign
+    // user-authored rules included, so that would inflate `unconditional_chars`
+    // silently, which is the figure the whole ceiling argument is read in.
+    //
+    // A file that CLAIMS a block `splitFrontmatter` could not parse falls back
+    // to the whole-text test. The claim test is the one `installThinLayer`
+    // already uses for the same blind spot, and is a regex rather than
+    // `startsWith('---')` for the reason stated there.
+    //
+    // WHICH WAY THE FALLBACK ERRS, SAID PLAINLY RATHER THAN CALLED
+    // "CONSERVATIVE". It can only move characters OUT of the standing bucket,
+    // never into it. That is conservative about the claim "this rule stands
+    // every session" — it never asserts one it cannot support. It is the
+    // FLATTERING direction for the ceiling argument, which reads the standing
+    // figure against a limit: a misfire here makes the layer look smaller than
+    // it is. Both halves are true and the second is the one a reader checking
+    // the overage needs, so it is stated rather than left to the word.
+    //
+    // AND THE STATE THAT IS NOT AN UNPARSEABLE BLOCK. `splitFrontmatter`
+    // returns '' for a WELL-FORMED EMPTY block too — `---\n---\n` has no
+    // `\n---\n` after index 4, so its own parse fails — and such a file has no
+    // `paths:` key by construction. Without the second test it fell to the
+    // whole-text scan and a body line beginning `paths:` (a quoted trigger
+    // example, which is exactly what a rule about triggers contains) moved the
+    // file's entire character count out of the standing figure. Measured
+    // before the exclusion: `---\n---\npaths: not a key, just prose\n` read
+    // path-scoped.
+    const emptyBlock = /^---\n---(\n|$)/.test(text);
+    if (frontmatter === '' && !emptyBlock && /^\uFEFF?[\s]*---/.test(text)) {
+        return !/^paths:/m.test(text);
+    }
+    return !/^paths:/m.test(frontmatter);
+}
+/**
+ * Measure one directory.
+ *
+ * `.md` only, matching `censusRuleDir` and `topRulesByCost`, so the FILE count
+ * is comparable with the existing byte censuses even though the character count
+ * is not. Cursor's `.mdc` tree is therefore read as zero files, which is the
+ * same blind spot every other census in this tree has and is not fixed here —
+ * fixing it in one reader and not the others would make two counts that
+ * disagree, which is worse than one that is openly partial.
+ */
+export function readLayer(host, scope, dir, recorded) {
+    const empty = {
+        files: 0,
+        unconditional: 0,
+        chars: 0,
+        package_owned: 0,
+        foreign: 0,
+        package_owned_chars: 0,
+        foreign_chars: 0,
+        unconditional_chars: 0,
+        scoped_chars: 0,
+        top: [],
+    };
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return { host, scope, dir, present: false, ...empty };
+    }
+    const readings = [];
+    for (const name of names.sort()) {
+        if (!name.endsWith('.md'))
+            continue;
+        const abs = path.join(dir, name);
+        let text;
+        try {
+            const st = fs.statSync(abs);
+            if (!st.isFile())
+                continue;
+            text = fs.readFileSync(abs, 'utf-8');
+        }
+        catch {
+            continue; // a file that cannot be read is not a file the host loads
+        }
+        // RECORDED-BUT-MODIFIED IS STILL RECORDED. The report's two columns
+        // answer "does this install claim the file"; `classifyOwnership` answers
+        // the finer question the upgrade path needs — whether the bytes still
+        // match — and folding that in here would give a column three meanings.
+        const owned = recorded.has(abs);
+        readings.push({
+            file: name,
+            // THE STRIP IS THE PROJECTOR'S OWN. `ruleBody` is what
+            // `project_thin_rules` and the delivery carrier both call, so "what
+            // a host loads" and "what a delivery carries" cannot drift into two
+            // spellings of the same measurement.
+            chars: ruleBody(text).length,
+            unconditional: isUnconditional(text),
+            package_owned: owned,
+        });
+    }
+    const top = [...readings]
+        // RANKED BY THE SAME MEASURE AS THE TOTAL, which is why
+        // `preamble_byte_census.topRulesByCost` is not reused here: it ranks by
+        // `statSync().size`, so its list and this total would be in different
+        // units and the largest file by one could be absent from the other.
+        .sort((a, b) => b.chars - a.chars || a.file.localeCompare(b.file))
+        .slice(0, TOP_FILES);
+    return {
+        host,
+        scope,
+        dir,
+        present: true,
+        files: readings.length,
+        unconditional: readings.filter((r) => r.unconditional).length,
+        chars: readings.reduce((n, r) => n + r.chars, 0),
+        package_owned: readings.filter((r) => r.package_owned).length,
+        foreign: readings.filter((r) => !r.package_owned).length,
+        package_owned_chars: readings.reduce((n, r) => n + (r.package_owned ? r.chars : 0), 0),
+        foreign_chars: readings.reduce((n, r) => n + (r.package_owned ? 0 : r.chars), 0),
+        unconditional_chars: readings.reduce((n, r) => n + (r.unconditional ? r.chars : 0), 0),
+        scoped_chars: readings.reduce((n, r) => n + (r.unconditional ? 0 : r.chars), 0),
+        top,
+    };
+}
+/**
+ * Where the limits live, derived from this module rather than from `cwd`.
+ *
+ * The two `..` hops climb from `src/scripts/_lib` to `src/`, which is where
+ * `config/` lives — NOT to the package root, though the comment said so until
+ * 2026-10-05. The result is correct and the arithmetic stated for it was not,
+ * which is the half a future reader would trust when changing the hops.
+ *
+ * `fileURLToPath`, NOT `new URL(...).pathname` — the claimed parity with
+ * `default_template_path()` was only half true until 2026-10-05. A `pathname`
+ * percent-encodes, so a package under a directory with a space resolved to
+ * `/Users/x/My%20Projects/...`, and on Windows it yields a leading-slash drive
+ * path. Either way the read fails, `loadHostInstructionLimits` swallows it and
+ * returns an empty map, and EVERY host then reads `unpublished` with `warn`
+ * false — the budget measurement degrading to "not measured" with no signal,
+ * which is the one failure mode this file's own limit table was written to
+ * avoid.
+ */
+export function defaultHostLimitsPath() {
+    return path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'config', 'host-instruction-limits.json');
+}
+/**
+ * Read the published-limit table.
+ *
+ * TOLERANT IN ONE DIRECTION ONLY. An unreadable or malformed file yields an
+ * EMPTY table, so every host reads `unpublished` and nothing warns — a reading
+ * this tree cannot stand behind must never become a warning it can. A present
+ * entry whose `limit` is not a positive finite number is treated the same way,
+ * because a `0` or a string would otherwise make every install look saturated.
+ */
+export function loadHostInstructionLimits(file = defaultHostLimitsPath()) {
+    const out = new Map();
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return out; // no table ⇒ no limits ⇒ no warnings
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return out;
+    for (const [host, v] of Object.entries(raw)) {
+        if (host.startsWith('_'))
+            continue; // `_comment` and friends are not hosts
+        if (typeof v !== 'object' || v === null || Array.isArray(v))
+            continue;
+        const e = v;
+        const n = e.limit;
+        const limit = typeof n === 'number' && Number.isFinite(n) && n > 0 ? n : null;
+        const k = e.kind;
+        const kind = limit === null
+            ? 'unpublished'
+            : k === 'vendor-published' || k === 'reported'
+                ? k
+                : 'reported'; // a cited figure with no stated kind is the weaker one
+        out.set(host, { limit, kind });
+    }
+    return out;
+}
+/**
+ * Fold the per-directory readings into one row per host, against its limit.
+ *
+ * Exported so a caller holding layers it built itself — the install receipt,
+ * which measures before and after — can produce the same rows without
+ * re-reading the tree.
+ */
+export function buildHostLimitRows(layers, limits) {
+    const byHost = new Map();
+    for (const l of layers) {
+        if (!l.present)
+            continue;
+        const acc = byHost.get(l.host) ?? { chars: 0, owned: 0, foreign: 0 };
+        acc.chars += l.chars;
+        acc.owned += l.package_owned_chars;
+        acc.foreign += l.foreign_chars;
+        byHost.set(l.host, acc);
+    }
+    // EVERY host that has a directory gets a row, present or not — a host whose
+    // layer is absent reads 0 against its limit, which is a real answer and the
+    // one step 3.5 asks for ("one row per host with a published limit").
+    for (const l of layers)
+        if (!byHost.has(l.host))
+            byHost.set(l.host, { chars: 0, owned: 0, foreign: 0 });
+    // AND every host the LIMITS table knows, whether or not a layer reached it.
+    // Rows were layer-driven while the requirement is limit-driven, so a limit
+    // recorded for a host the layer map does not list disappeared silently —
+    // the two sources agree today, which means they can only diverge in the
+    // direction the code did not cover.
+    for (const [host, e] of limits)
+        if (e.limit !== null && !byHost.has(host)) {
+            byHost.set(host, { chars: 0, owned: 0, foreign: 0 });
+        }
+    const rows = [];
+    for (const host of [...byHost.keys()].sort()) {
+        const a = byHost.get(host);
+        const e = limits.get(host) ?? { limit: null, kind: 'unpublished' };
+        const fraction = e.limit === null ? null : a.chars / e.limit;
+        rows.push({
+            host,
+            limit: e.limit,
+            kind: e.kind,
+            chars: a.chars,
+            package_owned_chars: a.owned,
+            foreign_chars: a.foreign,
+            fraction,
+            warn: fraction !== null && fraction >= LIMIT_WARN_FRACTION,
+        });
+    }
+    return rows;
+}
+/**
+ * Where `deployed-files.json` lives FOR A STATED HOME.
+ *
+ * `global_deploy_inventory.inventory_path()` answers for the process asking,
+ * honouring `AGENT_CONFIG_DEPLOY_INVENTORY` and `EVENT4U_CONFIG_HOME`. That is
+ * right for the installer, which is running the install it is recording, and
+ * WRONG for a reader measuring some other home: a report about a staged install
+ * under a temporary HOME would read the maintainer's own inventory and claim
+ * ownership of files that install never wrote.
+ *
+ * SO AN EXPLICITLY SUPPLIED HOME WINS, AND THE ENV OVERRIDES DECIDE ONLY THE
+ * HOME-LESS CASE. A caller that says which home it is measuring has already
+ * answered the question those variables would answer for it, and letting the
+ * asking process's environment override that is exactly the hazard named above.
+ * An intermediate draft of this function had the precedence the other way round
+ * while this paragraph said what it says now; the code is what changed.
+ *
+ * THE CONSEQUENCE, STATED RATHER THAN IMPLIED: `ReportOptions.home` is
+ * REQUIRED, so every caller of {@link buildInstalledLayerReport} supplies one
+ * and neither env override reaches this reader through that path. That is
+ * correct — those variables describe the asking process's own install, which is
+ * not what a report about another home is measuring — but it means "honours the
+ * env override" is not a true sentence about the report, and saying so here is
+ * cheaper than leaving the next reader to discover it.
+ *
+ * The layout is COMPOSED from the modules that own it rather than re-spelled,
+ * so a layout change moves this reader with it instead of leaving it looking in
+ * a directory nobody writes.
+ */
+export function defaultInventoryPath(home) {
+    // NO HOME STATED — the asking process is the subject, so the env-aware
+    // resolver is the right answer.
+    if (home === undefined || home === null || home === '')
+        return inventory_path();
+    // THE STATED HOME IS THE ASKING PROCESS'S OWN. `ReportOptions.home` is
+    // required, so `buildInstalledLayerReport` ALWAYS states one — including
+    // when it is simply measuring the machine it is running on. Treating that
+    // as "a different home" sent it to the hardcoded layout, found nothing
+    // under `EVENT4U_CONFIG_HOME` or `AGENT_CONFIG_DEPLOY_INVENTORY`, and
+    // printed "NO manifest and NO deploy inventory resolved" — the
+    // `0 package-owned` reading step 1.2 exists to remove, and it put the
+    // report and the receipt in disagreement about one install.
+    //
+    // The precedence argument only ever covered a home that is NOT this
+    // process's, so that is the case the branch now tests for.
+    try {
+        // BOTH SPELLINGS, for the reason `recorded_absolute_files` states at
+        // length: a lexical compare alone calls a symlinked or alternate
+        // spelling of the SAME home "a different home", takes the hardcoded
+        // layout, and reproduces the 0 package-owned reading this branch
+        // exists to prevent. macOS `/var` -> `/private/var` is the standing
+        // example.
+        const real = (q) => {
+            try {
+                return fs.realpathSync(q);
+            }
+            catch {
+                return path.resolve(q);
+            }
+        };
+        const mine = os.homedir();
+        if (path.resolve(home) === path.resolve(mine) || real(home) === real(mine)) {
+            return inventory_path();
+        }
+    }
+    catch {
+        // `homedir()` can throw on an exotic environment; fall through to the
+        // layout, which is the answer for a home that is not ours anyway.
+    }
+    return path.join(home, DEFAULT_EVENT4U_ROOT_RELATIVE, INVENTORY_BASENAME);
+}
+/**
+ * The ONE place that answers "which of these installed files are ours".
+ *
+ * Two readers ask it — the installed-layer report and the install receipt's
+ * budget lines — and until step 1.2 they asked different things. Both called
+ * `manifest_path(...)` and read a project-scoped `agents/installed-tools.lock`.
+ * A global-only install writes nothing into a project, so on exactly the
+ * install shape the thinned-layer roadmap's AC-1 is about, both reported
+ * `0 package-owned / N foreign` and AC-1's figure could not be produced at all.
+ *
+ * The global install DOES record what it wrote: `deployed-files.json` lists,
+ * per tool, the anchor and every file the installer maintains there —
+ * "the ownership proof that makes reaping safe". This reads it.
+ *
+ * IT IS A UNION, AND THE PATH SPACES ARE WHY. An earlier shape let the project
+ * manifest win OUTRIGHT whenever its file existed, on the reasoning that it
+ * carries hashes an inventory does not. That reasoning does not survive the
+ * observation that the two sources describe DISJOINT sets of paths: the
+ * manifest records project-relative entries resolved against `projectRoot`,
+ * the inventory records paths under the user's home. Exclusivity therefore
+ * bought nothing and cost everything — any `agents/installed-tools.lock` on
+ * disk, a gitignored file a single project-scoped install creates, restored
+ * the exact `0 package-owned` reading for the global layer that step 1.2
+ * exists to fix, while the report printed "read from the installed-tools
+ * manifest" with no evidence behind it for those paths.
+ *
+ * So every source contributes, and the MANIFEST IS MERGED LAST: on the paths
+ * it names its hash overwrites a hashless entry, which preserves the
+ * `recorded-unchanged` / `recorded-modified` distinction that motivated the
+ * precedence in the first place, without discarding evidence about paths it
+ * says nothing about.
+ *
+ * {@link OwnershipResolution.sources} lists every source that contributed at
+ * least one path, because one word cannot describe two path spaces — a report
+ * reading global and project layers together may have manifest evidence for
+ * one and inventory evidence for the other, and saying only one of them is
+ * wrong about half the files it is describing.
+ *
+ * A FILE THE USER EDITED AND THE INSTALLER PRESERVED STILL COUNTS AS
+ * MAINTAINED. The inventory records what the installer MAINTAINS at a path, not
+ * what the bytes currently are, so a preserved rule stays package-owned. That
+ * is the correct reading — the package is still responsible for the path — and
+ * it is why this function returns `null` hashes rather than fabricating one.
+ */
+export function resolveLayerOwnership(opts) {
+    const recorded = new Map();
+    const sources = [];
+    // HASHLESS SOURCES FIRST, so the manifest's hashes overwrite a `null` on
+    // any path both happen to name rather than the other way round.
+    if (opts.inventoryPath !== null) {
+        let n = 0;
+        try {
+            const inv = load_inventory(opts.inventoryPath ?? defaultInventoryPath(opts.home));
+            for (const abs of recorded_absolute_files(inv, opts.home ?? null)) {
+                // COUNT PATHS NEWLY CONTRIBUTED, not entries read, so a
+                // source that added nothing is not named as evidence.
+                //
+                // WHAT THIS GUARD DOES NOT DO, since an earlier comment here
+                // claimed it did: it does not collapse the two spellings
+                // `recorded_absolute_files` emits per file. The lexical and the
+                // realpath spelling are distinct Map keys, so wherever they
+                // differ — every path under macOS `/var` — each is newly
+                // contributed and `n` still rises twice for one file. Harmless
+                // only because `n` is read as `> 0` and never as a count; a
+                // future reader wanting a count must not take it from here.
+                if (!recorded.has(abs))
+                    n += 1;
+                recorded.set(abs, null);
+            }
+        }
+        catch {
+            // Defence in depth, and NOT where the documented behaviour lives.
+            // "A corrupt inventory is no evidence, never a failure" is real but
+            // is carried one module down: `load_inventory` swallows its own
+            // read and parse failures and returns an empty shell, and
+            // `recorded_absolute_files` type-guards every field. So this catch
+            // is unreachable for that reason and the fixture case named for it
+            // exercises `load_inventory`, not this guard. Kept because a future
+            // change to either could make it reachable; labelled so it is not
+            // mistaken for tested coverage.
+        }
+        if (n > 0)
+            sources.push('global-inventory');
+    }
+    let fromDeploy = 0;
+    for (const [anchor, rels] of opts.thisDeploy ?? new Map()) {
+        for (const rel of rels) {
+            const abs = path.resolve(anchor, rel);
+            // Same rule as the inventory branch: a source is named only when it
+            // contributes a path nothing else had. On every install after the
+            // first, `thisDeploy`'s paths are already in the inventory, and
+            // naming it there printed "the file set this install just wrote"
+            // for a source that added nothing.
+            if (!recorded.has(abs))
+                fromDeploy += 1;
+            recorded.set(abs, null);
+            // Both spellings, for the reason `recorded_absolute_files` states:
+            // the reader compares against a lexically joined path, and a HOME
+            // behind a symlink makes the two disagree.
+            try {
+                recorded.set(fs.realpathSync(abs), null);
+            }
+            catch {
+                // Not on disk — the lexical spelling is all there is.
+            }
+        }
+    }
+    if (fromDeploy > 0)
+        sources.push('this-deploy');
+    const manifestPath = opts.manifestPath ?? null;
+    if (manifestPath !== null && fs.existsSync(manifestPath)) {
+        let n = 0;
+        // DEGRADE LIKE THE INVENTORY BRANCH, which this function documents
+        // twice. The code this replaced wrapped exactly this call, so a corrupt
+        // `installed-tools.lock` used to read as "no manifest evidence" and the
+        // budget block still printed. Unguarded it threw into the receipt's
+        // outer catch and suppressed the WHOLE block — ownership line, per-host
+        // rows and the 80 % warning — and out of `buildInstalledLayerReport`,
+        // which has no outer catch at all. An unreadable manifest is no
+        // evidence, never a failure; the asymmetry was undeclared.
+        let recordedHashes;
+        try {
+            recordedHashes = readRecordedHashes(manifestPath, opts.projectRoot);
+        }
+        catch {
+            recordedHashes = NO_RECORDED_HASHES;
+        }
+        for (const [abs, hash] of recordedHashes) {
+            // The manifest contributes whenever it names a path at all: it
+            // supplies the HASH even where another source already had the path,
+            // which is evidence the others cannot give.
+            n += 1;
+            recorded.set(abs, hash);
+        }
+        if (n > 0)
+            sources.push('manifest');
+    }
+    if (recorded.size === 0) {
+        return { recorded: NO_RECORDED_HASHES, sources: [], source: 'none' };
+    }
+    // `source` keeps a single word for readers that want one. The manifest is
+    // the most specific evidence, so it leads when it contributed; otherwise
+    // the inventory, otherwise this deploy's own set.
+    const primary = sources.includes('manifest')
+        ? 'manifest'
+        : sources.includes('global-inventory')
+            ? 'global-inventory'
+            : 'this-deploy';
+    return { recorded, sources, source: primary };
+}
+/**
+ * Read every host rule directory in both scopes.
+ *
+ * BOTH SCOPES, BECAUSE THE HOST UNIONS THEM. A reading of the global layer
+ * alone would understate a consumer whose project carries its own rules, and
+ * the carrier's own scope filter reads the union for the same reason
+ * (`rule_layer_overlap.hostRuleLayerIds`).
+ */
+export function buildInstalledLayerReport(opts) {
+    const manifestPath = opts.manifestPath ?? null;
+    const { recorded, source: ownership_source, sources: ownership_sources } = resolveLayerOwnership({
+        manifestPath,
+        projectRoot: opts.projectRoot,
+        home: opts.home,
+        inventoryPath: opts.inventoryPath,
+    });
+    const layers = [];
+    for (const host of Object.keys(GLOBAL_RULE_DIRS).sort()) {
+        const dir = globalRuleLayerPath(host, opts.home);
+        if (dir === null)
+            continue;
+        layers.push(readLayer(host, 'global', dir, recorded));
+    }
+    for (const rel of Object.keys(PROJECT_RULE_DIRS).sort()) {
+        const host = PROJECT_RULE_DIRS[rel];
+        layers.push(readLayer(host, 'project', path.join(opts.projectRoot, rel), recorded));
+    }
+    const totals = layers.reduce((acc, l) => ({
+        files: acc.files + l.files,
+        unconditional: acc.unconditional + l.unconditional,
+        chars: acc.chars + l.chars,
+        package_owned: acc.package_owned + l.package_owned,
+        foreign: acc.foreign + l.foreign,
+        package_owned_chars: acc.package_owned_chars + l.package_owned_chars,
+        foreign_chars: acc.foreign_chars + l.foreign_chars,
+        unconditional_chars: acc.unconditional_chars + l.unconditional_chars,
+        scoped_chars: acc.scoped_chars + l.scoped_chars,
+    }), {
+        files: 0,
+        unconditional: 0,
+        chars: 0,
+        package_owned: 0,
+        foreign: 0,
+        package_owned_chars: 0,
+        foreign_chars: 0,
+        unconditional_chars: 0,
+        scoped_chars: 0,
+    });
+    const limits = buildHostLimitRows(layers, loadHostInstructionLimits(opts.hostLimitsPath ?? defaultHostLimitsPath()));
+    return {
+        home: opts.home,
+        project_root: opts.projectRoot,
+        host_version: opts.hostVersion ?? 'unknown',
+        manifest_present: manifestPath !== null && fs.existsSync(manifestPath),
+        ownership_source,
+        ownership_sources,
+        layers,
+        limits,
+        totals,
+    };
+}
+/**
+ * One line naming WHICH evidence answered ownership.
+ *
+ * Exported so the report and the install receipt say the same sentence about
+ * the same source — a consumer comparing a receipt against a later report must
+ * not have to decide whether a wording difference means a different reading.
+ */
+export function ownershipLine(sources) {
+    const list = (Array.isArray(sources) ? sources : [sources]).filter((s) => s !== 'none');
+    if (list.length === 0) {
+        return 'ownership: NO manifest and NO deploy inventory resolved — every file reads foreign, which is no evidence rather than a finding';
+    }
+    // EVERY contributor is named, never just one. The sources cover disjoint
+    // path spaces, so a line naming one of two is a true sentence about half
+    // the files and a false one about the rest.
+    const phrases = {
+        manifest: 'the installed-tools manifest',
+        'global-inventory': 'the global deploy inventory (deployed-files.json)',
+        'this-deploy': 'the file set this install just wrote',
+    };
+    const named = list.map((s) => phrases[s]);
+    const joined = named.length === 1
+        ? named[0]
+        : `${named.slice(0, -1).join(', ')} and ${named[named.length - 1]}`;
+    return `ownership: read from ${joined}`;
+}
+/** The report as lines, for a terminal. One directory per block. */
+export function renderInstalledLayerReport(report) {
+    const out = [];
+    out.push(`installed layer — host ${report.host_version}, HOME ${report.home}`);
+    out.push(`project ${report.project_root}`);
+    out.push(ownershipLine(report.ownership_sources));
+    for (const l of report.layers) {
+        if (!l.present) {
+            out.push(`  ${l.host} (${l.scope}) — absent: ${l.dir}`);
+            continue;
+        }
+        out.push(`  ${l.host} (${l.scope}) — ${String(l.files)} files ` +
+            `(${String(l.unconditional)} unconditional), ${String(l.chars)} chars ` +
+            `(${String(l.unconditional_chars)} standing + ${String(l.scoped_chars)} path-scoped), ` +
+            `${String(l.package_owned)} package-owned / ${String(l.foreign)} foreign`);
+        for (const f of l.top) {
+            out.push(`      ${String(f.chars).padStart(7)}  ${f.unconditional ? 'uncond' : 'scoped'}  ${f.file}`);
+        }
+    }
+    const t = report.totals;
+    out.push(`  TOTAL — ${String(t.files)} files (${String(t.unconditional)} unconditional), ` +
+        `${String(t.chars)} chars ` +
+        `(${String(t.unconditional_chars)} standing + ${String(t.scoped_chars)} path-scoped), ` +
+        `${String(t.package_owned)} package-owned / ${String(t.foreign)} foreign`);
+    out.push(...renderHostLimitRows(report.limits));
+    return out;
+}
+/**
+ * The budget block — one row per host, against its published limit.
+ *
+ * Extracted so the REPORT and the INSTALL RECEIPT print the same bytes. They
+ * answer the same question at two moments, and a consumer comparing a receipt
+ * against a later report must not have to decide whether a wording difference
+ * means a measurement difference.
+ */
+export function renderHostLimitRows(rows) {
+    // ONE ROW PER HOST, against its published limit — steps 1.4 and 3.5. The
+    // combined figure is what the row is about: a consumer's own instruction
+    // files sit in the same budget as this package's, so a package-owned number
+    // alone would understate what the host is actually holding.
+    const out = [
+        'host instruction budgets — package-owned + foreign against the published limit',
+    ];
+    for (const r of rows) {
+        const split = `${String(r.package_owned_chars)} package-owned + ` +
+            `${String(r.foreign_chars)} foreign = ${String(r.chars)} chars`;
+        if (r.limit === null) {
+            out.push(`  ${r.host} — ${split}; no published limit recorded — not measured`);
+            continue;
+        }
+        const pct = (r.fraction * 100).toFixed(1);
+        out.push(`  ${r.host} — ${split}; ${pct}% of ${String(r.limit)} (${r.kind})` +
+            (r.warn
+                ? ` — WARNING: at or past ${String(Math.round(LIMIT_WARN_FRACTION * 100))}% of the published limit`
+                : ''));
+    }
+    return out;
+}
+//# sourceMappingURL=installed_layer.js.map