@arcfold/dsh 0.0.0-stage → 0.4.0

package/src/tree/consolidation.mjs

@@ -0,0 +1,103 @@
+import { CONTRACT, canonicalJson, digest, fail, integer, jsonClone } from './contracts.mjs';
+import { validateOutput } from './prompts.mjs';
+
+export class ConsolidationService {
+  constructor({ repository, experience, contextBuilder, jobs }) { Object.assign(this, { repo: repository, experience, builder: contextBuilder, jobs }); }
+  plan(nodeId, reason) {
+    if (!['threshold', 'leave_timeout', 'node_leave', 'node_complete'].includes(reason)) fail('SUMMARY_TRIGGER', 'Unknown consolidation trigger');
+    const node = this.builder.node(nodeId), turns = this.experience.turns(nodeId), session = this.repo.list('tree_learning_sessions', s => s.nodeId === nodeId)[0];
+    // A hidden/revoked version still owns its immutable version number.
+    const previous = node.currentSummaryId && this.repo.get('tree_summaries', node.currentSummaryId), threshold = reason === 'threshold', history = session?.history ?? [];
+    const coveredJobs = threshold ? history.slice(0, -3) : history;
+    const selected = threshold ? turns.filter(t => coveredJobs.some(h => h.turnId === t.id)) : turns;
+    if (!selected.length) return null;
+    const throughTurnIds = selected.map(t => t.id), assignmentVersions = Object.fromEntries(selected.map(t => [t.id, t.assignmentRevision]));
+    if (!threshold && canonicalJson(previous?.throughTurnIds ?? []) === canonicalJson(throughTurnIds) && canonicalJson(previous?.assignmentVersions ?? {}) === canonicalJson(assignmentVersions)) return null;
+    const material = selected.map(t => this.experience.material(t));
+    if (material.some(m => m.revokedRefs.length)) fail('SUMMARY_SOURCE_REVOKED', 'Do not silently summarize missing original evidence');
+    const sourceWatermark = digest([throughTurnIds, assignmentVersions, material.map(m => m.nativeHash)]);
+    const learningRecords = coveredJobs.map(entry => {
+      const job = this.jobs.get(entry.jobId), input = jsonClone(job.input); delete input.epochSeed;
+      if (job.status !== 'committed') fail('SUMMARY_LEARNING_RECEIPT', 'Only committed learning can enter a stable summary');
+      const turn = job.trigger.turnId && this.repo.get('tree_turns', job.trigger.turnId);
+      if (job.invalidated || turn && !turn.nodeIds.includes(nodeId) || job.input.sources.some(s => !this.experience.sources.resolve(s.ref))) return { jobId: job.id, invalidated: true, reason: '来源已撤回或归属已纠正；旧输入和输出不再作为本节点整理依据。', inputHash: job.inputHash, resultHash: job.resultHash };
+      return { jobId: job.id, input, output: job.validatedResult, receipt: job.resultRef, nativeLogRef: job.nativeLogRef, invalidated: job.invalidated === true };
+    });
+    return { nodeId, reason, throughTurnIds, assignmentVersions, material, sourceWatermark,
+      learningRecords,
+      previousSummaryId: previous?.id ?? null, previousVersion: previous?.version ?? null, nodeRevision: node.revision,
+      coveredJobIds: coveredJobs.map(h => h.jobId), recentJobIds: history.slice(-3).map(h => h.jobId), contextEpoch: session?.contextEpoch ?? null };
+  }
+  freeze(plan) {
+    const context = this.builder.build([plan.nodeId], 'consolidation'), own = this.builder.node(plan.nodeId);
+    const siblings = this.repo.list('tree_nodes', n => !n.deleted && n.parentId === own.parentId && n.id !== own.id).map(n => n.id);
+    const items = this.builder.activeItems([...new Set([...context.ancestorPaths.flat(), ...siblings])], 'consolidation');
+    const sources = [...new Map(plan.material.flatMap(m => m.sources).map(s => [s.id, s])).values()];
+    const knownItems = items.map(({ item, version, method }) => ({ id: item.id, version: item.activeVersion, nodeId: item.nodeId, kind: item.kind, sourceKind: version.sourceKind, userProtected: item.userProtected, content: method ? { short: method.short, long: method.long } : version.content }));
+    const { material: _material, learningRecords, ...summaryPlan } = plan;
+    const learningHistory = learningRecords.map(record => {
+      if (!record.input) return record;
+      const { sources: originalSources, ...input } = record.input;
+      return { ...record, input: { ...input, sourceIds: originalSources.map(s => s.id) } };
+    });
+    const input = { inputVersion: CONTRACT, role: 'consolidation', scope: { nodeIds: [plan.nodeId], ancestorPaths: context.ancestorPaths, treeRevision: context.treeRevision }, sources, knownItems,
+      allowedIds: { nodeIds: [...new Set(context.ancestorPaths.flat())], fileIds: [], subjectIds: [] }, trigger: { reason: plan.reason }, changeReceipts: [], summaryPlan, learningHistory, constraints: context.segments };
+    const revisions = { [`tree_nodes:${plan.nodeId}`]: plan.nodeRevision };
+    for (const turnId of plan.throughTurnIds) revisions[`tree_turns:${turnId}`] = this.repo.get('tree_turns', turnId).revision;
+    for (const { item } of items) revisions[`tree_items:${item.id}`] = item.revision;
+    return { input, revisions };
+  }
+  applyResult(result, { job, requestId }) {
+    const output = validateOutput('consolidation', result, job.input), plan = job.input.summaryPlan, current = this.plan(plan.nodeId, plan.reason);
+    if (!current || current.sourceWatermark !== plan.sourceWatermark || current.previousSummaryId !== plan.previousSummaryId) fail('JOB_STALE', 'Summary source assignment or previous version changed');
+    const node = this.builder.node(plan.nodeId), version = (plan.previousVersion ?? 0) + 1, id = digest(['summary', node.id, version]);
+    const sourceRefs = [...new Map(job.input.sources.map(s => [canonicalJson(s.ref), s.ref])).values()];
+    return this.repo.command('commitTreeSummary', { requestId, expected: job.inputRevisionSet, input: { nodeId: node.id, jobId: job.id, sourceWatermark: plan.sourceWatermark, sourceRefs } }, { kind: 'model', id: job.id, role: 'consolidation' }, () => {
+      const { oneLine, ...body } = output.summary;
+      this.repo.save('tree_summaries', { id, nodeId: node.id, version, oneLine, body, throughTurnIds: plan.throughTurnIds, sourceRefs, previousVersion: plan.previousVersion,
+        sourceWatermark: plan.sourceWatermark, assignmentVersions: plan.assignmentVersions, coveredJobIds: plan.coveredJobIds, recentJobIds: plan.recentJobIds, reason: plan.reason, jobId: job.id });
+      this.repo.save('tree_nodes', { ...node, currentSummaryId: id, lastSummaryWatermark: plan.sourceWatermark }, node.revision);
+      // Broaden/retrospect remain versioned proposals for B5; this service never
+      // silently grants them item/method activation authority.
+      return { summaryId: id, version, nodeId: node.id, proposals: { broaden: output.broaden, retrospect: output.retrospect }, epochPending: plan.reason === 'threshold' };
+    });
+  }
+  finishEpoch(jobId) {
+    const job = this.jobs.get(jobId); if (job.status !== 'committed') fail('SUMMARY_NOT_COMMITTED', 'Only a committed durable summary can replace context');
+    const plan = job.input.summaryPlan; if (plan.reason !== 'threshold') return null;
+    const summary = this.repo.list('tree_summaries', s => s.jobId === jobId)[0];
+    if (!summary || summary.sourceRefs.some(ref => !this.experience.sources.resolve(ref))) fail('SUMMARY_SOURCE_REVOKED', 'Summary evidence is no longer current');
+    const session = this.repo.list('tree_learning_sessions', s => s.nodeId === plan.nodeId)[0];
+    if (session?.summaryId === summary.id && session.contextEpoch === plan.contextEpoch + 1) return session;
+    if (session?.contextEpoch !== plan.contextEpoch) fail('JOB_STALE', 'A different learning epoch already advanced');
+    return this.jobs.replaceEpoch(plan.nodeId, { summaryId: summary.id, summaryHash: digest(summary), sourceWatermark: summary.sourceWatermark, recentJobIds: plan.recentJobIds });
+  }
+  learningSeed(nodeId) {
+    const session = this.repo.list('tree_learning_sessions', s => s.nodeId === nodeId)[0];
+    if (!session || session.contextEpoch === 1 || session.appendSeq > 0) return null;
+    const summary = this.repo.get('tree_summaries', session.summaryId);
+    if (!summary || digest(summary) !== session.summaryHash || !this.builder.summary({ ...this.builder.node(nodeId), currentSummaryId: summary.id })) fail('EPOCH_COVERAGE', 'The new epoch requires its exact verified summary');
+    const recent = session.recentJobIds.map(id => {
+      const job = this.jobs.get(id); if (job.status !== 'committed' || job.invalidated || job.nodeIds[0] !== nodeId || job.input.sources.some(s => !this.experience.sources.resolve(s.ref))) fail('EPOCH_COVERAGE', 'Recent learning receipt or source is no longer valid');
+      const input = jsonClone(job.input); delete input.epochSeed;
+      return { jobId: job.id, input, output: job.validatedResult, receipt: job.resultRef, nativeLogRef: job.nativeLogRef };
+    });
+    return { contextEpoch: session.contextEpoch, summary: { id: summary.id, version: summary.version, oneLine: summary.oneLine, body: summary.body, sourceWatermark: summary.sourceWatermark }, recent, constraints: this.builder.build([nodeId], 'learning').segments };
+  }
+  pressure({ fullRequest, measure, contextWindow, maxOutputTokens }) {
+    integer(contextWindow, 'model context window'); integer(maxOutputTokens, 'output tokens');
+    const reading = measure(fullRequest);
+    if (reading?.then || reading?.kind !== 'exact' || reading.inputHash !== digest(fullRequest) || !Number.isSafeInteger(reading.tokens) || reading.tokens < 0 || !reading.tokenizerIdentity) fail('EXACT_TOKEN_COUNT_REQUIRED', 'Full prompt/messages/tools need a source-bound exact count; the host character heuristic is not proof');
+    const limit = Math.floor(Math.min(128000, contextWindow * 0.8, contextWindow - maxOutputTokens - 65536));
+    if (limit <= 0) fail('CONTEXT_CAPACITY', 'Model leaves no safe learning capacity');
+    return { tokens: reading.tokens, limit, needsSummary: reading.tokens > limit, tokenizerIdentity: reading.tokenizerIdentity, inputHash: reading.inputHash };
+  }
+  due(at = this.repo.now()) {
+    const now = Date.parse(at), result = [];
+    for (const node of this.repo.list('tree_nodes', n => !n.deleted && n.lastOwnTurnAt)) {
+      const timeout = this.builder.repo.ancestors(node.id).reverse().map(n => this.repo.get('tree_parameters', digest(['parameter', 'leaveTimeoutHours', n.id]))).find(Boolean)?.value ?? 24;
+      if (now - Date.parse(node.lastOwnTurnAt) >= timeout * 3600000) { const plan = this.plan(node.id, 'leave_timeout'); if (plan) result.push(plan); }
+    }
+    return result;
+  }
+}

