@xemahq/biome-bundle-pack 0.0.0-stage → 0.2.0

package/src/bundle-content.mjs

@@ -0,0 +1,30 @@
+// The content digest of a bundle tree, as the kernel contracts define it (`encodeBiomeBundleContentPreimage`): one
+// `{ path, sha256 }` per regular FILE, the manifest excluded because it carries the digest. Symlinks and directories are
+// not listed: the preimage knows files only, so the pnpm layout's links are covered by the archive digest, not by this one.
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { BIOME_BUNDLE_MANIFEST_FILE, encodeBiomeBundleContentPreimage } from '@xemahq/contracts/biome-bundle';
+
+/** Lowercase SHA-256 hex of `bytes`. */
+export const sha256Hex = (bytes) => createHash('sha256').update(bytes).digest('hex');
+
+/** Every regular file under `dir` except the manifest, as `{ path, sha256 }`, sorted by path. */
+export function bundleContentFiles(dir) {
+  const files = [];
+  const walk = (prefix) => {
+    for (const entry of readdirSync(join(dir, prefix), { withFileTypes: true })) {
+      const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+      if (entry.isDirectory()) {walk(rel);}
+      else if (entry.isFile() && rel !== BIOME_BUNDLE_MANIFEST_FILE) {files.push({ path: rel, sha256: sha256Hex(readFileSync(join(dir, rel))) });}
+    }
+  };
+  walk('');
+  return files.sort((a, b) => (a.path < b.path ? -1 : 1));
+}
+
+/** `sha256:<hex>` of the UTF-8 bytes of the content preimage of the bundle tree at `dir`. */
+export function bundleContentDigest(dir) {
+  return `sha256:${sha256Hex(Buffer.from(encodeBiomeBundleContentPreimage(bundleContentFiles(dir)), 'utf8'))}`;
+}

package/src/bundle-manifest.mjs

@@ -0,0 +1,27 @@
+// The `xema-bundle.json` at a bundle's root: what a host needs to load, migrate and register the bundle's members without
+// opening the tree. One bundle is one biome with all its members. It names the build source (repository and commit) but no
+// timestamp or host path; the commit is outside the content digest, which covers every file but this one. The object is graded by the contracts' own
+// `BiomeBundleManifestSchema`, so the packer cannot write a manifest a host would refuse.
+import { BIOME_BUNDLE_MANIFEST_SCHEMA_VERSION, BiomeBundleManifestSchema } from '@xemahq/contracts/biome-bundle';
+
+import { canonicalJson } from './canonical-json.mjs';
+
+/**
+ * The manifest text (canonical JSON, newline-terminated) of the parsed manifest. `members` are `{ member: <componentKey>, entry, migrations?, requiredEnvVars?, kind? }` (the NAMES the entry requires and its `http`/`worker` kind, captured by `memberEntryFacts`) ascending by member, where
+ * `migrations` is `{ engine, path }` (bundle-relative); `buildSource` is `{ repository, commit }`; `hostAbi` is `{ id, kernelContracts, identityPackages }`;
+ * `platform` is `{ os, cpu, libc }` or absent; `build` is the biome's build facts (`deriveBiomeBuildFacts`), required. Absent optional keys are omitted, never written as null. Paths are bundle-relative.
+ */
+export function bundleManifest({ biome, members, buildSource, hostAbi, contributionKinds, platform, build, contentDigest }) {
+  const manifest = BiomeBundleManifestSchema.parse({
+    schemaVersion: BIOME_BUNDLE_MANIFEST_SCHEMA_VERSION,
+    biome,
+    members: members.map(({ member, entry, migrations, requiredEnvVars, kind }) => ({ member, entry, ...(migrations === undefined ? {} : { migrations }), ...(requiredEnvVars === undefined ? {} : { requiredEnvVars }), ...(kind === undefined ? {} : { kind }) })),
+    buildSource,
+    hostAbi,
+    contributionKinds,
+    ...(platform === undefined ? {} : { platform }),
+    build,
+    contentDigest,
+  });
+  return `${canonicalJson(manifest)}\n`;
+}

package/src/bundle-unpack.mjs

