@runeditrun/rer 0.0.0-stage → 0.1.1

package/modules/release/export.mjs

@@ -0,0 +1,51 @@
+import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { git } from './source.mjs';
+import { sha256 } from './catalogue.mjs';
+
+// Read the checked Git blobs directly. export-ignore/export-subst attributes
+// cannot silently remove or change bytes after publication inspection.
+export function sourceTree(source, tree) {
+  mkdirSync(tree);
+  for (const [path, entry] of source.entries) {
+    // Git control paths can alias .git on case-insensitive filesystems. Never
+    // materialize source-supplied configuration before initializing an export.
+    if (path.split('/').some(part => part.normalize('NFC').replace(/\p{Cf}/gu, '').toLowerCase().replace(/[ .]+$/, '') === '.git'))
+      throw Error('Public export cannot contain Git control paths');
+    if (!['100644', '100755'].includes(entry.mode) || entry.type !== 'blob') throw Error('Public export requires ordinary committed files');
+    const target = resolve(tree, path);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, source.bytes(path), { flag: 'wx', mode: entry.mode === '100755' ? 0o755 : 0o644 });
+  }
+  return tree;
+}
+
+export function releaseMessage(source) {
+  const notes = source.release.publicReleaseNotes;
+  if (notes !== undefined && (typeof notes !== 'string' || !notes.trim())) throw Error('Public release notes must be nonempty text');
+  return source.tag + (notes ? `\n\n${notes.trim()}` : '');
+}
+
+export function annotate(repo, source, commit, name = source.tag) {
+  git(repo, '-c', 'user.name=Run Edit Run', '-c', 'user.email=releases@runeditrun.invalid', '-c', 'core.hooksPath=/dev/null',
+    'tag', '-a', name, commit, '-m', releaseMessage(source));
+}
+
+export function cleanHistory(source, temporary, tagged = false) {
+  const tree = sourceTree(source, resolve(temporary, 'clean-source'));
+  git(tree, 'init', '-q', '-b', 'main');
+  git(tree, 'add', '-f', '--all');
+  git(tree, '-c', 'user.name=Run Edit Run', '-c', 'user.email=releases@runeditrun.invalid', '-c', 'core.hooksPath=/dev/null', 'commit', '-qm', releaseMessage(source));
+  const commit = git(tree, 'rev-parse', 'HEAD').toString().trim();
+  if (git(tree, 'rev-parse', 'HEAD^{tree}').toString().trim() !== source.tree) throw Error('Clean export changed source bytes');
+  if (tagged) annotate(tree, source, commit);
+  return { repo: tree, commit };
+}
+
+export function publicExport(source, temporary, output) {
+  const tree = sourceTree(source, resolve(temporary, 'public-source'));
+  const archive = resolve(output, 'public-source.tar');
+  execFileSync('tar', ['-cf', archive, '-C', tree, '.'], { stdio: ['ignore', 'pipe', 'pipe'] });
+  return { path: 'public-source.tar', sha256: sha256(readFileSync(archive)), format: 'tar', revision: source.commit };
+}

package/modules/release/produce.mjs

