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

package/src/harnesses/exchange.mjs

@@ -0,0 +1,154 @@
+import { inspectInquiry } from '../inquiry/index.mjs'
+import { inspectKnowledge } from '../knowledge/ledger.mjs'
+import { inspectBuild } from '../build/ledger.mjs'
+import { assertHandoff, contentDigest, harnessDigest, harnessRef, restrictiveAudience, HARNESS_LIMITS } from './contracts.mjs'
+import { canonical } from '../capabilities/files.mjs'
+import { createHash } from 'node:crypto'
+
+export function inspectHarness(profile, records) {
+  if (profile === 'inquiry') return inspectInquiry(records)
+  if (profile === 'knowledge') return inspectKnowledge(records)
+  if (profile === 'build') return inspectBuild(records)
+  throw new Error('unknown harness profile')
+}
+function context(dependencySnapshots = [], verificationLimit = HARNESS_LIMITS.dependencyVerifications) {
+  if (!Array.isArray(dependencySnapshots) || dependencySnapshots.length > 64) throw new Error('dependency snapshot ceiling exceeded')
+  if (!Number.isSafeInteger(verificationLimit) || verificationLimit < 1 || verificationLimit > HARNESS_LIMITS.dependencyVerifications) throw new Error('invalid dependency verification limit')
+  return { snapshots: dependencySnapshots, inspections: new Map(), verified: new Map(), verificationLimit, verificationCalls: 0, historyReplays: 0, exhausted: false }
+}
+function inspect(profile, records, ctx) {
+  if (!ctx.inspections.has(profile)) ctx.inspections.set(profile, new Map())
+  const cache = ctx.inspections.get(profile)
+  if (!cache.has(records)) { cache.set(records, inspectHarness(profile, records)); ctx.historyReplays++ }
+  return cache.get(records)
+}
+const work = ctx => ({ verificationCalls: ctx.verificationCalls, historyReplays: ctx.historyReplays, verificationLimit: ctx.verificationLimit, exhausted: ctx.exhausted })
+const bounded = depth => { if (depth > HARNESS_LIMITS.dependencyDepth) throw new Error('harness dependency depth exceeded') }
+function artifact(profile, records, subjectId, ctx, depth) {
+  bounded(depth)
+  const state = inspect(profile, records, ctx), subject = records.find(r => r.id === subjectId)
+  if (!subject || state.reconsider.some(r => r.id === subjectId)) throw new Error('handoff subject is missing or requires reconsideration')
+  let audience, context
+  if (profile === 'knowledge') {
+    if (subject.kind !== 'contribution' || !state.accepted.includes(subject.id)) throw new Error('knowledge handoff requires an accepted contribution')
+    if (knowledgeFreshness(records, ctx, depth, [subject.id]).reconsider.some(r => r.id === subject.id)) throw new Error('knowledge import requires current source snapshots')
+    const review = records.findLast(r => r.kind === 'review' && r.data.target.id === subject.id)
+    context = [state.domain, review, ...review.data.evaluations.map(pin => records.find(r => r.id === pin.id))]
+    audience = restrictiveAudience(subject.data.audience, state.domain.data.audience)
+  } else if (profile === 'inquiry') {
+    if (subject.kind !== 'decision' || subject.data.disposition !== 'accepted') throw new Error('inquiry handoff requires an accepted decision')
+    const assessment = records.find(r => r.id === subject.data.assessment.id)
+    context = [records.find(r => r.id === assessment.data.hypothesis.id), assessment]
+    audience = state.campaign.data.audience
+  } else {
+    if (subject.kind !== 'candidate' || state.candidate?.id !== subject.id || !readiness(records, ctx, depth).readyReported) throw new Error('build handoff requires current accepted candidate and fresh dependencies')
+    context = [state.establishment, state.decision, ...state.gates]
+    audience = state.establishment.data.audience
+  }
+  return { state, audience, subject, payload: JSON.stringify({ subject, context, assurance: 'caller-reported; acceptance-is-not-truth-or-authority' }) }
+}
+function create({ profile, repository, records, subjectId, target }, ctx, depth) {
+  const { state, audience, subject, payload } = artifact(profile, records, subjectId, ctx, depth)
+  if (profile !== 'inquiry' && state.establishment.data.repository !== repository) throw new Error('handoff repository differs from establishment')
+  const repositoryBinding = profile === 'inquiry' ? 'caller-declared' : 'establishment-record'
+  return assertHandoff({ schema: 'atelier-harness-handoff@v1', source: { repository, repositoryBinding, profile, run: records[0].id, historyDigest: state.head, subject: harnessRef(subject) }, target, audience, payload, payloadDigest: contentDigest(payload), assurance: 'caller-reported', authority: 'none' })
+}
+function verify({ handoff, records }, ctx, depth) {
+  bounded(depth)
+  if (ctx.verificationCalls >= ctx.verificationLimit) { ctx.exhausted = true; throw new Error('harness dependency verification budget exhausted') }
+  ctx.verificationCalls++
+  assertHandoff(handoff)
+  if (!ctx.verified.has(records)) ctx.verified.set(records, new Map())
+  const cache = ctx.verified.get(records), key = harnessDigest(handoff), prior = cache.get(key)
+  if (prior?.active) throw new Error('harness dependency cycle detected')
+  if (prior?.result) return prior.result
+  cache.set(key, { active: true })
+  try {
+    inspect(handoff.source.profile, records, ctx)
+    const hash = createHash('sha256').update('[')
+    let extendsIssuedHistory = false
+    for (let i = 0; i < records.length; i++) {
+      if (i) hash.update(',')
+      hash.update(canonical(records[i]))
+      if (`sha256:${hash.copy().update(']').digest('hex')}` === handoff.source.historyDigest) extendsIssuedHistory = true
+    }
+    if (!extendsIssuedHistory) throw new Error('handoff source history changed or diverged')
+    const current = create({ ...handoff.source, records, subjectId: handoff.source.subject.id, target: handoff.target }, ctx, depth)
+    const observedHead = current.source.historyDigest
+    current.source.historyDigest = handoff.source.historyDigest
+    if (harnessDigest(current) !== harnessDigest(handoff)) throw new Error('handoff is stale or differs from its source history')
+    const result = { current: true, historyDigest: observedHead, issuedHistoryDigest: handoff.source.historyDigest, sourceRepositoryBinding: current.source.repositoryBinding, sourceAuthenticity: 'unverified', authority: 'none' }
+    cache.set(key, { result })
+    return result
+  } finally {
+    if (cache.get(key)?.active) cache.delete(key)
+  }
+}
+function matching(h, snapshots) {
+  return snapshots.filter(s => s.repository === h.source.repository && s.profile === h.source.profile && s.records?.[0]?.id === h.source.run)
+}
+function knowledgeFreshness(records, ctx, depth, subjects = null) {
+  bounded(depth)
+  const state = inspect('knowledge', records, ctx), stale = new Map(state.reconsider.map(r => [r.id, r.reasons]))
+  const needed = subjects ? new Set(subjects) : null
+  if (needed) for (const record of [...records].reverse()) if (needed.has(record.id) && record.kind === 'contribution') for (const item of record.data.basedOn) needed.add(item.contribution.id)
+  for (const record of records) {
+    if (record.kind !== 'contribution' || record.data.origin.method !== 'exchange' || (needed && !needed.has(record.id))) continue
+    const h = record.data.origin.handoff, snapshots = matching(h, ctx.snapshots)
+    let reason
+    if (snapshots.length !== 1) reason = 'import-source-missing-or-ambiguous'
+    else try { verify({ handoff: h, records: snapshots[0].records }, ctx, depth + 1) } catch { reason = ctx.exhausted ? 'import-source-verification-budget-exhausted' : 'import-source-requires-reconsideration' }
+    if (reason) stale.set(record.id, [...(stale.get(record.id) ?? []), reason])
+  }
+  // References always point backwards, so one history-order pass propagates
+  // changes discovered in external inputs through local meaning and activation.
+  for (const record of records) {
+    const d = record.data
+    const refs = record.kind === 'contribution' ? [d.domain, ...d.basedOn.map(e => e.contribution)]
+      : record.kind === 'evaluation' ? [d.contribution]
+      : record.kind === 'relation' ? [d.domain, d.subject, d.object]
+      : record.kind === 'review' ? [d.target, ...d.evaluations]
+      : record.kind === 'activation' ? d.reviews : []
+    const reasons = refs.flatMap(pin => stale.get(pin.id) ?? [])
+    if (reasons.length) stale.set(record.id, [...new Set([...(stale.get(record.id) ?? []), ...reasons])])
+  }
+  return { historyDigest: state.head, reconsider: [...stale].map(([id, reasons]) => ({ id, reasons })), freshness: 'relative-to-explicit-snapshots', canonicalMutation: false }
+}
+function readiness(records, ctx, depth) {
+  bounded(depth)
+  const state = inspect('build', records, ctx), blockers = []
+  if (!state.candidate) blockers.push('candidate-missing')
+  if (!state.reportedAccepted) blockers.push('current-accepted-decision-missing')
+  for (const [id, a] of Object.entries(state.attempts)) if (a.candidate === state.candidate?.id && !['completed', 'failed', 'cancelled'].includes(a.state)) blockers.push(`attempt-unsettled:${id}`)
+  for (const dependency of state.establishment?.data.dependencies ?? []) {
+    const h = dependency.handoff
+    const snapshots = matching(h, ctx.snapshots)
+    if (snapshots.length !== 1) { blockers.push(`dependency-missing-or-ambiguous:${dependency.id}`); continue }
+    try { verify({ handoff: h, records: snapshots[0].records }, ctx, depth + 1) } catch { blockers.push(`${ctx.exhausted ? 'dependency-verification-budget-exhausted' : 'dependency-requires-reconsideration'}:${dependency.id}`) }
+  }
+  return { candidate: state.candidate, readyReported: blockers.length === 0, blockers, historyDigest: state.head,
+    dependencyFreshness: 'relative-to-explicit-snapshots; no-live-observation', authenticatedAcceptance: false, executionAuthorized: false }
+}
+export function createHarnessHandoff(options) { return create(options, context(options.dependencySnapshots, options.verificationLimit), 0) }
+export function verifyHarnessHandoff(options) {
+  const ctx = context(options.dependencySnapshots, options.verificationLimit)
+  return { ...verify(options, ctx, 0), dependencyWork: work(ctx) }
+}
+export function buildReadiness(records, { dependencySnapshots, verificationLimit } = {}) {
+  const ctx = context(dependencySnapshots, verificationLimit)
+  return { ...readiness(records, ctx, 0), dependencyWork: work(ctx) }
+}
+export function reconcileKnowledge(records, { dependencySnapshots, verificationLimit } = {}) {
+  const ctx = context(dependencySnapshots, verificationLimit)
+  return { ...knowledgeFreshness(records, ctx, 0), dependencyWork: work(ctx) }
+}
+
+// A read-only projection that a Fabric adapter or another coordinator can read.
+// It imports no private registry, creates no tasks and grants no dispatch power.
+export function buildCoordinationProposal(records, options = {}) {
+  const state = inspectBuild(records), readiness = buildReadiness(records, options)
+  return { schema: 'atelier-build-coordination-proposal@v1', outcome: state.establishment?.data.purpose ?? null,
+    owner: state.establishment?.data.owner ?? null, candidate: state.candidate?.data ?? null,
+    dependencies: state.establishment?.data.dependencies ?? [], gates: state.gates.map(r => ({ id: r.data.gate, status: r.data.status, evidence: r.data.evidence, record: harnessRef(r) })),
+    ...readiness, reconsider: state.reconsider, acceptedByCoordinator: false }
+}