package/src/tree/context.mjs

@@ -0,0 +1,211 @@
+import { canonicalJson, digest, fail, jsonClone } from './contracts.mjs';
+import { DomainService } from './tree.mjs';
+import { TREE_CONTEXT_SOURCE, assertOwnedCompaction } from './host-context.mjs';
+
+const actor = { kind: 'program', id: 'tree-context' };
+const versionId = (id, version) => digest(['item_version', id, version]);
+const retired = 'arcfold/tree-context-retired';
+
+export class ContextBuilder extends DomainService {
+  constructor(options) { super(options); this.sources = options.sources; this.mounted = new Map(); }
+  activeItems(nodeIds, role = 'main') {
+    return this.repo.listByNodeIds('tree_items', nodeIds, i => i.lifecycle === 'active' && !i.stale && i.activeVersion).flatMap(item => {
+      const version = this.repo.get('tree_item_versions', versionId(item.id, item.activeVersion));
+      if (!version || version.sourceRefs.some(ref => !this.resolveSource(ref))) return [];
+      if (item.kind === 'supplement') {
+        const supplement = this.repo.get('tree_supplements', digest(['supplement', item.id, item.activeVersion]));
+        if (!supplement || supplement.target !== role) return [];
+        return [{ item, version, supplement }];
+      }
+      if (item.kind === 'method') {
+        const method = this.repo.get('tree_methods', digest(['method', item.id, item.activeVersion]));
+        if (!method || method.pendingScriptRequests.length) return [];
+        return [{ item, version, method }];
+      }
+      return [{ item, version }];
+    }).sort((a, b) => nodeIds.indexOf(a.item.nodeId) - nodeIds.indexOf(b.item.nodeId) || a.item.id.localeCompare(b.item.id));
+  }
+  summary(node) {
+    const summary = node.currentSummaryId && this.repo.get('tree_summaries', node.currentSummaryId);
+    if (!summary || summary.sourceRefs.some(ref => !this.resolveSource(ref)) || summary.throughTurnIds.some(id => {
+      const turn = this.repo.get('tree_turns', id); return !turn?.nodeIds.includes(node.id) || turn.assignmentRevision !== summary.assignmentVersions[id];
+    })) return null;
+    return summary;
+  }
+  reusableComponent(source) {
+    if (!Array.isArray(source.sourceRefs)) return false;
+    let available;
+    try {
+      available = source.componentKey?.startsWith('cross-session:') && this.sources?.resolveMany
+        ? this.sources.resolveMany(source.sourceRefs).every(Boolean) : source.sourceRefs.every(ref => this.resolveSource(ref));
+    } catch { return false; }
+    return available &&
+      (source.itemVersions ?? []).every(v => { const item = this.repo.get('tree_items', v.itemId); return item && !item.stale && item.lifecycle !== 'invalid'; }) &&
+      (source.turnAssignments ?? []).every(v => { const turn = this.repo.get('tree_turns', v.turnId); return turn?.status === 'settled' && turn.assignmentRevision === v.assignmentRevision && turn.nodeIds.includes(v.nodeId); }) &&
+      (source.summaryVersions ?? []).every(v => Boolean(this.summary({ id: v.nodeId, currentSummaryId: digest(['summary', v.nodeId, v.version]) })));
+  }
+  crossSessionSegments(nodeIds, sessionId, currentTurn) {
+    const selected = new Set(nodeIds);
+    const turns = this.repo.list('tree_turns', turn => turn.status === 'settled' && turn.settledAt < currentTurn.startedAt && turn.sessionId !== sessionId && turn.nodeIds.some(id => selected.has(id)))
+      .sort((a, b) => a.startedAt.localeCompare(b.startedAt) || a.sessionId.localeCompare(b.sessionId) || a.nativeTurn - b.nativeTurn || a.id.localeCompare(b.id));
+    const recent = turns.slice(-6), entries = [], assignments = [], refs = [];
+    let resolved = null;
+    if (this.sources?.resolveMany) {
+      try {
+        const allRefs = recent.flatMap(turn => turn.experienceRefs ?? turn.sourceRefs);
+        const allSources = this.sources.resolveMany(allRefs);
+        resolved = new Map(allRefs.map((ref, index) => [digest(ref), allSources[index]]));
+      } catch { /* Individual turns below retain the conservative fallback. */ }
+    }
+    let usedBytes = 0, omitted = turns.length - recent.length;
+    for (const turn of recent.toReversed()) {
+      // A mixed-goal turn can contain private information from another branch.
+      // Do not send its unsplit original into a narrower current scope.
+      if (turn.nodeIds.some(id => !selected.has(id))) { omitted++; continue; }
+      let sources;
+      try { sources = resolved ? (turn.experienceRefs ?? turn.sourceRefs).map(ref => resolved.get(digest(ref))) : this.sources?.resolveMany ? this.sources.resolveMany(turn.experienceRefs ?? turn.sourceRefs) : (turn.experienceRefs ?? turn.sourceRefs).map(ref => this.resolveSource(ref)); }
+      catch { omitted++; continue; }
+      if (sources.some(source => !source)) { omitted++; continue; }
+      const visible = sources.filter(source => source.role === 'user' && source.origin === 'user' || source.role === 'assistant' && source.origin === 'model');
+      const messages = visible.map(source => ({ role: source.role, text: source.text, sourceId: source.id }));
+      const entry = { turnId: turn.id, sessionId: turn.sessionId, messages };
+      const bytes = Buffer.byteLength(canonicalJson(entry));
+      if (usedBytes + bytes > 48 * 1024) { omitted++; continue; }
+      usedBytes += bytes; entries.unshift(entry); refs.push(...visible.map(source => source.ref));
+      assignments.push({ turnId: turn.id, nodeId: turn.nodeIds.find(id => selected.has(id)), assignmentRevision: turn.assignmentRevision });
+    }
+    if (!turns.length) return [];
+    const value = { recentOtherSessions: entries, omittedTurns: omitted,
+      instruction: '这些是同一目标在其他聊天的原话和答复，不代表用户已采纳助手建议。若未覆盖所需经历，用历史工具查证。' };
+    return [{ key: 'cross-session:' + digest([...selected].sort()), nodeId: null, version: digest([value, assignments]),
+      text: canonicalJson(value), sourceRefs: refs, itemVersions: [], summaryVersions: [], turnAssignments: assignments }];
+  }
+  build(nodeIds, role = 'main') {
+    const paths = nodeIds.map(id => this.repo.ancestors(id)), ordered = [...new Map(paths.flat().map(n => [n.id, n])).values()];
+    const items = this.activeItems(ordered.map(n => n.id), role), itemVersions = items.map(({ item }) => ({ itemId: item.id, version: item.activeVersion }));
+    const summaries = ordered.map(n => this.summary(n)).filter(Boolean), summaryVersions = summaries.map(s => ({ nodeId: s.nodeId, version: s.version }));
+    const segments = ordered.map(node => {
+      const rows = items.filter(i => i.item.nodeId === node.id), summary = summaries.find(s => s.nodeId === node.id), own = nodeIds.includes(node.id);
+      const value = { target: { id: node.id, name: node.name, status: node.status, statusOrigin: node.statusOrigin },
+        understandings: rows.filter(r => r.item.kind === 'understanding').map(({ item, version }) => ({ id: item.id, version: item.activeVersion, source: version.sourceKind, validation: item.validation, content: version.content })),
+        rules: rows.filter(r => r.method?.short).map(({ item, method }) => ({ id: item.id, version: item.activeVersion, text: method.short })),
+        methods: rows.filter(r => r.method?.long).map(({ item, method }) => ({ id: item.id, version: item.activeVersion, name: method.long.name, description: method.long.description })),
+        supplements: rows.filter(r => r.supplement).map(({ item, version }) => ({ id: item.id, version: item.activeVersion, text: version.content })),
+        experience: summary ? { version: summary.version, oneLine: summary.oneLine, ...(own ? { body: summary.body } : {}) } : null,
+        children: own ? this.repo.list('tree_nodes', n => !n.deleted && n.parentId === node.id).map(n => ({ id: n.id, name: n.name, status: n.status, oneLine: this.summary(n)?.oneLine ?? '' })).sort((a, b) => a.id.localeCompare(b.id)) : [],
+        probes: own ? this.repo.list('tree_items', i => i.nodeId === node.id && i.lifecycle === 'active' && i.probe).map(i => ({ itemId: i.id, version: i.activeVersion, what: i.probe.what })) : [] };
+      const text = canonicalJson({ ...value, instruction: '同一节点以最后一份背景为准；旧版中没有继续列出的内容已撤销。' });
+      return { key: `node:${node.id}`, nodeId: node.id, version: digest(value), text,
+        sourceRefs: [...rows.flatMap(r => r.version.sourceRefs), ...(summary?.sourceRefs ?? [])],
+        itemVersions: rows.map(r => ({ itemId: r.item.id, version: r.item.activeVersion })), summaryVersions: summary ? [{ nodeId: node.id, version: summary.version }] : [] };
+    });
+    // Names/status/oneLine are the explicitly permitted global discovery view.
+    // No sibling understanding, method, source text or summary body enters it.
+    const overview = this.repo.list('tree_nodes', n => !n.deleted && n.status === 'active').map(n => ({ id: n.id, name: n.name, status: n.status, oneLine: this.summary(n)?.oneLine ?? '' })).sort((a, b) => a.id.localeCompare(b.id));
+    const text = canonicalJson({ globalOverview: overview });
+    segments.unshift({ key: 'global-overview', nodeId: null, version: digest(overview), text,
+      sourceRefs: this.repo.list('tree_nodes', n => !n.deleted && n.status === 'active').flatMap(n => this.summary(n)?.sourceRefs ?? []), itemVersions: [],
+      summaryVersions: this.repo.list('tree_nodes', n => !n.deleted && n.status === 'active').flatMap(n => { const summary = this.summary(n); return summary ? [{ nodeId: n.id, version: summary.version }] : []; }) });
+    return { role, nodeIds: [...nodeIds], ancestorPaths: paths.map(p => p.map(n => n.id)), segments, itemVersions, summaryVersions,
+      treeRevision: this.repo.meta().treeRevision, renderedHash: digest(segments), bytes: Buffer.byteLength(segments.map(s => s.text).join('\n')) };
+  }
+  scope(sessionId) { return this.repo.meta().contextSessions?.[sessionId] ?? null; }
+  async activate(sessionId, turnId, { cancelPrevious, expectedEpoch } = {}) {
+    const turn = this.repo.get('tree_turns', turnId);
+    if (!turn || turn.sessionId !== sessionId) fail('TURN_SCOPE', 'Only this native turn may choose its session scope');
+    const token = digest(['scope-transition', sessionId, turnId, turn.assignmentRevision]), previous = this.scope(sessionId);
+    if (previous?.token === token && previous.phase === 'active') return previous;
+    if (expectedEpoch !== undefined && previous?.epoch !== expectedEpoch) fail('SCOPE_STALE', 'Scope changed before transition');
+    if (previous && typeof cancelPrevious !== 'function') fail('SCOPE_CANCELLER_REQUIRED', 'An owned cancellation callback must stop previous scope execution');
+    const beginId = digest(['begin-scope', token]);
+    if (previous?.token !== token) this.repo.command('leaveTreeScope', { requestId: beginId, expected: { [`tree_turns:${turnId}`]: turn.revision }, input: { sessionId, turnId, token, sourceRefs: turn.userSourceRefs } }, actor, () => {
+      const meta = this.repo.meta(), old = meta.contextSessions?.[sessionId];
+      const scope = { token, phase: 'leaving', epoch: (old?.epoch ?? 0) + 1, nodeIds: turn.nodeIds, turnId, assignmentRevision: turn.assignmentRevision,
+        previousNodeIds: old?.nodeIds ?? [], leaveEvents: (old?.nodeIds ?? []).filter(id => !turn.nodeIds.includes(id)).map(nodeId => ({ type: 'node_leave', nodeId })), sourceRefs: turn.userSourceRefs };
+      this.repo.save('tree_meta', { ...meta, contextSessions: { ...meta.contextSessions, [sessionId]: scope } }, meta.revision); return scope;
+    });
+    const pending = this.scope(sessionId);
+    if (pending?.token !== token) fail('SCOPE_STALE', 'A later scope owns cancellation; do not cancel it from this old transition');
+    if (pending.previousNodeIds.length) await cancelPrevious(jsonClone(pending));
+    return this.repo.command('enterTreeScope', { requestId: digest(['finish-scope', token]), expected: {}, input: { sessionId, token, sourceRefs: turn.userSourceRefs } }, actor, () => {
+      const meta = this.repo.meta(), current = meta.contextSessions?.[sessionId], latest = this.repo.get('tree_turns', turnId);
+      if (current?.token !== token || latest.assignmentRevision !== turn.assignmentRevision) fail('SCOPE_STALE', 'A later turn/correction superseded this transition');
+      const scope = { ...current, phase: 'active', enteredAt: this.repo.now(), enterEvents: current.nodeIds.filter(id => !current.previousNodeIds.includes(id)).map(nodeId => ({ type: 'node_enter', nodeId })) };
+      this.repo.save('tree_meta', { ...meta, contextSessions: { ...meta.contextSessions, [sessionId]: scope } }, meta.revision); return scope;
+    }).result;
+  }
+  capture(sessionId, role = 'main') {
+    const scope = this.scope(sessionId), turn = scope && this.repo.get('tree_turns', scope.turnId);
+    if (!scope || scope.phase !== 'active' || scope.assignmentRevision !== turn?.assignmentRevision || canonicalJson(scope.nodeIds) !== canonicalJson(turn.nodeIds)) fail('SCOPE_STALE', 'No active current assignment scope');
+    const value = { ...this.build(scope.nodeIds, role), scopeEpoch: scope.epoch, turnId: scope.turnId, assignmentRevision: scope.assignmentRevision };
+    if (role === 'main') {
+      value.segments.push(...this.crossSessionSegments(scope.nodeIds, sessionId, turn));
+      value.renderedHash = digest(value.segments);
+      value.bytes = Buffer.byteLength(value.segments.map(s => s.text).join('\n'));
+    }
+    return { ...value, key: digest(value) };
+  }
+  assertCurrent(sessionId, snapshot) { if (this.capture(sessionId, snapshot.role).key !== snapshot.key) fail('CONTEXT_STALE', 'Scope, versions or source availability changed before dispatch'); return true; }
+  expose(sessionId, invocationId, boundaryIndex, snapshot) {
+    this.assertCurrent(sessionId, snapshot);
+    const mounted = this.mounted.get(sessionId);
+    if (mounted && (mounted.snapshotKey !== snapshot.key || mounted.messages.some(m => !this.reusableComponent(m.source)))) fail('CONTEXT_STALE', 'Native projection must be refreshed before exposure');
+    const messages = mounted?.messages, visibleVersions = messages ? [...new Map(messages.flatMap(m => m.source.itemVersions ?? []).map(v => [canonicalJson(v), v])).values()] : snapshot.itemVersions;
+    const id = digest(['exposure', invocationId]), existing = this.repo.get('tree_exposures', id);
+    if (existing) { if (existing.contextKey !== snapshot.key || existing.revoked) fail('EXPOSURE_CHANGED', 'An invocation cannot change exposure'); return existing; }
+    this.repo.command('recordTreeExposure', { requestId: id, expected: {}, input: { invocationId, contextKey: snapshot.key } }, actor, () => {
+      this.repo.save('tree_exposures', { id, invocationId, role: snapshot.role, nodeIds: snapshot.nodeIds, itemVersions: snapshot.itemVersions, visibleItemVersions: visibleVersions, summaryVersions: snapshot.summaryVersions,
+        renderedHash: messages ? digest(messages) : snapshot.renderedHash, contextKey: snapshot.key, treeRevision: snapshot.treeRevision, modelSessionId: sessionId, boundaryIndex, scopeEpoch: snapshot.scopeEpoch,
+        bytes: messages ? Buffer.byteLength(canonicalJson(messages)) : snapshot.bytes }); return { exposureId: id };
+    }); return this.repo.get('tree_exposures', id);
+  }
+}
+
+/** Per-component native projection: unchanged ancestors keep their position. */
+export function mountTreeContext(ctx, { builder, sessionId, createUserMessage }) {
+  let session; const disposers = [];
+  disposers.push(ctx.on('agent/pre-step', async (payload, next) => {
+    const decision = await next(); if (decision.kind === 'reject') return decision;
+    payload.signal.throwIfAborted(); session = payload.agent.session;
+    if (session.id !== sessionId) fail('CONTEXT_SESSION', 'Context owner cannot mount another native session');
+    assertOwnedCompaction(session); const snapshot = builder.capture(sessionId), current = new Map(snapshot.segments.map(s => [s.key, s])), retainedMessages = [], latest = new Map();
+    for (const seq of [...session.surface.nodes]) {
+      const event = session.eventAt(seq); if (event.type !== 'user/message' || event.data.source?.kind !== TREE_CONTEXT_SOURCE) continue;
+      const source = event.data.source, segment = current.get(source.componentKey);
+      // Preserve earlier same-scope versions for a stable prefix, but never
+      // retain an out-of-scope component or withdrawn original evidence.
+      if (segment && (!segment.key.startsWith('cross-session:') || source.componentVersion === segment.version) && builder.reusableComponent(source)) {
+        retainedMessages.push(event.data); latest.set(segment.key, event.data); continue;
+      }
+      session.append('user/message', createUserMessage({ source: { kind: retired }, content: [{ type: 'text', text: '[previous Arcfold component retired]' }] }), { surfaceOp: { op: 'replace', startSeq: seq, endSeq: seq }, sourceEventSeqs: [seq] });
+    }
+    if (decision.messages.some(m => [TREE_CONTEXT_SOURCE, retired].includes(m.source?.kind))) fail('CONTEXT_OWNER', 'Only the scoped context owner may inject its messages');
+    const additions = [];
+    for (const segment of snapshot.segments) {
+      const previous = latest.get(segment.key); if (previous?.source.componentVersion === segment.version) continue;
+      let text = segment.text, overview;
+      if (segment.key === 'global-overview') {
+        overview = JSON.parse(segment.text).globalOverview;
+        if (previous?.source.overview) {
+          const old = new Map(previous.source.overview.map(row => [row.id, row])), now = new Set(overview.map(row => row.id));
+          const changes = [...overview.filter(row => !old.has(row.id) || canonicalJson(row) !== canonicalJson(old.get(row.id))), ...[...old.values()].filter(row => !now.has(row.id)).map(row => ({ id: row.id, removed: true }))];
+          text = canonicalJson({ globalOverviewChanges: changes, instruction: '只更新这些节点；同一编号以最后一行为准，removed 表示不再列入进行中概貌。' });
+        }
+      }
+      additions.push(createUserMessage({ source: { kind: TREE_CONTEXT_SOURCE, componentKey: segment.key, componentVersion: segment.version, sourceRefs: segment.sourceRefs, itemVersions: segment.itemVersions, summaryVersions: segment.summaryVersions, ...(segment.turnAssignments ? { turnAssignments: segment.turnAssignments } : {}), ...(overview ? { overview } : {}) }, content: [{ type: 'text', text }] }));
+    }
+    builder.mounted.set(sessionId, { snapshotKey: snapshot.key, messages: [...retainedMessages, ...additions] });
+    return { ...decision, messages: [...decision.messages, ...additions] };
+  }));
+  disposers.push(ctx.on('llm/stream', (options, next) => {
+    if (!session || options.sessionId !== sessionId) return next();
+    return (async function* () {
+      options.signal?.throwIfAborted(); assertOwnedCompaction(session);
+      const snapshot = builder.capture(sessionId), actual = options.messages.filter(m => m.source?.kind === TREE_CONTEXT_SOURCE);
+      const mounted = builder.mounted.get(sessionId);
+      if (mounted?.snapshotKey !== snapshot.key || actual.some(m => !builder.reusableComponent(m.source)) || canonicalJson(actual) !== canonicalJson(mounted.messages)) fail('CONTEXT_STALE', 'Actual native input differs from the prepared current-scope projection');
+      yield* next();
+    })();
+  }));
+  return async () => { builder.mounted.delete(sessionId); for (const dispose of disposers.reverse()) await dispose(); };
+}

