@xemahq/repo-build-tooling 0.1.0

package/LICENSE

@@ -0,0 +1,176 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,75 @@
+# `@xemahq/repo-build-tooling`
+
+This package belongs to Layer 1 — dev-time build tooling shared by every Xema
+repository. Nothing here ever ships inside a service image; every consumer
+declares it as a `devDependency`.
+
+## Why it is a package and not a file
+
+It used to be a file — five byte-identical copies of one 700-line script, one
+per repository that needed it, kept honest by a boundary check that ran each
+copy's `--self-test`.
+
+That arrangement could not hold the invariant it existed for. A defect found in
+one copy is fixed in one copy; the other four keep shipping it until someone
+remembers. Exactly that happened: three of the five copies deliberately carried
+*less* behaviour than the other two (they detected a leak shape without
+rewriting it), which was a reasonable decision at the time and then became a
+permanent, undocumented divergence nobody re-examined. A parity check on N
+copies is a workaround for not having one artifact.
+
+## How the two resolution modes work
+
+This is the standard shape in this fleet, and getting it wrong is the single
+most common source of "green locally, red in CI":
+
+- **Inside the `xema-monorepo` aggregator**, the root `package.json`'s
+  `pnpm.overrides` maps `@xemahq/repo-build-tooling` to `workspace:*`, so it
+  resolves to this directory. Editing the tool and rebuilding a service in the
+  same checkout needs no publish, no version bump and no registry round-trip.
+- **Inside each independent repository's own CI**, there is no aggregator and no
+  sibling checkout. The declared semver range is what resolves, from npm.
+
+So the range in a consumer's `package.json` is the real contract, and the local
+link is a development convenience layered on top. A symbol added here is not
+available to a consumer until this package is published AND that consumer's
+range admits the new version — the aggregator will happily compile against the
+local source and tell you nothing.
+
+## Contents
+
+### `xema-scrub-swagger-paths <dist-dir> [<dist-dir>…]`
+
+Post-build sanitizer for `@nestjs/swagger` plugin output, and the verification
+step for the same property. The plugin writes `require()` literals into
+`_OPENAPI_METADATA_FACTORY()` at `nest build` time — they exist in no source
+file — so this is the only thing in the fleet that can see them, and it runs
+immediately after `nest build` in all 54 services that use the plugin.
+
+It rewrites specifiers that name the builder's private install layout into the
+target package's public specifier, then re-reads the output from disk and fails
+the build if any leak survives.
+
+The rewrite is **derived and proved**, never tabled: the replacement comes from
+the target package's own `exports` map, and is accepted only if the emitted
+re-export chain (read statically — package code is never executed) reaches the
+same module. It refuses rather than guesses. That matters because the two
+packages that leak most are opposites — `@xemahq/kernel-contracts` exports only
+`./*` and has no root export, so rewriting to the bare name would swap one crash
+for another, while `@xemahq/platform-common` exports both `.` and `./dist/*`.
+
+`--self-test` proves, on a scratch tree with no build and no fixtures, that a
+missing/empty/no-`.js` directory each FAIL, that the detector matches every leak
+shape and no clean literal, and that a residual leak fails the run. This step's
+failure mode is silence, so "0 leaks" and "0 files read" must never be
+indistinguishable.
+
+## Scope boundary
+
+Dev-time tooling that **more than one repository** runs. Two rules keep it from
+becoming a junk drawer:
+
+- Nothing with a runtime consumer. If a service imports it at run time it is not
+  build tooling and belongs in an SDK package.
+- Nothing with a single consumer. A tool used by one repository stays in that
+  repository until a second one needs it.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@xemahq/repo-build-tooling",
+  "version": "0.1.0",
+  "description": "Dev-time build tooling shared by every Xema repository. Ships as plain ESM with zero dependencies so the published artifact is the reviewed source.",
+  "license": "Apache-2.0",
+  "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
+  "homepage": "https://xema.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xema-dev/xema-runtime-core.git",
+    "directory": "packages/sdks/repo-build-tooling"
+  },
+  "bugs": "https://github.com/xema-dev/xema-runtime-core/issues",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "bin": {
+    "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs"
+  },
+  "exports": {
+    "./scrub-swagger-plugin-paths": "./src/scrub-swagger-plugin-paths.mjs",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test"
+  }
+}

package/src/scrub-swagger-plugin-paths.mjs