package/src/harnesses/feedback.mjs

@@ -0,0 +1,16 @@
+import { assertDocument } from '../capabilities/package.mjs'
+import { harnessRef } from './contracts.mjs'
+import { inspectHarness } from './exchange.mjs'
+export function prepareHarnessFeedback({ profile, records, subjectId, id, outcome, cause, evidenceDigest, at, by }) {
+  const state = inspectHarness(profile, records), subject = records.find(r => r.id === subjectId)
+  if (!subject) throw new Error('feedback subject missing')
+  const atSubject = inspectHarness(profile, records.slice(0, records.indexOf(subject) + 1))
+  const binding = (atSubject.domain ?? atSubject.establishment ?? atSubject.campaign)?.data.binding
+  if (!binding) throw new Error('harness establishment has no skill binding')
+  if (!['skill', 'host', 'tool', 'configuration', 'context', 'provider', 'unknown'].includes(cause)) throw new Error('unknown feedback cause')
+  const event = { schema: 'mnstry.atelier-capability-event@v1', id, kind: 'feedback', ...binding, observer: by, outcome,
+    cause: ['context', 'provider'].includes(cause) ? 'unknown' : cause, evidenceDigest, at }
+  assertDocument(event, 'event')
+  return { event, subject: harnessRef(subject), historyDigest: state.head, reportedCause: cause,
+    causeMapping: event.cause === cause ? 'exact' : 'unsupported-steward-cause-preserved-in-wrapper', recorded: false, authority: 'none' }
+}

