@arcfold/dsh 0.0.0-stage → 0.4.0

package/src/tree/tools.mjs

@@ -0,0 +1,99 @@
+import { canonicalJson, digest, fail, shape, text, integer, array, oneOf } from './contracts.mjs';
+import { TreeService } from './tree.mjs';
+import { ExperienceService } from './experience.mjs';
+import { bindTurnSnapshot } from './ui.mjs';
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+
+const requiredString = { type: 'string', required: true };
+const requiredVersion = { type: 'integer', required: true };
+const strings = { type: 'array', required: true, items: { type: 'string' } };
+export const TREE_TOOLS = Object.freeze({
+  arcfold_mark_complete: { nodeId: requiredString, expectedRevision: requiredVersion, reason: requiredString },
+  arcfold_read_history: { nodeId: requiredString, kind: { type: 'string', enum: ['summary', 'turns'], required: true }, afterTurnId: { type: 'string' }, limit: { type: 'integer' } },
+  arcfold_read_method: { methodId: requiredString, expectedVersion: { type: 'integer' } },
+  arcfold_run_method_script: { methodId: requiredString, expectedVersion: requiredVersion, scriptId: requiredString, args: { type: 'object', required: true, additionalProperties: true } },
+  arcfold_request_script: { methodId: { type: 'string' }, expectedVersion: { type: 'integer' }, purpose: requiredString, evidenceIds: strings, fileRefs: strings },
+});
+const descriptions = {
+  arcfold_mark_complete: '把本轮目标标为助手判断的完成，保留理由和来源；先检查对应钩子，用户仍可重新打开。',
+  arcfold_read_history: '在当前节点的上级链或直接子节点分页读取原始经历或摘要。来源已撤回时不返回原文。',
+  arcfold_read_method: '读取当前范围内一个有效方法的完整说明、准确版本和脚本逻辑编号。读取不扩大权限。',
+  arcfold_run_method_script: '通过受限执行入口运行当前有效方法脚本。自动检查版本、权限和快照；参数不接受路径、命令或权限覆盖。',
+  arcfold_request_script: '根据本轮真实证据排入专用脚本作者。新方法省略methodId/expectedVersion，不要求先有方法。evidenceIds只取本轮授权背景evidence中的id。fileRefs只取背景fileRefs中已登记的逻辑编号，不是文件名或路径；背景fileRefs为空时必须传[]。工作区文件名及读写目标写在purpose中，由作者只读工具核实；无需让用户另外上传工作区文件。purpose只描述业务输入、输出与约束，不另设计命令行开关或要求将作者私有脚本写到工作区。宿主固定以--input临时JSON参数文件调用，试跑加--dry-run；正式执行由arcfold_run_method_script的可信权限控制，不需要额外apply/write开关。返回任务状态，不自动执行；不要无限轮询。',
+};
+
+export async function nativeTreeCall(ctx, runtime, exec) {
+  const agent = exec.agent; exec.signal?.throwIfAborted();
+  if (!exec.signal || !agent || ctx.agents.get(agent.id) !== agent || ctx.agents.currentInitiator() !== agent || agent.status !== 'running' || runtime.mainAgents.get(agent.session.id) !== agent || exec.parent !== undefined || exec.rootCallId !== exec.callId || !exec.callId) fail('MAIN_REQUIRED', 'Only the exact direct native main call may use tree tools');
+  const events = await runtime.freezeSession(agent.session); exec.signal.throwIfAborted();
+  const start = events.findLast(e => e.type === 'turn/start'), step = events.findLast(e => e.type === 'step/start');
+  const call = events.find(e => e.type === 'tool/call' && e.data.callId === exec.callId);
+  const message = call && events.findLast(e => e.seq < call.seq && e.type === 'assistant/message');
+  const block = message?.data.message?.content?.find(b => b.type === 'tool-call' && b.id === exec.callId);
+  if (!start || !step || step.seq < start.seq || !call || call.seq < step.seq || call.data.name !== exec.name || block?.name !== exec.name || block.arguments !== call.data.arguments || message.data.message.source?.kind !== 'model' || canonicalJson(JSON.parse(call.data.arguments)) !== canonicalJson(exec.arguments) || events.some(e => e.seq > step.seq && ['step/end', 'turn/end'].includes(e.type)) || events.some(e => e.seq > call.seq && e.type === 'tool/result' && e.data.message.toolCallId === exec.callId)) fail('NATIVE_CALL_REQUIRED', 'Call must match its complete durable assistant and live step');
+  const job = runtime.mainJob(agent.session.id, start.data.turn), scope = runtime.builder.capture(agent.session.id);
+  if (!job || job.status !== 'submitted' || job.trigger.turnId !== scope.turnId || job.input.assignmentRevision !== scope.assignmentRevision) fail('MAIN_REQUIRED', 'Main call has no current owned logical turn');
+  runtime.jobs.assertCurrent(job);
+  const invocation = runtime.repo.list('tree_invocations', i => i.jobId === job.id && i.stepStartSeq === step.seq)[0];
+  const exposure = invocation && runtime.repo.list('tree_exposures', e => e.invocationId === invocation.id && !e.revoked)[0];
+  if (!exposure) fail('EXPOSURE_REQUIRED', 'The native request must have a recorded current exposure');
+  return { agent, job, scope, exposure, events, call, actor: { kind: 'model', role: 'main', id: job.id }, requestId: digest(['tree-tool', agent.session.id, exec.callId]) };
+}
+
+export async function executeTreeTool(ctx, runtime, name, args, exec) {
+  const current = await nativeTreeCall(ctx, runtime, exec), { agent, job, scope, exposure, requestId, actor } = current;
+  const repo = runtime.repo, context = () => ({ actor, nodeIds: scope.nodeIds }), options = { repository: repo, resolveSource: runtime.resolveSource, context };
+  if (name === 'arcfold_mark_complete') {
+    shape(args, ['nodeId', 'expectedRevision', 'reason']); integer(args.expectedRevision, 'expectedRevision', 1); text(args.reason, 'reason', 2000);
+    if (!scope.nodeIds.includes(args.nodeId)) fail('OUT_OF_SCOPE', 'Only a directly assigned node may be marked complete');
+    const result = runtime.hooks(agent.session.id).evaluate({ sessionId: agent.session.id, moment: 'node_complete', eventKey: exec.callId, fields: { completedBy: 'model' }, signal: exec.signal });
+    if (result.decision !== 'allow') fail('HOOK_DENIED', 'Completion is blocked by a current method check');
+    const before = repo.list('tree_nodes'), receipt = new TreeService(options).setStatus({ requestId, expected: { ['tree_nodes:' + args.nodeId]: args.expectedRevision }, input: { nodeId: args.nodeId, status: 'completed', sourceRefs: job.input.sources.map(s => s.ref) } });
+    runtime.metrics.observeTree(receipt, before, { logicalTurnId: scope.turnId });
+    repo.command('recordCompletionReason', { requestId: digest([requestId, 'reason']), expected: {}, input: { nodeId: args.nodeId, reason: args.reason, callId: exec.callId, receiptId: receipt.id } }, actor, () => ({ receiptId: receipt.id }));
+    // Final consolidation is queued after the current turn has settled.
+    return { ...receipt.result, revision: repo.get('tree_nodes', args.nodeId).revision, receiptId: receipt.id };
+  }
+  if (name === 'arcfold_read_history') {
+    shape(args, ['nodeId', 'kind'], ['afterTurnId', 'limit']); oneOf(args.kind, ['summary', 'turns'], 'kind');
+    const history = new ExperienceService({ ...options, sources: runtime.sources }); history.assertReadScope(args.nodeId);
+    if (args.kind === 'turns') return history.history(args.nodeId, { afterTurnId: args.afterTurnId ?? null, limit: args.limit ?? 10 });
+    const summary = runtime.builder.summary(repo.get('tree_nodes', args.nodeId)); return { items: summary ? [summary] : [], revokedRefs: [], nextCursor: null };
+  }
+  if (name === 'arcfold_read_method') {
+    shape(args, ['methodId'], ['expectedVersion']);
+    const row = runtime.builder.activeItems(scope.ancestorPaths.flat()).find(r => r.item.id === args.methodId && r.method);
+    if (!row || args.expectedVersion !== undefined && args.expectedVersion !== row.item.activeVersion) fail('METHOD_STALE', 'Method is unavailable in the current scope/version');
+    repo.command('recordFullMethodRead', { requestId, expected: { ['tree_items:' + row.item.id]: row.item.revision }, input: { itemId: row.item.id, version: row.item.activeVersion, exposureId: exposure.id } }, actor, () => {
+      const old = repo.get('tree_exposures', exposure.id), values = old.methodReadVersions ?? [], value = { itemId: row.item.id, version: row.item.activeVersion };
+      repo.save('tree_exposures', { ...old, methodReadVersions: [...new Map([...values, value].map(v => [digest(v), v])).values()] }, old.revision); return value;
+    });
+    return { methodId: row.item.id, version: row.item.activeVersion, long: row.method.long, scopeNodeId: row.item.nodeId,
+      scripts: row.method.scripts.map(s => { const artifact = repo.list('tree_script_artifacts', a => a.scriptId === s.id && a.version === s.version && a.methodId === row.item.id)[0]; return { scriptId: s.id, usage: artifact?.usage ?? '' }; }) };
+  }
+  if (name === 'arcfold_request_script') {
+    shape(args, ['purpose', 'evidenceIds', 'fileRefs'], ['methodId', 'expectedVersion']); text(args.purpose, 'purpose', 2000); array(args.evidenceIds, 'evidenceIds', 20); array(args.fileRefs, 'fileRefs', 20);
+    if (scope.nodeIds.length !== 1 && !args.methodId) fail('SCRIPT_SCOPE_AMBIGUOUS', 'A multi-goal script request must identify its existing method');
+    const nodeId = args.methodId ? repo.get('tree_items', args.methodId)?.nodeId : scope.nodeIds[0];
+    const result = runtime.writers.request(args, { job, callId: exec.callId, nodeId, exposureId: exposure.id }); runtime.kick(); return result;
+  }
+  if (name === 'arcfold_run_method_script') {
+    shape(args, ['methodId', 'expectedVersion', 'scriptId', 'args']); integer(args.expectedVersion, 'expectedVersion', 1);
+    const resources = runtime.resourcesFor(runtime.host.workingDirectory.get(agent.session));
+    const broker = resources.brokerFor({ ...current, exec }); const result = await broker.run(args, { signal: exec.signal });
+    if (result.snapshotId) bindTurnSnapshot(repo, result.snapshotId, scope.turnId);
+    return { runId: result.id, exitCode: result.result?.code ?? null, stdout: result.result?.stdout ?? '', stderr: result.result?.stderr ?? '', truncated: result.result?.truncated ?? false, snapshotId: result.snapshotId ?? null, ...(result.error ? { denial: result.error.code } : {}) };
+  }
+  fail('TOOL_NOT_FOUND', 'Unknown tree tool');
+}
+
+export function mountTreeTools(ctx, runtime) {
+  for (const [name, parameters] of Object.entries(TREE_TOOLS)) ctx.tools.register(runtime.defineTool({ name, description: descriptions[name], parameters,
+    output: { schema: { type: 'json' }, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }] },
+    execute: async (args, exec) => {
+      try { return { ok: true, value: await executeTreeTool(ctx, runtime, name, args, exec) }; }
+      catch (error) { if (error instanceof HarnessError) throw error; throw new HarnessError(error.message, error.code ?? 'TREE_TOOL_FAILED', { cause: error }); }
+    },
+    presentCall: () => ({ card: 'generic', title: descriptions[name], kind: name === 'arcfold_run_method_script' ? 'write' : 'read' }),
+  }));
+}

