@xemahq/repo-build-tooling 0.9.2 → 0.10.1

package/README.md

@@ -108,6 +108,25 @@ build carries every composable platform service of the repository at one commit.
 Every step refuses rather than skips. The tool has no dependencies: the host and
 the kernel schema are resolved from the members being built.
 
+### `xema-service-bootstrap [--check] [--filter <key>] [--root <dir>]`
+
+Generates the descriptors `@xemahq/xema-service-nest` boots from, out of the
+repository's own `xema-biome.json` manifests. For every `kind: service` component
+it writes `src/generated/<name>.bootstrap.generated.ts` (a `BiomeServiceDescriptor`),
+and for every `kind: worker` component `src/generated/<key>.worker-descriptor.generated.ts`
+(a `XemaWorkerDescriptor`; a `shared-oci-image` worker lands in the package of the
+component whose image it shares). Only packages that declare
+`@xemahq/xema-service-nest` are written to.
+
+`requirements.scaling.concurrency.maximumPerInstance` becomes
+`maximumConcurrentRequests` on a service and `maximumConcurrentActivities` on a
+worker. A component without a positive integer there is refused, naming the
+manifest and the component.
+
+`--check` writes nothing and fails on any drift. A run that finds no manifest, or no
+service or worker to generate, fails rather than reporting success. Run it from the
+repository root, or pass `--root`.
+
 ## Scope boundary
 
 Dev-time tooling that **more than one repository** runs. Two rules keep it from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.9.2",
+  "version": "0.10.1",
   "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)",
@@ -25,7 +25,8 @@
     "xema-check-workspace-ranges": "src/check-workspace-range-matches-local.mjs",
     "xema-composed-image": "src/composed-image.mjs",
     "xema-readiness": "src/readiness.mjs",
-    "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs"
+    "xema-scrub-swagger-paths": "src/scrub-swagger-plugin-paths.mjs",
+    "xema-service-bootstrap": "src/service-bootstrap.mjs"
   },
   "exports": {
     "./check-no-vendored-deps": "./src/check-no-vendored-deps.mjs",
@@ -34,12 +35,13 @@
     "./ghcr-manifest": "./src/ghcr-manifest.mjs",
     "./package.json": "./package.json",
     "./readiness": "./src/readiness.mjs",
-    "./scrub-swagger-plugin-paths": "./src/scrub-swagger-plugin-paths.mjs"
+    "./scrub-swagger-plugin-paths": "./src/scrub-swagger-plugin-paths.mjs",
+    "./service-bootstrap": "./src/service-bootstrap.mjs"
   },
   "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/ghcr-manifest.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"
+    "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/ghcr-manifest.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/registry-fetch.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:a1775245f7e0b751aeab7d53393103ddc32079c97043755a22b9fa261fa05134"
+    "sourceDigest": "sha256:35b4aafd2345b2d892fff707b22790985f6ae1e20f75d0f7467f3401f8b583d2"
   }
 }

package/src/composed-image.mjs

@@ -77,6 +77,7 @@ import { pathToFileURL } from 'node:url';
 
 import { COMPOSED_IMAGE_DIR } from './composed-image-paths.mjs';
 import { composedCoordinate, emitCoordinate } from './composed-image-coordinate.mjs';
+import { describeErrorChain } from './registry-fetch.mjs';
 import { syncComposedDockerfile } from './composed-image-dockerfile.mjs';
 import { runImageLoad } from './load-image.mjs';
 import { runRefusalSmoke } from './smoke-refusal.mjs';
@@ -553,7 +554,9 @@ if (invokedPath !== undefined && import.meta.url === pathToFileURL(invokedPath).
     // the verdict is in, so the step ends here rather than on their timers.
     process.exit(0);
   } catch (error) {
-    console.error(`xema-composed-image: ${error.message}`);
+    const [head, ...causes] = describeErrorChain(error);
+    console.error(`xema-composed-image: ${error?.message ?? head}`);
+    for (const cause of causes) console.error(`  caused by ${cause}`);
     process.exit(1);
   }
 }

