@mnstry/atelier 0.2.0-alpha.6 → 0.2.0-alpha.8

package/src/guides/contracts.mjs

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { canonicalize } from '../attestation/jcs.mjs';
+import { validateJsonSchema } from '../export/atelier-export-contract.mjs';
+
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-guide.v1.schema.json', import.meta.url), 'utf8'));
+export function guideDocumentDigest(value) { return createHash('sha256').update(canonicalize(value)).digest('hex'); }
+export function validateGuideDocument(value, kind) {
+  if (!['offer', 'capability', 'consent', 'engagement'].includes(kind)) return ['unknown guide document kind'];
+  const errors = validateJsonSchema({ $schema: schema.$schema, $defs: schema.$defs, $ref: `#/$defs/${kind}` }, value);
+  if (kind === 'capability' && !errors.length) {
+    const url = new URL(value.serviceRef);
+    if (url.username || url.password || url.search || url.hash) errors.push('service reference must not contain credentials, query or fragment');
+  }
+  return errors;
+}
+function requireValid(value, kind) {
+  if (validateGuideDocument(value, kind).length) throw new Error(`invalid guide ${kind}`);
+}
+export function createGuideEngagement(offer) {
+  requireValid(offer, 'offer');
+  return { schema: 'mnstry.atelier-guide-engagement@v1', offerDigest: guideDocumentDigest(offer),
+    revision: 0, status: 'proposed', authority: 'local-assertion-only' };
+}
+export function transitionGuideEngagement(state, { expectedRevision, action, offerDigest }) {
+  requireValid(state, 'engagement');
+  if (expectedRevision !== state.revision || offerDigest !== state.offerDigest) throw new Error('stale or mismatched guide engagement');
+  const routes = { proposed: { accept: 'accepted', revoke: 'revoked' }, accepted: { pause: 'paused', revoke: 'revoked' }, paused: { resume: 'accepted', revoke: 'revoked' }, revoked: {} };
+  const status = Object.hasOwn(routes[state.status], action) ? routes[state.status][action] : null;
+  if (!status) throw new Error('guide transition refused');
+  return { ...state, revision: state.revision + 1, status };
+}
+
+// No connection, credentials, invocation, payment, or permission grant occurs.
+// A host must independently authenticate participants and revalidate revocation,
+// consent, policy, schema and exact bytes immediately before any disclosure.
+export function assessGuideInvocation({ offer, capability, engagement, consent, payload, now }) {
+  const blockers = [];
+  for (const [kind, value] of Object.entries({ offer, capability, engagement, consent })) {
+    if (validateGuideDocument(value, kind).length) blockers.push(`invalid ${kind}`);
+  }
+  if (blockers.length) return { status: 'blocked', blockers, executionAuthority: false };
+  let bytes;
+  try { bytes = canonicalize(payload); } catch { blockers.push('payload is not canonical JSON'); }
+  if (!Number.isFinite(now)) blockers.push('explicit current time required');
+  if (engagement.status !== 'accepted') blockers.push('engagement is not accepted');
+  if (engagement.offerDigest !== guideDocumentDigest(offer) || consent.offerDigest !== engagement.offerDigest) blockers.push('offer binding mismatch');
+  if (consent.engagementRevision !== engagement.revision) blockers.push('consent revision is stale');
+  if (!offer.capabilityIds.includes(capability.id) || consent.capabilityDigest !== guideDocumentDigest(capability)) blockers.push('capability binding mismatch');
+  if (consent.status !== 'approved') blockers.push('disclosure consent is not approved');
+  if (now < Date.parse(consent.validFrom) || now >= Date.parse(consent.expiresAt) || Date.parse(consent.validFrom) >= Date.parse(consent.expiresAt)) blockers.push('consent is not currently valid');
+  if (bytes !== undefined && (Buffer.byteLength(bytes) > capability.maxInputBytes || guideDocumentDigest(payload) !== consent.payloadDigest)) blockers.push('payload binding or byte limit mismatch');
+  return { status: blockers.length ? 'blocked' : 'eligible-for-host-validation', blockers, executionAuthority: false };
+}

