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

package/src/projection/obsidian/selection-ui/selection-state.mjs

@@ -0,0 +1,122 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { atomicReplacePrivateText, ensureContainedPrivateDirectory, readRegularTextNoFollow } from '../../../project/private-state.mjs'
+import { canonicalJson, closedObject, compareText } from '../../../runtime/obsidian/documents.mjs'
+import { refuse } from '../../../runtime/obsidian/errors.mjs'
+import { assertOutsideRepositories } from '../../../runtime/obsidian/machine-settings.mjs'
+import { SCOPE_MODES, assertObsidianContract } from '../contracts.mjs'
+import { SETTINGS_ROOT } from '../materialize/settings.mjs'
+import { FOCUS_BOOKMARK_TYPE, FOCUS_QUERY_VERSION } from './focus.mjs'
+import { SELECTION_SCHEMA } from './selection.mjs'
+
+// Where a selector is kept: Atelier's own private state of the workspace,
+//
+//   <data>/obsidian/<workspace-id>/state/selection/<scope-id>.json
+//
+// beside the maintenance and settings documents AOP-1 keeps there, through
+// the same private-state primitives (owner-only, atomic replace, no symlink
+// following) and the same guard that keeps private state outside every
+// enrolled repository. It is not under any vault, and it is never one of the
+// files the app's UI owns under `.obsidian/`.
+
+export const SELECTION_STATE_SCHEMA = 'atelier-obsidian-selection-state/v1'
+export const SELECTION_DIRECTORY = path.join('state', 'selection')
+
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
+const DIGEST = /^sha256:[0-9a-f]{64}$/
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/
+const segment = (identifier) => identifier.replaceAll(':', '_')
+
+export function validateSelectionState(document, workspaceId) {
+  const code = 'invalid-selection-state'
+  closedObject(document, { required: ['schema', 'workspaceId', 'scopeId', 'mode', 'selector', 'expansion', 'focus', 'updatedAt'] }, code, 'the selection state')
+  if (document.schema !== SELECTION_STATE_SCHEMA) refuse(code, 'the selection state names an unknown schema')
+  if (document.workspaceId !== workspaceId) refuse(code, 'the selection state belongs to another workspace')
+  if (typeof document.scopeId !== 'string' || !IDENTIFIER.test(document.scopeId)) refuse(code, 'the selection state names no scope')
+  if (!SCOPE_MODES.includes(document.mode)) refuse(code, 'the selection state carries an unknown mode')
+  // The selector and the expansion are exactly a scope document's: the contract decides whether they are well formed.
+  assertObsidianContract('scope', { schema: 'atelier-obsidian-scope/v1', scopeId: document.scopeId, mode: document.mode, selector: document.selector, ...(document.expansion === null ? {} : { expansion: document.expansion }) })
+  if (document.focus !== null) {
+    closedObject(document.focus, { required: ['version', 'query', 'queryDigest', 'paths', 'bookmark'] }, code, 'the persisted focus')
+    if (document.focus.version !== FOCUS_QUERY_VERSION || typeof document.focus.query !== 'string' || document.focus.query === '' || !DIGEST.test(String(document.focus.queryDigest))) refuse(code, 'the persisted focus is malformed')
+    if (!Array.isArray(document.focus.paths) || document.focus.paths.length === 0 || document.focus.paths.some((item) => typeof item !== 'string')) refuse(code, 'the persisted focus names no path')
+    closedObject(document.focus.bookmark, { required: ['type', 'title', 'options'] }, code, 'the persisted bookmark payload')
+    if (document.focus.bookmark.type !== FOCUS_BOOKMARK_TYPE) refuse(code, 'the persisted bookmark payload is not a graph bookmark')
+  }
+  if (document.mode === 'focus' ? document.focus === null : document.focus !== null) refuse(code, 'a focus is persisted exactly for a focus scope')
+  if (typeof document.updatedAt !== 'string' || !TIMESTAMP.test(document.updatedAt)) refuse(code, 'updatedAt must be a UTC timestamp')
+  return document
+}
+
+// A path Atelier may write: under the workspace's private state and never under a vault's `.obsidian/`.
+export function assertWritableSelectionPath({ workspaceRoot, file }) {
+  const relative = path.relative(workspaceRoot, file)
+  if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) refuse('selection-state-outside-workspace', 'the selection state is written under the workspace private state only')
+  const parts = relative.split(path.sep)
+  if (parts.includes(SETTINGS_ROOT) || parts[0] === 'vaults') refuse('ui-owned-file-refused', 'Atelier never writes a vault or a file under .obsidian/; the app owns those')
+  if (parts.length !== 3 || parts[0] !== 'state' || parts[1] !== 'selection') refuse('selection-state-outside-workspace', 'the selection state lives in state/selection')
+  return file
+}
+
+export function selectionStateDocument({ workspaceId, selection, now }) {
+  if (selection?.schema !== SELECTION_SCHEMA) refuse('invalid-selection', 'a resolved selection is persisted, nothing else')
+  return {
+    schema: SELECTION_STATE_SCHEMA,
+    workspaceId,
+    scopeId: selection.scope.scopeId,
+    mode: selection.scope.mode,
+    selector: selection.scope.selector,
+    expansion: selection.scope.expansion ?? null,
+    focus: selection.focus === null ? null : { version: selection.focus.version, query: selection.focus.query, queryDigest: selection.focus.queryDigest, paths: selection.focus.paths, bookmark: selection.focus.bookmark },
+    updatedAt: now,
+  }
+}
+
+const selectionFile = (workspaceRoot, scopeId) => path.join(workspaceRoot, SELECTION_DIRECTORY, `${segment(scopeId)}.json`)
+
+// Writes only when the bytes change. Returns { file, changed, document }.
+export function writeSelectionState({ workspaceRoot, workspaceId, repositoryRoots, selection, now }) {
+  const document = validateSelectionState(selectionStateDocument({ workspaceId, selection, now }), workspaceId)
+  assertOutsideRepositories({ managedRoot: workspaceRoot, repositoryRoots })
+  const file = assertWritableSelectionPath({ workspaceRoot, file: selectionFile(workspaceRoot, document.scopeId) })
+  const text = canonicalJson(document)
+  let existing = null
+  try { existing = readRegularTextNoFollow(file) } catch (error) { if (error.code !== 'ENOENT') throw error }
+  // A rewrite that changes only the time is not a change to the selection.
+  if (existing !== null) {
+    let previous = null
+    try { previous = JSON.parse(existing) } catch { previous = null }
+    if (previous !== null && canonicalJson({ ...previous, updatedAt: document.updatedAt }) === text) return { file, changed: false, document: previous }
+  }
+  fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 })
+  const directory = ensureContainedPrivateDirectory({ workspaceRoot, directory: path.join(workspaceRoot, SELECTION_DIRECTORY), label: 'Obsidian selection state' })
+  atomicReplacePrivateText(path.join(directory, path.basename(file)), text)
+  return { file, changed: true, document }
+}
+
+export function readSelectionState({ workspaceRoot, workspaceId, scopeId }) {
+  if (typeof scopeId !== 'string' || !IDENTIFIER.test(scopeId)) refuse('invalid-scope', 'name the scope whose selection to read')
+  let text
+  try { text = readRegularTextNoFollow(selectionFile(workspaceRoot, scopeId)) } catch (error) {
+    if (error.code === 'ENOENT') return null
+    refuse('invalid-selection-state', 'the selection state cannot be read', { cause: error.code ?? String(error.message) })
+  }
+  let document
+  try { document = JSON.parse(text) } catch { refuse('invalid-selection-state', 'the selection state is not JSON') }
+  const validated = validateSelectionState(document, workspaceId)
+  if (validated.scopeId !== scopeId) refuse('invalid-selection-state', 'the selection state names another scope')
+  return validated
+}
+
+export function listSelectionStates({ workspaceRoot, workspaceId }) {
+  let names
+  try { names = fs.readdirSync(path.join(workspaceRoot, SELECTION_DIRECTORY)) } catch (error) { if (error.code === 'ENOENT') return []; throw error }
+  const documents = []
+  for (const name of names.filter((item) => item.endsWith('.json')).sort(compareText)) {
+    const text = readRegularTextNoFollow(path.join(workspaceRoot, SELECTION_DIRECTORY, name))
+    let document
+    try { document = JSON.parse(text) } catch { refuse('invalid-selection-state', 'a selection state is not JSON', { file: name }) }
+    documents.push(validateSelectionState(document, workspaceId))
+  }
+  return documents.sort((left, right) => compareText(left.scopeId, right.scopeId))
+}

