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

package/src/coauthor/session.mjs

@@ -0,0 +1,161 @@
+import { createHash } from 'node:crypto';
+import { canonicalize } from '../attestation/jcs.mjs';
+
+// Experimental adapter seam. This reducer performs no storage or authorization.
+export const COAUTHOR_SESSION_VERSION = 'atelier-coauthor-session/experimental-v1';
+export function contentDigest(text) {
+  if (typeof text !== 'string') throw new TypeError('text required');
+  if (Buffer.from(text, 'utf8').toString('utf8') !== text) throw new TypeError('text must be lossless UTF-8');
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+const digestPattern = /^[a-f0-9]{64}$/;
+function requireText(value, label) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 100000) {
+    throw new TypeError(`${label} required and bounded`);
+  }
+}
+function sourceCheck(source) {
+  if (!source || typeof source !== 'object') throw new TypeError('source required');
+  requireText(source.ref, 'source ref');
+  if (!digestPattern.test(source.digest)) throw new TypeError('source digest required');
+}
+export function createSession({ id, fields }) {
+  requireText(id, 'session id');
+  if (!Array.isArray(fields) || fields.length === 0 || fields.length > 1000) throw new TypeError('fields required');
+  const ids = new Set();
+  const targets = fields.map(({ id: fieldId, source }) => {
+    requireText(fieldId, 'field id');
+    if (ids.has(fieldId)) throw new Error('duplicate field');
+    ids.add(fieldId);
+    sourceCheck(source);
+    return { id: fieldId, source: { ref: source.ref, digest: source.digest } };
+  });
+  return { version: COAUTHOR_SESSION_VERSION, id, revision: 0, phase: 'input', index: 0,
+    fields: targets, answers: [], proposal: null, saved: [], pending: null, events: [] };
+}
+function checkEvent(event) {
+  if (!event || typeof event !== 'object' || Array.isArray(event)) throw new TypeError('event required');
+  requireText(event.id, 'event id');
+  if (!Number.isSafeInteger(event.expectedRevision) || event.expectedRevision < 0) throw new TypeError('revision required');
+  const keys = {
+    answer: ['text', 'continueAfterSave'], propose: ['text'], confirm: [], reject: [],
+    save: [], receipt: ['receipt'], failed: [], retry: [], advance: [], pause: [], resume: [],
+  }[event.type];
+  if (!keys || Object.keys(event).some(key => !['id', 'type', 'expectedRevision', ...keys].includes(key))) {
+    throw new TypeError('unknown event or field');
+  }
+  if (['answer', 'propose'].includes(event.type)) requireText(event.text, 'answer text');
+  if (event.continueAfterSave !== undefined && typeof event.continueAfterSave !== 'boolean') throw new TypeError('continue must be boolean');
+  if (event.type === 'receipt') {
+    const r = event.receipt;
+    if (!r || Object.keys(r).sort().join(',') !== 'fieldId,requestId,sessionId,sourceDigest,sourceRef,valueDigest') throw new TypeError('invalid receipt shape');
+    for (const key of ['requestId', 'sessionId', 'fieldId', 'sourceRef']) requireText(r[key], key);
+    for (const key of ['sourceDigest', 'valueDigest']) if (!digestPattern.test(r[key])) throw new TypeError('invalid receipt digest');
+  }
+}
+function need(state, phases) {
+  if (!phases.includes(state.phase)) throw new Error(`event refused in ${state.phase}`);
+}
+function writeEffect(state) {
+  const field = state.fields[state.index];
+  return { type: 'write-field', requestId: state.pending.requestId, sessionId: state.id,
+    fieldId: field.id, sourceRef: field.source.ref, sourceDigest: field.source.digest,
+    text: state.proposal.text, valueDigest: contentDigest(state.proposal.text) };
+}
+function advance(state) {
+  state.index += 1;
+  state.phase = state.index === state.fields.length ? 'complete' : 'input';
+  state.proposal = null;
+  state.pending = null;
+}
+export function transition(session, event) {
+  // State is trusted adapter-owned memory. Rehydrate by replaying validated events,
+  // not by accepting an arbitrary caller-supplied session snapshot.
+  if (session?.version !== COAUTHOR_SESSION_VERSION) throw new Error('unsupported session');
+  checkEvent(event);
+  const fingerprint = contentDigest(canonicalize(event));
+  const prior = session.events.find(item => item.id === event.id);
+  if (prior) {
+    if (prior.fingerprint !== fingerprint) throw new Error('event id conflict');
+    return { session: structuredClone(session), effects: [], duplicate: true };
+  }
+  if (event.expectedRevision !== session.revision) throw new Error('stale revision');
+  const state = structuredClone(session);
+  const effects = [];
+  switch (event.type) {
+    case 'answer':
+      need(state, ['input', 'draft']);
+      state.answers.push({ eventId: event.id, fieldId: state.fields[state.index].id, text: event.text });
+      state.proposal = { text: event.text, originalEventId: event.id, confirmed: true,
+        continueAfterSave: event.continueAfterSave ?? false };
+      state.phase = 'draft';
+      break;
+    case 'propose':
+      need(state, ['draft']);
+      // Every machine revision requires confirmation; no heuristic decides meaning.
+      state.proposal.text = event.text;
+      state.proposal.confirmed = false;
+      state.phase = 'confirmation';
+      break;
+    case 'confirm':
+      need(state, ['confirmation']);
+      state.proposal.confirmed = true;
+      state.phase = 'draft';
+      break;
+    case 'reject':
+      need(state, ['confirmation']);
+      state.proposal.text = state.answers.find(answer => answer.eventId === state.proposal.originalEventId).text;
+      state.proposal.confirmed = true;
+      state.phase = 'draft';
+      break;
+    case 'save':
+      need(state, ['draft']);
+      state.pending = { requestId: event.id, retries: 0 };
+      state.phase = 'saving';
+      effects.push(writeEffect(state));
+      break;
+    case 'failed':
+      need(state, ['saving']);
+      state.phase = 'recovery';
+      break;
+    case 'retry':
+      need(state, ['recovery']);
+      if (state.pending.retries >= 1) throw new Error('retry budget exhausted; adapter reconciliation required');
+      state.pending.retries += 1;
+      state.phase = 'saving';
+      effects.push(writeEffect(state));
+      break;
+    case 'receipt': {
+      need(state, ['saving', 'recovery']);
+      const expected = writeEffect(state);
+      for (const key of ['requestId', 'sessionId', 'fieldId', 'sourceRef', 'sourceDigest', 'valueDigest']) {
+        if (event.receipt[key] !== expected[key]) throw new Error(`receipt mismatch: ${key}`);
+      }
+      state.saved.push({ fieldId: expected.fieldId, text: state.proposal.text, receipt: structuredClone(event.receipt) });
+      state.phase = 'saved';
+      state.pending = null;
+      if (state.proposal.continueAfterSave) advance(state);
+      break;
+    }
+    case 'advance':
+      need(state, ['saved']);
+      advance(state);
+      break;
+    case 'pause':
+      need(state, ['input', 'draft', 'confirmation', 'saved', 'recovery']);
+      state.resumePhase = state.phase;
+      state.phase = 'paused';
+      break;
+    case 'resume':
+      need(state, ['paused']);
+      state.phase = state.resumePhase;
+      delete state.resumePhase;
+      break;
+  }
+  state.revision += 1;
+  state.events.push({ id: event.id, fingerprint, event: structuredClone(event) });
+  return { session: state, effects, duplicate: false };
+}
+export function replaySession(config, events) {
+  return events.reduce((session, event) => transition(session, event).session, createSession(config));
+}

