@mnstry/atelier 0.2.0-alpha.1 → 0.2.0-alpha.11

package/src/project/config.mjs

@@ -1,6 +1,8 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
+import { sanitizedGitEnvironment } from '../runtime/git-adapter.mjs'
+import { parseProjectOptions } from '../cli/project-options.mjs'
 
 export const PROJECT_CONFIG_ARG_PREFIX = '--project-config='
 export const PROJECT_CONFIG_ENV = 'MNSTRY_ATELIER_PROJECT_CONFIG'
@@ -17,6 +19,16 @@ export const LOCAL_OVERLAY_FILES = ['atelier.local.json', 'atelier.workspace.loc
 // a way to silence checks on a repo you do manage.
 export const EXTERNAL_REPO_KIND = 'external'
 
+export class AtelierDiagnosticError extends Error {
+  constructor(code, message, { hint = null, exitCode = 2, cause = null } = {}) {
+    super(message, cause ? { cause } : undefined)
+    this.name = 'AtelierDiagnosticError'
+    this.code = code
+    this.hint = hint
+    this.exitCode = exitCode
+  }
+}
+
 export const isExternalRepo = (repo) => firstString(repo?.kind) === EXTERNAL_REPO_KIND
 
 // Kept here rather than imported from repo-identity.mjs so config validation stays
@@ -59,10 +71,19 @@ export function resolvePathValue(value, baseDir) {
 }
 
 export function readJson(file) {
+  if (!fs.existsSync(file)) {
+    const graphArtifact = path.basename(file) === 'knowledge.graph.json'
+    throw new AtelierDiagnosticError('artifact-missing', `required JSON artifact not found: ${file}`, {
+      hint: graphArtifact ? 'Run atelier graph with this project config, then retry.' : 'Create or regenerate the named artifact, then retry.',
+    })
+  }
   try {
     return JSON.parse(fs.readFileSync(file, 'utf8'))
   } catch (error) {
-    throw new Error(`invalid JSON at ${file}: ${error.message}`)
+    throw new AtelierDiagnosticError('json-invalid', `JSON is malformed at ${file}: ${error.message}`, {
+      hint: 'Repair or regenerate the named JSON file, then retry.',
+      cause: error,
+    })
   }
 }
 
@@ -75,14 +96,7 @@ export function writeJson(file, value) {
 }
 
 export function projectConfigArg(argv = process.argv.slice(2), prefix = PROJECT_CONFIG_ARG_PREFIX) {
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index]
-    if (typeof arg !== 'string') continue
-    if (arg.startsWith(prefix)) return arg.slice(prefix.length).trim() || null
-    if ((arg === '--project-config' || arg === '--project') && argv[index + 1]) return String(argv[index + 1]).trim() || null
-    if (arg.startsWith('--project=')) return arg.slice('--project='.length).trim() || null
-  }
-  return null
+  return parseProjectOptions(argv, prefix).project
 }
 
 export function stripProjectConfigArgs(argv = [], prefix = PROJECT_CONFIG_ARG_PREFIX) {
@@ -90,9 +104,30 @@ export function stripProjectConfigArgs(argv = [], prefix = PROJECT_CONFIG_ARG_PR
 }
 
 export function readProjectConfig(configPath) {
-  const doc = readJson(configPath)
+  let doc
+  try {
+    doc = readJson(configPath)
+  } catch (error) {
+    if (error instanceof AtelierDiagnosticError) {
+      throw new AtelierDiagnosticError(
+        error.code === 'artifact-missing' ? 'project-config-missing' : 'project-config-json-invalid',
+        error.code === 'artifact-missing'
+          ? `atelier project config not found: ${configPath}`
+          : `atelier project config is malformed: ${configPath}`,
+        {
+          hint: error.code === 'artifact-missing'
+            ? 'Pass --project PATH to a tracked atelier.project.json file.'
+            : 'Repair the JSON syntax, then run atelier config check with the same --project path.',
+          cause: error,
+        },
+      )
+    }
+    throw error
+  }
   if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
-    throw new Error(`atelier project config must be a JSON object: ${configPath}`)
+    throw new AtelierDiagnosticError('project-config-shape-invalid', `Atelier project config must be a JSON object: ${configPath}`, {
+      hint: 'Repair the document shape, then run atelier config check with the same --project path.',
+    })
   }
   return doc
 }
