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

package/LICENSE

@@ -0,0 +1,175 @@
+Xema Business Source License 1.1
+
+License text copyright (c) 2020 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:  Neuralchowder Inc.
+
+Licensed Work:  Xema. The Licensed Work is (c) 2026 Neuralchowder Inc.
+
+  The Licensed Work includes, without limitation, Xema Core, Xema Runtime,
+  Xema Kernel, Xema control plane, Xema application runtime, Xema biome
+  runtime, Xema biome registry, Xema store services, Xema orchestration
+  services, Xema agents, Xema skills, Xema memory services, Xema APIs, Xema
+  user interfaces, Xema command-line tools, Xema deployment artifacts, Xema
+  templates, Xema specifications, Xema schemas, Xema manifests, Xema
+  documentation, Xema examples, and all source code, object code, binaries,
+  packages, modules, configuration files, manifests, schemas, examples,
+  templates, documentation, and derivative works included in or distributed
+  as part of the Xema software project.
+
+  The Licensed Work does not include any third-party software, libraries,
+  dependencies, packages, assets, or components that are distributed with the
+  Licensed Work but are governed by their own separate license terms. Such
+  third-party materials remain subject to their respective licenses.
+
+  A specific file, package, component, or directory may state that it is
+  governed by a different license. In that case, that specific file, package,
+  component, or directory is governed by the license expressly stated therein.
+
+Additional Use Grant:
+
+  You may make production use of the Licensed Work, provided that your use
+  does not include offering, providing, making available, distributing,
+  hosting, managing, embedding, reselling, white-labeling, sublicensing,
+  commercializing, or otherwise making the Licensed Work, or any modified
+  version or derivative work of the Licensed Work, available to Third Parties
+  as part of a Competitive Offering.
+
+The following definitions and clarifications form part of, and govern
+the interpretation of, the Additional Use Grant set out above.
+
+  1. "Production Use" means any use of the Licensed Work other than for
+     development, testing, evaluation, demonstration, experimentation,
+     benchmarking, or other non-production purposes.
+
+  2. "Affiliate" means any entity that, directly or indirectly,
+     controls, is controlled by, or is under common control with you,
+     where "control" means ownership of more than fifty percent (50%) of
+     the voting interests of the entity, or the power to direct its
+     management.
+
+  3. "Third Party" means any natural person or legal entity other than
+     you and your Affiliates.
+
+  4. "Competitive Offering" means any product or service, made available
+     to one or more Third Parties for a fee or other consideration
+     (including without limitation on a paid, subscription,
+     advertising-supported, hosted, or managed-service basis), that is
+     offered or marketed as, or that competes with, a software platform,
+     runtime, orchestration system, agent or automation system,
+     extension or distribution marketplace, or other software system
+     that provides, in substantial part, the same or substantially
+     similar capabilities as those provided by the Licensed Work. A
+     product or service is a Competitive Offering whether the Licensed
+     Work is provided in whole or in part, alone or bundled with other
+     software, and whether modified or unmodified.
+
+  5. Providing, hosting, or managing the Licensed Work for a Third Party,
+     or otherwise making the Licensed Work available to a Third Party as
+     a hosted or managed service such that the Third Party obtains the
+     principal value or functionality of the Licensed Work, is a
+     Competitive Offering and is not permitted by the Additional Use
+     Grant.
+
+  6. Subject to the foregoing, the Additional Use Grant permits you to
+     make Production Use of the Licensed Work for your own internal
+     business purposes and to build, operate, and provide your own
+     products and services to Third Parties, provided that the Licensed
+     Work itself (whether modified or unmodified) is not the product or
+     service, and is not a Competitive Offering, made available to those
+     Third Parties.
+
+  7. You may modify the Licensed Work and create derivative works for
+     any purpose permitted by this License. Any Production Use of such
+     modified or derivative works remains subject to the same
+     restrictions as the Licensed Work, including the prohibition on
+     Competitive Offerings.
+
+  8. Use of the Licensed Work by your own employees, contractors, and
+     agents, acting on your behalf and for your benefit, is not by
+     itself making the Licensed Work available to a Third Party.
+
+  9. Embedding or distributing the Licensed Work as a component of your
+     own product or service is permitted only where the Licensed Work
+     does not constitute the principal value of that product or service
+     and the product or service is not a Competitive Offering.
+
+  10. Nothing in this Additional Use Grant grants any right to use any
+      name, trademark, service mark, or logo of the Licensor or its
+      Affiliates, except as reasonably required for customary
+      attribution.
+
+  11. The rights stated in this Additional Use Grant are the maximum
+      rights granted for Production Use prior to the Change Date. Any
+      Production Use not expressly permitted requires a separate
+      commercial license from the Licensor.
+
+  12. If any provision of this Additional Use Grant is held invalid or
+      unenforceable, that provision shall be limited or eliminated to
+      the minimum extent necessary so that the remainder of this
+      Additional Use Grant, and of this License, remains in full force
+      and effect. The Licensor reserves all rights not expressly granted
+      by this License.
+
+
+Change Date:  Four years from the date the specific version of the Licensed
+  Work is first publicly released by Licensor.
+
+Change License:  Mozilla Public License, Version 2.0
+
+For information about alternative licensing arrangements, commercial
+licensing, enterprise licensing, OEM licensing, appliance licensing, managed
+service licensing, cloud provider licensing, or other commercial use of the
+Licensed Work, please contact: licensing@neuralchowder.com
+
+-----------------------------------------------------------------------------
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph above
+terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of
+the Licensed Work, are subject to this License. This License applies separately
+for each version of the Licensed Work and the Change Date may vary for each
+version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or modified
+form from a third party, the terms and conditions set forth in this License
+apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor
+or its affiliates, provided that you may use a trademark or logo of Licensor
+as expressly required by this License.
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN
+"AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS
+OR IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# @xemahq/biome-bundle-pack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The core of packing a biome bundle, shared by the repository build pipeline
+(`@xemahq/repo-build-tooling`) and the `xema` CLI, so there is ONE bundle format:
+
+- `bundle-manifest`, `bundle-archive`, `bundle-content`, `seal-bundle`: the canonical manifest, the deterministic tar/gzip
+  archive, the content digest, and the sealing of a staged tree into `<out>/<hex>/` + `<out>/<hex>.tgz`;
+- `bundle-unpack`: `unpackBundle`, the reader of the archive `bundle-archive` writes (digest-checked, nothing leaves the
+  target directory);
+- `stage`, `host-provided`: `stageBundle` (production install, then the host-provided packages cut out) and the
+  standalone project install;
+- `pack-directory`: `packBiomeDirectory`, a built biome directory packed with the same pieces
+  (`xema biome install --from dir:<path>`, `xema biome dev`);
+- `bundle-build-source`, `target-platform`, `canonical-json`, `biome-content`.
+
+It holds no monorepo pipeline code (no workspace re-resolve, no image builds, no Prisma proof, no registry access).

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@xemahq/biome-bundle-pack",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "The pure core of packing a biome bundle: the canonical manifest, the deterministic archive, the content digest, the staged production install and the host-provided exclusion. Shared by the repository build pipeline and the xema CLI.",
+  "license": "LicenseRef-Xema-BSL-1.1",
+  "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
+  "homepage": "https://xema.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xema-dev/xema-base.git",
+    "directory": "packages/sdks/biome-bundle-pack"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "type": "module",
+  "files": [
+    "README.md",
+    "src"
+  ],
+  "exports": {
+    "./archive": "./src/bundle-archive.mjs",
+    "./biome-content": "./src/biome-content.mjs",
+    "./build-source": "./src/bundle-build-source.mjs",
+    "./canonical-json": "./src/canonical-json.mjs",
+    "./content": "./src/bundle-content.mjs",
+    "./host-provided": "./src/host-provided.mjs",
+    "./manifest": "./src/bundle-manifest.mjs",
+    "./member-required-env": "./src/member-required-env.mjs",
+    "./pack-directory": "./src/pack-directory.mjs",
+    "./seal": "./src/seal-bundle.mjs",
+    "./stage": "./src/stage.mjs",
+    "./target-platform": "./src/target-platform.mjs",
+    "./unpack": "./src/bundle-unpack.mjs",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@xemahq/host-abi-node": "^0.2.0",
+    "@xemahq/contracts": "^0.120.1"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.4",
+    "@xemahq/eslint-config": "^0.14.3"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "test": "node --test src/bundle-archive.test.mjs && node --test src/bundle-build-source.test.mjs && node --test src/host-provided.test.mjs && node --test src/stage.test.mjs && node --test src/bundle-unpack.test.mjs && node --test src/pack-directory.test.mjs"
+  },
+  "xemaRelease": {
+    "sourceDigest": "sha256:9dee0681ed083ba1816f3b709b76b20e76bd7b7703b6c2831d4181d2d672a1ee",
+    "sha": "9a88d6fde912be61affb481b069f009abfdfde21"
+  }
+}