package/src/coauthor/store.mjs

@@ -0,0 +1,173 @@
+import { withPrivateLock, publishPrivateFile } from '../project/durable-state.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { canonicalize } from '../attestation/jcs.mjs';
+import { createCollaborationEventLedger } from '../collaboration/event-ledger.mjs';
+import { ensureContainedPrivateDirectory, openRegularFileNoFollow } from '../project/private-state.mjs';
+import { createSession, transition, contentDigest } from './session.mjs';
+import { validateJsonSchema } from '../export/atelier-export-contract.mjs';
+
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-coauthor.v1.schema.json', import.meta.url), 'utf8'));
+function validate(value, kind) {
+  const errors = validateJsonSchema({ $schema: schema.$schema, $defs: schema.$defs, $ref: `#/$defs/${kind}` }, value);
+  if (errors.length) throw new Error(`invalid coauthor ${kind}`);
+}
+
+const MAX_SOURCE_BYTES = 1024 * 1024;
+function readText(file) {
+  const fd = openRegularFileNoFollow(file);
+  try {
+    if (fs.fstatSync(fd).size > MAX_SOURCE_BYTES) throw new Error('coauthor file exceeds byte limit');
+    return new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(fd));
+  } finally { fs.closeSync(fd); }
+}
+function sourcePath(root, ref) {
+  if (typeof ref !== 'string' || !ref || ref.includes('\\') || path.isAbsolute(ref) || ref.split('/').some(s => !s || s === '.' || s === '..' || s.startsWith('.'))) {
+    throw new Error('source must be a visible workspace-relative file');
+  }
+  let current = root;
+  for (const part of ref.split('/')) {
+    current = path.join(current, part);
+    if (fs.lstatSync(current).isSymbolicLink()) throw new Error('redirected source refused');
+  }
+  return current;
+}
+
+// Local CLI boundary, not an authenticated multi-user service. Responses remain
+// private drafts; this store never modifies a canonical source file.
+export function createCoauthorStore({ workspaceRoot = process.cwd() } = {}) {
+  const root = fs.realpathSync(workspaceRoot);
+  function privatePlacement() {
+    const gitEnv = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_')));
+    try {
+      const tracked = execFileSync('git', ['-C', root, 'ls-files', '-z', '--', '.atelier-local'], { env: gitEnv, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+      if (tracked) throw new Error('tracked private state');
+      execFileSync('git', ['-C', root, 'check-ignore', '--quiet', '.atelier-local/'], { env: gitEnv, stdio: 'ignore' });
+    } catch { throw new Error('coauthor requires a Git workspace with untracked, ignored .atelier-local/ state'); }
+  }
+  privatePlacement();
+  const directory = () => ensureContainedPrivateDirectory({ workspaceRoot: root,
+    directory: path.join(root, '.atelier-local', 'coauthor'), label: 'coauthor state' });
+  const ledger = () => createCollaborationEventLedger({ workspaceRoot: root,
+    ledgerPath: path.join(directory(), 'events.ndjson') });
+  const aggregate = id => `coauthor-${contentDigest(id)}`;
+  function locked(operation) {
+    privatePlacement();
+    const lockPath = path.join(directory(), 'operation.lock');
+    return withPrivateLock(lockPath, operation);
+  }
+  function load(id) {
+    const result = ledger().eventsFor(aggregate(id));
+    if (!result.ok) throw new Error(result.error);
+    if (!result.events.length) throw new Error('coauthor session not found');
+    let state;
+    let previous = null;
+    let version = 0;
+    let config;
+    for (const record of result.events) {
+      if (record.version !== ++version || record.payload.previousEventId !== previous) throw new Error('coauthor event chain is incomplete');
+      if (version === 1) {
+        if (record.type !== 'coauthor.started') throw new Error('coauthor start missing');
+        config = record.payload.config;
+        validate(config, 'config');
+        if (config.id !== id) throw new Error('coauthor identity mismatch');
+        state = createSession(config);
+      } else {
+        if (record.type !== 'coauthor.transition') throw new Error('unknown coauthor record');
+        const next = transition(state, record.payload.event);
+        if (next.duplicate) throw new Error('duplicate persisted transition');
+        state = next.session;
+      }
+      previous = record.id;
+    }
+    return { state, config, version, previous };
+  }
+  function verifySources(config) {
+    for (const field of config.fields) {
+      if (contentDigest(readText(sourcePath(root, field.source.ref))) !== field.source.digest) throw new Error('source changed; preserve history and start a newly bound session');
+    }
+  }
+  function append(id, current, event) {
+    const next = transition(current.state, event);
+    if (next.duplicate) return current;
+    const result = ledger().append({ aggregateId: aggregate(id), expectedVersion: current.version,
+      type: 'coauthor.transition', actor: 'local-harness', payload: { previousEventId: current.previous, event } });
+    if (!result.ok) throw new Error(result.error);
+    return { ...current, state: next.session, version: result.event.version, previous: result.event.id };
+  }
+  function reconcile(id, current) {
+    if (!['saving', 'recovery'].includes(current.state.phase)) return current;
+    verifySources(current.config);
+    const state = current.state;
+    const field = state.fields[state.index];
+    const requestId = state.pending.requestId;
+    const values = ensureContainedPrivateDirectory({ workspaceRoot: root,
+      directory: path.join(directory(), 'values', contentDigest(id)), label: 'coauthor values' });
+    const target = path.join(values, `${contentDigest(requestId)}.json`);
+    const receipt = { sessionId: id, requestId, fieldId: field.id, sourceRef: field.source.ref,
+      sourceDigest: field.source.digest, valueDigest: contentDigest(state.proposal.text) };
+    const saved = { schema: 'atelier-coauthor-draft@v1', status: 'draft', text: state.proposal.text, receipt };
+    validate(saved, 'draft');
+    const bytes = canonicalize(saved);
+    try {
+      // Existing values are immutable. A retry only verifies identical bytes.
+      try {
+        fs.lstatSync(target);
+        if (readText(target) !== bytes) throw new Error('saved draft differs from pending value');
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+        publishPrivateFile(target, bytes);
+      }
+      if (readText(target) !== bytes) throw new Error('saved draft readback mismatch');
+      verifySources(current.config);
+    } catch (error) {
+      if (state.phase === 'saving') append(id, current, {
+        id: `failure-${contentDigest(requestId)}-${state.revision}`, expectedRevision: state.revision, type: 'failed',
+      });
+      throw error;
+    }
+    return append(id, current, { id: `receipt-${contentDigest(requestId)}`,
+      expectedRevision: state.revision, type: 'receipt', receipt });
+  }
+  return {
+    start(config) {
+      return locked(() => {
+        validate(config, 'config');
+        const clean = createSession(config);
+        const canonicalConfig = { id: clean.id, fields: clean.fields };
+        verifySources(canonicalConfig);
+        const current = ledger().eventsFor(aggregate(clean.id));
+        if (!current.ok) throw new Error(current.error);
+        if (current.events.length) {
+          const existing = load(clean.id);
+          if (canonicalize(existing.config) !== canonicalize(canonicalConfig)) throw new Error('session id already bound to another configuration');
+          return existing.state;
+        }
+        const result = ledger().append({ aggregateId: aggregate(clean.id), expectedVersion: 0,
+          type: 'coauthor.started', actor: 'local-harness', payload: { previousEventId: null, config: canonicalConfig } });
+        if (!result.ok) throw new Error(result.error);
+        return load(clean.id).state;
+      });
+    },
+    read(id) { return load(id).state; },
+    dispatch(id, event) {
+      return locked(() => {
+        if (['receipt', 'failed'].includes(event?.type)) throw new Error('receipt and failure events are store-owned');
+        const current = load(id);
+        verifySources(current.config);
+        const next = append(id, current, event);
+        // Duplicate historical events never cause repeated effects.
+        if (next === current) return next.state;
+        return ['save', 'retry'].includes(event.type) ? reconcile(id, next).state : next.state;
+      });
+    },
+    recover(id) { return locked(() => {
+      const current = load(id);
+      // Paused and exhausted sessions require an explicit resume or operator
+      // reconciliation. Never turn a read into another automatic write attempt.
+      if (current.state.phase !== 'saving') return current.state;
+      return reconcile(id, current).state;
+    }); },
+  };
+}

package/src/collaboration/event-ledger.mjs

@@ -1,6 +1,7 @@
 import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
+import { withPrivateLock } from '../project/durable-state.mjs'
 import { canonicalize } from '../attestation/jcs.mjs'
 import {
   atomicReplacePrivateText,
@@ -26,18 +27,13 @@ function validTimestamp(value) {
 }
 
 function secureAppendLine(file, line) {
-  const descriptor = openRegularFileNoFollow(
-    file,
-    fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT,
-    0o600,
-  )
+  let previous = '';
   try {
-    fs.writeFileSync(descriptor, line)
-    fs.fsyncSync(descriptor)
-    fs.fchmodSync(descriptor, 0o600)
-  } finally {
-    fs.closeSync(descriptor)
-  }
+    const fd = openRegularFileNoFollow(file);
+    try { previous = fs.readFileSync(fd, 'utf8'); } finally { fs.closeSync(fd); }
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  // The ledger is bounded. Replace its complete validated prefix atomically.
+  atomicReplacePrivateText(file, previous + line);
 }
 
 function eventId(event) {
@@ -215,30 +211,12 @@ export function createCollaborationEventLedger({
   }
 
   function withWriteLock(operation) {
-    let descriptor
-    try {
-      descriptor = fs.openSync(lockPath, 'wx', 0o600)
-      fs.writeFileSync(descriptor, `${process.pid}\n`)
-      fs.fsyncSync(descriptor)
-    } catch (error) {
-      if (descriptor != null) fs.closeSync(descriptor)
-      if (error?.code === 'EEXIST') return { ok: false, status: 423, error: 'collaboration ledger is locked; retry after the active writer finishes' }
-      return { ok: false, status: 500, error: `collaboration ledger lock failed: ${error.message}` }
-    }
-    try {
-      return operation()
-    } finally {
-      fs.closeSync(descriptor)
-      try {
-        fs.unlinkSync(lockPath)
-      } catch {
-        // The completed write remains authoritative; cleanup can be diagnosed
-        // by the next writer's explicit locked result.
-      }
-    }
+    try { return withPrivateLock(lockPath, operation); }
+    catch (error) { return { ok: false, status: error.code === 'EEXIST' ? 423 : 500,
+      error: `collaboration ledger lock/write failed: ${error.message}` }; }
   }
 
-  function append({ aggregateId, expectedVersion = 0, type, actor, at = clock(), payload = {} }) {
+  function append({ aggregateId, expectedVersion = 0, type, actor, at = clock(), payload = {}, precondition = null }) {
     return withWriteLock(() => {
       const current = eventsFor(aggregateId)
       if (!current.ok) return current
@@ -249,6 +227,11 @@ export function createCollaborationEventLedger({
           error: `stale collaboration event refused: expected ${expectedVersion}, current ${current.currentVersion}`,
         }
       }
+      if (precondition !== null) {
+        if (typeof precondition !== 'function') return { ok: false, status: 400, error: 'append precondition must be a function' }
+        const permitted = precondition()
+        if (!permitted?.ok) return { ok: false, status: permitted?.status ?? 409, error: permitted?.error ?? 'append precondition refused' }
+      }
       if (current.stats.eventCount >= limits.maxEvents) {
         return { ok: false, status: 413, error: `collaboration ledger reached ${limits.maxEvents} event hard ceiling; compact it explicitly before appending` }
       }

package/src/collaboration/inspection-bundle.mjs

@@ -0,0 +1,223 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import {
+  loadBoundRun,
+  hashEvidence,
+  validBoundRun,
+} from '../readiness-protocols/evidence.mjs'
+import { validReviewArtifact } from './review-contracts.mjs'
+import { createReviewStore, validContribution } from './review-store.mjs'
+import {
+  compileDisclosurePatterns,
+  scanDisclosureText,
+} from '../disclosure/content-scan.mjs'
+import { openRegularFileNoFollow } from '../project/private-state.mjs'
+
+function prohibitedKeys(value, depth = 0) {
+  if (
+    typeof value === 'string' &&
+    (/^(?:[A-Za-z]:[\\/]|\\\\|\/(?!\/))/.test(value) ||
+      /[a-z][a-z0-9+.-]*:\/\/[^/\s]*@/i.test(value))
+  )
+    throw new Error(
+      'machine path or credential-bearing URL in selected content',
+    )
+  if (depth > 32) throw new Error('bundle nesting exceeds bounds')
+  if (value && typeof value === 'object')
+    for (const [key, child] of Object.entries(value)) {
+      if (
+        /nonce|session|grant|credential|password|token|secret|private.?key|authorization/i.test(
+          key,
+        )
+      )
+        throw new Error('nontransferable field in selected content')
+      prohibitedKeys(child, depth + 1)
+    }
+}
+export function prepareInspectionBundle(
+  project,
+  runIds,
+  { denylistDocument, responseIds = [] } = {},
+) {
+  if (!denylistDocument || !Array.isArray(denylistDocument.patterns))
+    throw new Error('private disclosure policy required before export')
+  if (
+    !Array.isArray(runIds) ||
+    !runIds.length ||
+    runIds.length > 20 ||
+    new Set(runIds).size !== runIds.length
+  )
+    throw new Error('select 1 to 20 unique run IDs')
+  const history = createReviewStore(project).records()
+  if (!history.ok) throw new Error(history.error)
+  if (
+    !Array.isArray(responseIds) ||
+    responseIds.length > 2000 ||
+    new Set(responseIds).size !== responseIds.length
+  )
+    throw new Error('invalid response selection')
+  const responses = responseIds.map((id) => {
+    const record = history.records.find(
+      (entry) =>
+        entry.input.requestId === id && entry.input.kind !== 'decision',
+    )
+    if (!record) throw new Error('selected response unavailable')
+    return record
+  })
+  prohibitedKeys(responses)
+  const members = runIds.map((id) => {
+    const bound = loadBoundRun(project, id)
+    if (!bound.ok) throw new Error(bound.error)
+    const value = {
+      schema: bound.schema,
+      run: bound.run,
+      runDigest: bound.runDigest,
+      snapshot: bound.snapshot,
+      decisions: history.records.filter(
+        (record) =>
+          record.input.kind === 'decision' && record.input.runId === id,
+      ),
+    }
+    prohibitedKeys(value)
+    return {
+      id,
+      bytes: Buffer.byteLength(JSON.stringify(value)),
+      digest: hashEvidence(value),
+      value,
+    }
+  })
+  const body = {
+    schema: 'atelier-inspection-bundle@v1',
+    purpose: 'historical-inspection-only',
+    classification: 'owner-selected-private-review',
+    members,
+    responses,
+  }
+  const bytes = JSON.stringify(body, null, 2)
+  const disclosure = scanDisclosureText(bytes, {
+    denylistPatterns: compileDisclosurePatterns(denylistDocument.patterns),
+  })
+  if (!disclosure.ok)
+    throw new Error('selected content failed disclosure policy; export refused')
+  const bundle = { ...body, digest: hashEvidence(body) }
+  inspectBundle(bundle)
+  return bundle
+}
+export function inspectBundle(bundle) {
+  const serialized = JSON.stringify(bundle)
+  if (Buffer.byteLength(serialized) > 4 * 1024 * 1024)
+    throw new Error('bundle exceeds byte bound')
+  if (!validReviewArtifact('bundle', bundle))
+    throw new Error('inspection bundle contract invalid')
+  if (
+    !bundle ||
+    bundle.schema !== 'atelier-inspection-bundle@v1' ||
+    bundle.purpose !== 'historical-inspection-only' ||
+    !Array.isArray(bundle.members) ||
+    !bundle.members.length ||
+    bundle.members.length > 20 ||
+    Object.keys(bundle).some(
+      (key) =>
+        ![
+          'schema',
+          'purpose',
+          'classification',
+          'members',
+          'responses',
+          'digest',
+          'ext',
+          'contractVersion',
+        ].includes(key),
+    )
+  )
+    throw new Error('unsupported inspection bundle')
+  const { digest, ...body } = bundle
+  if (digest !== hashEvidence(body)) throw new Error('bundle digest mismatch')
+  const ids = new Set(),
+    requests = new Set()
+  const verifyRecord = (record) => {
+    if (!validContribution(record) || requests.has(record.input.requestId))
+      throw new Error('invalid or duplicate historical contribution')
+    requests.add(record.input.requestId)
+  }
+  prohibitedKeys(bundle.responses)
+  for (const record of bundle.responses) {
+    verifyRecord(record)
+    if (record.input.kind === 'decision')
+      throw new Error('decision outside run member')
+  }
+  for (const member of bundle.members) {
+    if (
+      !member ||
+      !/^readiness-run-[a-z0-9-]+$/.test(member.id ?? '') ||
+      ids.has(member.id) ||
+      Object.keys(member).some(
+        (key) => !['id', 'bytes', 'digest', 'value', 'ext'].includes(key),
+      ) ||
+      member.digest !== hashEvidence(member.value) ||
+      member.bytes !== Buffer.byteLength(JSON.stringify(member.value))
+    )
+      throw new Error('invalid, duplicate or changed bundle member')
+    prohibitedKeys(member.value)
+    ids.add(member.id)
+    const value = member.value,
+      { digest: snapshotDigest, ...snapshot } = value.snapshot ?? {}
+    const { decisions, ...bound } = value
+    if (
+      !validBoundRun(bound) ||
+      value.schema !== 'atelier-bound-run@v1' ||
+      value.run?.runId !== member.id ||
+      value.runDigest !== hashEvidence(value.run) ||
+      snapshotDigest !== hashEvidence(snapshot) ||
+      !Array.isArray(value.decisions)
+    )
+      throw new Error('invalid historical evidence')
+    for (const record of value.decisions) {
+      verifyRecord(record)
+      if (
+        record.input.kind !== 'decision' ||
+        record.input.runId !== member.id ||
+        record.input.evidenceDigest !== snapshotDigest ||
+        !value.run.claims.some(
+          (claim) => claim.claimId === record.input.targetId,
+        )
+      )
+        throw new Error('decision does not bind selected evidence')
+    }
+  }
+  return {
+    ok: true,
+    schema: 'atelier-inspection-report@v1',
+    approvalAuthority: false,
+    authorship: 'unverified-historical-assertions',
+    writes: false,
+    members: bundle.members,
+    responses: bundle.responses,
+  }
+}
+export function readInspectionBundle(file) {
+  const descriptor = openRegularFileNoFollow(file)
+  try {
+    if (fs.fstatSync(descriptor).size > 4 * 1024 * 1024)
+      throw new Error('bundle exceeds byte bound')
+    return inspectBundle(JSON.parse(fs.readFileSync(descriptor, 'utf8')))
+  } finally {
+    fs.closeSync(descriptor)
+  }
+}
+export function writeInspectionBundle(file, bundle) {
+  inspectBundle(bundle)
+  if (path.extname(file) !== '.json')
+    throw new Error('inspection bundle output must be a JSON file')
+  const descriptor = openRegularFileNoFollow(
+    file,
+    fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL,
+    0o600,
+  )
+  try {
+    fs.writeFileSync(descriptor, JSON.stringify(bundle, null, 2) + '\n')
+    fs.fsyncSync(descriptor)
+  } finally {
+    fs.closeSync(descriptor)
+  }
+}

package/src/collaboration/review-contracts.mjs

@@ -0,0 +1,25 @@
+import fs from 'node:fs'
+import Ajv2020 from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+const ajv = new Ajv2020({ allErrors: true, strict: false })
+addFormats(ajv)
+for (const name of ['atelier-review'])
+  ajv.addSchema(
+    JSON.parse(
+      fs.readFileSync(
+        new URL(`../../contracts/${name}.v1.schema.json`, import.meta.url),
+        'utf8',
+      ),
+    ),
+  )
+const validators = new Map()
+export function validReviewArtifact(kind, value) {
+  if (!validators.has(kind))
+    validators.set(
+      kind,
+      ajv.compile({
+        $ref: `https://mnstry.ai/schemas/atelier/atelier-review.v1.schema.json#/$defs/${kind}`,
+      }),
+    )
+  return validators.get(kind)(value)
+}