@dsh-enhanced/plugin-control-plane 0.1.48 → 0.1.53

package/bin/dsh-local-release-adapter.js

@@ -25,6 +25,7 @@ import {
   existsSync,
   fsyncSync,
   lstatSync,
+  mkdtempSync,
   mkdirSync,
   openSync,
   readFileSync,
@@ -33,6 +34,7 @@ import {
   readdirSync,
   readSync,
   renameSync,
+  rmdirSync,
   rmSync,
   fstatSync,
   statSync,
@@ -43,6 +45,7 @@ import {
 } from 'node:fs'
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
+import { gunzipSync, gzipSync } from 'node:zlib'
 
 export const LOCAL_RELEASE_ADAPTER_VERSION = 'dsh-local-release-adapter-1'
 const PHASES = new Set(['pr', 'review', 'merge', 'build', 'sign', 'publish', 'registry-verify', 'catalog-admission'])
@@ -411,7 +414,8 @@ function catalogConfig(value, npm = false) {
 }
 function buildConfig(value) {
   const item = object(value, 'build config')
-  exactKeys(item, ['sandboxExecutable', 'tarExecutable', 'nodeExecutable', 'pnpmExecutable', 'pnpmRoot', 'storeRoot'], 'build config')
+  const expected = ['sandboxExecutable', 'tarExecutable', 'nodeExecutable', 'pnpmExecutable', 'pnpmRoot', 'storeRoot']
+  exactKeys(item, item.cacheRoot === undefined ? expected : [...expected, 'cacheRoot'], 'build config')
   const sandboxExecutable = inspectExecutable(item.sandboxExecutable, 'build sandbox')
   const tarExecutable = inspectExecutable(item.tarExecutable, 'tar')
   if (sandboxExecutable.path !== '/usr/bin/bwrap') fail('local build adapter requires the pinned Linux bubblewrap sandbox')
@@ -419,6 +423,7 @@ function buildConfig(value) {
   const pnpmExecutable = inspectExecutable(item.pnpmExecutable, 'pnpm executable')
   const pnpmRoot = pinnedDirectory(item.pnpmRoot, 'pnpm root')
   const storeRoot = pinnedDirectory(item.storeRoot, 'pnpm store')
+  const cacheRoot = item.cacheRoot === undefined ? undefined : pinnedDirectory(item.cacheRoot, 'pnpm cache')
   if (nodeExecutable.path !== join(pnpmRoot.path, 'node')) fail('Node executable must be the pinned pnpm root node entrypoint')
   if (pnpmExecutable.path !== join(pnpmRoot.path, 'pnpm')) fail('pnpm executable must be the pinned pnpm root entrypoint')
   let pnpmManifest
@@ -428,14 +433,40 @@ function buildConfig(value) {
   const storeVersion = Number.parseInt(pnpmVersion.split('.')[0], 10)
   const projectsPath = join(storeRoot.path, `v${storeVersion}`, 'projects')
   if (!existsSync(projectsPath) || !lstatSync(projectsPath).isDirectory()) fail('pnpm store project registry is unavailable')
-  return { sandboxExecutable, tarExecutable, nodeExecutable, pnpmExecutable, pnpmRoot, storeRoot, storeVersion }
+  return { sandboxExecutable, tarExecutable, nodeExecutable, pnpmExecutable, pnpmRoot, storeRoot, cacheRoot, storeVersion }
 }
 function verifyBuildPins(build) {
-  for (const [item, label] of [[build.pnpmRoot, 'pnpm root'], [build.storeRoot, 'pnpm store']]) {
+  const pinned = [[build.pnpmRoot, 'pnpm root'], [build.storeRoot, 'pnpm store']]
+  if (build.cacheRoot !== undefined) pinned.push([build.cacheRoot, 'pnpm cache'])
+  for (const [item, label] of pinned) {
     if (directoryInventory(item.path, label).sha256 !== item.sha256) fail(`${label} changed after configuration validation`)
   }
 }
 
+export function inspectLocalReleaseBuildEnvironment(value) {
+  const input = object(value, 'local release build environment')
+  exactKeys(input, input.cacheRoot === undefined ? ['pnpmRoot', 'storeRoot'] : ['pnpmRoot', 'storeRoot', 'cacheRoot'],
+    'local release build environment')
+  const executable = (path, label) => {
+    const pin = { path, sha256: sha256Bytes(stableBytes(path, label)) }
+    return inspectExecutable(pin, label)
+  }
+  const pnpmRoot = directoryInventory(input.pnpmRoot, 'pnpm root')
+  const storeRoot = directoryInventory(input.storeRoot, 'pnpm store')
+  const cacheRoot = input.cacheRoot === undefined ? undefined : directoryInventory(input.cacheRoot, 'pnpm cache')
+  const pins = {
+    sandboxExecutable: executable('/usr/bin/bwrap', 'build sandbox'),
+    tarExecutable: executable('/usr/bin/tar', 'tar'),
+    nodeExecutable: executable(join(pnpmRoot.path, 'node'), 'build Node executable'),
+    pnpmExecutable: executable(join(pnpmRoot.path, 'pnpm'), 'pnpm executable'),
+    pnpmRoot: { path: pnpmRoot.path, sha256: pnpmRoot.sha256 },
+    storeRoot: { path: storeRoot.path, sha256: storeRoot.sha256 },
+    ...(cacheRoot === undefined ? {} : { cacheRoot: { path: cacheRoot.path, sha256: cacheRoot.sha256 } }),
+  }
+  buildConfig(pins)
+  return pins
+}
+
 function command(executable, args, cwd, extraEnvironment = {}, input, inherited = [], hooks = {}) {
   if (process.platform !== 'linux' || !existsSync('/proc/self/fd')) fail('descriptor-pinned commands require Linux /proc/self/fd')
   const pinned = openPinnedFile(executable, `pinned ${basename(executable.path)} executable`, MAX_ARTIFACT_BYTES, true)
@@ -488,14 +519,17 @@ function openSandboxContext(build, workspace, output, runRoot) {
   const storeProjects = join(runRoot, 'store-projects')
   if (!existsSync(storeProjects)) mkdirSync(storeProjects, { mode: 0o700 })
   const toolchainSnapshot = join(runRoot, 'toolchain-snapshot'); const storeSnapshot = join(runRoot, 'store-snapshot')
+  const cacheSnapshot = build.cacheRoot === undefined ? undefined : join(runRoot, 'cache-snapshot')
   if (!existsSync(toolchainSnapshot)) copyPinnedTree(build.pnpmRoot, toolchainSnapshot, 'pnpm root')
   if (!existsSync(storeSnapshot)) copyPinnedTree(build.storeRoot, storeSnapshot, 'pnpm store')
+  if (cacheSnapshot !== undefined && !existsSync(cacheSnapshot)) copyPinnedTree(build.cacheRoot, cacheSnapshot, 'pnpm cache')
   const pnpmRoot = openPinnedDirectory({ path: toolchainSnapshot, sha256: build.pnpmRoot.sha256 }, 'pnpm snapshot')
   const storeRoot = openPinnedDirectory({ path: storeSnapshot, sha256: build.storeRoot.sha256 }, 'pnpm store snapshot')
   const workspaceRoot = openPinnedDirectory({ path: workspace }, 'build workspace')
   const outputRoot = openPinnedDirectory({ path: output }, 'build output')
   const storeProjectsRoot = openPinnedDirectory({ path: storeProjects }, 'pnpm project registry')
   const mounts = [pnpmRoot, storeRoot, workspaceRoot, outputRoot, storeProjectsRoot]
+  if (cacheSnapshot !== undefined) mounts.push(openPinnedDirectory({ path: cacheSnapshot, sha256: build.cacheRoot.sha256 }, 'pnpm cache snapshot'))
   return { mounts, runRoot }
 }
 function closeSandboxContext(context) { for (const item of context.mounts) closePinnedDirectory(item) }
@@ -504,16 +538,95 @@ function sandboxCommand(build, args, context, hooks = {}) {
   for (const item of mounts) verifyPinnedDirectory(item)
   const mountFd = index => String(3 + index)
   const sandboxArgs = ['--unshare-all', '--die-with-parent', '--new-session', '--clearenv',
-    '--ro-bind', '/usr', '/usr', '--ro-bind', '/lib', '/lib', '--ro-bind', '/lib64', '/lib64',
+    '--ro-bind', '/usr', '/usr', '--ro-bind', '/lib', '/lib',
+    // Debian arm64 keeps its loader under /lib; /lib64 is an x86_64 path.
+    ...(process.arch === 'arm64' ? [] : ['--ro-bind', '/lib64', '/lib64']),
+    '--symlink', 'usr/bin', '/bin',
     '--ro-bind-fd', mountFd(0), '/toolchain', '--ro-bind-fd', mountFd(1), '/store',
+    ...(build.cacheRoot === undefined ? [] : ['--ro-bind-fd', mountFd(5), '/cache']),
     '--bind-fd', mountFd(4), `/store/v${build.storeVersion}/projects`, '--proc', '/proc', '--dev', '/dev', '--tmpfs', '/tmp', '--dir', '/home',
     '--bind-fd', mountFd(2), '/workspace', '--bind-fd', mountFd(3), '/output',
     '--chdir', '/workspace', '--setenv', 'HOME', '/home', '--setenv', 'TMPDIR', '/tmp', '--setenv', 'SOURCE_DATE_EPOCH', '0',
-    '--setenv', 'PATH', '/toolchain:/usr/bin:/bin', '/toolchain/pnpm', ...args]
+    '--setenv', 'PATH', '/toolchain:/usr/bin:/bin',
+    ...(build.cacheRoot === undefined ? [] : ['--setenv', 'pnpm_config_cache_dir', '/cache']),
+    '/toolchain/pnpm', ...args]
   command(build.sandboxExecutable, sandboxArgs, runRoot, {}, undefined, mounts.map(item => item.descriptor),
     { beforeSpawn: hooks.beforeSandboxSpawn, afterSpawn: hooks.afterSandboxSpawn, afterFinally: hooks.afterSandboxFinally })
   for (const item of mounts) verifyPinnedDirectory(item)
 }
+
+/** Build one frozen local cohort with the release adapter's pinned, offline
+ * sandbox. The caller supplies private staging directories, never a live Home.
+ * All candidate code sees is a copy without Git metadata or installed modules. */
+export function buildLocalUpdateCohort(value) {
+  const input = object(value, 'local update cohort')
+  exactKeys(input, ['build', 'workspace', 'output', 'packagePaths'], 'local update cohort')
+  const build = buildConfig(input.build)
+  const workspace = canonicalPath(input.workspace, 'local update workspace')
+  const output = canonicalPath(input.output, 'local update output')
+  if (workspace === output || dirname(workspace) !== dirname(output)) fail('local update workspace and output must be private siblings')
+  privateDirectory(dirname(workspace), 'local update staging parent')
+  privateDirectory(workspace, 'local update workspace')
+  privateDirectory(output, 'local update output')
+  if (readdirSync(output).length !== 0) fail('local update output must be empty')
+  const outputIdentity = statSync(output, { bigint: true })
+  if (!Array.isArray(input.packagePaths) || input.packagePaths.length < 1 || input.packagePaths.length > 128) {
+    fail('local update package paths exceed their bound')
+  }
+  const paths = input.packagePaths.map(path => text(path, 'local update package path', /^(?:plugins|packages)\/[a-z0-9][a-z0-9-]{0,63}$/u))
+  const slugs = paths.map(path => basename(path))
+  if (new Set(paths).size !== paths.length || new Set(slugs).size !== slugs.length) fail('local update package paths are ambiguous')
+  verifyBuildPins(build)
+  const runRoot = mkdtempSync(join(dirname(workspace), '.local-cohort-build-'))
+  try {
+    chmodSync(runRoot, 0o700)
+    const isolatedWorkspace = join(runRoot, 'workspace')
+    copyBuildWorkspace(workspace, isolatedWorkspace)
+    normalizeBuildBinModes(isolatedWorkspace)
+    const sourceInputs = snapshotBuildInputs(isolatedWorkspace)
+    for (const path of paths) {
+      const packageRoot = join(isolatedWorkspace, path)
+      if (!existsSync(packageRoot) || !lstatSync(packageRoot).isDirectory()
+        || realpathSync(packageRoot) !== resolve(packageRoot)) fail(`local update package is unavailable: ${path}`)
+    }
+    const packed = join(runRoot, 'packed'); mkdirSync(packed, { mode: 0o700 })
+    for (const slug of slugs) mkdirSync(join(packed, slug), { mode: 0o700 })
+    const sandbox = openSandboxContext(build, isolatedWorkspace, packed, runRoot)
+    try {
+      sandboxCommand(build, ['install', '--offline', '--frozen-lockfile', '--frozen-store', '--ignore-scripts',
+        '--package-import-method=copy', '--store-dir=/store'], sandbox)
+      sandboxCommand(build, ['--workspace-root', '--if-present', 'run', 'build'], sandbox)
+      for (const [index, path] of paths.entries()) {
+        const packageRoot = join(isolatedWorkspace, path)
+        if (!lstatSync(packageRoot).isDirectory() || realpathSync(packageRoot) !== resolve(packageRoot)) {
+          fail(`local update package changed before pack: ${path}`)
+        }
+        sandboxCommand(build, ['--dir', `/workspace/${path}`, 'pack', '--pack-destination', `/output/${slugs[index]}`], sandbox)
+      }
+    } finally { closeSandboxContext(sandbox) }
+    verifyBuildInputs(isolatedWorkspace, sourceInputs)
+    verifyBuildPins(build)
+    if (readdirSync(packed).sort().join('\0') !== [...slugs].sort().join('\0')) fail('local update pack output has unexpected directories')
+    let totalBytes = 0
+    for (const slug of slugs) {
+      const directory = join(packed, slug)
+      privateDirectory(directory, `local update ${slug} output`)
+      const names = readdirSync(directory)
+      if (names.length !== 1 || !names[0].endsWith('.tgz')) fail(`local update pack output is ambiguous: ${slug}`)
+      const tarball = safeRegularFile(join(directory, names[0]), `local update ${slug} tarball`)
+      totalBytes += lstatSync(tarball).size
+      if (totalBytes > 2_147_483_648) fail('local update cohort output exceeds its bound')
+    }
+    // Output is a private, empty preparation directory; make the complete
+    // validated set visible in one rename, or leave it absent on failure.
+    const currentOutput = lstatSync(output, { bigint: true })
+    if (!currentOutput.isDirectory() || currentOutput.dev !== outputIdentity.dev
+      || currentOutput.ino !== outputIdentity.ino || readdirSync(output).length !== 0) fail('local update output changed during build')
+    rmdirSync(output)
+    renameSync(packed, output)
+    fsyncDirectory(dirname(output))
+  } finally { rmSync(runRoot, { recursive: true, force: true }) }
+}
 function git(gitValue, args, cwd, environment = {}, hooks = {}) {
   return command(gitValue.executable, [...SAFE_GIT_CONFIG, ...args], cwd,
     { GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', ...environment }, undefined, [],
@@ -964,6 +1077,92 @@ function copyBuildWorkspace(source, destination) {
   }
   inspect(destination)
 }
+function normalizeBuildBinModes(root) {
+  for (const collection of ['plugins', 'packages']) {
+    const collectionRoot = join(root, collection)
+    if (!existsSync(collectionRoot)) continue
+    for (const name of readdirSync(collectionRoot)) {
+      const packageRoot = join(collectionRoot, name)
+      if (!lstatSync(packageRoot).isDirectory()) continue
+      const manifestPath = join(packageRoot, 'package.json')
+      if (!existsSync(manifestPath)) continue
+      const manifestFile = lstatSync(manifestPath)
+      if (!manifestFile.isFile() || manifestFile.size > MAX_INPUT_BYTES) fail('local update package manifest is unsafe')
+      let manifest
+      try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) }
+      catch { fail('local update package manifest is invalid') }
+      if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) fail('local update package manifest is invalid')
+      const bin = manifest.bin
+      if (bin === undefined) continue
+      const binPaths = typeof bin === 'string' ? [bin]
+        : bin !== null && typeof bin === 'object' && !Array.isArray(bin) ? Object.values(bin) : null
+      if (binPaths === null) fail('local update package bin is invalid')
+      for (const binPath of binPaths) {
+        if (typeof binPath !== 'string' || binPath.length === 0 || binPath.length > 2_000
+          || binPath.includes('\0') || binPath.includes('\\') || isAbsolute(binPath)
+          || binPath.split('/').includes('..')) fail('local update bin path is invalid')
+        const path = resolve(packageRoot, binPath)
+        const inside = relative(packageRoot, path)
+        if (!inside || inside === '..' || inside.startsWith(`..${sep}`) || isAbsolute(inside)) fail('local update bin path escapes its package')
+        const parts = inside.split(sep)
+        let current = packageRoot
+        let missing = false
+        for (const [index, part] of parts.entries()) {
+          current = join(current, part)
+          let metadata
+          try { metadata = lstatSync(current) }
+          catch (error) {
+            if (error.code !== 'ENOENT') throw error
+            missing = true
+            break
+          }
+          if (metadata.isSymbolicLink() || (index === parts.length - 1 ? !metadata.isFile() : !metadata.isDirectory())) {
+            fail('local update bin path is unsafe')
+          }
+        }
+        if (missing) continue
+        if (realpathSync(path) !== path) fail('local update bin path is unsafe')
+        chmodSync(path, 0o755)
+      }
+    }
+  }
+}
+function snapshotBuildInputs(root) {
+  const directories = [], files = []
+  let entries = 0, bytes = 0
+  const visit = (path, relativePath = '') => {
+    const metadata = lstatSync(path)
+    if (++entries > 100_000) fail('local update source has too many entries')
+    if (metadata.isDirectory() && !metadata.isSymbolicLink()) {
+      directories.push({ path: relativePath, mode: metadata.mode & 0o777 })
+      for (const name of readdirSync(path).sort()) visit(join(path, name), relativePath ? `${relativePath}/${name}` : name)
+    } else if (metadata.isFile() && !metadata.isSymbolicLink()) {
+      bytes += metadata.size
+      if (metadata.size > MAX_ARTIFACT_BYTES || bytes > 4_294_967_296) fail('local update source exceeds its size bound')
+      files.push({ path: relativePath, mode: metadata.mode & 0o777, size: metadata.size,
+        sha256: sha256Bytes(readFileSync(path)) })
+    } else fail('local update source contains an unsupported entry')
+  }
+  visit(root)
+  return { directories, files }
+}
+function verifyBuildInputs(root, before) {
+  for (const item of before.directories) {
+    const path = item.path ? join(root, item.path) : root
+    const metadata = lstatSync(path)
+    if (!metadata.isDirectory() || metadata.isSymbolicLink() || (metadata.mode & 0o777) !== item.mode) {
+      fail(`local update source directory changed during build: ${item.path}`)
+    }
+  }
+  for (const item of before.files) {
+    const metadata = lstatSync(join(root, item.path))
+    if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size !== item.size
+      || (metadata.mode & 0o777) !== item.mode
+      || sha256Bytes(readFileSync(join(root, item.path))) !== item.sha256) {
+      fail(`local update source file changed during build: ${item.path}`)
+    }
+  }
+}
 function fileInventory(root) {
   const result = []
   const visit = (directory, prefix = '') => {
@@ -976,6 +1175,92 @@ function fileInventory(root) {
   }
   visit(root); return result
 }
+const TAR_BLOCK_BYTES = 512
+const DEPENDENCY_MAPS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']
+function tarOctal(header, start, length, label) {
+  const field = header.subarray(start, start + length)
+  if (field.some(byte => byte !== 0 && byte !== 32 && (byte < 48 || byte > 55))) {
+    fail(`${label} uses unsupported binary or non-octal tar encoding`)
+  }
+  const octal = field.toString('ascii').replaceAll('\0', ' ').trim()
+  if (!/^[0-7]+$/u.test(octal)) fail(`${label} is not an octal tar field`)
+  const value = Number.parseInt(octal, 8)
+  if (!Number.isSafeInteger(value)) fail(`${label} exceeds the safe tar size`)
+  return value
+}
+function tarString(header, start, length) {
+  const field = header.subarray(start, start + length)
+  const terminator = field.indexOf(0)
+  if (terminator !== -1 && field.subarray(terminator).some(byte => byte !== 0)) fail('tar pathname field has nonzero padding')
+  return field.subarray(0, terminator === -1 ? field.length : terminator).toString('utf8')
+}
+
+export function normalizePackedDependencyOrder(packed) {
+  if (!Buffer.isBuffer(packed) || packed.length < 1 || packed.length > MAX_ARTIFACT_BYTES) fail('packed archive size is invalid')
+  let archive
+  try { archive = gunzipSync(packed, { maxOutputLength: MAX_ARTIFACT_BYTES }) }
+  catch { fail('packed archive is invalid or exceeds the extraction limit') }
+  if (archive.length < TAR_BLOCK_BYTES * 3 || archive.length % TAR_BLOCK_BYTES !== 0) fail('packed tar block layout is invalid')
+  let manifestOffset; let manifestSize; let offset = 0; let terminated = false
+  while (offset < archive.length) {
+    const header = archive.subarray(offset, offset + TAR_BLOCK_BYTES)
+    if (header.every(byte => byte === 0)) {
+      if (archive.length - offset < TAR_BLOCK_BYTES * 2 || archive.subarray(offset).some(byte => byte !== 0)) {
+        fail('packed tar terminator is invalid')
+      }
+      terminated = true; break
+    }
+    const expectedChecksum = tarOctal(header, 148, 8, 'tar header checksum')
+    let checksum = 0
+    for (let index = 0; index < TAR_BLOCK_BYTES; index += 1) checksum += index >= 148 && index < 156 ? 32 : header[index]
+    if (checksum !== expectedChecksum) fail('packed tar header checksum is invalid')
+    const size = tarOctal(header, 124, 12, 'tar entry size')
+    const type = header[156]
+    if (type !== 0 && type !== 48 && type !== 53) fail('packed tar uses an unsupported entry representation')
+    if (type === 53 && size !== 0) fail('packed tar directory has a payload')
+    const name = tarString(header, 0, 100); const prefix = tarString(header, 345, 155)
+    const entryPath = prefix === '' ? name : `${prefix}/${name}`
+    const logicalPath = type === 53 && entryPath.endsWith('/') ? entryPath.slice(0, -1) : entryPath
+    if ((logicalPath !== 'package' && !logicalPath.startsWith('package/'))
+      || logicalPath.includes('//') || logicalPath.split('/').some(part => part === '' || part === '.' || part === '..')) {
+      fail('packed tar entry path is not canonical')
+    }
+    const dataOffset = offset + TAR_BLOCK_BYTES
+    const nextOffset = dataOffset + Math.ceil(size / TAR_BLOCK_BYTES) * TAR_BLOCK_BYTES
+    if (nextOffset > archive.length) fail('packed tar entry is truncated')
+    if (entryPath === 'package/package.json') {
+      if (manifestOffset !== undefined || prefix !== '' || (type !== 0 && type !== 48)) {
+        fail('packed manifest has a duplicate or unsupported representation')
+      }
+      manifestOffset = dataOffset; manifestSize = size
+    }
+    offset = nextOffset
+  }
+  if (!terminated || manifestOffset === undefined || manifestSize === undefined) fail('packed tar has no regular package manifest')
+  const sourceBytes = archive.subarray(manifestOffset, manifestOffset + manifestSize)
+  const source = sourceBytes.toString('utf8')
+  if (!Buffer.from(source, 'utf8').equals(sourceBytes)) fail('packed manifest is not valid UTF-8')
+  let manifest
+  try { manifest = JSON.parse(source) } catch { fail('packed manifest is not valid JSON') }
+  if (typeof manifest !== 'object' || manifest === null || Array.isArray(manifest)) fail('packed manifest must be an object')
+  const lineEnding = source.endsWith('\n') ? '\n' : ''
+  if (`${JSON.stringify(manifest, null, 2)}${lineEnding}` !== source) fail('packed manifest is not in the supported canonical JSON format')
+  const normalized = { ...manifest }
+  for (const name of DEPENDENCY_MAPS) {
+    if (!Object.hasOwn(manifest, name)) continue
+    const entries = manifest[name]
+    if (typeof entries !== 'object' || entries === null || Array.isArray(entries)
+      || Object.values(entries).some(value => typeof value !== 'string')) fail(`packed manifest ${name} is invalid`)
+    normalized[name] = Object.fromEntries(Object.entries(entries).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0))
+  }
+  const normalizedBytes = Buffer.from(`${JSON.stringify(normalized, null, 2)}${lineEnding}`)
+  if (normalizedBytes.length !== manifestSize) fail('packed manifest normalization changed its tar entry size')
+  const normalizedArchive = Buffer.from(archive)
+  normalizedBytes.copy(normalizedArchive, manifestOffset)
+  const result = gzipSync(normalizedArchive, { mtime: 0 })
+  if (result.length > MAX_ARTIFACT_BYTES) fail('normalized packed archive exceeds the artifact limit')
+  return result
+}
 function prepareBuildSource(request, context, gitValue, hooks) {
   const bundle = join(context.directory, 'source.bundle'); rmSync(bundle, { force: true })
   const temporaryRef = `refs/dsh-release/build/${sha256Bytes(request.operationId).slice(0, 32)}`
@@ -1012,15 +1297,18 @@ function runIsolatedBuild(request, context, runNumber, gitValue, build, packageP
   try {
     sandboxCommand(build, ['install', '--offline', '--frozen-lockfile', '--frozen-store', '--ignore-scripts',
       '--package-import-method=copy', '--store-dir=/store'], sandbox, hooks)
+    sandboxCommand(build, ['--workspace-root', '--if-present', 'run', 'build'], sandbox, hooks)
     sandboxCommand(build, ['--dir', `/workspace/${packagePath}`, 'run', 'build'], sandbox, hooks)
     sandboxCommand(build, ['--dir', `/workspace/${packagePath}`, 'pack', '--pack-destination', '/output'], sandbox, hooks)
   } finally { closeSandboxContext(sandbox) }
   const packed = readdirSync(output).filter(name => name.endsWith('.tgz'))
   if (packed.length !== 1 || readdirSync(output).length !== 1) fail('pnpm pack must produce exactly one tarball')
   const tarball = safeRegularFile(join(output, packed[0]), `isolated build ${runNumber} tarball`)
-  const bytes = readBounded(tarball, `isolated build ${runNumber} tarball`)
-  const unpacked = unpackPackage(build, tarball, join(runRoot, 'packed'), runRoot, hooks)
-  return { runRoot, checkout, workspace, packageRoot: unpacked.packageRoot, inventory: unpacked.inventory, tarball, bytes, sha256: sha256Bytes(bytes) }
+  const bytes = normalizePackedDependencyOrder(readBounded(tarball, `isolated build ${runNumber} tarball`))
+  const normalizedTarball = join(runRoot, 'normalized-package.tgz'); writeSynced(normalizedTarball, bytes, 0o600)
+  const unpacked = unpackPackage(build, normalizedTarball, join(runRoot, 'packed'), runRoot, hooks)
+  return { runRoot, checkout, workspace, packageRoot: unpacked.packageRoot, inventory: unpacked.inventory,
+    tarball: normalizedTarball, bytes, sha256: sha256Bytes(bytes) }
 }
 function temporaryBuildRef(request) { return `refs/dsh-release/build/${sha256Bytes(request.operationId).slice(0, 32)}` }
 function buildPhase(request, config, context, hooks) {
@@ -1069,7 +1357,8 @@ function buildPhase(request, config, context, hooks) {
   const sbomPath = join(outputs, 'sbom.cdx.json'); immutableCopy(sbomPath, Buffer.from(`${canonicalReleaseValue(sbom)}\n`), 0o600)
   const provenance = { _type: 'https://in-toto.io/Statement/v1', subject: [{ name: packageName, digest: { sha256: tarballSha256 } }],
     predicateType: 'https://slsa.dev/provenance/v1', predicate: { buildDefinition: { buildType: 'https://dsh-enhanced.dev/build/local-isolated/v1',
-      externalParameters: { packagePath, packageVersion }, resolvedDependencies: [{ uri: pathToFileURL(gitValue.remote).href, digest: { gitCommit: mergeCommit } }] },
+      externalParameters: { packagePath, packageVersion, manifestNormalization: 'sort-direct-dependency-maps-v1' },
+      resolvedDependencies: [{ uri: pathToFileURL(gitValue.remote).href, digest: { gitCommit: mergeCommit } }] },
     runDetails: { builder: { id: `dsh-local-release-adapter:${config.authority}:${config.keyId}` }, metadata: { invocationId: request.operationId },
       byproducts: [{ name: 'sbom', digest: { sha256: sha256Bytes(readFileSync(sbomPath)) } }] } } }
   const provenancePath = join(outputs, 'provenance.intoto.jsonl'); immutableCopy(provenancePath, Buffer.from(`${canonicalReleaseValue(provenance)}\n`), 0o600)
@@ -1384,6 +1673,39 @@ function persistReviewReceipt(receipt, config) {
   } else immutableJson(path, receipt, 0o600)
 }
 
+/** Read-only installation preflight. No request, receipt, lock, subprocess or
+ * release phase is created; return public identity only, never loaded keys. */
+export function inspectLocalReleaseAdapterConfiguration(environment, phase) {
+  if (!PHASES.has(phase)) fail('adapter inspection phase is invalid')
+  const config = loadConfig(environment, phase)
+  if (config.phase !== phase) fail('adapter config differs from inspection phase')
+  const publicKey = createPublicKey(config.privateKey)
+  if (config.authorizationAuthority.publicKey.equals(publicKey)
+    || (config.authorizationAuthority.authority === config.authority && config.authorizationAuthority.keyId === config.keyId)) {
+    fail('release authorization and adapter identities must be independent')
+  }
+  if (['pr', 'review', 'merge', 'build'].includes(phase)) {
+    const git = gitConfig(config.git)
+    if (phase === 'review' && (!git.reviewStore || !git.reviewDecisionRoot)) fail('review requires independent decision and receipt stores')
+    if (phase === 'merge' && (!git.reviewStore || !git.reviewAuthority || git.reviewAuthority.publicKey.equals(publicKey))) {
+      fail('merge requires an independent review identity and receipt store')
+    }
+  }
+  if (phase === 'build') buildConfig(config.build)
+  if (['publish', 'registry-verify', 'catalog-admission'].includes(phase)) {
+    const registry = registryConfig(config.registry)
+    if (!registry.signer) fail('registry requires an artifact signer')
+    if (phase === 'registry-verify' && !registry.downloadRoot) fail('registry verification requires a separate download root')
+    if (registry.signer.publicKey.equals(publicKey)) fail('registry phase and artifact signer must be independent')
+  }
+  if (phase === 'catalog-admission') {
+    const catalog = catalogConfig(config.catalog)
+    const helper = openPinnedFile(catalog.helper, 'catalog helper', 1_048_576, false)
+    try { privateFile(catalog.path, 'catalog file') } finally { closePinnedFile(helper) }
+  }
+  return { id: config.id, phase, executablePath: config.executablePath, authority: config.authority, keyId: config.keyId }
+}
+
 export async function runLocalReleaseAdapter(argv = process.argv.slice(2), environment = process.env, hooks = {}) {
   if (argv.length === 1 && argv[0] === '--version') { process.stdout.write(`${LOCAL_RELEASE_ADAPTER_VERSION}\n`); return }
   if (argv.length === 1 && argv[0] === '--capabilities') {