@xemahq/repo-build-tooling 0.26.5 → 0.27.1

package/README.md

@@ -34,7 +34,6 @@ pnpm exec xema-scrub-swagger-paths dist
 | `xema-arm64-supplement-needed` | Decides whether an arm64 supplement is still owed at `REGISTRY/IMAGE:CONTENT_TAG` (env: `REGISTRY`, `IMAGE`, `CONTENT_TAG`, `REGISTRY_USER`, `REGISTRY_TOKEN`). `needed=false` only when the coordinate serves an index whose linux/arm64 child is proven by its own image config; any other resolvable state is `needed=true`; a 401/403/5xx or an unresolvable child is an error. Writes `needed=true\|false` to `$GITHUB_OUTPUT`. Replaces the generated `arm64-supplement-needed.mjs` copy. |
 | `xema-promote-image --service <name> --dev-ref <repo> --release-ref <repo> --tag <tag> --commit <sha> --main-ref <ref> --signer-repository <owner/repo> --develop-workflow <file> --release-workflow <file>... [--release-index-workflow <file>] --promotion-predicate-out <path> -- <tag command>` | Publishes the develop image's digest under the release tag instead of rebuilding: `reused` (the release digest carries an `image-promotion/v1` attestation signed by a `--release-workflow` identity on main, with exactly one verified statement about the digest and a `ghcr.io/<owner>/dev/<name>` source; no dev-ref probe), `copied` (the proven develop digest, digest-preserving; fails closed if the release digest differs) or `miss` (build it; a reuse whose release digest has no `image-promotion/v1` attestation, a legacy image, is a miss with `reason=reuse-no-promotion` on the stdout line; with `--release-index-workflow`, a release tag that names an image index signed by that workflow on main, with exactly one `linux/amd64` child whose own digest passes that same reuse check, is instead `reused` with `evidence=release-index`, `digest` = the amd64 child A, `index_digest` = the index D and no predicate, but only when A's selected promotion statement promotes `--commit` itself (a rerun; a later commit with the same content takes the existing miss and attests its own promotion). On `evidence=release-index` the caller skips sign/attest, tags `:<sha>` and `main-<sha>` to the amd64 subject `digest` (release-arm64 resolves `:<sha>` to it and verifies its promotion), and points only the content tag (and `latest`, if it moves it) at the index `index_digest`. Any failed step keeps the miss, and two amd64 children are an error; a signature or identity failure, or a source outside `dev/`, is an error; a copy whose dev digest carries no SLSA v1 provenance at all, an image reused on develop from before provenance, is a miss with `reason=copy-no-develop-provenance`, while provenance that is present but fails a leg is an error). A develop digest is proven only if its SLSA v1 provenance is signed by the develop workflow at `refs/heads/develop`, its revision is an ancestor of the main ref, and the tag command prints the same tag at that revision and at `--commit`; any failed leg is an error, never a miss. On every non-miss result it writes the `https://xema.dev/attestations/image-promotion/v1` predicate for the caller to attest: a copy states the facts just proved; a reuse states this run's `release` and `promotedCommit` and carries `source` and `developProvenance` from the earlier promotion. Writes `result`, `digest`, `source`, `revision`, `evidence`, `provenance_digest`, `promotion_predicate`, `promotion_predicate_type` to `$GITHUB_OUTPUT`. Needs `docker`, `cosign` (major v2, the same as the develop attest step and xema-deploy's verify; it runs `cosign version` first and refuses any other major or an unparsable version), `git` and full history. It does not sign |
 | `xema-check-no-vendored-deps` | Fails on a `workspace:` range for a package the repository does not own |
-| `xema-prepush-sanity` | Lefthook `pre-push`: turbo `lint` and `typecheck` on what the push changes plus dependents, and `test` and `openapi:current` (where defined) only on the packages the push changed; a fleet-wide change runs only `lint` and `typecheck` on the full graph; root `lint` only without turbo; a park-only push (`refs/xema-session/*`) skips |
 | `xema-check-workspace-ranges` | Fails on a `workspace:` range the local package does not satisfy |
 
 `xema-composed-image members --write|--check` accepts `--manifests <glob>` (repeatable, default `**/xema-biome.json`), `--canonical-dockerfile <path>` and `--cross-repo-manifest <path>`. `xema-composed-image dockerfile` requires `--copy`, `--cache-id` and `--build-source`; it pins the version of this tool itself, and there is no flag for it (`--tooling-version` is refused as an unknown option).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.26.5",
