@mnstry/atelier 0.2.0-alpha.12 → 0.2.0-alpha.13

package/src/commands/practice.mjs

@@ -0,0 +1,24 @@
+import { planInstructionAdoption, applyInstructionAdoption, recoverInstructionAdoption, abandonInstructionAdoption, inspectInstructionAdoption, consumeInstructionContext } from '../capabilities/instructions.mjs'
+import { reportCommandFailure, parseJsonRequest } from '../cli/command-failure.mjs'
+
+const methods = { plan: planInstructionAdoption, apply: applyInstructionAdoption, recover: recoverInstructionAdoption, abandon: abandonInstructionAdoption, status: inspectInstructionAdoption, context: consumeInstructionContext }
+const fields = {
+  plan: ['workspaceId', 'scope', 'harnessId', 'lessonId', 'target', 'slot', 'mode'],
+  apply: ['workspaceId', 'scope', 'harnessId', 'lessonId', 'target', 'slot', 'mode', 'confirm'],
+  recover: ['confirm'], abandon: ['confirm', 'destinationDigest'], status: [], context: ['target', 'slot', 'session', 'scope', 'harnessId'],
+}
+try {
+  const [command, ...rest] = process.argv.slice(2)
+  if (!methods[command] || rest.length) throw new Error('Usage: atelier practice plan|apply|recover|abandon|status|context (JSON stdin)')
+  const chunks = []; let bytes = 0
+  for await (const chunk of process.stdin) {
+    bytes += chunk.length
+    if (bytes > 256 * 1024) throw new Error('practice request exceeds limit')
+    chunks.push(chunk)
+  }
+  const body = parseJsonRequest(Buffer.concat(chunks), 'practice request')
+  if (!body || Array.isArray(body) || typeof body !== 'object' || Object.keys(body).some(k => !fields[command].includes(k))) throw new Error('invalid practice request fields')
+  console.log(JSON.stringify(methods[command]({ ...body, workspaceRoot: process.cwd() }), null, 2))
+} catch (error) {
+  reportCommandFailure(error)
+}

package/src/commands/setup.mjs