package/src/tree/tree.mjs

@@ -0,0 +1,202 @@
+import { randomUUID } from 'node:crypto';
+import { array, canonicalJson, digest, fail, integer, oneOf, shape, sourceRefs, text, CATEGORIES, STATUSES } from './contracts.mjs';
+import { recordKey } from './repository.mjs';
+
+// The adapter supplies context and source resolution. Nothing in command.input
+// can impersonate a user, expand the current turn, or create source evidence.
+export class DomainService {
+  constructor({ repository, context, resolveSource }) { this.repo = repository; this.context = context; this.resolveSource = resolveSource; }
+  actor(roles = [], userOnly = false) {
+    const ctx = this.context();
+    if (!ctx?.actor || userOnly && ctx.actor.kind !== 'user' || ctx.actor.kind === 'model' && !roles.includes(ctx.actor.role)) fail('FORBIDDEN', 'Operation not permitted for this trusted actor', 403);
+    return ctx.actor;
+  }
+  refs(refs, options) { return sourceRefs(refs, this.resolveSource, options); }
+  node(id) { const n = this.repo.get('tree_nodes', id); if (!n || n.deleted) fail('NODE_NOT_FOUND', 'Node not found'); return n; }
+  scoped(id) { if (this.context().actor.kind === 'model' && !(this.context().nodeIds ?? []).includes(id)) fail('OUT_OF_SCOPE', 'Node is outside this invocation', 403); }
+  candidate(id) { if (this.context().actor.kind === 'model' && !(this.context().candidateNodeIds ?? []).includes(id)) fail('OUT_OF_SCOPE', 'Node was not in the frozen attribution candidates', 403); }
+  replace(kind, row, updates) { return this.repo.save(kind, { ...row, ...updates }, row.revision); }
+}
+
+export class TreeService extends DomainService {
+  #touchStructure() { const meta = this.repo.meta(); this.replace('tree_meta', meta, { treeRevision: meta.treeRevision + 1 }); }
+  #reactivate(id) {
+    for (const n of this.repo.ancestors(id)) if (n.status !== 'active') this.replace('tree_nodes', n, { status: 'active', statusOrigin: this.context().actor.kind === 'user' ? 'user' : 'model', cascadeFromId: null });
+  }
+  #status(id, status, refs) {
+    const node = this.node(id); oneOf(status, STATUSES, 'status');
+    if (id === this.repo.rootId() && status !== 'active') fail('ROOT_INVARIANT', 'The root stays active');
+    if (status === 'active') { this.#reactivate(id); return; }
+    this.replace('tree_nodes', node, { status, statusOrigin: this.context().actor.kind === 'user' ? 'user' : 'model', cascadeFromId: null, statusSourceRefs: refs, statusChangedAt: this.repo.now() });
+    // A terminal descendant is a boundary: its separately completed/abandoned
+    // subtree is not relabelled as a consequence of its parent's status.
+    const visit = parent => { for (const child of this.repo.list('tree_nodes', n => !n.deleted && n.parentId === parent)) {
+      if (['completed', 'abandoned'].includes(child.status)) continue;
+      this.replace('tree_nodes', child, { status, statusOrigin: 'cascade', cascadeFromId: id, statusSourceRefs: refs, statusChangedAt: this.repo.now() }); visit(child.id);
+    } }; visit(id);
+  }
+  #invalidateScope(ids, reason) {
+    for (const e of this.repo.list('tree_exposures', e => !e.revoked && e.nodeIds.some(id => ids.includes(id)))) this.replace('tree_exposures', e, { revoked: true, invalidationReason: reason });
+    for (const j of this.repo.list('tree_jobs', j => !['committed', 'failed', 'cancelled', 'unknown', 'invalid_output', 'stale'].includes(j.status) && (j.nodeIds ?? [j.scopeKey]).some(id => ids.includes(id)))) this.replace('tree_jobs', j, { status: j.status === 'submitted' ? 'submitted' : 'stale', invalidated: true, error: reason });
+  }
+  applyAttribution(command) {
+    const actor = this.actor(['attribution']);
+    return this.repo.command('applyAttribution', command, actor, () => {
+      const input = command.input;
+      shape(input, ['sessionId', 'nativeTurn', 'userSourceRefs', 'sourceRefs', 'actions', 'statusChanges'], ['failure', 'attributionRunId']);
+      text(input.sessionId, 'sessionId', 512); integer(input.nativeTurn, 'nativeTurn', 0);
+      const userRefs = this.refs(input.userSourceRefs, { user: true }), refs = this.refs(input.sourceRefs);
+      if (userRefs.some(r => !refs.some(s => canonicalJson(r) === canonicalJson(s)))) fail('INVALID_SOURCE', 'User references must be included in the turn');
+      const logicalTurnId = digest(['turn', input.sessionId, input.nativeTurn]), id = logicalTurnId;
+      if (this.repo.get('tree_turns', id)) fail('TURN_EXISTS', 'This native turn has already been attributed');
+      let nodeIds, createdNodeIds = [], fallback = null;
+      try {
+        nodeIds = this.repo.transaction(() => {
+          if (input.failure) fail('ATTRIBUTION_FAILED', text(input.failure, 'failure', 2000));
+          array(input.actions, 'actions', 8); if (!input.actions.length) fail('INVALID_FIELD', 'An attribution action is required', 400);
+          const selected = [];
+          for (const action of input.actions) {
+            oneOf(action.action, ['continue', 'switch', 'create', 'create_child'], 'action');
+            let target;
+            if (['continue', 'switch'].includes(action.action)) { shape(action, ['action', 'nodeId']); this.candidate(action.nodeId); target = this.node(action.nodeId).id; }
+            else {
+              shape(action, action.action === 'create' ? ['action', 'name'] : ['action', 'parentId', 'name']); text(action.name, 'name', 80);
+              const parentId = action.action === 'create' ? this.repo.rootId() : this.node(action.parentId).id;
+              this.candidate(parentId);
+              target = randomUUID(); this.repo.save('tree_nodes', { id: target, parentId, name: action.name, status: 'active', statusOrigin: actor.kind === 'user' ? 'user' : 'model', sourceRefs: userRefs, lastOwnTurnAt: null, lastSummaryWatermark: null }); createdNodeIds.push(target);
+            }
+            this.#reactivate(target); selected.push(target);
+          }
+          for (const change of array(input.statusChanges, 'statusChanges', 8)) {
+            shape(change, ['nodeId', 'status', 'sourceRefs']); oneOf(change.status, ['paused', 'completed', 'abandoned'], 'status'); this.refs(change.sourceRefs, { user: true });
+            this.candidate(change.nodeId);
+            this.#status(change.nodeId, change.status, change.sourceRefs);
+          }
+          return [...new Set(selected)];
+        });
+      } catch (error) {
+        // Only invalid attribution output falls back. Database/CAS/actor failures
+        // must remain explicit failures rather than masquerading as safe routing.
+        if (!['ATTRIBUTION_FAILED', 'INVALID_SHAPE', 'INVALID_FIELD', 'NODE_NOT_FOUND', 'ROOT_INVARIANT', 'INVALID_SOURCE', 'SOURCE_CHANGED', 'USER_SOURCE_REQUIRED'].includes(error.code)) throw error;
+        fallback = { code: error.code, reason: error.message, visible: true }; createdNodeIds = [];
+        const prior = this.repo.list('tree_turns', t => t.sessionId === input.sessionId && t.nativeTurn < input.nativeTurn).sort((a, b) => b.nativeTurn - a.nativeTurn)[0];
+        nodeIds = (prior?.nodeIds ?? []).filter(id => { const n = this.repo.get('tree_nodes', id); return n && !n.deleted; });
+        if (!nodeIds.length) nodeIds = [this.repo.rootId()];
+      }
+      const turn = this.repo.save('tree_turns', { id, sessionId: input.sessionId, nativeTurn: input.nativeTurn, logicalTurnId, userSourceRefs: userRefs, sourceRefs: refs, nodeIds, createdNodeIds, assignmentRevision: 1, status: 'open', startedAt: this.repo.now(), attributionRunId: input.attributionRunId ?? null, fallback });
+      for (const nodeId of nodeIds) {
+        this.repo.save('tree_links', { id: digest(['link', id, 1, nodeId]), turnId: id, nodeId, assignmentRevision: 1, active: true, sourceRefs: refs });
+        this.replace('tree_nodes', this.node(nodeId), { lastOwnTurnAt: turn.startedAt });
+      }
+      this.#touchStructure(); return { turnId: id, logicalTurnId, nodeIds, createdNodeIds, fallback };
+    });
+  }
+  moveNode(command) {
+    return this.repo.command('moveNode', command, this.actor([], true), () => {
+      shape(command.input, ['nodeId', 'parentId', 'sourceRefs']); const { nodeId, parentId } = command.input;
+      this.repo.requireExpected(command, 'tree_nodes', nodeId); const node = this.node(nodeId); this.node(parentId);
+      if (nodeId === this.repo.rootId()) fail('ROOT_INVARIANT', 'Root cannot move');
+      if (this.repo.ancestors(parentId).some(n => n.id === nodeId)) fail('TREE_CYCLE', 'A node cannot move below itself');
+      this.refs(command.input.sourceRefs, { required: false });
+      const affected = this.repo.list('tree_nodes', n => !n.deleted && this.repo.ancestors(n.id).some(a => a.id === nodeId)).map(n => n.id);
+      this.replace('tree_nodes', node, { parentId }); this.#touchStructure(); this.#invalidateScope(affected, 'node_moved'); return { nodeId, parentId };
+    });
+  }
+  setStatus(command) {
+    return this.repo.command('setStatus', command, this.actor(['main']), () => {
+      shape(command.input, ['nodeId', 'status', 'sourceRefs']); const { nodeId, status } = command.input; this.scoped(nodeId);
+      if (this.context().actor.kind === 'model' && status !== 'completed') fail('FORBIDDEN', 'Main may only mark the current node complete', 403);
+      this.repo.requireExpected(command, 'tree_nodes', nodeId); this.refs(command.input.sourceRefs, { required: false }); this.#status(nodeId, status, command.input.sourceRefs);
+      this.#touchStructure(); return { nodeId, status: this.node(nodeId).status, statusOrigin: this.node(nodeId).statusOrigin };
+    });
+  }
+  correctAssignment(command) {
+    return this.repo.command('correctAssignment', command, this.actor([], true), () => {
+      shape(command.input, ['turnId', 'nodeIds', 'sourceRefs'], ['undoCreate']); const { turnId } = command.input;
+      this.repo.requireExpected(command, 'tree_turns', turnId); const turn = this.repo.get('tree_turns', turnId); if (!turn) fail('TURN_NOT_FOUND', 'Turn not found');
+      this.refs(command.input.sourceRefs, { required: false }); const nodeIds = [...new Set(array(command.input.nodeIds, 'nodeIds', 8))];
+      if (!nodeIds.length) fail('INVALID_FIELD', 'At least one target node is required'); nodeIds.forEach(id => this.node(id));
+      const removed = turn.nodeIds.filter(id => !nodeIds.includes(id)), added = nodeIds.filter(id => !turn.nodeIds.includes(id));
+      if (!removed.length && !added.length) return { turnId, nodeIds, jobs: [], unchanged: true };
+      // Attribution predates tool/results. Preserve its immutable original refs,
+      // and include the separately settled native experience in correction.
+      const experienceRefs = [...new Map([...turn.sourceRefs, ...(turn.experienceRefs ?? [])].map(r => [canonicalJson(r), r])).values()];
+      const assignmentRevision = turn.assignmentRevision + 1;
+      for (const link of this.repo.list('tree_links', l => l.turnId === turnId && l.active)) this.replace('tree_links', link, { active: false });
+      for (const nodeId of nodeIds) this.repo.save('tree_links', { id: digest(['link', turnId, assignmentRevision, nodeId]), turnId, nodeId, assignmentRevision, active: true, sourceRefs: experienceRefs });
+      this.replace('tree_turns', turn, { nodeIds, assignmentRevision }); this.#invalidateScope(removed, 'assignment_corrected');
+      const jobs = [], matching = new Set(experienceRefs.map(canonicalJson));
+      for (const item of this.repo.list('tree_items', i => removed.includes(i.nodeId) && i.lifecycle === 'active')) {
+        const version = this.repo.get('tree_item_versions', digest(['item_version', item.id, item.activeVersion]));
+        if (!version?.sourceRefs.some(r => matching.has(canonicalJson(r)))) continue;
+        if (version.sourceRefs.every(r => matching.has(canonicalJson(r)))) {
+          this.replace('tree_items', item, { lifecycle: 'invalid', invalidationReason: 'assignment_corrected' });
+          for (const h of this.repo.list('tree_hooks', h => h.methodId === item.id && h.enabled)) this.replace('tree_hooks', h, { 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: 'assignment_corrected' });
+        } else {
+          this.replace('tree_items', item, { stale: true, staleReason: 'assignment_corrected' });
+          jobs.push(this.#queue('verification', item.nodeId, { turnId, itemId: item.id, itemVersion: item.activeVersion, assignmentRevision }));
+        }
+      }
+      for (const nodeId of added) jobs.push(this.#queue('learning', nodeId, { turnId, assignmentRevision, sourceRefs: experienceRefs }));
+      if (command.input.undoCreate) for (const id of turn.createdNodeIds ?? []) {
+        if (!removed.includes(id) || this.repo.list('tree_links', l => l.nodeId === id && l.active).length || this.repo.list('tree_nodes', n => !n.deleted && n.parentId === id).length) continue;
+        this.replace('tree_nodes', this.node(id), { deleted: true, deletionReason: 'undo_create_without_other_experience' });
+      }
+      this.#touchStructure(); return { turnId, nodeIds, removed, jobs };
+    });
+  }
+  #queue(kind, nodeId, input) {
+    const id = digest(['correction_job', kind, nodeId, input]);
+    this.repo.save('tree_jobs', { id, kind, scopeKey: nodeId, nodeIds: [nodeId], input, inputHash: digest(input), inputRevisionSet: { [recordKey('tree_nodes', nodeId)]: this.node(nodeId).revision }, status: 'queued' }); return id;
+  }
+  setParameter(command) {
+    return this.repo.command('setParameter', command, this.actor(['improvement']), () => {
+      shape(command.input, ['name', 'scopeNodeId', 'value', 'sourceRefs']); const { name, scopeNodeId, value } = command.input; this.node(scopeNodeId); this.scoped(scopeNodeId);
+      oneOf(name, ['retentionDays', 'leaveTimeoutHours'], 'parameter'); integer(value, name, 1, name === 'retentionDays' ? 365 : 168);
+      this.refs(command.input.sourceRefs, { required: this.context().actor.kind !== 'user' });
+      const id = digest(['parameter', name, scopeNodeId]), old = this.repo.get('tree_parameters', id);
+      if (old) { this.repo.requireExpected(command, 'tree_parameters', id); if (old.actor.kind === 'user' && this.context().actor.kind !== 'user') fail('USER_PROTECTED', 'Explicit user settings cannot be changed in background'); }
+      const saved = this.repo.save('tree_parameters', { id, name, scopeNodeId, value, sourceRefs: command.input.sourceRefs, actor: this.context().actor }, old?.revision ?? null); return { parameterId: saved.id, value };
+    });
+  }
+  parameter(name, nodeId) {
+    oneOf(name, ['retentionDays', 'leaveTimeoutHours'], 'parameter');
+    for (const n of this.repo.ancestors(nodeId).reverse()) { const p = this.repo.get('tree_parameters', digest(['parameter', name, n.id])); if (p) return p.value; }
+    return name === 'retentionDays' ? 7 : 24;
+  }
+}
+
+export class SignalService extends DomainService {
+  #write(input, correctionOf = null) {
+    shape(input, ['eventId', 'subjectRefs', 'dimension', 'subitem', 'category', 'polarity', 'evidenceKind', 'sourceRefs', 'nodeIds', 'confidence']);
+    text(input.eventId, 'eventId', 512); array(input.subjectRefs, 'subjects', 20).forEach(s => text(s, 'subject', 512));
+    oneOf(input.category, CATEGORIES, 'category'); oneOf(input.polarity, ['negative', 'weak', 'strong'], 'polarity'); oneOf(input.evidenceKind, ['language', 'ui', 'program'], 'evidenceKind');
+    if (input.evidenceKind === 'language') this.refs(input.sourceRefs); else this.refs(input.sourceRefs, { required: false });
+    if (input.evidenceKind === 'ui' && this.context().actor.kind !== 'user') fail('FORGED_UI', 'Only a trusted user operation is UI evidence');
+    if (this.context().actor.kind === 'model' && this.context().eventIds && !this.context().eventIds.includes(input.eventId)) fail('UNKNOWN_EVENT', 'Event was not supplied to this invocation');
+    for (const nodeId of array(input.nodeIds, 'nodeIds', 8)) this.node(nodeId);
+    if (!Number.isFinite(input.confidence) || input.confidence < 0 || input.confidence > 1) fail('INVALID_FIELD', 'Invalid confidence');
+    const subjectRefs = [...new Set(input.subjectRefs)].sort(), id = digest(['signal', input.eventId, input.category, subjectRefs, correctionOf]);
+    const old = this.repo.get('tree_signals', id);
+    if (old) {
+      const comparable = s => ({ ...s, nodeIds: [] });
+      const original = Object.fromEntries(Object.keys(input).map(k => [k, old[k]]));
+      if (canonicalJson(comparable({ ...input, subjectRefs })) !== canonicalJson(comparable(original))) fail('SIGNAL_CONFLICT', 'The same observation has conflicting evidence');
+      const nodeIds = [...new Set([...old.nodeIds, ...input.nodeIds])].sort();
+      if (canonicalJson(nodeIds) !== canonicalJson(old.nodeIds)) this.replace('tree_signals', old, { nodeIds }); return { signalId: id, duplicate: true };
+    }
+    this.repo.save('tree_signals', { ...input, subjectRefs, nodeIds: [...new Set(input.nodeIds)].sort(), id, ...(correctionOf ? { correctionOf } : {}) }); return { signalId: id, duplicate: false };
+  }
+  record(command) { return this.repo.command('recordSignal', command, this.actor(['learning', 'verification', 'consolidation']), () => this.#write(command.input)); }
+  correct(command) {
+    return this.repo.command('correctSignal', command, this.actor([], true), () => {
+      shape(command.input, ['signalId', 'replacement']); const old = this.repo.get('tree_signals', command.input.signalId); if (!old) fail('SIGNAL_NOT_FOUND', 'Signal missing');
+      this.repo.requireExpected(command, 'tree_signals', old.id); const replacement = command.input.replacement;
+      if (replacement.eventId !== old.eventId || canonicalJson([...replacement.subjectRefs].sort()) !== canonicalJson(old.subjectRefs)) fail('SIGNAL_CONFLICT', 'Correction must keep the original observation identity');
+      const result = this.#write(replacement, old.id);
+      for (const kind of ['tree_metric_windows', 'tree_clusters']) for (const row of this.repo.list(kind)) this.replace(kind, row, { needsRecheck: true });
+      return { ...result, correctionOf: old.id };
+    });
+  }
+}