package/src/projection/obsidian/selection-ui/selection.mjs

@@ -0,0 +1,109 @@
+import { refuse } from '../../../runtime/obsidian/errors.mjs'
+import { EXPANSION_DIRECTIONS, EXPANSION_ORDERS, MAX_EXPANSION_DEPTH, ObsidianContractRefusal, SCOPE_MODES, assertObsidianContract, selectScope } from '../contracts.mjs'
+import { allocateWorkspacePaths } from '../materialize/path-registry.mjs'
+import { buildFocusQuery, focusBookmarkPayload } from './focus.mjs'
+
+// Selection: a requested scope (full, scoped or focus, with an optional
+// bounded expansion) becomes an exact scope document, the exact selected set
+// and, for a focus, the graph query and bookmark payload derived from it.
+//
+// Selection is the contract's selectScope, unchanged: this module adds no
+// selector, no default and no fallback. An empty result is reported as
+// empty, or refused when the caller did not say empty is acceptable. It is
+// never widened. The note paths are the ones the workspace path registry
+// allocates, so a focus names the files a full vault of this workspace holds.
+
+export const SELECTION_SCHEMA = 'atelier-obsidian-selection/v1'
+export const SCOPE_CONTRACT_SCHEMA = 'atelier-obsidian-scope/v1'
+export const EMPTY_SELECTION_REASONS = Object.freeze(['explicit-empty', 'no-visible-members'])
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+// The exact document: the caller's members, the two expansion defaults the
+// contract allows filled in, and nothing else. A budget is never defaulted.
+export function scopeDocumentOf({ scopeId, mode, selector, expansion, ext } = {}) {
+  if (typeof scopeId !== 'string' || scopeId === '') refuse('invalid-scope', 'a scope names itself with a scopeId')
+  if (!SCOPE_MODES.includes(mode)) refuse('invalid-scope', 'scope mode must be full, focus or scoped', { mode: String(mode).slice(0, 32) })
+  if (!isPlainObject(selector)) refuse('invalid-scope', 'a scope carries a selector object')
+  let normalizedExpansion
+  if (expansion !== undefined && expansion !== null) {
+    if (!isPlainObject(expansion)) refuse('invalid-expansion', 'expansion must be an object')
+    if (expansion.depth === undefined || expansion.maxNodes === undefined) refuse('missing-expansion-budget', 'expansion requires both a depth and a maxNodes budget; neither is defaulted')
+    // The budgets are checked here, before the contract, so a bad budget is an expansion fault and not a generic scope fault.
+    if (!Number.isInteger(expansion.depth) || expansion.depth < 1 || expansion.depth > MAX_EXPANSION_DEPTH) refuse('invalid-expansion', `depth must be an integer from 1 to ${MAX_EXPANSION_DEPTH}`)
+    if (!Number.isInteger(expansion.maxNodes) || expansion.maxNodes < 1) refuse('invalid-expansion', 'maxNodes must be a positive integer')
+    const direction = expansion.direction ?? 'outgoing'
+    const order = expansion.order ?? 'canonical-id'
+    if (!EXPANSION_DIRECTIONS.includes(direction)) refuse('invalid-expansion', 'unknown expansion direction')
+    if (!EXPANSION_ORDERS.includes(order)) refuse('invalid-expansion', 'unknown expansion order')
+    normalizedExpansion = { depth: expansion.depth, maxNodes: expansion.maxNodes, direction, order, ...(expansion.ext === undefined ? {} : { ext: expansion.ext }) }
+  }
+  const document = {
+    schema: SCOPE_CONTRACT_SCHEMA,
+    scopeId,
+    mode,
+    selector,
+    ...(normalizedExpansion === undefined ? {} : { expansion: normalizedExpansion }),
+    ...(ext === undefined ? {} : { ext }),
+  }
+  try { assertObsidianContract('scope', document) } catch (error) {
+    if (error instanceof ObsidianContractRefusal) refuse('invalid-scope', 'the requested scope does not satisfy the scope contract', { errors: error.detail?.errors ?? [] })
+    throw error
+  }
+  return document
+}
+
+function contractRefusalToTyped(error) {
+  if (error instanceof ObsidianContractRefusal) refuse(error.code, error.message.replace(`${error.code}: `, ''), error.detail ?? {})
+  throw error
+}
+
+// `pathRegistry` is the workspace's persisted path registry when the caller
+// has one (AOP-1 keeps it in the maintenance state store); without it the
+// paths are those a fresh workspace would allocate. Both are deterministic.
+export function resolveSelection({ canonicalSnapshot, profile, scope, allowEmpty = false, pathRegistry = null, select = selectScope } = {}) {
+  const document = scopeDocumentOf(scope)
+  let result
+  try {
+    result = select({ canonicalSnapshot, profile, selector: document.selector, expansion: document.expansion, mode: document.mode })
+  } catch (error) { contractRefusalToTyped(error) }
+
+  const empty = result.nodes.length === 0
+  const emptyReason = empty ? (result.diagnostics.includes('selection-has-no-visible-members') ? 'no-visible-members' : 'explicit-empty') : null
+  if (empty && document.mode === 'focus') {
+    // A graph filter naming no note would show the whole vault or nothing, depending on the app. Neither is the request.
+    refuse('focus-selection-empty', 'the focus selects no visible note; a focus is never widened', { reason: emptyReason, unresolvedIds: result.unresolvedIds })
+  }
+  if (empty && allowEmpty !== true) refuse('selection-empty', 'the selection has no visible member; pass allowEmpty to produce an honest empty scope', { reason: emptyReason, unresolvedIds: result.unresolvedIds })
+
+  const workspaceId = typeof profile?.workspaceId === 'string' ? profile.workspaceId : 'ws-unnamed'
+  const nodeById = new Map(canonicalSnapshot.nodes.map((node) => [node.id, node]))
+  const vaultNodes = result.vaultNodes.map((id) => nodeById.get(id))
+  let pathOf
+  try { ({ pathOf } = allocateWorkspacePaths({ registry: pathRegistry, workspaceId, nodes: vaultNodes })) } catch (error) { contractRefusalToTyped(error) }
+  const notePaths = Object.fromEntries(result.nodes.map((id) => [id, pathOf(nodeById.get(id).repo, id)]))
+
+  let focus = null
+  if (document.mode === 'focus') {
+    const built = buildFocusQuery(result.nodes.map((id) => notePaths[id]))
+    focus = { ...built, bookmark: focusBookmarkPayload({ scopeId: document.scopeId, query: built.query }) }
+  }
+
+  return {
+    schema: SELECTION_SCHEMA,
+    scope: document,
+    mode: document.mode,
+    nodes: result.nodes,
+    edges: result.edges,
+    outsideSelectionEdges: result.outsideSelectionEdges,
+    vaultNodes: result.vaultNodes,
+    vaultEdges: result.vaultEdges,
+    truncated: result.truncated,
+    unresolvedIds: result.unresolvedIds,
+    diagnostics: result.diagnostics,
+    empty,
+    emptyReason,
+    notePaths,
+    focus,
+  }
+}