@@ -15,6 +15,14 @@ import {
 import { writeAtelierLock, loadAtelierLock, checkAtelierLock } from '../upgrade/upgrade.mjs'
 import { loadBoundaryPolicy, validateBoundaryPolicy } from '../boundary/policy.mjs'
 import { auditRepoIdentities } from '../project/repo-identity.mjs'
+import {
+  DEFAULT_ENROLLMENT_AUDIENCE,
+  assertAudienceAllowed,
+  assertEnrollmentAudience,
+  enrollmentReport,
+  planDocumentEnrollment,
+  writeDocumentEnrollment,
+} from '../graph/enroll.mjs'
 
 const PROFILE_SET = new Set(['single-repo', 'private-domain', 'shared-project', 'multi-repo', 'monorepo', 'control-workspace'])
 const IGNORE_LINES = [
@@ -190,6 +198,13 @@ function runAdopt(argv) {
   }
   const repoName = slug(firstString(args.name) || path.basename(target))
   const actor = slug(firstString(args.actor) || process.env.USER || 'owner')
+  if (typeof args['enroll-documents'] === 'string') throw new Error('--enroll-documents takes no value')
+  const enrollDocuments = args['enroll-documents'] === true
+  const audience = args.audience === undefined ? DEFAULT_ENROLLMENT_AUDIENCE : args.audience
+  if (args.audience !== undefined && !enrollDocuments) throw new Error('--audience applies only with --enroll-documents')
+  if (enrollDocuments) assertEnrollmentAudience(audience)
+  const include = firstString(args.include, args.includes)
+  const exclude = firstString(args.exclude, args.excludes)
   const projectPath = path.join(target, 'atelier.project.json')
   const existingProject = fs.existsSync(projectPath)
     ? resolveProjectConfig({ cwd: target, argv: ['--project', projectPath], writeLocalState: false }) : null
@@ -200,7 +215,7 @@ function runAdopt(argv) {
     graph: { repoAccessPath: 'repo-access.v1.json', outputPath: 'atelier-output/knowledge.graph.json' },
     projection: { outputRoot: 'atelier-output', readinessPath: 'atelier-output/atelier-readiness.json' },
     boundaries: { policyPath: 'boundary-policy.v1.json', governanceLedgerPath: 'governance/repo-boundary-ledger.md', strictNewRepos: true },
-    setup: { profile, include: firstString(args.include, args.includes) || null, exclude: firstString(args.exclude, args.excludes) || null },
+    setup: { profile, ...(include ? { include } : {}), ...(exclude ? { exclude } : {}) },
     repos: [{ name: repoName, path: '.', readBoundary: profile === 'shared-project' ? 'team' : 'private', role: profile }],
   }
   const configErrors = validateProjectConfigDoc(proposedConfig)
@@ -217,6 +232,10 @@ function runAdopt(argv) {
   const proposedPolicy = priorPolicy.ok ? priorPolicy.policy : cleanUndefined(baseBoundaryPolicy({ repoName, profile, actor }))
   const proposedPolicyErrors = validateBoundaryPolicy(proposedPolicy, proposedProject)
   if (proposedPolicyErrors.length) throw new Error(`adopt requires a valid boundary policy: ${proposedPolicyErrors.join('; ')}`)
+  // An audience the policy would refuse is refused before any scaffold write.
+  if (enrollDocuments) {
+    assertAudienceAllowed({ policy: proposedPolicy, repoNames: (proposedProject.repos ?? []).map((repo) => repo.name), audience })
+  }
   if (prior.lock) {
     const report = checkAtelierLock(existingProject)
     if (!report.ok) throw new Error(`adopt cannot accept existing lock drift: ${report.errors.join('; ')}`)
@@ -245,7 +264,8 @@ function runAdopt(argv) {
   if (!fs.existsSync(lockPath)) writeAtelierLock({ project, templateId: `adopt:${profile}` })
   const lockReport = checkAtelierLock(project)
   if (!lockReport.ok) throw new Error(`adopt lock check failed: ${lockReport.errors.join('; ')}`)
-  console.log(JSON.stringify({ ok: true, command: 'adopt', profile, target, projectPath }, null, 2))
+  const enrollment = enrollDocuments ? enrollmentReport(writeDocumentEnrollment(planDocumentEnrollment(project, { audience }))) : null
+  console.log(JSON.stringify({ ok: true, command: 'adopt', profile, target, projectPath, ...(enrollment ? { enrollment } : {}) }, null, 2))
 }
 
 function runDoctor(argv) {

package/src/commands/trackable.mjs

@@ -0,0 +1,19 @@
+import { createTrackableStore, previewTrackable, releaseTrackable } from '../trackables/store.mjs'
+import { reportCommandFailure, parseJsonRequest } from '../cli/command-failure.mjs'
+try {
+  const [command, ...rest] = process.argv.slice(2)
+  if (!['preview', 'release', 'execute', 'snapshot', 'view', 'export'].includes(command) || rest.length) throw new Error('Usage: atelier trackable preview|release|execute|snapshot|view|export (JSON stdin)')
+  const chunks = []; let length = 0
+  for await (const chunk of process.stdin) { length += chunk.length; if (length > 256 * 1024) throw new Error('request exceeds limit'); chunks.push(chunk) }
+  const input = parseJsonRequest(Buffer.concat(chunks), 'trackable request')
+  const fields = command === 'preview' ? ['definition', 'subject', 'at', 'effectiveAt', 'evidence'] : command === 'release' ? ['definition'] : ['scope', 'actor', ...(command === 'execute' ? ['command'] : command === 'view' ? ['instanceId', 'at'] : [])]
+  if (!input || Array.isArray(input) || typeof input !== 'object' || Object.keys(input).some(k => !fields.includes(k))) throw new Error('invalid trackable request fields')
+  let result
+  if (command === 'preview') result = previewTrackable(input)
+  else if (command === 'release') result = releaseTrackable(input.definition)
+  else {
+    const store = createTrackableStore({ workspaceRoot: process.cwd(), scope: input.scope, actor: input.actor })
+    result = command === 'execute' ? store.execute(input.command) : command === 'view' ? store.view({ instanceId: input.instanceId, at: input.at }) : command === 'export' ? store.exportHistory() : store.snapshot()
+  }
+  console.log(JSON.stringify(result, null, 2))
+} catch (error) { reportCommandFailure(error) }

package/src/contracts/corpus.mjs

@@ -26,8 +26,36 @@ import { fileURLToPath } from 'node:url'
 // document, not a schema, and is deliberately absent.
 
 export const CONTRACT_CORPUS = [
+  { name: 'atelier-evidence-navigation', contractFile: 'contracts/atelier-evidence-navigation.v1.schema.json', fixtureRoot: 'fixtures/evidence-navigation', registry: false },
+  { name: 'atelier-personal-workspace-manifest', contractFile: 'contracts/atelier-personal-workspace-manifest.v1.schema.json', fixtureRoot: 'fixtures/atelier-personal-workspace-contract/manifest', registry: true },
+  { name: 'atelier-personal-workspace-overlay', contractFile: 'contracts/atelier-personal-workspace-overlay.v1.schema.json', validFiles: ['fixtures/personal-workspace/overlay.json'], invalidFiles: ['authority-key.json', 'unknown-top-level-field.json', 'wrong-schema.json'].map((file) => `fixtures/atelier-personal-workspace-contract/overlay/invalid/${file}`), registry: true },
+  { name: 'atelier-template-profile', contractFile: 'contracts/atelier-template-profile.v1.schema.json', validFiles: ['fixtures/templates/local-library.v1.json'], registry: false },
+  ...['adoption-policy.v2', 'migration.v3', 'template-adoption.v1', 'upgrade-plan.v3'].map(shape => ({
+    name: `atelier-template-${shape}`, contractFile: `contracts/atelier-${shape}.schema.json`,
+    validFiles: [`fixtures/templates/upgrade-contracts/${shape}/valid.json`],
+    invalidFiles: [`fixtures/templates/upgrade-contracts/${shape}/invalid.json`], registry: false,
+  })),
   { name: 'atelier-decision-request', contractFile: 'contracts/atelier-decision-request.v1.schema.json', fixtureRoot: 'fixtures/decisions/request', registry: false },
   { name: 'atelier-decision-result', contractFile: 'contracts/atelier-decision-result.v1.schema.json', fixtureRoot: 'fixtures/decisions/result', registry: false },
+  ...Object.entries({ interaction: ['observation', 'assessment', 'act', 'policy'], coordination: ['outcome', 'dependency', 'directive', 'disposition', 'recovery'] }).flatMap(([profile, shapes]) => shapes.map(shape => ({ name: `atelier-${profile}-${shape}`, contractFile: `contracts/atelier-${profile}.v1.schema.json`, docPointer: `#/$defs/${shape}`, fixtureRoot: `fixtures/atelier-${profile}/${shape}`, registry: true }))),
+  ...['definition', 'request'].map(shape => ({ name: `atelier-trackable-${shape}`, contractFile: 'contracts/atelier-trackable.v1.schema.json', docPointer: `#/$defs/${shape}`, fixtureRoot: `fixtures/atelier-trackable/${shape}`, registry: true })),
+  ...['case', 'decision'].map(shape => ({ name: `atelier-judgment-${shape}`, contractFile: 'contracts/atelier-judgment.v1.schema.json', docPointer: `#/$defs/${shape}`, fixtureRoot: `fixtures/atelier-judgment/${shape}`, registry: false })),
+  ...['state', 'plan', 'receipt', 'context-receipt'].map(shape => ({ name: `atelier-instruction-${shape}`, contractFile: 'contracts/atelier-instruction-adoption.v1.schema.json', docPointer: `#/$defs/${shape}`, fixtureRoot: `fixtures/atelier-instruction-adoption/${shape}`, registry: false })),
+  ...['catalog', 'binding'].map(shape => ({ name: `atelier-architecture-${shape}`, contractFile: 'contracts/atelier-architecture.v1.schema.json', docPointer: `#/$defs/${shape}`, fixtureRoot: `fixtures/atelier-architecture/${shape}`, registry: false })),
+  ...Object.entries({ knowledge: ['domain', 'domain-revision', 'contribution', 'evaluation', 'relation', 'review', 'withdrawal', 'activation', 'ledger'], build: ['objective', 'candidate', 'attempt', 'progress', 'gate', 'decision', 'delivery', 'ledger'], harness: ['handoff'] }).flatMap(([profile, shapes]) => shapes.map(shape => ({
+    name: `atelier-${profile}-${shape}`, contractFile: `contracts/atelier-${profile}.v1.schema.json`,
+    docPointer: `#/$defs/${shape}`, fixtureRoot: `fixtures/atelier-${profile}-contract/${shape}`, registry: false,
+  }))),
+  ...['campaign', 'hypothesis', 'request', 'source', 'bundle', 'assessment', 'decision', 'withdrawal', 'feedback', 'legacy-assessment', 'ledger', 'handoff'].map(shape => ({
+    name: `atelier-inquiry-${shape}`, contractFile: 'contracts/atelier-inquiry.v1.schema.json',
+    docPointer: `#/$defs/${shape}`, fixtureRoot: `fixtures/atelier-inquiry-contract/${shape}`, registry: true,
+  })),
+  ...['package', 'release', 'adoption', 'state', 'plan', 'event', 'journal', 'notice'].map(shape => ({
+    name: `atelier-capability-${shape}`, contractFile: 'contracts/atelier-capability.v1.schema.json',
+    docPointer: `#/$defs/${shape}`, fixtureRoot: `fixtures/atelier-capability-contract/${shape}`, registry: false,
+  })),
+  { name: 'atelier-ingestion', contractFile: 'contracts/atelier-ingestion.v1.schema.json', fixtureRoot: 'fixtures/atelier-ingestion', registry: true },
+  { name: 'atelier-learning', contractFile: 'contracts/atelier-learning.v1.schema.json', fixtureRoot: 'fixtures/atelier-learning', registry: true },
   { name: 'atelier-adoption-policy-v1', contractFile: 'contracts/atelier-adoption-policy.v1.schema.json', fixtureRoot: 'fixtures/atelier-upgrade-transaction/adoption-policy', registry: false },
   { name: 'atelier-migration-v2', contractFile: 'contracts/atelier-migration.v2.schema.json', fixtureRoot: 'fixtures/atelier-upgrade-transaction/migration', registry: false },
   { name: 'atelier-upgrade-plan-v2', contractFile: 'contracts/atelier-upgrade-plan.v2.schema.json', fixtureRoot: 'fixtures/atelier-upgrade-transaction/upgrade-plan', registry: false },
@@ -69,6 +97,8 @@ export const CONTRACT_CORPUS = [
     fixtureRoot: 'fixtures/boundary-policy',
     registry: false,
   },
+  { name: 'atelier-boundary-delegations', contractFile: 'contracts/atelier-boundary-delegations.v1.schema.json', fixtureRoot: 'fixtures/boundary-delegations', registry: true },
+  { name: 'atelier-boundary-owner-keys', contractFile: 'contracts/atelier-boundary-owner-keys.v1.schema.json', fixtureRoot: 'fixtures/boundary-owner-keys', registry: true },
   {
     name: 'atelier-export',
     contractFile: 'contracts/atelier-export.v1.schema.json',

package/src/coordination/index.mjs

@@ -0,0 +1,110 @@
+import fs from 'node:fs'
+import Ajv from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+import { boundedLearningValue, learningDigest as digest } from '../learning/contracts.mjs'
+import { buildCoordinationProposal } from '../build/index.mjs'
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-coordination.v1.schema.json', import.meta.url)))
+const ajv = new Ajv({ strict: true, allErrors: true }); addFormats(ajv)
+const validate = ajv.compile(schema)
+const key = r => `${r.repository}/${r.id}`
+export function validateCoordination(record) {
+  try { boundedLearningValue(record) } catch (error) { return [error.message] }
+  if (!validate(record)) return validate.errors.map(e => `${e.instancePath || '/'}: ${e.message}`)
+  const errors = []
+  if (Date.parse(record.expiresAt) <= Date.parse(record.observedAt)) errors.push('expiry must follow observation')
+  if (new Set(record.scope).size !== record.scope.length || !record.scope.length) errors.push('nonempty distinct scope required')
+  if (record.kind === 'dependency' && record.body.receiving.status !== 'missing' && record.body.receiving.receipt === null) errors.push('reported receipt or acceptance needs native receipt reference')
+  if (record.kind === 'outcome') {
+    if (new Set(record.body.gates.map(g => g.id)).size !== record.body.gates.length) errors.push('duplicate gate identity')
+    if (record.body.gates.some(g => ['passed', 'waived'].includes(g.status) && g.evidence === null)) errors.push('reported passed/waived gate needs evidence')
+  }
+  if (record.kind === 'disposition' && ['sent', 'read', 'applied', 'verified'].includes(record.body.stage) && record.body.evidence === null) errors.push('reported disposition needs native evidence')
+  return errors
+}
+export function coordinationReference(record) {
+  const errors = validateCoordination(record)
+  if (errors.length) throw new Error(errors.join('; '))
+  return { repository: record.repository, id: record.id, digest: digest(record) }
+}
+export function coordinationView({ records, at, maxAgeMs = 86400000 }) {
+  if (!Array.isArray(records) || records.length > 256 || !Number.isFinite(Date.parse(at)) || !Number.isSafeInteger(maxAgeMs) || maxAgeMs < 1 || maxAgeMs > 30 * 86400000) throw new Error('bounded coordination snapshot and time required')
+  const map = new Map(), freshness = new Map()
+  for (const record of records) {
+    coordinationReference(record)
+    if (map.has(key(record))) throw new Error('ambiguous repository record identity; select an exact snapshot')
+    map.set(key(record), record)
+    const age = Date.parse(at) - Date.parse(record.observedAt)
+    freshness.set(key(record), age < 0 ? 'unknown' : Date.parse(at) >= Date.parse(record.expiresAt) || age > maxAgeMs ? 'stale' : 'current-reported')
+  }
+  const resolves = (pin, kind) => {
+    const record = map.get(key(pin))
+    return record?.kind === kind && digest(record) === pin.digest && freshness.get(key(pin)) === 'current-reported' ? record : null
+  }
+  const dependencies = [], adjacency = new Map()
+  for (const record of records.filter(r => r.kind === 'dependency')) {
+    const { producer: pin, consumer, artifactDigest, receiving } = record.body
+    const producer = resolves(pin, 'outcome'), target = map.get(key(consumer)), reasons = []
+    if (freshness.get(key(record)) !== 'current-reported') reasons.push('dependency-report-not-current')
+    if (!producer) reasons.push('producer-missing-stale-or-changed')
+    if (!target || target.kind !== 'outcome' || freshness.get(key(consumer)) !== 'current-reported') reasons.push('consumer-missing-or-stale')
+    if (producer && (producer.body.lifecycle !== 'active' || producer.body.candidate?.artifactDigest !== artifactDigest)) reasons.push('producer-artifact-unavailable')
+    if (record.repository !== consumer.repository) reasons.push('receiving-report-outside-consumer-repository')
+    if (target && (!record.scope.every(s => target.scope.includes(s)) || (producer && !record.scope.every(s => producer.scope.includes(s))))) reasons.push('dependency-scope-differs')
+    if (receiving.status !== 'accepted') reasons.push(`receiving-${receiving.status}`)
+    if (!adjacency.has(key(consumer))) adjacency.set(key(consumer), [])
+    adjacency.get(key(consumer)).push(key(pin))
+    dependencies.push({ reference: coordinationReference(record), producer: pin, consumer, receiving, reasons, nativeReceiptVerified: false })
+  }
+  // Strongly connected components (Tarjan): every dependency inside one lies on
+  // a cycle, whatever order the records arrive in.
+  const cycles = [], component = new Map(), index = new Map(), low = new Map(), stack = [], onStack = new Set()
+  let counter = 0
+  function connect(node) {
+    index.set(node, counter); low.set(node, counter++); stack.push(node); onStack.add(node)
+    for (const next of adjacency.get(node) ?? []) {
+      if (!index.has(next)) { connect(next); low.set(node, Math.min(low.get(node), low.get(next))) }
+      else if (onStack.has(next)) low.set(node, Math.min(low.get(node), index.get(next)))
+    }
+    if (low.get(node) !== index.get(node)) return
+    const members = []
+    let member
+    do { member = stack.pop(); onStack.delete(member); members.push(member) } while (member !== node)
+    if (members.length > 1 || (adjacency.get(node) ?? []).includes(node)) {
+      members.sort()
+      for (const m of members) component.set(m, cycles.length)
+      cycles.push(members)
+    }
+  }
+  for (const node of [...adjacency.keys()].sort()) if (!index.has(node)) connect(node)
+  for (const dependency of dependencies) {
+    const group = component.get(key(dependency.consumer))
+    if (group !== undefined && group === component.get(key(dependency.producer))) dependency.reasons.push('dependency-cycle')
+  }
+  const directives = records.filter(r => r.kind === 'directive').map(directive => {
+    const pin = coordinationReference(directive)
+    const replacements = records.filter(r => r.kind === 'directive' && r.body.supersedes && digest(r.body.supersedes) === digest(pin) &&
+      r.repository === directive.repository && key(r.body.target) === key(directive.body.target) && digest([...r.scope].sort()) === digest([...directive.scope].sort()))
+    // Supersession is permanent: a replacement going stale withdraws its own
+    // report, never revives the directive it replaced.
+    const superseded = replacements.length > 0
+    const reports = records.filter(r => r.kind === 'disposition' && digest(r.body.directive) === digest(pin))
+    return { reference: pin, target: directive.body.target, freshness: freshness.get(key(directive)), supersedes: directive.body.supersedes,
+      supersededBy: replacements.map(coordinationReference), activeReported: !superseded && freshness.get(key(directive)) === 'current-reported',
+      reports: reports.map(r => ({ reference: coordinationReference(r), stage: r.body.stage, evidence: r.body.evidence,
+        applicable: !superseded && freshness.get(key(r)) === 'current-reported' && freshness.get(key(directive)) === 'current-reported' && key(r.body.recipient) === key(directive.body.target) && r.repository === directive.body.target.repository && r.scope.every(s => directive.scope.includes(s)),
+        nativeReceiptVerified: false })), executionAuthorized: false }
+  })
+  const outcomes = records.filter(r => r.kind === 'outcome').map(record => ({ reference: coordinationReference(record), owner: record.body.owner, purpose: record.body.purpose,
+    priority: record.body.priority, freshness: freshness.get(key(record)), lifecycle: record.body.lifecycle, candidate: record.body.candidate,
+    gates: record.body.gates.map(g => ({ ...g, candidateCurrent: record.body.candidate !== null && g.candidateDigest === digest(record.body.candidate), nativeEvidenceVerified: false })),
+    blockers: dependencies.filter(d => key(d.consumer) === key(record)).flatMap(d => d.reasons) }))
+  const recovery = records.filter(r => r.kind === 'recovery').map(record => ({ reference: coordinationReference(record), ...record.body,
+    freshness: freshness.get(key(record)), priorPresent: !!resolves(record.body.prior, 'outcome'), successorPresent: map.get(key(record.body.successor ?? {}))?.kind === 'outcome', owningRepository: record.repository === record.body.prior.repository, executionAuthorized: false }))
+  return { schema: 'atelier-coordination-view@v1', at, maxAgeMs, coverage: records.map(coordinationReference), outcomes, dependencies, directives, recovery, cycles,
+    freshness: 'relative-to-supplied-observations', completionVerified: false, authorityTransferred: false, executionAuthorized: false }
+}
+// Retain the native Build history and its own dependency/gate qualification.
+// Additional portfolio records cannot change this result or waive its blockers.
+export function coordinatedBuild({ records, buildRecords, dependencySnapshots = [], at, maxAgeMs }) {
+  return { coordination: coordinationView({ records, at, maxAgeMs }), build: buildCoordinationProposal(buildRecords, { dependencySnapshots }), authorityTransferred: false }
+}

package/src/evidence-navigation/contracts.mjs

@@ -0,0 +1,60 @@
+import Ajv from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+import { evidenceSchema } from './schema.generated.mjs'
+
+const ajv = new Ajv({ strict: true, allErrors: true, ownProperties: true,
+  coerceTypes: false, useDefaults: false, removeAdditional: false, validateFormats: true })
+addFormats(ajv, { mode: 'full' })
+ajv.addSchema(evidenceSchema)
+const validators = new Map(Object.keys(evidenceSchema.$defs).map(name =>
+  [name, ajv.getSchema(`${evidenceSchema.$id}#/$defs/${name}`)]))
+
+export const EVIDENCE_PROTOCOL = 'atelier-evidence-navigation@v1'
+export const EVIDENCE_LIMITS = Object.freeze({ bytes: 262144, depth: 24, members: 8192, snapshots: 256, dependencyDepth: 12 })
+
+// Public functions consume JSON, never getters, cyclic graphs, or custom objects.
+// Copy before validation so no validator can mutate the caller's input.
+export function evidenceJson(value) {
+  const active = new Set()
+  let remaining = EVIDENCE_LIMITS.members
+  function copy(item, depth) {
+    if (--remaining < 0 || depth > EVIDENCE_LIMITS.depth) throw new Error('evidence value exceeds bounds')
+    if (item === null || typeof item === 'boolean') return item
+    if (typeof item === 'string' && item.length <= EVIDENCE_LIMITS.bytes && !item.includes('\u0000')) return item
+    if (typeof item === 'number' && Number.isFinite(item)) return item
+    if (typeof item !== 'object' || active.has(item)) throw new Error('evidence value must be JSON')
+    const array = Array.isArray(item)
+    const prototype = Object.getPrototypeOf(item)
+    if (array ? prototype !== Array.prototype : ![Object.prototype, null].includes(prototype)) throw new Error('evidence value must be JSON')
+    active.add(item)
+    const entries = []
+    for (const key of Reflect.ownKeys(item)) {
+      if (array && key === 'length') continue
+      const descriptor = Object.getOwnPropertyDescriptor(item, key)
+      if (typeof key !== 'string' || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) throw new Error('evidence value must be JSON')
+      entries.push([key, copy(descriptor.value, depth + 1)])
+    }
+    let result
+    if (array) {
+      const length = Object.getOwnPropertyDescriptor(item, 'length')?.value
+      if (entries.length !== length || entries.some(([key], index) => key !== String(index))) throw new Error('evidence array must be dense')
+      result = entries.map(([, value]) => value)
+    } else result = Object.fromEntries(entries)
+    active.delete(item)
+    return result
+  }
+  const result = copy(value, 0)
+  if (new TextEncoder().encode(JSON.stringify(result)).byteLength > EVIDENCE_LIMITS.bytes) throw new Error('evidence value exceeds bounds')
+  return result
+}
+
+export function validateEvidenceDocument(shape, value) {
+  if (typeof shape !== 'string') return { valid: false, reason: 'unsupported-shape' }
+  const validate = validators.get(shape)
+  if (typeof validate !== 'function') return { valid: false, reason: 'unsupported-shape' }
+  try {
+    return validate(evidenceJson(value))
+      ? { valid: true, reason: null }
+      : { valid: false, reason: 'invalid-document' }
+  } catch { return { valid: false, reason: 'invalid-document' } }
+}

package/src/evidence-navigation/evaluate.mjs

@@ -0,0 +1,69 @@
+import { EVIDENCE_LIMITS, evidenceJson, validateEvidenceDocument } from './contracts.mjs'
+
+const result = (status, reasons = []) => ({ status, reasons: [...new Set(reasons)], executionAuthorized: false, authorityTransferred: false, semanticTruthVerified: false })
+const valid = (shape, value) => validateEvidenceDocument(shape, value).valid
+const logicalKey = ref => JSON.stringify([ref.owner, ref.objectId, ref.selector.type, ref.selector.version, ref.selector.value])
+const exactRef = (a, b) => logicalKey(a) === logicalKey(b) && a.revision === b.revision && a.contentDigest === b.contentDigest
+const canonical = value => JSON.stringify(value, function (_key, item) {
+  return item && !Array.isArray(item) && typeof item === 'object'
+    ? Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]])) : item
+})
+
+/** Compare declared support. This assesses compatibility, never host qualification. */
+export function assessEvidenceCompatibility(profile, host) {
+  let input
+  try { input = evidenceJson({ profile, host }) } catch { return result('unsupported', ['invalid-document']) }
+  if (!valid('profile', input.profile) || !valid('hostCapabilities', input.host)) return result('unsupported', ['invalid-document'])
+  const reasons = []
+  if (!input.host.protocols.includes(input.profile.protocol)) reasons.push('unsupported-protocol')
+  if (input.profile.operations.some(operation => !input.host.operations.includes(operation))) reasons.push('unsupported-operation')
+  if (input.profile.requiredCapabilities.some(required => !input.host.capabilities.some(capability => capability.id === required.id && capability.version === required.version))) reasons.push('unsupported-capability')
+  return result(reasons.length ? 'unsupported' : 'compatible', reasons)
+}
+
+/** Check exact supplied snapshots. Their authenticity and read permission stay with the host. */
+export function assessEvidenceCurrency(reference, snapshots, options = {}) {
+  let input
+  try { input = evidenceJson({ reference, snapshots, options }) } catch { return result('unknown', ['invalid-document']) }
+  if (!input.options || typeof input.options !== 'object' || Array.isArray(input.options)) return result('unknown', ['invalid-document'])
+  const { at, maxDepth = EVIDENCE_LIMITS.dependencyDepth, maxNodes = EVIDENCE_LIMITS.snapshots } = input.options
+  if (!valid('evidenceRef', input.reference) || !Array.isArray(input.snapshots) || input.snapshots.length > EVIDENCE_LIMITS.snapshots ||
+      !input.snapshots.every(snapshot => valid('snapshot', snapshot)) || typeof at !== 'string' ||
+      !valid('validInterval', { from: at, until: null }) || !Number.isFinite(Date.parse(at)) ||
+      !Number.isSafeInteger(maxDepth) || maxDepth < 0 || maxDepth > EVIDENCE_LIMITS.dependencyDepth ||
+      !Number.isSafeInteger(maxNodes) || maxNodes < 1 || maxNodes > EVIDENCE_LIMITS.snapshots) return result('unknown', ['invalid-document'])
+  const index = new Map()
+  for (const snapshot of input.snapshots) {
+    const key = logicalKey(snapshot.reference)
+    index.set(key, [...(index.get(key) ?? []), snapshot])
+  }
+  let visited = 0
+  const reasons = new Set()
+  function visit(ref, path, depth) {
+    if (++visited > maxNodes || depth > maxDepth) { reasons.add('verification-bound'); return false }
+    const key = logicalKey(ref)
+    if (path.has(key)) { reasons.add('cyclic-dependency'); return false }
+    const matches = index.get(key) ?? []
+    if (matches.length !== 1) { reasons.add(matches.length ? 'ambiguous-snapshot' : 'missing-snapshot'); return false }
+    const snapshot = matches[0]
+    if (snapshot.currency !== 'current') { reasons.add(snapshot.currency === 'withdrawn-from-use' ? 'withdrawn' : 'not-current'); return false }
+    if (!exactRef(ref, snapshot.reference)) { reasons.add('changed-reference'); return false }
+    if (snapshot.validUntil !== null && !Number.isFinite(Date.parse(snapshot.validUntil))) { reasons.add('unrepresentable-expiry'); return false }
+    if (snapshot.validUntil !== null && Date.parse(at) >= Date.parse(snapshot.validUntil)) { reasons.add('expired'); return false }
+    const next = new Set(path).add(key)
+    return snapshot.dependencies.map(dependency => visit(dependency, next, depth + 1)).every(Boolean)
+  }
+  const current = visit(input.reference, new Set(), 0)
+  return result(current ? 'current' : 'not-current', [...reasons])
+}
+
+/** A later acceptance cannot change what kind of claim was recorded. */
+export function assessClaimContinuity(previous, next) {
+  let input
+  try { input = evidenceJson({ previous, next }) } catch { return result('unsupported', ['invalid-document']) }
+  if (!valid('claim', input.previous) || !valid('claim', input.next)) return result('unsupported', ['invalid-document'])
+  if (input.previous.claimId !== input.next.claimId || input.previous.ownerRecordRef.owner !== input.next.ownerRecordRef.owner || input.previous.ownerRecordRef.objectId !== input.next.ownerRecordRef.objectId) return result('unsupported', ['different-claim-identity'])
+  if (input.previous.kind !== input.next.kind) return result('unsupported', ['immutable-claim-kind'])
+  if (input.previous.revision === input.next.revision && canonical(input.previous) !== canonical(input.next)) return result('unsupported', ['unchanged-claim-revision'])
+  return result('compatible')
+}

package/src/evidence-navigation/generation.mjs

@@ -0,0 +1,22 @@
+// Generated from contracts. Run node scripts/generate-evidence-navigation.mjs.
+export const evidenceGeneration = {
+  "schema": "atelier-evidence-navigation-generation@v1",
+  "contract": "https://mnstry.ai/schemas/atelier/atelier-evidence-navigation.v1.schema.json",
+  "contractDigest": "sha256:738a93062065af4dd3f3df70ca12a6ef87b9496893e9f3df68e3bdab0fb37930",
+  "generatorVersion": 2,
+  "validator": {
+    "name": "ajv",
+    "version": "8.20.0",
+    "schemaDraft": "2020-12"
+  },
+  "formats": {
+    "name": "ajv-formats",
+    "version": "3.0.1",
+    "mode": "full"
+  },
+  "distribution": "schema-and-types-with-package-validator",
+  "files": {
+    "src/evidence-navigation/schema.generated.mjs": "sha256:553f800381b92cef8550a80a6c0f4f95d310e0a744effb7a1a45e21b31bed46c",
+    "src/evidence-navigation/types.mjs": "sha256:5b4b771657a91e739de779bae00f002feafae917b4ce73ed1d8b27efa0052e5d"
+  }
+}

package/src/evidence-navigation/index.mjs

@@ -0,0 +1,2 @@
+export { EVIDENCE_PROTOCOL, EVIDENCE_LIMITS, validateEvidenceDocument } from './contracts.mjs'
+export { assessEvidenceCompatibility, assessEvidenceCurrency, assessClaimContinuity } from './evaluate.mjs'

package/src/evidence-navigation/local.mjs

@@ -0,0 +1,167 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { performance } from 'node:perf_hooks'
+import { createIngestionStore } from '../ingestion/store.mjs'
+import { evidenceJson } from './contracts.mjs'
+
+const schema = 'atelier-local-evidence-result@v1'
+const flags = { executionAuthorized: false, authorityTransferred: false, semanticTruthVerified: false }
+const digest = text => createHash('sha256').update(text, 'utf8').digest('hex')
+const bytes = text => Buffer.byteLength(text, 'utf8')
+const refusal = reason => ({ schema, status: 'refused', reason, ...flags })
+function fail(reason = 'not-available') { throw { reason } }
+function record(input, keys) {
+  const value = evidenceJson(input)
+  if (!value || Array.isArray(value) || typeof value !== 'object' || Object.keys(value).some(key => !keys.includes(key))) fail('invalid-request')
+  return value
+}
+function positive(value, ceiling) { return Number.isSafeInteger(value) && value > 0 && value <= ceiling }
+function clip(text, ceiling) {
+  if (bytes(text) <= ceiling) return { text, truncated: false }
+  let result = '', used = 0
+  for (const character of text) {
+    const size = bytes(character)
+    if (used + size > ceiling) break
+    result += character; used += size
+  }
+  return { text: result, truncated: true }
+}
+
+/**
+ * One host-owned session over one exact, whole-plan admission. Construction
+ * options and callbacks are trusted code, never model arguments. No writes,
+ * providers, or persisted handles. A separate host must qualify actual authority.
+ */
+export function createLocalEvidenceReader({ workspaceRoot, workspaceId, plan,
+  admit, openStore = createIngestionStore, now = () => performance.now(), limits = {} } = {}) {
+  let binding, bounds, started
+  try {
+    binding = record(plan, ['planId', 'planDigest'])
+    bounds = { maxReads: 32, maxHandles: 32, maxTextBytes: 16384, maxTotalTextBytes: 65536, lifetimeMs: 60000,
+      ...record(limits, ['maxReads', 'maxHandles', 'maxTextBytes', 'maxTotalTextBytes', 'lifetimeMs']) }
+    if (!/^plan-[a-f0-9]{40}$/.test(binding.planId) || !/^sha256:[a-f0-9]{64}$/.test(binding.planDigest) ||
+      typeof workspaceRoot !== 'string' || typeof workspaceId !== 'string' ||
+      typeof admit !== 'function' || typeof openStore !== 'function' || typeof now !== 'function' ||
+      !positive(bounds.maxReads, 128) || !positive(bounds.maxHandles, 128) ||
+      !positive(bounds.maxTextBytes, 65536) || !positive(bounds.maxTotalTextBytes, 262144) ||
+      !positive(bounds.lifetimeMs, 600000)) throw new Error()
+    started = now()
+    if (!Number.isFinite(started)) throw new Error()
+  } catch { throw new Error('Invalid local evidence reader configuration') }
+  Object.freeze(binding)
+  const handles = new Map()
+  let reads = 0, releasedBytes = 0, closed = false, busy = false, lastTime = started
+  function live() {
+    const time = now()
+    if (closed || !Number.isFinite(time) || time < lastTime || time - started >= bounds.lifetimeMs) {
+      closed = true; handles.clear(); fail()
+    }
+    lastTime = time
+  }
+  function permission(operation, expected) {
+    live()
+    let decision
+    try {
+      const response = admit(Object.freeze({ operation, ...binding, readScope: 'all-plan' }))
+      let asynchronous = false
+      // Contain native Promise rejection without invoking an untrusted then getter.
+      try { Promise.prototype.then.call(response, undefined, () => {}); asynchronous = true } catch {}
+      if (asynchronous) fail()
+      decision = record(response, ['disposition', 'revision', 'readScope'])
+    }
+    catch { fail() }
+    if (decision.disposition !== 'permit' || decision.readScope !== 'all-plan' ||
+      typeof decision.revision !== 'string' || !decision.revision || decision.revision.length > 256 ||
+      (expected !== undefined && decision.revision !== expected)) fail()
+    live()
+    return decision.revision
+  }
+  function reserve(count) {
+    if (reads + count > bounds.maxReads || releasedBytes >= bounds.maxTotalTextBytes) fail('budget-exhausted')
+    reads += count // Failed reads retain their reservation; no free retries.
+  }
+  function exact(store, reference) {
+    live()
+    const value = store.getEvidence({ ...binding, ...reference })
+    if (!value || value.schema !== 'mnstry.atelier-ingestion-evidence@v1' || value.readScope !== 'all-plan' ||
+      value.planId !== binding.planId || value.planDigest !== binding.planDigest ||
+      value.sourceId !== reference.sourceId || value.sourceDigest !== reference.sourceDigest ||
+      value.attemptId !== reference.attemptId || value.locator?.kind !== reference.locator.kind ||
+      value.locator?.value !== reference.locator.value || value.freshness !== 'current' ||
+      value.integrity !== 'verified' || value.semanticAcceptance !== 'pending' || value.synthesized !== false ||
+      typeof value.text !== 'string' || bytes(value.text) > 262144) fail()
+    live()
+    return value.text
+  }
+  function execute(input, operation, body) {
+    if (busy) return refusal('not-available')
+    busy = true
+    try {
+      live()
+      let request
+      try { request = record(input, operation === 'search' ? ['query', 'limit', 'readScope'] : ['handle', 'readScope']) }
+      catch { fail('invalid-request') }
+      if (request.readScope !== undefined && request.readScope !== 'all-plan') fail('unsupported-scope')
+      return body(request)
+    } catch (error) {
+      // Never forward backend errors, path-bearing messages, or denied counts.
+      return refusal(['invalid-request', 'unsupported-scope', 'budget-exhausted'].includes(error?.reason) ? error.reason : 'not-available')
+    } finally { busy = false }
+  }
+  return Object.freeze({
+    search(input) {
+      return execute(input, 'search', request => {
+        const limit = request.limit ?? 5
+        if (typeof request.query !== 'string' || !request.query.trim() || request.query.length > 512 ||
+          bytes(request.query) > 2048 || request.query.toLowerCase().trim().split(/\s+/u).length > 32 || !positive(limit, 5)) fail('invalid-request')
+        const revision = permission('search')
+        if (handles.size + limit > bounds.maxHandles) fail('budget-exhausted')
+        reserve(1 + limit)
+        const store = openStore({ workspaceRoot, workspaceId })
+        permission('search', revision)
+        const found = store.query({ ...binding, query: request.query, limit })
+        if (!found || found.schema !== 'mnstry.atelier-ingestion-query@v1' || found.readScope !== 'all-plan' ||
+          found.planId !== binding.planId || found.planDigest !== binding.planDigest ||
+          !Array.isArray(found.hits) || found.hits.length > limit) fail()
+        const pending = [], items = []
+        let outputBytes = 0
+        for (const hit of found.hits) {
+          permission('search', revision)
+          const reference = evidenceJson({ sourceId: hit.sourceId, sourceDigest: hit.sourceDigest,
+            attemptId: hit.attemptId, locator: hit.locator })
+          // Query text is only a pointer. Exact fetch supplies every released byte.
+          const text = exact(store, reference)
+          const remaining = bounds.maxTotalTextBytes - releasedBytes - outputBytes
+          if (remaining <= 0) fail('budget-exhausted')
+          const projected = clip(text, Math.min(bounds.maxTextBytes, remaining))
+          outputBytes += bytes(projected.text)
+          const handle = randomUUID()
+          pending.push([handle, { reference, textDigest: digest(text), revision }])
+          items.push({ handle, ...projected, kind: 'source-evidence', semanticAcceptance: 'pending' })
+        }
+        permission('search', revision)
+        for (const [key, value] of pending) handles.set(key, value)
+        releasedBytes += outputBytes
+        return { schema, status: 'ok', items, coverage: 'partial', readScope: 'all-plan', ...flags }
+      })
+    },
+    get(input) {
+      return execute(input, 'get', request => {
+        if (typeof request.handle !== 'string' || request.handle.length > 64) fail('invalid-request')
+        const revision = permission('get')
+        const held = handles.get(request.handle)
+        if (!held || held.revision !== revision) fail()
+        reserve(1)
+        const store = openStore({ workspaceRoot, workspaceId })
+        permission('get', revision)
+        const text = exact(store, held.reference)
+        if (digest(text) !== held.textDigest) fail()
+        const projected = clip(text, Math.min(bounds.maxTextBytes, bounds.maxTotalTextBytes - releasedBytes))
+        permission('get', revision)
+        releasedBytes += bytes(projected.text)
+        return { schema, status: 'ok', item: { handle: request.handle, ...projected, kind: 'source-evidence', semanticAcceptance: 'pending' },
+          coverage: 'partial', readScope: 'all-plan', ...flags }
+      })
+    },
+    close() { closed = true; handles.clear() },
+  })
+}