@@ -0,0 +1,721 @@
+#!/usr/bin/env node
+// =============================================================================
+// scrub-swagger-plugin-paths.mjs
+//
+// Post-build sanitizer for @nestjs/swagger plugin v11.x output.
+//
+// CONTEXT
+//   The swagger CLI plugin emits `_OPENAPI_METADATA_FACTORY()` blocks that
+//   contain `require("<path>")` calls for any enum referenced via
+//   `@ApiProperty({ enum: ... })`. The plugin derives the path from
+//   TypeScript's resolved declaration file location and trims at the FIRST
+//   `node_modules/` segment in the relative path
+//   (see `node_modules/@nestjs/swagger/dist/plugin/utils/plugin-utils.js`
+//   around the `nodeModulesText` slice).
+//
+//   This produces two leak shapes, both fatal at pod boot:
+//
+//   (1) NESTED leak — pnpm's nested layout. When a service builds a DTO
+//       that references an enum reached via a transitive contract package,
+//       TypeScript can resolve the type via a nested symlink such as:
+//
+//         node_modules/@xemahq/kernel-contracts/policy/node_modules/
+//           @xemahq/kernel-contracts/execution-context/dist/lib/subject.d.ts
+//
+//       The first `node_modules/` slice trims off the outermost
+//       `node_modules/` but leaves the SECOND one inside the path,
+//       producing leaked emits like:
+//
+//         require("@xemahq/kernel-contracts/policy/node_modules/
+//                 @xemahq/kernel-contracts/execution-context/dist/lib/subject")
+//
+//       …which crashes the pod at boot with ERR_PACKAGE_PATH_NOT_EXPORTED
+//       because `policy-contracts`' `exports` field correctly does not
+//       (and should not) cover `./node_modules/*`.
+//
+//   (2) FLAT leak — direct dependency, deep dist subpath. When a service
+//       directly depends on a contracts package and references an enum
+//       via `@ApiProperty({ enum: ... })`, the plugin emits the
+//       declaration file path under the package's published layout:
+//
+//         require("@xemahq/kernel-contracts/capability/dist/lib/capability-grant")
+//
+//       This crashes at boot with the same ERR_PACKAGE_PATH_NOT_EXPORTED
+//       whenever the contracts package's published `exports` map does NOT
+//       expose `./dist/lib/*` (the kernel-leaf packages publish with a
+//       single `.` entry only — the deep subpath is an internal layout
+//       detail, not a public contract).
+//
+// FIX
+//   This script walks each `dist/**/*.js` under a service's build output
+//   and rewrites ALL THREE leak shapes to the canonical bare package specifier:
+//
+//     require("@xemahq/<outer>/node_modules/@xemahq/<inner>/<rest>")
+//       → require("@xemahq/<inner>/<rest>")
+//     require("@xemahq/<pkg>/dist/lib/<file>")
+//       → require("@xemahq/<pkg>")
+//     require("../../packages/contracts/<pkg>/dist/<subpath>/<file>")
+//       → require("@xemahq/<pkg>/<subpath>")
+//
+//   The nested case keeps the inner subpath because the inner package's
+//   `exports` covers `./dist/*` (the leak was caused by the OUTER package's
+//   exports). The flat case drops the subpath because the contracts
+//   package's root `exports` always re-exports every public symbol from
+//   `dist/index.js`; the enum that the plugin needed is available on the
+//   bare module. The relative workspace case reconstructs the canonical
+//   subpath specifier: the last directory before `/dist/` is the package
+//   name (maps to `@xemahq/<name>`); the first directory after `/dist/` is
+//   the subpath export (valid for packages using `./*` exports, e.g.
+//   community-contracts).  The rewrite is structurally safe — the bare
+//   specifier is what the plugin would have emitted under a "flat resolution"
+//   model.
+//
+//   The complementary `tsconfig` `paths` pin (PR #47) covers the same root
+//   cause at TypeScript resolution time; this scrubber is the structural
+//   safety net that protects every current AND future app from the same
+//   regression without per-app config maintenance.
+//
+// USAGE
+//   node tooling/codegen/scrub-swagger-plugin-paths.mjs <dist-dir> [<dist-dir>…]
+//   node tooling/codegen/scrub-swagger-plugin-paths.mjs --self-test
+//
+//   Each <dist-dir> is scanned recursively. The script is idempotent —
+//   running it twice on the same tree is a no-op. It exits 0 on success
+//   even when no rewrites are needed (a service may not import any
+//   contract enum). It exits 1 if a directory does not exist or a file
+//   cannot be read/written — fail fast, never silent.
+//
+// ── THIS STEP IS ALSO THE VERIFICATION (2026-08-06) ───────────────────────
+//   This script is not only a rewriter; it is the ONLY thing in the fleet that
+//   reads a service's compiled output at the moment it is produced. The leak
+//   literal exists in NO source file — the swagger plugin writes it into
+//   `_OPENAPI_METADATA_FACTORY()` at `nest build` time — so a check that wants
+//   to read it needs a built tree, and the aggregator's buildless boundary gate
+//   can never have one. `tooling/boundaries/check-no-deep-require-leaks.mjs`
+//   spent its whole life in that gate reporting a confident green over ZERO of
+//   its 53 subject packages.
+//
+//   The subject set is exactly "every package whose build chains this script"
+//   (CI-enforced by `check-swagger-plugin-scrub-wired.mjs`), and this script
+//   runs immediately after `nest build` in all 53 of them — in the carved
+//   repos' own CI (`pnpm -r --if-present run build`), inside every service
+//   image build, and locally. So the verification belongs HERE, where the
+//   build output exists, not in a gate that cannot build. Two properties make
+//   it able to fail:
+//
+//     1. A named directory that does not exist, is not a directory, or holds
+//        NO compiled `.js` is a hard error. It used to be a silent no-op
+//        ("a service may not have a dist/ yet") — which meant a service whose
+//        `outDir` moved kept a green scrub step over nothing at all. No caller
+//        invokes this before `tsc`: every one of the 53 build scripts is
+//        `nest build && node …/scrub-swagger-plugin-paths.mjs dist`.
+//     2. After rewriting, the output is RE-READ FROM DISK and asserted clean
+//        against the detector set below. The detectors are deliberately NOT
+//        the rewrite regexes: a single `String.replace` pass cannot fix a
+//        DOUBLY-nested literal (`@xemahq/a/node_modules/@xemahq/b/node_modules/
+//        @xemahq/c/x` rewrites to a literal that is still a leak), and this
+//        repo's copies of this file do not all rewrite the same shapes. A
+//        residual leak now fails the build that produced it instead of
+//        shipping into an image that crashes at boot with
+//        ERR_PACKAGE_PATH_NOT_EXPORTED.
+//
+//   `--self-test` re-proves both properties on a scratch tree, with no build
+//   and no fixtures on disk, for the usual reason: this step's failure mode is
+//   silence, so "0 leaks" and "0 files read" must never be indistinguishable.
+//   The boundary gate runs it for EVERY copy of this file in the tree
+//   (`check-swagger-plugin-scrub-wired.mjs`), which is what keeps the carved
+//   duplicates from drifting back into inertness.
+// =============================================================================
+
+import { createRequire } from 'node:module';
+import { readFileSync, realpathSync } from 'node:fs';
+import { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import process from 'node:process';
+
+// Matches the two known leak shapes. We intentionally scope to `@xemahq`
+// because:
+//   (1) every leak we have seen comes from a workspace contracts package
+//       (always `@xemahq/*`); third-party leaks would be an unrelated bug
+//       in a third-party package we cannot rewrite blindly;
+//   (2) scoping the match keeps the rewrite reversible and auditable.
+// If a future leak appears under another scope (e.g. `@xema-platform`),
+// extend the alternation rather than dropping the scope guard.
+const SCOPE_PATTERN = '@xemahq';
+
+// Shape 1 — NESTED: `require("@xemahq/<outer>/node_modules/@xemahq/<inner>/<rest>")`
+// Capture group 1: inner package + subpath we want to keep.
+const NESTED_LEAK_REGEX = new RegExp(
+  `require\\("${SCOPE_PATTERN}\\/[a-z0-9-]+\\/node_modules\\/(${SCOPE_PATTERN}\\/[a-z0-9-]+(?:\\/[^"]+)?)"\\)`,
+  'g',
+);
+
+// Shape 2 — FLAT: `require("@xemahq/<pkg>/dist/<rest>")`
+// Capture group 1: package name. We drop the `/dist/<rest>` tail because the
+// package's root `exports` re-exports every public symbol; the enum the
+// swagger plugin needed is available on the bare specifier.
+const FLAT_LEAK_REGEX = new RegExp(
+  `require\\("(${SCOPE_PATTERN}\\/[a-z0-9-]+)\\/dist\\/[^"]+"\\)`,
+  'g',
+);
+
+// Shape 3 — RELATIVE WORKSPACE: `require("../../packages/<tier>/<pkg>/dist/<subpath>/<rest>")`
+// TypeScript (with default preserveSymlinks:false) follows pnpm workspace
+// symlinks to their physical location.  The NestJS Swagger plugin then emits
+// a relative path from the service source file back up to the workspace root
+// and down into the contracts package.  There is no `node_modules/` segment
+// so shapes 1 and 2 above never fire.
+// Capture group 1: package directory name (= npm name without @xemahq/ scope).
+// Capture group 2: first path segment after dist/ = the subpath export name.
+// Scoped to paths that pass through `packages/`, `biomes/`, or `kernel/` to
+// avoid false-positive matches on intra-service relative requires.
+const RELATIVE_WORKSPACE_REGEX = new RegExp(
+  `require\\("(?:\\.\\./)+(?:packages|biomes|kernel)/(?:[a-z0-9][a-z0-9.-]*/)*([a-z0-9][a-z0-9.-]*)/dist/([a-z0-9][a-z0-9-]*)(?:/[^"]*)?"\\)`,
+  'g',
+);
+
+// Shape 4 — PNPM VIRTUAL STORE:
+//   `require(".pnpm/<pkg>@<ver>_<peer-hash>/node_modules/@xemahq/<pkg>/dist/<rest>")`
+//
+// This one shipped undetected in 25 services (387 literals) because the
+// detector set below was, until now, the union of the REWRITE shapes — so a
+// shape nothing rewrote was also a shape nothing could see, and the scrub step
+// reported success on every build.
+//
+// It is a genuine runtime hazard, not a cosmetic path. The specifier does not
+// begin with `./`, so Node treats `.pnpm` as a package name and finds it only
+// because `node_modules/.pnpm` happens to exist in the BUILDER's layout. The
+// directory name embeds a content hash of the peer-resolution key, and
+// `pnpm deploy --prod` (what the runtime stage copies) re-resolves that graph
+// with devDependencies pruned. A hash computed from the unpruned graph need not
+// exist in the pruned one.
+//
+// Capture group 1: package name. Group 2: subpath INSIDE the package.
+const PNPM_STORE_LEAK_REGEX = new RegExp(
+  `require\\("\\.pnpm\\/[^"]*?\\/node_modules\\/(${SCOPE_PATTERN}\\/[a-z0-9.-]+)\\/([^"]+)"\\)`,
+  'g',
+);
+
+// ── DETECTORS (verification only — never used to rewrite) ────────────────────
+// The union of every leak shape any copy of this script rewrites, kept
+// SEPARATE from the rewrite regexes above on purpose. A net whose pattern is
+// the rewriter's pattern can only ever report what the rewriter already fixed;
+// these are what the post-scrub re-read asserts against, so they must be able
+// to match something the rewrite pass leaves behind:
+//
+//   • NESTED / FLAT — a single `String.replace` pass does not re-scan its own
+//     replacement, so a doubly-nested literal survives the rewrite as a
+//     still-leaking single-nested one. That is the shape `--self-test` plants.
+//   • RELATIVE-WORKSPACE — emitted when TypeScript resolves a workspace
+//     contracts package through its physical path rather than through
+//     `node_modules`, so neither shape above fires. Only the `xema-base` /
+//     `xema-community` copies of this file REWRITE it; every copy DETECTS it,
+//     so a repo that has not audited the rewrite fails loudly instead of
+//     silently shipping a require that cannot resolve inside the image.
+//
+// Mirrors `tooling/boundaries/check-no-deep-require-leaks.mjs` — if you change
+// one, change both.
+const LEAK_DETECTORS = [
+  // STRUCTURAL, and deliberately not a mirror of any rewrite regex above.
+  //
+  // The property is objective and shape-free: a require specifier in built
+  // output may name a package, or a path relative to the emitting file. It may
+  // NOT name a segment of the builder's install layout — `node_modules/`
+  // anywhere, or the pnpm virtual store `.pnpm/` — because that layout is a
+  // private implementation detail of the machine that compiled the file and is
+  // re-computed, differently, in the image that runs it.
+  //
+  // The previous `nested` detector was the nested REWRITER's own pattern with
+  // its capture group removed. That is why shape 4 (`.pnpm/…`) shipped in 25
+  // services with the scrub step green on every build: nothing rewrote it, so
+  // by construction nothing detected it. This one subsumes `nested` and every
+  // future variant of the same class, including packages outside `@xemahq`.
+  [
+    'install-layout',
+    /require\("(?:[^"]*\/)?node_modules\/[^"]+"\)|require\("\.pnpm\/[^"]+"\)/g,
+  ],
+  ['flat', new RegExp(`require\\("${SCOPE_PATTERN}\\/[a-z0-9-]+\\/dist\\/[^"]+"\\)`, 'g')],
+  [
+    'relative-workspace',
+    /require\("(?:\.\.\/)+(?:packages|biomes|kernel)\/(?:[a-z0-9][a-z0-9.-]*\/)*[a-z0-9][a-z0-9.-]*\/dist\/[a-z0-9][a-z0-9-]*(?:\/[^"]*)?"\)/g,
+  ],
+];
+
+/** Every leak literal in `content`, de-duplicated, tagged with its shape. */
+function findLeaks(content) {
+  const found = [];
+  for (const [shape, regex] of LEAK_DETECTORS) {
+    const matches = content.match(regex);
+    if (!matches) continue;
+    for (const literal of new Set(matches)) found.push({ shape, literal });
+  }
+  return found;
+}
+
+/** Thrown for every fail-fast condition so `--self-test` can assert on it. */
+class ScrubFailure extends Error {}
+
+// ── Public specifier for a physical subpath (shape 4) ────────────────────────
+//
+// The other three shapes can hardcode their replacement because every package
+// they have ever matched exposes a root export. Shape 4 cannot: the two
+// packages it leaks most are opposites.
+//
+//   @xemahq/kernel-contracts  exports ONLY `./*` -> `./dist/*/index.js`.
+//     It has NO root export, so rewriting to the bare name produces a
+//     specifier that cannot resolve — a fix that swaps one crash for another.
+//     Its public form is `@xemahq/kernel-contracts/<first segment after dist>`.
+//
+//   @xemahq/platform-common   exports `.` AND `./dist/*`.
+//     Its public form is the bare name.
+//
+// So the replacement is DERIVED from the target package's own `exports` map,
+// not from a table here — a table would need an entry per package and would be
+// wrong the first time a package changed its export style. Whatever it derives
+// is then PROVED: both the original and the candidate are resolved, and the
+// rewrite only happens if they name the same physical file. A rewrite that
+// cannot be proved is refused rather than guessed.
+const specifierCache = new Map();
+
+/**
+ * Is `target` reachable from `entry` by following emitted re-exports?
+ *
+ * `tsc` compiles `export * from './lib/x'` to `__exportStar(require("./lib/x"),
+ * exports)`, so a barrel's re-export graph is legible in the emitted JS. This
+ * walks it with a visited set (barrels do form cycles) and a depth bound, and
+ * reads only relative requires — a re-export that leaves the package cannot
+ * make a symbol of THIS package public.
+ *
+ * Static on purpose. The alternative — importing both modules and diffing
+ * their export keys — would prove the same thing while executing arbitrary
+ * package code inside a build step.
+ */
+function reExportsReach(entry, target, depth = 6, seen = new Set()) {
+  if (entry === target) return true;
+  if (depth === 0 || seen.has(entry)) return false;
+  seen.add(entry);
+
+  let src;
+  try {
+    src = readFileSync(entry, 'utf8');
+  } catch {
+    return false;
+  }
+  const dir = dirname(entry);
+  for (const m of src.matchAll(/require\("(\.[^"]*)"\)/g)) {
+    let next;
+    try {
+      next = realpathSync(createRequire(entry).resolve(m[1]));
+    } catch {
+      continue;
+    }
+    if (reExportsReach(next, target, depth - 1, seen)) return true;
+  }
+  return false;
+}
+
+/**
+ * @param {(spec: string) => string} resolveFrom  resolver bound to the file being scrubbed
+ * @param {string} pkg      e.g. `@xemahq/kernel-contracts`
+ * @param {string} subpath  physical path inside the package, e.g. `dist/agent-composition/lib/x`
+ * @param {string} original the full leaked specifier, for the proof and the error
+ */
+function publicSpecifierFor(resolveFrom, pkg, subpath, original) {
+  const cacheKey = `${pkg}${subpath}`;
+  if (specifierCache.has(cacheKey)) return specifierCache.get(cacheKey);
+
+  let target;
+  try {
+    target = resolveFrom(original);
+  } catch (err) {
+    throw new ScrubFailure(
+      `cannot resolve the leaked specifier, so no rewrite can be proved correct:\n` +
+        `  ${original}\n  ${err.message}\n` +
+        `  Refusing to guess a replacement.`,
+    );
+  }
+
+  // Read the manifest off DISK by walking up from the resolved module, not
+  // through `resolveFrom(`${pkg}/package.json`)`. A well-formed `exports` map
+  // is entitled to omit `./package.json` — `@xemahq/entitlement-client` does —
+  // and resolving through it would make this step fail on exactly the packages
+  // whose export maps are strictest.
+  let exportsMap;
+  {
+    let dir = dirname(target);
+    let manifest = null;
+    for (let i = 0; i < 12 && dir !== dirname(dir); i += 1) {
+      try {
+        const candidate = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        if (candidate.name === pkg) {
+          manifest = candidate;
+          break;
+        }
+      } catch {
+        /* keep walking */
+      }
+      dir = dirname(dir);
+    }
+    if (!manifest) {
+      throw new ScrubFailure(
+        `cannot locate the package manifest of ${pkg} above its resolved module, so no\n` +
+          `  public specifier can be derived for\n  ${original}`,
+      );
+    }
+    exportsMap = manifest.exports ?? {};
+    // A package with no `exports` map has no subpath restrictions at all: its
+    // `main` is the public entry and every file is reachable. Bare is correct.
+    if (Object.keys(exportsMap).length === 0) exportsMap = { '.': manifest.main ?? 'index.js' };
+  }
+
+  // Candidates, most specific first. Every one is verified below; the order
+  // only decides which correct answer is preferred.
+  const afterDist = subpath.replace(/^dist\//, '').split('/')[0];
+  const candidates = [];
+  if (exportsMap['./*'] && afterDist) candidates.push(`${pkg}/${afterDist}`);
+  if (exportsMap['.']) candidates.push(pkg);
+  if (exportsMap['./dist/*'] || exportsMap['./dist/lib/*']) candidates.push(`${pkg}/${subpath}`);
+
+  for (const candidate of candidates) {
+    let resolved;
+    try {
+      resolved = resolveFrom(candidate);
+    } catch {
+      continue; // not admitted by the exports map after all
+    }
+    // Same file is the easy case. The common case is not that: a package's
+    // public entry is a BARREL that re-exports the leaked module, so the two
+    // are different files and the symbols are nonetheless there. Demanding
+    // file equality would refuse every correct rewrite for a barrelled package
+    // (it refused all 333 kernel-contracts leaks). Proving reachability
+    // through the re-export chain is the assertion that actually matters, and
+    // it is done by READING the emitted barrels — never by executing them, so
+    // a build step cannot be made to run package code.
+    if (resolved === target || reExportsReach(resolved, target)) {
+      specifierCache.set(cacheKey, candidate);
+      return candidate;
+    }
+  }
+
+  throw new ScrubFailure(
+    `no public specifier of ${pkg} resolves to the same file as\n` +
+      `  ${original}\n` +
+      `  tried: ${candidates.length > 0 ? candidates.join(', ') : '(none — the exports map admits no matching form)'}\n` +
+      `  Add the needed entry to that package's "exports", or export the symbol from a\n` +
+      `  path that is public. Rewriting to a specifier that resolves elsewhere would\n` +
+      `  substitute a different module at runtime, which is worse than the leak.`,
+  );
+}
+
+async function* walk(dir) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return;
+    }
+    throw err;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      // Skip nested node_modules — those are NOT our build output.
+      if (entry.name === 'node_modules') continue;
+      yield* walk(full);
+    } else if (entry.isFile() && entry.name.endsWith('.js')) {
+      yield full;
+    }
+  }
+}
+
+async function scrubFile(path) {
+  const src = await readFile(path, 'utf8');
+  let count = 0;
+  // Resolution is anchored at the file being rewritten, so a package resolves
+  // exactly as it will at runtime from that file — not as it happens to
+  // resolve from this script's own location.
+  const requireFrom = createRequire(path);
+  const resolveFrom = (spec) => realpathSync(requireFrom.resolve(spec));
+
+  let out = src.replace(PNPM_STORE_LEAK_REGEX, (match, pkg, subpath) => {
+    count += 1;
+    return `require("${publicSpecifierFor(resolveFrom, pkg, subpath, match.slice('require("'.length, -2))}")`;
+  });
+  out = out.replace(NESTED_LEAK_REGEX, (_match, kept) => {
+    count += 1;
+    return `require("${kept}")`;
+  });
+  out = out.replace(FLAT_LEAK_REGEX, (_match, pkg) => {
+    count += 1;
+    return `require("${pkg}")`;
+  });
+  out = out.replace(RELATIVE_WORKSPACE_REGEX, (_match, pkgName, subpath) => {
+    count += 1;
+    return `require("@xemahq/${pkgName}/${subpath}")`;
+  });
+  if (count > 0) {
+    await writeFile(path, out, 'utf8');
+  }
+  return count;
+}
+
+/**
+ * A named output directory must exist, be a directory, and hold at least one
+ * compiled `.js`. Anything else is a hard failure.
+ *
+ * This used to return `false` on ENOENT and be skipped, "so the build step
+ * composes cleanly when invoked before `tsc`". No caller does that — every
+ * subject's build script is `nest build && node …/scrub-swagger-plugin-paths.mjs
+ * dist` — and the lenient branch meant a service whose `outDir` moved kept a
+ * green scrub step over an empty scan. This step is a verification step; a
+ * verification that scanned nothing must never report success.
+ */
+async function assertScannable(dir) {
+  let s;
+  try {
+    s = await stat(dir);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new ScrubFailure(
+        `output directory does not exist: ${dir}\n` +
+          `  This script runs AFTER \`nest build\`, so the directory it is handed must hold that\n` +
+          `  build's output. A missing path means the argument disagrees with the service's\n` +
+          `  tsconfig \`outDir\` — which would leave the swagger-plugin path leak unscrubbed AND\n` +
+          `  unverified in the bytes that actually ship.`,
+      );
+    }
+    throw err;
+  }
+  if (!s.isDirectory()) throw new ScrubFailure(`not a directory: ${dir}`);
+
+  for await (const _file of walk(dir)) return; // eslint-disable-line no-unused-vars
+  throw new ScrubFailure(
+    `output directory holds no compiled .js: ${dir}\n` +
+      `  Same failure as a missing directory: nothing was scrubbed and nothing was verified.`,
+  );
+}
+
+/**
+ * Re-read the written tree and assert no leak literal survived the rewrite.
+ * Reads from DISK rather than trusting the in-memory rewrite result, so a
+ * write that did not land is caught too.
+ */
+async function verifyDirs(dirs) {
+  const residual = [];
+  for (const dir of dirs) {
+    for await (const file of walk(dir)) {
+      const leaks = findLeaks(await readFile(file, 'utf8'));
+      if (leaks.length > 0) residual.push({ file, leaks });
+    }
+  }
+  return residual;
+}
+
+/** Scrub + verify. Throws `ScrubFailure` on any fail-fast condition. */
+async function run(args) {
+  const dirs = args.map((a) => resolve(a));
+  for (const dir of dirs) await assertScannable(dir);
+
+  let totalFiles = 0;
+  let totalRewrites = 0;
+  const touched = [];
+
+  for (const dir of dirs) {
+    for await (const file of walk(dir)) {
+      totalFiles += 1;
+      const count = await scrubFile(file);
+      if (count > 0) {
+        totalRewrites += count;
+        touched.push({ file, count });
+      }
+    }
+  }
+
+  const residual = await verifyDirs(dirs);
+  if (residual.length > 0) {
+    const lines = [
+      `${residual.length} file(s) still contain a leaked require() literal AFTER scrubbing.`,
+      '',
+      'Each one crashes the pod at boot with ERR_PACKAGE_PATH_NOT_EXPORTED, because the',
+      "outer package's exports field correctly does not cover the leaked subpath. The",
+      'rewrite pass could not repair these, so the build that produced them fails here',
+      'rather than shipping them into an image.',
+      '',
+      'Fix:',
+      '  1. Pin the enum in the service tsconfig `paths` so TypeScript resolves it flat.',
+      '  2. If the shape is new, extend the rewrite regexes in this file AND the detector',
+      '     set in tooling/boundaries/check-no-deep-require-leaks.mjs together.',
+      '',
+    ];
+    for (const { file, leaks } of residual) {
+      lines.push(`  • ${file}`);
+      for (const { shape, literal } of leaks) lines.push(`      [${shape}] ${literal}`);
+    }
+    throw new ScrubFailure(lines.join('\n'));
+  }
+
+  return { totalFiles, totalRewrites, touched };
+}
+
+// ── Self-test ────────────────────────────────────────────────────────────────
+
+async function expectFailure(label, fn) {
+  let threw = null;
+  try {
+    await fn();
+  } catch (err) {
+    threw = err;
+  }
+  if (!(threw instanceof ScrubFailure)) {
+    throw new Error(
+      `self-test: "${label}" was expected to FAIL and did not (${threw ? threw.message : 'no error thrown'}).`,
+    );
+  }
+  return threw;
+}
+
+async function selfTest() {
+  const root = await mkdtemp(join(tmpdir(), 'scrub-swagger-selftest-'));
+  try {
+    // 1. Missing directory — the wrong-outDir case.
+    await expectFailure('missing directory', () => run([join(root, 'does-not-exist')]));
+
+    // 2. Present but empty — the zero-scan case that used to pass silently.
+    const empty = join(root, 'empty');
+    await mkdir(empty, { recursive: true });
+    await expectFailure('empty directory', () => run([empty]));
+
+    // 2b. Present, non-empty, but no compiled .js.
+    const noJs = join(root, 'no-js');
+    await mkdir(noJs, { recursive: true });
+    await writeFile(join(noJs, 'readme.txt'), 'not compiled output\n', 'utf8');
+    await expectFailure('directory with no compiled .js', () => run([noJs]));
+
+    // 3. Detector proves it matches every shape, and does NOT match clean code.
+    const samples = [
+      [
+        'install-layout',
+        'require("@xemahq/policy-contracts/node_modules/@xemahq/subject-contracts/dist/lib/x")',
+      ],
+      // The shape that shipped in 25 services while this step reported success.
+      // It is listed here NOT because a rewriter handles it — that is exactly
+      // the reasoning that hid it — but because the detector's property
+      // ("names a segment of the builder's install layout") covers it.
+      [
+        'install-layout',
+        'require(".pnpm/@xemahq+kernel-contracts@7.5.0_abc123/node_modules/@xemahq/kernel-contracts/dist/capability/lib/x")',
+      ],
+      // Not an @xemahq package, and matched by nothing this script rewrites.
+      // A detector that can only see what a rewriter already fixes is the
+      // defect, so prove it sees beyond them.
+      ['install-layout', 'require("some-vendor/node_modules/left-pad/dist/index")'],
+      ['flat', 'require("@xemahq/capability-contracts/dist/lib/capability-grant")'],
+      ['relative-workspace', 'require("../../packages/kernel/kernel-contracts/dist/capability/lib/x")'],
+    ];
+    for (const [shape, literal] of samples) {
+      const hits = findLeaks(literal);
+      if (!hits.some((h) => h.shape === shape)) {
+        throw new Error(`self-test: detector missed the ${shape} shape: ${literal}`);
+      }
+    }
+    const clean = 'require("@xemahq/kernel-contracts");require("./local");require("../shared/util");';
+    if (findLeaks(clean).length !== 0) {
+      throw new Error(`self-test: detector matched clean output: ${JSON.stringify(findLeaks(clean))}`);
+    }
+
+    // 4. End-to-end GREEN — a single nested leak is rewritten and verifies clean.
+    const green = join(root, 'green');
+    await mkdir(green, { recursive: true });
+    const greenFile = join(green, 'dto.js');
+    await writeFile(greenFile, `${samples[0][1]};\n`, 'utf8');
+    const greenResult = await run([green]);
+    if (greenResult.totalRewrites < 1) {
+      throw new Error(`self-test: expected at least 1 rewrite, got ${greenResult.totalRewrites}`);
+    }
+    const greenAfter = await readFile(greenFile, 'utf8');
+    // The NESTED pass unwraps to `@xemahq/subject-contracts/dist/lib/x`, which
+    // the FLAT pass then reduces to the bare specifier — the two passes chain,
+    // and the verification proves the chain terminated clean.
+    if (greenAfter.trim() !== 'require("@xemahq/subject-contracts");') {
+      throw new Error(`self-test: unexpected rewrite result: ${greenAfter.trim()}`);
+    }
+    if (findLeaks(greenAfter).length !== 0) {
+      throw new Error(`self-test: rewritten file still leaks: ${greenAfter}`);
+    }
+
+    // 5. End-to-end RED — a DOUBLY-nested literal. One `String.replace` pass
+    //    does not re-scan its own replacement, so the rewrite leaves a literal
+    //    that is still a leak. This is the case the old script shipped
+    //    silently, and the reason the verification re-reads the tree.
+    const red = join(root, 'red');
+    await mkdir(red, { recursive: true });
+    await writeFile(
+      join(red, 'dto.js'),
+      'require("@xemahq/policy-contracts/node_modules/@xemahq/outer-contracts/node_modules/@xemahq/inner-contracts/dist/lib/x");\n',
+      'utf8',
+    );
+    const redErr = await expectFailure('residual leak after rewrite', () => run([red]));
+    if (!redErr.message.includes('still contain a leaked require')) {
+      throw new Error(`self-test: residual failure had the wrong message: ${redErr.message}`);
+    }
+
+    process.stdout.write(
+      'scrub-swagger-plugin-paths --self-test: PASS — missing dir, empty dir, no-.js dir all FAIL; ' +
+        'detector matches all 3 leak shapes and no clean literal; a rewritable leak verifies clean; ' +
+        'a residual leak FAILS the run.\n',
+    );
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+// ── Entry point ──────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes('--self-test')) {
+    if (args.length !== 1) {
+      throw new ScrubFailure('--self-test takes no other arguments');
+    }
+    await selfTest();
+    return;
+  }
+
+  const unknownFlags = args.filter((a) => a.startsWith('-'));
+  if (unknownFlags.length > 0) {
+    throw new ScrubFailure(
+      `unknown flag(s): ${unknownFlags.join(', ')}. This script takes output directories, or --self-test.`,
+    );
+  }
+  if (args.length === 0) {
+    process.stderr.write(
+      'usage: scrub-swagger-plugin-paths.mjs <dist-dir> [<dist-dir>…] | --self-test\n',
+    );
+    process.exit(2);
+  }
+
+  const { totalFiles, totalRewrites, touched } = await run(args);
+  if (totalRewrites === 0) {
+    // Silent on the common (clean) path — keeps build logs quiet. The run is
+    // still a verified one: `assertScannable` proved there was output to read.
+    return;
+  }
+
+  process.stdout.write(
+    `scrub-swagger-plugin-paths: rewrote ${totalRewrites} leaked require() literal(s) across ${touched.length} file(s) (scanned ${totalFiles}, verified clean).\n`,
+  );
+  for (const { file, count } of touched) {
+    process.stdout.write(`  ${file}  (${count})\n`);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(
+    `scrub-swagger-plugin-paths: FAILED — ${
+      err instanceof ScrubFailure ? err.message : err instanceof Error ? (err.stack ?? err.message) : String(err)
+    }\n`,
+  );
+  process.exit(1);
+});