@arcfold/dsh 0.0.0-stage → 0.4.0

package/src/tree/script-writer.mjs

@@ -0,0 +1,149 @@
+import { canonicalJson, digest, fail, shape, integer, text, jsonClone } from './contracts.mjs';
+import { processPolicy } from './host-process.mjs';
+import { relativeFile } from './snapshots.mjs';
+import { SCRIPT_LIMITS, ARG_SCHEMA_GUIDANCE, scriptPath, validateArgSchema, normalizeArgs, ConfinedScriptRunner } from './scripts.mjs';
+import { WRITER_TOOLS } from './jobs.mjs';
+
+const program = { kind: 'program', id: 'tree-script-writer' };
+const emptyArgs = { type: 'object', properties: {}, required: [], additionalProperties: false };
+const strings = values => { if (!Array.isArray(values) || values.length > 20) fail('WRITER_MANIFEST', 'Bounded verification notes required'); return values.map(v => text(v, 'verification note', 2000)); };
+
+/** One trusted binding per native writer job; models cannot choose its owner. */
+export class ScriptWriter {
+  constructor({ repository, artifacts, workspaceIO, binding, assertJob, runtimeRoot, protectedRoots, runner = new ConfinedScriptRunner(), allowUnconfinedFixture = false }) {
+    Object.assign(this, { repo: repository, artifacts, io: workspaceIO, binding: jsonClone(binding), assertJob, runtimeRoot, protectedRoots, runner });
+    if (typeof assertJob !== 'function' || !binding.jobId || !binding.scriptId || !binding.methodId || !Number.isSafeInteger(binding.draftVersion) || !Number.isSafeInteger(binding.requestIndex)) fail('WRITER_BINDING', 'Trusted writer ownership required');
+    if ((runner.enforcement !== 'full' || workspaceIO.enforcement !== 'full') && !allowUnconfinedFixture) fail('SANDBOX_UNAVAILABLE', 'Writer I/O and probe require full confinement');
+    this.timeoutMs = binding.timeoutMs ?? SCRIPT_LIMITS.timeoutMs; integer(this.timeoutMs, 'timeoutMs', 1, SCRIPT_LIMITS.maximumTimeoutMs);
+    this.id = digest(['script-draft', binding.jobId]); this.active = new Set();
+    const old = this.draft(); if (old && digest(old.binding) !== digest(this.binding)) fail('WRITER_BINDING', 'Existing job binding differs');
+    if (!old) this.change('open', () => ({ binding: this.binding, state: 'open', files: [], probes: [], startedAt: this.repo.now() }));
+  }
+  draft() { return this.repo.meta().scriptDrafts?.[this.id] ?? null; }
+  assertCurrent({ finished = false } = {}) {
+    const result = this.assertJob(this.binding.jobId); if (result?.then || result !== true) fail('WRITER_STALE', 'Native writer job is no longer current');
+    const item = this.repo.get('tree_items', this.binding.methodId), bundle = this.repo.get('tree_methods', digest(['method', this.binding.methodId, this.binding.draftVersion]));
+    if (!item || item.lifecycle !== 'draft' || item.draftVersion !== this.binding.draftVersion || !bundle?.pendingScriptRequests[this.binding.requestIndex]) fail('WRITER_STALE', 'Requested method draft was withdrawn or replaced');
+    const version = this.repo.get('tree_item_versions', digest(['item_version', item.id, item.draftVersion]));
+    if (!version || version.sourceRefs.some(ref => !this.artifacts.resolveSource(ref))) fail('SOURCE_STALE', 'Writer source is no longer eligible');
+    if (!finished && this.draft()?.state !== 'open') fail('WRITER_FINISHED', 'This artifact draft is already finished');
+  }
+  change(kind, update, expectedRevision) {
+    const current = this.draft();
+    return this.repo.command('recordTreeWriter', { requestId: digest([this.id, kind, current?.revision ?? 0]), expected: {}, input: { draftId: this.id, kind, revision: current?.revision ?? 0 } }, program, () => {
+      const meta = this.repo.meta(), row = meta.scriptDrafts?.[this.id]; if ((row?.revision ?? 0) !== (current?.revision ?? 0)) fail('REVISION_CONFLICT', 'Writer draft changed');
+      if (expectedRevision !== undefined && (row?.revision ?? 0) !== expectedRevision) fail('ARTIFACT_CONFLICT', 'Draft changed while artifact bytes were being prepared');
+      const next = { ...row, ...update(row), id: this.id, revision: (row?.revision ?? 0) + 1, updatedAt: this.repo.now() };
+      this.repo.save('tree_meta', { ...meta, scriptDrafts: { ...meta.scriptDrafts, [this.id]: next } }, meta.revision); return next;
+    }).result;
+  }
+  async scan(copy, signal) { this.assertCurrent(); const result = await this.io.scan({ copy, signal }); this.assertCurrent(); return result; }
+  async read(input, options = {}) {
+    shape(input, ['relativePath'], ['offset', 'limit']); relativeFile(input.relativePath); const offset = input.offset ?? 0, limit = input.limit ?? 16000;
+    integer(offset, 'offset', 0, 20 * 1024 * 1024); integer(limit, 'limit', 1, 16000);
+    const { manifest, contents } = await this.scan(true, options.signal), file = manifest.files.find(f => f.path === input.relativePath);
+    if (!file) fail('WRITER_READ_DENIED', 'File is absent or outside ordinary workspace content');
+    const bytes = contents.get(file.path), value = bytes.toString('utf8'); if (!Buffer.from(value).equals(bytes) || value.includes('\0')) fail('WRITER_BINARY', 'Writer reads UTF-8 text only');
+    const chars = [...value]; return { path: file.path, sha256: file.sha256, offset, content: chars.slice(offset, offset + limit).join(''), nextOffset: offset + limit < chars.length ? offset + limit : null };
+  }
+  async list(input = {}, options = {}) {
+    shape(input, [], ['relativePath', 'offset', 'limit']); const root = input.relativePath ?? '', offset = input.offset ?? 0, limit = input.limit ?? 100;
+    if (root) relativeFile(root); integer(offset, 'offset', 0, 1000000); integer(limit, 'limit', 1, 200);
+    const { manifest } = await this.scan(false, options.signal), files = manifest.files.filter(f => !root || f.path.startsWith(root + '/')).map(f => ({ path: f.path, size: f.size }));
+    return { files: files.slice(offset, offset + limit), nextOffset: offset + limit < files.length ? offset + limit : null, coverage: manifest.exclusions.length ? 'partial' : 'full' };
+  }
+  async search(input, options = {}) {
+    shape(input, ['query'], ['relativePath', 'limit']); text(input.query, 'literal query', 512); const root = input.relativePath ?? '', limit = input.limit ?? 20;
+    if (root) relativeFile(root); integer(limit, 'limit', 1, 100);
+    const { manifest, contents } = await this.scan(true, options.signal), matches = []; let truncated = false;
+    for (const file of manifest.files) {
+      if (root && file.path !== root && !file.path.startsWith(root + '/')) continue; const bytes = contents.get(file.path), value = bytes.toString('utf8');
+      if (value.includes('\0') || !Buffer.from(value).equals(bytes)) continue;
+      const lines = value.split('\n'); for (let i = 0; i < lines.length; i++) if (lines[i].includes(input.query)) {
+        if (matches.length === limit) { truncated = true; break; } matches.push({ path: file.path, line: i + 1, text: [...lines[i]].slice(0, 120).join('') });
+      } if (truncated) break;
+    }
+    return { matches, truncated, mode: 'literal' };
+  }
+  put(input) {
+    shape(input, ['relativePath', 'content'], ['expectedHash']); this.assertCurrent(); const path = scriptPath(input.relativePath);
+    if (path.split('/').some(p => p.startsWith('.arcfold-'))) fail('ARTIFACT_PATH', 'Reserved execution filename');
+    const draft = this.draft(), old = draft.files.find(f => f.path === path);
+    if (old ? input.expectedHash !== old.sha256 : input.expectedHash !== undefined && input.expectedHash !== null) fail('ARTIFACT_CONFLICT', 'writer_put must compare the exact previous file hash');
+    if (typeof input.content !== 'string') fail('ARTIFACT_CONTENT', 'Source text required');
+    const files = draft.files.filter(f => f.path !== path), size = Buffer.byteLength(input.content);
+    if (files.length + 1 > SCRIPT_LIMITS.files || files.reduce((n, f) => n + f.size, size) > SCRIPT_LIMITS.bytes) fail('ARTIFACT_LIMIT', 'Draft exceeds 16 files or 256 KiB');
+    const file = { path, ...this.artifacts.put(input.content) }; files.push(file); files.sort((a, b) => a.path.localeCompare(b.path));
+    this.change('put', () => ({ files }), draft.revision); return file;
+  }
+  artifact(entry, argSchema = emptyArgs) {
+    return { id: digest(['script-artifact', this.binding.scriptId, this.binding.scriptVersion ?? 1]), scriptId: this.binding.scriptId, methodId: this.binding.methodId, version: this.binding.scriptVersion ?? 1, language: 'node-esm', entry: scriptPath(entry), files: this.draft().files, argSchema, dryRunSupport: true,
+      buildRunId: this.binding.jobId, activationState: 'ready', draftVersion: this.binding.draftVersion, requestIndex: this.binding.requestIndex, timeoutMs: this.timeoutMs };
+  }
+  cancel() { for (const abort of this.active) abort.abort(); }
+  async probe(input, { signal } = {}) {
+    shape(input, ['entry', 'args']); this.assertCurrent(); if (Buffer.byteLength(canonicalJson(input.args)) > SCRIPT_LIMITS.args) fail('ARGS_INVALID', 'Probe input exceeds 64 KiB');
+    const artifact = this.artifact(input.entry), filesHash = digest(artifact.files), args = jsonClone(input.args), abort = new AbortController(); this.active.add(abort);
+    const combined = signal ? AbortSignal.any([signal, abort.signal]) : abort.signal;
+    const check = () => { this.assertCurrent(); if (digest(this.draft().files) !== filesHash) fail('ARTIFACT_CONFLICT', 'Draft changed during probe'); };
+    const watcher = setInterval(() => { try { check(); } catch { abort.abort(); } }, 25); watcher.unref();
+    const policy = processPolicy({ workspace: this.io.workspace, runtimeRoot: this.runtimeRoot, protectedRoots: [...this.protectedRoots, this.artifacts.directory], sessionPolicy: { mode: 'read-only', workspaceRoot: this.io.workspace } });
+    let result;
+    try { const scan = await this.scan(false, combined); result = await this.runner.run({ artifact, args, artifacts: this.artifacts, policy, readPaths: scan.manifest.files.map(f => f.path), readOnly: true, timeoutMs: 10000, signal: combined, assertCurrent: check }); }
+    catch (error) { result = { code: null, reason: 'probe_error', error: { code: error.code ?? 'PROBE_FAILED', message: error.message } }; }
+    finally { clearInterval(watcher); this.active.delete(abort); }
+    const probe = { id: digest([this.id, 'probe', this.draft().probes.length]), entry: input.entry, filesHash, args, argsHash: digest(args), result, readOnly: true, enforcement: this.runner.enforcement, at: this.repo.now() };
+    // Interrupted/replaced drafts retain the attempt, but can never finish it.
+    this.change('probe', row => ({ probes: [...row.probes, probe] })); return probe;
+  }
+  finish(input) {
+    shape(input, ['manifest', 'verified', 'notVerified']); this.assertCurrent({ finished: true });
+    if (this.active.size) fail('WRITER_BUSY', 'A running probe must finish before the artifact can be sealed');
+    const draft = this.draft(); if (draft.state === 'finished') { if (draft.finishHash !== digest(input)) fail('ARTIFACT_CONFLICT', 'Finished manifest cannot change'); return this.repo.get('tree_script_artifacts', draft.artifactId); }
+    shape(input.manifest, ['entry', 'files', 'argSchema', 'dryRunSupport', 'usage'], ['writePaths']); validateArgSchema(input.manifest.argSchema); text(input.manifest.usage, 'script usage', 2000);
+    const writePaths = input.manifest.writePaths ?? [];
+    if (!Array.isArray(writePaths) || writePaths.length > 64 || new Set(writePaths).size !== writePaths.length) fail('WRITER_MANIFEST', 'At most 64 distinct relative write files are allowed');
+    writePaths.forEach(relativeFile);
+    if (input.manifest.dryRunSupport !== true || !Array.isArray(input.manifest.files) || digest([...input.manifest.files].sort()) !== digest(draft.files.map(f => f.path).sort())) fail('WRITER_MANIFEST', 'Exact file list and dry-run contract required');
+    const claims = strings(input.verified), notVerified = strings(input.notVerified), artifact = this.artifact(input.manifest.entry, input.manifest.argSchema); this.artifacts.verify(artifact);
+    const successful = draft.probes.filter(p => p.entry === artifact.entry && p.filesHash === digest(artifact.files) && p.result.code === 0 && !p.result.reason && !p.result.truncated);
+    if (!successful.length) fail('PROBE_REQUIRED', 'Current exact artifact needs a successful confined read-only probe');
+    for (const probe of successful) normalizeArgs(artifact.argSchema, probe.args);
+    const finished = { ...artifact, writePaths: [...writePaths].sort(), usage: input.manifest.usage, probeIds: successful.map(p => p.id), verified: ['Exact artifact read-only probe completed; enforcement=' + this.runner.enforcement], authoredVerificationClaims: claims, notVerified: [...new Set([...notVerified, 'Real write behavior was not verified by the writer probe'])] };
+    if (finished.notVerified.length > 20) fail('WRITER_MANIFEST', 'At most 19 authored limitations plus the mandatory real-write limitation fit the final report; combine related notes without dropping limitations.');
+    this.repo.transaction(() => {
+      this.repo.command('finishTreeScriptArtifact', { requestId: digest(['finish-artifact', this.id]), expected: {}, input: { binding: this.binding, manifest: input, files: artifact.files } }, program, () => {
+        this.assertCurrent(); if (this.repo.get('tree_script_artifacts', artifact.id)) fail('ARTIFACT_CONFLICT', 'Artifact version already exists'); this.repo.save('tree_script_artifacts', finished); return { artifactId: artifact.id };
+      });
+      this.change('finish', () => ({ state: 'finished', artifactId: artifact.id, finishHash: digest(input) }), draft.revision);
+    }); return this.repo.get('tree_script_artifacts', artifact.id);
+  }
+  verifyFinal(output) {
+    this.assertCurrent({ finished: true }); const draft = this.draft(), artifact = this.repo.get('tree_script_artifacts', draft.artifactId);
+    if (draft.state !== 'finished' || !artifact || !Array.isArray(output.files) || digest(output.files.map(f => f.name).sort()) !== digest(artifact.files.map(f => f.path).sort()) || output.usage !== artifact.usage) fail('WRITER_FINAL_MISMATCH', 'Native final result must describe the exact finished artifact and usage');
+    this.artifacts.verify(artifact); return { artifactId: artifact.id, filesHash: digest(artifact.files), probeIds: artifact.probeIds, notVerified: artifact.notVerified };
+  }
+  completionTemplate() {
+    this.assertCurrent({ finished: true }); const draft = this.draft(), artifact = this.repo.get('tree_script_artifacts', draft.artifactId);
+    if (draft.state !== 'finished' || !artifact) fail('WRITER_FINAL_MISMATCH', 'Finish the artifact before requesting its final report');
+    this.artifacts.verify(artifact);
+    return { files: artifact.files.map(file => ({ name: file.path, purpose: '已封存的方法脚本文件' })),
+      usage: artifact.usage, stepsText: artifact.usage, verified: artifact.verified,
+      notVerified: artifact.notVerified, problems: '' };
+  }
+  /** B2 owns the native loop; this mounts six closures, never general tools. */
+  mount(agentContext, defineTool) {
+    const schemas = {
+      writer_read: { relativePath: { type: 'string', required: true }, offset: { type: 'integer' }, limit: { type: 'integer' } },
+      writer_list: { relativePath: { type: 'string' }, offset: { type: 'integer' }, limit: { type: 'integer' } },
+      writer_search: { query: { type: 'string', required: true }, relativePath: { type: 'string' }, limit: { type: 'integer' } },
+      writer_put: { relativePath: { type: 'string', required: true }, content: { type: 'string', required: true }, expectedHash: { type: 'string' } },
+      writer_probe: { entry: { type: 'string', required: true }, args: { type: 'object', additionalProperties: true, required: true } },
+      writer_finish: { manifest: { type: 'object', additionalProperties: false, required: true, properties: { entry: { type: 'string', required: true }, files: { type: 'array', items: { type: 'string' }, required: true }, argSchema: { type: 'object', additionalProperties: true, required: true }, dryRunSupport: { type: 'boolean', required: true }, usage: { type: 'string', required: true }, writePaths: { type: 'array', items: { type: 'string' } } } }, verified: { type: 'array', items: { type: 'string' }, required: true }, notVerified: { type: 'array', items: { type: 'string' }, required: true } },
+    };
+    for (const name of WRITER_TOOLS) agentContext.tools.register(defineTool({ name, description: ({ writer_read: 'Read bounded UTF-8 workspace content. Paths are relative.', writer_list: 'List allowed workspace files. Omit relativePath or use an empty string for the root; do not use dot.', writer_search: 'Search allowed workspace text literally.', writer_put: 'Write one .mjs draft file; replacements require its previous hash.', writer_probe: 'Run this draft read-only for up to ten seconds. args is the JSON business argument object, not command-line flags. The host writes it to a temporary file outside the workspace and invokes entry --input <that-file> --dry-run. The script must parse that JSON, then resolve business file paths from its fields against process.cwd(). Do not treat the --input file itself as a workspace business file.', writer_finish: 'Finish the exact files with entry, closed argSchema for the JSON business arguments (not argv), dryRunSupport:true, usage, writePaths (at most 64 relative output files, no directories; omitted means read-only), and verification limits. The host intersects this declaration with current user permissions; it grants none. writePaths are business outputs, not private script files. ' + ARG_SCHEMA_GUIDANCE })[name],
+      parameters: schemas[name], output: { schema: { type: 'json' }, render: (_args, result) => [{ type: 'text', text: JSON.stringify(result) },
+        ...(name === 'writer_finish' ? [{ type: 'text', text: '作者任务已经封存。下一条直接返回完整最终JSON；usage必须逐字复制，files必须包含这些原文件名。可以补充文件用途和操作说明，但不能改写usage或声称已验证真实写入。完整模板：' + JSON.stringify(this.completionTemplate()) }] : [])] },
+      execute: async (args, context) => this[name.slice('writer_'.length)](args, { signal: context?.signal }) }));
+  }
+}