@@ -0,0 +1,136 @@
+import { mkdtempSync, rmSync, writeFileSync, cpSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { inspectSource, newOutput, git, command } from './source.mjs';
+import { catalogue, writeCatalogue, sha256, json } from './catalogue.mjs';
+import { publicExport, cleanHistory, annotate, releaseMessage } from './export.mjs';
+import { publicationScan, validatePublicationDestination } from './publication-scan.mjs';
+import { publicDestination, requirePublicDestination, remotePublicHead, publicChild, assertPublicTree } from './public-child.mjs';
+import { writePublishHandoff } from './publish-handoff.mjs';
+
+export async function release({ repo, ref = 'HEAD', output, project, repository, dryRun = false, tag = false, cleanHistory: clean = false, envFile, onto }) {
+  if (!/^[\w.-]+\/[\w.-]+$/.test(project ?? '')) throw Error('--project must be publisher/name');
+  if (!/^https:\/\/github\.com\/[\w.-]+\/[\w.-]+(?:\.git)?$/i.test(repository ?? '')) throw Error('--repository must be a credential-free GitHub repository URL');
+  if (onto !== undefined && clean) throw Error('--onto and --clean-history are mutually exclusive');
+  const preview = dryRun || !tag;
+  const source = inspectSource(repo, ref);
+  validatePublicationDestination(source, project, repository);
+  releaseMessage(source);
+  if (typeof tag === 'string' && tag !== source.tag) throw Error('Requested tag must match the committed release version');
+  const existing = git(source.repo, 'tag', '--list', source.tag).toString().trim();
+  if (existing && tag && !dryRun) throw Error('Release tag already exists; choose a new committed version');
+  // Validate metadata before installs or output writes.
+  catalogue(source, project, repository, { verify: { status: 'PENDING' }, publishCheck: { status: 'PENDING' } }, preview);
+  const destination = onto !== undefined ? publicDestination(onto, repository, source.repo) : null;
+  let publicParent = null;
+  if (destination) {
+    requirePublicDestination(destination);
+    publicParent = remotePublicHead(source.repo, destination, source.tag);
+  }
+  output = newOutput(source.repo, output);
+  const temporary = mkdtempSync(resolve(tmpdir(), 'rer-release-'));
+  let receipt;
+  try {
+    const checkout = resolve(temporary, 'seed');
+    git(source.repo, 'clone', '--no-hardlinks', '--no-checkout', '--', source.repo, checkout);
+    git(checkout, 'checkout', '--detach', source.commit);
+    // Honour the seed's committed install policy. Base's native-build settings
+    // are not interchangeable with pnpm 8's locked onlyBuiltDependencies.
+    const install = await command('pnpm', ['install', '--frozen-lockfile'], checkout);
+    const verify = install.status === 'PASS' ? await command('pnpm', ['run', 'verify'], checkout) : { status: 'FAIL', reason: 'frozen-install-failed', tests: 0, passed: 0, failed: 0 };
+    // Release-only scale and capacity cases stay outside routine CI. The
+    // committed seed script is an additional gate in previews and releases.
+    if (verify.status === 'PASS' && JSON.parse(source.bytes('package.json')).scripts['verify:release']) {
+      verify.release = await command('pnpm', ['run', 'verify:release'], checkout);
+      if (verify.release.status !== 'PASS') {
+        verify.status = 'FAIL'; verify.exitCode = verify.release.exitCode;
+        verify.reason = 'release-verification-failed';
+      }
+    }
+    if (git(checkout, 'status', '--porcelain', '--untracked-files=no').length) {
+      verify.status = 'FAIL'; verify.reason = 'verify-changed-tracked-source';
+    }
+    // Explicit clean-history publication scans every byte and ref of the actual
+    // parentless export. Ordinary releases retain the private full-history gate.
+    const exported = destination ? publicChild(source, temporary, destination, publicParent, Boolean(tag))
+      : clean ? cleanHistory(source, temporary, Boolean(tag)) : null;
+    const scanRepo = exported?.repo ?? source.repo;
+    const scanRef = exported?.commit ?? source.commit;
+    let report = publicationScan(scanRepo, scanRef, envFile, project, repository, destination?.spec);
+    if (!exported && tag && report.status === 'PASS') {
+      // Stage the exact final annotation before any source tag or distributable
+      // artifact exists, in a fresh clone of the selected commit: verification
+      // left build output in its checkout, which is not release source. Source
+      // history was scanned above, including refs a checkout clone leaves out.
+      const candidate = resolve(temporary, 'annotation');
+      git(source.repo, 'clone', '--no-hardlinks', '--no-checkout', '--', source.repo, candidate);
+      git(candidate, 'checkout', '--detach', source.commit);
+      const staged = git(candidate, 'tag', '--list', source.tag).toString().trim();
+      annotate(candidate, source, source.commit, staged ? `${source.tag}-publication-candidate` : source.tag);
+      const annotations = publicationScan(candidate, source.commit, envFile, project, repository);
+      report.annotationInspection = annotations;
+      if (annotations.status !== 'PASS') {
+        report.status = annotations.status;
+        report.complete = annotations.complete;
+        report.guarantees.historyScanned = annotations.complete;
+        report.findings.push(...annotations.findings);
+      }
+    }
+    if (destination) {
+      assertPublicTree(exported.repo, exported.commit, source.tree);
+      if (report.status === 'PASS' && (report.complete !== true || report.guarantees?.historyScanned !== true ||
+        report.publicBase?.commit !== publicParent || report.source?.commit !== exported.commit)) {
+        report.status = 'INCOMPLETE';
+        report.complete = false;
+        report.guarantees ??= {};
+        report.guarantees.historyScanned = false;
+      }
+      // A successful scan cannot authorize a handoff against a different tip.
+      requirePublicDestination(destination);
+      if (remotePublicHead(exported.repo, destination, source.tag) !== publicParent) throw Error('Public destination changed during release');
+    }
+    writeFileSync(resolve(output, 'publish-check.json'), json(report), { flag: 'wx' });
+    const gates = { verify, publishCheck: { status: report.status, findings: report.findings.length,
+      reportSha256: sha256(json(report)) } };
+    const passed = verify.status === 'PASS' && report.status === 'PASS';
+    receipt = { schemaVersion: 1, status: passed ? (preview ? 'DRY_RUN' : 'RELEASED') : 'BLOCKED',
+      dryRun, tagRequested: Boolean(tag), source: { commit: source.commit, tree: source.tree }, tag: { name: source.tag, created: false, pushed: false }, gates,
+      publicationHistory: destination ? 'public-child' : clean ? 'parentless-export' : 'source-history',
+      ...(destination ? { publicParent, publicDestination: { repository: destination.url, branch: destination.branch } } : {}),
+      publicExport: null, siteRelease: null };
+    // A blocked preview may prepare the site metadata/docs for local review.
+    // Its provenance explicitly records blocked gates; it is never a release.
+    const publicSource = exported ? { ...source, commit: exported.commit, publicTagStaged: Boolean(destination && tag) } : source;
+    if (passed || preview) receipt.siteRelease = writeCatalogue(publicSource, output, catalogue(publicSource, project, repository, gates, preview));
+    if (passed) {
+      if (tag) {
+        receipt.publicExport = publicExport(source, temporary, output);
+        if (exported) {
+          cpSync(exported.repo, resolve(output, 'public-git'), { recursive: true, errorOnExist: true });
+          Object.assign(receipt.publicExport, { gitPath: 'public-git', commit: exported.commit, tree: source.tree,
+            ...(destination ? { publicParent, tag: source.tag, tagObject: exported.tagObject, revision: exported.commit } : {}) });
+        }
+      }
+      // Verification must not have changed the original or selected source.
+      if (git(source.repo, 'status', '--porcelain', '--untracked-files=all').length) throw Error('Source changed during release');
+      if (tag && !dryRun) {
+        // Public-child writes every artifact before the last guard/source tag,
+        // so a failed write or changed remote cannot leave a private tag.
+        if (!destination) annotate(source.repo, source, source.commit);
+        receipt.tag.created = true;
+      }
+    }
+    if (passed && tag && destination) writePublishHandoff(output, destination, receipt);
+    writeFileSync(resolve(output, 'release-receipt.json'), json(receipt), { flag: 'wx' });
+    if (passed && destination) {
+      requirePublicDestination(destination);
+      if (remotePublicHead(exported.repo, destination, source.tag) !== publicParent) throw Error('Public destination changed before handoff');
+      if (tag && !dryRun) annotate(source.repo, source, source.commit);
+    }
+    return receipt;
+  } catch (error) {
+    // No incomplete directory should be mistaken for a completed export.
+    rmSync(output, { recursive: true, force: true });
+    throw error;
+  } finally { rmSync(temporary, { recursive: true, force: true }); }
+}

package/modules/release/public-child-transport-state.cjs

@@ -0,0 +1,29 @@
+// Shared serialization for the fixture's Git and smart HTTP transport doubles.
+const fs = require('node:fs');
+const { randomUUID } = require('node:crypto');
+
+exports.withTransportState = function (path, update, operation) {
+  const lock = path + '.lock', deadline = Date.now() + 10000;
+  const pause = new Int32Array(new SharedArrayBuffer(4));
+  for (;;) {
+    try { fs.mkdirSync(lock); break; }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      if (Date.now() >= deadline) throw new Error('Timed out waiting for fixture transport state lock');
+      Atomics.wait(pause, 0, 0, 10);
+    }
+  }
+  let temporary;
+  try {
+    const state = fs.existsSync(path) ? JSON.parse(fs.readFileSync(path)) : { heads: 0, fetches: 0 };
+    update(state);
+    temporary = path + '.' + process.pid + '.' + randomUUID() + '.tmp';
+    const fd = fs.openSync(temporary, 'wx');
+    try { fs.writeFileSync(fd, JSON.stringify(state)); } finally { fs.closeSync(fd); }
+    fs.renameSync(temporary, path);
+    temporary = undefined;
+    return operation(state);
+  } finally {
+    try { if (temporary) fs.unlinkSync(temporary); } finally { fs.rmdirSync(lock); }
+  }
+};