package/src/harnesses/history.mjs

@@ -0,0 +1,37 @@
+import { assertHarness, harnessDigest, HARNESS_LIMITS } from './contracts.mjs'
+export const unique = (items, label) => { if (new Set(items).size !== items.length) throw new Error(`duplicate ${label}`) }
+
+// Shared integrity mechanics; each domain retains its own states and meaning.
+export function replay(records, profile, firstKind, visit) {
+  if (!Array.isArray(records) || records.length > HARNESS_LIMITS.records || Buffer.byteLength(JSON.stringify(records)) > HARNESS_LIMITS.bytes) throw new Error('harness history exceeds bounds')
+  const entries = new Map(), dependencies = new Map(), stale = new Map()
+  const context = {
+    entries, stale, dependencies, first: null,
+    resolve(ref, kinds, current = true) {
+      const r = entries.get(ref.id)
+      if (!r || harnessDigest(r) !== ref.digest || !kinds.includes(r.kind)) throw new Error('missing, wrong-kind or mismatched reference')
+      if (current && stale.has(r.id)) throw new Error('reference requires reconsideration')
+      return r
+    },
+    invalidate(id, reason) {
+      const queue = [id], visited = new Set()
+      while (queue.length) {
+        const next = queue.shift(); if (visited.has(next)) continue; visited.add(next)
+        stale.set(next, [...new Set([...(stale.get(next) ?? []), reason])])
+        for (const [child, refs] of dependencies) if (refs.includes(next)) queue.push(child)
+      }
+    },
+  }
+  for (const record of records) {
+    assertHarness(record, profile)
+    if (entries.has(record.id)) throw new Error('immutable record identity already exists')
+    if (!context.first) {
+      if (record.kind !== firstKind || record.id !== record.run) throw new Error('harness establishment must be first')
+      context.first = record
+    } else if (record.run !== context.first.id || record.kind === firstKind) throw new Error('harness run mismatch')
+    const refs = visit(record, context) ?? []
+    entries.set(record.id, record); dependencies.set(record.id, [...new Set(refs)])
+    for (const target of refs) for (const reason of stale.get(target) ?? []) context.invalidate(record.id, reason)
+  }
+  return { establishment: context.first, records, head: harnessDigest(records), reconsider: [...stale].map(([id, reasons]) => ({ id, kind: entries.get(id).kind, reasons })), assurance: 'caller-reported; integrity-and-consistency-only', authority: 'none' }
+}