@@ -0,0 +1,114 @@
+// The reader of a bundle archive: the inverse of `canonicalTar` + `gzipCanonical`. It reads exactly what that writer
+// writes (ustar headers, pax `path` and `linkpath` records, directories, files, symlinks) and refuses everything else,
+// so there is ONE bundle format with one writer and one reader. Nothing leaves `destDir`: an absolute or `..` path, a
+// duplicate path, an entry through a symlink and a symlink whose target resolves outside the tree are refused.
+// Loads only `node:` builtins.
+import { mkdirSync, symlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, normalize, posix, resolve, sep } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+
+import { archiveDigest } from './bundle-archive.mjs';
+
+const BLOCK = 512;
+
+/** The ustar type flags this reader accepts: what the writer writes. */
+const TypeFlag = Object.freeze({ File: '0', Symlink: '2', Directory: '5', Pax: 'x' });
+
+/** The archive bytes do not hash to the digest they were fetched under. */
+export class BundleArchiveDigestMismatchError extends Error {
+  constructor(expected, actual) {
+    super(`the bundle archive hashes to ${actual}, not the expected ${expected}`);
+    this.name = 'BundleArchiveDigestMismatchError';
+  }
+}
+
+const readString = (header, offset, width) => {
+  const end = header.indexOf(0, offset);
+  return header.subarray(offset, end === -1 || end > offset + width ? offset + width : end).toString('utf8');
+};
+const readOctal = (header, offset, width) => parseInt(readString(header, offset, width).trim() || '0', 8);
+
+/** `{ key: value }` of the pax records in `data` (`"<length> <key>=<value>\n"` each). */
+function parsePax(data) {
+  const records = {};
+  let at = 0;
+  while (at < data.length) {
+    const space = data.indexOf(0x20, at);
+    const length = Number(data.subarray(at, space).toString('latin1'));
+    if (!Number.isInteger(length) || length <= 0) {throw new Error('the bundle archive has a malformed pax record');}
+    const body = data.subarray(space + 1, at + length - 1).toString('utf8');
+    const equals = body.indexOf('=');
+    records[body.slice(0, equals)] = body.slice(equals + 1);
+    at += length;
+  }
+  return records;
+}
+
+/** The entries of an uncompressed tar, in order. */
+function* readEntries(tar) {
+  let at = 0;
+  let pax = {};
+  while (at + BLOCK <= tar.length) {
+    const header = tar.subarray(at, at + BLOCK);
+    if (header.every((byte) => byte === 0)) {return;}
+    const size = readOctal(header, 124, 12);
+    const type = String.fromCharCode(header[156]);
+    const prefix = readString(header, 345, 155);
+    const name = readString(header, 0, 100);
+    const data = tar.subarray(at + BLOCK, at + BLOCK + size);
+    at += BLOCK + Math.ceil(size / BLOCK) * BLOCK;
+    if (type === TypeFlag.Pax) {
+      pax = parsePax(data);
+      continue;
+    }
+    if (![TypeFlag.File, TypeFlag.Symlink, TypeFlag.Directory].includes(type)) {
+      throw new Error(`the bundle archive has an entry of type "${type}", which a bundle never holds`);
+    }
+    const path = (pax.path ?? (prefix === '' ? name : `${prefix}/${name}`)).replace(/\/$/, '');
+    const linkname = pax.linkpath ?? readString(header, 157, 100);
+    yield { path, type, mode: readOctal(header, 100, 8), data, linkname };
+    pax = {};
+  }
+  throw new Error('the bundle archive ends without its end-of-archive marker');
+}
+
+/**
+ * Unpack the canonical bundle archive `archiveBytes` (the `.tgz`) into the existing, empty directory `destDir`.
+ * When `expectedDigest` is given the bytes are hashed first and a mismatch throws
+ * {@link BundleArchiveDigestMismatchError} before anything is written.
+ */
+export function unpackBundle(archiveBytes, destDir, { expectedDigest } = {}) {
+  if (expectedDigest !== undefined) {
+    const actual = archiveDigest(archiveBytes);
+    if (actual !== expectedDigest) {throw new BundleArchiveDigestMismatchError(expectedDigest, actual);}
+  }
+  const root = resolve(destDir);
+  const seen = new Set();
+  const links = new Set();
+  for (const entry of readEntries(gunzipSync(archiveBytes))) {
+    const relative = normalize(entry.path);
+    if (entry.path === '' || isAbsolute(entry.path) || relative === '..' || relative.startsWith(`..${sep}`)) {
+      throw new Error(`the bundle archive has an entry that leaves the bundle: "${entry.path}"`);
+    }
+    if (seen.has(relative)) {throw new Error(`the bundle archive lists "${entry.path}" twice`);}
+    seen.add(relative);
+    for (let parent = dirname(relative); parent !== '.'; parent = dirname(parent)) {
+      if (links.has(parent)) {throw new Error(`the bundle archive writes "${entry.path}" through the symlink "${parent}"`);}
+    }
+    const target = join(root, relative);
+    if (entry.type === TypeFlag.Directory) {
+      mkdirSync(target, { recursive: true, mode: 0o755 });
+    } else if (entry.type === TypeFlag.Symlink) {
+      const resolved = posix.normalize(posix.join(posix.dirname(entry.path), entry.linkname));
+      if (posix.isAbsolute(entry.linkname) || resolved === '..' || resolved.startsWith('../')) {
+        throw new Error(`the bundle archive has a symlink that leaves the bundle: "${entry.path}" -> "${entry.linkname}"`);
+      }
+      mkdirSync(dirname(target), { recursive: true });
+      symlinkSync(entry.linkname, target);
+      links.add(relative);
+    } else {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, entry.data, { mode: (entry.mode & 0o111) === 0 ? 0o644 : 0o755 });
+    }
+  }
+}

