@arcfold/dsh 0.0.0-stage → 0.4.0

package/src/tree/items.mjs

@@ -0,0 +1,294 @@
+import { randomUUID } from 'node:crypto';
+import { array, canonicalJson, digest, fail, integer, oneOf, shape, text, validateLong, validateShort, CATEGORIES } from './contracts.mjs';
+import { DomainService } from './tree.mjs';
+
+const versionId = (id, version) => digest(['item_version', id, version]);
+const methodId = (id, version) => digest(['method', id, version]);
+const supplementId = (id, version) => digest(['supplement', id, version]);
+export const HOOK_RULES = Object.freeze({
+  user_message: { fields: ['userMessage'], actions: ['add_context'] },
+  before_tool: { fields: ['toolName', 'command', 'filePath', 'earlierToolsInTurn', 'earlierFilesInTurn'], actions: ['block', 'ask_user', 'add_context'] },
+  after_tool: { fields: ['toolName', 'command', 'filePath', 'isError', 'output'], actions: ['add_context'] },
+  turn_end: { fields: ['toolsCalled', 'filesWritten', 'earlierToolsInTurn', 'earlierFilesInTurn'], actions: ['remind_user', 'continue'] },
+  node_enter: { fields: ['nodeId', 'nodeName'], actions: ['add_context'] },
+  node_leave: { fields: ['filesWrittenInNode'], actions: ['remind_user', 'leave_note'] },
+  node_complete: { fields: ['filesWrittenInNode', 'completedBy'], actions: ['remind_user', 'block'] },
+});
+export function validateHook(hook) {
+  shape(hook, ['moment', 'conditions', 'action', 'message']); const rule = HOOK_RULES[hook.moment];
+  if (!rule) fail('INVALID_HOOK', 'Unknown hook moment'); oneOf(hook.action, rule.actions, 'hook action'); text(hook.message, 'hook message', 80, true);
+  for (const condition of array(hook.conditions, 'conditions', 16)) {
+    shape(condition, ['field', 'op', 'value']); oneOf(condition.field, rule.fields, 'hook field'); oneOf(condition.op, ['equals', 'contains', 'not_contains', 'starts_with', 'ends_with'], 'operator');
+    if (typeof condition.value !== 'boolean') text(condition.value, 'condition value', 512, true);
+    if (typeof condition.value === 'boolean' && condition.op !== 'equals') fail('INVALID_HOOK', 'Boolean values only support equality');
+  }
+}
+
+export class ItemService extends DomainService {
+  item(id) { const item = this.repo.get('tree_items', id); if (!item) fail('ITEM_NOT_FOUND', 'Item not found'); return item; }
+  version(id, version) { const row = this.repo.get('tree_item_versions', versionId(id, version)); if (!row) fail('ITEM_VERSION_NOT_FOUND', 'Item version not found'); return row; }
+  #newItem(kind, nodeId, content, refs, sourceKind, { lifecycle = 'active' } = {}) {
+    const id = randomUUID(); this.repo.save('tree_items', { id, kind, nodeId, activeVersion: lifecycle === 'active' ? 1 : null, draftVersion: lifecycle === 'draft' ? 1 : null, lifecycle, validation: 'unverified', userProtected: this.context().actor.kind === 'user', originNodeId: nodeId, originChain: [nodeId] });
+    this.repo.save('tree_item_versions', { id: versionId(id, 1), itemId: id, version: 1, content, sourceKind, sourceRefs: refs, reason: 'proposal' }); return id;
+  }
+  #understanding(proposal, nodeId) {
+    shape(proposal, ['content', 'source', 'sourceRefs']); text(proposal.content, 'content', 2000); oneOf(proposal.source, ['user_expressed', 'assistant_inferred', 'unknown'], 'source');
+    const refs = this.refs(proposal.sourceRefs, { user: proposal.source === 'user_expressed' }); return this.#newItem('understanding', nodeId, proposal.content, refs, proposal.source);
+  }
+  #method(proposal, nodeId, previous = null) {
+    shape(proposal, ['kind', 'short', 'long', 'hooks', 'scriptRequests', 'expectedEffect', 'sourceRefs']); oneOf(proposal.kind, ['collaboration', 'technique'], 'method kind');
+    if (proposal.short === null && proposal.long === null) fail('TEXT_REQUIRED', 'A method requires short or long text');
+    if (proposal.short !== null) validateShort(proposal.short); if (proposal.long !== null) validateLong(proposal.long);
+    array(proposal.hooks, 'hooks', 8).forEach(validateHook);
+    for (const request of array(proposal.scriptRequests, 'scriptRequests', 8)) {
+      shape(request, ['purpose', 'evidence', 'files']); text(request.purpose, 'script purpose', 2000); array(request.evidence, 'evidence', 20).forEach(s => text(s, 'evidence id', 512)); array(request.files, 'files', 20).forEach(s => text(s, 'file reference', 512));
+    }
+    if (!proposal.expectedEffect) fail('EXPECTATION_REQUIRED', 'An explicit expected effect is required');
+    shape(proposal.expectedEffect, ['category', 'change', 'text']); oneOf(proposal.expectedEffect.category, CATEGORIES, 'category'); oneOf(proposal.expectedEffect.change, ['gone', 'less', 'more'], 'expected change'); text(proposal.expectedEffect.text, 'expectation', 40);
+    const refs = this.refs(proposal.sourceRefs), lifecycle = proposal.scriptRequests.length ? 'draft' : 'active';
+    const id = previous?.id ?? this.#newItem('method', nodeId, proposal, refs, 'assistant_inferred', { lifecycle }), version = previous ? previous.activeVersion + 1 : 1;
+    if (previous) {
+      this.#withdraw(previous, 'bundle_replaced');
+      this.repo.save('tree_item_versions', { id: versionId(id, version), itemId: id, version, content: proposal, sourceKind: 'assistant_inferred', sourceRefs: refs, reason: 'bundle_replaced', supersedes: previous.activeVersion });
+      this.replace('tree_items', this.item(id), { lifecycle, activeVersion: lifecycle === 'active' ? version : null, draftVersion: lifecycle === 'draft' ? version : null, validation: 'unverified' });
+    }
+    const hooks = proposal.hooks.map((h, index) => {
+      const hookId = digest(['hook', id, index]), key = digest(['hook_version', hookId, version]);
+      this.repo.save('tree_hooks', { ...h, id: key, hookId, methodId: id, version, scopeNodeId: nodeId, enabled: lifecycle === 'active' }); return { id: hookId, version };
+    });
+    this.repo.save('tree_methods', { id: methodId(id, version), itemId: id, version, short: proposal.short, long: proposal.long, scripts: previous ? this.repo.get('tree_methods', methodId(id, previous.activeVersion)).scripts : [], hooks, expectation: proposal.expectedEffect, evaluation: { status: 'unverified', windowId: null, evidenceIds: [] }, pendingScriptRequests: proposal.scriptRequests }); return id;
+  }
+  #supplement(proposal, nodeId) {
+    shape(proposal, ['target', 'text', 'sourceRefs', 'traitEvidence', 'universalStopgap'], ['reportId']);
+    oneOf(proposal.target, ['learning', 'attribution', 'consolidation'], 'target'); validateShort(proposal.text); const refs = this.refs(proposal.sourceRefs);
+    const evidence = this.refs(proposal.traitEvidence, { required: !proposal.universalStopgap });
+    if (typeof proposal.universalStopgap !== 'boolean') fail('INVALID_FIELD', 'universalStopgap must be boolean');
+    if (proposal.universalStopgap && (!proposal.reportId || !this.repo.get('tree_reports', proposal.reportId))) fail('REPORT_REQUIRED', 'A universal stopgap must link a local report');
+    const id = this.#newItem('supplement', nodeId, proposal.text, refs, 'assistant_inferred');
+    this.repo.save('tree_supplements', { id: supplementId(id, 1), itemId: id, version: 1, target: proposal.target, scopeNodeId: nodeId, traitEvidence: evidence, universalStopgap: proposal.universalStopgap, reportId: proposal.reportId ?? null }); return id;
+  }
+  commitProposal(command) {
+    return this.repo.command('commitProposal', command, this.actor(['learning', 'consolidation', 'verification', 'improvement']), () => {
+      const input = command.input; shape(input, ['nodeId', 'understandings', 'methods', 'supplements'], ['revisions']); this.node(input.nodeId); this.scoped(input.nodeId);
+      const result = {};
+      for (const [partition, limit, apply] of [['understandings', 20, p => this.#understanding(p, input.nodeId)], ['methods', 10, p => this.#method(p, input.nodeId)], ['supplements', 10, p => this.#supplement(p, input.nodeId)]]) {
+        try {
+          result[partition] = this.repo.transaction(() => {
+            const ids = array(input[partition], partition, limit).map(apply);
+            if (partition === 'understandings') for (const revision of array(input.revisions ?? [], 'revisions', 20)) this.#correctVersion(revision, ids, input.nodeId, command);
+            return { status: 'applied', itemIds: ids };
+          });
+        } catch (error) {
+          if (!error.code || ['SQLITE_BUSY', 'REVISION_CONFLICT'].includes(error.code)) throw error;
+          result[partition] = { status: 'rejected', code: error.code, reason: error.message };
+        }
+      }
+      return result;
+    });
+  }
+  #correctVersion(revision, replacements, nodeId, command) {
+    shape(revision, ['targetId', 'targetVersion', 'mark', 'replacedByIndex', 'sourceRefs']); oneOf(revision.mark, ['changed', 'invalid'], 'mark'); integer(revision.replacedByIndex, 'replacement index', 0, replacements.length - 1);
+    const item = this.item(revision.targetId); this.repo.requireExpected(command, 'tree_items', item.id);
+    if (item.kind !== 'understanding') fail('UNDERSTANDING_REQUIRED', 'Understanding corrections cannot rewrite a method bundle');
+    if (item.activeVersion !== revision.targetVersion) fail('VERSION_CONFLICT', 'Target version changed'); this.refs(revision.sourceRefs, { user: true });
+    // The learning adapter validates exact current-user evidence and binds each
+    // classified correction to this item. Domain proposals cannot grant it.
+    const correction = this.context().corrections?.[item.id] ?? this.context().correction;
+    if (!correction || !correction.itemIds?.includes(item.id) || revision.sourceRefs.some(r => !correction.sourceRefs?.some(s => canonicalJson(r) === canonicalJson(s)))) fail('CORRECTION_REQUIRED', 'No trusted current-user correction for this item');
+    if (item.nodeId !== nodeId && !correction.global) fail('LOCAL_EXCEPTION', 'A local exception cannot invalidate an ancestor item');
+    if (item.nodeId !== nodeId) {
+      const replacement = this.item(replacements[revision.replacedByIndex]);
+      this.replace('tree_items', replacement, { nodeId: item.nodeId, originChain: [...new Set([...replacement.originChain, item.nodeId])] });
+    }
+    this.replace('tree_items', item, { lifecycle: revision.mark, replacedBy: replacements[revision.replacedByIndex], correctionSourceRefs: revision.sourceRefs });
+  }
+  #copyBundle(item, from, to, updates = {}) {
+    if (item.kind === 'method') {
+      const bundle = this.repo.get('tree_methods', methodId(item.id, from)); if (!bundle) fail('BUNDLE_MISSING', 'Method version missing');
+      const hooks = bundle.hooks.map(ref => {
+        const old = this.repo.get('tree_hooks', digest(['hook_version', ref.id, ref.version]));
+        if (!old) fail('BUNDLE_MISSING', 'Hook missing'); this.replace('tree_hooks', old, { enabled: false });
+        this.repo.save('tree_hooks', { ...old, id: digest(['hook_version', ref.id, to]), version: to, scopeNodeId: item.nodeId, enabled: !old.manuallyDisabled }); return { id: ref.id, version: to };
+      });
+      this.repo.save('tree_methods', { ...bundle, ...updates, id: methodId(item.id, to), version: to, hooks });
+    } else if (item.kind === 'supplement') {
+      const old = this.repo.get('tree_supplements', supplementId(item.id, from)); this.repo.save('tree_supplements', { ...old, ...updates, id: supplementId(item.id, to), version: to, scopeNodeId: item.nodeId });
+    }
+  }
+  activateDraft(command) {
+    return this.repo.command('activateDraft', command, this.actor([]), () => {
+      if (this.context().actor.kind !== 'program') fail('FORBIDDEN', 'Only the artifact broker may activate a finished draft');
+      shape(command.input, ['itemId', 'version', 'artifactIds']); const item = this.item(command.input.itemId); this.repo.requireExpected(command, 'tree_items', item.id);
+      if (item.lifecycle !== 'draft' || item.draftVersion !== command.input.version) fail('VERSION_CONFLICT', 'Draft changed');
+      const bundle = this.repo.get('tree_methods', methodId(item.id, item.draftVersion));
+      const artifacts = array(command.input.artifactIds, 'artifacts', 8).map(id => this.repo.get('tree_script_artifacts', id));
+      if (artifacts.length !== bundle.pendingScriptRequests.length || new Set(command.input.artifactIds).size !== artifacts.length) fail('BUNDLE_INCOMPLETE', 'Every requested script must be ready exactly once');
+      for (const artifact of artifacts) if (!artifact || artifact.methodId !== item.id || artifact.activationState !== 'ready' || artifact.language !== 'node-esm' || !this.context().verifiedArtifacts?.some(v => v.id === artifact.id && v.revision === artifact.revision && v.filesHash === digest(artifact.files))) fail('ARTIFACT_UNVERIFIED', 'Broker must verify current artifact bytes before submitting activation');
+      const version = item.draftVersion + 1, old = this.version(item.id, item.draftVersion);
+      this.repo.save('tree_item_versions', { ...old, id: versionId(item.id, version), version, reason: 'all_scripts_ready', supersedes: old.version, bundleHash: digest(artifacts.map(a => a.files)) });
+      this.#copyBundle(item, item.draftVersion, version, { scripts: [...bundle.scripts, ...artifacts.map(a => ({ id: a.scriptId, version: a.version, hash: digest(a.files) }))], pendingScriptRequests: [] });
+      this.replace('tree_items', item, { lifecycle: 'active', activeVersion: version, draftVersion: null }); return { itemId: item.id, version };
+    });
+  }
+  confirm(command) {
+    return this.repo.command('confirmItem', command, this.actor([], true), () => {
+      shape(command.input, ['itemId', 'version']); const item = this.item(command.input.itemId); this.repo.requireExpected(command, 'tree_items', item.id);
+      if (item.lifecycle !== 'active' || item.activeVersion !== command.input.version) fail('VERSION_CONFLICT', 'Active version changed');
+      const old = this.version(item.id, item.activeVersion), version = old.version + 1;
+      this.repo.save('tree_item_versions', { ...old, id: versionId(item.id, version), version, sourceKind: 'user_expressed', confirmationRef: digest(['change', command.requestId]), supersedes: old.version, reason: 'trusted_user_confirmation' });
+      this.#copyBundle(item, old.version, version); this.replace('tree_items', item, { activeVersion: version, userProtected: true, validation: 'supported' }); return { itemId: item.id, version };
+    });
+  }
+  #withdraw(item, reason, lifecycle = 'withdrawn') {
+    for (const hook of this.repo.list('tree_hooks', h => h.methodId === item.id && h.enabled)) this.replace('tree_hooks', hook, { enabled: false });
+    for (const run of this.repo.list('tree_script_runs', r => r.methodVersion?.itemId === item.id && !['succeeded', 'failed', 'revoked'].includes(r.state))) this.replace('tree_script_runs', run, { state: 'revoked', denial: reason });
+    for (const e of this.repo.list('tree_exposures', e => !e.revoked && e.itemVersions.some(v => v.itemId === item.id))) this.replace('tree_exposures', e, { revoked: true, invalidationReason: reason });
+    this.replace('tree_items', item, { lifecycle });
+  }
+  withdraw(command) {
+    return this.repo.command('withdrawItem', command, this.actor([], true), () => {
+      shape(command.input, ['itemId', 'version', 'reason']); const item = this.item(command.input.itemId); this.repo.requireExpected(command, 'tree_items', item.id); text(command.input.reason, 'reason');
+      if ((item.activeVersion ?? item.draftVersion) !== command.input.version) fail('VERSION_CONFLICT', 'Item version changed'); this.#withdraw(item, command.input.reason); return { itemId: item.id, lifecycle: 'withdrawn' };
+    });
+  }
+  recheckSources(command) {
+    return this.repo.command('recheckItemSources', command, this.actor(['verification']), () => {
+      const input = command.input, authority = this.context().sourceRecheck;
+      shape(input, ['itemId', 'version', 'operation', 'reason', 'sourceRefs'], ['replacement']);
+      oneOf(input.operation, ['support', 'rewrite', 'withdraw', 'probe'], 'source review operation'); text(input.reason, 'reason');
+      const job = authority && this.repo.get('tree_jobs', authority.jobId), exposure = authority && this.repo.get('tree_exposures', authority.exposureId);
+      const invocation = exposure && this.repo.get('tree_invocations', exposure.invocationId);
+      if (!job || job.role !== 'verification' || job.status !== 'validated' || job.input.sourceRecheck?.itemId !== input.itemId || job.input.sourceRecheck?.itemVersion !== input.version ||
+          this.context().actor.id !== job.id || exposure?.kind !== 'source_recheck' || exposure.role !== 'verification' || exposure.revoked || exposure.inputHash !== job.inputHash ||
+          invocation?.jobId !== job.id || invocation.state !== 'result_received' || invocation.inputHash !== job.inputHash) fail('RECHECK_AUTHORITY', 'An actual validated source-review owner is required');
+      const item = this.item(input.itemId); this.repo.requireExpected(command, 'tree_items', item.id); this.scoped(item.nodeId);
+      if (item.lifecycle !== 'active' || !item.stale || item.staleReason !== 'assignment_corrected' || item.activeVersion !== input.version) fail('VERSION_CONFLICT', 'Source-review target changed');
+      if (item.userProtected && input.operation !== 'probe') fail('USER_PROTECTED', 'Protected source conflicts require owner review');
+      const refs = this.refs(input.sourceRefs), allowed = new Set(job.input.sources.map(s => canonicalJson(s.ref)));
+      if (refs.some(ref => !allowed.has(canonicalJson(ref)))) fail('RECHECK_SOURCE', 'Only still-assigned frozen evidence may support this version');
+      const review = { jobId: job.id, intentId: job.input.sourceRecheck.intentId, exposureId: exposure.id, version: input.version,
+        operation: input.operation, reason: input.reason, sourceRefs: refs, status: input.operation === 'probe' ? 'needs_evidence' : 'resolved' };
+      if (input.operation === 'probe') {
+        this.replace('tree_items', item, { sourceReview: review, probe: { what: input.reason, evidenceRefs: refs, version: item.activeVersion, windowId: job.input.window.id } });
+        return { itemId: item.id, status: 'needs_evidence', active: false };
+      }
+      if (input.operation === 'withdraw') {
+        this.#withdraw(item, 'assignment_source_review');
+        this.replace('tree_items', this.item(item.id), { sourceReview: review, stale: false, staleReason: null });
+        return { itemId: item.id, status: 'withdrawn', active: false };
+      }
+      const old = this.version(item.id, item.activeVersion), next = old.version + 1;
+      let content = old.content;
+      if (input.operation === 'rewrite') {
+        if (item.kind === 'understanding') { text(input.replacement, 'replacement', 2000); content = input.replacement; }
+        else if (item.kind === 'method') {
+          const proposal = input.replacement;
+          shape(proposal, ['kind', 'short', 'long', 'hooks', 'scriptRequests', 'expectedEffect', 'sourceRefs']);
+          if (proposal.kind !== old.content.kind || canonicalJson(proposal.hooks) !== canonicalJson(old.content.hooks) || proposal.scriptRequests.length || this.repo.get('tree_methods', methodId(item.id, old.version)).scripts.length) fail('RECHECK_COMPONENT', 'Source recheck cannot create or silently change executable components');
+          if (proposal.short === null && proposal.long === null) fail('TEXT_REQUIRED', 'A method requires text');
+          if (proposal.short !== null) validateShort(proposal.short); if (proposal.long !== null) validateLong(proposal.long);
+          shape(proposal.expectedEffect, ['category', 'change', 'text']); oneOf(proposal.expectedEffect.category, CATEGORIES, 'category'); oneOf(proposal.expectedEffect.change, ['gone', 'less', 'more'], 'change'); text(proposal.expectedEffect.text, 'expectation', 40);
+          content = proposal;
+        } else fail('RECHECK_KIND', 'A supplement needing different wording requires an explicit probe');
+      }
+      if (item.kind === 'method') content = { ...content, sourceRefs: refs };
+      const supplement = item.kind === 'supplement' ? this.repo.get('tree_supplements', supplementId(item.id, old.version)) : null;
+      const remainingTraits = supplement?.traitEvidence.filter(ref => refs.some(r => canonicalJson(r) === canonicalJson(ref)));
+      if (supplement && !supplement.universalStopgap && !remainingTraits.length) fail('RECHECK_TRAIT', 'A personal supplement still needs its own user evidence');
+      const sourceKind = input.operation === 'support' ? old.sourceKind : 'assistant_inferred';
+      if (sourceKind === 'user_expressed') this.refs(refs, { user: true });
+      this.repo.save('tree_item_versions', { id: versionId(item.id, next), itemId: item.id, version: next, content, sourceKind, sourceRefs: refs, supersedes: old.version, reason: 'assignment_source_review' });
+      this.#copyBundle(item, old.version, next, item.kind === 'method' ? { short: content.short, long: content.long, expectation: content.expectedEffect, evaluation: { status: 'unverified', windowId: null, evidenceIds: [] } } : supplement ? { traitEvidence: remainingTraits } : {});
+      this.replace('tree_items', item, { activeVersion: next, stale: false, staleReason: null, validation: 'unverified', sourceReview: review });
+      for (const e of this.repo.list('tree_exposures', e => !e.revoked && e.itemVersions.some(v => v.itemId === item.id))) this.replace('tree_exposures', e, { revoked: true, invalidationReason: 'assignment_source_review' });
+      return { itemId: item.id, version: next, status: 'resolved', active: true };
+    });
+  }
+  review(command) {
+    return this.repo.command('reviewItem', command, this.actor(['verification', 'consolidation']), () => {
+      const input = command.input; shape(input, ['itemId', 'version', 'exposureId', 'operation', 'reason', 'sourceRefs', 'windowId', 'opportunityRefs'], ['toNodeId', 'replacement', 'result', 'mergeTargetId', 'mergeTargetVersion']);
+      oneOf(input.operation, ['support', 'rewrite', 'mark_invalid', 'mark_changed', 'move', 'merge', 'promote', 'demote', 'withdraw', 'harden'], 'operation'); text(input.reason, 'reason'); text(input.windowId, 'windowId', 512);
+      const item = this.item(input.itemId); this.repo.requireExpected(command, 'tree_items', item.id);
+      if (item.lifecycle !== 'active' || item.activeVersion !== input.version) fail('VERSION_CONFLICT', 'Target is no longer active');
+      // A verification transaction may change several items from the same
+      // actual exposure. Its trusted adapter validates every snapshot before
+      // any mutation and supplies those exact snapshots for this transaction.
+      // No command/model field can provide this authority.
+      const exposure = this.context().reviewExposure?.(input.exposureId) ?? this.repo.get('tree_exposures', input.exposureId);
+      if (!exposure || exposure.kind === 'source_recheck' || exposure.revoked || !exposure.itemVersions.some(v => v.itemId === item.id && v.version === input.version)) fail('EXPOSURE_REQUIRED', 'Review must bind an actual exposure of this version');
+      this.refs(input.sourceRefs); this.refs(input.opportunityRefs, { required: false });
+      if (item.userProtected && this.context().actor.kind !== 'user' && input.operation !== 'support') fail('USER_PROTECTED', 'A model cannot modify protected content');
+      if (this.context().actor.kind === 'model' && !exposure.nodeIds.some(id => (this.context().nodeIds ?? []).includes(id))) fail('OUT_OF_SCOPE', 'Exposure is outside reviewer scope');
+      const result = input.opportunityRefs.length ? oneOf(input.result ?? 'unclear', ['met', 'not_met', 'unclear'], 'verification result') : 'unclear';
+      const reviewId = digest(['review', item.id, input.version, input.windowId]);
+      if ((item.reviews ?? []).some(r => r.id === reviewId)) return { itemId: item.id, duplicateWindow: true };
+      const review = { id: reviewId, version: input.version, windowId: input.windowId, operation: input.operation, result, sourceRefs: input.sourceRefs, opportunityRefs: input.opportunityRefs, exposureId: exposure.id, reason: input.reason };
+      let updates = { reviews: [...(item.reviews ?? []), review] };
+      if (input.operation === 'support') {
+        const supportingNodes = new Set(); const observedSources = new Set();
+        for (const r of updates.reviews.filter(r => r.version === item.activeVersion && r.result === result && result !== 'unclear')) {
+          const uniqueEvidence = r.opportunityRefs.some(ref => !observedSources.has(canonicalJson(ref)));
+          r.opportunityRefs.forEach(ref => observedSources.add(canonicalJson(ref)));
+          const nodes = this.repo.get('tree_exposures', r.exposureId)?.nodeIds ?? [];
+          // One observation assigned to multiple nodes is still one observation;
+          // without a per-source node mapping it cannot prove independent support.
+          if (uniqueEvidence && nodes.length === 1) supportingNodes.add(nodes[0]);
+        }
+        const ancestorItem = item.nodeId === this.repo.rootId() || exposure.nodeIds.some(id => id !== item.nodeId);
+        const supported = this.context().actor.kind === 'user' || !ancestorItem || supportingNodes.size >= 2;
+        updates.validation = result === 'met' ? supported ? 'supported' : 'unverified' : result === 'not_met' ? supported ? 'refuted' : item.validation : item.validation;
+      }
+      else if (['mark_invalid', 'mark_changed'].includes(input.operation)) updates.lifecycle = input.operation === 'mark_invalid' ? 'invalid' : 'changed';
+      else if (['move', 'promote', 'demote'].includes(input.operation)) {
+        this.node(input.toNodeId); const ancestors = this.repo.ancestors(item.nodeId).map(n => n.id), chain = item.originChain ?? [item.originNodeId];
+        if (input.operation === 'promote' && (input.toNodeId === item.nodeId || !ancestors.includes(input.toNodeId))) fail('INVALID_PROMOTION', 'Promotion is restricted to ancestors');
+        if (input.operation === 'demote' && (input.toNodeId === item.nodeId || !chain.includes(input.toNodeId) || !this.repo.ancestors(input.toNodeId).some(n => n.id === item.nodeId))) fail('INVALID_DEMOTION', 'Demotion requires a recorded origin below current scope');
+        if (input.operation === 'move' && !exposure.nodeIds.includes(input.toNodeId)) fail('OUT_OF_SCOPE', 'Move requires evidence in its target scope');
+        updates = { ...updates, nodeId: input.toNodeId, validation: 'unverified', originChain: [...new Set([...chain, input.toNodeId])] };
+        for (const h of this.repo.list('tree_hooks', h => h.methodId === item.id && h.enabled)) this.replace('tree_hooks', h, { scopeNodeId: input.toNodeId });
+      } else if (['rewrite', 'harden', 'merge'].includes(input.operation)) {
+        let merged = null;
+        if (input.operation === 'merge') {
+          merged = this.item(input.mergeTargetId); this.repo.requireExpected(command, 'tree_items', merged.id);
+          if (merged.id === item.id || merged.activeVersion !== input.mergeTargetVersion || merged.kind !== item.kind || merged.nodeId !== item.nodeId || merged.lifecycle !== 'active' || !exposure.itemVersions.some(v => v.itemId === merged.id && v.version === merged.activeVersion)) fail('MERGE_CONFLICT', 'Merge requires two current exposed versions of the same kind and scope');
+          if (merged.userProtected && this.context().actor.kind !== 'user') fail('USER_PROTECTED', 'Merge cannot consume protected content');
+        }
+        const version = item.activeVersion + 1, old = this.version(item.id, item.activeVersion);
+        const refs = [...new Map([...old.sourceRefs, ...(merged ? this.version(merged.id, merged.activeVersion).sourceRefs : []), ...input.sourceRefs].map(ref => [canonicalJson(ref), ref])).values()];
+        if (item.kind === 'method') this.#method({ ...input.replacement, sourceRefs: refs }, item.nodeId, item);
+        else {
+          if (input.operation === 'harden') fail('METHOD_REQUIRED', 'Only methods can be hardened');
+          if (item.kind === 'understanding') text(input.replacement, 'replacement', 2000); else validateShort(input.replacement);
+          this.repo.save('tree_item_versions', { id: versionId(item.id, version), itemId: item.id, version, content: input.replacement, sourceKind: 'assistant_inferred', sourceRefs: refs, supersedes: old.version, reason: input.reason });
+          this.#copyBundle(item, old.version, version); updates.activeVersion = version; updates.validation = 'unverified';
+        }
+        if (merged) { this.#withdraw(merged, 'merged_into_version'); this.replace('tree_items', this.item(merged.id), { mergedInto: { itemId: item.id, version } }); }
+      }
+      const updated = this.replace('tree_items', this.item(item.id), updates);
+      if (['withdraw', 'mark_invalid', 'mark_changed'].includes(input.operation)) this.#withdraw(updated, input.reason, input.operation === 'withdraw' ? 'withdrawn' : updates.lifecycle);
+      if (input.operation !== 'support') for (const e of this.repo.list('tree_exposures', e => !e.revoked && e.itemVersions.some(v => v.itemId === item.id))) this.replace('tree_exposures', e, { revoked: true, invalidationReason: 'item_reviewed' });
+      const unclear = new Set();
+      for (const r of [...updates.reviews].reverse().filter(r => r.version === input.version)) { if (r.result !== 'unclear') break; unclear.add(r.windowId); }
+      const unclearWindows = unclear.size;
+      return { itemId: item.id, result, unclearWindows, needsReflection: unclearWindows >= 3 };
+    });
+  }
+}
+
+export class ReportService extends DomainService {
+  preview(reportId, { includeEvidence = false } = {}) {
+    this.actor([], true); const report = this.repo.get('tree_reports', reportId); if (!report) fail('REPORT_NOT_FOUND', 'Local report not found');
+    const safeText = value => String(value).replace(/(?:\/[\w.\-\p{L}]+){2,}/gu, '[路径已隐藏]').replace(/[“「"]([^”」"]*)[”」"]/gu, '[原话已隐藏]');
+    // Default export omits the original problem/evidence fields altogether:
+    // unmarked free text cannot be reliably distinguished from a raw quote.
+    return { reportId, revision: report.revision, category: safeText(report.category), step: safeText(report.step), problem: includeEvidence ? report.problem : '[原始问题描述已隐藏；可选择附证据]', whyUniversal: includeEvidence ? report.whyUniversal : '[详细诊断已隐藏]', suggestedFix: includeEvidence ? report.suggestedFix : '[详细建议已隐藏]', evidenceRefs: includeEvidence ? report.evidenceRefs : [], ...(includeEvidence && report.reviewOutput ? { reviewOutput: report.reviewOutput } : {}), status: report.status, includesEvidence: includeEvidence };
+  }
+  export(command) {
+    return this.repo.command('exportReport', command, this.actor([], true), () => {
+      shape(command.input, ['reportId', 'includeEvidence', 'previewHash']); if (typeof command.input.includeEvidence !== 'boolean') fail('INVALID_FIELD', 'Evidence choice must be boolean');
+      const report = this.repo.get('tree_reports', command.input.reportId); if (!report) fail('REPORT_NOT_FOUND', 'Report missing'); this.repo.requireExpected(command, 'tree_reports', report.id);
+      const preview = this.preview(report.id, command.input); if (digest(preview) !== command.input.previewHash) fail('PREVIEW_CHANGED', 'Preview changed before export');
+      this.replace('tree_reports', report, { exportAudit: [...report.exportAudit, { requestId: command.requestId, at: this.repo.now(), includeEvidence: command.input.includeEvidence, contentHash: digest(preview) }] }); return { content: preview };
+    });
+  }
+}

package/src/tree/jobs.mjs

@@ -0,0 +1,184 @@
+import { randomUUID } from 'node:crypto';
+import { CONTRACT, ROLES, array, canonicalJson, digest, fail, integer, jsonClone, oneOf, shape, text } from './contracts.mjs';
+import { compilePrompt, parseFinalOutput, outputBindings } from './prompts.mjs';
+import { recordKey } from './repository.mjs';
+
+export const ROLE_LIMITS = Object.freeze({ main: 8192, attribution: 2048, learning: 8192, consolidation: 8192, verification: 8192, improvement: 8192, script_writer: 8192 });
+export const WRITER_TOOLS = Object.freeze(['writer_read', 'writer_list', 'writer_search', 'writer_put', 'writer_probe', 'writer_finish']);
+export const TERMINAL_JOBS = Object.freeze(['committed', 'failed', 'unknown', 'invalid_output', 'stale', 'cancelled']);
+const priority = { attribution: 0, script_writer: 1, learning: 2, consolidation: 3, verification: 4, improvement: 5, main: 0 };
+const triggers = {
+  main: ['user_turn'], attribution: ['human_input'], learning: ['settled_main_turn', 'assignment_correction'],
+  consolidation: ['threshold', 'leave_timeout', 'node_complete'], verification: ['window', 'cluster', 'stagnation', 'assignment_correction'],
+  improvement: ['repair_group'], script_writer: ['explicit_script_request', 'learned_script_request'],
+};
+export function freezeModelConfig(role, value) {
+  shape(value, ['provider', 'model', 'reasoningEffort', 'maxTokens', 'preset', 'cwd', 'modelVersion', 'priceVersion', 'budgetScope', 'stage']);
+  for (const key of ['provider', 'model', 'preset', 'cwd', 'modelVersion', 'priceVersion', 'budgetScope', 'stage']) text(value[key], key, 4096);
+  if (!value.cwd.startsWith('/')) fail('CONFIG_PATH', 'Explicit absolute working directory required');
+  oneOf(value.reasoningEffort, ['off', 'low', 'high', 'max'], 'reasoning effort'); integer(value.maxTokens, 'maxTokens', 1, role === 'main' && value.budgetScope !== 'arcfold-tree-v3-150cny' ? Number.MAX_SAFE_INTEGER : ROLE_LIMITS[role]); return jsonClone(value);
+}
+
+export class TreeJobs {
+  constructor({ repository, assertSources, now = () => Date.now() }) {
+    if (typeof assertSources !== 'function') fail('SOURCE_RESOLVER_REQUIRED', 'Jobs require a trusted source recheck');
+    this.repo = repository; this.assertSources = assertSources; this.now = now;
+  }
+  get(id) { const job = this.repo.get('tree_jobs', id); if (!job) fail('JOB_NOT_FOUND', 'Model job not found'); return job; }
+  #command(type, requestId, input, expected, mutation) { return this.repo.command(type, { requestId, input, expected }, { kind: 'program', id: 'tree-model-jobs' }, mutation); }
+  #replace(job, updates) { return this.repo.save('tree_jobs', { ...job, ...updates }, job.revision); }
+  assertCurrent(job) {
+    if (job.invalidated || ['stale', 'cancelled'].includes(job.status)) fail('JOB_STALE', 'Job scope was invalidated');
+    for (const [key, revision] of Object.entries(job.inputRevisionSet)) { const index = key.indexOf(':'); if (index < 1 || this.repo.get(key.slice(0, index), key.slice(index + 1))?.revision !== revision) fail('JOB_STALE', 'A frozen input revision changed'); }
+    const checked = this.assertSources(job.input.sources);
+    if (checked?.then) fail('ASYNC_GUARD', 'Source recheck must be synchronous'); if (checked === false) fail('JOB_STALE', 'A frozen source changed or was withdrawn');
+    if (digest(job.input) !== job.inputHash || digest(job.modelConfig) !== job.modelConfigHash || digest(job.prompt.text) !== job.promptHash) fail('JOB_CORRUPT', 'Frozen model input was altered');
+    return true;
+  }
+  enqueue({ role, key, nodeIds, input, revisionSet, config, trigger }) {
+    oneOf(role, ROLES, 'role'); text(key, 'stable job key', 512); array(nodeIds, 'nodeIds', 8); if (!nodeIds.length) fail('JOB_SCOPE', 'At least one node is required');
+    if (!trigger || !triggers[role].includes(trigger.kind)) fail('JOB_TRIGGER', 'Role requires an explicit host trigger');
+    if (['main', 'attribution', 'learning'].includes(role) && !['main', 'user', 'program'].includes(trigger.producerRole)) fail('RECURSIVE_JOB', 'Auxiliary events cannot recursively schedule user learning');
+    if (['main', 'attribution'].includes(role) && trigger.origin !== 'user') fail('PROGRAM_NOT_USER', 'Only real human input starts a logical user turn');
+    if (role === 'learning' && (trigger.kind === 'settled_main_turn' ? trigger.producerRole !== 'main' || trigger.status !== 'settled' : trigger.actorKind !== 'user')) fail('RECURSIVE_JOB', 'Learning requires settled main experience or a trusted user correction');
+    if (role === 'learning' && nodeIds.length !== 1) fail('JOB_SCOPE', 'Each learning job belongs to one node');
+    const id = digest(['model_job', role, key]), prompt = compilePrompt(role), modelConfig = freezeModelConfig(role, config);
+    const envelope = { ...jsonClone(input), inputVersion: CONTRACT, role, jobId: id, trigger: jsonClone(trigger) };
+    if (canonicalJson(envelope.scope?.nodeIds) !== canonicalJson(nodeIds) || !Array.isArray(envelope.sources) || !Array.isArray(envelope.knownItems) || !envelope.allowedIds) fail('INPUT_CONTRACT', 'A complete frozen scope and reference envelope is required');
+    if (['learning', 'verification', 'improvement'].includes(role)) envelope.outputBindings = outputBindings(envelope);
+    for (const nodeId of nodeIds) { const node = this.repo.get('tree_nodes', nodeId); if (!node || node.deleted) fail('JOB_SCOPE', 'Unknown scope node'); }
+    const inputHash = digest(envelope), inputRevisionSet = jsonClone(revisionSet), specification = { role, key, nodeIds, inputHash, inputRevisionSet, modelConfig, promptHash: prompt.hash };
+    // Retry under another caller request id must still find this same job.
+    const existing = this.repo.get('tree_jobs', id);
+    if (existing) { if (existing.specificationHash !== digest(specification)) fail('JOB_IDENTITY_CONFLICT', 'A job key cannot be reused with different frozen input or configuration'); return existing; }
+    this.#command('enqueueModelJob', digest(['enqueue', id]), specification, inputRevisionSet, () => {
+      const job = { id, kind: role, role, scopeKey: nodeIds.join(','), nodeIds, input: envelope, inputHash, inputRevisionSet, modelConfig, modelConfigHash: digest(modelConfig), prompt, promptHash: prompt.hash, specificationHash: digest(specification), status: 'queued', trigger, nativeSessionId: null, invocationIds: [], enqueuedOrder: trigger.ordinal ?? this.repo.meta().lastEventOrdinal };
+      this.assertCurrent(job); this.repo.save('tree_jobs', job); return { jobId: id };
+    }); return this.get(id);
+  }
+  prepare(id, workerId = 'local-worker') {
+    const current = this.get(id); if (current.status !== 'queued') return current;
+    this.#command('prepareModelJob', digest(['prepare', id]), { jobId: id, workerId }, { [recordKey('tree_jobs', id)]: current.revision }, () => {
+      const job = this.get(id); this.assertCurrent(job);
+      const active = this.repo.list('tree_jobs', j => ['prepared', 'submitted', 'result_received', 'validated'].includes(j.status));
+      if (!['main', 'attribution'].includes(job.role) && active.filter(j => !['main', 'attribution'].includes(j.role)).length >= 2) fail('WORKER_BUSY', 'Two background model jobs are already active');
+      if (job.role === 'script_writer' && active.some(j => j.role === 'script_writer')) fail('WRITER_BUSY', 'Only one writer may run');
+      if (['learning', 'consolidation'].includes(job.role)) {
+        if (this.repo.list('tree_jobs', j => j.role === 'learning' && j.status === 'unknown' && j.nodeIds.some(n => job.nodeIds.includes(n))).length) fail('LEARNING_UNKNOWN', 'Resolve the uncertain prior learning request before reusing its session');
+        if (active.some(j => ['learning', 'consolidation'].includes(j.role) && j.nodeIds.some(n => job.nodeIds.includes(n)))) fail('NODE_BUSY', 'This node already has an active learning/consolidation writer');
+        if (this.repo.list('tree_jobs', j => j.id !== id && j.status === 'queued' && ['learning', 'consolidation'].includes(j.role) && j.nodeIds.some(n => job.nodeIds.includes(n)) && j.enqueuedOrder < job.enqueuedOrder).length) fail('NODE_ORDER', 'Earlier node experience must be processed first');
+      }
+      let nativeSessionId = `session-${randomUUID()}`, contextEpoch = 1;
+      if (job.role === 'main') { text(job.trigger.nativeSessionId, 'main native session', 512); integer(job.trigger.nativeTurn, 'main native turn', 1); nativeSessionId = job.trigger.nativeSessionId; }
+      if (job.role === 'learning') {
+        const sessionId = digest(['learning_session', job.nodeIds[0]]); let session = this.repo.get('tree_learning_sessions', sessionId);
+        if (!session) session = this.repo.save('tree_learning_sessions', { id: sessionId, nodeId: job.nodeIds[0], sessionId: nativeSessionId, contextEpoch: 1, appendSeq: 0, sourceWatermark: null, appliedChangeOrdinal: 0, estimateTokens: 0, history: [] });
+        if (session.paused) fail('LEARNING_PAUSED', 'Learning awaits successful context consolidation');
+        nativeSessionId = session.sessionId; contextEpoch = session.contextEpoch;
+      }
+      this.#replace(job, { status: 'prepared', nativeSessionId, contextEpoch, leaseOwner: workerId, preparedAt: this.repo.now() }); return { jobId: id, nativeSessionId, contextEpoch };
+    }); return this.get(id);
+  }
+  queued() { return this.repo.list('tree_jobs', j => j.status === 'queued' && ROLES.includes(j.role)).sort((a, b) => priority[a.role] - priority[b.role] || a.enqueuedOrder - b.enqueuedOrder || a.id.localeCompare(b.id)); }
+  transition(id, next, details = {}) {
+    const current = this.get(id); if (current.status === next) return current;
+    const allowed = { prepared: ['submitted', 'failed', 'stale', 'cancelled', 'unknown'], submitted: ['result_received', 'unknown', 'cancelled', 'stale'], unknown: ['result_received'], result_received: ['validated', 'invalid_output', 'stale', 'unknown'], validated: ['committed', 'stale', 'cancelled'], queued: ['failed', 'stale', 'cancelled'] };
+    if (!allowed[current.status]?.includes(next)) fail('JOB_TRANSITION', `Cannot change ${current.status} to ${next}`);
+    this.#command('transitionModelJob', digest(['transition', id, current.status, next, current.revision]), { jobId: id, next, details }, { [recordKey('tree_jobs', id)]: current.revision }, () => {
+      this.#replace(current, { ...details, status: next, ...(TERMINAL_JOBS.includes(next) ? { leaseOwner: null } : {}) }); return { jobId: id, status: next };
+    }); return this.get(id);
+  }
+  submit(id) { const job = this.get(id); this.assertCurrent(job); return this.transition(id, 'submitted', { submittedAt: this.repo.now(), startedMs: this.now() }); }
+  failBeforeInvocation(id, { nativeLogRef, eventsHash, reason }) {
+    const job = this.get(id);
+    if (!['submitted', 'unknown'].includes(job.status) || job.invocationIds.length || this.repo.list('tree_invocations', call => call.jobId === id).length) fail('INVOCATION_EXISTS', 'Only a durably ended, never admitted request can be recorded as not sent');
+    text(nativeLogRef, 'native failure receipt', 4096); text(eventsHash, 'native failure hash', 128); text(reason, 'native failure reason', 4096);
+    this.#command('recordPreDispatchFailure', digest(['not-sent', id, eventsHash]), { jobId: id, nativeLogRef, eventsHash, reason }, { [recordKey('tree_jobs', id)]: job.revision }, () => {
+      this.#replace(job, { status: 'failed', leaseOwner: null, nativeLogRef, eventsHash, error: { code: 'NATIVE_PRE_DISPATCH', message: reason }, notSent: true }); return { jobId: id, status: 'failed' };
+    }); return this.get(id);
+  }
+  recordError(id, error) {
+    const job = this.get(id), details = { code: error.code ?? 'HOST_ERROR', message: error.message };
+    this.#command('recordModelJobError', digest(['job-error', id, job.revision]), { jobId: id, error: details }, { [recordKey('tree_jobs', id)]: job.revision }, () => {
+      this.#replace(job, { error: details }); return { jobId: id };
+    }); return this.get(id);
+  }
+  bindMessage(id, message) {
+    const job = this.get(id);
+    if (job.nativeMessage) { if (canonicalJson(job.nativeMessage) !== canonicalJson(message)) fail('MESSAGE_CONFLICT', 'The native input identity is immutable'); return job; }
+    if (job.status !== 'prepared' || message.role !== 'user' || !message.id || message.source?.kind !== 'arcfold/tree-job' || message.source.jobId !== job.id || message.source.inputHash !== job.inputHash || canonicalJson(message.content) !== canonicalJson([{ type: 'text', text: canonicalJson(job.input) }])) fail('MESSAGE_CONFLICT', 'Exact host-created input message required before submission');
+    this.#command('bindModelMessage', digest(['native-message', id]), { jobId: id, message }, { [recordKey('tree_jobs', id)]: job.revision }, () => { this.#replace(job, { nativeMessage: jsonClone(message) }); return { jobId: id, messageId: message.id }; }); return this.get(id);
+  }
+  admitInvocation(id, { turn, step, stepStartSeq, requestHash, allowedTools }) {
+    const job = this.get(id); if (job.status !== 'submitted') fail('JOB_NOT_SUBMITTED', 'Request has no submitted job'); this.assertCurrent(job);
+    for (const n of [turn, step, stepStartSeq]) integer(n, 'native position', 0);
+    const position = { sessionId: job.nativeSessionId, turn, step, stepStartSeq }, requestId = `dsh-messages-${digest(position)}`, invocationId = digest(['tree_invocation', requestId]);
+    const existing = this.repo.get('tree_invocations', invocationId);
+    if (existing) { if (existing.jobId !== id || existing.requestHash !== requestHash || existing.state !== 'admitted') fail('INVOCATION_REPLAY', 'Native position already owns a different or finished request'); return existing; }
+    if (job.role !== 'main' && job.role !== 'script_writer' && job.invocationIds.length >= 1) fail('ROLE_CALL_LIMIT', 'Reader roles have one model request per job');
+    if (job.role === 'script_writer' && (job.invocationIds.length >= 12 || this.now() - job.startedMs >= 120000)) fail('WRITER_LIMIT', 'Writer step/time limit reached');
+    const tools = [...allowedTools].sort();
+    if (!['main', 'script_writer'].includes(job.role) && tools.length || job.role === 'script_writer' && tools.some(t => !WRITER_TOOLS.includes(t))) fail('ROLE_TOOLS', 'Role tools exceed the frozen allowlist');
+    this.#command('admitModelInvocation', digest(['admit', invocationId]), { jobId: id, position, requestHash, allowedTools: tools }, { [recordKey('tree_jobs', id)]: job.revision }, () => {
+      this.repo.save('tree_invocations', { id: invocationId, jobId: id, role: job.role, nativeSessionId: job.nativeSessionId, nativeTurn: turn, nativeStep: step, stepStartSeq, ordinal: job.invocationIds.length + 1, modelConfigHash: job.modelConfigHash, promptHash: job.promptHash, inputHash: job.inputHash, requestHash, allowedTools: tools, state: 'admitted', ledgerRequestId: requestId });
+      this.#replace(job, { invocationIds: [...job.invocationIds, invocationId] }); return { invocationId, requestId };
+    }); return this.repo.get('tree_invocations', invocationId);
+  }
+  invocationResult(invocationId, details) {
+    const invocation = this.repo.get('tree_invocations', invocationId); if (!invocation) fail('INVOCATION_MISSING', 'No request identity');
+    shape(details, ['state'], ['usage', 'resultHash', 'nativeLogRef']); oneOf(details.state, ['result_received', 'unknown'], 'invocation result');
+    if (invocation.state === 'result_received') { if (details.resultHash !== invocation.resultHash) fail('RESULT_CONFLICT', 'A request has one immutable result'); return invocation; }
+    this.#command('recordInvocationResult', digest(['invocation-result', invocationId, details.state]), { invocationId, ...details }, { [recordKey('tree_invocations', invocationId)]: invocation.revision }, () => { this.repo.save('tree_invocations', { ...invocation, ...details }, invocation.revision); return { invocationId }; }); return this.repo.get('tree_invocations', invocationId);
+  }
+  receive(id, { message, nativeLogRef, eventsHash }) {
+    const job = this.get(id); text(nativeLogRef, 'durable native log reference', 4096); text(eventsHash, 'native events hash', 128);
+    const resultHash = digest(message);
+    if (job.resultHash) {
+      if (job.resultHash !== resultHash) fail('RESULT_CONFLICT', 'A job cannot replace its received result');
+      return job.status === 'unknown' ? this.transition(id, 'result_received') : job;
+    }
+    return this.transition(id, 'result_received', { rawMessage: jsonClone(message), resultHash, nativeLogRef, eventsHash, resultReceivedAt: this.repo.now() });
+  }
+  validate(id) {
+    const job = this.get(id); if (['validated', 'committed', 'invalid_output', 'stale'].includes(job.status)) return job;
+    if (job.status !== 'result_received') fail('RESULT_REQUIRED', 'Durable received output required');
+    try {
+      this.assertCurrent(job);
+      const parsed = job.role === 'main' ? { result: { message: job.rawMessage }, rawHash: digest(job.rawMessage) } : parseFinalOutput(job.role, job.rawMessage, job.input);
+      return this.transition(id, 'validated', { validatedResult: parsed.result, outputEnvelope: { schemaVersion: CONTRACT, jobId: id, inputHash: job.inputHash, result: parsed.result }, rawHash: parsed.rawHash, rejectedItems: parsed.rejectedItems ?? [] });
+    } catch (e) { return this.transition(id, e.code === 'JOB_STALE' ? 'stale' : 'invalid_output', { error: { code: e.code ?? 'OUTPUT_JSON', message: e.message, validationErrors: e.validationErrors ?? e.errors ?? [] }, rawHash: e.rawHash ?? digest(job.rawMessage) }); }
+  }
+  commit(id, applyResult = () => ({})) {
+    const job = this.get(id); if (job.status === 'committed') return job;
+    if (job.status !== 'validated') fail('VALIDATED_REQUIRED', 'Only validated output can commit');
+    try {
+      return this.repo.transaction(() => {
+        this.assertCurrent(this.get(id));
+        const result = applyResult(jsonClone(job.validatedResult), { job, requestId: digest(['apply-model-result', id]) });
+        if (result?.then) fail('ASYNC_COMMIT', 'Domain application must be synchronous');
+        if (job.role === 'learning') {
+          const s = this.repo.get('tree_learning_sessions', digest(['learning_session', job.nodeIds[0]]));
+          if (s.sessionId !== job.nativeSessionId || s.contextEpoch !== job.contextEpoch) fail('JOB_STALE', 'Learning epoch changed');
+          this.#command('appendLearningReceipt', digest(['learning-append', id]), { jobId: id }, { [recordKey('tree_learning_sessions', s.id)]: s.revision }, () => {
+            this.repo.save('tree_learning_sessions', { ...s, appendSeq: s.appendSeq + 1, sourceWatermark: job.trigger.watermark ?? job.trigger.ordinal ?? s.sourceWatermark, appliedChangeOrdinal: this.repo.meta().lastEventOrdinal, history: [...s.history, { jobId: id, turnId: job.trigger.turnId ?? null, sourceRefs: job.input.sources.map(s => s.ref), nativeLogRef: job.nativeLogRef, resultHash: job.resultHash, receipt: jsonClone(result), inputHash: job.inputHash }] }, s.revision); return { nodeId: s.nodeId };
+          });
+        }
+        return this.transition(id, 'committed', { resultRef: jsonClone(result), committedAt: this.repo.now() });
+      });
+    } catch (e) { if (e.code === 'JOB_STALE') return this.transition(id, 'stale', { error: { code: e.code, message: e.message } }); throw e; }
+  }
+  replaceEpoch(nodeId, { summaryId, sourceWatermark, recentJobIds, summaryHash }) {
+    const session = this.repo.get('tree_learning_sessions', digest(['learning_session', nodeId])); if (!session) fail('SESSION_REQUIRED', 'Learning session missing');
+    const summary = this.repo.get('tree_summaries', summaryId);
+    if (!summary || summary.nodeId !== nodeId || digest(summary) !== summaryHash || canonicalJson(session.history.slice(-3).map(h => h.jobId)) !== canonicalJson(recentJobIds) || sourceWatermark === undefined || summary.sourceWatermark !== sourceWatermark || canonicalJson(summary.coveredJobIds ?? []) !== canonicalJson(session.history.slice(0, -3).map(h => h.jobId))) fail('EPOCH_COVERAGE', 'A verified summary, exact coverage watermark and latest three learning jobs are required');
+    if (this.repo.list('tree_jobs', j => j.nodeIds?.includes(nodeId) && ['prepared', 'submitted', 'result_received', 'validated'].includes(j.status)).length) fail('NODE_BUSY', 'Cannot replace an active learning epoch');
+    const id = digest(['epoch', nodeId, session.contextEpoch + 1]);
+    this.#command('replaceLearningEpoch', id, { nodeId, summaryId, sourceWatermark, recentJobIds, summaryHash }, { [recordKey('tree_learning_sessions', session.id)]: session.revision }, () => {
+      this.repo.save('tree_learning_sessions', { ...session, sessionId: `session-${randomUUID()}`, previousSessions: [...(session.previousSessions ?? []), { sessionId: session.sessionId, contextEpoch: session.contextEpoch }], contextEpoch: session.contextEpoch + 1, appendSeq: 0, summaryId, summaryHash, sourceWatermark, recentJobIds, paused: false, estimateTokens: 0 }, session.revision); return { nodeId, epoch: session.contextEpoch + 1 };
+    }); return this.repo.get('tree_learning_sessions', session.id);
+  }
+  pauseLearning(nodeId, reason) {
+    const s = this.repo.get('tree_learning_sessions', digest(['learning_session', nodeId])); if (!s) fail('SESSION_REQUIRED', 'Learning session missing'); text(reason, 'pause reason');
+    this.#command('pauseLearningEpoch', digest(['pause-learning', s.id, s.revision]), { nodeId, reason }, { [recordKey('tree_learning_sessions', s.id)]: s.revision }, () => { this.repo.save('tree_learning_sessions', { ...s, paused: true, pauseReason: reason }, s.revision); return { nodeId }; });
+  }
+}