package/src/tree/contracts.mjs

@@ -0,0 +1,142 @@
+import { createHash } from 'node:crypto';
+import { DomainError, canonicalJson, jsonClone } from '../store.mjs';
+export { canonicalJson, jsonClone };
+export const SCHEMA = 'arcfold.goal-tree/v3';
+export const SCHEMA_VERSION = 1;
+export const CONTRACT = 'arcfold.tree.v3.1';
+export const digest = value => createHash('sha256').update(canonicalJson(value)).digest('hex');
+export const fail = (code, message, status = 409) => { throw new DomainError(code, message, status); };
+export const count = text => [...text].length;
+export function text(value, field, max = 2000, empty = false) {
+  if (typeof value !== 'string' || value.includes('\0') || (!empty && !value.trim()) || count(value) > max) fail('INVALID_FIELD', `Invalid ${field}`, 400);
+  return value;
+}
+export function array(value, field, max = 2000) {
+  if (!Array.isArray(value) || value.length > max) fail('INVALID_FIELD', `Invalid ${field}`, 400); return value;
+}
+export function oneOf(value, choices, field) { if (!choices.includes(value)) fail('INVALID_FIELD', `Invalid ${field}`, 400); return value; }
+export function integer(value, field, min = 1, max = Number.MAX_SAFE_INTEGER) {
+  if (!Number.isSafeInteger(value) || value < min || value > max) fail('INVALID_FIELD', `Invalid ${field}`, 400); return value;
+}
+export function shape(value, required, optional = []) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || required.some(k => !Object.hasOwn(value, k)) ||
+      Object.keys(value).some(k => !required.includes(k) && !optional.includes(k))) fail('INVALID_SHAPE', 'Missing or unknown fields', 400);
+  return value;
+}
+export const STATUSES = ['active', 'paused', 'completed', 'abandoned'];
+export const CATEGORIES = ['not_understood', 'misread', 'restart', 'repeated', 'overdone', 'omitted', 'misreported', 'redo', 'proceeded', 'approved', 'adopted_proposal', 'confirmed_inference'];
+export const ROLES = ['main', 'attribution', 'learning', 'consolidation', 'verification', 'script_writer', 'improvement'];
+export const IMMUTABLE_KINDS = new Set(['tree_item_versions', 'tree_summaries', 'tree_change_events', 'tree_receipts', 'tree_methods', 'tree_supplements']);
+
+// Minimum persisted contracts. Role-specific output schemas live in B2 and
+// cannot add authority fields to model output. Stored extension fields are host-owned.
+export const RECORD_FIELDS = Object.freeze({
+  tree_meta: 'schemaVersion userId rootNodeId treeRevision lastEventOrdinal',
+  tree_nodes: 'parentId name status statusOrigin sourceRefs lastOwnTurnAt lastSummaryWatermark',
+  tree_turns: 'sessionId nativeTurn logicalTurnId userSourceRefs sourceRefs nodeIds status startedAt',
+  tree_links: 'turnId nodeId assignmentRevision active sourceRefs',
+  tree_summaries: 'nodeId version oneLine body throughTurnIds sourceRefs previousVersion',
+  tree_items: 'kind nodeId activeVersion lifecycle validation userProtected originNodeId',
+  tree_item_versions: 'itemId version content sourceKind sourceRefs reason',
+  tree_methods: 'itemId version short long scripts hooks expectation evaluation',
+  tree_supplements: 'itemId version target scopeNodeId traitEvidence universalStopgap',
+  tree_parameters: 'name scopeNodeId value sourceRefs actor',
+  tree_exposures: 'invocationId role nodeIds itemVersions summaryVersions renderedHash treeRevision modelSessionId boundaryIndex',
+  tree_learning_sessions: 'nodeId sessionId contextEpoch appendSeq sourceWatermark appliedChangeOrdinal estimateTokens',
+  tree_jobs: 'kind scopeKey inputHash inputRevisionSet status',
+  tree_invocations: 'jobId role nativeSessionId ordinal modelConfigHash promptHash inputHash allowedTools state',
+  tree_signals: 'eventId subjectRefs dimension subitem category polarity evidenceKind sourceRefs nodeIds confidence',
+  tree_episodes: 'signalIds beforeRefs reactionRefs resolutionRefs nodeIds state start',
+  tree_clusters: 'category polarity epoch episodeIds status methodIds reviewWatermark recurrenceCount',
+  tree_repairs: 'producerRole stage type sourceSignalIds nodeIds reason requestId',
+  tree_change_events: 'ordinal commandType actor entityIds beforeVersions afterVersions sourceRefs receiptId',
+  tree_hooks: 'hookId methodId version scopeNodeId moment conditions action message enabled',
+  tree_hook_runs: 'logicalTurnId eventKey hookId version scopeEpoch inputHash result continuationCycle observedAt',
+  tree_script_artifacts: 'scriptId methodId version language entry files argSchema dryRunSupport buildRunId activationState',
+  tree_script_runs: 'runId methodVersion nodeEpoch workspaceIdentity policyHash snapshotId argvHash state',
+  tree_snapshots: 'snapshotId workspaceIdentity manifestHash commitId reason coverage restoreState',
+  tree_reports: 'category fingerprint step problem evidenceRefs whyUniversal stopgapIds suggestedFix status exportAudit',
+  tree_metric_windows: 'scope fromOrdinal toOrdinal observations numerators denominators missing algorithmVersion',
+  tree_receipts: 'requestId inputHash result revisions eventIds',
+});
+export function validateRef(ref) {
+  shape(ref, ['sessionId', 'seq', 'sha256'], ['messageId']);
+  text(ref.sessionId, 'sessionId', 512); integer(ref.seq, 'seq', 0);
+  if (!/^[a-f0-9]{64}$/.test(ref.sha256)) fail('INVALID_SOURCE', 'Source must have an exact SHA-256');
+  if (ref.messageId !== undefined) text(ref.messageId, 'messageId', 512);
+}
+export function sourceRefs(refs, resolveSource, { user = false, required = true } = {}) {
+  array(refs, 'sourceRefs', 20); if (required && !refs.length) fail('SOURCE_REQUIRED', 'Immutable source evidence required');
+  let human = false;
+  for (const ref of refs) {
+    validateRef(ref); const source = resolveSource(ref);
+    if (!source || source.then || source.sha256 !== ref.sha256) fail('SOURCE_CHANGED', 'Source cannot be verified synchronously');
+    human ||= source.role === 'user' && source.origin === 'user';
+  }
+  if (user && !human) fail('USER_SOURCE_REQUIRED', 'User-expressed content requires an actual human source, not a program message');
+  return jsonClone(refs);
+}
+export function validateRecord(kind, record) {
+  if (!Object.hasOwn(RECORD_FIELDS, kind)) fail('UNKNOWN_KIND', `Unknown tree record kind ${kind}`);
+  if (RECORD_FIELDS[kind].split(' ').some(k => !Object.hasOwn(record, k))) fail('INVALID_RECORD', `Incomplete ${kind}`);
+  text(record.id, 'id', 512);
+  const lists = {
+    tree_turns: ['nodeIds'], tree_summaries: ['throughTurnIds'], tree_methods: ['scripts', 'hooks'], tree_supplements: ['traitEvidence'],
+    tree_exposures: ['nodeIds', 'itemVersions', 'summaryVersions'], tree_invocations: ['allowedTools'], tree_signals: ['subjectRefs', 'nodeIds'],
+    tree_episodes: ['signalIds', 'beforeRefs', 'reactionRefs', 'resolutionRefs', 'nodeIds'], tree_clusters: ['episodeIds', 'methodIds'],
+    tree_repairs: ['sourceSignalIds', 'nodeIds'], tree_change_events: ['entityIds', 'beforeVersions', 'afterVersions'], tree_hooks: ['conditions'],
+    tree_script_artifacts: ['files'], tree_reports: ['evidenceRefs', 'stopgapIds', 'exportAudit'], tree_receipts: ['eventIds'],
+  }[kind] ?? [];
+  lists.forEach(k => array(record[k], k, 100000));
+  const objects = {
+    tree_summaries: ['body'], tree_methods: ['expectation', 'evaluation'], tree_parameters: ['actor'], tree_jobs: ['inputRevisionSet'],
+    tree_change_events: ['actor'], tree_script_artifacts: ['argSchema'], tree_snapshots: ['coverage'], tree_metric_windows: ['numerators', 'denominators'], tree_receipts: ['result', 'revisions'],
+  }[kind] ?? [];
+  for (const k of objects) if (!record[k] || typeof record[k] !== 'object' || Array.isArray(record[k])) fail('INVALID_RECORD', `Invalid ${kind}.${k}`);
+  const identities = {
+    tree_meta: ['userId', 'rootNodeId'], tree_turns: ['sessionId', 'logicalTurnId'], tree_links: ['turnId', 'nodeId'], tree_summaries: ['nodeId'],
+    tree_items: ['nodeId', 'originNodeId'], tree_item_versions: ['itemId', 'reason'], tree_methods: ['itemId'], tree_supplements: ['itemId', 'scopeNodeId'],
+    tree_parameters: ['scopeNodeId'], tree_exposures: ['invocationId', 'role', 'renderedHash', 'modelSessionId'], tree_learning_sessions: ['nodeId', 'sessionId'],
+    tree_jobs: ['kind', 'scopeKey', 'inputHash', 'status'], tree_invocations: ['jobId', 'role', 'nativeSessionId', 'modelConfigHash', 'promptHash', 'inputHash', 'state'],
+    tree_signals: ['eventId', 'dimension', 'subitem'], tree_episodes: ['state', 'start'], tree_clusters: ['category', 'polarity', 'status'],
+    tree_repairs: ['producerRole', 'stage', 'type', 'reason', 'requestId'], tree_change_events: ['commandType', 'receiptId'],
+    tree_hooks: ['hookId', 'methodId', 'scopeNodeId', 'moment', 'action'], tree_hook_runs: ['logicalTurnId', 'eventKey', 'hookId', 'inputHash', 'observedAt'],
+    tree_script_artifacts: ['scriptId', 'methodId', 'language', 'entry', 'buildRunId', 'activationState'], tree_script_runs: ['runId', 'policyHash', 'snapshotId', 'argvHash', 'state'],
+    tree_snapshots: ['snapshotId', 'manifestHash', 'commitId', 'reason'], tree_reports: ['category', 'fingerprint', 'step', 'problem', 'whyUniversal', 'suggestedFix', 'status'],
+    tree_metric_windows: ['algorithmVersion'], tree_receipts: ['requestId', 'inputHash'],
+  }[kind] ?? [];
+  identities.forEach(k => text(record[k], k, k === 'problem' || k === 'whyUniversal' || k === 'suggestedFix' || k === 'reason' ? 20000 : 512));
+  if (kind === 'tree_turns') { integer(record.nativeTurn, 'nativeTurn', 0); oneOf(record.status, ['open', 'settled', 'interrupted', 'failed'], 'turn status'); }
+  if (kind === 'tree_links') { integer(record.assignmentRevision, 'assignmentRevision'); if (typeof record.active !== 'boolean') fail('INVALID_RECORD', 'Link active must be boolean'); }
+  if (kind === 'tree_jobs') oneOf(record.status, ['queued', 'prepared', 'submitted', 'result_received', 'validated', 'committed', 'failed', 'unknown', 'invalid_output', 'stale', 'cancelled'], 'job status');
+  if (kind === 'tree_exposures') {
+    oneOf(record.role, ROLES, 'role'); integer(record.treeRevision, 'treeRevision'); integer(record.boundaryIndex, 'boundaryIndex', 0);
+    for (const ref of record.itemVersions) { shape(ref, ['itemId', 'version']); text(ref.itemId, 'itemId', 512); integer(ref.version, 'item version'); }
+    for (const ref of record.summaryVersions) { shape(ref, ['nodeId', 'version']); text(ref.nodeId, 'nodeId', 512); integer(ref.version, 'summary version'); }
+  }
+  if (kind === 'tree_invocations') oneOf(record.role, ROLES, 'role');
+  if (kind === 'tree_hooks' && typeof record.enabled !== 'boolean') fail('INVALID_RECORD', 'Hook enabled must be boolean');
+  if (kind === 'tree_meta') { integer(record.schemaVersion, 'schemaVersion'); integer(record.treeRevision, 'treeRevision'); integer(record.lastEventOrdinal, 'lastEventOrdinal', 0); }
+  if (kind === 'tree_change_events') integer(record.ordinal, 'ordinal');
+  for (const field of ['sourceRefs', 'userSourceRefs']) if (record[field] !== undefined) array(record[field], field).forEach(validateRef);
+  if (kind === 'tree_nodes') { text(record.name, 'name', 200); oneOf(record.status, STATUSES, 'status'); oneOf(record.statusOrigin, ['user', 'model', 'cascade'], 'statusOrigin'); }
+  if (kind === 'tree_items') { oneOf(record.kind, ['understanding', 'method', 'supplement'], 'item kind'); oneOf(record.lifecycle, ['draft', 'active', 'withdrawn', 'changed', 'invalid'], 'lifecycle'); oneOf(record.validation, ['unverified', 'supported', 'refuted'], 'validation'); if (typeof record.userProtected !== 'boolean') fail('INVALID_RECORD', 'User protection must be boolean'); if (record.activeVersion !== null) integer(record.activeVersion, 'activeVersion'); if (record.lifecycle === 'active' && record.activeVersion === null) fail('INVALID_RECORD', 'Active items need a version'); }
+  if (kind === 'tree_item_versions') oneOf(record.sourceKind, ['user_expressed', 'assistant_inferred', 'unknown'], 'sourceKind');
+  if (kind === 'tree_supplements') oneOf(record.target, ['learning', 'attribution', 'consolidation'], 'supplement target');
+  if (kind === 'tree_parameters') { oneOf(record.name, ['retentionDays', 'leaveTimeoutHours'], 'parameter'); integer(record.value, record.name, 1, record.name === 'retentionDays' ? 365 : 168); }
+  if (kind === 'tree_signals') { oneOf(record.category, CATEGORIES, 'category'); oneOf(record.polarity, ['negative', 'weak', 'strong'], 'polarity'); oneOf(record.evidenceKind, ['language', 'ui', 'program'], 'evidenceKind'); }
+  if (record.version !== undefined) integer(record.version, 'version');
+  return record;
+}
+
+export function validateShort(value) {
+  shape(value, ['situation', 'action', 'basis', 'notApplicable']);
+  for (const key of Object.keys(value)) text(value[key], key, 200, true);
+  if (count(Object.values(value).join('')) > 200) fail('CONTENT_LIMIT', 'Short text exceeds 200 codepoints');
+}
+export function validateLong(value) {
+  shape(value, ['name', 'description', 'whenToUse', 'steps', 'pitfalls', 'verify']);
+  text(value.name, 'name', 80); text(value.description, 'description', 60);
+  for (const key of ['whenToUse', 'steps', 'pitfalls', 'verify']) text(value[key], key, 2000, true);
+  if (count(value.whenToUse + value.steps + value.pitfalls + value.verify) > 2000) fail('CONTENT_LIMIT', 'Long text exceeds 2000 codepoints');
+}