package/src/biome-content.mjs

@@ -0,0 +1,49 @@
+// The biome's non-code content a bundle carries beside its code, at repo-relative paths: the biome manifest, its generated
+// index when it has one, and every top-level `contributions/*.contribution.json`. The contribution kinds the bundle
+// declares are read from those files, each graded by the contracts' own `ContributionKindRefSchema`: a file without a
+// string `kind`, or with a kind the schema refuses, refuses the pack, naming the file.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, posix } from 'node:path';
+
+import { ContributionKindRefSchema } from '@xemahq/contracts/contribution';
+
+const INDEX_FILE = 'xema-biome.index.json';
+const CONTRIBUTIONS_DIRECTORY = 'contributions';
+const CONTRIBUTION_SUFFIX = '.contribution.json';
+
+function copyInto({ root, stage, rel }) {
+  mkdirSync(dirname(join(stage, rel)), { recursive: true });
+  copyFileSync(join(root, rel), join(stage, rel));
+}
+
+/**
+ * Copy the content of each biome (`manifests`: repository-relative `<biomeDir>/xema-biome.json` paths) into `stage`, in
+ * sorted order, and return the sorted unique contribution kinds of the contribution files. Throws once, naming every
+ * offending file.
+ */
+export function copyBiomeContent({ root, stage, manifests }) {
+  const kinds = new Set();
+  const problems = [];
+  for (const manifest of [...manifests].sort()) {
+    const biomeDirectory = posix.dirname(manifest);
+    copyInto({ root, stage, rel: manifest });
+    const index = posix.join(biomeDirectory, INDEX_FILE);
+    if (existsSync(join(root, index))) {copyInto({ root, stage, rel: index });}
+    const directory = join(root, biomeDirectory, CONTRIBUTIONS_DIRECTORY);
+    if (!existsSync(directory)) {continue;}
+    const names = readdirSync(directory, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith(CONTRIBUTION_SUFFIX))
+      .map((entry) => entry.name)
+      .sort();
+    for (const name of names) {
+      const rel = posix.join(biomeDirectory, CONTRIBUTIONS_DIRECTORY, name);
+      copyInto({ root, stage, rel });
+      const kind = JSON.parse(readFileSync(join(root, rel), 'utf8')).kind;
+      const parsed = typeof kind === 'string' ? ContributionKindRefSchema.safeParse(kind) : undefined;
+      if (parsed?.success === true) {kinds.add(kind);}
+      else {problems.push(`${rel}: ${parsed === undefined ? 'has no string "kind"' : `kind "${kind}" is refused: ${parsed.error.issues.map((issue) => issue.message).join('; ')}`}`);}
+    }
+  }
+  if (problems.length > 0) {throw new Error(`cannot pack the biome content:\n${problems.map((p) => `  - ${p}`).join('\n')}`);}
+  return [...kinds].sort();
+}