package/modules/release/public-child.mjs

@@ -0,0 +1,71 @@
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { sourceTree, releaseMessage } from './export.mjs';
+import { publicGit, publicOid } from './public-git.mjs';
+
+const repositoryUrl = /^https:\/\/github\.com\/([A-Za-z0-9][A-Za-z0-9_.-]*)\/([A-Za-z0-9][A-Za-z0-9_.-]*)$/i;
+const identity = url => url.match(repositoryUrl)?.slice(1).join('/').toLowerCase().replace(/\.git$/, '');
+
+export function publicDestination(onto, repository, repo) {
+  if (typeof onto !== 'string' || onto.split('#').length !== 2) throw Error('--onto requires an explicit public repository branch');
+  const [url, branch] = onto.split('#');
+  if (!identity(url) || identity(url) !== identity(repository)) throw Error('--onto must match the declared publication repository');
+  if (!branch || branch === 'HEAD' || branch.startsWith('-') || branch.startsWith('refs/')) throw Error('--onto requires a branch name');
+  publicGit(repo, ['check-ref-format', `refs/heads/${branch}`]);
+  return { url, branch, spec: onto, identity: identity(url) };
+}
+
+export function requirePublicDestination(destination) {
+  // Reuse the scanner's strict HTTP/status/duplicate-key validation. Pending
+  // destinations are deliberately not accepted by this release mode.
+  const script = 'import sys; sys.path.insert(0, sys.argv[1]); from github_refs import GitHubResolver; sys.exit(0 if GitHubResolver().resolve(sys.argv[2]) == "public" else 1)';
+  try {
+    execFileSync('python3', ['-B', '-c', script, resolve(import.meta.dirname, '../../scripts/publish-check'), destination.identity],
+      { stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch { throw Error('Public destination must exist and have confirmed public visibility'); }
+}
+
+export function remotePublicHead(repo, destination, tag) {
+  const headRef = `refs/heads/${destination.branch}`, tagRef = `refs/tags/${tag}`;
+  const lines = publicGit(repo, ['--git-dir=/dev/null', 'ls-remote', '--refs', '--', destination.url, headRef, tagRef]).toString().trim().split('\n').filter(Boolean);
+  if (lines.length !== 1) throw Error('Public destination must have one unambiguous branch and no release tag');
+  const fields = lines[0].split('\t');
+  if (fields.length !== 2 || fields[1] !== headRef || !/^[0-9a-f]{40}$/.test(fields[0])) throw Error('Public destination branch is missing or ambiguous');
+  return fields[0];
+}
+
+export function assertPublicTree(repo, commit, sourceTreeId) {
+  if (publicOid(repo, 'rev-parse', `${commit}^{tree}`) !== sourceTreeId) throw Error('Public child changed the selected source tree');
+}
+
+export function publicChild(source, temporary, destination, parent, tagged) {
+  const repo = sourceTree(source, resolve(temporary, 'public-child'));
+  publicGit(repo, ['init', '-q', '--template=', '-b', destination.branch]);
+  publicGit(repo, ['fetch', '--quiet', '--no-tags', '--no-recurse-submodules', '--no-write-fetch-head', '--',
+    destination.url, `refs/heads/${destination.branch}:refs/public-release/parent`]);
+  if (publicOid(repo, 'rev-parse', 'refs/public-release/parent') !== parent ||
+      publicOid(repo, 'cat-file', '-t', parent) !== 'commit' ||
+      publicOid(repo, 'rev-parse', '--is-shallow-repository') !== 'false') throw Error('Public parent changed or is not a complete commit');
+  // Store only selected source blobs; never copy or fetch private Git objects.
+  // Index plumbing avoids clean filters and all export/working-tree attributes.
+  const records = [];
+  for (const [path, entry] of source.entries) {
+    const oid = publicGit(repo, ['hash-object', '-w', '--stdin', '--no-filters'], source.bytes(path)).toString().trim();
+    if (oid !== entry.oid) throw Error('Public source blob identity changed');
+    records.push(`${entry.mode} ${oid}\t${path}\0`);
+  }
+  publicGit(repo, ['update-index', '-z', '--index-info'], Buffer.from(records.join('')));
+  const tree = publicOid(repo, 'write-tree');
+  if (tree !== source.tree) throw Error('Public child changed the selected source tree');
+  const commit = publicGit(repo, ['commit-tree', tree, '-p', parent, '-F', '-'], Buffer.from(releaseMessage(source) + '\n')).toString().trim();
+  publicGit(repo, ['update-ref', `refs/heads/${destination.branch}`, commit]);
+  publicGit(repo, ['update-ref', '-d', 'refs/public-release/parent']);
+  assertPublicTree(repo, commit, source.tree);
+  if (publicOid(repo, 'rev-list', '--parents', '-n', '1', commit) !== `${commit} ${parent}`) throw Error('Public child must have exactly the pinned public parent');
+  let tagObject = null;
+  if (tagged) {
+    publicGit(repo, ['tag', '-a', '--cleanup=verbatim', source.tag, commit, '-F', '-'], Buffer.from(releaseMessage(source) + '\n'));
+    tagObject = publicOid(repo, 'rev-parse', `refs/tags/${source.tag}`);
+  }
+  return { repo, commit, parent, tagObject };
+}

package/modules/release/public-git.mjs

@@ -0,0 +1,21 @@
+import { execFileSync } from 'node:child_process';
+
+// Public construction never inherits alternate object stores, templates, filters,
+// replacement ancestry, hooks, signing, credential URL rewrites or global config.
+export function publicGit(repo, args, input) {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+  Object.assign(env, { GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null',
+    GIT_NO_REPLACE_OBJECTS: '1', GIT_NO_LAZY_FETCH: '1', GIT_GRAFT_FILE: '/dev/null', GIT_TERMINAL_PROMPT: '0' });
+  try {
+    return execFileSync('git', ['--no-replace-objects', '-C', repo,
+      '-c', 'core.hooksPath=/dev/null', '-c', 'core.useReplaceRefs=false',
+      '-c', 'core.attributesFile=/dev/null', '-c', 'core.autocrlf=false',
+      '-c', 'commit.gpgSign=false', '-c', 'tag.gpgSign=false',
+      '-c', 'user.name=Run Edit Run', '-c', 'user.email=releases@runeditrun.invalid',
+      '-c', 'protocol.ext.allow=never', '-c', 'protocol.fd.allow=never',
+      '-c', 'gc.auto=0', '-c', 'maintenance.auto=false', ...args],
+    { env, input, stdio: ['pipe', 'pipe', 'pipe'], maxBuffer: 128 * 1024 * 1024 });
+  } catch { throw Error('Public Git operation failed'); }
+}
+
+export const publicOid = (repo, ...args) => publicGit(repo, args).toString().trim();

package/modules/release/publication-scan.mjs

@@ -0,0 +1,22 @@
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+export function validatePublicationDestination(source, project, repository) {
+  try {
+    execFileSync('python3', ['-B', resolve(import.meta.dirname, '../../scripts/publish-check/destination.py'),
+      '--repo', source.repo, '--ref', source.commit, '--project', project, '--repository', repository],
+    { stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch { throw Error('Publication destination must agree with the committed edition and project identities'); }
+}
+
+export function publicationScan(repo, ref, envFile, project, repository, publicBase) {
+  try {
+    return JSON.parse(execFileSync(process.execPath,
+      [resolve(import.meta.dirname, '../../scripts/publish-check.mjs'), '--repo', repo, '--ref', ref,
+        ...(publicBase ? ['--public-base', publicBase] : []), ...(project != null ? ['--project', project] : []), ...(repository != null ? ['--repository', repository] : []), ...(envFile ? ['--env-file', envFile] : [])],
+      { stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 128 * 1024 * 1024 }));
+  } catch (error) {
+    try { return JSON.parse(error.stdout); }
+    catch { throw Error('Publication inspection did not produce a report'); }
+  }
+}

package/modules/release/publish-handoff.mjs

@@ -0,0 +1,37 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { sha256, json } from './catalogue.mjs';
+
+const quote = value => "'" + String(value).replaceAll("'", "'\\''") + "'";
+// A test command must not mask a failed command substitution with matching output.
+const requireOutput = (command, expected) => `release_output=$(${command}) || exit 1\ntest "$release_output" = ${expected}`;
+
+export function writePublishHandoff(output, destination, receipt) {
+  const { commit, tree, tagObject } = receipt.publicExport;
+  const parent = receipt.publicParent;
+  const tag = receipt.tag.name;
+  // Embedded identities and receipt digest bind the commands to this artifact,
+  // including when pasted from an unrelated working directory.
+  const script = [
+    'set -eu',
+    `artifact=${quote(output)}`,
+    'cd -- "$artifact/public-git"',
+    requireOutput(`node -e 'const fs=require("node:fs"),c=require("node:crypto"); process.stdout.write(c.createHash("sha256").update(fs.readFileSync(process.argv[1])).digest("hex"))' "$artifact/release-receipt.json"`, quote(sha256(json(receipt)))),
+    requireOutput(`node -e 'const fs=require("node:fs"),c=require("node:crypto"); process.stdout.write(c.createHash("sha256").update(fs.readFileSync(process.argv[1])).digest("hex"))' "$artifact/publish-check.json"`, quote(receipt.gates.publishCheck.reportSha256)),
+    requireOutput(`node -e 'const fs=require("node:fs"),c=require("node:crypto"); process.stdout.write(c.createHash("sha256").update(fs.readFileSync(process.argv[1])).digest("hex"))' "$artifact/public-git/.git/config"`, quote(sha256(readFileSync(resolve(output, 'public-git/.git/config'))))),
+    '# Discard inherited Git overrides while keeping authentication in the environment.',
+    'release_git() {',
+    `  node -e ${quote('const cp=require("node:child_process"); const env=Object.fromEntries(Object.entries(process.env).filter(([k])=>!k.startsWith("GIT_") && k!=="GH_DEBUG" && k!=="DEBUG")); Object.assign(env,{GIT_CONFIG_NOSYSTEM:"1",GIT_CONFIG_GLOBAL:"/dev/null",GIT_NO_REPLACE_OBJECTS:"1",GIT_GRAFT_FILE:"/dev/null",GIT_TERMINAL_PROMPT:"0"}); const result=cp.spawnSync("git",["--no-replace-objects","-c","core.hooksPath=/dev/null","-c","core.useReplaceRefs=false","-c","push.followTags=false","-c","credential.helper=","-c","credential.helper=!gh auth git-credential",...process.argv.slice(1)],{env,stdio:"inherit"}); process.exit(result.status??1);')} -- "$@"`,
+    '}',
+    requireOutput('release_git rev-parse --show-toplevel', '"$artifact/public-git"'),
+    requireOutput('release_git rev-parse HEAD', quote(commit)),
+    requireOutput("release_git rev-parse 'HEAD^{tree}'", quote(tree)),
+    requireOutput('release_git rev-list --parents -n 1 HEAD', quote(`${commit} ${parent}`)),
+    requireOutput(`release_git cat-file -t ${quote(`refs/tags/${tag}`)}`, 'tag'),
+    requireOutput(`release_git rev-parse ${quote(`refs/tags/${tag}`)}`, quote(tagObject)),
+    requireOutput(`release_git rev-parse ${quote(`refs/tags/${tag}^{commit}`)}`, quote(commit)),
+    requireOutput(`release_git ls-remote --refs -- ${quote(destination.url)} ${quote(`refs/heads/${destination.branch}`)} ${quote(`refs/tags/${tag}`)}`, quote(`${parent}\trefs/heads/${destination.branch}`)),
+    `release_git push --atomic --no-follow-tags -- ${quote(destination.url)} ${quote(`${commit}:refs/heads/${destination.branch}`)} ${quote(`${tagObject}:refs/tags/${tag}`)}`,
+  ].join('\n');
+  writeFileSync(resolve(output, 'PUBLISH.md'), `# Publish the reviewed public child\n\nThe producer has not pushed anything. Review the receipt and publication report before running these commands. They publish exactly the public child and its annotated tag to the declared destination with one ordinary atomic push. A moved branch or existing tag requires a fresh release artifact; do not force the push. Authentication uses your existing GitHub CLI credentials.\n\n\`\`\`sh\n${script}\n\`\`\`\n`, { flag: 'wx' });
+}

package/modules/release/source.mjs

@@ -0,0 +1,71 @@
+import { mkdtemp,rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { shared } from '../../cli/shared.mjs';
+import { execFileSync, spawn } from 'node:child_process';
+import { realpathSync, existsSync, lstatSync, mkdirSync } from 'node:fs';
+import { resolve, dirname, relative, isAbsolute } from 'node:path';
+import { testSummary } from './test-summary.mjs';
+
+export function git(repo, ...args) {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+  Object.assign(env, { GIT_NO_REPLACE_OBJECTS: '1', GIT_NO_LAZY_FETCH: '1', GIT_TERMINAL_PROMPT: '0',
+    GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_GRAFT_FILE: '/dev/null' });
+  try {
+    return execFileSync('git', ['--no-replace-objects', '-c', 'core.useReplaceRefs=false', '-c', 'core.hooksPath=/dev/null', '-C', repo, ...args],
+      { env, stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 128 * 1024 * 1024 });
+  } catch { throw Error('Git source operation failed'); }
+}
+
+export function inspectSource(repo, ref) {
+  repo = realpathSync(repo);
+  if (git(repo, 'status', '--porcelain', '--untracked-files=all').length) throw Error('Release requires a clean source checkout');
+  const commit = git(repo, 'rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`).toString().trim();
+  const tree = git(repo, 'rev-parse', `${commit}^{tree}`).toString().trim();
+  const records = git(repo, 'ls-tree', '-r', '-z', commit).toString().split('\0').filter(Boolean);
+  const entries = new Map(records.map(record => {
+    const separator = record.indexOf('\t');
+    const header = record.slice(0, separator), path = record.slice(separator + 1);
+    const [mode, type, oid] = header.split(' ');
+    if (!path || path.split('/').some(part => ['', '.', '..', '.git'].includes(part)) || path.includes('\\')) throw Error('Unsafe Git tree path');
+    return [path, { mode, type, oid }];
+  }));
+  const bytes = path => {
+    const entry = entries.get(path);
+    if (!entry || entry.type !== 'blob' || !['100644', '100755'].includes(entry.mode)) throw Error('Release input must be a committed ordinary file');
+    return git(repo, 'cat-file', 'blob', entry.oid);
+  };
+  const seed = JSON.parse(bytes('seed.json'));
+  const pkg = JSON.parse(bytes('package.json'));
+  const release = JSON.parse(bytes('RELEASE.json'));
+  if (!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/.test(seed.version) ||
+      pkg.version !== seed.version || release.version !== seed.version || !pkg.scripts?.verify) throw Error('Seed, package and release versions must agree, and verify must exist');
+  const timestamp = git(repo, 'log', '-1', '--format=%cI', commit).toString().trim();
+  return { repo, commit, tree, entries, bytes, seed, release, timestamp, tag: `v${seed.version}` };
+}
+
+export function newOutput(repo, output) {
+  output = resolve(output);
+  for (let ancestor = output; ; ancestor = dirname(ancestor)) {
+    if (existsSync(ancestor) && lstatSync(ancestor).isSymbolicLink()) throw Error('Output cannot traverse symlinks');
+    if (ancestor === dirname(ancestor)) break;
+  }
+  if (existsSync(output)) throw Error('Output must be a new directory');
+  const rel = relative(repo, output);
+  if (!rel || (!isAbsolute(rel) && !rel.startsWith('..' + '/'))) throw Error('Output must be outside the source checkout');
+  mkdirSync(output, { recursive: true });
+  return output;
+}
+
+// Keep child diagnostics private: arbitrary verify scripts can print credential
+// values. Only exit status and numeric test summaries leave this boundary.
+export async function command(command, args, cwd) {
+ const {createCommands}=await shared('commands.mjs');
+ const directory=await mkdtemp(resolve(tmpdir(),'rer-release-'));
+ const store=await createCommands(directory,{logs:[]},{terminal:()=>{},queue:{verb:'release'}});
+ const summary=testSummary(),env={...process.env,FORCE_COLOR:'0'};delete env.NODE_TEST_CONTEXT;
+ try {
+  await store.run('Release verification',command,args,{cwd,env,onChild:child=>child.stdout.on('data',bytes=>summary.write(bytes))});
+  return {status:'PASS',exitCode:0,...summary.finish()};
+ }catch(error){return {status:'FAIL',exitCode:error.childExitCode??null,...summary.finish()};}
+ finally{await store.closeCommands();await rm(directory,{recursive:true,force:true});}
+}

package/modules/release/test-summary.mjs

@@ -0,0 +1,50 @@
+import { StringDecoder } from 'node:string_decoder';
+import { stripVTControlCharacters } from 'node:util';
+
+const nodeFields = { tests: 'tests', pass: 'passed', fail: 'failed', skipped: 'skipped', cancelled: 'cancelled', todo: 'todo' };
+const playwrightFields = { passed: 'passed', failed: 'failed', skipped: 'skipped', flaky: 'flaky', interrupted: 'interrupted', 'did not run': 'notRun' };
+
+// Retain only bounded, complete lines and expose only numeric counters. These
+// are reporter summaries, not individual test titles, retries or diagnostics.
+export function testSummary() {
+  const decoder = new StringDecoder('utf8');
+  const counts = { tests: 0, passed: 0, failed: 0, skipped: 0, flaky: 0 };
+  let pending = '', oversized = false;
+
+  function line(raw) {
+    const text = stripVTControlCharacters(raw).replace(/\r$/, '');
+    const node = /^(?:ℹ|#)[ \t]+(tests|pass|fail|skipped|cancelled|todo)[ \t]+(\d+)[ \t]*$/.exec(text);
+    const playwright = /^ {2}(\d+) (passed \(\d+(?:\.\d+)?(?:ms|s|m|h|d)\)|failed|skipped|flaky|interrupted|did not run)[ \t]*$/.exec(text);
+    if (!node && !playwright) return;
+    const field = node ? nodeFields[node[1]] : playwrightFields[playwright[2].startsWith('passed ') ? 'passed' : playwright[2]];
+    const value = Number(node ? node[2] : playwright[1]);
+    if (!Number.isSafeInteger(value) || !Number.isSafeInteger((counts[field] ?? 0) + value) ||
+        (playwright && !Number.isSafeInteger(counts.tests + value))) return;
+    if (value || field in counts) counts[field] = (counts[field] ?? 0) + value;
+    // Node supplies its total explicitly; Playwright's outcome buckets are disjoint.
+    if (playwright) counts.tests += value;
+  }
+
+  function consume(text) {
+    for (const part of text.split(/(?<=\n)/)) {
+      if (!oversized) {
+        if (pending.length + part.length > 8192) { pending = ''; oversized = true; }
+        else pending += part;
+      }
+      if (part.endsWith('\n')) {
+        if (!oversized) line(pending.slice(0, -1));
+        pending = ''; oversized = false;
+      }
+    }
+  }
+
+  return {
+    write(bytes) { consume(decoder.write(bytes)); },
+    finish() {
+      consume(decoder.end());
+      if (!oversized && pending) line(pending);
+      pending = ''; oversized = false;
+      return { ...counts };
+    },
+  };
+}