@@ -130,22 +165,7 @@ export function readLocalOverlay({ configDir, env = process.env, cwd = process.c
 }
 
 export function parseRepoPathOverrides(argv = process.argv.slice(2), cwd = process.cwd()) {
-  const out = new Map()
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index]
-    let value = null
-    if (arg === '--repo-path' && argv[index + 1]) {
-      value = argv[index + 1]
-      index += 1
-    } else if (typeof arg === 'string' && arg.startsWith('--repo-path=')) {
-      value = arg.slice('--repo-path='.length)
-    }
-    if (!value || !value.includes('=')) continue
-    const [name, ...rest] = value.split('=')
-    const repoPath = rest.join('=')
-    if (firstString(name) && firstString(repoPath)) out.set(name.trim(), resolvePathValue(repoPath, cwd))
-  }
-  return out
+  return new Map([...parseProjectOptions(argv).repoPaths].map(([name, value]) => [name, resolvePathValue(value, cwd)]))
 }
 
 function overlayRepoPath(overlay, repoName) {
@@ -155,25 +175,25 @@ function overlayRepoPath(overlay, repoName) {
   return firstString(direct, repo.path, repo.localPath)
 }
 
-function resolveRepoPath({ repo, repoName, configDir, workspaceRoot, overlay, cliRepoPaths }) {
+function resolveRepoPath({ repo, repoName, configDir, workspaceRoot, overlay, cliRepoPaths, gitExecutable, env }) {
   if (repoName && cliRepoPaths.has(repoName)) return cliRepoPaths.get(repoName)
   const overlayPath = overlayRepoPath(overlay, repoName)
   const fromOverlay = resolvePathValue(overlayPath, configDir)
   if (fromOverlay) return fromOverlay
   const fromConfig = resolvePathValue(repo.path, configDir) || resolvePathValue(repo.path, workspaceRoot)
   if (fromConfig) return fromConfig
-  return discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot })
+  return discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot, gitExecutable, env })
 }
 
-function repoPathSource({ repo, repoName, overlay, cliRepoPaths, workspaceRoot, configDir }) {
+function repoPathSource({ repo, repoName, overlay, cliRepoPaths, workspaceRoot, configDir, gitExecutable, env }) {
   if (repoName && cliRepoPaths.has(repoName)) return 'cli'
   if (overlayRepoPath(overlay, repoName)) return 'local-overlay'
   if (firstString(repo.path)) return 'tracked-config'
-  if (discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot })) return 'sibling-discovery'
+  if (discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot, gitExecutable, env })) return 'sibling-discovery'
   return null
 }
 
