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

package/src/collaboration/event-ledger.mjs

@@ -0,0 +1,348 @@
+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,
+  ensureContainedPrivateDirectory,
+  openRegularFileNoFollow,
+} from '../project/private-state.mjs'
+
+export const ATELIER_COLLABORATION_EVENT_SCHEMA = 'atelier-collaboration-event@v1'
+export const COLLABORATION_LEDGER_LIMITS = Object.freeze({
+  maxLineBytes: 256 * 1024,
+  maxBytes: 16 * 1024 * 1024,
+  maxEvents: 10_000,
+  retainPerAggregate: 50,
+  retainDays: 180,
+})
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function validTimestamp(value) {
+  return typeof value === 'string' && Number.isFinite(Date.parse(value))
+}
+
+function secureAppendLine(file, line) {
+  let previous = '';
+  try {
+    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) {
+  const authoritative = {
+    schema: event.schema,
+    aggregateId: event.aggregateId,
+    version: event.version,
+    type: event.type,
+    actor: event.actor,
+    at: event.at,
+    payload: event.payload,
+  }
+  const digest = crypto
+    .createHash('sha256')
+    .update(canonicalize(authoritative))
+    .digest('hex')
+    .slice(0, 32)
+  return `event-${digest}`
+}
+
+function boundedLimit(value, hardLimit) {
+  return Number.isFinite(value) && value > 0 ? Math.min(Math.floor(value), hardLimit) : hardLimit
+}
+
+export function validateCollaborationEvent(event) {
+  const issues = []
+  if (!isRecord(event)) return { ok: false, issues: ['event must be an object'] }
+  if (event.schema !== ATELIER_COLLABORATION_EVENT_SCHEMA) issues.push('event schema is unsupported')
+  if (typeof event.id !== 'string' || !/^event-[a-f0-9]{32}$/.test(event.id)) issues.push('event id is invalid')
+  if (typeof event.aggregateId !== 'string' || !event.aggregateId) issues.push('aggregateId is required')
+  if (!Number.isInteger(event.version) || event.version < 1) issues.push('version must be a positive integer')
+  if (typeof event.type !== 'string' || !/^[a-z][a-z0-9.-]*$/.test(event.type)) issues.push('event type is invalid')
+  if (typeof event.actor !== 'string' || !event.actor.trim()) issues.push('actor is required')
+  if (!validTimestamp(event.at)) issues.push('event timestamp is invalid')
+  if (!isRecord(event.payload)) issues.push('event payload must be an object')
+  if (
+    typeof event.id === 'string' && /^event-[a-f0-9]{32}$/.test(event.id) &&
+    typeof event.aggregateId === 'string' && event.aggregateId &&
+    Number.isInteger(event.version) && event.version > 0 &&
+    typeof event.type === 'string' && /^[a-z][a-z0-9.-]*$/.test(event.type) &&
+    typeof event.actor === 'string' && event.actor.trim() &&
+    validTimestamp(event.at) && isRecord(event.payload)
+  ) {
+    try {
+      if (event.id !== eventId(event)) issues.push('event id does not match authoritative event content')
+    } catch {
+      issues.push('authoritative event content cannot be canonicalized')
+    }
+  }
+  return issues.length === 0 ? { ok: true, value: event } : { ok: false, issues }
+}
+
+export function createCollaborationEventLedger({
+  workspaceRoot = process.cwd(),
+  ledgerPath = path.join(workspaceRoot, '.atelier-proposals', 'events.ndjson'),
+  clock = () => new Date().toISOString(),
+  maxLineBytes = COLLABORATION_LEDGER_LIMITS.maxLineBytes,
+  maxBytes = COLLABORATION_LEDGER_LIMITS.maxBytes,
+  maxEvents = COLLABORATION_LEDGER_LIMITS.maxEvents,
+} = {}) {
+  const root = fs.realpathSync(workspaceRoot)
+  const resolvedLedger = path.resolve(ledgerPath)
+  const ledgerDirReal = ensureContainedPrivateDirectory({
+    workspaceRoot,
+    directory: path.dirname(resolvedLedger),
+    label: 'collaboration ledger directory',
+  })
+  const ledgerReal = path.join(ledgerDirReal, path.basename(resolvedLedger))
+  const relative = path.relative(root, ledgerReal)
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error('collaboration ledger escapes workspace')
+  }
+
+  const limits = Object.freeze({
+    maxLineBytes: boundedLimit(maxLineBytes, COLLABORATION_LEDGER_LIMITS.maxLineBytes),
+    maxBytes: boundedLimit(maxBytes, COLLABORATION_LEDGER_LIMITS.maxBytes),
+    maxEvents: boundedLimit(maxEvents, COLLABORATION_LEDGER_LIMITS.maxEvents),
+  })
+  const lockPath = `${ledgerReal}.lock`
+
+  function failure(status, error, diagnostics = [], stats = {}) {
+    return { ok: false, status, error, events: [], diagnostics, stats }
+  }
+
+  function readAll() {
+    const startedAt = performance.now()
+    if (!fs.existsSync(ledgerReal)) {
+      return { ok: true, status: 200, events: [], diagnostics: [], stats: { bytes: 0, eventCount: 0, durationMs: performance.now() - startedAt } }
+    }
+
+    let descriptor
+    let bytes
+    try {
+      descriptor = openRegularFileNoFollow(ledgerReal, fs.constants.O_RDONLY)
+      bytes = fs.fstatSync(descriptor).size
+    } catch (error) {
+      return failure(500, `collaboration ledger cannot be inspected: ${error.message}`)
+    }
+    if (bytes > limits.maxBytes) {
+      fs.closeSync(descriptor)
+      return failure(413, `collaboration ledger exceeds ${limits.maxBytes} byte hard ceiling`, [{ code: 'ledger-byte-limit', bytes }], { bytes, eventCount: 0 })
+    }
+
+    let raw
+    try {
+      raw = fs.readFileSync(descriptor, 'utf8')
+    } catch (error) {
+      return failure(500, `collaboration ledger cannot be read: ${error.message}`, [], { bytes, eventCount: 0 })
+    } finally {
+      fs.closeSync(descriptor)
+    }
+
+    const diagnostics = []
+    const events = []
+    const versions = new Map()
+    const eventIds = new Set()
+    const lines = raw.split('\n')
+    for (let index = 0; index < lines.length; index += 1) {
+      const line = lines[index]
+      if (!line) continue
+      const lineNumber = index + 1
+      const lineBytes = Buffer.byteLength(line)
+      if (lineBytes > limits.maxLineBytes) {
+        diagnostics.push({ line: lineNumber, code: 'ledger-line-limit', message: `line exceeds ${limits.maxLineBytes} bytes` })
+        continue
+      }
+      if (events.length >= limits.maxEvents) {
+        diagnostics.push({ line: lineNumber, code: 'ledger-event-limit', message: `ledger exceeds ${limits.maxEvents} events` })
+        break
+      }
+      let event
+      try {
+        event = JSON.parse(line)
+      } catch (error) {
+        diagnostics.push({ line: lineNumber, code: 'ledger-json-invalid', message: error.message })
+        continue
+      }
+      const validation = validateCollaborationEvent(event)
+      if (!validation.ok) {
+        diagnostics.push({ line: lineNumber, code: 'ledger-event-invalid', message: validation.issues.join('; ') })
+        continue
+      }
+      if (eventIds.has(event.id)) {
+        diagnostics.push({ line: lineNumber, code: 'ledger-event-duplicate', message: `duplicate event id ${event.id}` })
+        continue
+      }
+      const previousVersion = versions.get(event.aggregateId) ?? 0
+      if (event.version <= previousVersion) {
+        diagnostics.push({ line: lineNumber, code: 'ledger-version-order', message: `version ${event.version} does not advance aggregate ${event.aggregateId}` })
+        continue
+      }
+      eventIds.add(event.id)
+      versions.set(event.aggregateId, event.version)
+      events.push(event)
+    }
+
+    const stats = { bytes, eventCount: events.length, durationMs: performance.now() - startedAt }
+    if (diagnostics.length) {
+      return { ok: false, status: 422, error: `collaboration ledger validation failed at ${diagnostics.length} line(s)`, events, diagnostics, stats }
+    }
+    return { ok: true, status: 200, events, diagnostics: [], stats }
+  }
+
+  function eventsFor(aggregateId) {
+    const id = String(aggregateId || '').trim()
+    if (!id) return failure(400, 'aggregateId is required')
+    const result = readAll()
+    if (!result.ok) return result
+    const events = result.events.filter((event) => event.aggregateId === id)
+    return {
+      ...result,
+      events,
+      currentVersion: events.at(-1)?.version ?? 0,
+    }
+  }
+
+  function withWriteLock(operation) {
+    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 = {}, precondition = null }) {
+    return withWriteLock(() => {
+      const current = eventsFor(aggregateId)
+      if (!current.ok) return current
+      if (current.currentVersion !== expectedVersion) {
+        return {
+          ok: false,
+          status: 409,
+          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` }
+      }
+      const version = current.currentVersion + 1
+      const event = {
+        schema: ATELIER_COLLABORATION_EVENT_SCHEMA,
+        aggregateId,
+        version,
+        type,
+        actor: String(actor || '').trim(),
+        at,
+        payload,
+      }
+      try {
+        event.id = eventId(event)
+      } catch {
+        return { ok: false, status: 400, error: 'authoritative event content cannot be canonicalized' }
+      }
+      const validation = validateCollaborationEvent(event)
+      if (!validation.ok) return { ok: false, status: 400, error: validation.issues.join('; ') }
+      const line = `${JSON.stringify(event)}\n`
+      const lineBytes = Buffer.byteLength(line)
+      if (lineBytes > limits.maxLineBytes) {
+        return { ok: false, status: 413, error: `collaboration event exceeds ${limits.maxLineBytes} byte line ceiling` }
+      }
+      if (current.stats.bytes + lineBytes > limits.maxBytes) {
+        return { ok: false, status: 413, error: `collaboration ledger would exceed ${limits.maxBytes} byte hard ceiling; compact it explicitly before appending` }
+      }
+      try {
+        secureAppendLine(ledgerReal, line)
+      } catch (error) {
+        return { ok: false, status: 500, error: `collaboration ledger cannot be appended: ${error.message}` }
+      }
+      return { ok: true, status: 200, event }
+    })
+  }
+
+  function materialize(aggregateId, reducer, initial = null) {
+    if (typeof reducer !== 'function') return { ok: false, status: 400, error: 'reducer is required', value: initial }
+    const result = eventsFor(aggregateId)
+    if (!result.ok) return { ...result, value: initial }
+    return {
+      ...result,
+      value: result.events.reduce((state, event) => reducer(state, event), initial),
+    }
+  }
+
+  function compact({
+    now = clock(),
+    retainPerAggregate = COLLABORATION_LEDGER_LIMITS.retainPerAggregate,
+    retainDays = COLLABORATION_LEDGER_LIMITS.retainDays,
+  } = {}) {
+    return withWriteLock(() => {
+      const current = readAll()
+      if (!current.ok) return current
+      const perAggregate = Math.max(2, boundedLimit(retainPerAggregate, COLLABORATION_LEDGER_LIMITS.retainPerAggregate))
+      const days = boundedLimit(retainDays, COLLABORATION_LEDGER_LIMITS.retainDays)
+      const cutoff = Date.parse(now) - days * 24 * 60 * 60 * 1000
+      if (!Number.isFinite(cutoff)) return { ok: false, status: 400, error: 'compaction timestamp is invalid' }
+
+      const grouped = new Map()
+      for (const event of current.events) {
+        const group = grouped.get(event.aggregateId) ?? []
+        group.push(event)
+        grouped.set(event.aggregateId, group)
+      }
+      const kept = []
+      for (const events of grouped.values()) {
+        const first = events[0]
+        const latest = events.at(-1)
+        const recent = events.filter((event) => Date.parse(event.at) >= cutoff)
+        const candidates = [first, ...recent, latest]
+        const unique = [...new Map(candidates.map((event) => [event.id, event])).values()]
+          .sort((left, right) => left.version - right.version)
+        const selected = unique.length <= perAggregate
+          ? unique
+          : [unique[0], ...unique.slice(-(perAggregate - 1))]
+        kept.push(...selected)
+      }
+      // `at` is contributor-controlled metadata and may regress. The physical
+      // ledger must retain each aggregate's causal version order after rewrite.
+      kept.sort((left, right) => (
+        left.aggregateId.localeCompare(right.aggregateId) ||
+        left.version - right.version ||
+        left.id.localeCompare(right.id)
+      ))
+      const text = kept.length ? `${kept.map((event) => JSON.stringify(event)).join('\n')}\n` : ''
+      if (Buffer.byteLength(text) > limits.maxBytes) {
+        return { ok: false, status: 413, error: 'compacted collaboration ledger still exceeds the byte hard ceiling' }
+      }
+      atomicReplacePrivateText(ledgerReal, text)
+      return {
+        ok: true,
+        status: 200,
+        before: current.events.length,
+        after: kept.length,
+        removed: current.events.length - kept.length,
+        retainPerAggregate: perAggregate,
+        retainDays: days,
+      }
+    })
+  }
+
+  return Object.freeze({
+    ledgerPath: ledgerReal,
+    lockPath,
+    limits,
+    readAll,
+    eventsFor,
+    append,
+    materialize,
+    compact,
+  })
+}

package/src/collaboration/index.mjs

@@ -0,0 +1,17 @@
+export {
+  ATELIER_COLLABORATION_EVENT_SCHEMA,
+  createCollaborationEventLedger,
+  validateCollaborationEvent,
+} from './event-ledger.mjs'
+
+export {
+  ATELIER_PROPOSAL_SCHEMA,
+  ATELIER_PROPOSALS_SCHEMA,
+  COPY_ONLY_PROPOSAL_CAPABILITY,
+  PROPOSAL_REVIEW_STATUSES,
+  acceptedProposalCopy,
+  canTransitionProposal,
+  copyOnlyActionSummary,
+  createProposalStore,
+  validateCopyOnlyProposalAuthority,
+} from './proposals.mjs'

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)
+  }
+}