package/src/bundle-archive.mjs

@@ -0,0 +1,140 @@
+// The canonical archive of a bundle: the same tree gives the same bytes on any host, at any time, in any creation
+// order, so the sha256 of the tar is a content address. Nothing of the build host leaks in: entries are sorted bytewise by
+// path, owners are root with empty names, every mtime is 0, modes are 0755 or 0644 (a symlink 0777), and the gzip header
+// carries the "unknown" OS byte. Long or non-ASCII names go into pax extended headers, which every modern tar reads.
+// A name or target that needs a pax record is also written truncated in the ustar header, as GNU tar and Python do: libarchive
+// ignores the pax link record when the header's own link field is empty.
+// Loads only `node:` builtins.
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, readdirSync, readlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { gzipSync } from 'node:zlib';
+
+const BLOCK = 512;
+const NAME_LIMIT = 100;
+const PREFIX_LIMIT = 155;
+const MAX_ENTRY_SIZE = 8 ** 11 - 1;
+const GZIP_OS_OFFSET = 9;
+const GZIP_OS_UNKNOWN = 255;
+
+/** The ustar type flags this archive writes. */
+const TypeFlag = Object.freeze({ File: '0', Symlink: '2', Directory: '5', Pax: 'x' });
+
+const bytewise = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+const isAscii = (text) => /^[\x20-\x7e]*$/.test(text);
+
+/** Every path under `dir` (relative, `/`-separated) with its lstat, sorted bytewise; sockets, devices and FIFOs are refused. */
+function listEntries(dir) {
+  const found = [];
+  const refused = [];
+  const walk = (prefix) => {
+    for (const name of readdirSync(join(dir, prefix))) {
+      const rel = prefix === '' ? name : `${prefix}/${name}`;
+      const stat = lstatSync(join(dir, rel));
+      if (stat.isDirectory()) {
+        found.push({ rel, stat });
+        walk(rel);
+      } else if (stat.isFile() || stat.isSymbolicLink()) {
+        found.push({ rel, stat });
+      } else {
+        refused.push(rel);
+      }
+    }
+  };
+  walk('');
+  if (refused.length > 0) {throw new Error(`cannot archive ${refused.length} entr${refused.length > 1 ? 'ies' : 'y'} that are neither file, directory nor symlink: ${refused.join(', ')}`);}
+  return found.sort((a, b) => bytewise(a.rel, b.rel));
+}
+
+const octal = (value, width) => Buffer.from(`${value.toString(8).padStart(width - 1, '0')}\0`, 'latin1');
+
+function field(header, offset, width, value) {
+  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value, 'utf8');
+  bytes.copy(header, offset, 0, Math.min(bytes.length, width));
+}
+
+/** `{ name, prefix }` of a path that fits ustar's 100-byte name with a 155-byte prefix split at a `/`, else `undefined`. */
+function splitName(path) {
+  const bytes = Buffer.from(path, 'utf8');
+  if (bytes.length <= NAME_LIMIT) {return { name: path, prefix: '' };}
+  for (let i = path.lastIndexOf('/'); i > 0; i = path.lastIndexOf('/', i - 1)) {
+    const prefix = path.slice(0, i);
+    const name = path.slice(i + 1);
+    if (Buffer.byteLength(prefix) <= PREFIX_LIMIT && Buffer.byteLength(name) <= NAME_LIMIT && name.length > 0) {return { name, prefix };}
+  }
+  return undefined;
+}
+
+function ustarHeader({ name, prefix = '', mode, size, type, linkname = '' }) {
+  const header = Buffer.alloc(BLOCK);
+  field(header, 0, NAME_LIMIT, name);
+  field(header, 100, 8, octal(mode, 8));
+  field(header, 108, 8, octal(0, 8));
+  field(header, 116, 8, octal(0, 8));
+  field(header, 124, 12, octal(size, 12));
+  field(header, 136, 12, octal(0, 12));
+  header.fill(0x20, 148, 156);
+  field(header, 156, 1, type);
+  field(header, 157, NAME_LIMIT, linkname);
+  field(header, 257, 6, 'ustar\0');
+  field(header, 263, 2, '00');
+  field(header, 345, PREFIX_LIMIT, prefix);
+  let sum = 0;
+  for (const byte of header) {sum += byte;}
+  field(header, 148, 8, Buffer.from(`${sum.toString(8).padStart(6, '0')}\0 `, 'latin1'));
+  return header;
+}
+
+/** One pax record `"<length> <key>=<value>\n"`, the length counting its own digits. */
+function paxRecord(key, value) {
+  const body = ` ${key}=${value}\n`;
+  let length = Buffer.byteLength(body);
+  while (String(length).length + Buffer.byteLength(body) !== length) {length = String(length).length + Buffer.byteLength(body);}
+  return Buffer.from(`${length}${body}`, 'utf8');
+}
+
+const padded = (data) => Buffer.concat([data, Buffer.alloc((BLOCK - (data.length % BLOCK)) % BLOCK)]);
+
+/** The header block(s) of one entry: a pax header first whenever the name or link target does not fit plain ustar. */
+function entryHeaders({ path, mode, size, type, linkname }) {
+  const split = isAscii(path) ? splitName(path) : undefined;
+  const linkFits = isAscii(linkname) && Buffer.byteLength(linkname) <= NAME_LIMIT;
+  const records = [];
+  if (split === undefined) {records.push(paxRecord('path', path));}
+  if (!linkFits) {records.push(paxRecord('linkpath', linkname));}
+  const plain = split ?? { name: Buffer.from(path, 'utf8').subarray(0, NAME_LIMIT).toString('latin1'), prefix: '' };
+  const real = ustarHeader({ ...plain, mode, size, type, linkname: Buffer.from(linkname, 'utf8').subarray(0, NAME_LIMIT) });
+  if (records.length === 0) {return [real];}
+  const pax = Buffer.concat(records);
+  return [ustarHeader({ name: 'PaxHeader', mode: 0o644, size: pax.length, type: TypeFlag.Pax }), padded(pax), real];
+}
+
+/** The POSIX tar of every entry under `dir` (not `dir` itself), canonical as the header says. Refuses sockets, devices and FIFOs. */
+export function canonicalTar(dir) {
+  const parts = [];
+  for (const { rel, stat } of listEntries(dir)) {
+    if (stat.isDirectory()) {
+      parts.push(...entryHeaders({ path: `${rel}/`, mode: 0o755, size: 0, type: TypeFlag.Directory, linkname: '' }));
+    } else if (stat.isSymbolicLink()) {
+      parts.push(...entryHeaders({ path: rel, mode: 0o777, size: 0, type: TypeFlag.Symlink, linkname: readlinkSync(join(dir, rel)) }));
+    } else {
+      if (stat.size > MAX_ENTRY_SIZE) {throw new Error(`${rel} is ${stat.size} bytes, more than a tar entry holds`);}
+      const mode = (stat.mode & 0o111) === 0 ? 0o644 : 0o755;
+      parts.push(...entryHeaders({ path: rel, mode, size: stat.size, type: TypeFlag.File, linkname: '' }), padded(readFileSync(join(dir, rel))));
+    }
+  }
+  parts.push(Buffer.alloc(BLOCK * 2));
+  return Buffer.concat(parts);
+}
+
+/** The tar gzipped at level 9 with the header's OS byte fixed, so the bytes do not depend on the build host. */
+export function gzipCanonical(tarBuffer) {
+  const gz = gzipSync(tarBuffer, { level: 9 });
+  gz[GZIP_OS_OFFSET] = GZIP_OS_UNKNOWN;
+  return gz;
+}
+
+/** `sha256:<hex>` of the archive bytes (the `.tgz` `gzipCanonical` made): the bundle's address. */
+export function archiveDigest(archiveBytes) {
+  return `sha256:${createHash('sha256').update(archiveBytes).digest('hex')}`;
+}

