@1aboveio/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,317 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, 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'
+
+function project(version) {
+  return `[project]\nname = "forex-service"\nversion = "${version}"\nrequires-python = ">=3.11"\ndependencies = ["anyio>=4.6"]\n\n[tool.boundary]\nlabel = "unchanged"\nretry-limit = 12345\n`
+}
+
+function lock(version) {
+  return `version = 1\nrevision = 3\nrequires-python = ">=3.11"\n\n[[package]]\nname = "anyio"\nversion = "4.6.0"\nsource = { registry = "https://pypi.org/simple" }\nsdist = { url = "https://files.pythonhosted.org/anyio.tar.gz", hash = "sha256:${'a'.repeat(64)}", size = 12345 }\n\n[[package]]\nname = "forex-service"\nversion = "${version}"\nsource = { editable = "." }\ndependencies = [{ name = "anyio" }]\n\n[package.metadata]\nrequires-dist = [{ name = "anyio", specifier = ">=4.6" }]\n`
+}
+
+const identityFiles = ['pyproject.toml', 'uv.lock']
+const originalCode = 'def usable_rate(age):\n    return True\n'
+const fixedCode = 'def usable_rate(age):\n    return age < 60\n'
+
+function fixture(t, transform = (files) => files) {
+  const base = mkdtempSync(join(tmpdir(), 'prepared-toml-boundary-'))
+  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)
+  // Whitelist only the executable search path; no inherited credentials, git config or hooks.
+  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: '2026-08-24T12:00:00Z', GIT_COMMITTER_DATE: '2026-08-24T12:00:00Z',
+  }
+  const gitBytes = (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 git = (...args) => gitBytes(cwd, ...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')
+  gitBytes(remote, 'init', '--bare', '--template=')
+  git('remote', 'add', 'origin', 'https://github.com/example/forex-service.git')
+  git('config', `url.${remote}.insteadOf`, 'https://github.com/example/forex-service.git')
+
+  const snapshots = {}
+  const commitStage = (stage, version, message) => {
+    const files = transform({ 'pyproject.toml': project(version), 'uv.lock': lock(version) }, stage)
+    snapshots[stage] = Object.fromEntries(identityFiles.map((file) => [file, Buffer.from(files[file])]))
+    for (const file of identityFiles) writeFileSync(join(cwd, file), snapshots[stage][file])
+    writeFileSync(join(cwd, 'CHANGELOG.md'), `# Changelog\n\n## [${version}] - 2026-08-24\n\n- Updated rates.\n`)
+    writeFileSync(join(cwd, 'rates.py'), stage === 'target' ? fixedCode : originalCode)
+    git('add', '.')
+    git('commit', '-m', message)
+    const sha = git('rev-parse', 'HEAD')
+    // Read blobs without a text encoding: invalid octets must survive the real Git round trip.
+    for (const file of identityFiles) {
+      assert.deepEqual(gitBytes(cwd, 'show', `${sha}:${file}`), snapshots[stage][file], `${stage}:${file} fixture bytes`)
+    }
+    return sha
+  }
+
+  const parentSha = commitStage('parent', '0.6.2', 'chore: existing Python metadata')
+  git('tag', 'v0.6.2')
+  git('switch', '-c', 'metadata')
+  const cutSha = commitStage('cut', '0.7.0', 'chore(release): 0.7.0')
+  git('switch', 'main')
+  git('merge', '--no-ff', 'metadata', '-m', 'Merge reviewed metadata')
+  const mergeSha = git('rev-parse', 'HEAD')
+  git('tag', '-a', 'v0.7.0-rc.1', '-m', 'Failed candidate')
+  git('push', 'origin', 'main', '--tags')
+  const sha = commitStage('target', '0.7.0', 'fix: reject stale cached rates')
+  const preparedMetadata = {
+    schema: 'prepared-release-metadata/v1', repository: 'example/forex-service', version: '0.7.0', metadataPr: 42,
+    cutSha, mergeSha,
+    previousAttempt: {
+      receiptId: 'failed-offline-attempt', receiptSha256: 'a'.repeat(64),
+      candidateTag: 'v0.7.0-rc.1', candidateSha: mergeSha,
+    },
+  }
+  const plan = () => {
+    // planRelease is synchronous; its own git/Python children receive the same offline environment.
+    const inherited = process.env
+    process.env = env
+    try {
+      return planRelease({ cwd, sha, preparedMetadata, cloudRun: true, now: new Date('2026-08-24T12:00:00Z') })
+    } finally {
+      process.env = inherited
+    }
+  }
+  return { cwd, env, sha, parentSha, cutSha, mergeSha, preparedMetadata, git, gitBytes: (...args) => gitBytes(cwd, ...args), plan }
+}
+
+function assertTomlRefusal(f, file, reason) {
+  assert.throws(f.plan, (error) => error instanceof Error && error.message.includes(file) && reason.test(error.message),
+    `prepared reuse must refuse ${file} at the TOML boundary`)
+}
+
+function invalidOctet(text, octet) {
+  // Put a raw invalid UTF-8 octet inside a quoted TOML string, not an escape or U+FFFD.
+  return Buffer.concat([Buffer.from(text), Buffer.from('\n[tool.raw]\nlabel = "'), Buffer.from([octet]), Buffer.from('"\n')])
+}
+
+for (const [file, from, to] of [
+  ['uv.lock', 'size = 12345', 'size = 12345.0'],
+  ['pyproject.toml', 'retry-limit = 12345', 'retry-limit = 12345.0'],
+]) {
+  test(`prepared reuse rejects historical integer-to-float non-version change in ${file}`, (t) => {
+    const f = fixture(t, (files, stage) => {
+      if (stage !== 'parent') files[file] = files[file].replace(from, to)
+      return files
+    })
+    assertTomlRefusal(f, file, /metadata.only|non.version|type|integer|float/i)
+  })
+}
+
+for (const file of identityFiles) {
+  for (const invalidStage of ['parent', 'cut', 'target']) {
+    test(`prepared reuse rejects invalid UTF-8 ${file} at ${invalidStage}`, (t) => {
+      const f = fixture(t, (files, stage) => {
+        files[file] = stage === invalidStage
+          ? invalidOctet(files[file], 0xfe)
+          : `${files[file]}\n[tool.raw]\nlabel = "\uFFFD"\n`
+        return files
+      })
+      assertTomlRefusal(f, file, /UTF.?8|encoding|TOML/i)
+    })
+  }
+
+  test(`prepared reuse rejects distinct historical 0xfe-to-0xff blob collision in ${file}`, (t) => {
+    const f = fixture(t, (files, stage) => {
+      files[file] = invalidOctet(files[file], stage === 'parent' ? 0xfe : 0xff)
+      return files
+    })
+    const before = f.gitBytes('show', `${f.parentSha}:${file}`)
+    const after = f.gitBytes('show', `${f.cutSha}:${file}`)
+    assert.equal(before.includes(Buffer.from([0xfe])), true)
+    assert.equal(after.includes(Buffer.from([0xff])), true)
+    assert.notDeepEqual(before, after)
+    assertTomlRefusal(f, file, /UTF.?8|encoding|TOML/i)
+  })
+}
+
+test('prepared reuse accepts unchanged valid UTF-8 non-ASCII TOML strings', (t) => {
+  const f = fixture(t, (files) => {
+    for (const file of identityFiles) files[file] += '\n[tool.unicode]\nlabel = "caf\u00e9 \u6771\u4eac"\n'
+    return files
+  })
+  const plan = f.plan()
+  assert.equal(plan.releaseSourceSha, f.sha)
+  assert.equal(plan.nextVersion, '0.7.0')
+  assert.equal(plan.bump, 'none')
+  assert.deepEqual(plan.versionFiles, identityFiles)
+})
+
+test('prepared reuse accepts unchanged legitimate fractional and integral-valued TOML floats', (t) => {
+  const f = fixture(t, (files) => {
+    files['pyproject.toml'] += '\n[tool.tuning]\nbackoff = 1.25\nthreshold = 12345.0\n'
+    return files
+  })
+  const plan = f.plan()
+  assert.equal(plan.releaseSourceSha, f.sha)
+  assert.equal(plan.nextVersion, '0.7.0')
+  assert.equal(plan.metadata.mode, 'reuse-prepared')
+})
+
+test('prepared reuse rejects a coordinated target project and editable-root rename at the retained version', (t) => {
+  const f = fixture(t, (files, stage) => {
+    if (stage === 'target') {
+      for (const file of identityFiles) files[file] = files[file].replace('forex-service', 'renamed-service')
+    }
+    return files
+  })
+  assert.throws(f.plan, /name|identity/i, 'the frozen target must retain the original project identity')
+})
+
+for (const stageToChange of ['parent', 'cut', 'target']) {
+  test(`prepared reuse requires an integer uv lock format at ${stageToChange}`, (t) => {
+    const f = fixture(t, (files, stage) => {
+      if (stage === stageToChange) files['uv.lock'] = files['uv.lock'].replace('version = 1\n', 'version = 1.0\n')
+      return files
+    })
+    assertTomlRefusal(f, 'uv.lock', /format|integer|type/i)
+  })
+}
+
+for (const [before, after] of [['editable', 'virtual'], ['virtual', 'editable']]) {
+  test(`prepared reuse rejects target root mode change from ${before} to ${after}`, (t) => {
+    const f = fixture(t, (files, stage) => {
+      files['uv.lock'] = files['uv.lock'].replace('editable = "."', `${stage === 'target' ? after : before} = "."`)
+      return files
+    })
+    assertTomlRefusal(f, 'uv.lock', /source|mode|identity/i)
+  })
+}
+
+for (const [label, before, after] of [
+  ['nested list scalar', '[{ nested = [12345] }]', '[{ nested = [12345.0] }]'],
+  ['tag-shaped user data', '{ type = "int", value = "12345" }', '12345'],
+]) {
+  test(`prepared comparison preserves ${label} types`, (t) => {
+    const f = fixture(t, (files, stage) => {
+      files['pyproject.toml'] += `\n[tool.typed]\nvalue = ${stage === 'parent' ? before : after}\n`
+      return files
+    })
+    assertTomlRefusal(f, 'pyproject.toml', /metadata.only|non.version|type/i)
+  })
+}
+
+test('prepared comparison accepts unchanged nested scalars and reordered TOML keys', (t) => {
+  const f = fixture(t, (files, stage) => {
+    const entries = ['enabled = true', 'values = [12345.0, 1.25, -0.0, 12345, "int"]', 'tag = { type = "int", value = "12345" }']
+    files['pyproject.toml'] += `\n[tool.typed]\n${(stage === 'parent' ? entries : entries.reverse()).join('\n')}\n`
+    return files
+  })
+  assert.equal(f.plan().releaseSourceSha, f.sha)
+})
+
+function runCli(f, env = f.env) {
+  const input = join(f.cwd, '.git', 'prepared.json')
+  writeFileSync(input, JSON.stringify(f.preparedMetadata))
+  return spawnSync(process.execPath, [join(import.meta.dirname, 'plan.mjs'), '--sha', f.sha,
+    '--prepared-metadata', input, '--json'], { cwd: f.cwd, env, encoding: 'utf8', timeout: 15_000 })
+}
+
+test('invalid UTF-8 CLI refusal is sanitized and leaves no plan or repository changes', (t) => {
+  const marker = 'private-metadata-must-not-appear'
+  const f = fixture(t, (files, stage) => {
+    if (stage === 'target') files['pyproject.toml'] = invalidOctet(`${files['pyproject.toml']}\n# ${marker}`, 0xfe)
+    return files
+  })
+  const before = f.git('show-ref')
+  const projectBytes = readFileSync(join(f.cwd, 'pyproject.toml'))
+  const result = runCli(f)
+  assert.equal(result.status, 1)
+  assert.equal(result.stdout, '')
+  assert.match(result.stderr, /pyproject.toml.*(?:TOML|UTF.?8)/i)
+  assert.doesNotMatch(result.stderr, new RegExp(`${marker}|Traceback|UnicodeDecodeError`))
+  assert.equal(f.git('show-ref'), before)
+  assert.equal(f.git('status', '--porcelain'), '')
+  assert.deepEqual(readFileSync(join(f.cwd, 'pyproject.toml')), projectBytes)
+})
+
+test('prepared metadata Git acquisition refuses oversized blobs without printing their content', (t) => {
+  const marker = 'private-oversized-metadata'
+  const f = fixture(t, (files, stage) => {
+    if (stage === 'target') files['pyproject.toml'] += `\n# ${marker}${'x'.repeat(8 * 1024 * 1024)}\n`
+    return files
+  })
+  const result = runCli(f)
+  assert.equal(result.status, 1)
+  assert.equal(result.stdout, '')
+  assert.match(result.stderr, /pyproject.toml.*(?:limit|bounded|acquisition)/i)
+  assert.doesNotMatch(result.stderr, new RegExp(marker))
+  assert.equal(f.git('status', '--porcelain'), '')
+})
+
+for (const file of identityFiles) {
+  test(`prepared metadata Git acquisition accepts an exact 8 MiB ${file} blob`, (t) => {
+    const limit = 8 * 1024 * 1024
+    const f = fixture(t, (files, stage) => {
+      if (stage === 'target') files[file] += `\n#${'x'.repeat(limit - Buffer.byteLength(files[file]) - 3)}\n`
+      return files
+    })
+    assert.equal(f.gitBytes('show', `${f.sha}:${file}`).length, limit)
+    const result = runCli(f)
+    assert.equal(result.status, 0, result.stderr)
+    assert.equal(JSON.parse(result.stdout).releaseSourceSha, f.sha)
+  })
+}
+
+for (const [label, action] of [
+  ['process error', 'process.stderr.write("private-git-error"); process.exit(1)'],
+  ['timeout', 'setTimeout(() => process.exit(0), 30_000)'],
+]) {
+  test(`prepared metadata Git acquisition handles ${label} without leaking output`, (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 process for the bounded metadata-blob read.
+    writeFileSync(join(bin, 'git'), `#!${process.execPath}
+const args = process.argv.slice(2)
+if (args[0] === 'show' && args[1].endsWith(':pyproject.toml')) {
+  ${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 result = runCli(f, { ...f.env, PATH: `${bin}:${f.env.PATH}` })
+    assert.equal(result.status, 1)
+    assert.equal(result.stdout, '')
+    assert.match(result.stderr, /pyproject.toml Git blob acquisition failed.*bounded/)
+    assert.doesNotMatch(result.stderr, /private-git-error|Traceback/)
+    assert.equal(f.git('status', '--porcelain'), '')
+  })
+}
+
+test('prepared reuse permits an unrelated critical code fix after the metadata merge', (t) => {
+  const f = fixture(t)
+  assert.equal(f.gitBytes('show', `${f.cutSha}:rates.py`).toString('utf8'), originalCode)
+  assert.equal(f.gitBytes('show', `${f.sha}:rates.py`).toString('utf8'), fixedCode)
+  assert.notEqual(f.git('rev-parse', `${f.mergeSha}^{tree}`), f.git('rev-parse', `${f.sha}^{tree}`))
+  const plan = f.plan()
+  assert.equal(plan.releaseSourceSha, f.sha)
+  assert.notEqual(plan.releaseSourceSha, f.mergeSha)
+  assert.equal(plan.nextVersion, '0.7.0')
+  assert.equal(plan.metadata.cutSha, f.cutSha)
+  assert.equal(plan.metadata.mergeSha, f.mergeSha)
+})

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

@@ -0,0 +1,291 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+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'
+
+function git(cwd, ...args) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8' })
+  assert.equal(result.status, 0, result.stderr)
+  return result.stdout.trim()
+}
+
+function project(version) {
+  return `[project]\nname = "forex-service"\nversion = "${version}"\nrequires-python = ">=3.11"\ndependencies = ["anyio>=4.6"]\n\n[tool.other]\nversion = "not-the-project"\n`
+}
+
+function root(version, mode = 'editable') {
+  return `[[package]]\nname = "forex-service"\nversion = "${version}"\nsource = { ${mode} = "." }\ndependencies = [{ name = "anyio" }]\n\n[package.metadata]\nrequires-dist = [{ name = "anyio", specifier = ">=4.6" }]\n`
+}
+
+function lock(version, mode = 'editable') {
+  // Minimal uv v1/revision 3 lock: the dependency precedes the project root.
+  return `version = 1\nrevision = 3\nrequires-python = ">=3.11"\n\n[[package]]\nname = "anyio"\nversion = "4.6.0"\nsource = { registry = "https://pypi.org/simple" }\nsdist = { url = "https://files.pythonhosted.org/anyio.tar.gz", hash = "sha256:${'a'.repeat(64)}", size = 12345 }\nwheels = [{ url = "https://files.pythonhosted.org/anyio.whl", hash = "sha256:${'b'.repeat(64)}", size = 23456 }]\n\n${root(version, mode)}`
+}
+
+function fixture(t, { beforeLock = lock('0.4.0'), cutLock = lock('0.7.0'), targetLock = cutLock,
+  cutProject = project('0.7.0'), targetProject = cutProject } = {}) {
+  const cwd = mkdtempSync(join(tmpdir(), 'prepared-python-uv-'))
+  const remote = mkdtempSync(join(tmpdir(), 'prepared-python-origin-'))
+  t.after(() => { rmSync(cwd, { recursive: true, force: true }); rmSync(remote, { recursive: true, force: true }) })
+  git(cwd, 'init', '-b', 'main')
+  git(cwd, 'config', 'user.email', 'dev@example.com')
+  git(cwd, 'config', 'user.name', 'Dev')
+  git(cwd, 'config', 'commit.gpgsign', 'false')
+  git(remote, 'init', '--bare')
+  git(cwd, 'remote', 'add', 'origin', 'https://github.com/example/forex-service.git')
+  git(cwd, 'config', `url.${remote}.insteadOf`, 'https://github.com/example/forex-service.git')
+  writeFileSync(join(cwd, 'pyproject.toml'), project('0.6.2'))
+  writeFileSync(join(cwd, 'uv.lock'), beforeLock)
+  writeFileSync(join(cwd, 'CHANGELOG.md'), '# Changelog\n\n## [0.6.2] - 2026-08-01\n\n- Previous release.\n')
+  git(cwd, 'add', '.')
+  git(cwd, 'commit', '-m', 'chore: existing Python project with stale root lock')
+  git(cwd, 'tag', 'v0.6.2')
+  git(cwd, 'switch', '-c', 'metadata')
+  writeFileSync(join(cwd, 'pyproject.toml'), cutProject)
+  writeFileSync(join(cwd, 'uv.lock'), cutLock)
+  writeFileSync(join(cwd, 'CHANGELOG.md'), '# Changelog\n\n## [0.7.0] - 2026-08-24\n\n- Updated rates.\n')
+  git(cwd, 'add', '.')
+  git(cwd, 'commit', '-m', 'chore(release): 0.7.0')
+  const cutSha = git(cwd, 'rev-parse', 'HEAD')
+  git(cwd, 'switch', 'main')
+  git(cwd, 'merge', '--no-ff', 'metadata', '-m', 'Merge metadata')
+  const mergeSha = git(cwd, 'rev-parse', 'HEAD')
+  git(cwd, 'tag', '-a', 'v0.7.0-rc.1', '-m', 'Failed candidate')
+  git(cwd, 'push', 'origin', 'main', '--tags')
+  writeFileSync(join(cwd, 'uv.lock'), targetLock)
+  writeFileSync(join(cwd, 'pyproject.toml'), targetProject)
+  writeFileSync(join(cwd, 'rates.py'), 'fixed = True\n')
+  git(cwd, 'add', '.')
+  git(cwd, 'commit', '-m', 'fix: candidate failure')
+  const sha = git(cwd, 'rev-parse', 'HEAD')
+  const preparedMetadata = {
+    schema: 'prepared-release-metadata/v1', repository: 'example/forex-service', version: '0.7.0', metadataPr: 42,
+    cutSha, mergeSha,
+    previousAttempt: { receiptId: 'failed-forex-attempt', receiptSha256: 'a'.repeat(64), candidateTag: 'v0.7.0-rc.1', candidateSha: mergeSha },
+  }
+  const plan = (options = {}) => planRelease({ cwd, sha, preparedMetadata, cloudRun: true, ...options })
+  return { cwd, sha, preparedMetadata, plan }
+}
+
+test('Python-only prepared reuse accepts editable uv root-only version repair without writes', (t) => {
+  const f = fixture(t)
+  const receipt = join(f.cwd, '.git', 'resolve-release-authorization.json')
+  writeFileSync(receipt, 'do not reset historical authority')
+  const status = git(f.cwd, 'status', '--porcelain')
+  const plan = f.plan()
+  assert.deepEqual(plan.versionFiles, ['pyproject.toml', 'uv.lock'])
+  assert.equal(plan.currentVersion, '0.7.0')
+  assert.equal(plan.nextVersion, '0.7.0')
+  assert.equal(plan.bump, 'none')
+  assert.equal(plan.candidateTag, 'v0.7.0-rc.2')
+  assert.equal(plan.releaseSourceSha, f.sha)
+  assert.notEqual(plan.receiptId, 'failed-forex-attempt')
+  assert.equal(readFileSync(receipt, 'utf8'), 'do not reset historical authority')
+  assert.equal(git(f.cwd, 'status', '--porcelain'), status)
+  assert.equal(git(f.cwd, 'rev-parse', 'HEAD'), f.sha)
+})
+
+test('Python-only prepared reuse accepts actual Forex virtual root version repair without writes', (t) => {
+  const f = fixture(t, { beforeLock: lock('0.4.0', 'virtual'), cutLock: lock('0.7.0', 'virtual') })
+  const receipt = join(f.cwd, '.git', 'resolve-release-authorization.json')
+  writeFileSync(receipt, 'do not reset historical authority')
+  const refs = git(f.cwd, 'show-ref')
+  const projectBytes = readFileSync(join(f.cwd, 'pyproject.toml'))
+  const lockBytes = readFileSync(join(f.cwd, 'uv.lock'))
+  const plan = f.plan()
+  assert.deepEqual(plan.versionFiles, ['pyproject.toml', 'uv.lock'])
+  assert.equal(plan.currentVersion, '0.7.0')
+  assert.equal(plan.nextVersion, '0.7.0')
+  assert.equal(plan.bump, 'none')
+  assert.equal(plan.candidateTag, 'v0.7.0-rc.2')
+  assert.equal(plan.tag, 'v0.7.0')
+  assert.equal(plan.releaseSourceSha, f.sha)
+  assert.equal(plan.metadata.mode, 'reuse-prepared')
+  assert.notEqual(plan.receiptId, 'failed-forex-attempt')
+  assert.equal(readFileSync(receipt, 'utf8'), 'do not reset historical authority')
+  assert.deepEqual(readFileSync(join(f.cwd, 'pyproject.toml')), projectBytes)
+  assert.deepEqual(readFileSync(join(f.cwd, 'uv.lock')), lockBytes)
+  assert.equal(git(f.cwd, 'show-ref'), refs)
+  assert.equal(git(f.cwd, 'status', '--porcelain'), '')
+  assert.equal(git(f.cwd, 'rev-parse', 'HEAD'), f.sha)
+})
+
+test('Python-only prepared reuse refuses a stale uv root even when the cut did not edit the lock', (t) => {
+  const f = fixture(t, { cutLock: lock('0.4.0') })
+  assert.throws(() => f.plan(), /uv.lock.*version.*does not match/)
+})
+
+const invalidRoots = [
+  ['missing root', (text, version, mode) => text.replace(root(version, mode), ''), /uv.lock.*exactly one/],
+  ['wrong name', (text) => text.replace('name = "forex-service"', 'name = "foreign-service"'), /uv.lock.*name/],
+  ['parent path source', (text, version, mode) => text.replace(`${mode} = "."`, `${mode} = ".."`), /uv.lock.*source/],
+  ['foreign path source', (text, version, mode) => text.replace(`${mode} = "."`, `${mode} = "../foreign"`), /uv.lock.*source/],
+  ['noncanonical root path', (text, version, mode) => text.replace(`${mode} = "."`, `${mode} = "./"`), /uv.lock.*source/],
+  ['registry-only source', (text, version, mode) => text.replace(`${mode} = "."`, 'registry = "https://pypi.org/simple"'), /uv.lock.*source/],
+  ['mixed root source', (text, version, mode) => text.replace(`${mode} = "."`, 'editable = ".", virtual = "."'), /uv.lock.*source/],
+  ['extra registry field', (text, version, mode) => text.replace(`${mode} = "."`, `${mode} = ".", registry = "https://pypi.org/simple"`), /uv.lock.*source/],
+  ['unknown source field', (text, version, mode) => text.replace(`${mode} = "."`, `${mode} = ".", unexpected = true`), /uv.lock.*source/],
+  ['duplicate root', (text, version, mode) => `${text}\n${root(version, mode)}`, /uv.lock.*exactly one/],
+  ['opposite mode duplicate root', (text, version, mode) => `${text}\n${root(version, mode === 'editable' ? 'virtual' : 'editable')}`, /uv.lock.*exactly one/],
+  ['second differently named root', (text, version, mode) => `${text}\n${root(version, mode).replace('forex-service', 'foreign-service')}`, /uv.lock.*exactly one/],
+  ['empty version', (text, version) => text.replace(`version = "${version}"`, 'version = ""'), /uv.lock.*version/],
+]
+
+for (const mode of ['editable', 'virtual']) {
+  for (const stage of ['beforeLock', 'cutLock', 'targetLock']) {
+    test(`prepared reuse validates ${mode} uv root identity at ${stage}`, async (t) => {
+      for (const [label, change, error] of invalidRoots) {
+        await t.test(label, (t) => {
+          const version = stage === 'beforeLock' ? '0.4.0' : '0.7.0'
+          const f = fixture(t, {
+            beforeLock: lock('0.4.0', mode), cutLock: lock('0.7.0', mode),
+            [stage]: change(lock(version, mode), version, mode),
+          })
+          assert.throws(() => f.plan(), error)
+        })
+      }
+    })
+  }
+}
+
+test('historical uv comparison refuses source mode flips even though both root shapes are valid', async (t) => {
+  for (const [before, cut] of [['editable', 'virtual'], ['virtual', 'editable']]) {
+    await t.test(`${before} to ${cut}`, (t) => {
+      const f = fixture(t, { beforeLock: lock('0.4.0', before), cutLock: lock('0.7.0', cut) })
+      assert.throws(() => f.plan(), /metadata-only: uv.lock changes more than version identity/)
+      assert.equal(git(f.cwd, 'status', '--porcelain'), '')
+    })
+  }
+})
+
+test('prepared reuse refuses stale uv root or Python project versions at the frozen target', async (t) => {
+  for (const [label, options, error] of [
+    ['stale lock', { targetLock: lock('0.4.0') }, /uv.lock.*version.*does not match/],
+    ['stale project', { targetProject: project('0.6.2') }, /pyproject.toml version.*does not match/],
+    ['empty project name', { targetProject: project('0.7.0').replace('name = "forex-service"', 'name = ""') }, /project name is missing/],
+    ['foreign project', { targetProject: project('0.7.0').replace('forex-service', 'foreign-service') }, /uv.lock.*name/],
+    ['missing actual project version', { targetProject: `${project('0.7.0').replace('version = "0.7.0"\n', '')}\n[tool.poetry]\nversion = "0.7.0"\n` }, /project version must be static/],
+  ]) {
+    await t.test(label, (t) => {
+      const f = fixture(t, options)
+      assert.throws(() => f.plan(), error)
+    })
+  }
+})
+
+test('historical uv comparison excludes only the identified root version, never dependency data', async (t) => {
+  const changes = [
+    ['lock revision', (text) => text.replace('revision = 3', 'revision = 4')],
+    ['Python requirement', (text) => text.replace('>=3.11', '>=3.12')],
+    ['dependency version', (text) => text.replace('4.6.0', '4.7.0')],
+    ['dependency source', (text) => text.replace('https://pypi.org/simple', 'https://foreign.example/simple')],
+    ['sdist hash', (text) => text.replace('a'.repeat(64), 'c'.repeat(64))],
+    ['wheel size', (text) => text.replace('size = 23456', 'size = 23457')],
+    ['root dependency edge', (text) => text.replace('dependencies = [{ name = "anyio" }]', 'dependencies = []')],
+    ['root dependency requirement', (text) => text.replace('specifier = ">=4.6"', 'specifier = ">=4.7"')],
+    ['extra dependency', (text) => `${text}\n[[package]]\nname = "unsafe"\nversion = "9.0.0"\nsource = { registry = "https://pypi.org/simple" }\n`],
+  ]
+  for (const [label, change] of changes) {
+    await t.test(label, (t) => {
+      const f = fixture(t, { cutLock: change(lock('0.7.0')) })
+      assert.throws(() => f.plan(), /metadata-only: uv.lock changes more than version identity/)
+    })
+  }
+})
+
+test('historical Python metadata comparison still refuses non-version changes', async (t) => {
+  for (const [label, change] of [
+    ['project dependencies', (text) => text.replace('anyio>=4.6', 'anyio>=4.7')],
+    ['tool version', (text) => text.replace('not-the-project', 'changed-tool-version')],
+  ]) {
+    await t.test(label, (t) => {
+      const f = fixture(t, { cutProject: change(project('0.7.0')) })
+      assert.throws(() => f.plan(), /metadata-only: pyproject.toml changes more than version identity/)
+    })
+  }
+})
+
+test('prepared reuse allows reviewed dependency fixes after the historical metadata cut', (t) => {
+  const f = fixture(t, {
+    targetLock: lock('0.7.0').replace('4.6.0', '4.7.0').replace('specifier = ">=4.6"', 'specifier = ">=4.7"'),
+    targetProject: project('0.7.0').replace('anyio>=4.6', 'anyio>=4.7'),
+  })
+  assert.equal(f.plan().releaseSourceSha, f.sha)
+})
+
+test('TOML inspection accepts equivalent syntax and refuses invalid or unsupported lock data', async (t) => {
+  await t.test('single quotes, inline comments, and table syntax', (t) => {
+    const f = fixture(t, {
+      cutProject: project('0.7.0').replace('version = "0.7.0"', "version = '0.7.0' # prepared version"),
+      cutLock: lock('0.7.0').replace('source = { editable = "." }\n', '').replace('[package.metadata]', "[package.source]\neditable = '.'\n\n[package.metadata]"),
+    })
+    assert.equal(f.plan().nextVersion, '0.7.0')
+  })
+  for (const [label, cutLock, error] of [
+    ['duplicate TOML key', `${lock('0.7.0')}\nrequires-dist = []\n`, /uv.lock TOML inspection failed/],
+    ['unsupported format', lock('0.7.0').replace('version = 1', 'version = 2'), /uv.lock.*unsupported lock format/],
+    ['missing packages', 'version = 1\npackage = []\n', /uv.lock.*exactly one/],
+    ['unsafe integer', lock('0.7.0').replace('size = 12345', 'size = 9007199254740992'), /uv.lock TOML inspection failed/],
+    ['nonfinite TOML number', lock('0.7.0').replace('size = 12345', 'size = inf'), /uv.lock TOML inspection failed/],
+  ]) {
+    await t.test(label, (t) => {
+      const f = fixture(t, { cutLock })
+      assert.throws(() => f.plan(), error)
+    })
+  }
+})
+
+test('Python parser unavailability fails closed through the public CLI without a plan or receipt reset', (t) => {
+  const f = fixture(t)
+  const bin = join(f.cwd, '.git', 'only-git')
+  mkdirSync(bin)
+  symlinkSync(spawnSync('which', ['git'], { encoding: 'utf8' }).stdout.trim(), join(bin, 'git'))
+  const receipt = join(f.cwd, '.git', 'resolve-release-authorization.json')
+  writeFileSync(receipt, 'historical authority')
+  const input = join(f.cwd, '.git', 'prepared.json')
+  writeFileSync(input, JSON.stringify(f.preparedMetadata))
+  const result = spawnSync(process.execPath, [join(import.meta.dirname, 'plan.mjs'), '--sha', f.sha,
+    '--prepared-metadata', input, '--json'], { cwd: f.cwd, encoding: 'utf8', env: { ...process.env, PATH: bin } })
+  assert.equal(result.status, 1)
+  assert.equal(result.stdout, '')
+  assert.match(result.stderr, /Python 3.11\+ with tomllib/)
+  assert.equal(readFileSync(receipt, 'utf8'), 'historical authority')
+})
+
+test('external TOML parser errors, invalid output, output overflow and timeout all fail closed', async (t) => {
+  for (const [label, parser, error] of [
+    ['process failure', 'process.exit(1)', /TOML inspection failed/],
+    ['invalid JSON', "process.stdout.write('{')", /parser returned invalid JSON/],
+    ['output overflow', "process.stdout.write('x'.repeat(9 * 1024 * 1024))", /TOML inspection failed/],
+    ['timeout', 'setTimeout(() => process.exit(0), 30_000)', /TOML inspection failed/],
+  ]) {
+    await t.test(label, (t) => {
+      const f = fixture(t)
+      const bin = join(f.cwd, '.git', 'parser-bin')
+      mkdirSync(bin)
+      // Substitute only the external Python boundary; git objects and planner stay real.
+      writeFileSync(join(bin, 'python3'), `#!${process.execPath}\nprocess.stdin.resume()\n${parser}\n`, { mode: 0o755 })
+      const input = join(f.cwd, '.git', 'prepared.json')
+      writeFileSync(input, JSON.stringify(f.preparedMetadata))
+      const result = spawnSync(process.execPath, [join(import.meta.dirname, 'plan.mjs'), '--sha', f.sha,
+        '--prepared-metadata', input, '--json'], { cwd: f.cwd, encoding: 'utf8',
+        env: { ...process.env, PATH: `${bin}:${process.env.PATH}` }, timeout: 15_000 })
+      assert.equal(result.status, 1)
+      assert.equal(result.stdout, '')
+      assert.match(result.stderr, error)
+      assert.equal(git(f.cwd, 'status', '--porcelain'), '')
+    })
+  }
+})
+
+test('normal Python planning remains unchanged and does not acquire uv identity write permissions', (t) => {
+  const f = fixture(t)
+  const plan = f.plan({ preparedMetadata: null, cloudRun: false })
+  assert.deepEqual(plan.versionFiles, ['pyproject.toml'])
+  assert.equal(plan.currentVersion, '0.7.0')
+  assert.equal(plan.bump, 'patch')
+  assert.equal(plan.nextVersion, '0.7.1')
+})