package/src/harnesses/index.mjs

@@ -0,0 +1,4 @@
+export { HARNESS_LIMITS, EMPTY_HARNESS_HEAD, harnessDigest, harnessRef, contentDigest, validateHarnessDocument } from './contracts.mjs'
+export { inspectHarness, createHarnessHandoff, verifyHarnessHandoff, buildReadiness, buildCoordinationProposal, reconcileKnowledge } from './exchange.mjs'
+export { appendHarness, readHarness } from './store.mjs'
+export { prepareHarnessFeedback } from './feedback.mjs'

package/src/harnesses/store.mjs

@@ -0,0 +1,29 @@
+import { jsonAt, replaceJson, stat, within, workspaceRoot } from '../capabilities/files.mjs'
+import { withOperationLock } from '../capabilities/adoption.mjs'
+import { assertHarness, EMPTY_HARNESS_HEAD, HARNESS_LIMITS } from './contracts.mjs'
+import { inspectHarness } from './exchange.mjs'
+function location(profile, run) {
+  if (!['knowledge', 'build'].includes(profile) || !/^[a-z][a-z0-9-]{0,63}$/.test(run ?? '')) throw new Error('invalid stored harness profile or run')
+  return `.atelier-local/harnesses/${profile}/${run}/ledger.json`
+}
+function read(root, profile, run) {
+  const file = location(profile, run)
+  if (!stat(within(root, file))) return inspectHarness(profile, [])
+  const ledger = assertHarness(jsonAt(root, file), profile, 'ledger'), state = inspectHarness(profile, ledger.records)
+  if (ledger.head !== state.head || state.establishment.id !== run) throw new Error('harness ledger integrity mismatch')
+  return state
+}
+export function readHarness({ workspaceRoot: root, profile, run }) { return read(workspaceRoot(root), profile, run) }
+export function appendHarness({ workspaceRoot: input, profile, record, confirm }) {
+  assertHarness(record, profile)
+  const root = workspaceRoot(input, { write: true })
+  return withOperationLock(root, () => {
+    const before = read(root, profile, record.run)
+    if ((before.head ?? EMPTY_HARNESS_HEAD) !== confirm) throw new Error('append requires current harness history digest')
+    const state = inspectHarness(profile, [...before.records, record])
+    const ledger = { schema: 'atelier-harness-ledger@v1', profile, records: state.records, head: state.head }
+    if (Buffer.byteLength(JSON.stringify(ledger, null, 2)) + 1 > HARNESS_LIMITS.bytes) throw new Error('serialized harness ledger exceeds bounds')
+    replaceJson(root, location(profile, record.run), ledger)
+    return { recorded: record.id, head: state.head, reconsider: state.reconsider, authority: 'none' }
+  })
+}

package/src/ingestion/contracts.mjs

@@ -0,0 +1,41 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { canonicalize } from '../attestation/jcs.mjs';
+
+export const INGESTION_MAX_PLAN_BYTES = 256 * 1024;
+export const INGESTION_MAX_EVIDENCE_ITEMS = 2000;
+export const ingestionSchema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-ingestion.v1.schema.json', import.meta.url), 'utf8'));
+const ajv = new Ajv2020({ allErrors: false, strict: false }); addFormats(ajv); ajv.addSchema(ingestionSchema);
+const validators = new Map();
+export function ingestionDigest(value) { return `sha256:${createHash('sha256').update(canonicalize(value)).digest('hex')}`; }
+export function validateIngestionValue(definition, value) {
+  if (!Object.hasOwn(ingestionSchema.$defs, definition)) return ['unknown ingestion definition'];
+  if (!validators.has(definition)) validators.set(definition, ajv.getSchema(`${ingestionSchema.$id}#/$defs/${definition}`));
+  return validators.get(definition)(value) ? [] : ['ingestion document does not match its contract'];
+}
+export function ingestionJson(value) {
+  const seen = new Set();
+  function visit(item, depth = 0) {
+    if (depth > 24) throw new Error('ingestion JSON depth exceeded');
+    if (item === null || typeof item === 'boolean') return;
+    if (typeof item === 'string') { if (item.includes('\u0000')) throw new Error('invalid ingestion text'); return; }
+    if (typeof item === 'number' && Number.isFinite(item)) return;
+    if (typeof item !== 'object' || seen.has(item) || (!Array.isArray(item) && ![null, Object.prototype].includes(Object.getPrototypeOf(item)))) throw new Error('ingestion input must be plain JSON');
+    seen.add(item);
+    if (Reflect.ownKeys(item).length > 4096) throw new Error('ingestion member ceiling exceeded');
+    for (const key of Reflect.ownKeys(item)) {
+      if (Array.isArray(item) && key === 'length') continue;
+      const descriptor = Object.getOwnPropertyDescriptor(item, key);
+      if (typeof key !== 'string' || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) throw new Error('ingestion input must be plain JSON');
+      visit(descriptor.value, depth + 1);
+    }
+    if (Array.isArray(item) && Object.keys(item).length !== item.length) throw new Error('ingestion arrays must be dense');
+    seen.delete(item);
+  }
+  visit(value);
+  const text = canonicalize(value);
+  if (Buffer.byteLength(text) > INGESTION_MAX_PLAN_BYTES) throw new Error('ingestion document byte ceiling exceeded');
+  return JSON.parse(text);
+}