package/src/bundle-unpack.test.mjs

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { archiveDigest, canonicalTar, gzipCanonical } from './bundle-archive.mjs';
+import { bundleContentDigest } from './bundle-content.mjs';
+import { BundleArchiveDigestMismatchError, unpackBundle } from './bundle-unpack.mjs';
+
+const scratch = () => fs.mkdtempSync(path.join(os.tmpdir(), 'xema-unpack-'));
+
+function put(root, rel, content, mode) {
+  fs.mkdirSync(path.dirname(path.join(root, rel)), { recursive: true });
+  fs.writeFileSync(path.join(root, rel), content);
+  if (mode !== undefined) {fs.chmodSync(path.join(root, rel), mode);}
+}
+
+function sampleTree() {
+  const tree = scratch();
+  put(tree, 'dist/main.js', 'console.log(1);\n');
+  put(tree, 'bin/run.sh', '#!/bin/sh\n', 0o755);
+  put(tree, `deep/${'long-directory-name-'.repeat(8)}/${'file-name-'.repeat(12)}.txt`, 'long path\n');
+  put(tree, 'unicode/café.txt', 'non-ascii path\n');
+  fs.mkdirSync(path.join(tree, 'empty'));
+  fs.symlinkSync('../dist/main.js', path.join(tree, 'bin', 'main-link'));
+  fs.symlinkSync(`x/${'y'.repeat(150)}`, path.join(tree, 'long-link'));
+  return tree;
+}
+
+const pack = (tree) => gzipCanonical(canonicalTar(tree));
+
+test('a packed tree unpacks to the same content digest, the same modes, links and empty directories, and packs to the same bytes again', () => {
+  const tree = sampleTree();
+  const archive = pack(tree);
+  const out = scratch();
+
+  unpackBundle(archive, out, { expectedDigest: archiveDigest(archive) });
+
+  assert.equal(bundleContentDigest(out), bundleContentDigest(tree));
+  assert.equal(fs.statSync(path.join(out, 'bin/run.sh')).mode & 0o111, 0o111);
+  assert.equal(fs.statSync(path.join(out, 'dist/main.js')).mode & 0o111, 0);
+  assert.equal(fs.readlinkSync(path.join(out, 'bin/main-link')), '../dist/main.js');
+  assert.equal(fs.readlinkSync(path.join(out, 'long-link')), `x/${'y'.repeat(150)}`);
+  assert.deepEqual(fs.readdirSync(path.join(out, 'empty')), []);
+  assert.deepEqual(pack(out), archive);
+});
+
+test('bytes that do not hash to the expected digest are refused before anything is written', () => {
+  const archive = pack(sampleTree());
+  const out = scratch();
+
+  assert.throws(() => unpackBundle(archive, out, { expectedDigest: `sha256:${'0'.repeat(64)}` }), BundleArchiveDigestMismatchError);
+  assert.deepEqual(fs.readdirSync(out), []);
+});
+
+test('an archive that reaches outside the bundle is refused', () => {
+  const tree = scratch();
+  fs.symlinkSync('../../etc/passwd', path.join(tree, 'escape'));
+  const out = scratch();
+
+  assert.throws(() => unpackBundle(pack(tree), out), /leaves the bundle/);
+});