package/src/projection/project.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs'
+import { isDeepStrictEqual } from 'node:util'
 import path from 'node:path'
 import { commandProject, readJson, writeJson } from '../project/config.mjs'
 import { summarizeReadinessJourney } from '../readiness-protocols/runtime.mjs'
@@ -50,7 +51,7 @@ export function buildProjectProjection(project) {
   const dimensionCards = readinessJourney.dimensions.map((item) => `<article class="readiness-card" data-protocol="${esc(item.protocolId)}">
     <p class="eyebrow">${esc(item.label)}</p>
     <h3>${esc(item.title)}</h3>
-    <p><strong>${esc(item.status)}</strong> · ${esc(item.score)} / 100</p>
+    <p><strong>${esc(item.status)}</strong> · ${esc(item.score)} / 100 answers complete</p>
     <p>${esc(item.blockers[0] || 'review-ready')}</p>
     <button type="button" data-copy="${esc(item.agentPrompt)}">Copy protocol prompt</button>
   </article>`).join('\n')
@@ -93,6 +94,7 @@ ${branding.themeCss}</style>
     <div>
       <p class="eyebrow">MNSTRY Tenant Readiness</p>
       <h2 id="tenant-readiness-title">Readiness Journey</h2>
+      <p>Scores measure answer completeness, not evidence confidence, approval or runtime readiness.</p>
       <p>${esc(readinessJourney.dimensions.length)} dimensions · next protocol: ${esc(readinessJourney.nextProtocol || 'none')}</p>
     </div>
     <div class="readiness-score">${esc(readinessJourney.score)}%</div>
@@ -117,36 +119,43 @@ document.addEventListener('click', async (event) => {
   return { output, html, graph, readinessJourney }
 }
 
+export function buildProjectManifest(project, projection) {
+  return {
+    schema: 'mnstry.atelier-manifest@v1',
+    generatedAt: 'deterministic',
+    graphPath: path.relative(project.outputRoot, project.graphPath).split(path.sep).join('/'),
+    entry: 'index.html',
+    tenantReadiness: {
+      score: projection.readinessJourney.score,
+      ready: projection.readinessJourney.ready,
+      dimensions: projection.readinessJourney.dimensions.map((item) => ({
+        key: item.key,
+        protocolId: item.protocolId,
+        status: item.status,
+        score: item.score,
+      })),
+    },
+    nodes: projection.graph.nodes.map((node) => ({ id: node.id, title: node.title, audience: node.audience, path: node.path })),
+  }
+}
+
 export function runProjectCommand(argv = process.argv.slice(2)) {
   const check = argv.includes('--check')
   const project = commandProject({ argv })
   const projection = buildProjectProjection(project)
   if (check) {
     const current = fs.existsSync(projection.output) ? fs.readFileSync(projection.output, 'utf8') : null
-    if (current !== projection.html) {
+    const manifestPath = path.join(project.outputRoot, 'atelier.manifest.json')
+    let manifest = null
+    try { manifest = readJson(manifestPath) } catch { /* Missing or invalid artifacts are stale. */ }
+    if (current !== projection.html || !isDeepStrictEqual(manifest, JSON.parse(JSON.stringify(buildProjectManifest(project, projection))))) {
       console.error(`project projection is stale: ${projection.output}`)
       process.exit(1)
     }
   } else {
     fs.mkdirSync(path.dirname(projection.output), { recursive: true })
     fs.writeFileSync(projection.output, projection.html)
-    writeJson(path.join(project.outputRoot, 'atelier.manifest.json'), {
-      schema: 'mnstry.atelier-manifest@v1',
-      generatedAt: 'deterministic',
-      graphPath: project.graphPath,
-      entry: 'index.html',
-      tenantReadiness: {
-        score: projection.readinessJourney.score,
-        ready: projection.readinessJourney.ready,
-        dimensions: projection.readinessJourney.dimensions.map((item) => ({
-          key: item.key,
-          protocolId: item.protocolId,
-          status: item.status,
-          score: item.score,
-        })),
-      },
-      nodes: projection.graph.nodes.map((node) => ({ id: node.id, title: node.title, audience: node.audience, path: node.path })),
-    })
+    writeJson(path.join(project.outputRoot, 'atelier.manifest.json'), buildProjectManifest(project, projection))
   }
   console.log(`project projection: ${projection.graph.counts.nodes} nodes -> ${projection.output}`)
 }

package/src/readiness-protocols/evidence.mjs

@@ -0,0 +1,282 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { fileURLToPath } from 'node:url'
+import { canonicalize } from '../attestation/jcs.mjs'
+import { buildGraph } from '../graph/graph.mjs'
+import {
+  loadExtensionPacks,
+  createProtocolRegistry,
+} from '../extension-packs/loader.mjs'
+import { readRegularTextNoFollow } from '../project/private-state.mjs'
+import { createCollaborationEventLedger } from '../collaboration/event-ledger.mjs'
+import { inspectPackLifecycle } from '../extension-packs/lifecycle.mjs'
+import { readLocalOverlay } from '../project/config.mjs'
+import { readBoundedSource } from './source-read.mjs'
+export { readBoundedSource } from './source-read.mjs'
+import { validReviewArtifact } from '../collaboration/review-contracts.mjs'
+import { buildReadinessRun, answerForField } from './runtime.mjs'
+
+export const hashEvidence = (value) =>
+  `sha256:${crypto
+    .createHash('sha256')
+    .update(canonicalize(value))
+    .digest('hex')}`
+const hashBytes = (value) =>
+  `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`
+const packageRoot = fileURLToPath(new URL('../../', import.meta.url))
+function evaluatorInventory() {
+  const files = ['package.json']
+  function visit(relative) {
+    for (const name of fs
+      .readdirSync(path.join(packageRoot, relative))
+      .sort()) {
+      const next = path.posix.join(relative, name),
+        stat = fs.lstatSync(path.join(packageRoot, next))
+      if (stat.isSymbolicLink()) throw new Error('redirected evaluator input')
+      if (stat.isDirectory()) visit(next)
+      else if (stat.isFile() && /\.(mjs|json)$/.test(name)) files.push(next)
+    }
+  }
+  visit('src')
+  visit('contracts')
+  return files
+    .sort()
+    .map((file) => ({
+      file,
+      digest: hashBytes(readRegularTextNoFollow(path.join(packageRoot, file))),
+    }))
+}
+const evaluator = hashEvidence(evaluatorInventory())
+
+function currentInputs(project, protocolId, answers) {
+  if (
+    project.configPath &&
+    hashEvidence(JSON.parse(readRegularTextNoFollow(project.configPath))) !==
+      hashEvidence(project.config)
+  )
+    throw new Error('project config changed; resolve the project again')
+  if (hashEvidence(evaluatorInventory()) !== evaluator)
+    throw new Error('evaluator changed; restart before review')
+  if (
+    project.localOverlay &&
+    hashEvidence(readLocalOverlay({ configDir: project.configDir }).overlay) !==
+      hashEvidence(project.localOverlay.overlay)
+  )
+    throw new Error('local overlay changed; resolve again')
+  const loaded = loadExtensionPacks(project)
+  const packs = loaded.packs ?? loaded
+  const lifecycle = inspectPackLifecycle(project, packs)
+  if (!lifecycle.ok) throw new Error(lifecycle.errors.join('; '))
+  const registry = createProtocolRegistry({ packs })
+  const protocol = registry.protocolById(protocolId)
+  if (!protocol) throw new Error('protocol unavailable for evidence binding')
+  const graph = buildGraph(project)
+  if (graph.errors.length)
+    throw new Error('source graph is invalid; evidence capture refused')
+  if (graph.nodes.length > 256)
+    throw new Error('review evidence exceeds bounded source count')
+  const sources = [],
+    excerpts = new Map()
+  for (const node of graph.nodes) {
+    const repo = project.repos.find(
+      (entry) => entry.name === node.repo && !entry.external,
+    )
+    if (!repo?.path) throw new Error('source repository unavailable')
+    const source = readBoundedSource(repo.path, node.path)
+    const metadata = !/\.md$/i.test(node.path)
+      ? readBoundedSource(repo.path, `${node.path}.kg.json`).digest
+      : null
+    excerpts.set(node.id, source.text.slice(0, 2000))
+    sources.push({
+      id: node.id,
+      repo: node.repo,
+      path: node.path,
+      audience: node.audience,
+      digest: source.digest,
+      metadata,
+    })
+  }
+  sources.sort((a, b) =>
+    `${a.repo}/${a.path}`.localeCompare(`${b.repo}/${b.path}`, 'en'),
+  )
+  const claimEvidence = protocol.claimMappings.map((mapping) => {
+    const raw = answerForField(answers, mapping.evidence)
+    const references = (Array.isArray(raw) ? raw.flat(Infinity) : [raw])
+      .filter((value) => typeof value === 'string' && value.trim())
+      .map((value) => value.trim())
+    const resolved = [],
+      unresolved = []
+    for (const reference of references) {
+      const source = sources.find((item) => item.id === reference)
+      if (source)
+        resolved.push({
+          id: source.id,
+          repo: source.repo,
+          path: source.path,
+          digest: source.digest,
+          excerpt: excerpts.get(source.id),
+        })
+      else unresolved.push(reference)
+    }
+    return {
+      mappingId: mapping.id,
+      sourceFields: mapping.sourceFields,
+      answers: Object.fromEntries(
+        mapping.sourceFields.map((field) => [
+          field,
+          answerForField(answers, field) ?? null,
+        ]),
+      ),
+      evidenceField: mapping.evidence,
+      references,
+      resolved,
+      unresolved,
+      status: !references.length
+        ? 'missing'
+        : unresolved.length
+        ? 'unresolved'
+        : 'linked-source',
+    }
+  })
+  const readPolicy = (file) =>
+    fs.existsSync(file) ? hashBytes(readRegularTextNoFollow(file)) : null
+  return {
+    schema: 'atelier-review-evidence@v1',
+    protocolId,
+    protocol,
+    protocolDigest: hashEvidence(protocol),
+    answers,
+    answersDigest: hashEvidence(answers),
+    configDigest: hashEvidence(project.config),
+    lifecycleDigest: hashEvidence(lifecycle),
+    policyDigest: hashEvidence({
+      access: readPolicy(project.repoAccessPath),
+      boundary: readPolicy(project.boundaryPolicyPath),
+    }),
+    packs: packs
+      .map(({ id, version, digest }) => ({ id, version, digest }))
+      .sort((a, b) => a.id.localeCompare(b.id, 'en')),
+    evaluator: { id: 'answer-completeness/v1', digest: evaluator },
+    sources,
+    claimEvidence,
+    limitations: [
+      'Answers are operator assertions; source presence does not substantiate each claim.',
+      'No calibrated evidence confidence or runtime acceptance is established.',
+    ],
+  }
+}
+
+export function captureReviewEvidence(project, protocolId, answers) {
+  const first = currentInputs(project, protocolId, answers)
+  const second = currentInputs(project, protocolId, answers)
+  const digest = hashEvidence(first)
+  if (digest !== hashEvidence(second))
+    throw new Error('review inputs changed during capture')
+  const snapshot = { ...first, digest }
+  if (!validReviewArtifact('evidence', snapshot))
+    throw new Error('evidence contract invalid or exceeds bounds')
+  return snapshot
+}
+
+export function evidenceLedger(project) {
+  return createCollaborationEventLedger({
+    workspaceRoot: project.configDir,
+    ledgerPath: path.join(
+      project.configDir,
+      '.atelier-local/review/evidence.ndjson',
+    ),
+  })
+}
+
+export function recordReviewEvidence(project, run) {
+  const snapshot = captureReviewEvidence(project, run.protocolId, run.answers)
+  if (
+    hashEvidence(
+      buildReadinessRun({
+        project,
+        protocol: snapshot.protocol,
+        answers: run.answers,
+        createdAt: run.createdAt,
+      }),
+    ) !== hashEvidence(run)
+  )
+    throw new Error('run no longer matches its current protocol and evaluator')
+  const payload = {
+    schema: 'atelier-bound-run@v1',
+    run,
+    runDigest: hashEvidence(run),
+    snapshot,
+  }
+  if (!validBoundRun(payload)) throw new Error('bound run contract invalid')
+  const ledger = evidenceLedger(project)
+  const existing = ledger.eventsFor(run.runId)
+  if (!existing.ok) throw new Error(existing.error)
+  if (existing.events.length) {
+    if (hashEvidence(existing.events[0].payload) !== hashEvidence(payload))
+      throw new Error('run identity already has different evidence')
+    return existing.events[0].payload
+  }
+  const result = ledger.append({
+    aggregateId: run.runId,
+    expectedVersion: 0,
+    type: 'run-bound',
+    actor: 'local-runtime',
+    payload,
+  })
+  if (!result.ok) throw new Error(result.error)
+  return payload
+}
+
+export function validBoundRun(payload) {
+  if (!validReviewArtifact('bound', payload)) return false
+  const { digest, ...body } = payload.snapshot
+  const { run, snapshot } = payload
+  return (
+    payload.runDigest === hashEvidence(run) &&
+    digest === hashEvidence(body) &&
+    snapshot.protocolDigest === hashEvidence(snapshot.protocol) &&
+    snapshot.answersDigest === hashEvidence(snapshot.answers) &&
+    snapshot.answersDigest === hashEvidence(run.answers) &&
+    snapshot.protocol.id === run.protocolId &&
+    snapshot.protocolId === run.protocolId &&
+    snapshot.claimEvidence.length === run.claims.length &&
+    snapshot.claimEvidence.every(
+      (entry, index) =>
+        entry.mappingId === snapshot.protocol.claimMappings[index]?.id,
+    )
+  )
+}
+
+export function loadBoundRun(project, runId) {
+  const result = evidenceLedger(project).eventsFor(runId)
+  if (!result.ok) return result
+  if (result.events.length !== 1 || result.events[0].type !== 'run-bound')
+    return {
+      ok: false,
+      status: 409,
+      error: 'run lacks immutable review evidence',
+    }
+  const payload = result.events[0].payload
+  const { digest, ...body } = payload.snapshot ?? {}
+  if (
+    !validBoundRun(payload) ||
+    payload.schema !== 'atelier-bound-run@v1' ||
+    payload.run?.runId !== runId ||
+    payload.runDigest !== hashEvidence(payload.run) ||
+    digest !== hashEvidence(body)
+  )
+    return { ok: false, status: 422, error: 'run evidence is invalid' }
+  return { ok: true, status: 200, ...payload }
+}
+
+export function currentRunEligibility(project, bound) {
+  try {
+    return (
+      captureReviewEvidence(project, bound.run.protocolId, bound.run.answers)
+        .digest === bound.snapshot.digest
+    )
+  } catch {
+    return false
+  }
+}

package/src/readiness-protocols/runtime.mjs

@@ -73,7 +73,7 @@ function nestedAnswer(value, parts) {
   return nestedAnswer(value[head], rest)
 }
 
-function answerForField(answers, fieldId) {
+export function answerForField(answers, fieldId) {
   for (const key of pathVariants(fieldId)) {
     if (Object.hasOwn(answers, key)) return answers[key]
   }
@@ -119,9 +119,8 @@ export function claimsForProtocolRun({ protocol, answers, projectName, runId, cr
     provider: 'atelier-readiness',
     status: 'proposed',
     promoted: false,
-    confidence: Object.values(answers).some(answerPresent) ? 0.7 : 0.2,
     evidence: [`readiness-run:${runId}`],
-    notes: [`Proposed ${mapping.id} from ${protocol.title}.`],
+    notes: [`Proposed ${mapping.id} from ${protocol.title}.`, 'Answer presence is not evidence confidence; human judgment is required.'],
     createdAt,
     }
   })
@@ -147,6 +146,7 @@ export function buildReadinessRun({ project, protocol, answers = {}, createdAt =
     claims: claimsForProtocolRun({ protocol, answers: normalizedAnswers, projectName, runId, createdAt }),
     safety: {
       runtimeMutation: false,
+      runtimeImport: false,
       canonicalWrites: false,
       claimOnly: true,
       storage: 'ignored-local',
@@ -367,6 +367,7 @@ export function buildTenantPacket(project, { runs = listProtocolRuns(project), r
     ext: {
       'mnstry.atelier': {
         extensionPacks: packContribution,
+        scoreMeaning: 'Legacy readinessScore measures completed input dimensions; it is not evidence confidence or runtime admission.',
       },
     },
   }

package/src/readiness-protocols/source-read.mjs

@@ -0,0 +1,39 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { openRegularFileNoFollow } from '../project/private-state.mjs'
+const hashBytes = (value) =>
+  `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`
+
+export function readBoundedSource(root, relative) {
+  if (
+    typeof relative !== 'string' ||
+    path.isAbsolute(relative) ||
+    relative.split(/[\\/]/).some((part) => part === '..' || part === '.git')
+  )
+    throw new Error('source reference escapes declared boundary')
+  const realRoot = fs.realpathSync(root)
+  const file = path.resolve(realRoot, relative)
+  let cursor = realRoot
+  for (const part of path.relative(realRoot, file).split(path.sep)) {
+    cursor = path.join(cursor, part)
+    if (fs.lstatSync(cursor).isSymbolicLink())
+      throw new Error('redirected source reference refused')
+  }
+  const descriptor = openRegularFileNoFollow(file)
+  try {
+    const before = fs.fstatSync(descriptor)
+    if (before.size > 1024 * 1024)
+      throw new Error('source exceeds review byte bound')
+    const bytes = fs.readFileSync(descriptor)
+    const after = fs.fstatSync(descriptor)
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs)
+      throw new Error('source changed during read')
+    return {
+      digest: hashBytes(bytes),
+      text: new TextDecoder('utf-8', { fatal: true }).decode(bytes),
+    }
+  } finally {
+    fs.closeSync(descriptor)
+  }
+}