package/src/ghcr-manifest.mjs

@@ -4,6 +4,8 @@
 // Only 200 and 404 are answers; anything else throws, so an unreachable or
 // unauthorised registry can never read as "missing" and trigger a rebuild.
 
+import { registryFetch } from './registry-fetch.mjs';
+
 const MANIFEST_ACCEPT = [
   'application/vnd.oci.image.index.v1+json',
   'application/vnd.oci.image.manifest.v1+json',
@@ -38,7 +40,7 @@ export async function acquireGhcrPullToken({ registry, repository, user, token,
   const url = new URL(`https://${registry}/token`);
   url.searchParams.set('service', registry);
   url.searchParams.set('scope', `repository:${repository}:pull`);
-  const response = await fetchImpl(url, {
+  const response = await registryFetch(fetchImpl, url, {
     method: 'GET',
     headers: { Authorization: basicAuthorization(user, token), Accept: 'application/json' },
   });
@@ -60,7 +62,7 @@ export async function acquireGhcrPullToken({ registry, repository, user, token,
 /** Returns `true` only for a proven existing manifest and `false` only for 404. */
 export async function ghcrManifestExists({ registry, repository, contentHash, user, token, fetchImpl = fetch }) {
   const bearer = await acquireGhcrPullToken({ registry, repository, user, token, fetchImpl });
-  const response = await fetchImpl(`https://${registry}/v2/${repository}/manifests/${contentHash}`, {
+  const response = await registryFetch(fetchImpl, `https://${registry}/v2/${repository}/manifests/${contentHash}`, {
     method: 'HEAD',
     headers: { Authorization: `Bearer ${bearer}`, Accept: MANIFEST_ACCEPT },
   });

package/src/registry-fetch.mjs

@@ -0,0 +1,82 @@
+// The one place a registry request is sent and a network failure is named.
+//
+// Node's fetch rejects with `TypeError: fetch failed` and keeps the real reason
+// (ENOTFOUND, ECONNREFUSED, a TLS error, a timeout) in `error.cause`. Letting that
+// escape as a bare message hides which request failed and why.
+
+/** The URL with credentials and every query value removed; only the query keys remain. */
+export function redactUrl(input) {
+  let url;
+  try {
+    url = new URL(String(input));
+  } catch {
+    return '<unparseable url>';
+  }
+  url.username = '';
+  url.password = '';
+  const keys = [...new Set(url.searchParams.keys())];
+  url.search = '';
+  url.hash = '';
+  return keys.length > 0 ? `${url.href}?${keys.map((key) => `${key}=<redacted>`).join('&')}` : url.href;
+}
+
+function describeOne(error) {
+  if (!(error instanceof Error)) return String(error);
+  const details = ['code', 'errno', 'syscall', 'hostname', 'address', 'port']
+    .filter((key) => error[key] !== undefined)
+    .map((key) => `${key}=${error[key]}`);
+  const head = `${error.name}: ${error.message}`;
+  return details.length > 0 ? `${head} (${details.join(', ')})` : head;
+}
+
+/** One line per link of the `cause` chain, outermost first. Bounded against cycles. */
+export function describeErrorChain(error) {
+  const lines = [];
+  const seen = new Set();
+  for (let current = error; current !== undefined && !seen.has(current) && lines.length < 10; ) {
+    lines.push(describeOne(current));
+    if (!(current instanceof Error)) break;
+    seen.add(current);
+    current = current.cause;
+  }
+  return lines;
+}
+
+/** Total attempts per request, the first included. */
+export const MAX_ATTEMPTS = 3;
+/** Fixed wait in milliseconds after failed attempt n (1-based); deterministic, no jitter. */
+export const RETRY_BACKOFF_MS = [1000, 3000];
+
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function causeCode(error) {
+  for (let current = error, depth = 0; current instanceof Error && depth < 10; current = current.cause, depth += 1) {
+    if (current.code !== undefined) return String(current.code);
+  }
+  return 'unknown';
+}
+
+/**
+ * Send one registry request. Only a transport failure (the fetch promise rejects) is
+ * retried (an abort, `AbortError` or an aborted `init.signal`, is rethrown at once), up to MAX_ATTEMPTS with RETRY_BACKOFF_MS between attempts; any HTTP response,
+ * whatever its status, is returned as is. The final failure is thrown naming the method,
+ * the redacted URL and the attempt count, with the last error as `cause`. Headers are
+ * never reported. `options.sleep` replaces the real wait (for tests).
+ */
+export async function registryFetch(fetchImpl, url, init, { sleep = realSleep } = {}) {
+  const method = init?.method ?? 'GET';
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await fetchImpl(url, init);
+    } catch (error) {
+      if (error?.name === 'AbortError' || init?.signal?.aborted === true) throw error;
+      if (attempt >= MAX_ATTEMPTS) {
+        throw new Error(`${method} ${redactUrl(url)} failed after ${attempt} attempts`, { cause: error });
+      }
+      process.stderr.write(
+        `registry request failed (attempt ${attempt} of ${MAX_ATTEMPTS}): ${method} ${redactUrl(url)} cause=${causeCode(error)}; retrying\n`,
+      );
+      await sleep(RETRY_BACKOFF_MS[attempt - 1]);
+    }
+  }
+}

package/src/registry-fetch.test.mjs

@@ -0,0 +1,151 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import { MAX_ATTEMPTS, RETRY_BACKOFF_MS, describeErrorChain, redactUrl, registryFetch } from './registry-fetch.mjs';
+
+const BIN = path.join(path.dirname(fileURLToPath(import.meta.url)), 'composed-image.mjs');
+
+async function closedPort() {
+  const server = net.createServer();
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address();
+  await new Promise((resolve) => server.close(resolve));
+  return port;
+}
+
+test('redactUrl drops credentials, query values and the fragment', () => {
+  const out = redactUrl('https://user:pw@ghcr.io/token?service=ghcr.io&scope=secret-scope#frag');
+  assert.equal(out, 'https://ghcr.io/token?service=<redacted>&scope=<redacted>');
+  assert.equal(redactUrl('not a url'), '<unparseable url>');
+});
+
+test('a refused connection names the method, the URL and the cause code, never the headers', async () => {
+  const port = await closedPort();
+  const url = `http://127.0.0.1:${port}/v2/org/img/manifests/abc?access_token=SECRETQ`;
+  const error = await registryFetch(fetch, url, { method: 'HEAD', headers: { Authorization: 'Bearer SECRETH' } }, { sleep: async () => {} }).then(
+    () => assert.fail('expected the request to fail'),
+    (caught) => caught,
+  );
+  const text = [error.message, ...describeErrorChain(error)].join('\n');
+  assert.match(error.message, new RegExp(`^HEAD http://127\\.0\\.0\\.1:${port}/v2/org/img/manifests/abc\\?access_token=<redacted> failed after 3 attempts$`));
+  assert.match(text, /ECONNREFUSED/);
+  assert.doesNotMatch(text, /SECRETQ|SECRETH/);
+});
+
+test('describeErrorChain walks the cause chain and survives a cycle', () => {
+  const inner = Object.assign(new Error('getaddrinfo ENOTFOUND ghcr.io'), { code: 'ENOTFOUND', hostname: 'ghcr.io' });
+  const outer = new TypeError('fetch failed', { cause: inner });
+  inner.cause = outer;
+  const lines = describeErrorChain(outer);
+  assert.equal(lines.length, 2);
+  assert.match(lines[1], /code=ENOTFOUND, hostname=ghcr\.io/);
+});
+
+test('the CLI prints the failing request and the cause chain to stderr and exits 1', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fetch-cause-'));
+  try {
+    const hashDir = path.join(root, 'node_modules', '@xemahq', 'distribution-source-hash');
+    fs.mkdirSync(hashDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(hashDir, 'package.json'),
+      JSON.stringify({ name: '@xemahq/distribution-source-hash', bin: { 'xema-compute-image-tag': 'bin.js' } }),
+    );
+    fs.writeFileSync(path.join(hashDir, 'bin.js'), `console.log('${'a'.repeat(64)}');\n`);
+    fs.writeFileSync(path.join(root, 'package.json'), '{}');
+    const preload = path.join(root, 'preload.mjs');
+    fs.writeFileSync(
+      preload,
+      `globalThis.fetch = async () => { throw new TypeError('fetch failed', { cause: Object.assign(new Error('getaddrinfo ENOTFOUND ghcr.io'), { code: 'ENOTFOUND', hostname: 'ghcr.io' }) }); };\n`,
+    );
+    const result = spawnSync(process.execPath, ['--import', preload, BIN, 'coordinate', '--image-name', 'img'], {
+      cwd: root,
+      encoding: 'utf8',
+      env: {
+        PATH: process.env.PATH,
+        SHA: 'b'.repeat(40),
+        REGISTRY: 'ghcr.io',
+        REGISTRY_ORG: 'org',
+        REGISTRY_USER: 'u',
+        REGISTRY_TOKEN: 'TOPSECRET',
+      },
+    });
+    assert.equal(result.status, 1);
+    assert.match(result.stderr, /GET https:\/\/ghcr\.io\/token\?service=<redacted>&scope=<redacted> failed after 3 attempts/);
+    assert.match(result.stderr, /caused by TypeError: fetch failed/);
+    assert.match(result.stderr, /caused by Error: getaddrinfo ENOTFOUND ghcr\.io \(code=ENOTFOUND, hostname=ghcr\.io\)/);
+    assert.doesNotMatch(result.stderr, /TOPSECRET/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+const transportError = () =>
+  new TypeError('fetch failed', { cause: Object.assign(new Error('getaddrinfo EAI_AGAIN ghcr.io'), { code: 'EAI_AGAIN' }) });
+
+test('a transient transport failure is retried once and then returns the response', async () => {
+  let calls = 0;
+  const waits = [];
+  const response = new Response('ok', { status: 200 });
+  const fetchImpl = async () => {
+    calls += 1;
+    if (calls === 1) throw transportError();
+    return response;
+  };
+  const result = await registryFetch(fetchImpl, 'https://ghcr.io/token?scope=x', { method: 'GET' }, { sleep: async (ms) => waits.push(ms) });
+  assert.equal(calls, 2);
+  assert.equal(result, response);
+  assert.deepEqual(waits, [RETRY_BACKOFF_MS[0]]);
+});
+
+test('three transport failures throw naming 3 attempts and keep the cause chain', async () => {
+  let calls = 0;
+  const waits = [];
+  const fetchImpl = async () => {
+    calls += 1;
+    throw transportError();
+  };
+  const error = await registryFetch(fetchImpl, 'https://ghcr.io/v2/o/i/manifests/a', { method: 'HEAD' }, { sleep: async (ms) => waits.push(ms) }).then(
+    () => assert.fail('expected failure'),
+    (caught) => caught,
+  );
+  assert.equal(calls, MAX_ATTEMPTS);
+  assert.deepEqual(waits, [1000, 3000]);
+  assert.equal(error.message, 'HEAD https://ghcr.io/v2/o/i/manifests/a failed after 3 attempts');
+  assert.match(describeErrorChain(error).join('\n'), /fetch failed[\s\S]*code=EAI_AGAIN/);
+});
+
+test('an HTTP error status is returned after one call, never retried', async () => {
+  let calls = 0;
+  const fetchImpl = async () => {
+    calls += 1;
+    return new Response('down', { status: 503 });
+  };
+  const result = await registryFetch(fetchImpl, 'https://ghcr.io/token', { method: 'GET' }, { sleep: async () => assert.fail('must not sleep') });
+  assert.equal(calls, 1);
+  assert.equal(result.status, 503);
+});
+
+test('an abort is rethrown at once, never retried', async () => {
+  let calls = 0;
+  const controller = new AbortController();
+  controller.abort();
+  const fetchImpl = async () => {
+    calls += 1;
+    throw new Error('request failed');
+  };
+  const error = await registryFetch(fetchImpl, 'https://ghcr.io/token', { method: 'GET', signal: controller.signal }, { sleep: async () => assert.fail('must not sleep') }).then(
+    () => assert.fail('expected failure'),
+    (caught) => caught,
+  );
+  assert.equal(calls, 1);
+  assert.equal(error.message, 'request failed');
+  let named = 0;
+  await registryFetch(async () => { named += 1; throw new DOMException('aborted', 'AbortError'); }, 'https://ghcr.io/token', {}, { sleep: async () => assert.fail('must not sleep') }).catch(() => {});
+  assert.equal(named, 1);
+});

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

@@ -167,12 +167,15 @@ const FLAT_LEAK_REGEX = new RegExp(
 // 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 1: relative path from the scrubbed file to the package directory.
 // Capture group 2: first path segment after dist/ = the subpath export name.
+// 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',
 );
 
@@ -416,6 +419,28 @@ function publicSpecifierFor(resolveFrom, pkg, subpath, original) {
   );
 }
 
+/**
+ * The npm name of the workspace package at `packageDir`, read from the
+ * package.json AT that directory. No walk-up: an ancestor's manifest (usually
+ * the workspace root) names a different package. Never a fixed scope or the
+ * directory name.
+ */
+function packageNameAt(packageDir, original) {
+  const manifest = join(packageDir, 'package.json');
+  let raw;
+  try {
+    raw = readFileSync(manifest, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT' && err.code !== 'ENOTDIR') throw err;
+    throw new ScrubFailure(`${packageDir} has no package.json, so no specifier can be derived for\n  ${original}`);
+  }
+  const { name } = JSON.parse(raw);
+  if (typeof name !== 'string' || name === '') {
+    throw new ScrubFailure(`${manifest} has no "name", so no specifier can be derived for\n  ${original}`);
+  }
+  return name;
+}
+
 async function* walk(dir) {
   let entries;
   try {
@@ -561,9 +586,10 @@ async function scrubFile(path) {
         `  rather than reaching through dist/.`,
     );
   }
-  out = out.replace(RELATIVE_WORKSPACE_REGEX, (_match, pkgName, subpath) => {
+  out = out.replace(RELATIVE_WORKSPACE_REGEX, (match, relPackageDir, subpath) => {
     count += 1;
-    return `require("@xemahq/${pkgName}/${subpath}")`;
+    const name = packageNameAt(resolve(dirname(path), relPackageDir), match);
+    return `require("${name}/${subpath}")`;
   });
   if (count > 0) {
     await writeFile(path, out, 'utf8');
@@ -796,6 +822,59 @@ async function selfTest() {
       throw new Error(`self-test: rewritten file still leaks: ${greenAfter}`);
     }
 
+    // 4b. RELATIVE-WORKSPACE — the rewritten specifier is the target package's
+    // own manifest `name`: scoped, unscoped, and name != directory.
+    const ws = join(root, 'ws');
+    const pkgs = [
+      ['packages/contracts/scoped-dir', '@xemahq/scoped-dir'],
+      ['packages/contracts/plain-dir', 'plain-contract'],
+      ['packages/contracts/other-dir', '@xemahq/renamed'],
+    ];
+    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 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(
+      wsFile,
+      `class Dto {\n  static _OPENAPI_METADATA_FACTORY() {\n    return { ${pkgs
+        .map(([dir], i) => `k${i}: () => require("${relOf(dir)}")`)
+        .join(', ')} };\n  }\n}\n`,
+      'utf8',
+    );
+    await run([join(ws, 'services/svc/dist')]);
+    const wsAfter = await readFile(wsFile, 'utf8');
+    for (const expected of ['require("@xemahq/scoped-dir/lib")', 'require("plain-contract/lib")', 'require("@xemahq/renamed/lib")']) {
+      if (!wsAfter.includes(expected)) {
+        throw new Error(`self-test: relative-workspace rewrite missing ${expected}: ${wsAfter}`);
+      }
+    }
+    // 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 });
+    await writeFile(
+      join(orphan, 'svc/dist/dto.js'),
+      'class D {\n  static _OPENAPI_METADATA_FACTORY() {\n    return { a: () => require("../../packages/none/dist/lib/x") };\n  }\n}\n',
+      'utf8',
+    );
+    await expectFailure('relative workspace target without package.json', () => run([join(orphan, 'svc/dist')]));
+
+    // An ANCESTOR's package.json must not stand in for the target's own.
+    const walkup = join(root, 'walkup');
+    await mkdir(join(walkup, 'packages/none/dist/lib'), { recursive: true });
+    await mkdir(join(walkup, 'svc/dist'), { recursive: true });
+    await writeFile(join(walkup, 'package.json'), JSON.stringify({ name: 'workspace-root' }), 'utf8');
+    await writeFile(
+      join(walkup, 'svc/dist/dto.js'),
+      'class D {\n  static _OPENAPI_METADATA_FACTORY() {\n    return { a: () => require("../../packages/none/dist/lib/x") };\n  }\n}\n',
+      'utf8',
+    );
+    await expectFailure('relative workspace target without package.json but with an ancestor that has one', () =>
+      run([join(walkup, 'svc/dist')]),
+    );
+
     // 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

package/src/service-bootstrap-concurrency.mjs

@@ -0,0 +1,49 @@
+/**
+ * The per-instance concurrency a component declares, read from its manifest.
+ *
+ * `xema.components[].requirements.scaling.concurrency.maximumPerInstance` is a
+ * REQUIRED positive integer in the kernel schema. For a service it is the
+ * maximum concurrent requests; for a worker, the maximum concurrent activities
+ * per instance. The SDK descriptors carry it as a required field, so the
+ * generator refuses a component without it instead of emitting a descriptor
+ * that guesses a limit.
+ */
+
+/** @returns {number} the declared positive integer; throws naming manifest and component. */
+export function readMaximumPerInstance(component, manifestRel) {
+  const value = component?.requirements?.scaling?.concurrency?.maximumPerInstance;
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(
+      `[xema-service-bootstrap] ${manifestRel} component "${component?.key}" must declare ` +
+        '`requirements.scaling.concurrency.maximumPerInstance` as a positive integer ' +
+        `(found ${JSON.stringify(value)}). It is the component's per-instance concurrency limit.`,
+    );
+  }
+  return value;
+}
+
+/**
+ * The Nexus handler budget of a worker component:
+ * `requirements.scaling.concurrency.maximumNexusOperationsPerInstance`, its
+ * own term beside `maximumPerInstance`. 0 for a component that provides no
+ * Nexus service (the kernel schema refuses the field there). A component that
+ * DOES provide one must declare it as a positive integer: there is no default,
+ * so the generator refuses it instead of emitting a descriptor that guesses.
+ *
+ * @returns {number} the declared positive integer, or 0 when no Nexus is provided.
+ */
+export function readMaximumNexusOperationsPerInstance(component, manifestRel) {
+  const provides = component?.protocol?.nexus?.provides;
+  if (!Array.isArray(provides) || provides.length === 0) {
+    return 0;
+  }
+  const value = component?.requirements?.scaling?.concurrency?.maximumNexusOperationsPerInstance;
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(
+      `[xema-service-bootstrap] ${manifestRel} component "${component?.key}" provides a Nexus service and must declare ` +
+        '`requirements.scaling.concurrency.maximumNexusOperationsPerInstance` as a positive integer ' +
+        `(found ${JSON.stringify(value)}). It is the component's per-instance Nexus handler limit; there is no default.`,
+    );
+  }
+  return value;
+}

package/src/service-bootstrap-protocols.mjs

@@ -0,0 +1,108 @@
+/**
+ * Compile optional, generic service protocol metadata for a generated
+ * BiomeServiceDescriptor. Protocol identities and operations remain open
+ * strings, while endpoint transports are the kernel contract's closed enum.
+ */
+
+const ENDPOINT_PROTOCOL_MEMBERS = new Map([
+  ['event-hub', 'EventHub'],
+  ['grpc', 'Grpc'],
+  ['http', 'Http'],
+  ['mcp', 'Mcp'],
+]);
+
+const ENUM_EXPRESSION = Symbol('service-endpoint-protocol-expression');
+
+function enumExpression(member) {
+  return { [ENUM_EXPRESSION]: `ServiceEndpointProtocol.${member}` };
+}
+
+function renderTypescriptValue(value, depth = 0) {
+  if (value && typeof value === 'object' && ENUM_EXPRESSION in value) {
+    return value[ENUM_EXPRESSION];
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    const indentation = '  '.repeat(depth);
+    const entries = value
+      .map(
+        (entry) =>
+          `${'  '.repeat(depth + 1)}${renderTypescriptValue(entry, depth + 1)}`,
+      )
+      .join(',\n');
+    return `[\n${entries}\n${indentation}]`;
+  }
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return '{}';
+    const indentation = '  '.repeat(depth);
+    const properties = entries
+      .map(
+        ([key, entry]) =>
+          `${'  '.repeat(depth + 1)}${JSON.stringify(key)}: ${renderTypescriptValue(entry, depth + 1)}`,
+      )
+      .join(',\n');
+    return `{\n${properties}\n${indentation}}`;
+  }
+  const literal = JSON.stringify(value);
+  if (literal === undefined) {
+    throw new TypeError(
+      'xema.ships.apis[].protocols must contain JSON values.',
+    );
+  }
+  return literal;
+}
+
+function compileEndpointProtocols(protocols, protocolIndex) {
+  if (!Array.isArray(protocols)) {
+    throw new TypeError(
+      `xema.ships.apis[].protocols[${protocolIndex}].endpointProtocols must be an array.`,
+    );
+  }
+  return protocols.map((protocol, endpointIndex) => {
+    const member = ENDPOINT_PROTOCOL_MEMBERS.get(protocol);
+    if (member === undefined) {
+      throw new TypeError(
+        `xema.ships.apis[].protocols[${protocolIndex}].endpointProtocols[${endpointIndex}] ` +
+          `has unknown ServiceEndpointProtocol ${JSON.stringify(protocol)}; expected one of ` +
+          `${[...ENDPOINT_PROTOCOL_MEMBERS.keys()].join(' | ')}.`,
+      );
+    }
+    return enumExpression(member);
+  });
+}
+
+export function renderServiceProtocols(protocols) {
+  if (
+    protocols === undefined ||
+    (Array.isArray(protocols) && protocols.length === 0)
+  ) {
+    return { field: '', imports: [] };
+  }
+  if (!Array.isArray(protocols)) {
+    throw new TypeError('xema.ships.apis[].protocols must be an array.');
+  }
+
+  let importsEndpointProtocol = false;
+  const compiled = protocols.map((protocol, protocolIndex) => {
+    if (
+      protocol === null ||
+      typeof protocol !== 'object' ||
+      Array.isArray(protocol)
+    ) {
+      return protocol;
+    }
+    if (!Object.hasOwn(protocol, 'endpointProtocols')) return protocol;
+    const endpointProtocols = compileEndpointProtocols(
+      protocol.endpointProtocols,
+      protocolIndex,
+    );
+    if (endpointProtocols.length > 0) importsEndpointProtocol = true;
+    return { ...protocol, endpointProtocols };
+  });
+
+  return {
+    field: `\n  protocols: ${renderTypescriptValue(compiled, 1)},`,
+    imports: importsEndpointProtocol ? ['ServiceEndpointProtocol'] : [],
+  };
+}