package/src/bundle-archive.test.mjs

@@ -0,0 +1,97 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { gunzipSync } from 'node:zlib';
+
+import { archiveDigest, canonicalTar, gzipCanonical } from './bundle-archive.mjs';
+
+const scratch = () => fs.mkdtempSync(path.join(os.tmpdir(), 'xema-archive-'));
+
+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);}
+}
+
+test('the same tree gives the same bytes whatever the mtimes, the creation order and the non-exec modes', () => {
+  const a = scratch();
+  const b = scratch();
+  put(a, 'x/one.txt', '1', 0o644);
+  put(a, 'y/two.txt', '2', 0o600);
+  put(a, 'run.sh', '#!/bin/sh\n', 0o755);
+  fs.symlinkSync('x/one.txt', path.join(a, 'link'));
+  put(b, 'run.sh', '#!/bin/sh\n', 0o700);
+  put(b, 'y/two.txt', '2', 0o664);
+  fs.symlinkSync('x/one.txt', path.join(b, 'link'));
+  put(b, 'x/one.txt', '1', 0o640);
+  fs.utimesSync(path.join(b, 'x/one.txt'), 1000, 1000);
+  assert.ok(canonicalTar(a).equals(canonicalTar(b)));
+  assert.equal(archiveDigest(gzipCanonical(canonicalTar(a))), archiveDigest(gzipCanonical(canonicalTar(b))));
+  assert.match(archiveDigest(gzipCanonical(canonicalTar(a))), /^sha256:[0-9a-f]{64}$/);
+});
+
+test('a changed file byte, or a changed exec bit, changes the digest', () => {
+  const a = scratch();
+  put(a, 'f', 'abc', 0o644);
+  const before = archiveDigest(gzipCanonical(canonicalTar(a)));
+  put(a, 'f', 'abd', 0o644);
+  const edited = archiveDigest(gzipCanonical(canonicalTar(a)));
+  assert.notEqual(edited, before);
+  fs.chmodSync(path.join(a, 'f'), 0o755);
+  assert.notEqual(archiveDigest(gzipCanonical(canonicalTar(a))), edited);
+});
+
+test('a path over 255 bytes and a long symlink target survive the system tar', () => {
+  const dir = scratch();
+  const deep = `${'d'.repeat(90)}/${'e'.repeat(90)}/${'f'.repeat(90)}`;
+  const file = `${deep}/${'n'.repeat(60)}.txt`;
+  const target = `../${'t'.repeat(150)}/target`;
+  const unicode = 'café/über.txt';
+  put(dir, file, 'long');
+  put(dir, unicode, 'u');
+  fs.symlinkSync(target, path.join(dir, 'link'));
+  const tarFile = path.join(scratch(), 'bundle.tar');
+  fs.writeFileSync(tarFile, canonicalTar(dir));
+  const listing = execFileSync('tar', ['-tvf', tarFile], { encoding: 'utf8' });
+  assert.ok(listing.includes(file), 'long path listed');
+  // The non-ASCII name is proven by extracting it below, not by the listing: a
+  // system tar prints non-ASCII bytes as octal escapes unless the locale is
+  // UTF-8, and turbo's strict env hands the task no locale at all.
+  const out = scratch();
+  execFileSync('tar', ['-xf', tarFile, '-C', out]);
+  assert.equal(fs.readFileSync(path.join(out, file), 'utf8'), 'long');
+  assert.equal(fs.readFileSync(path.join(out, unicode), 'utf8'), 'u');
+  assert.equal(fs.readlinkSync(path.join(out, 'link')), target);
+});
+
+test('gzipCanonical fixes the OS byte and gunzips to the tar', () => {
+  const dir = scratch();
+  put(dir, 'f', 'abc');
+  const tar = canonicalTar(dir);
+  const gz = gzipCanonical(tar);
+  assert.equal(gz[9], 255);
+  assert.ok(gunzipSync(gz).equals(tar));
+});
+
+test('entries are sorted bytewise and owned by root with mtime 0', () => {
+  const dir = scratch();
+  put(dir, 'b', '');
+  put(dir, 'a-b', '');
+  put(dir, 'a/c', '');
+  const tarFile = path.join(scratch(), 'bundle.tar');
+  fs.writeFileSync(tarFile, canonicalTar(dir));
+  const names = execFileSync('tar', ['-tf', tarFile], { encoding: 'utf8' }).trim().split('\n');
+  assert.deepEqual(names, ['a/', 'a-b', 'a/c', 'b']);
+  const header = canonicalTar(dir);
+  assert.equal(header.subarray(108, 116).toString('latin1'), '0000000\0');
+  assert.equal(header.subarray(136, 148).toString('latin1'), '00000000000\0');
+});
+
+test('a FIFO is refused', () => {
+  const dir = scratch();
+  execFileSync('mkfifo', [path.join(dir, 'pipe')]);
+  assert.throws(() => canonicalTar(dir), /neither file, directory nor symlink: pipe/);
+});