package/src/ingestion/evaluation.mjs

@@ -0,0 +1,119 @@
+import { createHash } from 'node:crypto'
+
+const digest = value => `sha256:${createHash('sha256').update(JSON.stringify(value)).digest('hex')}`
+const invalid = () => { throw new Error('invalid ingestion evaluation document') }
+function object(value, keys, required = keys) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).some(key => !keys.includes(key))
+    || required.some(key => !Object.hasOwn(value, key))) invalid()
+}
+function text(value, max = 512) { if (typeof value !== 'string' || !value.trim() || value.length > max) invalid() }
+function count(value) { if (!Number.isSafeInteger(value) || value < 0) invalid() }
+function measure(value) { if (value !== null && (!Number.isFinite(value) || value < 0)) invalid() }
+function evidence(items) {
+  if (!Array.isArray(items) || items.length > 10000) invalid()
+  for (const item of items) {
+    object(item, ['locator', 'text']); object(item.locator, ['kind', 'value'])
+    if (!['line', 'csv-cell', 'json-pointer'].includes(item.locator.kind)) invalid()
+    if (typeof item.locator.value !== 'string' || item.locator.value.length > 2048
+      || typeof item.text !== 'string' || item.text.length > 65536) invalid()
+  }
+}
+function key(item) { return JSON.stringify([item.locator.kind, item.locator.value, item.text]) }
+function score(expected, actual) {
+  const remaining = new Map()
+  for (const item of expected) remaining.set(key(item), (remaining.get(key(item)) ?? 0) + 1)
+  let matched = 0
+  for (const item of actual) {
+    const k = key(item)
+    if (remaining.get(k) > 0) { matched++; remaining.set(k, remaining.get(k) - 1) }
+  }
+  return { expected: expected.length, returned: actual.length, matched,
+    missed: expected.length - matched, unexpected: actual.length - matched }
+}
+
+/** Score exact structural evidence against a predeclared local suite. This does
+ * not judge semantic support, authenticate supplied human assessments, execute a
+ * provider or grant model qualification. Unknown costs remain unknown. */
+export function evaluateIngestionTrial({ suite, trial }) {
+  let serialized
+  try { serialized = JSON.stringify({ suite, trial }) } catch { invalid() }
+  if (!serialized || Buffer.byteLength(serialized) > 4 * 1024 * 1024) invalid()
+  object(suite, ['id', 'revision', 'thresholds', 'cases'])
+  text(suite.id); text(suite.revision)
+  object(suite.thresholds, ['minimumRecall', 'maximumUnexpected', 'maximumFailed'])
+  if (!Number.isFinite(suite.thresholds.minimumRecall) || suite.thresholds.minimumRecall < 0
+    || suite.thresholds.minimumRecall > 1) invalid()
+  count(suite.thresholds.maximumUnexpected); count(suite.thresholds.maximumFailed)
+  if (!Array.isArray(suite.cases) || !suite.cases.length || suite.cases.length > 256) invalid()
+  const ids = new Set()
+  for (const item of suite.cases) {
+    object(item, ['id', 'stratum', 'split', 'sourceDigest', 'expected'])
+    text(item.id); text(item.stratum)
+    if (ids.has(item.id) || !['calibration', 'held-out'].includes(item.split)
+      || !/^sha256:[0-9a-f]{64}$/.test(item.sourceDigest)) invalid()
+    ids.add(item.id); evidence(item.expected)
+  }
+  object(trial, ['id', 'suiteDigest', 'processor', 'currency', 'outcomes'])
+  text(trial.id)
+  if (trial.suiteDigest !== digest(suite)) throw new Error('evaluation suite digest mismatch')
+  object(trial.processor, ['id', 'version', 'configurationDigest'])
+  text(trial.processor.id); text(trial.processor.version)
+  if (!/^sha256:[0-9a-f]{64}$/.test(trial.processor.configurationDigest)
+    || !/^[A-Z]{3}$/.test(trial.currency)) invalid()
+  if (!Array.isArray(trial.outcomes) || trial.outcomes.length > suite.cases.length) invalid()
+  const outcomes = new Map()
+  for (const item of trial.outcomes) {
+    object(item, ['caseId', 'sourceDigest', 'status', 'evidence', 'attempts', 'elapsedMs', 'cost', 'humanAssessment'])
+    if (!ids.has(item.caseId) || outcomes.has(item.caseId)
+      || !['complete', 'failed', 'uncertain'].includes(item.status)) invalid()
+    if (item.sourceDigest !== suite.cases.find(c => c.id === item.caseId).sourceDigest) {
+      throw new Error('evaluation source digest mismatch')
+    }
+    evidence(item.evidence); count(item.attempts); measure(item.elapsedMs); measure(item.cost)
+    if (item.attempts < 1 || (item.status !== 'complete' && item.evidence.length)) invalid()
+    if (item.humanAssessment !== null) {
+      object(item.humanAssessment, ['verdict', 'actorId', 'evidenceRef'])
+      if (!['accepted', 'rejected', 'deferred'].includes(item.humanAssessment.verdict)) invalid()
+      text(item.humanAssessment.actorId); text(item.humanAssessment.evidenceRef)
+      if (item.humanAssessment.verdict === 'accepted' && item.status !== 'complete') invalid()
+    }
+    outcomes.set(item.caseId, item)
+  }
+  const cases = suite.cases.map(item => {
+    const outcome = outcomes.get(item.id)
+    return { caseId: item.id, stratum: item.stratum, split: item.split,
+      status: outcome?.status ?? 'missing', ...score(item.expected, outcome?.evidence ?? []),
+      attempts: outcome?.attempts ?? null, elapsedMs: outcome?.elapsedMs ?? null,
+      cost: outcome?.cost ?? null, humanVerdict: outcome?.humanAssessment?.verdict ?? 'unassessed' }
+  })
+  function summarize(rows) {
+    const totals = { cases: rows.length, expected: 0, returned: 0, matched: 0, missed: 0, unexpected: 0, failed: 0 }
+    for (const row of rows) {
+      for (const k of ['expected', 'returned', 'matched', 'missed', 'unexpected']) totals[k] += row[k]
+      if (row.status !== 'complete') totals.failed++
+    }
+    const recall = totals.expected ? totals.matched / totals.expected : null
+    // A zero-evidence sample cannot establish extraction recall.
+    const passed = recall !== null && recall >= suite.thresholds.minimumRecall
+      && totals.unexpected <= suite.thresholds.maximumUnexpected && totals.failed <= suite.thresholds.maximumFailed
+    return { ...totals, recall, passed }
+  }
+  const strata = [...new Set(cases.filter(c => c.split === 'held-out').map(c => c.stratum))]
+    .map(stratum => ({ stratum, ...summarize(cases.filter(c => c.split === 'held-out' && c.stratum === stratum)) }))
+  const heldOut = summarize(cases.filter(c => c.split === 'held-out'))
+  const accepted = cases.filter(c => c.humanVerdict === 'accepted').length
+  const unknownCostCases = cases.filter(c => c.cost === null).length
+  const knownCost = cases.reduce((total, c) => total + (c.cost ?? 0), 0)
+  if (!Number.isFinite(knownCost)) throw new Error('evaluation cost total exceeds numeric bounds')
+  const totalCost = unknownCostCases ? null : knownCost
+  return { schema: 'mnstry.atelier-ingestion-evaluation@v1', suiteDigest: digest(suite),
+    trialDigest: digest(trial), processor: structuredClone(trial.processor), cases,
+    calibration: summarize(cases.filter(c => c.split === 'calibration')), heldOut, strata,
+    structuralThresholdsPassed: heldOut.passed && strata.length > 0 && strata.every(s => s.passed),
+    costs: { currency: trial.currency, knownCost, unknownCostCases, totalCost, acceptedResults: accepted,
+      costPerAcceptedResult: accepted && totalCost !== null ? totalCost / accepted : null },
+    semanticQualification: 'not-assessed', humanAssessmentIdentity: 'caller-asserted', grantsAuthority: false }
+}
+
+export function ingestionEvaluationDigest(value) { return digest(value) }