-function discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot }) {
+function discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot, gitExecutable = 'git', env = process.env }) {
   if (!repoName) return null
   const candidates = [
     path.join(workspaceRoot, repoName),
@@ -182,14 +202,14 @@ function discoverSiblingRepoPath({ repo, repoName, configDir, workspaceRoot }) {
   ]
   for (const candidate of candidates) {
     if (!fs.existsSync(candidate)) continue
-    if (repo.remote && !gitRemoteMatches(candidate, repo.remote)) continue
+    if (repo.remote && !gitRemoteMatches(candidate, repo.remote, { gitExecutable, env })) continue
     return path.resolve(candidate)
   }
   return null
 }
 
-function gitRemoteMatches(repoPath, expected) {
-  const result = spawnSync('git', ['-C', repoPath, 'remote', 'get-url', 'origin'], { encoding: 'utf8' })
+function gitRemoteMatches(repoPath, expected, { gitExecutable = 'git', env = process.env } = {}) {
+  const result = spawnSync(gitExecutable, ['-C', repoPath, 'remote', 'get-url', 'origin'], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
   if (result.status !== 0) return false
   const actual = normalizeRemote(result.stdout.trim())
   return actual === normalizeRemote(expected)
@@ -203,9 +223,9 @@ function normalizeRemote(value) {
     .toLowerCase()
 }
 
-export function gitRemoteUrl(repoPath) {
+export function gitRemoteUrl(repoPath, { gitExecutable = 'git', env = process.env } = {}) {
   if (!repoPath || !fs.existsSync(repoPath)) return null
-  const result = spawnSync('git', ['-C', repoPath, 'remote', 'get-url', 'origin'], { encoding: 'utf8' })
+  const result = spawnSync(gitExecutable, ['-C', repoPath, 'remote', 'get-url', 'origin'], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
   return result.status === 0 ? firstString(result.stdout) : null
 }
 
@@ -228,7 +248,9 @@ export function resolveProjectConfig({
   env = process.env,
   cwd = process.cwd(),
   configArgPrefix = PROJECT_CONFIG_ARG_PREFIX,
+  gitExecutable = 'git',
   configEnv = PROJECT_CONFIG_ENV,
+  writeLocalState = true,
   defaults = {},
 } = {}) {
   const argPath = projectConfigArg(argv, configArgPrefix)
@@ -253,7 +275,9 @@ export function resolveProjectConfig({
       missingConfigPath = configPath
       configPath = null
     } else {
-      throw new Error(`atelier project config not found: ${configPath || requestedPath}`)
+      throw new AtelierDiagnosticError('project-config-missing', `atelier project config not found: ${configPath || requestedPath}`, {
+        hint: 'Pass --project PATH to a tracked atelier.project.json file.',
+      })
     }
   }
 
@@ -331,7 +355,7 @@ export function resolveProjectConfig({
     localOverlay,
     repos: (Array.isArray(config.repos) ? config.repos : []).map((repo) => {
       const repoName = firstString(repo.name) || (repo.path ? path.basename(repo.path) : null)
-      const repoPath = resolveRepoPath({ repo, repoName, configDir, workspaceRoot, overlay: localOverlay.overlay, cliRepoPaths })
+      const repoPath = resolveRepoPath({ repo, repoName, configDir, workspaceRoot, overlay: localOverlay.overlay, cliRepoPaths, gitExecutable, env })
       const external = isExternalRepo(repo)
       return {
         ...repo,
@@ -339,23 +363,25 @@ export function resolveProjectConfig({
         path: repoPath,
         external,
         readBoundary: external ? null : firstString(repo.readBoundary) || 'team',
-        pathSource: repoPath ? repoPathSource({ repo, repoName, overlay: localOverlay.overlay, cliRepoPaths, workspaceRoot, configDir }) : null,
+        pathSource: repoPath ? repoPathSource({ repo, repoName, overlay: localOverlay.overlay, cliRepoPaths, workspaceRoot, configDir, gitExecutable, env }) : null,
       }
     }),
   }
-  resolved.localState = ensureLocalState(resolved, { write: true })
+  resolved.localState = ensureLocalState(resolved, { write: writeLocalState, gitExecutable, env })
   return resolved
 }
 
-export function commandProject({ argv = process.argv.slice(2), env = process.env, cwd = process.cwd() } = {}) {
-  const project = resolveProjectConfig({ argv, env, cwd })
+export function commandProject({ argv = process.argv.slice(2), env = process.env, cwd = process.cwd(), gitExecutable = 'git', writeLocalState = true } = {}) {
+  const project = resolveProjectConfig({ argv, env, cwd, gitExecutable, writeLocalState })
   // Fail closed at CLI entry, but only when a real config file was loaded; the
   // defaults/no-file path resolves with an empty config that would spuriously
   // fail document validation.
   if (project.configPath != null) {
     const configErrors = validateProjectConfigDoc(project.config)
     if (configErrors.length) {
-      throw new Error(`invalid atelier project config at ${project.configPath}:\n${configErrors.join('\n')}`)
+      throw new AtelierDiagnosticError('project-config-contract-invalid', `invalid atelier project config at ${project.configPath}:\n${configErrors.join('\n')}`, {
+        hint: 'Fix the listed fields, then run atelier config check with the same --project path.',
+      })
     }
   }
   if (project.schema !== PROJECT_CONFIG_SCHEMA) {
@@ -375,21 +401,36 @@ export function localStateRoot(projectOrDir) {
   return path.join(configDir || process.cwd(), LOCAL_STATE_DIR)
 }
 
-function gitRootFor(dir) {
-  const result = spawnSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' })
+function gitRootFor(dir, { gitExecutable = 'git', env = process.env } = {}) {
+  const result = spawnSync(gitExecutable, ['-C', dir, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
   return result.status === 0 ? result.stdout.trim() : null
 }
 
-function isIgnoredByGit(gitRoot, rel) {
-  const result = spawnSync('git', ['-C', gitRoot, 'check-ignore', '-q', rel], { encoding: 'utf8' })
+function gitPrefixFor(dir, { gitExecutable = 'git', env = process.env } = {}) {
+  const result = spawnSync(gitExecutable, ['-C', dir, 'rev-parse', '--show-prefix'], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
+  return result.status === 0 ? result.stdout.trim() : null
+}
+
+function isIgnoredByGit(gitRoot, rel, { gitExecutable = 'git', env = process.env } = {}) {
+  const result = spawnSync(gitExecutable, ['-C', gitRoot, 'check-ignore', '-q', rel], { encoding: 'utf8', env: sanitizedGitEnvironment(env) })
   return result.status === 0
 }
 
-export function ensureLocalState(project, { write = false } = {}) {
+export function ensureLocalState(project, { write = false, gitExecutable = 'git', env = process.env } = {}) {
   const root = localStateRoot(project)
-  const gitRoot = gitRootFor(project.configDir)
-  const rel = gitRoot ? path.relative(gitRoot, root).split(path.sep).join('/') : LOCAL_STATE_DIR
-  const ignored = gitRoot ? isIgnoredByGit(gitRoot, `${rel}/`) || isIgnoredByGit(gitRoot, rel) : true
+  const gitRoot = gitRootFor(project.configDir, { gitExecutable, env })
+  // Git owns the repository-relative spelling. Deriving it by comparing
+  // filesystem paths breaks when Windows exposes the cwd through an 8.3 short
+  // name (RUNNER~1) but Git reports the same root through its long name.
+  const gitPrefix = gitRoot ? gitPrefixFor(project.configDir, { gitExecutable, env }) : null
+  const rel = gitRoot && gitPrefix !== null ? `${gitPrefix}${LOCAL_STATE_DIR}` : LOCAL_STATE_DIR
+  // A directory-only ignore rule such as `.atelier-local/` is not evaluated
+  // consistently by Git for an absent directory on every host. Probe a
+  // hypothetical child as well: it proves the directory rule before Atelier
+  // creates any local state, including on Git for Windows.
+  const ignored = gitRoot && gitPrefix !== null
+    ? isIgnoredByGit(gitRoot, `${rel}/.atelier-ignore-probe`, { gitExecutable, env }) || isIgnoredByGit(gitRoot, `${rel}/`, { gitExecutable, env }) || isIgnoredByGit(gitRoot, rel, { gitExecutable, env })
+    : gitRoot === null
   const report = {
     root,
     ignored,
@@ -443,6 +484,19 @@ function extErrors(value, label) {
     .map(([key]) => `${label}.${key} must be an object; ext members are namespaced objects`)
 }
 
+// Hands one namespaced ext member to its structured consumer, uninterpreted.
+// The project validator above deliberately does not look inside a member, so
+// the consumer validates it against its own closed contract and fails closed.
+// `present` separates "no such member" (the consumer's feature is simply not
+// configured) from a member that exists with any value at all, including a
+// malformed one, which the consumer must refuse rather than ignore.
+export function projectExtMember(project, key) {
+  const ext = project?.config?.ext
+  if (ext == null) return { present: false, value: undefined }
+  if (typeof ext !== 'object' || Array.isArray(ext)) return { present: true, value: undefined }
+  return Object.hasOwn(ext, key) ? { present: true, value: ext[key] } : { present: false, value: undefined }
+}
+
 export function validateProjectConfigDoc(doc, { neutralTemplate = false } = {}) {
   const errors = []
   if (!doc || typeof doc !== 'object' || Array.isArray(doc)) return ['project config must be a JSON object']
@@ -504,6 +558,7 @@ export function validateProjectConfigDoc(doc, { neutralTemplate = false } = {})
   }
   if (alignment.appRepo != null && !firstString(alignment.appRepo)) errors.push('alignment.appRepo must be a non-empty string')
 
+  const repoNames = new Set()
   for (const [index, repo] of (Array.isArray(doc.repos) ? doc.repos : []).entries()) {
     if (!repo || typeof repo !== 'object' || Array.isArray(repo)) {
       errors.push(`repos[${index}] must be an object`)
@@ -512,6 +567,11 @@ export function validateProjectConfigDoc(doc, { neutralTemplate = false } = {})
     errors.push(...unknownKeyErrors(repo, `repos[${index}]`, new Set(['name', 'path', 'readBoundary', 'role', 'kind', 'remote', 'identity', 'aliases', 'required', 'ext'])))
     errors.push(...extErrors(repo.ext, `repos[${index}].ext`))
     if (!firstString(repo.name)) errors.push(`repos[${index}].name is required`)
+    else {
+      const key = repo.name.toLowerCase()
+      if (repoNames.has(key)) errors.push(`repos[${index}].name duplicates another repository name`)
+      repoNames.add(key)
+    }
     if (repo.identity != null) {
       const identity = asObject(repo.identity)
       errors.push(...unknownKeyErrors(identity, `repos[${index}].identity`, new Set(['provider', 'id', 'ext'])))

package/src/project/durable-state.mjs

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { hostname } from 'node:os';
+import { ensureContainedPrivateDirectory, openRegularFileNoFollow, readRegularTextNoFollow, syncPrivateDirectory } from './private-state.mjs';
+
+const host = createHash('sha256').update(hostname()).digest('hex');
+const pendingPattern = /^\.atelier-write-[a-f0-9-]{36}\.tmp$/;
+export const isPendingPrivateWrite = name => pendingPattern.test(name);
+
+export { syncPrivateDirectory };
+
+// Publish a complete immutable file with an atomic, non-overwriting hard link.
+// A process interruption can leave a private staging file, never a partial final.
+export function publishPrivateFile(file, bytes) {
+  const directory = path.dirname(file);
+  const pending = path.join(directory, `.atelier-write-${randomUUID()}.tmp`);
+  let fd;
+  try {
+    fd = openRegularFileNoFollow(pending, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
+    fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); fs.closeSync(fd); fd = undefined;
+    try { fs.linkSync(pending, file); }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const existing = openRegularFileNoFollow(file);
+      try { if (!fs.readFileSync(existing).equals(Buffer.from(bytes))) throw error; }
+      finally { fs.closeSync(existing); }
+    }
+    syncPrivateDirectory(directory);
+    const actual = openRegularFileNoFollow(file);
+    try { if (!fs.readFileSync(actual).equals(Buffer.from(bytes))) throw new Error('published file readback mismatch'); }
+    finally { fs.closeSync(actual); }
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    try { fs.unlinkSync(pending); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+}
+
+function unavailable(diagnostic = { reason: 'ownership changed' }) {
+  return Object.assign(new Error(`EEXIST: private state is locked (${diagnostic.reason}${diagnostic.file ? `: ${diagnostic.file}` : ''}); inspectPrivateLock and preserve ownership records before offline recovery`), { code: 'EEXIST', diagnostic });
+}
+function ownerState(record, legacy = false) {
+  const pid = typeof record === 'number' ? record : record?.pid;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return 'invalid owner';
+  if (!legacy && record?.host !== host) return 'host identity differs';
+  try { process.kill(pid, 0); return 'process exists'; }
+  catch (error) { return error.code === 'ESRCH' ? 'absent' : 'process identity unavailable'; }
+}
+
+// Read-only diagnosis. Older tickets were superseded by a successful successor;
+// only the newest ticket owns this lock. A release marker prevents a completed
+// successor from disappearing and resurrecting an obsolete owner on PID reuse.
+export function inspectPrivateLock(lockPath) {
+  const directory = `${lockPath}.owners`;
+  let names;
+  try {
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) return { available: false, reason: 'unsafe ownership directory' };
+    names = fs.readdirSync(directory).filter(name => !isPendingPrivateWrite(name)).sort();
+  } catch (error) { if (error.code !== 'ENOENT') throw error; names = []; }
+  const unexpected = names.find(name => !/^\d{12}\.(json|released)$/.test(name));
+  if (unexpected) return { available: false, reason: 'unknown ownership file', file: unexpected };
+  const nameSet = new Set(names);
+  const tickets = names.filter(name => name.endsWith('.json'));
+  const orphan = names.find(name => name.endsWith('.released') && !nameSet.has(name.replace(/\.released$/, '.json')));
+  if (orphan) return { available: false, reason: 'release without owner', file: orphan };
+  let legacy, legacyDigest = null;
+  try {
+    const bytes = readRegularTextNoFollow(lockPath);
+    legacy = JSON.parse(bytes); legacyDigest = createHash('sha256').update(bytes).digest('hex');
+  } catch (error) {
+    if (error.code !== 'ENOENT') return { available: false, reason: 'unreadable legacy owner', file: path.basename(lockPath) };
+  }
+  if (tickets.length) {
+    const file = tickets.at(-1), generation = Number(file.slice(0, 12));
+    let body, record;
+    try { body = readRegularTextNoFollow(path.join(directory, file)); record = JSON.parse(body); }
+    catch { return { available: false, reason: 'unreadable owner', file }; }
+    if (!Number.isSafeInteger(record?.pid) || record.pid <= 0 || !/^[a-f0-9]{64}$/.test(record?.host) || !/^[a-f0-9-]{36}$/.test(record?.nonce)) return { available: false, reason: 'invalid owner', file };
+    if (legacyDigest !== null && record.legacyDigest !== legacyDigest) {
+      const reason = ownerState(legacy, true);
+      if (reason !== 'absent') return { available: false, reason: `legacy ${reason}`, file: path.basename(lockPath) };
+    }
+    const marker = file.replace(/\.json$/, '.released');
+    if (names.includes(marker)) {
+      try {
+        if (readRegularTextNoFollow(path.join(directory, marker)) !== body) return { available: false, reason: 'release identity differs', file: marker };
+      } catch { return { available: false, reason: 'unreadable release', file: marker }; }
+      return { available: true, reason: 'released', generation, file, legacyDigest };
+    }
+    const reason = ownerState(record);
+    return { available: reason === 'absent', reason, generation, file, legacyDigest };
+  }
+  if (legacyDigest === null) return { available: true, reason: 'unused', generation: 0, legacyDigest };
+  const reason = ownerState(legacy, true);
+  return { available: reason === 'absent', reason, generation: 0, file: path.basename(lockPath), legacyDigest };
+}
+
+export function acquirePrivateLock(lockPath) {
+  const parent = path.dirname(lockPath);
+  const directory = ensureContainedPrivateDirectory({ workspaceRoot: parent, directory: `${lockPath}.owners`, label: 'private lock' });
+  let ticket, body;
+  try {
+    const status = inspectPrivateLock(lockPath);
+    if (!status.available) throw unavailable(status);
+    const generation = status.generation;
+    if (generation >= 999999999999) throw unavailable({ reason: 'ownership generation exhausted' });
+    ticket = path.join(directory, `${String(generation + 1).padStart(12, '0')}.json`);
+    body = JSON.stringify({ pid: process.pid, host, nonce: randomUUID(), legacyDigest: status.legacyDigest });
+    publishPrivateFile(ticket, body);
+    let released = false;
+    return () => {
+      if (released) return;
+      if (readRegularTextNoFollow(ticket) !== body) throw unavailable();
+      publishPrivateFile(ticket.replace(/\.json$/, '.released'), body);
+      released = true;
+    };
+  } catch (error) {
+    // No operation has started: clean up only this exact attempted owner.
+    if (ticket && body) {
+      try { if (readRegularTextNoFollow(ticket) === body) fs.unlinkSync(ticket); }
+      catch { /* Preserve uncertain ownership for offline diagnosis. */ }
+    }
+    if (error.code === 'EEXIST' && !error.diagnostic) throw unavailable(); throw error;
+  }
+}
+
+export function withPrivateLock(lockPath, operation) {
+  const release = acquirePrivateLock(lockPath);
+  try { return operation(); } finally { release(); }
+}
+
+// Revalidate file identities on every read; unchanged prefixes reuse their
+// verified result. A changed existing file forces replay, a missing tail is
+// refused for the lifetime of this reader. Startup always verifies all history.
+export function createVerifiedFileSequence({ directory, initial, apply, ignoreFiles = [] }) {
+  let names = [], identities = [], value = initial();
+  const identity = file => {
+    const s = fs.lstatSync(file, { bigint: true });
+    if (!s.isFile() || s.isSymbolicLink()) throw new Error('non-regular history refused');
+    return [s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs].join(':');
+  };
+  return () => {
+    const listed = fs.readdirSync(directory).filter(n => !isPendingPrivateWrite(n)).sort();
+    // Explicit adapter metadata exceptions must still be regular files. Never
+    // hide unknown filenames or malformed committed records behind a glob.
+    for (const name of listed.filter(n => ignoreFiles.includes(n))) identity(path.join(directory, name));
+    const next = listed.filter(n => !ignoreFiles.includes(n));
+    if (next.length < names.length) throw new Error('history shortened; preserve and inspect');
+    const ids = next.map(n => identity(path.join(directory, n)));
+    const reuse = names.every((n, i) => n === next[i] && identities[i] === ids[i]);
+    let result = reuse ? value : initial();
+    for (let i = reuse ? names.length : 0; i < next.length; i++) {
+      const file = path.join(directory, next[i]);
+      result = apply(readRegularTextNoFollow(file), result, i + 1, next[i]);
+      if (identity(file) !== ids[i]) throw new Error('history changed during verification');
+    }
+    names = next; identities = ids; value = result;
+    return structuredClone(result);
+  };
+}