package/src/bundle-build-source.mjs

@@ -0,0 +1,58 @@
+// Where a bundle's code was built: one repository at one commit, recorded in `xema-bundle.json` so Biome Host can copy it into
+// the member facts. The library reads no environment and installs nothing: the process entry reads `GITHUB_*` once and passes
+// `ci` down; a local pack reads the git checkout through the injected `exec`. A tree that is not a clean checkout is refused
+// unless the caller states the source explicitly (`--build-source <repository>@<commit>`).
+import { ProcessMemberBuildSourceSchema } from '@xemahq/contracts/process-topology';
+
+/** The `ci` argument of `resolveBuildSource` from a process environment: the GitHub Actions repository and sha, or `undefined` outside Actions. Process entries only. */
+export function ciBuildSource(env) {
+  if (env.GITHUB_ACTIONS !== 'true') {return undefined;}
+  const repository = env.GITHUB_REPOSITORY;
+  const commit = env.GITHUB_SHA;
+  if (!repository || !commit) {throw new Error('GITHUB_ACTIONS is set but GITHUB_REPOSITORY or GITHUB_SHA is not: pass --build-source <repository>@<commit>');}
+  return { repository, commit };
+}
+
+/** `<repository>@<commit>` as a build source. The commit follows the LAST `@`, so an scp-style `git@host:path` repository is allowed. */
+export function parseBuildSource(text) {
+  const at = text.lastIndexOf('@');
+  const repository = at < 0 ? '' : text.slice(0, at);
+  const commit = at < 0 ? '' : text.slice(at + 1);
+  if (repository.length === 0 || !ProcessMemberBuildSourceSchema.safeParse({ repository: 'r', commit }).success) {
+    throw new Error(`--build-source must be <repository>@<40-hex commit>, got "${text}"`);
+  }
+  return { repository, commit };
+}
+
+/** A GitHub remote (`https://github.com/o/r(.git)`, `git@github.com:o/r(.git)`, `ssh://git@github.com/o/r`) as `o/r`, the form CI records; any other remote is kept as written. */
+export function repositoryName(remote) {
+  const match = /^(?:https?:\/\/(?:[^@/]+@)?|ssh:\/\/git@|git@)github\.com[/:]([^/]+\/[^/]+?)(?:\.git)?\/?$/u.exec(remote.trim());
+  return match === null ? remote.trim() : match[1];
+}
+
+function git(exec, root, args) {
+  const result = exec('git', args, { cwd: root });
+  return result.status === 0 ? result.stdout.trim() : undefined;
+}
+
+/** The build source of the git checkout at `root`: its `origin` URL and `HEAD`. Refuses a missing checkout, a missing origin and a dirty tree (unless `allowDirty`: the content digest, not the commit, identifies a dev tree's bytes). */
+export function localBuildSource({ root, exec, allowDirty = false }) {
+  const head = git(exec, root, ['rev-parse', 'HEAD']);
+  if (head === undefined) {throw new Error(`${root} is not a git checkout: pass --build-source <repository>@<commit>`);}
+  const origin = git(exec, root, ['remote', 'get-url', 'origin']);
+  if (origin === undefined || origin === '') {throw new Error(`${root} has no origin remote: pass --build-source <repository>@<commit>`);}
+  const status = git(exec, root, ['status', '--porcelain']);
+  if (status === undefined) {throw new Error(`cannot read the git status of ${root}: pass --build-source <repository>@<commit>`);}
+  if (status !== '' && !allowDirty) {throw new Error(`${root} has uncommitted changes, so its HEAD does not describe what is packed: commit them or pass --build-source <repository>@<commit>`);}
+  return { repository: repositoryName(origin), commit: head };
+}
+
+/**
+ * The build source to record: `explicit` (`<repository>@<commit>`) when given, else `ci` (what the entry read from GitHub Actions),
+ * else the local checkout at `root`. Every source is graded: the commit must be a full lowercase 40-hex git commit.
+ */
+export function resolveBuildSource({ root, explicit, ci, exec, allowDirty = false }) {
+  const source = explicit !== undefined ? parseBuildSource(explicit) : ci ?? localBuildSource({ root, exec, allowDirty });
+  if (!ProcessMemberBuildSourceSchema.safeParse(source).success) {throw new Error(`build source commit "${source.commit}" is not a full lowercase 40-hex git commit`);}
+  return source;
+}