package/src/ingestion/optional/composition/index.mjs

@@ -0,0 +1,171 @@
+import { createHash } from 'node:crypto'
+import { PRESENCE_PROFILES } from '../evaluation/index.mjs'
+
+// Private host execution declarations reuse existing capability owners. This is
+// not a capability-adoption, identity, evidence or knowledge canonical.
+const json = value => JSON.stringify(value)
+const digest = value => createHash('sha256').update(json(value)).digest('hex')
+const ownValue = (object, key) => Object.getOwnPropertyDescriptor(object ?? {}, key)?.value
+const callableFor = (bindings, step) => ownValue(ownValue(bindings, step.provider), step.operation)
+const compiledCallables = new WeakMap()
+
+export function compileRoute({ profile, selected, bindings, operationRoles }) {
+  if (!PRESENCE_PROFILES.includes(profile) || !selected || !ownValue(bindings, 'vanilla') || !operationRoles) throw new TypeError('Known presence profile, selected route, vanilla binding and own operation-role declarations required')
+  const present = new Set(['vanilla', ...(profile === 'vanilla' ? [] : profile.split('+'))])
+  const used = new Set(), callables = new Map()
+  const resolve = (step, role) => {
+    const callable = callableFor(bindings, step ?? {})
+    if (typeof step?.provider !== 'string' || typeof step?.operation !== 'string' || !present.has(step.provider) ||
+      typeof callable !== 'function') throw new Error(`Selected ${role} capability is unavailable in this profile`)
+    if (step.provider === 'jev' && role !== 'assess') throw new Error('Jev supplies bounded judgments rather than extraction or generation')
+    const id = `${step.provider}/${step.operation}`
+    if (used.has(id)) throw new Error('Duplicate selected operation across route roles')
+    if (ownValue(ownValue(operationRoles, step.provider), step.operation) !== role) throw new Error(`Selected operation is not declared for ${role}`)
+    used.add(id)
+    callables.set(id, callable)
+    return Object.freeze({ provider: step.provider, operation: step.operation, role, options: structuredClone(step.options ?? {}) })
+  }
+  const list = (values, role) => {
+    if (!Array.isArray(values)) throw new TypeError(`Explicit selected ${role} operations required`)
+    return values.map(x => resolve(x, role))
+  }
+  const route = { profile, extractor: selected.extractor ? resolve(selected.extractor, 'extract') : null,
+    assessors: list(selected.assessors ?? [], 'assess'), projectors: list(selected.projectors ?? [], 'project'),
+    retrievers: list(selected.retrievers ?? [], 'retrieve'), answerer: selected.answerer ? resolve(selected.answerer, 'answer') : null,
+    nativeAnswer: selected.nativeAnswer ? resolve(selected.nativeAnswer, 'native-answer') : null,
+    view: selected.view ?? 'native-exploration' }
+  if (!['native-exploration', 'accepted-knowledge'].includes(route.view)) throw new Error('Explicit native exploration or existing accepted knowledge view required')
+  if (route.answerer && !route.retrievers.length) throw new Error('Grounded answer route needs selected evidence retrieval')
+  if (route.nativeAnswer && (route.answerer || route.retrievers.length)) throw new Error('Coupled native retrieval/answer is a separate route; do not duplicate retrieval or generation')
+  const compiled = Object.freeze({ ...route, routeDigest: digest(route) })
+  compiledCallables.set(compiled, callables)
+  return compiled
+}
+
+function answerReference(ref) {
+  if (!ref || ['sourceId', 'revision', 'representationId'].some(k => typeof ownValue(ref, k) !== 'string' || !ownValue(ref, k) || ownValue(ref, k).length > 256)) return null
+  const locator = ownValue(ref, 'locator')
+  if (typeof locator === 'string' ? !locator || locator.length > 16384 :
+    !locator || Object.keys(locator).sort().join(',') !== 'kind,value' || ['kind','value'].some(k => typeof ownValue(locator, k) !== 'string' || !ownValue(locator, k) || ownValue(locator, k).length > 16384)) return null
+  return { sourceId: ownValue(ref, 'sourceId'), revision: ownValue(ref, 'revision'),
+    representationId: ownValue(ref, 'representationId'), locator: typeof locator === 'string' ? locator :
+      { kind: ownValue(locator, 'kind'), value: ownValue(locator, 'value') } }
+}
+
+export async function composeEvidence(bundles, { eligible }) {
+  if (!Array.isArray(bundles) || typeof eligible !== 'function') throw new TypeError('Located bundles and actual current evidence owner required')
+  const combined = new Map(), unresolved = [], excluded = []
+  for (const bundle of bundles) {
+    if (!bundle?.provider || !Array.isArray(bundle.hits)) throw new TypeError('Each native bundle needs provider and hits')
+    // Explicit declined native citations survive receiving and prevent a coupled
+    // answer from appearing fully grounded merely because some hits mapped.
+    for (const field of ['unresolved', 'unresolvedReferences']) {
+      if (bundle[field] !== undefined && !Array.isArray(bundle[field])) throw new TypeError('Native receiving gaps must be explicit arrays')
+      for (const gap of bundle[field] ?? []) unresolved.push({ provider: bundle.provider, receivingGap: structuredClone(gap) })
+    }
+    for (const hit of bundle.hits) {
+      // Detach the exact inspected quote/reference before asynchronous receiving.
+      const nativeHit = structuredClone(hit), reference = answerReference(nativeHit?.evidenceRef), quote = nativeHit?.quote
+      if (!reference || typeof quote !== 'string' || !quote) { unresolved.push({ provider: bundle.provider, hit: nativeHit }); continue }
+      const identity = json([reference.sourceId, reference.revision, reference.representationId, reference.locator, quote])
+      const verdict = await eligible(structuredClone(reference), { quote, provider: bundle.provider, generation: bundle.generation })
+      if (verdict?.current !== true || verdict?.permitted !== true || verdict?.supported !== true) { excluded.push({ provider: bundle.provider, hit: nativeHit, reason: verdict?.reason ?? 'exact-quote-support-unreceived' }); continue }
+      if (!combined.has(identity)) combined.set(identity, { evidenceRef: reference, quote, observations: [] })
+      combined.get(identity).observations.push({ provider: bundle.provider, generation: bundle.generation ?? null,
+        nativeHit, score: nativeHit.score ?? null, scoreSemantics: nativeHit.scoreSemantics ?? 'unmapped-native-score' })
+    }
+  }
+  return { hits: [...combined.values()], unresolved, excluded,
+    providerArtifacts: bundles.map(x => ({ provider: x.provider, generation: x.generation ?? null, artifactRef: x.artifactRef ?? null })),
+    distinctSourceCount: new Set([...combined.values()].map(x => x.evidenceRef.sourceId)).size,
+    combinedScore: null, acceptance: 'existing-owner-view-only' }
+}
+
+// Only eligible located evidence reaches ordinary answer generation. Raw hits,
+// artifacts, view content and native rejection strings stay in receipt custody.
+function answerEvidence(evidence) {
+  return { hits: evidence.hits.map(x => ({ evidenceRef: answerReference(x.evidenceRef), quote: x.quote })),
+    distinctSourceCount: evidence.distinctSourceCount,
+    rejectionCounts: { unlocated: evidence.unresolved.length, ineligible: evidence.excluded.length } }
+}
+
+export class CompositionFailure extends Error {
+  constructor(cause, state) {
+    super(`Selected route needs owner reconciliation: ${cause.message}`, { cause })
+    this.name = 'CompositionFailure'
+    Object.assign(this, state)
+  }
+}
+
+/** Host bridges retain actual effect admission, view and evidence authority.
+ * No implicit retry or fallback occurs. Receipt custody survives late failures.
+ */
+export function createComposition({ bindings, operationRoles, invoke, readKnowledgeView, eligible }) {
+  if (!operationRoles || typeof invoke !== 'function' || typeof readKnowledgeView !== 'function' || typeof eligible !== 'function') throw new TypeError('Actual operation roles, effect, knowledge-view and evidence owners required')
+  return Object.freeze({ async execute({ route, input, question, signal }) {
+    const compiled = compileRoute({ profile: route.profile, selected: route, bindings, operationRoles })
+    const receipts = [], retainedResults = [], dispatched = []
+    let failedStep = null, effectUncertain = false
+    const call = async (step, payload) => {
+      failedStep = step
+      if (signal?.aborted) throw new Error('Host cancelled selected route')
+      // Each owner receives an isolated payload; prior results remain under
+      // separate custody even when a later callable mutates its own input.
+      const invocationPayload = structuredClone(payload)
+      dispatched.push(step); effectUncertain = true
+      const returned = await invoke({ step, callable: compiledCallables.get(compiled).get(`${step.provider}/${step.operation}`), payload: invocationPayload, routeDigest: compiled.routeDigest, signal })
+      let result
+      try { result = structuredClone(returned) }
+      catch (snapshotError) {
+        // Returned data/costs remain in custody even when a snapshot cannot be
+        // made. Do not continue grounding or pretend this live value is frozen.
+        retainedResults.push({ step, result: returned, snapshotState: 'failed', snapshotError })
+        throw snapshotError
+      }
+      // Retain a detached snapshot even when its receipt is malformed.
+      retainedResults.push({ step, result, snapshotState: 'received' })
+      if (!result || !result.receiptRef) throw new Error('Selected operation must return its actual receipt reference')
+      receipts.push(structuredClone({ ...step, receiptRef: result.receiptRef, usage: result.usage ?? null }))
+      effectUncertain = false; failedStep = null
+      return structuredClone(result)
+    }
+    const counts = () => ({ selectedExtractorCount: dispatched.filter(x => x.role === 'extract').length,
+      selectedAnswererCount: dispatched.filter(x => ['answer', 'native-answer'].includes(x.role)).length })
+    try {
+      const extraction = compiled.extractor ? await call(compiled.extractor, { input }) : null
+      const assessments = []
+      for (const step of compiled.assessors) assessments.push(await call(step, { input, extraction }))
+      const view = structuredClone(await readKnowledgeView(structuredClone({ requestedView: compiled.view, input, extraction, assessments, routeDigest: compiled.routeDigest })))
+      if (!view?.ownerRef || view.kind !== compiled.view) throw new Error('Existing knowledge owner must return the selected view')
+      const projections = []
+      for (const step of compiled.projectors) projections.push(await call(step, { input, view }))
+      if (compiled.nativeAnswer) {
+        // Existing host must admit authorized current input before a coupled
+        // native model call. Final evidence validation is a separate check.
+        const native = await call(compiled.nativeAnswer, { input, question, view, projections })
+        if (!Array.isArray(native.hits)) throw new Error('Coupled native answer must return located evidence references')
+        const evidence = await composeEvidence([{ ...native, provider: compiled.nativeAnswer.provider }], { eligible })
+        const current = evidence.excluded.length === 0 && evidence.unresolved.length === 0 && evidence.hits.length > 0
+        return { routeDigest: compiled.routeDigest, extraction, assessments, view, projections, evidence,
+          answer: current ? native : null, withheldNativeResult: current ? null : native,
+          answerStatus: current ? 'current-grounding-received' : 'withheld-grounding-unreceived', receipts,
+          ...counts(), nativeAnswerGroundingCurrent: current,
+          canonicalMutation: false, semanticAcceptance: 'existing-owner-only', nativeQualification: false }
+      }
+      const bundles = []
+      for (const step of compiled.retrievers) {
+        const result = await call(step, { input, question, view, projections })
+        if (!Array.isArray(result.hits)) throw new Error('Retriever must return located evidence hits')
+        bundles.push({ ...result, provider: step.provider })
+      }
+      const evidence = await composeEvidence(bundles, { eligible })
+      const answer = compiled.answerer ? await call(compiled.answerer, { question, evidence: answerEvidence(evidence),
+        view: { kind: view.kind, ownerRef: view.ownerRef } }) : null
+      return { routeDigest: compiled.routeDigest, extraction, assessments, view, projections, evidence, answer, receipts,
+        ...counts(), canonicalMutation: false, semanticAcceptance: 'existing-owner-only', nativeQualification: false }
+    } catch (cause) {
+      throw new CompositionFailure(cause, { routeDigest: compiled.routeDigest, receipts, retainedResults, failedStep,
+        effectUncertain, ...counts(), retryAuthorized: false })
+    }
+  } })
+}