package/src/canonical-json.mjs

@@ -0,0 +1,9 @@
+/** Canonical JSON: keys sorted recursively, no whitespace. */
+export function canonicalJson(value) {
+  if (Array.isArray(value)) {return `[${value.map(canonicalJson).join(',')}]`;}
+  if (value !== null && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+

package/src/host-provided.mjs

@@ -0,0 +1,160 @@
+// What a member bundle must NOT carry: the packages the host provides (`IDENTITY_PACKAGES` of the in-image module:
+// `@nestjs/common`, `@nestjs/core`, `@nestjs/config`, `reflect-metadata` and the service SDK), and everything only they reach.
+// A bundle that shipped its own copy would be a second copy of a singleton beside the host's: `instanceof`, Nest's DI
+// metadata and module identity all break. So the host's packages are cut out of the member's pnpm install tree and the
+// rest is pruned to what the member's own dependencies still reach.
+//
+// The set is the caller's (`hostProvided`): the contracts package names it, this file only cuts it.
+// The cut is by symlink, not by directory name: in a pnpm tree a package is a real directory in
+// `node_modules/.pnpm/<entry>/node_modules/<name>` and every use of it is a symlink to there. Four steps:
+//   1. every `.pnpm` entry whose package is host-provided is deleted, injected `@file+` copies included;
+//   2. every symlink to a host-provided package, in any `node_modules` of the tree (the member's, each entry's, the hidden
+//      hoist, the root), is deleted;
+//   3. every `.pnpm` entry the member's `node_modules` no longer reaches by following symlinks is pruned (the host-provided
+//      packages' own dependencies, unless the member or another kept package shares them);
+//   4. a symlink left dangling is deleted, and a symlink whose target resolves outside the tree is refused: a bundle must
+//      not depend on the machine that packed it.
+// Every walk is sorted, so the same tree gives the same result.
+import { existsSync, lstatSync, readdirSync, readlinkSync, realpathSync, rmSync, unlinkSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+
+/** `<name>` of a `node_modules/.pnpm` entry (`@scope+name@1.0.0_peer@2…` → `@scope/name`). */
+export function pnpmEntryName(entry) {
+  const at = entry.indexOf('@', entry.startsWith('@') ? 1 : 0);
+  if (at <= 0) {return undefined;}
+  const flat = entry.slice(0, at);
+  return flat.startsWith('@') ? flat.replace('+', '/') : flat;
+}
+
+const NODE_MODULES = 'node_modules';
+const PNPM_DIRECTORY = '.pnpm';
+
+const byName = (a, b) => (a.name < b.name ? -1 : 1);
+const entriesOf = (dir) => readdirSync(dir, { withFileTypes: true }).sort(byName);
+
+/** Every entry under `dir`, symlinks reported and never followed, directories first-visited in sorted order: `visit(path, dirent)`. */
+function walk(dir, visit) {
+  for (const entry of entriesOf(dir)) {
+    const path = join(dir, entry.name);
+    visit(path, entry);
+    if (entry.isDirectory()) {walk(path, visit);}
+  }
+}
+
+/** The package slots of a `node_modules` directory: `[path, name]` for `<name>` and `@scope/<name>`, sorted; a scope directory is not a slot. */
+function slotsOf(modulesDir) {
+  const slots = [];
+  for (const entry of entriesOf(modulesDir)) {
+    if (entry.name.startsWith('.')) {continue;}
+    const path = join(modulesDir, entry.name);
+    if (entry.name.startsWith('@') && entry.isDirectory()) {
+      for (const inner of entriesOf(path)) {slots.push([join(path, inner.name), `${entry.name}/${inner.name}`]);}
+    } else {
+      slots.push([path, entry.name]);
+    }
+  }
+  return slots;
+}
+
+/** Where the symlink at `link` points: its target resolved from its real parent, then fully when it exists. */
+function linkTarget(link) {
+  const lexical = resolve(realpathSync(dirname(link)), readlinkSync(link));
+  return existsSync(link) ? realpathSync(link) : lexical;
+}
+
+const isInside = (root, path) => path === root || path.startsWith(root + sep);
+
+/** The `.pnpm` entry a path lies in, or `undefined` (the hidden hoist and anything outside `.pnpm` are no entry). */
+function entryOf(pnpmDir, path) {
+  if (!isInside(pnpmDir, path) || path === pnpmDir) {return undefined;}
+  const first = relative(pnpmDir, path).split(sep)[0];
+  return first === NODE_MODULES ? undefined : first;
+}
+
+/** Delete every `.pnpm` entry whose package is in `hostProvided`; returns the count. */
+function removeHostEntries(pnpmDir, hostProvided) {
+  let removed = 0;
+  for (const entry of entriesOf(pnpmDir)) {
+    if (!entry.isDirectory() || entry.name === NODE_MODULES || !hostProvided.has(pnpmEntryName(entry.name))) {continue;}
+    rmSync(join(pnpmDir, entry.name), { recursive: true });
+    removed += 1;
+  }
+  return removed;
+}
+
+/** Delete every symlink in a `node_modules` slot of the tree that names a host-provided package; returns the count. */
+function removeHostLinks(treeRoot, hostProvided) {
+  const links = [];
+  walk(treeRoot, (path, entry) => {
+    if (entry.name !== NODE_MODULES || !entry.isDirectory()) {return;}
+    for (const [slot, name] of slotsOf(path)) {
+      if (hostProvided.has(name) && lstatSync(slot).isSymbolicLink()) {links.push(slot);}
+    }
+  });
+  for (const link of links) {unlinkSync(link);}
+  return links.length;
+}
+
+/** The `.pnpm` entries the members' `node_modules` (`memberModules`) reach through symlinks, a reached entry's own `node_modules` siblings being its dependencies. */
+function reachableEntries({ pnpmDir, memberModules }) {
+  const reached = new Set();
+  const pending = [];
+  const follow = (slotPath) => {
+    if (!lstatSync(slotPath).isSymbolicLink()) {return;}
+    const entry = entryOf(pnpmDir, linkTarget(slotPath));
+    if (entry !== undefined && !reached.has(entry)) {
+      reached.add(entry);
+      pending.push(entry);
+    }
+  };
+  for (const modules of memberModules.filter((dir) => existsSync(dir))) {for (const [slot] of slotsOf(modules)) {follow(slot);}}
+  while (pending.length > 0) {
+    const modules = join(pnpmDir, pending.pop(), NODE_MODULES);
+    if (existsSync(modules)) {for (const [slot] of slotsOf(modules)) {follow(slot);}}
+  }
+  return reached;
+}
+
+/** Delete the `.pnpm` entries not in `reached`; returns the count. */
+function pruneUnreached(pnpmDir, reached) {
+  let pruned = 0;
+  for (const entry of entriesOf(pnpmDir)) {
+    if (!entry.isDirectory() || entry.name === NODE_MODULES || reached.has(entry.name)) {continue;}
+    rmSync(join(pnpmDir, entry.name), { recursive: true });
+    pruned += 1;
+  }
+  return pruned;
+}
+
+/** Delete every dangling symlink of the tree and refuse one that points outside it; returns the deleted count. */
+function removeDangling(treeRoot) {
+  const real = realpathSync(treeRoot);
+  const dangling = [];
+  const escaping = [];
+  walk(treeRoot, (path, entry) => {
+    if (!entry.isSymbolicLink()) {return;}
+    if (!isInside(real, linkTarget(path))) {escaping.push(`${relative(treeRoot, path)} -> ${readlinkSync(path)}`);}
+    else if (!existsSync(path)) {dangling.push(path);}
+  });
+  if (escaping.length > 0) {
+    throw new Error(`the bundle tree holds ${escaping.length} symlink(s) that point outside it:\n${escaping.map((p) => `  - ${p}`).join('\n')}`);
+  }
+  for (const link of dangling) {unlinkSync(link);}
+  return dangling.length;
+}
+
+/**
+ * Cut the host-provided packages (`hostProvided`: package names, the caller's: this module owns no default) out of the pnpm
+ * install tree under `treeRoot` and prune what only they reached from every `<treeRoot>/<memberDirectory>/node_modules`.
+ * Returns `{ removedLinks, removedEntries, pruned }`.
+ */
+export function excludeHostProvided({ treeRoot, memberDirectories, hostProvided }) {
+  const provided = new Set(hostProvided);
+  const pnpmDir = join(realpathSync(treeRoot), NODE_MODULES, PNPM_DIRECTORY);
+  const hasStore = existsSync(pnpmDir);
+  const removedEntries = hasStore ? removeHostEntries(pnpmDir, provided) : 0;
+  const removedLinks = removeHostLinks(treeRoot, provided);
+  const pruned = hasStore ? pruneUnreached(pnpmDir, reachableEntries({ pnpmDir, memberModules: memberDirectories.map((directory) => join(realpathSync(treeRoot), directory, NODE_MODULES)) })) : 0;
+  return { removedLinks: removedLinks + removeDangling(treeRoot), removedEntries, pruned };
+}

package/src/host-provided.test.mjs

@@ -0,0 +1,128 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { excludeHostProvided, pnpmEntryName } from './host-provided.mjs';
+
+const IDENTITY_PACKAGES = ['@nestjs/common', '@nestjs/core', '@nestjs/config', 'reflect-metadata', '@xemahq/xema-service-nest'];
+
+const MEMBER = 'biomes/alpha/api/alpha-api';
+
+function pkg(tree, entry, name) {
+  const dir = path.join(tree, 'node_modules/.pnpm', entry, 'node_modules', name);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name }));
+}
+
+/** `<from>/<name>` links to `<to>`, a path relative to the directory holding the link. */
+function link(from, name, to) {
+  const at = path.join(from, name);
+  fs.mkdirSync(path.dirname(at), { recursive: true });
+  fs.symlinkSync(to, at);
+}
+
+const inEntry = (tree, entry) => path.join(tree, 'node_modules/.pnpm', entry, 'node_modules');
+
+/** A pnpm-shaped tree: the member links its deps; @nestjs/core reaches `core-only` and the shared dep; the SDK reaches `sdk-only`. */
+function fixture() {
+  const tree = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-host-provided-'));
+  const store = path.join(tree, 'node_modules/.pnpm');
+  const entries = {
+    'app-dep@1.0.0': 'app-dep',
+    'shared@1.0.0': 'shared',
+    'with-peer@1.0.0_@nestjs+common@10.0.0': 'with-peer',
+    '@nestjs+common@10.0.0': '@nestjs/common',
+    '@nestjs+core@10.0.0': '@nestjs/core',
+    'core-only@1.0.0': 'core-only',
+    'common-only@1.0.0': 'common-only',
+    '@xemahq+xema-service-nest@file+packages+sdk': '@xemahq/xema-service-nest',
+    'sdk-only@1.0.0': 'sdk-only',
+  };
+  for (const [entry, name] of Object.entries(entries)) {pkg(tree, entry, name);}
+  const dep = (entry, name, target, targetName = target.split('@')[0]) =>
+    link(inEntry(tree, entry), name, `${'../'.repeat(name.split('/').length)}../${target}/node_modules/${targetName}`);
+  dep('app-dep@1.0.0', 'shared', 'shared@1.0.0');
+  dep('with-peer@1.0.0_@nestjs+common@10.0.0', '@nestjs/common', '@nestjs+common@10.0.0', '@nestjs/common');
+  dep('@nestjs+common@10.0.0', 'common-only', 'common-only@1.0.0');
+  dep('@nestjs+core@10.0.0', '@nestjs/common', '@nestjs+common@10.0.0', '@nestjs/common');
+  dep('@nestjs+core@10.0.0', 'core-only', 'core-only@1.0.0');
+  dep('@nestjs+core@10.0.0', 'shared', 'shared@1.0.0');
+  dep('@xemahq+xema-service-nest@file+packages+sdk', 'sdk-only', 'sdk-only@1.0.0');
+  dep('@xemahq+xema-service-nest@file+packages+sdk', '@nestjs/core', '@nestjs+core@10.0.0', '@nestjs/core');
+
+  const member = path.join(tree, MEMBER, 'node_modules');
+  const up = '../'.repeat(MEMBER.split('/').length + 1);
+  const fromMember = (name, entry, target = name) => link(member, name, `${up}node_modules/.pnpm/${entry}/node_modules/${target}`);
+  fromMember('app-dep', 'app-dep@1.0.0');
+  fromMember('shared', 'shared@1.0.0');
+  fromMember('with-peer', 'with-peer@1.0.0_@nestjs+common@10.0.0');
+  fromMember('@nestjs/common', '@nestjs+common@10.0.0');
+  fromMember('@nestjs/core', '@nestjs+core@10.0.0');
+  fromMember('@xemahq/xema-service-nest', '@xemahq+xema-service-nest@file+packages+sdk');
+  fs.mkdirSync(path.join(member, '.prisma/client'), { recursive: true });
+
+  const hoist = path.join(store, 'node_modules');
+  link(hoist, 'shared', '../shared@1.0.0/node_modules/shared');
+  link(hoist, '@nestjs/common', '../../@nestjs+common@10.0.0/node_modules/@nestjs/common');
+  link(hoist, 'core-only', '../core-only@1.0.0/node_modules/core-only');
+  link(path.join(tree, 'node_modules'), '@nestjs/core', '../.pnpm/@nestjs+core@10.0.0/node_modules/@nestjs/core');
+  return tree;
+}
+
+const exists = (p) => fs.lstatSync(p, { throwIfNoEntry: false }) !== undefined;
+
+function danglingLinks(dir) {
+  const found = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isSymbolicLink()) {if (!fs.existsSync(p)) {found.push(p);}}
+    else if (entry.isDirectory()) {found.push(...danglingLinks(p));}
+  }
+  return found;
+}
+
+test('the host-provided packages, their links and what only they reached are gone; ordinary deps stay', () => {
+  const tree = fixture();
+  const counts = excludeHostProvided({ treeRoot: tree, memberDirectories: [MEMBER], hostProvided: IDENTITY_PACKAGES });
+  const store = path.join(tree, 'node_modules/.pnpm');
+  const member = path.join(tree, MEMBER, 'node_modules');
+
+  for (const gone of ['@nestjs+common@10.0.0', '@nestjs+core@10.0.0', '@xemahq+xema-service-nest@file+packages+sdk']) {assert.ok(!exists(path.join(store, gone)), gone);}
+  for (const gone of ['@nestjs/common', '@nestjs/core', '@xemahq/xema-service-nest']) {assert.ok(!exists(path.join(member, gone)), `member link ${gone}`);}
+  assert.ok(!exists(path.join(store, 'node_modules/@nestjs/common')), 'hidden hoist link');
+  assert.ok(!exists(path.join(tree, 'node_modules/@nestjs/core')), 'root link');
+  assert.ok(!exists(path.join(inEntry(tree, 'with-peer@1.0.0_@nestjs+common@10.0.0'), '@nestjs/common')), 'peer link');
+
+  for (const pruned of ['core-only@1.0.0', 'common-only@1.0.0', 'sdk-only@1.0.0']) {assert.ok(!exists(path.join(store, pruned)), `${pruned} was reached only through a host package`);}
+  assert.ok(!exists(path.join(store, 'node_modules/core-only')), 'its hoist link is not left dangling');
+
+  for (const kept of ['app-dep@1.0.0', 'shared@1.0.0', 'with-peer@1.0.0_@nestjs+common@10.0.0']) {assert.ok(exists(path.join(store, kept)), kept);}
+  for (const kept of ['app-dep', 'shared', 'with-peer']) {assert.ok(fs.existsSync(path.join(member, kept, 'package.json')), `member keeps ${kept}`);}
+  assert.ok(fs.existsSync(path.join(inEntry(tree, 'app-dep@1.0.0'), 'shared/package.json')), 'a dep shared with @nestjs/core stays reachable');
+  assert.ok(exists(path.join(member, '.prisma/client')));
+  assert.deepEqual(danglingLinks(tree), []);
+  assert.equal(counts.removedEntries, 3);
+  assert.equal(counts.pruned, 3);
+  assert.ok(counts.removedLinks >= 6);
+});
+
+test('the result is the same when run twice', () => {
+  const tree = fixture();
+  excludeHostProvided({ treeRoot: tree, memberDirectories: [MEMBER], hostProvided: IDENTITY_PACKAGES });
+  assert.deepEqual(excludeHostProvided({ treeRoot: tree, memberDirectories: [MEMBER], hostProvided: IDENTITY_PACKAGES }), { removedLinks: 0, removedEntries: 0, pruned: 0 });
+});
+
+test('a symlink that points outside the tree is refused', () => {
+  const tree = fixture();
+  const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'xema-outside-'));
+  fs.symlinkSync(outside, path.join(tree, MEMBER, 'node_modules/escape'));
+  assert.throws(() => excludeHostProvided({ treeRoot: tree, memberDirectories: [MEMBER], hostProvided: IDENTITY_PACKAGES }), /point outside it:\n {2}- .*escape/);
+});
+
+test('pnpmEntryName reads scoped, unscoped and peer-suffixed .pnpm entries', () => {
+  assert.equal(pnpmEntryName('prisma@7.8.0_@types+react@19.3.0'), 'prisma');
+  assert.equal(pnpmEntryName('@prisma+client@7.8.0_prisma@7.8.0'), '@prisma/client');
+  assert.equal(pnpmEntryName('node_modules'), undefined);
+});