package/src/bundle-build-source.test.mjs

@@ -0,0 +1,53 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { ciBuildSource, localBuildSource, parseBuildSource, repositoryName, resolveBuildSource } from './bundle-build-source.mjs';
+
+const COMMIT = 'a'.repeat(40);
+
+/** A git stand-in: `answers` maps the subcommand (`rev-parse`, `remote`, `status`) to stdout, or `null` for a failing exit. */
+const gitExec = (answers) => (file, args) => {
+  assert.equal(file, 'git');
+  const answer = answers[args[0]];
+  return answer === null || answer === undefined ? { status: 128, stdout: '', stderr: 'fatal' } : { status: 0, stdout: `${answer}\n`, stderr: '' };
+};
+const clean = { 'rev-parse': COMMIT, remote: 'git@github.com:xema-dev/xema-base.git', status: '' };
+
+test('a local checkout gives its origin and HEAD', () => {
+  assert.deepEqual(localBuildSource({ root: '/r', exec: gitExec(clean) }), { repository: 'xema-dev/xema-base', commit: COMMIT });
+});
+
+test('outside a checkout, without an origin or with a dirty tree the pack is refused and names the override', () => {
+  assert.throws(() => localBuildSource({ root: '/r', exec: gitExec({ ...clean, 'rev-parse': null }) }), /not a git checkout.*--build-source/);
+  assert.throws(() => localBuildSource({ root: '/r', exec: gitExec({ ...clean, remote: null }) }), /no origin remote/);
+  assert.throws(() => localBuildSource({ root: '/r', exec: gitExec({ ...clean, status: ' M a.txt' }) }), /uncommitted changes.*--build-source/);
+});
+
+test('an explicit source wins over CI and the checkout; CI wins over the checkout', () => {
+  const never = () => { throw new Error('git must not run'); };
+  const ci = { repository: 'o/r', commit: COMMIT };
+  assert.deepEqual(resolveBuildSource({ root: '/r', explicit: `o/x@${'b'.repeat(40)}`, ci, exec: never }), { repository: 'o/x', commit: 'b'.repeat(40) });
+  assert.deepEqual(resolveBuildSource({ root: '/r', ci, exec: never }), ci);
+  assert.deepEqual(resolveBuildSource({ root: '/r', exec: gitExec(clean) }), { repository: 'xema-dev/xema-base', commit: COMMIT });
+});
+
+test('an explicit source on a dirty tree is accepted', () => {
+  assert.deepEqual(resolveBuildSource({ root: '/r', explicit: `o/r@${COMMIT}`, exec: gitExec({ ...clean, status: ' M a' }) }), { repository: 'o/r', commit: COMMIT });
+});
+
+test('--build-source needs a repository and a full lowercase 40-hex commit', () => {
+  for (const bad of ['o/r', 'o/r@abc', `@${COMMIT}`, `o/r@${'A'.repeat(40)}`]) {assert.throws(() => parseBuildSource(bad), /--build-source must be/);}
+  assert.deepEqual(parseBuildSource(`git@host:o/r@${COMMIT}`), { repository: 'git@host:o/r', commit: COMMIT });
+});
+
+test('CI is read from GitHub Actions only, and half of it is refused', () => {
+  assert.equal(ciBuildSource({}), undefined);
+  assert.equal(ciBuildSource({ GITHUB_REPOSITORY: 'o/r', GITHUB_SHA: COMMIT }), undefined);
+  assert.deepEqual(ciBuildSource({ GITHUB_ACTIONS: 'true', GITHUB_REPOSITORY: 'o/r', GITHUB_SHA: COMMIT }), { repository: 'o/r', commit: COMMIT });
+  assert.throws(() => ciBuildSource({ GITHUB_ACTIONS: 'true', GITHUB_REPOSITORY: 'o/r' }), /GITHUB_SHA/);
+});
+
+test('GitHub remotes become owner/repo; others are kept', () => {
+  for (const remote of ['https://github.com/o/r.git', 'https://tok@github.com/o/r', 'git@github.com:o/r.git', 'ssh://git@github.com/o/r']) {assert.equal(repositoryName(remote), 'o/r');}
+  assert.equal(repositoryName('https://git.example.com/o/r.git'), 'https://git.example.com/o/r.git');
+});