@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/resolve-release/scripts/plan-npm.test.mjs

@@ -0,0 +1,659 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createHash } from 'node:crypto'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { planRelease } from './plan.mjs'
+import { probeNpmVersionAbsence } from './npm-version-absence.mjs'
+
+const version = '1.3.0'
+const now = new Date('2026-10-19T12:00:00Z')
+const original = '## [1.3.0] - 2026-10-18\n\n- Original reviewed notes.\n'
+const reviewed = '## [1.3.0] - 2026-10-18\n\n- Corrected reviewed notes.\n'
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex')
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`
+
+function fixture(t, { name = '@example/demo', format = 3, lock = true, preparedVersion = version, transform = (files) => files } = {}) {
+  const base = mkdtempSync(join(tmpdir(), 'prepared-npm-'))
+  t.after(() => rmSync(base, { recursive: true, force: true }))
+  const cwd = join(base, 'repo')
+  const remote = join(base, 'origin.git')
+  const home = join(base, 'home')
+  for (const directory of [cwd, remote, home]) mkdirSync(directory)
+  const env = {
+    PATH: process.env.PATH, HOME: home, TMPDIR: base, LC_ALL: 'C', TZ: 'UTC',
+    GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_ATTR_NOSYSTEM: '1',
+    GIT_ALLOW_PROTOCOL: 'file', GIT_TERMINAL_PROMPT: '0',
+    GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'core.hooksPath', GIT_CONFIG_VALUE_0: '/dev/null',
+    GIT_AUTHOR_DATE: now.toISOString(), GIT_COMMITTER_DATE: now.toISOString(),
+  }
+  const gitAt = (directory, ...args) => {
+    const result = spawnSync('git', args, { cwd: directory, env, timeout: 10_000, maxBuffer: 16 * 1024 * 1024 })
+    assert.equal(result.status, 0, result.stderr?.toString('utf8'))
+    return result.stdout
+  }
+  const bytes = (...args) => gitAt(cwd, ...args)
+  const git = (...args) => bytes(...args).toString('utf8').trim()
+  git('init', '--template=', '-b', 'main')
+  git('config', 'user.email', 'fixture@example.invalid')
+  git('config', 'user.name', 'Offline Fixture')
+  git('config', 'commit.gpgsign', 'false')
+  git('config', 'tag.gpgsign', 'false')
+  gitAt(remote, 'init', '--bare', '--template=')
+  git('remote', 'add', 'origin', 'https://github.com/example/demo.git')
+  git('config', `url.${remote}.insteadOf`, 'https://github.com/example/demo.git')
+  const snapshots = {}
+  const commit = (stage, releaseVersion) => {
+    const pkg = { name, version: releaseVersion, scripts: { test: 'node --test' }, dependencies: { dep: '^1.0.0' } }
+    const files = {
+      'package.json': json(pkg), VERSION: `${releaseVersion}\n`,
+      'CHANGELOG.md': `# Changelog\n\n${stage === 'target' ? reviewed : stage === 'parent' ? '## [1.2.0] - 2026-10-01\n\n- Old release.\n' : original}`,
+      'index.js': stage === 'target' ? 'export const fixed = true\n' : 'export const fixed = false\n',
+    }
+    if (lock) files['package-lock.json'] = json({
+      name, version: releaseVersion, lockfileVersion: format,
+      packages: {
+        '': { name, version: releaseVersion, dependencies: { dep: '^1.0.0' } },
+        'node_modules/dep': { version: '1.0.0', resolved: 'https://invalid.example/dep.tgz', integrity: 'sha512-fixture' },
+      },
+    })
+    files['CHANGELOG.md'] = files['CHANGELOG.md'].replaceAll(version, preparedVersion)
+    const changed = transform(files, stage)
+    for (const file of Object.keys(files)) if (!Object.hasOwn(changed, file)) rmSync(join(cwd, file), { force: true })
+    for (const [file, content] of Object.entries(changed)) writeFileSync(join(cwd, file), content)
+    git('add', '.')
+    git('commit', '--allow-empty', '-m', `chore: ${stage}`)
+    snapshots[stage] = Object.fromEntries(Object.keys(changed).map((file) => [file, readFileSync(join(cwd, file))]))
+    return git('rev-parse', 'HEAD')
+  }
+  const parentSha = commit('parent', '1.2.0')
+  git('tag', 'v1.2.0')
+  git('switch', '-c', 'metadata')
+  const cutSha = commit('cut', preparedVersion)
+  git('switch', 'main')
+  git('merge', '--no-ff', 'metadata', '-m', 'Merge reviewed metadata')
+  const mergeSha = git('rev-parse', 'HEAD')
+  const sourceSha = commit('previous', preparedVersion)
+  const sha = commit('target', preparedVersion)
+  git('push', 'origin', 'main', '--tags')
+  const receipt = join(cwd, '.git', 'resolve-release-authorization.json')
+  const receiptBytes = Buffer.from('historical receipt: no authority for this attempt\n')
+  writeFileSync(receipt, receiptBytes)
+  const preparedMetadata = {
+    schema: 'prepared-release-metadata/v2', repository: 'example/demo', version: preparedVersion, metadataPr: 42, cutSha, mergeSha,
+    previousAttempt: { kind: 'pre-tag', receiptId: 'failed-pre-tag-attempt', receiptSha256: digest(receiptBytes), sourceSha },
+  }
+  const plan = (options = {}) => {
+    const inherited = process.env
+    process.env = env
+    try { return planRelease({ cwd, sha, preparedMetadata, now, ...options }) } finally { process.env = inherited }
+  }
+  const cli = (options = {}) => {
+    const input = join(cwd, '.git', 'prepared.json')
+    writeFileSync(input, json(options.input ?? preparedMetadata))
+    return spawnSync(process.execPath, [join(import.meta.dirname, 'plan.mjs'), '--sha', options.sha ?? sha,
+      '--prepared-metadata', input, '--json', ...(options.args ?? [])], {
+      cwd, env: options.env ?? env, encoding: 'utf8', timeout: 20_000,
+    })
+  }
+  const unchanged = () => {
+    const refs = git('show-ref')
+    const remoteRefs = gitAt(remote, 'show-ref')
+    const status = git('status', '--porcelain')
+    const head = git('rev-parse', 'HEAD')
+    const files = Object.fromEntries(Object.keys(snapshots.target).map((file) => [file, readFileSync(join(cwd, file))]))
+    return () => {
+      assert.equal(git('show-ref'), refs)
+      assert.deepEqual(gitAt(remote, 'show-ref'), remoteRefs)
+      assert.equal(git('status', '--porcelain'), status)
+      assert.equal(git('rev-parse', 'HEAD'), head)
+      for (const [file, content] of Object.entries(files)) assert.deepEqual(readFileSync(join(cwd, file)), content)
+      assert.deepEqual(readFileSync(receipt), receiptBytes)
+    }
+  }
+  return { cwd, remote, env, git, bytes, gitAt, sha, sourceSha, parentSha, cutSha, mergeSha, snapshots,
+    receipt, receiptBytes, preparedMetadata, plan, cli, unchanged }
+}
+
+function editJson(files, file, change) {
+  const value = JSON.parse(files[file])
+  change(value)
+  return { ...files, [file]: json(value) }
+}
+
+test('genuine pre-tag npm reuse needs no RC and preserves frozen source, provenance and repository bytes via API and CLI', (t) => {
+  const f = fixture(t)
+  assert.equal(f.git('tag', '--list', '*-rc.*'), '')
+  assert.equal(f.gitAt(f.remote, 'tag', '--list', '*-rc.*').length, 0)
+  const verify = f.unchanged()
+  const plan = f.plan()
+  assert.equal(plan.sha, f.sha)
+  assert.equal(plan.releaseSourceSha, f.sha)
+  assert.equal(plan.bump, 'none')
+  assert.equal(plan.currentVersion, version)
+  assert.equal(plan.nextVersion, version)
+  assert.equal(plan.tag, `v${version}`)
+  assert.equal(plan.candidateTag, null)
+  assert.deepEqual(plan.artifact, { kind: 'npm', packageName: '@example/demo', version })
+  assert.deepEqual(plan.versionFiles, ['package.json', 'package-lock.json', 'VERSION'])
+  assert.equal(plan.changelogMarkdown, reviewed)
+  assert.equal(plan.metadata.originalSectionSha256, digest(original))
+  assert.equal(plan.metadata.preparedSectionSha256, digest(reviewed))
+  assert.equal(plan.metadata.mode, 'reuse-prepared')
+  assert.equal(plan.metadata.schema, f.preparedMetadata.schema)
+  assert.deepEqual(plan.metadata.previousAttempt, f.preparedMetadata.previousAttempt)
+  assert.deepEqual(plan.metadata.remoteInspection, {
+    remote: 'origin', finalTagAbsent: `v${version}`, candidateTagAbsent: null, inspectedAt: now.toISOString(),
+  })
+  assert.notEqual(plan.receiptId, f.preparedMetadata.previousAttempt.receiptId)
+  assert.notEqual(f.plan().receiptId, plan.receiptId)
+  const result = f.cli()
+  assert.equal(result.status, 0, result.stderr)
+  const output = JSON.parse(result.stdout)
+  assert.deepEqual(output.artifact, plan.artifact)
+  assert.deepEqual(output.metadata.previousAttempt, f.preparedMetadata.previousAttempt)
+  assert.equal(output.releaseSourceSha, f.sha)
+  assert.equal(output.candidateTag, null)
+  verify()
+  writeFileSync(join(f.cwd, 'package.json'), json({ name: 'dirty', version: '9.0.0' }))
+  f.git('add', '.')
+  f.git('commit', '-m', 'chore: later source must not replace frozen target')
+  assert.equal(f.plan().metadata.preparedSectionSha256, digest(reviewed))
+  assert.deepEqual(f.plan().artifact, plan.artifact)
+})
+
+for (const [name, format, lock] of [['demo', 2, true], ['@example/demo', 3, true], ['demo', 3, false], ['a'.repeat(214), 2, false]]) {
+  test(`npm pre-tag accepts ${name.slice(0, 24)} with ${lock ? `lock v${format}` : 'no lock'}`, (t) => {
+    const f = fixture(t, { name, format, lock, transform: (files) => editJson(files, 'package.json', (pkg) => { pkg.private = false }) })
+    assert.deepEqual(f.plan().artifact, { kind: 'npm', packageName: name, version })
+    assert.equal(f.plan({ sha: f.sourceSha }).releaseSourceSha, f.sourceSha)
+    const input = structuredClone(f.preparedMetadata)
+    input.previousAttempt.sourceSha = f.mergeSha
+    assert.equal(f.plan({ sha: f.mergeSha, preparedMetadata: input }).releaseSourceSha, f.mergeSha)
+  })
+}
+
+const invalidPackages = [
+  ['missing name', (pkg) => { delete pkg.name }, /package.json.*name/],
+  ...['Upper', '.dot', '_underscore', '@Scope/pkg', '@scope/.pkg', '@scope', 'a/b', 'has space', 'a%2fb', 'a?b', 'node_modules', 'favicon.ico', '', 'x'.repeat(215)]
+    .map((name) => [`unsafe name ${name.slice(0, 15)}`, (pkg) => { pkg.name = name }, /package.json.*name/]),
+  ['private true', (pkg) => { pkg.private = true }, /private/],
+  ['private null', (pkg) => { pkg.private = null }, /private/],
+  ['private string', (pkg) => { pkg.private = 'false' }, /private/],
+  ['empty workspaces', (pkg) => { pkg.workspaces = [] }, /workspaces/],
+  ['null workspaces', (pkg) => { pkg.workspaces = null }, /workspaces/],
+  ['workspace object', (pkg) => { pkg.workspaces = { packages: [] } }, /workspaces/],
+  ['stale package version', (pkg) => { pkg.version = '1.2.0' }, /package.json.*version/],
+  ['non-string version', (pkg) => { pkg.version = 1.3 }, /package.json.*version/],
+]
+
+test('npm pre-tag refuses invalid or non-publishable package identities', async (t) => {
+  for (const [label, change, error] of invalidPackages) {
+    await t.test(label, (t) => {
+      const f = fixture(t, { transform: (files, stage) => stage === 'target' ? editJson(files, 'package.json', change) : files })
+      assert.throws(f.plan, error)
+    })
+  }
+})
+
+const invalidLocks = [
+  ['top name', (value) => { value.name = 'foreign' }, /lock.*name/],
+  ['missing top name', (value) => { delete value.name }, /lock.*name/],
+  ['stale top version', (value) => { value.version = '1.2.0' }, /lock.*version/],
+  ['stale root version', (value) => { value.packages[''].version = '1.2.0' }, /lock.*version/],
+  ['missing root version', (value) => { delete value.packages[''].version }, /lock.*version/],
+  ['foreign root name', (value) => { value.packages[''].name = 'foreign' }, /lock.*name/],
+  ['missing root name', (value) => { delete value.packages[''].name }, /lock.*name/],
+  ['missing root', (value) => { delete value.packages[''] }, /lock.*root/],
+  ['missing packages', (value) => { delete value.packages }, /lock.*root/],
+  ['null root', (value) => { value.packages[''] = null }, /lock.*root/],
+  ['array root', (value) => { value.packages[''] = [] }, /lock.*root/],
+  ['array packages', (value) => { value.packages = [] }, /lock.*root/],
+  ...[1, 4, '3', null, 2.5].map((format) => [`format ${format}`, (value) => { value.lockfileVersion = format }, /lock.*format/]),
+  ['missing format', (value) => { delete value.lockfileVersion }, /lock.*format/],
+]
+
+test('npm pre-tag validates lock identity and supported integer formats at cut, previous source and target', async (t) => {
+  for (const stage of ['cut', 'previous', 'target']) {
+    for (const [label, change, error] of invalidLocks) {
+      await t.test(`${stage}: ${label}`, (t) => {
+        const f = fixture(t, { transform: (files, current) => current === stage ? editJson(files, 'package-lock.json', change) : files })
+        assert.throws(f.plan, error)
+      })
+    }
+  }
+})
+
+test('npm pre-tag rejects stale package and VERSION identities at historical and new sources', async (t) => {
+  for (const stage of ['cut', 'previous', 'target']) {
+    for (const file of ['package.json', 'VERSION']) {
+      await t.test(`${stage}: ${file}`, (t) => {
+        const f = fixture(t, { transform: (files, current) => current !== stage ? files : file === 'VERSION'
+          ? { ...files, VERSION: '1.2.0\n' } : editJson(files, file, (pkg) => { pkg.version = '1.2.0' }) })
+        assert.throws(f.plan, /version.*does not match/)
+      })
+    }
+  }
+})
+
+test('npm pre-tag refuses coordinated renames at previous source or target', async (t) => {
+  for (const stage of ['previous', 'target']) {
+    await t.test(stage, (t) => {
+      const f = fixture(t, { transform: (files, current) => {
+        if (current !== stage) return files
+        return editJson(editJson(files, 'package.json', (pkg) => { pkg.name = 'renamed' }), 'package-lock.json', (lock) => {
+          lock.name = 'renamed'; lock.packages[''].name = 'renamed'
+        })
+      } })
+      assert.throws(f.plan, /name.*prepared identity/)
+    })
+  }
+})
+
+test('metadata-only cut excludes only version positions, never scripts, dependencies, lock edges or integrity', async (t) => {
+  for (const [label, file, change] of [
+    ['scripts', 'package.json', (pkg) => { pkg.scripts.test = 'execute-unreviewed-code' }],
+    ['dependencies', 'package.json', (pkg) => { pkg.dependencies.dep = '^2.0.0' }],
+    ['lock integrity', 'package-lock.json', (lock) => { lock.packages['node_modules/dep'].integrity = 'changed' }],
+    ['lock dependency', 'package-lock.json', (lock) => { lock.packages['node_modules/dep'].version = '2.0.0' }],
+    ['lock root edge', 'package-lock.json', (lock) => { lock.packages[''].dependencies.dep = '^2.0.0' }],
+  ]) {
+    await t.test(label, (t) => {
+      const f = fixture(t, { transform: (files, stage) => stage === 'cut' ? editJson(files, file, change) : files })
+      assert.throws(f.plan, /metadata-only: .*changes more than version identity/)
+    })
+  }
+  await t.test('code hidden in original cut', (t) => {
+    const f = fixture(t, { transform: (files, stage) => stage === 'cut' ? { ...files, 'index.js': 'unreviewed\n' } : files })
+    assert.throws(f.plan, /original cut is not metadata-only/)
+  })
+})
+
+function legacyInput(f) {
+  return { ...f.preparedMetadata, schema: 'prepared-release-metadata/v1', previousAttempt: {
+    receiptId: 'previous-rc', receiptSha256: 'a'.repeat(64),
+    candidateTag: `v${f.preparedMetadata.version}-rc.1`, candidateSha: f.mergeSha,
+  } }
+}
+
+function withNumber(files, file, source) {
+  return { ...files, [file]: files[file].replace(/}\s*$/, `, "config": {"threshold": ${source}}}\n`) }
+}
+
+test('pre-tag numeric identity catches underflow and fraction rounding in both original-cut JSON files; v1 stays compatible', async (t) => {
+  for (const file of ['package.json', 'package-lock.json']) {
+    for (const [label, before, after] of [['underflow', '0', '1e-400'], ['fraction rounding', '0.1', '0.10000000000000001']]) {
+      await t.test(`${file}: ${label}`, (t) => {
+        const f = fixture(t, { transform: (files, stage) => withNumber(files, file, stage === 'parent' ? before : after) })
+        const verify = f.unchanged()
+        assert.throws(f.plan, new RegExp(`metadata-only: ${file} changes more than version identity`))
+        const result = f.cli()
+        assert.equal(result.status, 1)
+        assert.equal(result.stdout, '')
+        assert.match(result.stderr, /changes more than version identity/)
+        assert.equal(f.plan({ preparedMetadata: legacyInput(f) }).nextVersion, version)
+        verify()
+      })
+    }
+  }
+})
+
+test('pre-tag comparison permits unchanged ordinary floats and exact decimal/exponent equivalents with whitespace and key reordering', (t) => {
+  const f = fixture(t, { transform: (files, stage) => {
+    for (const file of ['package.json', 'package-lock.json']) {
+      const value = JSON.parse(files[file])
+      files[file] = JSON.stringify(Object.fromEntries(Object.entries(value).reverse()), null, stage === 'parent' ? 2 : 4)
+      files = withNumber(files, file, stage === 'parent'
+        ? '[0.1, 1e-7, 0.10, 1.25e+2, -0.0100, 1e-400, -0, 0e99999999999999999999, 1e-9007199254740992]'
+        : '[0.1, 1e-7, 1e-1, 125.0, -1e-2, 10e-401, -0.0, 0, 1e-9007199254740992]')
+    }
+    return files
+  } })
+  assert.deepEqual(f.plan().artifact, { kind: 'npm', packageName: '@example/demo', version })
+})
+
+test('pre-tag numeric canonical nodes cannot be impersonated by strings, containers or prototype keys', async (t) => {
+  for (const file of ['package.json', 'package-lock.json']) {
+    for (const [before, after] of [
+      ['0.1', '"0.1"'], ['0.1', '["number","1","-1"]'], ['0.1', '{"data":0.1,"canonical":["number","1","-1"]}'],
+      ['[0.1]', '{"0":0.1}'], ['false', '0'], ['null', '0'], ['-0', '0'],
+      ['{"__proto__":0.1}', '{"__proto__":0.10000000000000001}'],
+      ['{"constructor":{"version":0.1}}', '{"constructor":{"version":0.10000000000000001}}'],
+      ['{"version":0.1}', '{"version":0.10000000000000001}'],
+      ['1e-9007199254740992', '2e-9007199254740992'],
+      // Outside the normalization bound, even equal decimals require identical source tokens.
+      ['1e-9007199254740992', '10e-9007199254740993'],
+    ]) {
+      await t.test(`${file}: ${before} -> ${after}`, (t) => {
+        const f = fixture(t, { transform: (files, stage) => withNumber(files, file, stage === 'parent' ? before : after) })
+        assert.throws(f.plan, /changes more than version identity/)
+      })
+    }
+  }
+})
+
+test('pre-tag rejects unsafe canonical version components in input and consistent root identities while v1 remains compatible', async (t) => {
+  for (const preparedVersion of ['9007199254740992.0.0', '1.9007199254740992.0', '1.3.9007199254740992']) {
+    await t.test(preparedVersion, (t) => {
+      const f = fixture(t, { preparedVersion })
+      assert.throws(f.plan, /version.*safe integer/)
+      const result = f.cli()
+      assert.equal(result.status, 1)
+      assert.equal(result.stdout, '')
+      assert.match(result.stderr, /version.*safe integer/)
+      assert.equal(f.plan({ preparedMetadata: legacyInput(f) }).nextVersion, preparedVersion)
+    })
+  }
+})
+
+test('pre-tag rejects unsafe historical parent versions at every root version position', async (t) => {
+  for (const position of ['package.json', 'package-lock.json', 'lock root', 'VERSION']) {
+    await t.test(position, (t) => {
+      const f = fixture(t, { transform: (files, stage) => {
+        if (stage !== 'parent') return files
+        const huge = '9007199254740992.0.0'
+        if (position === 'VERSION') return { ...files, VERSION: `${huge}\n` }
+        const file = position === 'lock root' ? 'package-lock.json' : position
+        return editJson(files, file, (value) => {
+          if (position === 'lock root') value.packages[''].version = huge
+          else value.version = huge
+        })
+      } })
+      assert.throws(f.plan, /version.*safe integer/)
+      assert.equal(f.plan({ preparedMetadata: legacyInput(f) }).nextVersion, version)
+    })
+  }
+})
+
+test('a valid pre-tag plan artifact passes the real npm helper input boundary using only a fake external E404', (t) => {
+  const f = fixture(t, { preparedVersion: '9007199254740991.3.0' })
+  const artifact = f.plan().artifact
+  const bin = join(f.cwd, '.git', 'fake-npm')
+  const calls = join(bin, 'calls.json')
+  mkdirSync(bin)
+  writeFileSync(join(bin, 'npm'), `#!${process.execPath}
+require('node:fs').writeFileSync(${JSON.stringify(calls)}, JSON.stringify(process.argv.slice(2)))
+process.stderr.write('npm error code E404\\n')
+process.exit(1)
+`, { mode: 0o755 })
+  const inherited = process.env
+  let result
+  try {
+    process.env = { ...f.env, PATH: bin }
+    result = probeNpmVersionAbsence({ packageName: artifact.packageName, version: artifact.version,
+      registry: 'https://registry.example.invalid/custom/', cwd: f.cwd })
+    assert.throws(() => probeNpmVersionAbsence({ packageName: artifact.packageName, version: '9007199254740992.0.0',
+      registry: 'https://registry.example.invalid/custom/', cwd: f.cwd }), /invalid arguments/)
+  } finally { process.env = inherited }
+  assert.equal(result.status, 'absent')
+  assert.equal(result.reason, 'version-absent')
+  assert.deepEqual(JSON.parse(readFileSync(calls, 'utf8')), [
+    'view', '@example/demo@9007199254740991.3.0', 'version', '--registry=https://registry.example.invalid/custom/', '--json',
+  ])
+})
+
+test('reviewed later dependency, script, lock and code edits remain eligible with constant root identities', (t) => {
+  const f = fixture(t, { transform: (files, stage) => {
+    if (!['previous', 'target'].includes(stage)) return files
+    return editJson(editJson(files, 'package.json', (pkg) => {
+      pkg.dependencies.dep = '^2.0.0'; pkg.scripts.test = 'node --test test'
+    }), 'package-lock.json', (lock) => {
+      lock.packages[''].dependencies.dep = '^2.0.0'
+      lock.packages['node_modules/dep'].version = '2.0.0'
+      lock.packages['node_modules/dep'].integrity = 'reviewed-integrity'
+    })
+  } })
+  assert.equal(f.plan().releaseSourceSha, f.sha)
+  assert.notEqual(f.git('rev-parse', `${f.mergeSha}^{tree}`), f.git('rev-parse', `${f.sha}^{tree}`))
+})
+
+test('npm pre-tag requires a real root package and an unchanged metadata file set', async (t) => {
+  for (const [label, stage, transform, error] of [
+    ['no package', null, (files) => { const copy = { ...files }; delete copy['package.json']; return copy }, /root package.json/],
+    ['target new identity file', 'target', (files) => ({ ...files, 'package-lock.json': json({}) }), /file set/],
+    ['previous missing identity file', 'previous', (files) => { const copy = { ...files }; delete copy.VERSION; return copy }, /file set/],
+    ['cut missing identity file', 'cut', (files) => { const copy = { ...files }; delete copy.VERSION; return copy }, /file set/],
+  ]) {
+    await t.test(label, (t) => {
+      const f = fixture(t, { lock: label !== 'target new identity file', transform: (files, current) => stage === null || current === stage ? transform(files) : files })
+      assert.throws(f.plan, error)
+    })
+  }
+})
+
+test('strict v2 union rejects unknown, missing, null and mixed fields without plan output or writes', (t) => {
+  const f = fixture(t)
+  const p = f.preparedMetadata
+  const previous = p.previousAttempt
+  const invalid = [
+    [{ ...p, schema: 'prepared-release-metadata/v3' }, /schema/],
+    [{ ...p, extra: true }, /unknown field/],
+    ...[null, [], {}, { ...previous, kind: null }, { ...previous, kind: 'other' },
+      { ...previous, candidateTag: null }, { ...previous, candidateSha: f.mergeSha }]
+      .map((previousAttempt) => [{ ...p, previousAttempt }, /previousAttempt|kind/]),
+    ...Object.keys(previous).map((key) => {
+      const value = { ...previous }; delete value[key]
+      return [{ ...p, previousAttempt: value }, /previousAttempt|kind/]
+    }),
+    ...['kind', 'receiptId', 'receiptSha256', 'sourceSha'].map((key) => [{ ...p, previousAttempt: { ...previous, [key]: null } }, /kind|receiptId|receiptSha256|sourceSha/]),
+    [{ ...p, previousAttempt: { ...previous, sourceSha: 'HEAD' } }, /sourceSha.*full/],
+    [{ ...p, previousAttempt: { ...previous, receiptId: '../unsafe' } }, /receiptId/],
+    [{ ...p, previousAttempt: { ...previous, receiptSha256: 'A'.repeat(64) } }, /receiptSha256/],
+    [{ ...p, previousAttempt: { ...previous, kind: 'cloudRunRC' } }, /previousAttempt/],
+    [{ ...p, previousAttempt: { kind: 'cloudRunRC', receiptId: 'rc', receiptSha256: 'a'.repeat(64), candidateTag: null, candidateSha: f.mergeSha } }, /candidateTag/],
+  ]
+  const verify = f.unchanged()
+  for (const [preparedMetadata, error] of invalid) assert.throws(() => f.plan({ preparedMetadata }), error)
+  assert.throws(() => f.plan({ cloudRun: true }), /pre-tag.*cloudRun|pre-tag.*Cloud Run/)
+  const result = f.cli({ args: ['--cloud-run'] })
+  assert.equal(result.status, 1)
+  assert.equal(result.stdout, '')
+  assert.match(result.stderr, /pre-tag.*cloudRun|pre-tag.*Cloud Run/)
+  verify()
+})
+
+test('previous source must resolve to a commit on merge -> previous -> frozen target ancestry', (t) => {
+  const f = fixture(t)
+  const withSource = (sourceSha) => ({ ...f.preparedMetadata, previousAttempt: { ...f.preparedMetadata.previousAttempt, sourceSha } })
+  assert.throws(() => f.plan({ preparedMetadata: withSource('f'.repeat(40)) }), /failed|object|revision/i)
+  assert.throws(() => f.plan({ preparedMetadata: withSource(f.parentSha) }), /historical merge to previous source.*ancestor/)
+  assert.throws(() => f.plan({ sha: f.mergeSha }), /previous source to target.*ancestor/)
+  f.git('tag', '-a', 'annotated-source', '-m', 'Not a commit')
+  const tagObject = f.git('rev-parse', 'annotated-source')
+  assert.throws(() => f.plan({ preparedMetadata: withSource(tagObject) }), /must identify a commit/)
+  f.git('switch', '--orphan', 'unrelated')
+  f.git('add', '.')
+  f.git('commit', '--allow-empty', '-m', 'unrelated root')
+  const unrelated = f.git('rev-parse', 'HEAD')
+  assert.throws(() => f.plan({ preparedMetadata: withSource(unrelated) }), /historical merge to previous source.*ancestor/)
+  assert.throws(() => f.plan({ sha: unrelated }), /ancestor/)
+})
+
+test('any existing final tag spends the version, including a tag on the old source; inspection failure refuses', async (t) => {
+  for (const annotated of [false, true]) {
+    await t.test(annotated ? 'annotated' : 'lightweight', (t) => {
+      const f = fixture(t)
+      f.git('tag', ...(annotated ? ['-a', `v${version}`, f.sourceSha, '-m', 'Spent version'] : [`v${version}`, f.sourceSha]))
+      f.git('push', 'origin', `refs/tags/v${version}`)
+      const verify = f.unchanged()
+      const result = f.cli()
+      assert.equal(result.status, 1)
+      assert.equal(result.stdout, '')
+      assert.match(result.stderr, /final tag already exists.*spent/)
+      verify()
+    })
+  }
+  await t.test('remote inspection unavailable', (t) => {
+    const f = fixture(t)
+    f.git('config', '--unset', `url.${f.remote}.insteadOf`)
+    f.git('config', `url.${join(f.remote, 'missing')}.insteadOf`, 'https://github.com/example/demo.git')
+    const verify = f.unchanged()
+    const result = f.cli()
+    assert.equal(result.status, 1)
+    assert.equal(result.stdout, '')
+    assert.match(result.stderr, /remote inspection failed.*absence is unproven/)
+    verify()
+  })
+})
+
+for (const file of ['package.json', 'package-lock.json']) {
+  for (const stage of ['parent', 'cut', 'previous', 'target']) {
+    test(`strict JSON rejects invalid UTF-8 ${file} at ${stage}`, (t) => {
+      const f = fixture(t, { transform: (files, current) => {
+        const value = JSON.parse(files[file]); value.description = '\uFFFD'
+        const [before, after] = json(value).split('\uFFFD')
+        files[file] = current === stage
+          ? Buffer.concat([Buffer.from(before), Buffer.from([0xfe]), Buffer.from(after)])
+          : json(value)
+        return files
+      } })
+      assert.throws(f.plan, new RegExp(`${file}.*(?:UTF.?8|JSON)`))
+    })
+  }
+  test(`strict JSON refuses non-object, malformed, nonfinite and oversized ${file} without output leakage`, async (t) => {
+    for (const [label, content, error] of [
+      ['null', 'null', /JSON.*object/], ['array', '[]', /JSON.*object/], ['string', '"value"', /JSON.*object/],
+      ['malformed', '{"private-marker":', /JSON/],
+      ['nonfinite number', '{"private-marker":1e400}', /JSON/],
+      ['unsafe integer', '{"private-marker":9007199254740993}', /JSON/],
+      ['oversize', `{"private-marker":"${'x'.repeat(8 * 1024 * 1024)}"}`, /bounded|limit|acquisition/],
+    ]) {
+      await t.test(label, (t) => {
+        const f = fixture(t, { transform: (files, stage) => stage === 'target' ? { ...files, [file]: content } : files })
+        const result = f.cli()
+        assert.equal(result.status, 1)
+        assert.equal(result.stdout, '')
+        assert.match(result.stderr, new RegExp(`${file}.*(?:${error.source})`))
+        assert.doesNotMatch(result.stderr, /private-marker/)
+      })
+    }
+  })
+  test(`strict JSON accepts an exact 8 MiB ${file} and valid Unicode`, (t) => {
+    const limit = 8 * 1024 * 1024
+    const f = fixture(t, { transform: (files, stage) => {
+      if (stage !== 'target') return files
+      const value = JSON.parse(files[file]); value.description = 'caf\u00e9 \u6771\u4eac'
+      const text = json(value)
+      return { ...files, [file]: `${text}${' '.repeat(limit - Buffer.byteLength(text))}` }
+    } })
+    assert.equal(f.bytes('show', `${f.sha}:${file}`).length, limit)
+    assert.equal(f.plan().releaseSourceSha, f.sha)
+  })
+}
+
+test('npm metadata acquisition fails closed on Git errors and timeouts without leaking blob or process output', async (t) => {
+  for (const file of ['package.json', 'package-lock.json']) {
+    for (const [label, action] of [
+      ['process error', 'process.stderr.write("private-git-error"); process.exit(1)'],
+      ['timeout', 'setTimeout(() => process.exit(0), 30_000)'],
+    ]) {
+      await t.test(`${file}: ${label}`, (t) => {
+        const f = fixture(t)
+        const realGit = spawnSync('which', ['git'], { env: f.env, encoding: 'utf8' }).stdout.trim()
+        const bin = join(f.cwd, '.git', 'git-bin')
+        mkdirSync(bin)
+        // Substitute only the external Git blob read; every other Git operation remains real.
+        writeFileSync(join(bin, 'git'), `#!${process.execPath}
+const args = process.argv.slice(2)
+if (args[0] === 'show' && args[1].endsWith(${JSON.stringify(`:${file}`)})) {
+  ${action}
+} else {
+  const { spawnSync } = require('node:child_process')
+  const result = spawnSync(${JSON.stringify(realGit)}, args, { stdio: 'inherit' })
+  process.exit(result.status ?? 1)
+}
+`, { mode: 0o755 })
+        const verify = f.unchanged()
+        const result = f.cli({ env: { ...f.env, PATH: `${bin}:${f.env.PATH}` } })
+        assert.equal(result.status, 1)
+        assert.equal(result.stdout, '')
+        assert.match(result.stderr, new RegExp(`${file} Git blob acquisition failed.*bounded`))
+        assert.doesNotMatch(result.stderr, /private-git-error/)
+        verify()
+      })
+    }
+  }
+})
+
+test('npm identity files must remain regular non-executable Git blobs', async (t) => {
+  for (const file of ['package.json', 'package-lock.json']) {
+    for (const mode of ['symlink', 'executable']) {
+      await t.test(`${file}: ${mode}`, (t) => {
+        const f = fixture(t)
+        if (mode === 'symlink') {
+          rmSync(join(f.cwd, file))
+          symlinkSync('VERSION', join(f.cwd, file))
+          f.git('add', file)
+        } else {
+          f.git('update-index', '--chmod=+x', file)
+        }
+        f.git('commit', '-m', 'chore: unsafe metadata file mode')
+        const sha = f.git('rev-parse', 'HEAD')
+        const result = f.cli({ sha })
+        assert.equal(result.status, 1)
+        assert.equal(result.stdout, '')
+        assert.match(result.stderr, new RegExp(`regular metadata file: ${file}`))
+      })
+    }
+  }
+})
+
+test('Node-only CLI tripwires forbid npm/Python and RC construction or inspection while real Git handles final absence', (t) => {
+  const f = fixture(t)
+  const realGit = spawnSync('which', ['git'], { env: f.env, encoding: 'utf8' }).stdout.trim()
+  const bin = join(f.cwd, '.git', 'tripwires')
+  const calls = join(f.cwd, '.git', 'external-calls.jsonl')
+  mkdirSync(bin)
+  for (const command of ['npm', 'npx', 'python', 'python3']) {
+    writeFileSync(join(bin, command), `#!${process.execPath}\nrequire('node:fs').appendFileSync(${JSON.stringify(calls)}, ${JSON.stringify(`${command}\n`)})\nprocess.exit(99)\n`, { mode: 0o755 })
+  }
+  writeFileSync(join(bin, 'git'), `#!${process.execPath}
+const { spawnSync } = require('node:child_process')
+const { appendFileSync } = require('node:fs')
+const args = process.argv.slice(2)
+appendFileSync(${JSON.stringify(calls)}, JSON.stringify(args) + '\\n')
+if (args.some(arg => arg.includes('-rc.'))) process.exit(98)
+const result = spawnSync(${JSON.stringify(realGit)}, args, { stdio: 'inherit' })
+process.exit(result.status ?? 1)
+`, { mode: 0o755 })
+  const verify = f.unchanged()
+  const result = f.cli({ env: { ...f.env, PATH: `${bin}:${f.env.PATH}` } })
+  assert.equal(result.status, 0, result.stderr)
+  assert.deepEqual(JSON.parse(result.stdout).metadata.previousAttempt, f.preparedMetadata.previousAttempt)
+  const commands = readFileSync(calls, 'utf8').trim().split('\n').map((line) => JSON.parse(line))
+  assert.deepEqual(commands.filter((args) => args[0] === 'ls-remote'), [
+    ['ls-remote', '--tags', 'origin', `refs/tags/v${version}`, `refs/tags/v${version}^{}`],
+  ])
+  assert.equal(commands.some((args) => ['tag', 'update-ref', 'commit', 'switch'].includes(args[0])), false)
+  verify()
+})
+
+test('v2 cloudRunRC preserves RC binding, ordinals and immutability, without changing v1 shape or behavior', (t) => {
+  const f = fixture(t)
+  f.git('tag', '-a', `v${version}-rc.2`, f.mergeSha, '-m', 'Previous immutable RC')
+  f.git('push', 'origin', `refs/tags/v${version}-rc.2`)
+  f.git('tag', `v${version}-rc.4`, f.sha)
+  f.git('push', 'origin', `refs/tags/v${version}-rc.4`)
+  f.git('tag', '-d', `v${version}-rc.4`)
+  const previous = { receiptId: 'previous-rc', receiptSha256: 'a'.repeat(64), candidateTag: `v${version}-rc.2`, candidateSha: f.mergeSha }
+  const v1 = { ...f.preparedMetadata, schema: 'prepared-release-metadata/v1', previousAttempt: previous }
+  const v2 = { ...v1, schema: 'prepared-release-metadata/v2', previousAttempt: { kind: 'cloudRunRC', ...previous } }
+  const verify = f.unchanged()
+  for (const preparedMetadata of [v1, v2]) {
+    const plan = f.plan({ cloudRun: true, preparedMetadata })
+    assert.equal(plan.candidateTag, `v${version}-rc.5`)
+    assert.deepEqual(plan.metadata.previousAttempt, preparedMetadata.previousAttempt)
+    assert.equal(Object.hasOwn(plan, 'artifact'), false)
+    assert.throws(() => f.plan({ cloudRun: true, preparedMetadata: { ...preparedMetadata,
+      previousAttempt: { ...preparedMetadata.previousAttempt, candidateSha: f.sha } } }), /candidateSha.*historical mergeSha/)
+    assert.throws(() => f.plan({ cloudRun: true, preparedMetadata: { ...preparedMetadata,
+      previousAttempt: { ...preparedMetadata.previousAttempt, candidateTag: `v${version}-rc.9007199254740992` } } }), /ordinal/)
+  }
+  assert.throws(() => f.plan({ preparedMetadata: { ...v2, previousAttempt: { ...v2.previousAttempt, sourceSha: f.sourceSha } } }), /unknown field/)
+  assert.throws(() => f.plan({ preparedMetadata: { ...v1, previousAttempt: v2.previousAttempt } }), /unknown field/)
+  verify()
+  f.gitAt(f.remote, 'update-ref', `refs/tags/v${version}-rc.2`, f.sha)
+  assert.throws(() => f.plan({ preparedMetadata: v2, cloudRun: true }), /previous candidate remote tag SHA/)
+})