@event4u/agent-config 14.8.0 → 14.9.0

package/src/scripts/check_pack_size.ts

@@ -28,6 +28,7 @@ import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { runSelfTest } from './_lib/gate_self_test.js';
 
 const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
 const BUDGET_PATH = path.join(REPO_ROOT, 'src', 'config', 'pack-size-budget.json');
@@ -98,6 +99,126 @@ export function skillBytes(files: readonly PackFile[]): { perSkill: Record<strin
 }
 
 /** Every violation, as human-readable lines. Empty array means green. */
+/**
+ * Content classes the published payload is checked for.
+ *
+ * The gap this closes: before it, the tarball was measured by SIZE and by build
+ * correctness, and by nothing that read what the files ARE. A payload can be
+ * comfortably under budget and still ship compiled tests, an IDE directory, or
+ * a credential-shaped file.
+ *
+ * `limit: 0` is a hard class — nothing of that shape may ship. A positive limit
+ * is a RATCHET: the number was measured, not chosen, and it may only walk down.
+ * The distinction is in `measured_in`, which every entry carries, because the
+ * same `npm pack` reports a fifth of the source maps in an unbuilt worktree as
+ * in a built one. A threshold with no stated tree reads as drift the first time
+ * someone runs it from a fresh checkout.
+ */
+interface ContentClass {
+    id: string;
+    /** Matches a payload path. */
+    match: (p: string) => boolean;
+    /** 0 = must not ship at all. > 0 = shrink-only ratchet. */
+    limit: number;
+    /** Which tree the limit was measured in, and when. */
+    measured_in: string;
+    /**
+     * True when the class only exists in a BUILT tree.
+     *
+     * This is the difference between a check and a false pass. `npm pack
+     * --dry-run --ignore-scripts` on a clean checkout — which is the condition
+     * `pack-size-budget.json` declares for its own numbers — produces no
+     * `dist/cli/**` at all, so a source-map count of 22 sails under a limit of
+     * 120 while measuring a fifth of the payload. Reported NOT MEASURABLE
+     * instead, on the same principle as the dead-scope assertion above: a check
+     * that could not run is not a clean bill.
+     */
+    requires_build: boolean;
+    why: string;
+}
+
+/**
+ * Was this payload produced from a built tree?
+ *
+ * Keyed on the payload itself rather than on the filesystem, so it describes
+ * the thing being judged instead of the machine judging it.
+ */
+function payloadIsBuilt(files: readonly PackFile[]): boolean {
+    return files.some((f) => f.path.startsWith('dist/cli/'));
+}
+
+const CONTENT_CLASSES: readonly ContentClass[] = [
+    {
+        id: 'compiled-test-artefact',
+        requires_build: true,
+        match: (p) => /\.(test|spec)\.(js|js\.map|d\.ts)$/.test(p),
+        limit: 0,
+        measured_in: 'built main checkout, 2026-08-22: 8 `.test.js` + 8 `.test.js.map` were shipping before the `files[]` negations landed',
+        why: "a compiled test's output has no consumer-facing purpose; council 2026-08-22 decision (b') strips BOTH the JS and its map, because stripping only the maps left the compiled tests themselves in the tarball",
+    },
+    {
+        id: 'credential-shaped',
+        requires_build: false,
+        match: (p) => /(^|\/)\.env(\.|$)|\.pem$|(^|\/)id_(rsa|ed25519)$|\.p12$|\.pfx$/.test(p),
+        limit: 0,
+        measured_in: 'built main checkout, 2026-08-22: 0 present',
+        why: 'a clean class with no check is indistinguishable from a class nobody looked at — and this one is worth a canary precisely because it is empty today',
+    },
+    {
+        id: 'ide-metadata',
+        requires_build: false,
+        match: (p) => /(^|\/)\.(idea|vscode)\//.test(p),
+        limit: 0,
+        measured_in: 'built main checkout, 2026-08-22: 0 present',
+        why: 'same reason as the credential class: empty and unchecked is not the same as empty and verified',
+    },
+    {
+        id: 'source-map',
+        requires_build: true,
+        match: (p) => p.endsWith('.js.map'),
+        limit: 120,
+        measured_in: 'built worktree, 2026-08-22, AFTER the compiled-test negations: 120 product maps (128 total minus 8 test maps)',
+        why: "a product source map is a consumer debugging affordance — proper line mapping and stepping over shipped JS — so council 2026-08-22 kept the 119/120 product maps and refused a blanket zero. Recorded as a PROVISIONAL measured ratchet, not an architectural constant: nothing here establishes that any consumer debugs the shipped JS, and nothing establishes they do not",
+    },
+];
+
+/**
+ * Count each content class in the payload and report over-limit classes.
+ *
+ * Returns one error string per violating class, with the offending paths — the
+ * count alone tells a reader a rule broke and not which file broke it.
+ */
+export function classifyPayload(files: readonly PackFile[]): string[] {
+    const out: string[] = [];
+    const built = payloadIsBuilt(files);
+    for (const c of CONTENT_CLASSES) {
+        if (c.requires_build && !built) continue;
+        const hits = files.filter((f) => c.match(f.path)).map((f) => f.path);
+        if (hits.length <= c.limit) continue;
+        const shown = hits.slice(0, 8);
+        out.push(
+            `content class \`${c.id}\`: ${String(hits.length)} entr${hits.length === 1 ? 'y' : 'ies'} ` +
+                `exceeds its limit of ${String(c.limit)} (measured in: ${c.measured_in}) — ` +
+                `${shown.join(', ')}${hits.length > shown.length ? `, +${String(hits.length - shown.length)} more` : ''}. ` +
+                `Why this class is checked: ${c.why}`,
+        );
+    }
+    return out;
+}
+
+/** Per-class counts, for the green-path report. */
+export function payloadClassCounts(
+    files: readonly PackFile[],
+): Array<{ id: string; count: number; limit: number; measurable: boolean }> {
+    const built = payloadIsBuilt(files);
+    return CONTENT_CLASSES.map((c) => ({
+        id: c.id,
+        count: files.filter((f) => c.match(f.path)).length,
+        limit: c.limit,
+        measurable: built || !c.requires_build,
+    }));
+}
+
 export function evaluate(budget: PackSizeBudget, pack: PackResult): string[] {
     const errors: string[] = [];
 
@@ -163,7 +284,103 @@ function readPack(argv: readonly string[]): PackResult {
     return parsePackJson(stdout);
 }
 
+/**
+ * Per-class discrimination, proven rather than asserted.
+ *
+ * WHY THIS EXISTS AND THE CANARY DOES NOT COVER IT. `gate-coverage.yml` carries
+ * `canary?: CanarySpec` — exactly ONE recipe per gate id, not a list (see
+ * `check_gate_coverage.ts`'s entry shape). The roadmap step behind this asked
+ * for "one canary per class", which the register cannot express. Two of the four
+ * classes cannot be planted through it at all: `compiled-test-artefact` is
+ * excluded from the payload by the `files[]` negations that fixed it, so a plant
+ * never ships and never reds, and `source-map` needs 121 files in a BUILT tree.
+ *
+ * So the register gets the one canary it can hold — the credential-shaped plant,
+ * chosen because that class is empty today and an empty unchecked class is
+ * indistinguishable from one nobody looked at — and every class is proven red
+ * here, over a synthetic payload, deterministically and with no pack run.
+ *
+ * A test file was the alternative and is weaker: the non-adopter ratchet in
+ * `check_gate_coverage` requires a NEW registered gate to carry a `--self-test`
+ * or an exemption, and a self-test drives the gate's own decision function
+ * rather than a copy of it.
+ */
+function packFiles(...paths: readonly string[]): PackFile[] {
+    return paths.map((path) => ({ path, size: 1 }));
+}
+
+/** A payload that looks built, so `requires_build` classes do not abstain. */
+function builtPayload(...paths: readonly string[]): PackFile[] {
+    return packFiles('dist/cli/agent-config.js', ...paths);
+}
+
+function selfTest(): number {
+    // NOT under `dist/cli/` — that prefix is exactly what `payloadIsBuilt`
+    // keys on, so maps placed there would make an "unbuilt" fixture built and
+    // the abstain case would test nothing. Found by the case failing, which is
+    // the self-test doing its job on its own fixtures.
+    const maps = (n: number): string[] =>
+        Array.from({ length: n }, (_, i) => `dist/hooks/chunk-${String(i)}.js.map`);
+    return runSelfTest({
+        gate: 'check_pack_size',
+        minCases: 9,
+        minRejectCases: 5,
+        cases: [
+            {
+                name: 'credential-shaped: a .pem in the payload is refused',
+                expect: 'reject',
+                run: () => (classifyPayload(packFiles('src/scripts/x.pem')).length > 0 ? 1 : 0),
+            },
+            {
+                name: 'credential-shaped: a dotted .env form is refused',
+                expect: 'reject',
+                run: () => (classifyPayload(packFiles('src/config/.env.production')).length > 0 ? 1 : 0),
+            },
+            {
+                name: 'ide-metadata: a .vscode entry is refused',
+                expect: 'reject',
+                run: () => (classifyPayload(packFiles('src/scripts/.vscode/settings.json')).length > 0 ? 1 : 0),
+            },
+            {
+                name: 'compiled-test-artefact: a shipped .test.js is refused',
+                expect: 'reject',
+                run: () => (classifyPayload(builtPayload('dist/cli/a.test.js')).length > 0 ? 1 : 0),
+            },
+            {
+                name: 'source-map: one over the measured ratchet is refused',
+                expect: 'reject',
+                run: () => (classifyPayload(builtPayload(...maps(121))).length > 0 ? 1 : 0),
+            },
+            {
+                name: 'source-map: the ratchet boundary itself passes',
+                expect: 'accept',
+                run: () => (classifyPayload(builtPayload(...maps(120))).length > 0 ? 1 : 0),
+            },
+            {
+                name: 'a plain payload passes — the classes are not firing on everything',
+                expect: 'accept',
+                run: () => (classifyPayload(packFiles('src/scripts/x.ts', 'README.md')).length > 0 ? 1 : 0),
+            },
+            {
+                // The false pass 1.2 closed. An unbuilt payload carries a fifth
+                // of the source maps, so a build-gated class must ABSTAIN there
+                // rather than report clean — and must not report a failure
+                // either, or every clean-checkout run would red.
+                name: 'unbuilt payload: build-gated classes abstain, not pass and not fail',
+                expect: 'accept',
+                run: () => (classifyPayload(packFiles(...maps(121))).length > 0 ? 1 : 0),
+            },
+            {
+                name: 'unbuilt payload: a build-INDEPENDENT class still fires',
+                expect: 'reject',
+                run: () => (classifyPayload(packFiles('src/scripts/id_rsa')).length > 0 ? 1 : 0),
+            },
+        ],
+    });
+}
+
 export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    if (argv.includes('--self-test')) return selfTest();
     let budget: PackSizeBudget;
     let pack: PackResult;
     try {
@@ -199,7 +416,14 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         throw err;
     }
 
-    const errors = evaluate(budget, pack);
+    // The coverage register requires an enforced gate to report what it
+    // inspected, and it is the same reason `assertScanned` runs above: a verdict
+    // with no denominator cannot be told apart from a verdict over nothing.
+    // Printed on EVERY path, including the failing one, so a reader of a red run
+    // still knows the population it was red over.
+    process.stdout.write(`scanned: ${String(pack.files.length)}\n`);
+
+    const errors = [...evaluate(budget, pack), ...classifyPayload(pack.files)];
     const { perSkill, total } = skillBytes(pack.files);
     if (argv.includes('--json')) {
         process.stdout.write(
@@ -216,6 +440,15 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
             `${Object.keys(perSkill).length} skills, largest share ` +
             `${Math.max(...Object.values(perSkill).map((b) => (b / total) * 100)).toFixed(2)}%\n`,
     );
+    // Printed on the GREEN path on purpose. A class that is clean and silent is
+    // indistinguishable from a class nobody checks, which is the whole reason
+    // two of these four are limit-0 over an empty set today.
+    for (const c of payloadClassCounts(pack.files)) {
+        const verdict = c.measurable
+            ? `${String(c.count)} / ${c.limit === 0 ? 'must be 0' : `${String(c.limit)} max`}`
+            : 'NOT MEASURABLE — this payload has no dist/cli/**, so the tree is unbuilt and the class is out of view';
+        process.stdout.write(`    content class ${c.id}: ${verdict}\n`);
+    }
     return 0;
 }
 

package/src/scripts/check_publish_surface.ts

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+/**
+ * Make a change to what ships a diff a reviewer reads.
+ *
+ * THE DEFECT. Two surfaces decide the published payload — `package.json`
+ * `files[]` and `.npmignore` — and nothing compared them or noticed when one
+ * changed. Editing what ships is legitimate; editing it invisibly is not, and a
+ * 26-root allowlist plus a 27-line ignore file is exactly the shape nobody
+ * re-reads.
+ *
+ * THE ARTEFACT IS NOT A COPY OF THE TWO FILES. Copying them would move the
+ * problem: a reviewer would still have to know which of the two wins. It
+ * records the resolved surface plus the one fact that is genuinely surprising —
+ * **`files[]` is an allowlist and it overrides `.npmignore` for anything under
+ * an included root.** That was measured, not assumed: an attempt to strip
+ * compiled test artefacts via `.npmignore` had NO effect, because `dist/` is an
+ * included root; the strip only worked as `!` negations inside `files[]`. So
+ * every `.npmignore` pattern is classified against the live payload, and a
+ * pattern the payload contradicts is reported SHADOWED rather than listed as
+ * though it were doing something.
+ *
+ * `--write` regenerates. Default checks. The check compares the artefact to the
+ * live config, so a stale artefact is the failure rather than the resting state.
+ *
+ * Exit: 0 in sync, 1 on drift, 2 on a usage error or a dead scope.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runSelfTest } from './_lib/gate_self_test.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+export const ARTEFACT = path.join(REPO_ROOT, 'src/config/publish-surface.json');
+
+export interface PublishSurface {
+    _comment: string;
+    /** Positive `files[]` entries — the allowlist roots. */
+    roots: string[];
+    /** `!`-prefixed `files[]` entries — the only way to remove from a root. */
+    negations: string[];
+    /** `.npmignore` patterns, comments and blanks dropped. */
+    npmignore: string[];
+    /**
+     * `.npmignore` patterns the live payload contradicts — the rule is present
+     * and not doing what its author expected.
+     *
+     * INFORMATIONAL, and excluded from the drift verdict. It is derived from the
+     * live payload, so it is tree-dependent in principle: a built tree ships
+     * `dist/cli/**` and an unbuilt one does not. Comparing it would make the
+     * gate red for anyone whose build state differs from whoever last
+     * regenerated the artefact — the exact false-drift shape the content-class
+     * check had to close with `measured_in`.
+     *
+     * Measured in both states on 2026-08-22 and identical (`['agents/']`), so
+     * the tolerance is not covering a known difference; it is refusing to assert
+     * one it cannot control.
+     */
+    npmignore_shadowed: string[];
+    /** Which tree the shadowed set above was measured in. */
+    shadowed_measured_in: string;
+}
+
+/** Strip comments and blanks; keep author order, because order is reviewable. */
+export function parseNpmignore(text: string): string[] {
+    return text
+        .split('\n')
+        .map((l) => l.replace(/\r$/, '').trim())
+        .filter((l) => l !== '' && !l.startsWith('#'));
+}
+
+/**
+ * Does an `.npmignore` pattern match a payload path?
+ *
+ * Deliberately a narrow subset of gitignore semantics — a leading double-star segment, a
+ * trailing `/` for a directory, and `*` inside a segment. A full matcher would
+ * be a dependency, and the classification only has to be right about the
+ * patterns this file actually uses; a pattern it cannot model is reported as
+ * not-shadowed, which is the conservative direction (it never claims a rule is
+ * inert without a payload path to prove it).
+ */
+export function npmignoreMatches(pattern: string, payloadPath: string): boolean {
+    let p = pattern;
+    const anchored = p.startsWith('/');
+    if (anchored) p = p.slice(1);
+    const dirOnly = p.endsWith('/');
+    if (dirOnly) p = p.slice(0, -1);
+    const anySegment = p.startsWith('**/');
+    if (anySegment) p = p.slice(3);
+    const rx = new RegExp(
+        `${anchored ? '^' : anySegment ? '(^|/)' : '(^|/)'}${p
+            .split('*')
+            .map((s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+            .join('[^/]*')}${dirOnly ? '/' : '($|/)'}`,
+    );
+    return rx.test(payloadPath);
+}
+
+export function packPayload(root: string): string[] {
+    const out = spawnSync('npm', ['pack', '--dry-run', '--ignore-scripts', '--json'], {
+        cwd: root,
+        encoding: 'utf-8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (out.status !== 0 || typeof out.stdout !== 'string') return [];
+    const i = out.stdout.indexOf('[');
+    if (i < 0) return [];
+    try {
+        const parsed = JSON.parse(out.stdout.slice(i)) as { files?: { path?: unknown }[] }[];
+        const files = Array.isArray(parsed[0]?.files) ? (parsed[0]?.files ?? []) : [];
+        return files.map((f) => (typeof f.path === 'string' ? f.path : '')).filter((s) => s !== '');
+    } catch {
+        return [];
+    }
+}
+
+export function buildSurface(root: string, payload: readonly string[]): PublishSurface {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8')) as {
+        files?: string[];
+    };
+    const entries = pkg.files ?? [];
+    const ignPath = path.join(root, '.npmignore');
+    const npmignore = fs.existsSync(ignPath) ? parseNpmignore(fs.readFileSync(ignPath, 'utf-8')) : [];
+    const shadowed = npmignore.filter((pat) => payload.some((p) => npmignoreMatches(pat, p)));
+    return {
+        _comment:
+            'GENERATED by src/scripts/check_publish_surface.ts --write. Do not hand-edit. ' +
+            'It records the resolved publish surface so a change to what ships is a diff a reviewer reads. ' +
+            '`files[]` is an ALLOWLIST and it overrides .npmignore for anything under an included root — ' +
+            'measured, after an attempt to strip compiled test artefacts via .npmignore had no effect because ' +
+            'dist/ is an included root. That is why `negations` exists and why `npmignore_shadowed` is reported: ' +
+            'a pattern the live payload contradicts is present and not doing what its author expected.',
+        roots: entries.filter((e) => !e.startsWith('!')),
+        negations: entries.filter((e) => e.startsWith('!')),
+        npmignore,
+        npmignore_shadowed: shadowed,
+        shadowed_measured_in:
+            payload.some((p) => p.startsWith('dist/cli/'))
+                ? 'built tree (payload carries dist/cli/**)'
+                : 'unbuilt tree (payload carries no dist/cli/**)',
+    };
+}
+
+/**
+ * The fields the drift verdict compares — everything read from a FILE, nothing
+ * derived from the payload. See `npmignore_shadowed`.
+ */
+export function driftKey(s: PublishSurface): string {
+    return `${JSON.stringify({ roots: s.roots, negations: s.negations, npmignore: s.npmignore }, null, 2)}\n`;
+}
+
+function render(s: PublishSurface): string {
+    return `${JSON.stringify(s, null, 2)}\n`;
+}
+
+function selfTest(): number {
+    return runSelfTest({
+        gate: 'check_publish_surface',
+        minCases: 7,
+        minRejectCases: 4,
+        cases: [
+            {
+                name: 'a directory pattern matches a path under it',
+                expect: 'reject',
+                run: () => (npmignoreMatches('agents/', 'agents/roadmaps/x.md') ? 1 : 0),
+            },
+            {
+                name: 'a double-star-prefixed pattern matches at any depth',
+                expect: 'reject',
+                run: () => (npmignoreMatches('**/*.pyc', 'src/a/b/c.pyc') ? 1 : 0),
+            },
+            {
+                name: 'a bare filename matches at any depth',
+                expect: 'reject',
+                run: () => (npmignoreMatches('.DS_Store', 'docs/.DS_Store') ? 1 : 0),
+            },
+            {
+                name: 'a `*` glob stays within one segment',
+                expect: 'reject',
+                run: () => (npmignoreMatches('*.swp', 'a.swp') ? 1 : 0),
+            },
+            {
+                // The counter-test: a segment glob must NOT cross a slash, or
+                // every pattern would match everything and the whole
+                // shadowed-set would be noise.
+                //
+                // The first version of this case asserted that `*.swp` does not
+                // match `a.swp/b.txt` — which is wrong, and the self-test caught
+                // it: gitignore semantics say `*.swp` matches a DIRECTORY of
+                // that name and everything under it, so the matcher was right
+                // and the fixture was not. `a*b` vs `a/x/b` tests the property
+                // the case was reaching for without the ambiguity.
+                name: 'a `*` glob does not cross a slash',
+                expect: 'accept',
+                run: () => (npmignoreMatches('a*b', 'a/x/b') ? 1 : 0),
+            },
+            {
+                name: 'a directory pattern does not match a same-named file',
+                expect: 'accept',
+                run: () => (npmignoreMatches('vendor/', 'vendor') ? 1 : 0),
+            },
+            {
+                name: 'an unrelated pattern matches nothing',
+                expect: 'accept',
+                run: () => (npmignoreMatches('composer.lock', 'src/scripts/x.ts') ? 1 : 0),
+            },
+            {
+                // Drift detection itself: the shadowed set must react to the
+                // payload, not just to the file. A pattern with no payload
+                // match is not shadowed.
+                name: 'shadowed is computed against the payload, not asserted',
+                expect: 'reject',
+                run: () => {
+                    const withHit = buildSurfaceFrom(['agents/'], ['agents/x.md']);
+                    const without = buildSurfaceFrom(['agents/'], ['src/x.ts']);
+                    return withHit.length === 1 && without.length === 0 ? 1 : 0;
+                },
+            },
+        ],
+    });
+}
+
+/** Test seam: the shadowed computation alone, with no filesystem. */
+export function buildSurfaceFrom(npmignore: readonly string[], payload: readonly string[]): string[] {
+    return npmignore.filter((pat) => payload.some((p) => npmignoreMatches(pat, p)));
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    if (argv.includes('--self-test')) return selfTest();
+    const payload = packPayload(REPO_ROOT);
+    try {
+        assertScanned({
+            gate: 'check_publish_surface',
+            scanned: payload.length,
+            units: 'packed file(s)',
+            roots: ['npm pack --dry-run --ignore-scripts payload (package.json files[])'],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  publish surface: ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+    process.stdout.write(`scanned: ${String(payload.length)}\n`);
+    const live = render(buildSurface(REPO_ROOT, payload));
+    if (argv.includes('--write')) {
+        fs.writeFileSync(ARTEFACT, live);
+        process.stdout.write(`✅  publish surface written to ${path.relative(REPO_ROOT, ARTEFACT)}\n`);
+        return 0;
+    }
+    if (!fs.existsSync(ARTEFACT)) {
+        process.stderr.write(
+            `❌  publish surface: ${path.relative(REPO_ROOT, ARTEFACT)} is missing — run with --write\n`,
+        );
+        return 1;
+    }
+    const committed = fs.readFileSync(ARTEFACT, 'utf-8');
+    let committedKey: string;
+    try {
+        committedKey = driftKey(JSON.parse(committed) as PublishSurface);
+    } catch {
+        process.stderr.write(`❌  publish surface: ${path.relative(REPO_ROOT, ARTEFACT)} is not valid JSON\n`);
+        return 1;
+    }
+    if (committedKey === driftKey(buildSurface(REPO_ROOT, payload))) {
+        if (committed !== live) {
+            // The tree-independent surface matches; only the payload-derived
+            // shadowed set differs, which a different build state explains.
+            // Said out loud rather than swallowed: a silent difference between
+            // the committed artefact and the live one is the thing this gate
+            // exists to make visible, even when it is not a failure.
+            process.stdout.write(
+                '⚠️  publish surface: files[] and .npmignore match, but the payload-derived\n' +
+                    '    shadowed set differs — a different build state, not drift in what ships.\n' +
+                    '    Regenerate with --write if you want the artefact to record THIS tree.\n',
+            );
+        }
+        process.stdout.write('✅  publish surface in sync with package.json files[] + .npmignore.\n');
+        return 0;
+    }
+    process.stderr.write(
+        '❌  publish surface drifted: what ships changed and the committed artefact did not.\n' +
+            '    Changing what ships is legitimate; changing it without the artefact moving is the defect,\n' +
+            '    because the change is then invisible in review. Run:\n' +
+            '      ./scripts-run src/scripts/check_publish_surface --write\n' +
+            '    and commit the diff alongside the package.json / .npmignore edit that caused it.\n',
+    );
+    return 1;
+}
+
+if (process.argv[1] !== undefined && process.argv[1].includes('check_publish_surface')) {
+    process.exit(main(process.argv.slice(2)));
+}