+  "version": "0.27.1",
   "description": "Dev-time build tooling shared by every Xema repository. Ships as plain ESM, depending only on @xemahq/release-policy for registry access, so the published artifact is the reviewed source.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -25,8 +25,6 @@
     "xema-check-no-vendored-deps": "src/check-no-vendored-deps.mjs",
     "xema-check-workspace-ranges": "src/check-workspace-range-matches-local.mjs",
     "xema-composed-image": "src/composed-image.mjs",
-    "xema-install-git-hooks": "src/install-git-hooks.mjs",
-    "xema-prepush-sanity": "src/prepush-sanity.mjs",
     "xema-promote-image": "src/promote-image.mjs",
     "xema-readiness": "src/readiness.mjs",
     "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs",
@@ -38,9 +36,7 @@
     "./check-no-vendored-deps": "./src/check-no-vendored-deps.mjs",
     "./check-workspace-range-matches-local": "./src/check-workspace-range-matches-local.mjs",
     "./composed-image": "./src/composed-image.mjs",
-    "./install-git-hooks": "./src/install-git-hooks.mjs",
     "./package.json": "./package.json",
-    "./prepush-sanity": "./src/prepush-sanity.mjs",
     "./promote-image": "./src/promote-image.mjs",
     "./readiness": "./src/readiness.mjs",
     "./scrub-swagger-plugin-paths": "./src/scrub-swagger-plugin-paths.mjs",
@@ -51,9 +47,9 @@
     "@xemahq/release-policy": "^16.0.0"
   },
   "scripts": {
-    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/composed-image-coordinate-cli.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs && node --test src/composed-image-prebuilt-dockerfile.test.mjs && node --test src/composed-image-in-image-closure.test.mjs && node --test src/composed-image-stage.test.mjs && node --test src/composed-image-stage-tree.test.mjs && node --test src/composed-image-install.test.mjs && node --test src/composed-image-proof.test.mjs && node --test src/composed-image-pnpm-context.test.mjs && node --test src/composed-image-sync-injected.test.mjs && node --test src/composed-image-prisma-check.test.mjs && node --test src/composed-image-prisma-engine.test.mjs && node --test src/composed-migrate.test.mjs && node --test src/promote-image.test.mjs && node --test src/arm64-supplement-needed.test.mjs && node --test src/prepush-sanity.test.mjs && node --test src/service-image.test.mjs && node --test src/install-git-hooks.test.mjs && node --test src/image-cpu-arch.test.mjs"
+    "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/composed-image-coordinate-cli.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs && node --test src/composed-image-prebuilt-dockerfile.test.mjs && node --test src/composed-image-in-image-closure.test.mjs && node --test src/composed-image-stage.test.mjs && node --test src/composed-image-stage-tree.test.mjs && node --test src/composed-image-install.test.mjs && node --test src/composed-image-proof.test.mjs && node --test src/composed-image-pnpm-context.test.mjs && node --test src/composed-image-sync-injected.test.mjs && node --test src/composed-image-prisma-check.test.mjs && node --test src/composed-image-prisma-engine.test.mjs && node --test src/composed-migrate.test.mjs && node --test src/promote-image.test.mjs && node --test src/arm64-supplement-needed.test.mjs && node --test src/service-image.test.mjs && node --test src/image-cpu-arch.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:f0df75e0b53e7d061fca29cca85baadc3e8d20ac245220164fe16d5e3f051adc"
+    "sourceDigest": "sha256:65b9132685b9423a89b13ec6d03b21f3c7c66c529c98fbf09ee6a7bd4cde39d9"
   }
 }

package/src/composed-image-prisma-check.mjs

@@ -1,18 +1,19 @@
 // `xema-composed-image prisma-check`, INSIDE the image build, on the TARGET arch.
 // Every member that owns a Prisma schema carries its generated client(s) in
 // `<member>/node_modules/.prisma/<client>/`, generated on the CI runner and staged
