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

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

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

@@ -0,0 +1,219 @@
+import { createHash } from 'node:crypto'
+import { performance } from 'node:perf_hooks'
+
+// Private Q02 execution/assessment sidecar. Existing intake and knowledge owners
+// retain all authoritative records; this module grants no execution permission.
+export const PRESENCE_PROFILES = Object.freeze(['vanilla', 'graphify', 'lightrag', 'jev',
+  'graphify+lightrag', 'graphify+jev', 'lightrag+jev', 'graphify+lightrag+jev'])
+const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex')
+const phases = new Set(['cold', 'incremental', 'warm', 'recovery'])
+const terminalStates = new Set(['completed', 'failed', 'unavailable', 'unsupported', 'not-run', 'uncertain'])
+const numberOrNull = value => value === null || Number.isFinite(value) && value >= 0
+const requiredPins = ['installedCandidate', 'corpusDigest', 'targetsDigest', 'routeDigest', 'questionOrderDigest']
+
+export function validateExecutionPlan(plan) {
+  if (!plan || requiredPins.some(key => typeof plan[key] !== 'string' || !plan[key]) ||
+    !Array.isArray(plan.tasks) || !plan.tasks.length) throw new TypeError('Pinned installed target, frozen inputs and explicit task cohort required')
+  const ids = new Set()
+  for (const task of plan.tasks) {
+    if (!task?.id || ids.has(task.id) || !PRESENCE_PROFILES.includes(task.profile) ||
+      !phases.has(task.phase) || !task.routeId || !Number.isSafeInteger(task.repetition) || task.repetition < 1 ||
+      !task.questionId || !task.cacheState) throw new TypeError('Unique tasks require profile, phase, route, repetition, question and cache state')
+    ids.add(task.id)
+  }
+  return Object.freeze(structuredClone(plan))
+}
+
+// Host returns all attempted components, including failures and fallback. Unknown
+// or omitted required charges remain unknown rather than becoming free work.
+export function accountComponents(components) {
+  if (!Array.isArray(components)) throw new TypeError('Explicit accounting components required')
+  const currencies = new Set(), ids = new Set()
+  let knownSubtotal = 0, unknown = false
+  for (const item of components) {
+    if (!item?.id || ids.has(item.id) || !item.kind || !numberOrNull(item.cost) ||
+      !numberOrNull(item.elapsedMs) || typeof item.complete !== 'boolean') throw new TypeError('Unique valid attempted cost components required')
+    ids.add(item.id)
+    if (item.currency !== null && !/^[A-Z]{3}$/.test(item.currency ?? '')) throw new TypeError('Explicit currency or null required')
+    if (item.cost === null || !item.complete) unknown = true
+    else knownSubtotal += item.cost
+    if (item.cost !== null && item.cost !== 0 && item.currency === null) unknown = true
+    if (item.currency !== null) currencies.add(item.currency)
+  }
+  if (!components.length || currencies.size > 1) unknown = true
+  return { totalCost: unknown ? null : knownSubtotal, knownSubtotal,
+    currency: currencies.size === 1 ? [...currencies][0] : null,
+    complete: !unknown, attemptedComponents: components.length,
+    incompleteComponents: components.filter(x => x.cost === null || !x.complete).map(x => x.id),
+    unknownOrMixedCurrency: currencies.size > 1 || components.some(x => x.cost !== null && x.cost !== 0 && x.currency === null) }
+}
+
+// Separate existing assessor receipts are verified by a trusted receiving host.
+// Producer-supplied assessment fields never enter the useful-answer numerator.
+export function assessmentBinding(record) {
+  return { taskId: record.taskId, planDigest: record.planDigest, questionId: record.questionId,
+    routeId: record.routeId, resultDigest: record.resultDigest }
+}
+function assessmentReceived(record, receipt, verifyAssessment) {
+  if (record.outcome !== 'completed' || typeof verifyAssessment !== 'function' || !receipt) return false
+  const binding = assessmentBinding(record)
+  if (Object.values(binding).some(x => typeof x !== 'string' || !x) ||
+    !receipt.receiptRef || !receipt.assessorRef || !receipt.rubricRef || receipt.bindingDigest !== digest(binding)) return false
+  try {
+    const verified = verifyAssessment(structuredClone(receipt), structuredClone(binding))
+    if (typeof verified?.then === 'function') { Promise.resolve(verified).catch(() => {}); return false }
+    return verified?.verified === true && verified?.current === true && !!verified.ownerRef &&
+      verified.receiptRef === receipt.receiptRef && verified.bindingDigest === receipt.bindingDigest &&
+      receipt.usefulAccepted === true && receipt.supportAccepted === true
+  } catch { return false }
+}
+
+export function summarizeCohort({ assignedTaskIds, records, sharedComponents = [], assessmentReceipts = [], verifyAssessment }) {
+  if (!Array.isArray(assignedTaskIds) || !assignedTaskIds.length || new Set(assignedTaskIds).size !== assignedTaskIds.length ||
+    !Array.isArray(records) || !Array.isArray(assessmentReceipts)) throw new TypeError('Complete assigned denominator required')
+  const assigned = new Set(assignedTaskIds), observed = new Set(), assessmentTasks = new Set()
+  for (const record of records) {
+    if (!assigned.has(record.taskId) || observed.has(record.taskId) || !terminalStates.has(record.outcome)) throw new TypeError('Records must uniquely match the assigned cohort')
+    observed.add(record.taskId)
+  }
+  for (const receipt of assessmentReceipts) {
+    if (!assigned.has(receipt?.taskId) || assessmentTasks.has(receipt.taskId)) throw new TypeError('Separate assessor receipts must uniquely match assigned tasks')
+    assessmentTasks.add(receipt.taskId)
+  }
+  const useful = records.filter(record => assessmentReceived(record, assessmentReceipts.find(x => x.taskId === record.taskId), verifyAssessment))
+  const costs = [...sharedComponents, ...records.flatMap(x => x.components ?? [])]
+  let accounting
+  try { accounting = accountComponents(costs) }
+  catch (error) {
+    // Retain malformed/colliding accounting for reconciliation without losing
+    // already executed tasks or treating unverified charges as free work.
+    accounting = { totalCost: null, knownSubtotal: null, currency: null, complete: false,
+      attemptedComponents: costs.length, accountingIssue: error.message, retainedComponents: costs }
+  }
+  const missing = assignedTaskIds.filter(id => !observed.has(id))
+  const complete = !missing.length && records.every(x => Array.isArray(x.components) && x.components.length)
+  const totalCost = complete ? accounting.totalCost : null
+  return { assigned: assigned.size, observed: observed.size, missing,
+    usefulAccepted: useful.length, usefulAcceptedFraction: useful.length / assigned.size,
+    failedOrUnavailable: assigned.size - useful.length, accounting: { ...accounting, complete: complete && accounting.complete, totalCost },
+    costPerUsefulAcceptedAnswer: totalCost === null || !useful.length ? null : totalCost / useful.length,
+    elapsedObservations: records.map(x => ({ taskId: x.taskId, outcome: x.outcome, elapsedMs: x.elapsedMs ?? null })),
+    semanticQualityQualified: false, humanAuthorityVerified: false }
+}
+
+export function amortizedCosts({ ingestionComponents, queryComponents, queryCounts = [1, 10, 100] }) {
+  const initial = accountComponents(ingestionComponents), query = accountComponents(queryComponents)
+  return queryCounts.map(count => {
+    if (!Number.isSafeInteger(count) || count < 1) throw new TypeError('Positive predeclared query counts required')
+    const compatible = initial.currency === query.currency || initial.totalCost === 0 || query.totalCost === 0
+    return { queryCount: count, totalCost: initial.totalCost === null || query.totalCost === null || !compatible ? null : initial.totalCost + count * query.totalCost,
+      costPerQuery: initial.totalCost === null || query.totalCost === null || !compatible ? null : initial.totalCost / count + query.totalCost,
+      assumedWorkload: true, observedDemand: false }
+  })
+}
+
+/**
+ * Admission, native effects, resource bounds and cleanup belong to injected
+ * existing host owners. The host enforces per-call provider/CPU/deadline limits.
+ * No automatic retry/fallback, provider construction or rubric loading occurs.
+ */
+export function createQualificationExecutor({ admit, openTrial, executeTask, closeTrial, appendSidecar,
+  receiveAssessment, verifyAssessment,
+  monotonic = () => performance.now(), now = () => new Date().toISOString() }) {
+  for (const fn of [admit, openTrial, executeTask, closeTrial, appendSidecar]) if (typeof fn !== 'function') throw new TypeError('Actual admission, execution, sidecar and cleanup owners required')
+  if ((receiveAssessment !== undefined || verifyAssessment !== undefined) &&
+    (typeof receiveAssessment !== 'function' || typeof verifyAssessment !== 'function')) throw new TypeError('Separate assessment receiving and receipt verification owners required together')
+  return Object.freeze({ async run(planInput, { signal } = {}) {
+    const plan = validateExecutionPlan(planInput), planDigest = digest(plan)
+    const admission = await admit({ plan: structuredClone(plan), planDigest, signal })
+    if (admission?.planDigest !== planDigest || admission?.executionAllowed !== true ||
+      !admission?.ownerRef || !admission?.limitsRef) throw new Error('Existing owner refused or did not bind actual execution admission')
+    const records = [], trials = new Map(), sharedComponents = [], terminalCleanup = [], assessmentReceipts = [], componentIds = new Set(), sidecarFailures = []
+    const retainComponents = components => {
+      accountComponents(components)
+      if (components.some(x => componentIds.has(x.id))) throw new Error('Duplicate attempted accounting component across the cohort')
+      for (const x of components) componentIds.add(x.id)
+    }
+    const unknownAttempt = (task, stage, attemptedResult, error) => {
+      let id = `${task.id}/${stage}/unreported-attempt`
+      while (componentIds.has(id)) id += '/unreported'
+      componentIds.add(id)
+      return { outcome: 'uncertain', effectStage: stage, attemptedResult,
+        reconciliationReason: error?.message ?? 'actual result unreceived',
+        components: [{ id, kind: 'unreported-native-attempt', cost: null, currency: null, elapsedMs: null, complete: false }] }
+    }
+    const save = async (task, result, started, startedAt) => {
+      const record = { outcome: result.outcome, components: result.components, effectStage: result.effectStage,
+        reconciliationReason: result.reconciliationReason, executionResult: result, resultDigest: null,
+        taskId: task.id, profile: task.profile, phase: task.phase, routeId: task.routeId, repetition: task.repetition,
+        questionId: task.questionId, cacheState: task.cacheState, planDigest, startedAt, endedAt: now(), elapsedMs: Math.max(0, monotonic() - started),
+        qualification: 'unscored-execution-sidecar', admissionOwnerRef: admission.ownerRef }
+      // Retain execution before invoking a separate assessor or sidecar sink.
+      records.push(record)
+      record.executionResult = structuredClone(result)
+      record.resultDigest = digest(record.executionResult)
+      if (record.outcome === 'completed' && receiveAssessment) {
+        try {
+          const receipt = await receiveAssessment({ binding: assessmentBinding(record), result: structuredClone(result), plan: structuredClone(plan), signal })
+          if (receipt) {
+            record.assessmentReceiving = structuredClone(receipt)
+            if (receipt.taskId === task.id && receipt.bindingDigest === digest(assessmentBinding(record)) &&
+              receipt.receiptRef && receipt.assessorRef && receipt.rubricRef) assessmentReceipts.push(structuredClone(receipt))
+          }
+        } catch (error) { record.assessmentReceivingError = error.message }
+      }
+      await appendSidecar(structuredClone(record))
+    }
+    let failure
+    try {
+      for (const task of plan.tasks) {
+        if (signal?.aborted) break
+        const trialKey = `${task.profile}/${task.routeId}/${task.phase}/${task.repetition}`
+        if (!trials.has(trialKey)) {
+          const started = monotonic(), startedAt = now(), entry = { handle: null, task: structuredClone(task) }
+          trials.set(trialKey, entry)
+          let opened
+          try {
+            opened = await openTrial({ task: structuredClone(task), trialKey, planDigest, admission, signal })
+            if (opened?.handle) entry.handle = opened.handle
+            if (!entry.handle || !Array.isArray(opened.components) || !opened.components.length) throw new Error('Trial owner must return an actual handle and explicit shared accounting')
+            retainComponents(opened.components)
+            sharedComponents.push(...opened.components)
+          } catch (error) {
+            await save(task, unknownAttempt(task, 'trial-open', opened ?? error.attemptedResult, error), started, startedAt)
+            break
+          }
+        }
+        const started = monotonic(), startedAt = now()
+        let result
+        try {
+          result = await executeTask({ task: structuredClone(task), trial: trials.get(trialKey).handle, planDigest, admission, signal })
+          if (!terminalStates.has(result?.outcome) || !Array.isArray(result.components) || !result.components.length) throw new Error('Incomplete host task receipt')
+          retainComponents(result.components)
+        } catch (error) {
+          result = unknownAttempt(task, 'task-execution', result ?? error.attemptedResult, error)
+        }
+        await save(task, result, started, startedAt)
+        if (result.outcome === 'uncertain') break
+      }
+    } catch (error) { failure = error }
+    finally {
+      for (const [trialKey, entry] of [...trials].reverse()) {
+        let cleanup
+        try { cleanup = await closeTrial({ trial: entry.handle, task: entry.task, trialKey, planDigest, admission }) }
+        catch (error) { cleanup = { verified: false, outcome: 'cleanup-uncertain', reason: error.message } }
+        terminalCleanup.push({ trialKey, ...cleanup })
+      }
+      try { await appendSidecar({ kind: 'trial-cleanup', planDigest, terminalCleanup, qualification: 'host-reported-not-independently-verified' }) }
+      catch (error) { sidecarFailures.push({ stage: 'trial-cleanup', error }); failure ??= error }
+    }
+    if (failure) {
+      // Original sidecar/cleanup failure retains all executed output and custody.
+      Object.assign(failure, { records, sharedComponents, assessmentReceipts, terminalCleanup, sidecarFailures, planDigest, retryAuthorized: false })
+      throw failure
+    }
+    return { planDigest, records, sharedComponents, assessmentReceipts, terminalCleanup,
+      cohort: summarizeCohort({ assignedTaskIds: plan.tasks.map(x => x.id), records, sharedComponents, assessmentReceipts, verifyAssessment }),
+      cleanupVerified: terminalCleanup.every(x => x.verified === true), nativeQualification: false, benefitQualified: false }
+  } })
+}