package/src/tree/experience.mjs

@@ -0,0 +1,140 @@
+import { canonicalJson, digest, fail, integer, jsonClone, validateRef } from './contracts.mjs';
+import { DomainService } from './tree.mjs';
+
+const messageOf = (event, messageId) => event.type === 'agent/inbox/spliced' ? event.data.inserted?.find(m => m.id === messageId) : event.type === 'user/message' ? event.data : event.data?.message;
+const visibleBlocks = message => (message?.content ?? []).filter(b => b.type !== 'reasoning');
+
+/** Reads a host-frozen durable native log. Source labels never come from text. */
+export class NativeSources {
+  constructor({ readSession, isRevoked = () => false }) { Object.assign(this, { readSession, isRevoked }); }
+  events(sessionId) {
+    const packet = this.readSession(sessionId);
+    if (packet?.then || packet?.durable !== true || packet.sessionId !== sessionId || !Array.isArray(packet.events)) fail('DURABLE_SOURCE_REQUIRED', 'A synchronously frozen durable native log is required');
+    const events = jsonClone(packet.events);
+    for (const [seq, event] of events.entries()) if (event.seq !== seq || typeof event.type !== 'string' || !event.data) fail('NATIVE_LOG_INVALID', 'Native original log must retain its complete event sequence');
+    return events;
+  }
+  ref(sessionId, event, messageId) {
+    const message = messageOf(event, messageId);
+    return { sessionId, seq: event.seq, ...(message?.id ? { messageId: message.id } : {}), sha256: digest(event) };
+  }
+  project(sessionId, event, messageId) {
+    let role, origin, content;
+    if (['user/message', 'agent/inbox/spliced'].includes(event.type) && messageOf(event, messageId)?.source?.kind === 'user') { role = 'user'; origin = 'user'; content = visibleBlocks(messageOf(event, messageId)); }
+    else if (event.type === 'assistant/message' && event.data.message?.source?.kind === 'model') {
+      role = 'assistant'; origin = 'model'; content = visibleBlocks(event.data.message).filter(b => b.type !== 'tool-call');
+    } else if (event.type === 'tool/call') { role = 'assistant'; origin = 'tool-call'; content = [{ type: 'tool-call', id: event.data.callId, name: event.data.name, arguments: event.data.arguments }]; }
+    else if (event.type === 'tool/result' && event.data.message?.role === 'tool') { role = 'tool'; origin = 'tool'; content = visibleBlocks(event.data.message); }
+    else return null;
+    if (!content.length) return null;
+    const ref = this.ref(sessionId, event, messageId);
+    return { id: digest(['native-source', ref]), role, origin, content, text: content.map(b => b.type === 'text' ? b.text : canonicalJson(b)).join('\n'), ref, sha256: ref.sha256, nativeType: event.type, at: new Date(event.time).toISOString(), ...(event.type === 'tool/result' ? { toolCallId: event.data.message.toolCallId, isError: event.data.message.isError === true } : {}) };
+  }
+  resolve(ref) {
+    validateRef(ref); if (this.isRevoked(ref)) return null;
+    const event = this.events(ref.sessionId)[ref.seq];
+    if (!event || digest(event) !== ref.sha256 || ref.messageId && messageOf(event, ref.messageId)?.id !== ref.messageId) return null;
+    return this.project(ref.sessionId, event, ref.messageId);
+  }
+  resolveMany(refs) {
+    const eventsBySession = new Map();
+    return refs.map(ref => {
+      validateRef(ref);
+      if (this.isRevoked(ref)) return null;
+      if (!eventsBySession.has(ref.sessionId)) eventsBySession.set(ref.sessionId, this.events(ref.sessionId));
+      const event = eventsBySession.get(ref.sessionId)[ref.seq];
+      if (!event || digest(event) !== ref.sha256 || ref.messageId && messageOf(event, ref.messageId)?.id !== ref.messageId) return null;
+      return this.project(ref.sessionId, event, ref.messageId);
+    });
+  }
+  claimed(sessionId, messages) {
+    const events = this.events(sessionId);
+    return messages.filter(m => m.source?.kind === 'user').map(message => {
+      const original = events.find(e => e.type === 'agent/inbox/spliced' && e.data.inserted?.some(m => m.id === message.id && canonicalJson(m) === canonicalJson(message)));
+      if (!original) fail('USER_INBOX_SOURCE', 'Claimed user input must match its durable native inbox original');
+      return this.project(sessionId, original, message.id);
+    });
+  }
+  turn(sessionId, nativeTurn, { requireEnd = true } = {}) {
+    integer(nativeTurn, 'native turn', 0); const events = this.events(sessionId);
+    const start = events.find(e => e.type === 'turn/start' && e.data.turn === nativeTurn);
+    if (!start) fail('TURN_SOURCE_MISSING', 'Native turn start missing');
+    const end = events.find(e => e.type === 'turn/end' && e.seq > start.seq && e.data.turn === nativeTurn);
+    if (requireEnd && !end) fail('TURN_NOT_SETTLED', 'Native turn has not durably ended');
+    const next = events.find(e => e.type === 'turn/start' && e.seq > start.seq), through = end?.seq ?? (next ? next.seq - 1 : events.at(-1).seq);
+    const ownEvents = events.filter(e => e.seq >= start.seq && e.seq <= through), sources = ownEvents.map(e => this.project(sessionId, e)).filter(Boolean);
+    const userSources = sources.filter(s => s.role === 'user' && s.origin === 'user');
+    if (!userSources.length) fail('PROGRAM_NOT_USER', 'Program-only input is not a logical human turn');
+    return { sessionId, nativeTurn, startSeq: start.seq, endSeq: end?.seq ?? null, nativeHash: digest(ownEvents), endReason: end?.data.reason ?? null, sources, userSources };
+  }
+}
+
+export class ExperienceService extends DomainService {
+  constructor(options) { super(options); this.sources = options.sources; }
+  settle(turnId) {
+    const actor = this.actor([]); if (actor.kind !== 'program') fail('HOST_REQUIRED', 'Only durable host turn/end settles experience');
+    const turn = this.repo.get('tree_turns', turnId); if (!turn) fail('TURN_NOT_FOUND', 'Attribution must exist before settlement');
+    const captured = this.sources.turn(turn.sessionId, turn.nativeTurn), requestId = digest(['settle-experience', turnId]), receiptId = digest(['receipt', requestId]);
+    const prior = this.repo.get('tree_receipts', receiptId);
+    if (prior) { if (turn.experienceHash !== captured.nativeHash) fail('SOURCE_CHANGED', 'Settled native turn changed'); return prior; }
+    for (const ref of turn.userSourceRefs) {
+      const original = this.sources.resolve(ref);
+      if (!original || !captured.userSources.some(s => s.ref.messageId === ref.messageId && canonicalJson(s.content) === canonicalJson(original.content))) fail('SOURCE_CHANGED', 'Attribution user source differs from the durable turn');
+    }
+    const refs = [...turn.userSourceRefs, ...captured.sources.filter(s => s.role !== 'user' || !turn.userSourceRefs.some(r => r.messageId === s.ref.messageId)).map(s => s.ref)], status = captured.endReason.kind === 'completed' ? 'settled' : captured.endReason.kind === 'error' ? 'failed' : 'interrupted';
+    return this.repo.command('settleExperience', { requestId, expected: { [`tree_turns:${turnId}`]: turn.revision }, input: { turnId, nativeHash: captured.nativeHash, endSeq: captured.endSeq, sourceRefs: refs } }, actor, () => {
+      this.replace('tree_turns', turn, { status, settledAt: this.repo.now(), experienceRefs: refs, experienceHash: captured.nativeHash, nativeEndSeq: captured.endSeq, nativeEndReason: captured.endReason, settlementReceiptId: receiptId });
+      const jobs = [];
+      for (const nodeId of turn.nodeIds) {
+        const node = this.node(nodeId); this.replace('tree_nodes', node, { lastOwnTurnAt: this.repo.now(), lastOwnTurnId: turnId });
+        if (status !== 'settled') continue;
+        const id = digest(['settled-learning', turnId, nodeId, turn.assignmentRevision]);
+        const input = { turnId, assignmentRevision: turn.assignmentRevision, sourceRefs: refs };
+        this.repo.save('tree_jobs', { id, kind: 'learning', scopeKey: nodeId, nodeIds: [nodeId], input, inputHash: digest(input), inputRevisionSet: { [`tree_turns:${turnId}`]: turn.revision + 1 }, status: 'queued', triggerKind: 'settled_main_turn' }); jobs.push(id);
+      }
+      return { turnId, status, nodeIds: turn.nodeIds, sourceRefs: refs, learningIntents: jobs };
+    });
+  }
+  turns(nodeId, { includeInterrupted = true } = {}) {
+    this.node(nodeId);
+    const ids = new Set(this.repo.list('tree_links', l => l.nodeId === nodeId && l.active).map(l => l.turnId));
+    return this.repo.list('tree_turns', t => ids.has(t.id) && (t.status === 'settled' || includeInterrupted && ['interrupted', 'failed'].includes(t.status)))
+      .sort((a, b) => a.startedAt.localeCompare(b.startedAt) || a.sessionId.localeCompare(b.sessionId) || a.nativeTurn - b.nativeTurn || a.id.localeCompare(b.id));
+  }
+  material(turn) {
+    const sources = [], revokedRefs = [];
+    for (const ref of turn.experienceRefs ?? turn.sourceRefs) { const value = this.sources.resolve(ref); if (value) sources.push(value); else revokedRefs.push(ref); }
+    return { turnId: turn.id, status: turn.status, assignmentRevision: turn.assignmentRevision, sources, revokedRefs, nativeHash: turn.experienceHash ?? null };
+  }
+  assertReadScope(nodeId) {
+    const ctx = this.context(); if (ctx.actor.kind === 'user') return;
+    if (!(ctx.nodeIds ?? []).some(id => this.repo.ancestors(id).some(n => n.id === nodeId) || this.node(nodeId).parentId === id)) fail('OUT_OF_SCOPE', 'History is limited to ancestors and direct children');
+  }
+  history(nodeId, { afterTurnId = null, limit = 10, byteLimit = 65536 } = {}) {
+    this.assertReadScope(nodeId); integer(limit, 'limit', 1, 50); integer(byteLimit, 'byte limit', 1024, 65536);
+    const all = this.turns(nodeId); let index = 0, offset = 0, cursor;
+    if (afterTurnId !== null) {
+      if (typeof afterTurnId !== 'string') fail('CURSOR_STALE', 'History cursor must be a string');
+      if (afterTurnId.startsWith('page:')) {
+        try { cursor = JSON.parse(Buffer.from(afterTurnId.slice(5), 'base64url').toString()); } catch { fail('CURSOR_STALE', 'Malformed history cursor'); }
+        if (!cursor || cursor.nodeId !== nodeId || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0) fail('CURSOR_STALE', 'History cursor belongs to a different scope');
+        index = all.findIndex(t => t.id === cursor.turnId); offset = cursor.offset;
+      } else { const prior = all.findIndex(t => t.id === afterTurnId); if (prior < 0) fail('CURSOR_STALE', 'Unknown previous turn'); index = prior + 1; }
+    }
+    if (index < 0) fail('CURSOR_STALE', 'History cursor no longer belongs to this node');
+    const encode = (turnId, offset, hash) => 'page:' + Buffer.from(canonicalJson({ nodeId, turnId, offset, hash })).toString('base64url');
+    const items = [], revokedRefs = []; let bytes = 0;
+    for (let i = index; i < all.length && items.length < limit; i++) {
+      const material = this.material(all[i]); revokedRefs.push(...material.revokedRefs);
+      const projected = canonicalJson(material), from = i === index ? offset : 0, points = [...projected];
+      if (i === index && cursor && cursor.hash !== digest(material)) fail('CURSOR_STALE', 'Source withdrawal or assignment changed this page; restart from its turn');
+      if (from > points.length) fail('CURSOR_STALE', 'History offset is outside this turn');
+      let to = from;
+      while (to < points.length && bytes + Buffer.byteLength(points[to]) <= byteLimit) bytes += Buffer.byteLength(points[to++]);
+      if (to > from) items.push({ turnId: all[i].id, status: all[i].status, text: points.slice(from, to).join(''), offset: from, complete: from === 0 && to === points.length });
+      if (to < points.length) return { items, revokedRefs, nextCursor: encode(all[i].id, to, digest(material)) };
+      if (items.length === limit && i + 1 < all.length) return { items, revokedRefs, nextCursor: all[i].id };
+    }
+    return { items, revokedRefs, nextCursor: null };
+  }
+}