package/src/intake/store.mjs

@@ -0,0 +1,119 @@
+import { withPrivateLock, publishPrivateFile } from '../project/durable-state.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { canonicalize } from '../attestation/jcs.mjs';
+import { validateJsonSchema } from '../export/atelier-export-contract.mjs';
+import { ensureContainedPrivateDirectory, openRegularFileNoFollow } from '../project/private-state.mjs';
+
+export const INTAKE_MAX_BYTES = 16 * 1024 * 1024;
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-intake.v1.schema.json', import.meta.url), 'utf8'));
+export function validateIntakeDocument(value) { return validateJsonSchema(schema, value); }
+function valid(value) { if (validateIntakeDocument(value).length) throw new Error('invalid intake document'); return value; }
+export function intakeDigest(bytes) { return createHash('sha256').update(bytes).digest('hex'); }
+const idPattern = /^[a-z][a-z0-9-]{0,63}$/;
+const digestPattern = /^[0-9a-f]{64}$/;
+function digest(value) { if (!digestPattern.test(value ?? '')) throw new Error('invalid content digest'); return value; }
+function id(value) { if (!idPattern.test(value ?? '')) throw new Error('invalid intake identifier'); return value; }
+function read(file) {
+  const fd = openRegularFileNoFollow(file);
+  try {
+    if (fs.fstatSync(fd).size > INTAKE_MAX_BYTES) throw new Error('intake byte ceiling exceeded');
+    const bytes = fs.readFileSync(fd);
+    if (bytes.length > INTAKE_MAX_BYTES) throw new Error('intake byte ceiling exceeded');
+    return bytes;
+  } finally { fs.closeSync(fd); }
+}
+function immutable(file, bytes) {
+  publishPrivateFile(file, bytes);
+  if (!read(file).equals(Buffer.from(bytes))) throw new Error('immutable intake readback mismatch');
+}
+
+// Local integrity storage, not a worker, semantic acceptance service, or import
+// authority. Callers retain their source trees and choose their existing extractor.
+export function createIntakeStore({ workspaceRoot = process.cwd() } = {}) {
+  const root = fs.realpathSync(workspaceRoot);
+  function placement() {
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_')));
+    try {
+      if (execFileSync('git', ['-C', root, 'ls-files', '-z', '--', '.atelier-local'], { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })) throw new Error('tracked state');
+      execFileSync('git', ['-C', root, 'check-ignore', '--quiet', '.atelier-local/'], { env, stdio: 'ignore' });
+    } catch { throw new Error('intake requires ignored, untracked .atelier-local/ in a Git workspace'); }
+  }
+  placement();
+  function directory(...parts) {
+    return ensureContainedPrivateDirectory({ workspaceRoot: root, directory: path.join(root, '.atelier-local', 'intake', ...parts), label: 'intake state' });
+  }
+  function locked(fn) {
+    placement();
+    const file = path.join(directory(), 'operation.lock');
+    return withPrivateLock(file, fn);
+  }
+  function sourceFile(ref) {
+    if (typeof ref !== 'string' || !ref || path.isAbsolute(ref) || ref.includes('\\') ||
+      ref.split('/').some(p => !p || p === '.' || p === '..' || p.startsWith('.'))) throw new Error('source must be a visible workspace-relative file');
+    let file = root;
+    for (const part of ref.split('/')) {
+      file = path.join(file, part);
+      if (fs.lstatSync(file).isSymbolicLink()) throw new Error('redirected intake source refused');
+    }
+    return file;
+  }
+  function blob(blobId) {
+    const bytes = read(path.join(directory('blobs'), digest(blobId)));
+    if (intakeDigest(bytes) !== blobId) throw new Error('stored blob digest mismatch');
+    return bytes;
+  }
+  function record(dir, name, value) { valid(value); immutable(path.join(dir, name), canonicalize(value) + '\n'); return value; }
+  return Object.freeze({
+    ingest({ ref, expectedDigest }) {
+      return locked(() => {
+        digest(expectedDigest);
+        const file = sourceFile(ref), bytes = read(file);
+        if (intakeDigest(bytes) !== expectedDigest) throw new Error('source digest mismatch');
+        immutable(path.join(directory('blobs'), expectedDigest), bytes);
+        if (intakeDigest(read(sourceFile(ref))) !== expectedDigest) throw new Error('source changed during intake');
+        const manifest = { schema: 'mnstry.atelier-intake-source@v1', sourceRef: ref, blobId: expectedDigest, bytes: bytes.length, originalMutation: false };
+        return record(directory('sources'), intakeDigest(canonicalize(manifest)) + '.json', manifest);
+      });
+    },
+    beginAttempt({ attemptId, blobId, extractorId, extractorVersion, configurationDigest }) {
+      return locked(() => {
+        id(attemptId); id(extractorId); digest(configurationDigest); blob(blobId);
+        if (typeof extractorVersion !== 'string' || !/^[a-zA-Z0-9._-]{1,64}$/.test(extractorVersion)) throw new Error('invalid extractor version');
+        const manifest = { schema: 'mnstry.atelier-intake-attempt@v1', attemptId, blobId, extractorId, extractorVersion, configurationDigest };
+        return record(directory('attempts', attemptId), 'attempt.json', manifest);
+      });
+    },
+    completeAttempt({ attemptId, output, expectedOutputDigest }) {
+      return locked(() => {
+        id(attemptId); digest(expectedOutputDigest);
+        if (typeof output !== 'string' || Buffer.byteLength(output) > INTAKE_MAX_BYTES) throw new Error('output must be bounded UTF-8 text');
+        if (intakeDigest(output) !== expectedOutputDigest) throw new Error('output digest mismatch');
+        const dir = directory('attempts', attemptId);
+        const attemptBytes = read(path.join(dir, 'attempt.json'));
+        const attempt = valid(JSON.parse(attemptBytes));
+        if (attempt.attemptId !== attemptId || attempt.schema !== 'mnstry.atelier-intake-attempt@v1') throw new Error('attempt identity mismatch');
+        blob(attempt.blobId);
+        immutable(path.join(dir, 'output.txt'), output);
+        // Completion is written last. A crash before it is incomplete, not success.
+        return record(dir, 'completion.json', { schema: 'mnstry.atelier-intake-completion@v1', attemptId,
+          attemptDigest: intakeDigest(attemptBytes), outputDigest: expectedOutputDigest, bytes: Buffer.byteLength(output),
+          integrity: 'verified', semanticAcceptance: 'pending' });
+      });
+    },
+    readCompletion(attemptId) {
+      placement(); id(attemptId);
+      const dir = directory('attempts', attemptId), receipt = valid(JSON.parse(read(path.join(dir, 'completion.json'))));
+      if (receipt.schema !== 'mnstry.atelier-intake-completion@v1' || receipt.attemptId !== attemptId ||
+        receipt.integrity !== 'verified' || receipt.semanticAcceptance !== 'pending') throw new Error('invalid completion receipt');
+      const attemptBytes = read(path.join(dir, 'attempt.json')), output = read(path.join(dir, 'output.txt'));
+      if (intakeDigest(attemptBytes) !== receipt.attemptDigest || intakeDigest(output) !== receipt.outputDigest || output.length !== receipt.bytes) throw new Error('completion integrity mismatch');
+      const attempt = valid(JSON.parse(attemptBytes));
+      if (attempt.attemptId !== attemptId || attempt.schema !== 'mnstry.atelier-intake-attempt@v1') throw new Error('attempt identity mismatch');
+      blob(attempt.blobId);
+      return receipt;
+    },
+  });
+}