package/src/member-required-env.mjs

@@ -0,0 +1,32 @@
+// The NAMES of the environment a built member entry requires, read from the entry itself: its `main.js` passes them to
+// `bootstrapXemaService`, and the member's own copy of `@xemahq/xema-service-nest` captures that call without booting
+// (`readServiceEntry`). The same capture the seed closure derivation uses, so the code stays the one declaration.
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+
+import { MemberRequiredEnvVarsSchema, ProcessMemberKindSchema, processMemberKindOfCapture } from '@xemahq/contracts/process-topology';
+
+/**
+ * What ONE capture of the entry at `entryPath` yields, resolved through the SDK copy installed beside `packageRoot` (the
+ * directory holding the member's `package.json` and `node_modules`): the sorted, de-duplicated `requiredEnvVars` (names only; the
+ * schema refuses a NAME=value) and the member's `kind`, from which bootstrap function the entry calls (`entry.kind`).
+ */
+export function memberEntryFacts({ packageRoot, entryPath }) {
+  const memberRequire = createRequire(join(packageRoot, 'package.json'));
+  let serviceNest;
+  try {
+    serviceNest = memberRequire('@xemahq/xema-service-nest');
+  } catch (cause) {
+    throw new Error(`cannot read the required environment of ${entryPath}: @xemahq/xema-service-nest is not installed beside ${packageRoot}`, { cause });
+  }
+  const captured = serviceNest.readServiceEntry(entryPath, {});
+  return {
+    requiredEnvVars: MemberRequiredEnvVarsSchema.parse([...new Set(captured.entry.options.requiredEnvVars ?? [])].sort()),
+    kind: ProcessMemberKindSchema.parse(processMemberKindOfCapture(captured.entry.kind)),
+  };
+}
+
+/** The `requiredEnvVars` of {@link memberEntryFacts}. */
+export function memberRequiredEnvVars(input) {
+  return memberEntryFacts(input).requiredEnvVars;
+}