package/src/tree/scripts.mjs

@@ -0,0 +1,208 @@
+import { constants, closeSync, fstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { canonicalJson, digest, fail, shape, integer, jsonClone } from './contracts.mjs';
+import { contentHash, processPolicy, confinedArgv, spawnConfined } from './host-process.mjs';
+import { relativeFile } from './snapshots.mjs';
+import { ItemService } from './items.mjs';
+
+const program = { kind: 'program', id: 'tree-script-broker' };
+export const SCRIPT_LIMITS = Object.freeze({ files: 16, bytes: 262144, args: 65536, timeoutMs: 30000, maximumTimeoutMs: 120000 });
+export const ARG_SCHEMA_FIELDS = Object.freeze({ object: ['type', 'properties', 'required', 'additionalProperties'], array: ['type', 'items', 'maxItems'], string: ['type', 'maxLength', 'enum'], boolean: ['type'], integer: ['type', 'minimum', 'maximum'], number: ['type', 'minimum', 'maximum'] });
+export const ARG_SCHEMA_GUIDANCE = `argSchema is a bounded subset, not arbitrary JSON Schema. Allowed keys by type: ${canonicalJson(ARG_SCHEMA_FIELDS)}. Every object requires properties (at most32 keys), required:[], and additionalProperties:false. Each string REQUIRES integer maxLength0..65536; optional enum has at most256 strings. Do NOT add minLength, pattern, default, description, $schema or $ref. Arrays require maxItems0..256 and items. Numbers/integers require finite minimum and maximum. Boolean has only type. Nesting at most6. Example: {"type":"object","properties":{"source":{"type":"string","maxLength":512},"destination":{"type":"string","maxLength":512}},"required":["source","destination"],"additionalProperties":false}. All successful probe.args must validate against the final schema; do not retroactively require untested fields.`;
+export function scriptPath(path) { relativeFile(path); if (!path.endsWith('.mjs')) fail('SCRIPT_LANGUAGE', 'Only Node ESM .mjs files are supported'); return path; }
+
+/** A closed, bounded JSON-schema subset; no references, coercion or regex. */
+export function validateArgSchema(schema, depth = 0) {
+  if (depth > 6 || !schema || typeof schema !== 'object' || Array.isArray(schema)) fail('ARG_SCHEMA', 'Bounded argument schema required');
+  const allowed = ARG_SCHEMA_FIELDS[schema.type];
+  if (!allowed || Object.keys(schema).some(k => !allowed.includes(k))) fail('ARG_SCHEMA', `Unsupported ${schema.type} argument schema keys; allowed: ${(allowed ?? []).join(', ')}. ${ARG_SCHEMA_GUIDANCE}`);
+  if (schema.type === 'object') {
+    if (!schema.properties || typeof schema.properties !== 'object' || Array.isArray(schema.properties) || Object.keys(schema.properties).length > 32 || schema.additionalProperties !== false || !Array.isArray(schema.required) || schema.required.some(k => !Object.hasOwn(schema.properties, k))) fail('ARG_SCHEMA', 'Closed object properties and required fields must be explicit');
+    for (const [key, value] of Object.entries(schema.properties)) { if (['__proto__', 'constructor', 'prototype'].includes(key)) fail('ARG_SCHEMA', 'Unsafe property'); validateArgSchema(value, depth + 1); }
+  } else if (schema.type === 'array') { integer(schema.maxItems, 'maxItems', 0, 256); validateArgSchema(schema.items, depth + 1); }
+  else if (schema.type === 'string') { if (!Number.isInteger(schema.maxLength) || schema.maxLength < 0 || schema.maxLength > 65536) fail('ARG_SCHEMA', 'Every string requires integer maxLength between 0 and 65536; minLength is not supported.'); if (schema.enum !== undefined && (!Array.isArray(schema.enum) || schema.enum.length > 256 || schema.enum.some(v => typeof v !== 'string' || [...v].length > schema.maxLength))) fail('ARG_SCHEMA', 'Invalid string enumeration'); }
+  else if (['integer', 'number'].includes(schema.type)) { if (!Number.isFinite(schema.minimum) || !Number.isFinite(schema.maximum) || schema.minimum > schema.maximum) fail('ARG_SCHEMA', 'Finite numeric bounds required'); }
+  return schema;
+}
+export function normalizeArgs(schema, args) {
+  validateArgSchema(schema); const bytes = canonicalJson(args); if (Buffer.byteLength(bytes) > SCRIPT_LIMITS.args) fail('ARGS_INVALID', 'Arguments exceed 64 KiB');
+  const check = (s, value) => {
+    if (s.type === 'object') { if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(k => !Object.hasOwn(s.properties, k)) || s.required.some(k => !Object.hasOwn(value, k))) fail('ARGS_INVALID', 'Unexpected or missing argument'); for (const [k, v] of Object.entries(value)) check(s.properties[k], v); }
+    else if (s.type === 'array') { if (!Array.isArray(value) || value.length > s.maxItems) fail('ARGS_INVALID', 'Invalid bounded array'); value.forEach(v => check(s.items, v)); }
+    else if (s.type === 'string') { if (typeof value !== 'string' || [...value].length > s.maxLength || s.enum && !s.enum.includes(value)) fail('ARGS_INVALID', 'Invalid bounded string'); }
+    else if (s.type === 'boolean') { if (typeof value !== 'boolean') fail('ARGS_INVALID', 'Boolean required'); }
+    else if (!Number.isFinite(value) || s.type === 'integer' && !Number.isSafeInteger(value) || value < s.minimum || value > s.maximum) fail('ARGS_INVALID', 'Number outside declared bounds');
+  };
+  check(schema, args); return JSON.parse(bytes);
+}
+
+/** Private content-addressed bytes; no model-selected host path is persisted. */
+export class ScriptArtifacts {
+  constructor({ repository, directory, resolveSource, assertBuild }) { this.repo = repository; mkdirSync(directory, { recursive: true, mode: 0o700 }); this.directory = realpathSync(directory); this.resolveSource = resolveSource;
+    this.assertBuild = assertBuild ?? ((id, artifact) => { const job = this.repo.get('tree_jobs', id); return job?.role === 'script_writer' && job.status === 'committed' && job.resultRef?.artifactId === artifact.id && job.resultRef?.filesHash === digest(artifact.files); }); }
+  sourcePath(hash) { if (!/^[a-f0-9]{64}$/.test(hash)) fail('ARTIFACT_HASH', 'Invalid content identity'); return join(this.directory, hash + '.mjs'); }
+  put(content) {
+    if (typeof content !== 'string' || content.includes('\0') || Buffer.from(content).toString('utf8') !== content || Buffer.byteLength(content) > SCRIPT_LIMITS.bytes) fail('ARTIFACT_CONTENT', 'Bounded UTF-8 source text required');
+    const sha256 = contentHash(content), path = this.sourcePath(sha256);
+    try { writeFileSync(path, content, { flag: 'wx', mode: 0o400 }); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+    this.read({ sha256, size: Buffer.byteLength(content) }); return { sha256, size: Buffer.byteLength(content) };
+  }
+  read(file) {
+    const path = this.sourcePath(file.sha256), fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try { const stat = fstatSync(fd); if (!stat.isFile() || stat.nlink !== 1 || stat.size > SCRIPT_LIMITS.bytes || stat.size !== file.size) fail('ARTIFACT_HASH', 'Artifact file identity changed'); const bytes = readFileSync(fd); if (contentHash(bytes) !== file.sha256) fail('ARTIFACT_HASH', 'Artifact bytes changed'); return bytes; }
+    finally { closeSync(fd); }
+  }
+  verify(artifact) {
+    if (artifact?.language !== 'node-esm' || !Array.isArray(artifact.files) || !artifact.files.length || artifact.files.length > SCRIPT_LIMITS.files) fail('ARTIFACT_INVALID', 'Bounded Node artifact required');
+    const names = new Set(); let bytes = 0;
+    for (const file of artifact.files) { scriptPath(file.path); if (names.has(file.path)) fail('ARTIFACT_INVALID', 'Duplicate artifact path'); names.add(file.path); bytes += this.read(file).length; }
+    if (bytes > SCRIPT_LIMITS.bytes || !names.has(artifact.entry)) fail('ARTIFACT_INVALID', 'Entry or size invalid'); validateArgSchema(artifact.argSchema);
+    return { id: artifact.id, revision: artifact.revision, filesHash: digest(artifact.files) };
+  }
+  activate({ methodId, draftVersion, artifactIds, requestId }) {
+    const item = this.repo.get('tree_items', methodId), bundle = this.repo.get('tree_methods', digest(['method', methodId, draftVersion]));
+    if (!item || !bundle) fail('METHOD_MISSING', 'Draft method missing');
+    const artifacts = artifactIds.map(id => this.repo.get('tree_script_artifacts', id));
+    if (artifacts.some(a => !a || this.assertBuild(a.buildRunId, a) !== true)) fail('ARTIFACT_BUILD_REQUIRED', 'The exact native writer job must commit its final result before activation');
+    if (new Set(artifacts.map(a => a?.requestIndex)).size !== bundle.pendingScriptRequests.length || artifacts.some(a => a?.requestIndex < 0 || a?.requestIndex >= bundle.pendingScriptRequests.length || a?.draftVersion !== draftVersion)) fail('BUNDLE_INCOMPLETE', 'Each requested script must have its own completed artifact');
+    const verifiedArtifacts = artifacts.map(a => this.verify(a)), service = new ItemService({ repository: this.repo, resolveSource: this.resolveSource, context: () => ({ actor: program, verifiedArtifacts }) });
+    const version = this.repo.get('tree_item_versions', digest(['item_version', methodId, draftVersion]));
+    if (!version || version.sourceRefs.some(ref => !this.resolveSource(ref))) fail('SOURCE_STALE', 'Draft evidence was withdrawn');
+    return service.activateDraft({ requestId, expected: { ['tree_items:' + methodId]: item.revision }, input: { itemId: methodId, version: draftVersion, artifactIds } });
+  }
+}
+
+// Module resolution is a dependency rule, not an OS security boundary. The
+// deny-by-default process policy remains authoritative even for eval or native
+// builtin access. Normal imports can use only fixed Node builtins or this bundle.
+function loaderSource(urls) {
+  return `import { registerHooks, isBuiltin } from 'node:module';\nimport { pathToFileURL } from 'node:url';\nconst allowed = new Set(${JSON.stringify(urls)});\nregisterHooks({ resolve(specifier, context, next) { if (!isBuiltin(specifier)) { let url; if (specifier.startsWith('/')) url = pathToFileURL(specifier).href; else if (specifier.startsWith('./') || specifier.startsWith('../') || specifier.startsWith('file:')) url = new URL(specifier, context.parentURL).href; if (!allowed.has(url)) throw new Error('SCRIPT_DEPENDENCY_DENIED'); } const result = next(specifier, context); if (!isBuiltin(result.url) && !allowed.has(result.url)) throw new Error('SCRIPT_DEPENDENCY_DENIED'); return result; }, load(url, context, next) { if (!isBuiltin(url) && !allowed.has(url)) throw new Error('SCRIPT_DEPENDENCY_DENIED'); return next(url, context); } });\n`;
+}
+
+/** Only this owned execution path copies artifact bytes across the private fence. */
+export class ConfinedScriptRunner {
+  enforcement = 'full';
+  async run({ artifact, args, artifacts, policy, readPaths, readOnly = false, timeoutMs = SCRIPT_LIMITS.timeoutMs, signal, assertCurrent, beforeSpawn = () => {} }) {
+    if (!Array.isArray(readPaths)) fail('SCRIPT_READ_SCOPE', 'An inspected ordinary-file read set is required');
+    const reads = [...new Set(readPaths.map(p => join(policy.workspace, relativeFile(p))))];
+    artifacts.verify(artifact); const root = mkdtempSync(join(policy.runtimeRoot, 'method-'));
+    try {
+      const urls = [];
+      for (const file of artifact.files) { const target = join(root, file.path); mkdirSync(dirname(target), { recursive: true, mode: 0o700 }); writeFileSync(target, artifacts.read(file), { flag: 'wx', mode: 0o400 }); urls.push(pathToFileURL(target).href); }
+      const loader = join(root, '.arcfold-loader.mjs'), input = join(root, '.arcfold-input.json');
+      writeFileSync(loader, loaderSource(urls), { flag: 'wx', mode: 0o400 }); writeFileSync(input, canonicalJson(args), { flag: 'wx', mode: 0o400 });
+      const effective = { ...policy, writeRoots: readOnly ? [] : policy.writeRoots, immutableRoots: [...policy.immutableRoots, ...artifact.files.map(f => join(root, f.path)), loader, input] };
+      // Do not grant the entire workspace: credentials, private state, excluded
+      // directories, later-created files and uninspected links stay unreadable.
+      const wrapped = confinedArgv({ policy: { ...effective, workspace: root }, runDirectory: root, argv: [process.execPath, '--max-old-space-size=256', '--import', loader, join(root, artifact.entry), '--input', input, ...(readOnly ? ['--dry-run'] : [])] });
+      const exclusions = [...policy.protectedRoots, policy.runtimeRoot].map(p => `(require-not (subpath ${JSON.stringify(p)}))`).join(' ');
+      // Reading the root directory itself is needed by macOS getcwd; a literal
+      // directory grant does not authorize reading its descendant file bytes.
+      wrapped.argv[2] += '\n(allow file-read* ' + [policy.workspace, ...reads].map(p => `(require-all (literal ${JSON.stringify(p)}) ${exclusions})`).join(' ') + ')';
+      const profileHash = digest(wrapped.argv[2]), profileFile = join(root, '.arcfold-policy.sb');
+      writeFileSync(profileFile, wrapped.argv[2], { flag: 'wx', mode: 0o400 }); wrapped.argv[1] = '-f'; wrapped.argv[2] = profileFile;
+      signal?.throwIfAborted(); await assertCurrent(); signal?.throwIfAborted(); await beforeSpawn({ profileHash, readPaths, argvHash: digest(wrapped.argv) });
+      return await spawnConfined(wrapped, { cwd: policy.workspace, runDirectory: root, signal, timeoutMs: readOnly ? Math.min(timeoutMs, 10000) : timeoutMs, outputLimit: readOnly ? 65536 : 1048576, assertCurrent });
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  }
+}
+
+export class MethodScriptBroker {
+  constructor({ repository, artifacts, snapshots, context, readScope, resolveSource, authorizeWrites, runtimeRoot, protectedRoots, runner = new ConfinedScriptRunner(), allowUnconfinedFixture = false }) {
+    if ([context, readScope, resolveSource, authorizeWrites].some(f => typeof f !== 'function')) fail('SCRIPT_HOST', 'Trusted authority, scope, sources and write authorization are required');
+    Object.assign(this, { repo: repository, artifacts, snapshots, context, readScope, resolveSource, authorizeWrites, runtimeRoot, protectedRoots, runner });
+    if (runner.enforcement !== 'full' && !allowUnconfinedFixture) fail('SANDBOX_UNAVAILABLE', 'Scripts require full process confinement'); this.active = new Map();
+  }
+  freeze(input) {
+    shape(input, ['methodId', 'expectedVersion', 'scriptId', 'args']); const ctx = this.context();
+    if (ctx.actor?.kind !== 'model' || ctx.actor.role !== 'main' || !ctx.sessionId || !ctx.nativeToolCallId) fail('MAIN_REQUIRED', 'Only an owned main-agent tool call may execute a method script');
+    const scope = this.readScope(ctx.sessionId), item = this.repo.get('tree_items', input.methodId), bundle = this.repo.get('tree_methods', digest(['method', input.methodId, input.expectedVersion]));
+    if (!scope || scope.phase !== 'active' || !scope.nodeIds.length) fail('SCOPE_STALE', 'No admitted main scope');
+    if (!item || item.kind !== 'method' || item.lifecycle !== 'active' || item.stale || item.activeVersion !== input.expectedVersion || !bundle || bundle.pendingScriptRequests.length) fail('METHOD_STALE', 'Method is not currently executable');
+    if (!scope.nodeIds.some(id => this.repo.ancestors(id).some(n => n.id === item.nodeId))) fail('OUT_OF_SCOPE', 'Method is outside current node ancestry');
+    const version = this.repo.get('tree_item_versions', digest(['item_version', item.id, item.activeVersion])); if (!version || version.sourceRefs.some(ref => !this.resolveSource(ref))) fail('SOURCE_STALE', 'Method source is no longer eligible');
+    const ref = bundle.scripts.find(s => s.id === input.scriptId), artifact = ref && this.repo.list('tree_script_artifacts', a => a.scriptId === ref.id && a.version === ref.version && a.methodId === item.id)[0];
+    if (!artifact || artifact.activationState !== 'ready' || digest(artifact.files) !== ref.hash) fail('ARTIFACT_STALE', 'No active artifact version'); this.artifacts.verify(artifact);
+    const args = normalizeArgs(artifact.argSchema, input.args), authorization = this.authorizeWrites({ context: ctx, scope, item, artifact, args });
+    if (!authorization || authorization.then || !Array.isArray(authorization.paths) || !authorization.authorizationRef) fail('SCRIPT_AUTHORIZATION', 'Synchronous host write authorization required');
+    const paths = [...new Set(authorization.paths.map(relativeFile))].sort();
+    const policy = processPolicy({ workspace: this.snapshots.workspace, runtimeRoot: this.runtimeRoot, protectedRoots: [...this.protectedRoots, this.artifacts.directory, this.snapshots.storageRoot], sessionPolicy: ctx.sessionPolicy, authorizedWriteRoots: paths.map(p => join(this.snapshots.workspace, p)) });
+    // Read-only calls may inspect data but cannot acquire any declared writes.
+    if (paths.length && !policy.writeRoots.length) fail('SCRIPT_POLICY', 'Current session does not authorize these writes');
+    const ticket = { sessionId: ctx.sessionId, nativeToolCallId: ctx.nativeToolCallId, actor: ctx.actor, scope, itemId: item.id, methodVersion: item.activeVersion, itemRevision: item.revision, artifactId: artifact.id, artifactRevision: artifact.revision, filesHash: digest(artifact.files), argsHash: digest(args), authorization, policyHash: digest(policy), workspaceIdentity: this.snapshots.identity };
+    return { ticket: jsonClone({ ...ticket, key: digest(ticket) }), artifact, args, paths, policy };
+  }
+  assertCurrent(frozen, input) { this.snapshots.assertIdentity(); if (this.freeze(input).ticket.key !== frozen.ticket.key) fail('SCRIPT_STALE', 'Execution authority changed'); }
+  update(id, updates) {
+    const old = this.repo.get('tree_script_runs', id); if (!old) fail('SCRIPT_RUN', 'Missing durable run intent');
+    this.repo.command('recordTreeScriptResult', { requestId: digest([id, old.revision, updates]), expected: {}, input: { id, ...updates } }, program, () => {
+      const row = this.repo.get('tree_script_runs', id); if (row.revision !== old.revision) fail('REVISION_CONFLICT', 'Script result changed');
+      this.repo.save('tree_script_runs', { ...row, ...updates, ...(row.state === 'revoked' ? { state: 'revoked' } : {}) }, row.revision); return { runId: id };
+    }); return this.repo.get('tree_script_runs', id);
+  }
+  invalidate() { for (const run of this.active.values()) { try { this.assertCurrent(run.frozen, run.input); } catch { run.abort.abort(); } } }
+  cancelSession(sessionId) { for (const run of this.active.values()) if (run.frozen.ticket.sessionId === sessionId) run.abort.abort(); }
+  async run(input, { signal } = {}) {
+    input = jsonClone(input); const frozen = this.freeze(input), id = digest(['script-run', frozen.ticket.sessionId, frozen.ticket.nativeToolCallId]);
+    if (this.active.has(id)) fail('SCRIPT_ACTIVE', 'This native tool call is already executing');
+    const previous = this.repo.get('tree_script_runs', id);
+    if (previous) { if (previous.inputHash !== digest(input)) fail('IDEMPOTENCY_CONFLICT', 'Native tool call changed'); return previous; }
+    const abort = new AbortController(), combined = signal ? AbortSignal.any([signal, abort.signal]) : abort.signal; this.active.set(id, { abort, frozen, input });
+    // Native withdrawal/scope events call invalidate immediately. This bounded
+    // watcher also catches changes committed by another session/process.
+    const watcher = setInterval(() => this.invalidate(), 25); watcher.unref();
+    try {
+      return await this.snapshots.locked(async () => {
+        combined.throwIfAborted(); this.snapshots.assertAvailable(); this.assertCurrent(frozen, input);
+        const snapshot = await this.snapshots.captureLocked({ requestId: id, reason: 'script', protectedPaths: frozen.paths, signal: combined });
+        combined.throwIfAborted(); this.assertCurrent(frozen, input);
+        this.repo.command('prepareTreeScript', { requestId: id, expected: {}, input: { input, ticket: frozen.ticket, snapshotId: snapshot.id } }, program, () => {
+          this.repo.save('tree_script_runs', { id, runId: id, methodVersion: { itemId: input.methodId, version: input.expectedVersion }, nodeEpoch: frozen.ticket.scope.epoch, workspaceIdentity: frozen.ticket.workspaceIdentity,
+            policyHash: frozen.ticket.policyHash, snapshotId: snapshot.id, argvHash: digest({ interpreter: process.execPath, artifact: frozen.ticket.filesHash, entry: frozen.artifact.entry, args: frozen.args }), inputHash: digest(input), ticket: frozen.ticket, state: 'prepared', processState: 'prepared' }); return { runId: id };
+        });
+        try {
+          const readPaths = [...new Set([...snapshot.manifest.files.map(f => f.path), ...frozen.paths])];
+          const result = await this.runner.run({ ...frozen, readPaths, artifacts: this.artifacts, signal: combined, timeoutMs: frozen.artifact.timeoutMs ?? SCRIPT_LIMITS.timeoutMs,
+            assertCurrent: () => this.assertCurrent(frozen, input), beforeSpawn: evidence => this.update(id, { state: 'spawn_intent', processState: 'spawn_intent', executionPolicy: evidence, policyHash: digest({ policy: frozen.policy, ...evidence }) }) });
+          return this.update(id, { state: result.code === 0 && !result.reason && !result.truncated ? 'succeeded' : result.reason === 'cancelled' ? 'cancelled' : 'failed', processState: 'completed', result, completedAt: this.repo.now() });
+        } catch (error) {
+          const current = this.repo.get('tree_script_runs', id), notStarted = current.processState === 'prepared'; return this.update(id, { state: notStarted ? 'failed' : 'unknown', processState: notStarted ? 'not_started' : 'unknown', error: { code: error.code ?? 'SCRIPT_PROCESS', message: error.message }, completedAt: this.repo.now() });
+        }
+      });
+    } finally { clearInterval(watcher); this.active.delete(id); }
+  }
+  recover(id) {
+    if (this.active.has(id)) fail('SCRIPT_ACTIVE', 'Current process still owns this execution'); const run = this.repo.get('tree_script_runs', id);
+    if (!run) fail('SCRIPT_RUN', 'Unknown execution');
+    // A completed process receipt is written in the same command as its result.
+    // Without it, preserve uncertainty; never run the generated program again.
+    const pending = ['prepared', 'spawn_intent'].includes(run.processState ?? run.state);
+    return pending ? this.update(id, { state: (run.processState ?? run.state) === 'prepared' ? 'failed' : 'unknown', processState: (run.processState ?? run.state) === 'prepared' ? 'not_started' : 'unknown', error: { code: 'HOST_INTERRUPTED', message: 'No durable completed process result' } }) : run;
+  }
+}
+
+/** Public tool surface; bind only to B7's admitted main-agent instance. */
+export function mountMethodScriptTool(agentContext, { host, defineTool, isMain, resolveBroker }) {
+  if ([defineTool, isMain, resolveBroker].some(fn => typeof fn !== 'function')) fail('SCRIPT_HOST', 'Native tool registration requires trusted main ownership');
+  agentContext.tools.register(defineTool({ name: 'arcfold_run_method_script', description: 'Execute one active method script in the current goal scope. The host checks its exact version, current file permissions and snapshot coverage. This does not grant new permissions.',
+    parameters: { methodId: { type: 'string', required: true }, expectedVersion: { type: 'integer', required: true }, scriptId: { type: 'string', required: true }, args: { type: 'object', additionalProperties: true, required: true } },
+    output: { schema: { type: 'json' }, render: (_args, result) => [{ type: 'text', text: JSON.stringify(result) }] },
+    async execute(input, exec) {
+      const check = () => {
+        exec.signal?.throwIfAborted(); const agent = exec.agent;
+        if (!agent || host.agents.get(agent.id) !== agent || host.agents.currentInitiator() !== agent || agent.status !== 'running' || isMain(agent.session.id) !== true || exec.parent !== undefined || exec.callId !== exec.rootCallId) fail('MAIN_REQUIRED', 'Only the exact live native main tool call may cross the script boundary');
+        return agent;
+      };
+      const agent = check(); if (await host.sessions.flush(agent.session) !== true) fail('SCRIPT_NATIVE_EVIDENCE', 'The native tool call must be durable before script execution'); check();
+      const events = agent.session.snapshotEvents(), call = events.filter(e => e.type === 'tool/call' && e.data.callId === exec.callId);
+      const step = events.findLast(e => e.type === 'step/start'), turn = events.findLast(e => e.type === 'turn/start'), assistant = call.length === 1 && events.findLast(e => e.type === 'assistant/message' && e.seq < call[0].seq);
+      const block = assistant?.data.message.content?.filter(b => b.type === 'tool-call' && b.id === exec.callId);
+      if (call.length !== 1 || !step || !turn || !assistant || assistant.data.message.source?.kind !== 'model' || assistant.data.interrupted || block?.length !== 1 || block[0].name !== 'arcfold_run_method_script' || call[0].data.name !== block[0].name || call[0].data.arguments !== block[0].arguments || canonicalJson(JSON.parse(call[0].data.arguments)) !== canonicalJson(input) || canonicalJson(exec.arguments) !== canonicalJson(input) || step.seq <= turn.seq || assistant.seq <= step.seq || call[0].data.turn !== turn.data.turn || call[0].data.step !== step.data.step || events.some(e => e.seq > step.seq && ['step/end', 'turn/end'].includes(e.type)) || events.some(e => e.seq > call[0].seq && e.type === 'tool/result' && e.data.message?.toolCallId === exec.callId)) fail('SCRIPT_NATIVE_EVIDENCE', 'Script arguments and identity must match one unfinished durable native tool call');
+      const broker = resolveBroker({ agent, sessionId: agent.session.id, callId: exec.callId, turn: turn.data.turn, step: step.data.step });
+      if (!(broker instanceof MethodScriptBroker)) fail('SCRIPT_HOST', 'No trusted script broker for this main call');
+      const run = await broker.run(input, { signal: exec.signal });
+      return { runId: run.id, state: run.state, processState: run.processState, snapshotId: run.snapshotId, coverage: broker.snapshots.snapshot(run.snapshotId).coverage, result: run.result ?? null, error: run.error ?? null };
+    },
+  }));
+}

package/src/tree/signals.mjs

@@ -0,0 +1,118 @@
+import { canonicalJson, digest, fail, oneOf, sourceRefs } from './contracts.mjs';
+import { SignalService } from './tree.mjs';
+
+export const signalPolarity = category => category === 'proceeded' ? 'weak' : ['approved', 'adopted_proposal', 'confirmed_inference'].includes(category) ? 'strong' : 'negative';
+const program = { kind: 'program', id: 'tree-signal-evidence' };
+const unique = values => [...new Map(values.map(v => [canonicalJson(v), v])).values()];
+export function evidenceResolver(repo, nativeResolve) {
+  return ref => {
+    if (ref.sessionId !== 'arcfold-ui:' + repo.rootId()) return nativeResolve(ref);
+    const event = repo.list('tree_change_events', e => e.ordinal === ref.seq)[0];
+    if (!event || event.actor.kind !== 'user' || digest(event) !== ref.sha256) return null;
+    const receipt = repo.get('tree_receipts', event.receiptId);
+    return { id: digest(['ui-source', ref]), role: 'user', origin: 'ui', text: canonicalJson({ operation: event.commandType, entityIds: event.entityIds, result: receipt.result }), ref, sha256: ref.sha256 };
+  };
+}
+
+/** Corrections replace an observation in derived views, never its audit row. */
+export function effectiveSignals(repo, resolveSource = () => true) {
+  const rows = repo.list('tree_signals'), byId = new Map(rows.map(r => [r.id, r]));
+  const ordinals = new Map();
+  for (const event of repo.list('tree_change_events')) for (const [index, key] of event.entityIds.entries()) if (key.startsWith('tree_signals:') && event.beforeVersions[index] === 0) ordinals.set(key.slice('tree_signals:'.length), event.ordinal);
+  const root = row => { const seen = new Set(); while (row.correctionOf) { if (seen.has(row.id) || !byId.has(row.correctionOf)) fail('SIGNAL_HISTORY', 'Broken correction chain'); seen.add(row.id); row = byId.get(row.correctionOf); } return row.id; };
+  const latest = new Map();
+  for (const row of rows) { const key = root(row), old = latest.get(key); if (!old || (ordinals.get(row.id) ?? 0) > (ordinals.get(old.id) ?? 0)) latest.set(key, row); }
+  return [...latest.values()].filter(r => r.sourceRefs.every(resolveSource));
+}
+
+/** One human message is one episode even when several nodes learn from it. */
+export class EpisodeSignals {
+  constructor({ repository, resolveSource, experience }) { Object.assign(this, { repo: repository, resolveSource, experience }); }
+  recordCategories(categories, { job, requestId }) {
+    const actor = { kind: 'model', id: job.id, role: job.role }, nodeIds = job.nodeIds;
+    const signalService = new SignalService({ repository: this.repo, resolveSource: this.resolveSource, context: () => ({ actor, nodeIds }) });
+    return this.repo.transaction(() => categories.map((category, index) => {
+      const source = job.input.sources.find(s => s.id === category.sourceId);
+      if (!source || source.role !== 'user' || source.origin !== 'user' || !job.input.currentTurn?.sourceIds.includes(source.id) || !this.resolveSource(source.ref)) fail('SIGNAL_USER_REQUIRED', 'Categories must refer to the current real human message');
+      const turn = this.repo.list('tree_turns', t => t.status === 'settled' && t.userSourceRefs.some(r => digest(r) === digest(source.ref)))[0];
+      if (!turn || !turn.nodeIds.some(id => nodeIds.includes(id))) fail('SIGNAL_SCOPE', 'Referenced message must belong to settled experience in this scope');
+      const eventId = digest(['human-message', source.ref]), episodeId = digest(['episode', eventId]);
+      const signal = signalService.record({ requestId: digest([requestId, 'category', index]), expected: {}, input: { eventId, subjectRefs: category.subjectIds,
+        dimension: 'collaboration', subitem: category.category, category: category.category, polarity: signalPolarity(category.category), evidenceKind: 'language', sourceRefs: [source.ref], nodeIds: turn.nodeIds, confidence: 1 } }).result;
+      this.repo.command('recordSignalEpisode', { requestId: digest([requestId, 'episode', index]), expected: {}, input: { episodeId, signalId: signal.signalId, note: category.note } }, actor, () => {
+        const old = this.repo.get('tree_episodes', episodeId);
+        const previous = this.repo.list('tree_turns', t => t.sessionId === turn.sessionId && t.nativeTurn < turn.nativeTurn && t.status === 'settled').sort((a, b) => b.nativeTurn - a.nativeTurn)[0];
+        const beforeRefs = previous?.nodeIds.some(id => turn.nodeIds.includes(id)) ? this.experience.material(previous).sources.filter(s => s.role === 'assistant' && s.origin === 'model').map(s => s.ref) : [];
+        const resolutionRefs = this.experience.material(turn).sources.filter(s => s.role === 'assistant' && s.origin === 'model').map(s => s.ref);
+        this.repo.save('tree_episodes', { ...old, id: episodeId, eventId, turnId: turn.id, signalIds: [...new Set([...(old?.signalIds ?? []), signal.signalId])],
+          beforeTurnId: previous?.id ?? null, beforeRefs, reactionRefs: [source.ref], resolutionRefs, nodeIds: turn.nodeIds, state: 'observed', start: old?.start ?? this.repo.now(), ordinal: old?.ordinal ?? this.repo.meta().lastEventOrdinal + 1,
+          annotations: [...(old?.annotations ?? []), { jobId: job.id, category: category.category, note: category.note }] }, old?.revision ?? null);
+        return { episodeId };
+      });
+      return { ...signal, episodeId };
+    }));
+  }
+  episodes() {
+    const signals = effectiveSignals(this.repo, this.resolveSource);
+    return this.repo.list('tree_episodes').map(e => {
+      const turn = e.turnId && this.repo.get('tree_turns', e.turnId);
+      const before = e.beforeTurnId && this.repo.get('tree_turns', e.beforeTurnId);
+      // Preserve stored audit refs, but remove a preceding answer from derived
+      // input when it no longer shares the corrected current assignment.
+      const beforeRefs = turn && !before?.nodeIds.some(id => turn.nodeIds.includes(id)) ? [] : e.beforeRefs;
+      return { ...e, beforeRefs, nodeIds: turn?.nodeIds ?? e.nodeIds, signals: signals.filter(s => s.eventId === e.eventId) };
+    }).filter(e => e.reactionRefs.every(this.resolveSource));
+  }
+  captureConfirmation(receiptId) {
+    const receipt = this.repo.get('tree_receipts', receiptId), event = receipt && this.repo.get('tree_change_events', receipt.eventIds[0]);
+    if (!event || event.actor.kind !== 'user' || event.commandType !== 'confirmItem') fail('UI_CONFIRMATION', 'Only an actual trusted user confirmation receipt is strong confirmation evidence');
+    const eventId = digest(['user-operation', receiptId]), id = digest(['episode', eventId]), existing = this.repo.get('tree_episodes', id); if (existing) return existing;
+    if (event.ordinal !== this.repo.meta().lastEventOrdinal) fail('UI_CONFIRMATION_ORDER', 'Capture UI evidence in the same outer transaction as confirmation');
+    const item = this.repo.get('tree_items', receipt.result.itemId);
+    if (!item || item.kind !== 'understanding' || item.activeVersion !== receipt.result.version) fail('UI_CONFIRMATION', 'Confirmation must identify the exact current understanding version');
+    const version = this.repo.get('tree_item_versions', digest(['item_version', item.id, item.activeVersion]));
+    const previous = this.repo.get('tree_item_versions', digest(['item_version', item.id, version.supersedes]));
+    if (previous?.sourceKind !== 'assistant_inferred') return null;
+    const ref = { sessionId: 'arcfold-ui:' + this.repo.rootId(), seq: event.ordinal, sha256: digest(event) }, resolver = evidenceResolver(this.repo, this.resolveSource);
+    const service = new SignalService({ repository: this.repo, resolveSource: resolver, context: () => ({ actor: event.actor }) });
+    return this.repo.transaction(() => {
+      const signal = service.record({ requestId: digest([id, 'signal']), expected: {}, input: { eventId, subjectRefs: [item.id], dimension: 'collaboration', subitem: 'confirmed_inference', category: 'confirmed_inference', polarity: 'strong', evidenceKind: 'ui', sourceRefs: [ref], nodeIds: [item.nodeId], confidence: 1 } }).result;
+      this.repo.command('captureUserConfirmation', { requestId: id, expected: {}, input: { receiptId, sourceRefs: [ref] } }, program, () => {
+        this.repo.save('tree_episodes', { id, eventId, signalIds: [signal.signalId], beforeRefs: [], reactionRefs: [ref], resolutionRefs: [], nodeIds: [item.nodeId], state: 'observed', start: event.createdAt, ordinal: event.ordinal, confirmationRef: receiptId }); return { episodeId: id };
+      }); return this.repo.get('tree_episodes', id);
+    });
+  }
+  // Controls come from a trusted explicit observation of a proposal and its
+  // response. No-response is unknown; only actual rejecting evidence is rejected.
+  control({ proposalRef, responseRefs, nodeIds, category, outcome, requestId }) {
+    oneOf(outcome, ['ignored', 'unknown', 'rejected'], 'control outcome');
+    oneOf(category, ['approved', 'adopted_proposal', 'confirmed_inference'], 'control category');
+    const proposal = this.resolveSource(proposalRef);
+    if (proposal?.role !== 'assistant' || proposal.origin !== 'model') fail('PROPOSAL_SOURCE', 'A control must identify the actual assistant proposal');
+    sourceRefs([proposalRef], this.resolveSource); sourceRefs(responseRefs, this.resolveSource, { required: outcome !== 'unknown', user: outcome !== 'unknown' });
+    for (const id of nodeIds) if (!this.repo.get('tree_nodes', id)) fail('NODE_NOT_FOUND', 'Unknown control node');
+    const id = digest(['proposal-control', proposalRef, category]);
+    return this.repo.command('recordProposalControl', { requestId, expected: {}, input: { proposalRef, responseRefs, nodeIds, category, outcome } }, program, () => {
+      const old = this.repo.get('tree_episodes', id);
+      this.repo.save('tree_episodes', { ...old, id, eventId: id, signalIds: [], beforeRefs: [proposalRef], reactionRefs: responseRefs, resolutionRefs: [], nodeIds,
+        state: 'control', category, outcome, start: old?.start ?? this.repo.now(), ordinal: old?.ordinal ?? this.repo.meta().lastEventOrdinal + 1, history: [...(old?.history ?? []), { outcome, responseRefs }] }, old?.revision ?? null);
+      return { episodeId: id };
+    }).result;
+  }
+  material(episode) {
+    return { ...episode, sources: unique([...episode.beforeRefs, ...episode.reactionRefs, ...episode.resolutionRefs]).map(ref => {
+      const s = this.resolveSource(ref); if (!s) fail('SOURCE_CHANGED', 'Episode evidence was withdrawn'); return { ...s, ref, id: s.id ?? digest(ref) };
+    }) };
+  }
+  hookCandidates() {
+    const runs = this.repo.list('tree_hook_runs'), groups = new Map();
+    for (const run of runs.filter(r => r.result.status === 'needs_action')) {
+      const id = digest([run.logicalTurnId, run.methodId, run.version]);
+      if (!groups.has(id)) groups.set(id, { id, logicalTurnId: run.logicalTurnId, methodId: run.methodId, version: run.version, hookRunIds: [], recovered: true });
+      const group = groups.get(id); group.hookRunIds.push(run.id);
+      group.recovered &&= runs.some(r => r.logicalTurnId === run.logicalTurnId && r.hookId === run.hookId && r.version === run.version && r.eventOrdinal > run.eventOrdinal && r.result.status === 'pass');
+    }
+    // These are execution observations, never additional human negative signals.
+    return [...groups.values()].map(group => ({ ...group, kind: 'hook_omission_candidate', separateHumanSignal: false }));
+  }
+}