package/src/preview/channel.mjs

@@ -0,0 +1,89 @@
+// Browser-only channel. Host/session/service authority never enters this module.
+import { parseRequest, parseBoundedJSON, closed, need, isRef, isDigest, MODES } from '../composition/wire.mjs';
+const HELLO = 'atelier.preview.mount/experimental-v1';
+function origin(value) { const u = new URL(value); need(u.origin !== 'null' && u.protocol === 'https:' && u.origin === value); return value; }
+function resultCheck(bytes, request, generation) {
+  const result = parseBoundedJSON(bytes);
+  closed(result, ['state'], ['projectedData']);
+  const s = result.state;
+  closed(s, ['schema', 'requestId', 'placementId', 'sourceDigest', 'mode', 'state', 'sessionGeneration', 'publicMessage']);
+  need(s.schema === 'atelier-preview-state/proposal-v1' && s.requestId === request.requestId && s.placementId === request.placementId && s.sourceDigest === request.sourceDigest && s.mode === request.mode);
+  need(s.sessionGeneration === generation && ['loading', 'ready', 'unauthenticated', 'forbidden', 'expired', 'unavailable', 'stale'].includes(s.state));
+  need(typeof s.publicMessage === 'string' && s.publicMessage.length <= 160);
+  need(s.state === 'ready' ? Object.hasOwn(result, 'projectedData') : !Object.hasOwn(result, 'projectedData'));
+  return result;
+}
+function fail(request, generation) { return { state: { schema: 'atelier-preview-state/proposal-v1', requestId: request.requestId, placementId: request.placementId,
+  sourceDigest: request.sourceDigest, mode: request.mode, state: 'unavailable', sessionGeneration: generation, publicMessage: 'Preview unavailable.' } }; }
+
+export function mountPreview({ frame, previewOrigin, requestBytes, generation, handle, onState = () => {} }) {
+  origin(previewOrigin); need(new URL(frame.src).origin === previewOrigin && previewOrigin !== window.location.origin);
+  const template = parseRequest(requestBytes); need(!template.intentRef && Number.isSafeInteger(generation) && generation >= 0 && typeof handle === 'function');
+  const nonce = crypto.randomUUID(), channel = new MessageChannel(), controller = new AbortController();
+  let active = true, ready = false, sequence = 0, latest = 0;
+  const invalidate = () => {
+    if (!active) return; active = false; controller.abort();
+    channel.port1.postMessage(JSON.stringify({type:'invalidate',nonce})); channel.port1.close(); frame.removeEventListener('load', invalidate);
+    onState('stale');
+  };
+  frame.addEventListener('load', invalidate); // Future navigation invalidates this mount.
+  channel.port1.onmessage = async event => {
+    if (!active) return;
+    try {
+      const v = parseBoundedJSON(event.data);
+      if (!ready) { closed(v, ['type', 'nonce']); need(v.type === 'ready' && v.nonce === nonce); ready = true; onState('connected'); return; }
+      closed(v, ['type', 'nonce', 'sequence', 'request']);
+      need(v.type === 'request' && v.nonce === nonce && Number.isSafeInteger(v.sequence) && v.sequence > sequence);
+      const request = parseRequest(v.request);
+      need(request.placementId === template.placementId && request.sourceDigest === template.sourceDigest && request.mode === template.mode);
+      sequence = v.sequence; latest = sequence; const thisSequence = sequence;
+      let result;
+      try { result = resultCheck(JSON.stringify(await handle(v.request, controller.signal)), request, generation); }
+      catch { result = fail(request, generation); }
+      if (!active || controller.signal.aborted || thisSequence !== latest) return;
+      channel.port1.postMessage(JSON.stringify({ type: 'result', nonce, sequence: thisSequence, result }));
+    } catch { invalidate(); }
+  };
+  channel.port1.start();
+  frame.contentWindow.postMessage(JSON.stringify({ type: HELLO, nonce, generation, request: requestBytes }), previewOrigin, [channel.port2]);
+  return Object.freeze({ dispose: invalidate });
+}
+
+export function receivePreview({ shellOrigin, onMount, onResult, onInvalidate = () => {} }) {
+  origin(shellOrigin); need(shellOrigin !== window.location.origin);
+  let active = null;
+  function clear() { active?.port.close(); active = null; onInvalidate(); }
+  function receive(event) {
+    if (event.origin !== shellOrigin || event.source !== window.parent) return;
+    try {
+      const v = parseBoundedJSON(event.data);
+      closed(v, ['type', 'nonce', 'generation', 'request']);
+      need(v.type === HELLO && isRef(v.nonce) && Number.isSafeInteger(v.generation) && v.generation >= 0 && event.ports.length === 1);
+      const request = parseRequest(v.request); need(!request.intentRef && isDigest(request.sourceDigest) && MODES.includes(request.mode));
+      clear();
+      const mount = { port: event.ports[0], nonce: v.nonce, generation: v.generation, request, sequence: 0, settled: 0 };
+      active = mount;
+      mount.port.onmessage = e => {
+        if (active !== mount) return;
+        try {
+          const packet = parseBoundedJSON(e.data);
+          if (packet?.type === 'invalidate') { closed(packet, ['type','nonce']); need(packet.nonce === mount.nonce); clear(); return; }
+          closed(packet, ['type', 'nonce', 'sequence', 'result']);
+          need(packet.type === 'result' && packet.nonce === mount.nonce && packet.sequence === mount.sequence && packet.sequence > mount.settled);
+          const result = resultCheck(JSON.stringify(packet.result), mount.pending, mount.generation);
+          mount.settled = packet.sequence; onResult(result);
+        } catch { clear(); }
+      };
+      mount.port.start(); mount.port.postMessage(JSON.stringify({ type: 'ready', nonce: mount.nonce }));
+      onMount(request);
+    } catch { clear(); }
+  }
+  window.addEventListener('message', receive);
+  return Object.freeze({ request(intent) {
+    if (!active) return false;
+    const sequence = ++active.sequence;
+    const request = { ...active.request, requestId: crypto.randomUUID(), ...(intent ? { schema: 'atelier-component-intent/proposal-v1', intentRef: intent.ref, payload: intent.payload } : {}) };
+    parseRequest(JSON.stringify(request)); active.pending = request;
+    active.port.postMessage(JSON.stringify({ type: 'request', nonce: active.nonce, sequence, request: JSON.stringify(request) })); return true;
+  }, dispose() { clear(); window.removeEventListener('message', receive); } });
+}

package/src/project/config.mjs

@@ -2,6 +2,7 @@ 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'
@@ -95,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) {
@@ -171,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) {
@@ -271,6 +250,7 @@ export function resolveProjectConfig({
   configArgPrefix = PROJECT_CONFIG_ARG_PREFIX,
   gitExecutable = 'git',
   configEnv = PROJECT_CONFIG_ENV,
+  writeLocalState = true,
   defaults = {},
 } = {}) {
   const argPath = projectConfigArg(argv, configArgPrefix)
@@ -387,12 +367,12 @@ export function resolveProjectConfig({
       }
     }),
   }
-  resolved.localState = ensureLocalState(resolved, { write: true, gitExecutable, env })
+  resolved.localState = ensureLocalState(resolved, { write: writeLocalState, gitExecutable, env })
   return resolved
 }
 
-export function commandProject({ argv = process.argv.slice(2), env = process.env, cwd = process.cwd(), gitExecutable = 'git' } = {}) {
-  const project = resolveProjectConfig({ argv, env, cwd, gitExecutable })
+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.
@@ -504,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']
@@ -565,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`)
@@ -573,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);
+  };
+}