-// without running anything. Each client's schema must be the member's own schema as
+// without running anything; non-client generator outputs there (the org-erasure graph)
+// must load and export their names. Each client's schema must be the member's own schema as
 // `prisma format` writes it, or the client is stale. The image carries no native engine: the only supported
 // client is Rust-free (a wasm query compiler plus a driver adapter). This refuses any
 // native engine file, compiles the wasm, checks the client matches the member's
 // `prisma` CLI, and constructs it. It never connects.
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 
 import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
 import { readMembers } from './composed-image-members.mjs';
-import { clientSchemaProblems, memberPrismaSchema } from './composed-migrate.mjs';
+import { clientSchemaProblems, memberPrismaOutputs, memberPrismaSchema } from './composed-migrate.mjs';
 
 const NATIVE_ENGINE = [/^libquery_engine-.*\.node$/, /^query-engine-/, /\.so\.node$/, /\.dll\.node$/, /\.dylib\.node$/];
 const WASM_COMPILER = /^query_compiler.*_bg\.wasm$/;
@@ -35,16 +36,14 @@ function cliVersion(memberRequire, memberDirectory) {
 async function schemaVerdicts({ root, imageDir, formatSpawn, concurrency }) {
   const jobs = [];
   for (const [, directory] of readMembers({ root, imageDir })) {
+    let schema;
     try {
-      if (memberPrismaSchema(root, directory) === undefined) continue;
+      schema = memberPrismaSchema(root, directory);
     } catch {
       continue; // reported by the main pass
     }
-    const container = join(root, directory, 'node_modules', '.prisma');
-    if (!existsSync(container)) continue;
-    for (const entry of readdirSync(container, { withFileTypes: true }).filter((e) => e.isDirectory())) {
-      jobs.push({ root, memberDir: directory, clientDir: join(container, entry.name) });
-    }
+    if (schema === undefined) continue;
+    for (const clientDir of memberPrismaOutputs(root, directory, schema).clients) jobs.push({ root, memberDir: directory, clientDir });
   }
   const verdicts = await clientSchemaProblems(jobs, { spawn: formatSpawn, concurrency });
   return new Map(jobs.map((job, i) => [job.clientDir, verdicts[i]]));
@@ -75,10 +74,22 @@ export async function prismaCheck({ root = process.cwd(), imageDir = COMPOSED_IM
       continue;
     }
     const memberRequire = createRequire(join(memberDirectory, 'package.json'));
-    for (const name of dirs) {
+    const outputs = memberPrismaOutputs(root, directory, schema);
+    for (const problem of outputs.problems) problems.push(`${key}: ${problem}`);
+    // A non-client artifact (e.g. the org-erasure graph) is imported at boot: it must load and export its names.
+    for (const { dir, kind, exports } of outputs.artifacts) {
+      const label = `${key} (.prisma/${basename(dir)})`;
+      try {
+        const module = memberRequire(dir);
+        const absent = exports.filter((name) => module?.[name] === undefined);
+        if (absent.length > 0) problems.push(`${label}: the ${kind} does not export ${absent.join(', ')}`);
+      } catch (error) {
+        problems.push(`${label}: the ${kind} does not load: ${error?.message ?? String(error)}`);
+      }
+    }
+    for (const clientDirectory of outputs.clients) {
       clients += 1;
-      const label = `${key} (.prisma/${name})`;
-      const clientDirectory = join(container, name);
+      const label = `${key} (.prisma/${basename(clientDirectory)})`;
       const staleProblem = stale.get(clientDirectory);
       if (staleProblem !== undefined) {
         problems.push(`${label}: ${staleProblem}`);

package/src/composed-image-prisma-check.test.mjs

@@ -38,3 +38,21 @@ test('a stale client (the source gained a field after generation) is refused; th
   await assert.rejects(prismaCheck({ root: stale, log() {}, formatSpawn: formatNoop }), /differs from the member's prisma\/schema\.prisma .*stale/);
   await assert.rejects(prismaCheck({ root: workspace(), log() {}, formatSpawn: formatNoop }), (e) => !/stale/.test(e.message));
 });
+
+test('an org-erasure graph is not treated as a client: it must load and export orgErasureGraph', async () => {
+  const schema =
+    'generator client {\n  provider = "prisma-client-js"\n  output   = "../node_modules/.prisma/alpha-db"\n}\n\n' +
+    'generator orgErasureGraph {\n  provider = "xema-org-erasure-graph"\n  output   = "../node_modules/.prisma/alpha-db-org-erasure-graph"\n}\n\ndatasource db {}\n';
+  const graph = (root, js) => {
+    write(root, 'biomes/alpha/api/alpha-db-api/prisma/schema.prisma', schema);
+    write(root, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db/schema.prisma', schema);
+    write(root, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db-org-erasure-graph/index.js', js);
+    write(root, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db-org-erasure-graph/index.d.ts', '');
+    return root;
+  };
+  // The fixture client has no wasm compiler, so the check fails, but only on the client, never on the graph.
+  await assert.rejects(prismaCheck({ root: graph(workspace(), 'exports.orgErasureGraph = {};\n'), log() {}, formatSpawn: formatNoop }), (e) =>
+    /\.prisma\/alpha-db\): no query_compiler/.test(e.message) && !/org-erasure-graph/.test(e.message));
+  await assert.rejects(prismaCheck({ root: graph(workspace(), 'exports.other = 1;\n'), log() {}, formatSpawn: formatNoop }),
+    /\.prisma\/alpha-db-org-erasure-graph\): the org-erasure graph does not export orgErasureGraph/);
+});

package/src/composed-image-stage.mjs

@@ -5,7 +5,7 @@
 //
 //   <dir>/out/<package dir>/<output>/               every closure package's outputs (default: dist);
 //                                                   `--also <pkg>` adds that package's closure (no member checks)
-//   <dir>/out/<pkg dir>/node_modules/.prisma/       the generated Prisma clients of every closure root that has
+//   <dir>/out/<pkg dir>/node_modules/.prisma/       the generated Prisma clients (and artifacts such as the org-erasure graph) of every closure root that has
 //                                                   `prisma/schema.prisma` (members and `--also` roots alike)
 //   <dir>/tool/                                     this package (package.json + src, no tests):
 //                                                   bind-mounted into the build, never copied into a layer
@@ -18,7 +18,7 @@ import { fileURLToPath } from 'node:url';
 
 import { COMPOSED_IMAGE_DIR, NODE_MAJOR_LABEL } from './composed-image-paths.mjs';
 import { memberClosure, readMembers } from './composed-image-members.mjs';
-import { clientSchemaProblems, memberPrismaSchema } from './composed-migrate.mjs';
+import { clientSchemaProblems, memberPrismaOutputs, memberPrismaSchema } from './composed-migrate.mjs';
 
 export const DEFAULT_OUTPUTS = Object.freeze(['dist']);
 const TOOL_PACKAGE = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -114,9 +114,11 @@ export async function planBuildOutputs({
     const hasClient = existsSync(clients) && readdirSync(clients, { withFileTypes: true }).some((e) => e.isDirectory());
     if (schema !== undefined && !hasClient) problems.push(`${key}: ${directory} has prisma/schema.prisma but no node_modules/.prisma/<client>/ — run prisma generate`);
     if (schema !== undefined && hasClient) {
-      for (const entry of readdirSync(clients, { withFileTypes: true }).filter((e) => e.isDirectory())) {
-        schemaJobs.push({ key, root, memberDir: directory, clientDir: join(clients, entry.name) });
-      }
+      // Each folder by what generated it: clients are checked against the schema, other artifacts
+      // (e.g. the org-erasure graph the process imports at boot) must be present and complete.
+      const prismaOutputs = memberPrismaOutputs(root, directory, schema);
+      for (const problem of prismaOutputs.problems) problems.push(`${key}: ${problem}`);
+      for (const clientDir of prismaOutputs.clients) schemaJobs.push({ key, root, memberDir: directory, clientDir });
     }
     if (schema === undefined && hasClient) problems.push(`${key}: ${directory} ships node_modules/.prisma/<client>/ but has no prisma/schema.prisma`);
   }

package/src/composed-image-stage.test.mjs

@@ -173,3 +173,44 @@ test('--also refuses a non-member closure root with prisma/schema.prisma but no
   await assert.rejects(stage(root, { exec: alsoPnpm(root, EXTRA), also: ['@t/extra'] }), /packages\/sdks\/extra has prisma\/schema\.prisma but no generated client: run prisma generate/);
   assert.equal(fs.existsSync(path.join(root, '.xema-stage')), false);
 });
+
+const GRAPH_SCHEMA =
+  'generator client {\n  provider = "prisma-client-js"\n  output   = "../node_modules/.prisma/alpha-db"\n}\n\n' +
+  'generator orgErasureGraph {\n  provider = "xema-org-erasure-graph"\n  output   = "../node_modules/.prisma/alpha-db-org-erasure-graph"\n}\n\ndatasource db {}\n';
+
+function withErasureGraph() {
+  const root = ready();
+  write(root, 'biomes/alpha/api/alpha-db-api/prisma/schema.prisma', GRAPH_SCHEMA);
+  write(root, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db/schema.prisma', GRAPH_SCHEMA);
+  write(root, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db-org-erasure-graph/index.js', 'exports.orgErasureGraph = {};\n');
+  write(root, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db-org-erasure-graph/index.d.ts', 'export declare const orgErasureGraph: unknown;\n');
+  return root;
+}
+
+test('stages a member with a Prisma client and an org-erasure graph, carrying the graph', async () => {
+  const root = withErasureGraph();
+  await stage(root);
+  const staged = files(path.join(root, '.xema-stage/out'));
+  assert.ok(staged.includes('biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db-org-erasure-graph/index.js'));
+  assert.ok(staged.includes('biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db/index.js'));
+});
+
+test('a client without its schema still fails beside an org-erasure graph; a missing or incomplete graph fails clearly', async () => {
+  const noClientSchema = withErasureGraph();
+  fs.rmSync(path.join(noClientSchema, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db/schema.prisma'));
+  await assert.rejects(stage(noClientSchema), (e) => /\.prisma\/alpha-db: carries no schema\.prisma/.test(e.message) && !/org-erasure-graph/.test(e.message));
+  const missing = withErasureGraph();
+  fs.rmSync(path.join(missing, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db-org-erasure-graph'), { recursive: true });
+  await assert.rejects(stage(missing), /generator orgErasureGraph \(provider "xema-org-erasure-graph"\): node_modules\/\.prisma\/alpha-db-org-erasure-graph is missing — run prisma generate/);
+  const incomplete = withErasureGraph();
+  fs.rmSync(path.join(incomplete, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db-org-erasure-graph/index.d.ts'));
+  await assert.rejects(stage(incomplete), /the org-erasure graph node_modules\/\.prisma\/alpha-db-org-erasure-graph lacks index\.d\.ts/);
+});
+
+test('refuses a generator of an unknown provider writing into node_modules/.prisma', async () => {
+  const root = withErasureGraph();
+  const schema = `${GRAPH_SCHEMA}generator other {\n  provider = "some-generator"\n  output   = "../node_modules/.prisma/alpha-db-other"\n}\n`;
+  write(root, 'biomes/alpha/api/alpha-db-api/prisma/schema.prisma', schema);
+  write(root, 'biomes/alpha/api/alpha-db-api/node_modules/.prisma/alpha-db/schema.prisma', schema);
+  await assert.rejects(stage(root), /generator other \(provider "some-generator"\) writes node_modules\/\.prisma\/alpha-db-other, a kind the composed image does not know/);
+});

package/src/composed-migrate.mjs

@@ -11,9 +11,9 @@
 // platform migration runner drops it the same way). Exits with the child's code.
 // This file is also the single home of `memberPrismaSchema`, which the build tool imports.
 import { spawn as spawnAsync, spawnSync } from 'node:child_process';
-import { copyFileSync, existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync } from 'node:fs';
 import { availableParallelism, tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 /**
@@ -42,6 +42,75 @@ export function memberPrismaSchema(root, memberDir) {
   return existsSync(schema) ? schema : undefined;
 }
 
+/**
+ * Generators that write into `node_modules/.prisma/` something that is NOT a Prisma client,
+ * keyed by provider: what the output is, the files it must carry and the names its module
+ * must export. The process imports these at boot, so a missing one is a stage failure.
+ */
+export const PRISMA_ARTIFACT_GENERATORS = Object.freeze({
+  'xema-org-erasure-graph': Object.freeze({ kind: 'org-erasure graph', files: ['index.js', 'index.d.ts'], exports: ['orgErasureGraph'] }),
+});
+const PRISMA_CLIENT_PROVIDERS = new Set(['prisma-client-js', 'prisma-client']);
+
+/**
+ * The schema's generator blocks: `[{ name, provider, output }]`. `output` is the absolute
+ * directory (resolved against the schema's directory, as Prisma does), or undefined when the
+ * block sets none or not as a string literal (e.g. `env(...)`).
+ */
+export function schemaGenerators(schemaPath) {
+  const text = readFileSync(schemaPath, 'utf8').replace(/^\s*\/\/.*$/gm, '');
+  const generators = [];
+  for (const block of text.matchAll(/^\s*generator\s+(\w+)\s*\{([^}]*)\}/gm)) {
+    const provider = /^\s*provider\s*=\s*"([^"]*)"/m.exec(block[2])?.[1];
+    const output = /^\s*output\s*=\s*"([^"]*)"/m.exec(block[2])?.[1];
+    generators.push({ name: block[1], provider, output: output === undefined ? undefined : resolve(dirname(schemaPath), output) });
+  }
+  return generators;
+}
+
+/**
+ * Sort a member's `node_modules/.prisma/<dir>/` folders by the generator that wrote them, read
+ * from the member's schema: `{ clients, artifacts, problems }`. A folder a client generator
+ * declares, or one no generator declares, is a Prisma client (`clients`: absolute dirs, to be
+ * checked against the schema). A folder a `PRISMA_ARTIFACT_GENERATORS` provider declares is that
+ * artifact (`artifacts`: `{ dir, provider, kind, exports }`) and must carry its files. A declared
+ * output that is absent, or a generator of an unknown provider writing into `.prisma/`, is a problem.
+ */
+export function memberPrismaOutputs(root, memberDir, schemaPath) {
+  const container = join(resolve(root, memberDir), 'node_modules', '.prisma');
+  const present = new Set(
+    existsSync(container) ? readdirSync(container, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => join(container, e.name)) : [],
+  );
+  const declared = new Map(); // dir -> provider
+  const problems = [];
+  for (const { name, provider, output } of schemaGenerators(schemaPath)) {
+    if (output === undefined || dirname(output) !== container) continue;
+    const label = `${memberDir}: generator ${name} (provider "${provider}")`;
+    if (!PRISMA_CLIENT_PROVIDERS.has(provider) && PRISMA_ARTIFACT_GENERATORS[provider] === undefined) {
+      problems.push(`${label} writes node_modules/.prisma/${basename(output)}, a kind the composed image does not know`);
+      continue;
+    }
+    declared.set(output, provider);
+    if (!present.has(output)) problems.push(`${label}: node_modules/.prisma/${basename(output)} is missing — run prisma generate`);
+  }
+  const clients = [];
+  const artifacts = [];
+  for (const dir of [...present].sort()) {
+    const spec = PRISMA_ARTIFACT_GENERATORS[declared.get(dir)];
+    if (spec === undefined) {
+      clients.push(dir);
+      continue;
+    }
+    const missing = spec.files.filter((file) => !existsSync(join(dir, file)));
+    if (missing.length > 0) {
+      problems.push(`${memberDir}: the ${spec.kind} node_modules/.prisma/${basename(dir)} lacks ${missing.join(', ')} — run prisma generate`);
+      continue;
+    }
+    artifacts.push({ dir, provider: declared.get(dir), kind: spec.kind, exports: spec.exports });
+  }
+  return { clients, artifacts, problems };
+}
+
 /** Async process run with collected output: `{ status, stdout, stderr }` or `{ error }`. */
 function runAsync(command, args, options) {
   return new Promise((done) => {

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

@@ -129,7 +129,7 @@
 
 import { createRequire } from 'node:module';
 import { readFileSync, realpathSync } from 'node:fs';
-import { mkdir, mkdtemp, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readdir, readFile, rm, stat, symlink, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import process from 'node:process';
@@ -168,14 +168,14 @@ const FLAT_LEAK_REGEX = new RegExp(
 // and down into the contracts package.  There is no `node_modules/` segment
 // so shapes 1 and 2 above never fire.
 // Capture group 1: relative path from the scrubbed file to the package directory.
-// Capture group 2: first path segment after dist/ = the subpath export name.
+// Capture group 2: everything after dist/ (the physical subpath inside the package).
 // The public package name is NOT derived from the directory name or a fixed
 // scope: it is read from the target package's own package.json `name`, so
 // unscoped and differently-named workspace packages resolve correctly.
 // 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-]*)(?:/[^"]*)?"\\)`,
+  `require\\("((?:\\.\\./)+(?:packages|biomes|kernel)/(?:[a-z0-9][a-z0-9.-]*/)*[a-z0-9][a-z0-9.-]*)/dist/([a-z0-9][a-z0-9-]*(?:/[^"]*)?)"\\)`,
   'g',
 );
 
@@ -323,6 +323,7 @@ function reExportsReach(entry, target, depth = 6, seen = new Set()) {
  * @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
+ * @param {string} [importer] the file holding the require, named in the refusal
  */
 // NUL is the separator in the cache key because it cannot occur in a package
 // name or a subpath, so no two distinct specifiers can collide on a
@@ -332,7 +333,7 @@ function reExportsReach(entry, target, depth = 6, seen = new Set()) {
 // silently, and a file no search can read is a file no audit, no review and no
 // boundary check covers. Enforced by the aggregator boundary gate
 // `grep-readable-sources`.
-function publicSpecifierFor(resolveFrom, pkg, subpath, original) {
+function publicSpecifierFor(resolveFrom, pkg, subpath, original, importer) {
   const cacheKey = `${pkg}\u0000${subpath}`;
   if (specifierCache.has(cacheKey)) return specifierCache.get(cacheKey);
 
@@ -412,6 +413,7 @@ function publicSpecifierFor(resolveFrom, pkg, subpath, original) {
   throw new ScrubFailure(
     `no public specifier of ${pkg} resolves to the same file as\n` +
       `  ${original}\n` +
+      (importer ? `  required by ${importer}\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` +
@@ -586,10 +588,16 @@ async function scrubFile(path) {
         `  rather than reaching through dist/.`,
     );
   }
-  out = out.replace(RELATIVE_WORKSPACE_REGEX, (match, relPackageDir, subpath) => {
+  out = out.replace(RELATIVE_WORKSPACE_REGEX, (match, relPackageDir, rest) => {
     count += 1;
     const name = packageNameAt(resolve(dirname(path), relPackageDir), match);
-    return `require("${name}/${subpath}")`;
+    // Through the target's own `exports` map, never a hardcoded `<name>/<seg>`:
+    // a package that exports only "." has no such subpath, and the old form
+    // crashed at runtime with ERR_PACKAGE_PATH_NOT_EXPORTED. When the root
+    // barrel re-exports the file, the root is the proved public form; when no
+    // exported subpath reaches it, the build refuses.
+    const original = match.slice('require("'.length, -2);
+    return `require("${publicSpecifierFor(resolveFrom, name, `dist/${rest}`, original, path)}")`;
   });
   if (count > 0) {
     await writeFile(path, out, 'utf8');
@@ -712,6 +720,13 @@ async function expectFailure(label, fn) {
   return threw;
 }
 
+/** Make `name` resolvable from `consumerDir` the way a workspace install does. */
+async function linkWorkspacePackage(consumerDir, name, packageDir) {
+  const link = join(consumerDir, 'node_modules', name);
+  await mkdir(dirname(link), { recursive: true });
+  await symlink(packageDir, link, 'dir');
+}
+
 async function selfTest() {
   const root = await mkdtemp(join(tmpdir(), 'scrub-swagger-selftest-'));
   try {
@@ -830,11 +845,18 @@ async function selfTest() {
       ['packages/contracts/plain-dir', 'plain-contract'],
       ['packages/contracts/other-dir', '@xemahq/renamed'],
     ];
+    await mkdir(join(ws, 'services/svc/dist'), { recursive: true });
     for (const [dir, name] of pkgs) {
       await mkdir(join(ws, dir, 'dist/lib'), { recursive: true });
-      await writeFile(join(ws, dir, 'package.json'), JSON.stringify({ name }), 'utf8');
+      await writeFile(
+        join(ws, dir, 'package.json'),
+        JSON.stringify({ name, exports: { './*': './dist/*/index.js' } }),
+        'utf8',
+      );
+      await writeFile(join(ws, dir, 'dist/lib/index.js'), 'module.exports = require("./x");\n', 'utf8');
+      await writeFile(join(ws, dir, 'dist/lib/x.js'), 'module.exports = {};\n', 'utf8');
+      await linkWorkspacePackage(join(ws, 'services/svc'), name, join(ws, dir));
     }
-    await mkdir(join(ws, 'services/svc/dist'), { recursive: true });
     const wsFile = join(ws, 'services/svc/dist/dto.js');
     const relOf = (dir) => `../../../${dir}/dist/lib/x`;
     await writeFile(
@@ -851,6 +873,42 @@ async function selfTest() {
         throw new Error(`self-test: relative-workspace rewrite missing ${expected}: ${wsAfter}`);
       }
     }
+
+    // 4c. A package that exports ONLY "." (xema-base authorization-nest). The
+    // swagger plugin requires the enum's declaring file; `<name>/<file>` is not
+    // exported and crashed at runtime with ERR_PACKAGE_PATH_NOT_EXPORTED.
+    //   - root barrel re-exports the file -> the root is the proved form;
+    //   - no exported subpath reaches the file -> the build refuses, naming the
+    //     package, the file and the importing module.
+    const dot = join(root, 'dot');
+    const dotPkg = join(dot, 'packages/sdks/dot-only');
+    await mkdir(join(dotPkg, 'dist'), { recursive: true });
+    await mkdir(join(dot, 'svc/dist'), { recursive: true });
+    await writeFile(
+      join(dotPkg, 'package.json'),
+      JSON.stringify({ name: '@xemahq/dot-only', exports: { '.': './dist/index.js' } }),
+      'utf8',
+    );
+    await writeFile(join(dotPkg, 'dist/index.js'), 'module.exports = require("./grant-wire");\n', 'utf8');
+    await writeFile(join(dotPkg, 'dist/grant-wire.js'), 'module.exports = { Kind: {} };\n', 'utf8');
+    await writeFile(join(dotPkg, 'dist/internal-only.js'), 'module.exports = { Hidden: {} };\n', 'utf8');
+    await linkWorkspacePackage(join(dot, 'svc'), '@xemahq/dot-only', dotPkg);
+    const dotDto = (file) =>
+      `class Dto {\n  static _OPENAPI_METADATA_FACTORY() {\n    return { kind: { type: () => require("../../packages/sdks/dot-only/dist/${file}").Kind } };\n  }\n}\n`;
+    const dotFile = join(dot, 'svc/dist/dto.js');
+    await writeFile(dotFile, dotDto('grant-wire'), 'utf8');
+    await run([join(dot, 'svc/dist')]);
+    const dotAfter = await readFile(dotFile, 'utf8');
+    if (!dotAfter.includes('require("@xemahq/dot-only").Kind') || dotAfter.includes('dot-only/')) {
+      throw new Error(`self-test: a "."-only package must map to its root, got: ${dotAfter}`);
+    }
+    await writeFile(dotFile, dotDto('internal-only'), 'utf8');
+    const dotRefusal = await expectFailure('unexported file no exported subpath reaches', () => run([join(dot, 'svc/dist')]));
+    for (const named of ['@xemahq/dot-only', 'internal-only', dotFile]) {
+      if (!dotRefusal.message.includes(named)) {
+        throw new Error(`self-test: the refusal must name ${named}; got: ${dotRefusal.message}`);
+      }
+    }
     // A target directory without its own package.json is a hard failure.
     const orphan = join(root, 'orphan');
     await mkdir(join(orphan, 'svc/dist'), { recursive: true });