@arcfold/dsh 0.0.0-stage → 0.4.0

package/src/store.mjs

@@ -0,0 +1,394 @@
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync, chmodSync, existsSync, openSync, closeSync, readSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+export class DomainError extends Error {
+  constructor(code, message, status = 409, details) {
+    super(message);
+    this.name = 'DomainError';
+    this.code = code;
+    this.status = this.statusCode = status;
+    if (details !== undefined) this.details = details;
+  }
+}
+
+// Preserve the 3.0 JSON contract without its job, lease or execution machinery.
+export function jsonClone(value) {
+  const ancestors = new Set();
+  function visit(item) {
+    if (item === null || typeof item === 'string' || typeof item === 'boolean') return;
+    if (typeof item === 'number' && Number.isFinite(item)) return;
+    if (typeof item !== 'object' || ancestors.has(item))
+      throw new DomainError('invalid_record', 'Only finite, acyclic JSON values can be saved.', 400);
+    const prototype = Object.getPrototypeOf(item);
+    if (!Array.isArray(item) && prototype !== Object.prototype && prototype !== null)
+      throw new DomainError('invalid_record', 'Only plain JSON objects can be saved.', 400);
+    if (Reflect.ownKeys(item).some(key => typeof key === 'symbol'))
+      throw new DomainError('invalid_record', 'Symbol keys cannot be saved.', 400);
+    ancestors.add(item);
+    if (Array.isArray(item)) {
+      for (let i = 0; i < item.length; i++) {
+        if (!Object.hasOwn(item, i)) throw new DomainError('invalid_record', 'Sparse arrays cannot be saved.', 400);
+        visit(item[i]);
+      }
+    } else {
+      for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(item))) {
+        if (!Object.hasOwn(descriptor, 'value')) throw new DomainError('invalid_record', 'Accessors cannot be saved.', 400);
+        visit(descriptor.value);
+      }
+    }
+    ancestors.delete(item);
+  }
+  visit(value);
+  return JSON.parse(JSON.stringify(value));
+}
+
+export function canonicalJson(value) {
+  const item = jsonClone(value);
+  function sorted(value) {
+    if (Array.isArray(value)) return value.map(sorted);
+    if (value && typeof value === 'object')
+      return Object.fromEntries(Object.keys(value).sort().map(key => [key, sorted(value[key])]));
+    return value;
+  }
+  return JSON.stringify(sorted(item));
+}
+
+export function identity(value, label) {
+  if (typeof value !== 'string' || !value.trim() || value.length > 512 || value.includes('\0'))
+    throw new DomainError('invalid_identity', `${label} must be a nonempty string of at most 512 characters.`, 400);
+}
+
+function filters(where = {}) {
+  if (!where || typeof where !== 'object' || Array.isArray(where) || Object.getPrototypeOf(where) !== Object.prototype)
+    throw new DomainError('invalid_filter', 'Filters must be a plain object.', 400);
+  const clauses = [], parameters = [];
+  for (const [field, value] of Object.entries(where)) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(field) ||
+        (!['string', 'number', 'boolean'].includes(typeof value) && value !== null) ||
+        (typeof value === 'number' && !Number.isFinite(value)))
+      throw new DomainError('invalid_filter', 'Filters require safe field names and scalar values.', 400);
+    clauses.push('json_extract(body,?) IS ?');
+    parameters.push('$.' + field, typeof value === 'boolean' ? Number(value) : value);
+  }
+  return { sql: clauses.length ? ' AND ' + clauses.join(' AND ') : '', parameters };
+}
+
+const IMMUTABLE = new Set(['dsh_events', 'events', 'deliveries']);
+const WEB_BUDGET_MODE = 'web-only-budget-v1';
+const WEB_BUDGET_APPLICATION_ID = 0x41574631; // AWF1: format discriminator, never authorization.
+const WEB_TABLES = {
+  records: `CREATE TABLE records (
+    kind TEXT NOT NULL, id TEXT NOT NULL, revision INTEGER NOT NULL CHECK(revision > 0),
+    created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+    body TEXT NOT NULL CHECK(json_valid(body)), PRIMARY KEY(kind,id)
+  )`,
+  store_meta: 'CREATE TABLE store_meta (key TEXT PRIMARY KEY,value TEXT NOT NULL)',
+  budget_requests: `CREATE TABLE budget_requests (
+    id TEXT PRIMARY KEY, body_hash TEXT NOT NULL,
+    status TEXT NOT NULL CHECK(status IN ('reserved','dispatched','unknown','settled','released')),
+    reserved_micro INTEGER NOT NULL CHECK(reserved_micro>=0),
+    spent_micro INTEGER NOT NULL CHECK(spent_micro>=0),
+    body TEXT NOT NULL CHECK(json_valid(body)),
+    scope TEXT NOT NULL DEFAULT 'web-unlimited' CHECK(scope='web-unlimited')
+  )`,
+};
+const normalizedSql = value => value.replace(/\s+/g, ' ').trim();
+
+// Read only the application-owned format field, without opening SQLite. An
+// absent/zero/different id does not prove ownership and retains old-mode behavior.
+function fileApplicationId(filename) {
+  const bytes = Buffer.alloc(4), descriptor = openSync(filename, 'r');
+  try { return readSync(descriptor, bytes, 0, 4, 68) === 4 ? bytes.readUInt32BE(0) : null; }
+  finally { closeSync(descriptor); }
+}
+
+// Pure web ledgers use rollback journaling. Refuse other/unfinished files before
+// SQLite could recover a journal or create WAL sidecars while inspecting them.
+export function assertWebBudgetFileFormat(filename) {
+  const header = Buffer.alloc(20), descriptor = openSync(filename, 'r');
+  let count;
+  try { count = readSync(descriptor, header, 0, header.length, 0); }
+  finally { closeSync(descriptor); }
+  if (count !== 20 || header.subarray(0, 16).toString() !== 'SQLite format 3\0' ||
+      header[18] !== 1 || header[19] !== 1 || fileApplicationId(filename) !== WEB_BUDGET_APPLICATION_ID)
+    throw new DomainError('unsupported_ledger_schema', 'An intact, idle web-only ledger is required.', 409);
+}
+
+function assertWebFile(filename) {
+  assertWebBudgetFileFormat(filename);
+  if (['-journal', '-wal', '-shm'].some(suffix => existsSync(filename + suffix)))
+    throw new DomainError('unsupported_ledger_schema', 'An intact, idle web-only ledger is required.', 409);
+}
+
+/** JSON business records; this store never claims or runs DSH work. */
+export class Store {
+  // Internal owned-recovery handoff: never a configuration bypass. Every
+  // supplied connection is validated; the caller retains it on success.
+  static fromWebBudgetConnection(db, { filename, webBudgetIdentity }) {
+    if (!(db instanceof DatabaseSync)) throw new DomainError('invalid_connection', 'A native SQLite connection is required.');
+    const store = Object.create(Store.prototype);
+    Object.assign(store, { db, filename: resolve(filename), webBudget: true, legacyLedger: false,
+      legacyRecords: true, metaTable: 'store_meta', closed: false, depth: 0, savepointSequence: 0 });
+    const identity = jsonClone(webBudgetIdentity);
+    if (!identity || Object.keys(identity).sort().join(',') !== 'id,specification' ||
+        identity.specification?.scope !== 'web-unlimited')
+      throw new DomainError('invalid_web_authorization', 'An explicit web budget identity is required.');
+    store.webBudgetIdentity = Object.freeze({ id: identity.id, specification: Object.freeze(identity.specification) });
+    const version = db.prepare('SELECT sqlite_version() AS version').get().version.split('.').map(Number);
+    if (version[0] < 3 || version[0] === 3 && (version[1] < 51 || version[1] === 51 && version[2] < 3))
+      throw new DomainError('unsupported_sqlite', 'Ledger accounting requires SQLite >= 3.51.3.', 500);
+    store.assertWebBudgetSchema();
+    return store;
+  }
+  constructor(filename, { mode = 'business', create = false, webBudgetIdentity } = {}) {
+    if (typeof filename !== 'string' || !filename)
+      throw new DomainError('invalid_path', 'A database filename is required.', 400);
+    if (!['business', 'legacy-ledger-v2', 'legacy-records-v2', WEB_BUDGET_MODE].includes(mode) || typeof create !== 'boolean')
+      throw new DomainError('invalid_store_mode', 'Unsupported store mode.', 400);
+    this.webBudget = mode === WEB_BUDGET_MODE;
+    if (this.webBudget) {
+      const expected = jsonClone(webBudgetIdentity);
+      if (!expected || Object.keys(expected).sort().join(',') !== 'id,specification' ||
+          expected.specification?.scope !== 'web-unlimited')
+        throw new DomainError('invalid_web_authorization', 'An explicit web budget identity is required.', 400);
+      identity(expected.id, 'Web authorization id');
+      this.webBudgetIdentity = Object.freeze({ id: expected.id, specification: Object.freeze(expected.specification) });
+    }
+    this.legacyLedger = mode === 'legacy-ledger-v2';
+    this.legacyRecords = this.webBudget || this.legacyLedger || mode === 'legacy-records-v2';
+    this.metaTable = this.legacyRecords ? 'store_meta' : 'business_meta';
+    this.filename = filename === ':memory:' ? filename : resolve(filename);
+    let existed = this.filename !== ':memory:' && existsSync(this.filename);
+    let newWebFile = this.filename === ':memory:' && create;
+    if (this.webBudget && this.filename !== ':memory:' && create) {
+      mkdirSync(dirname(this.filename), { recursive: true, mode: 0o700 });
+      try {
+        const descriptor = openSync(this.filename, 'wx', 0o600);
+        closeSync(descriptor); newWebFile = true; existed = false;
+      } catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        existed = true;
+      }
+    }
+    // A committed web format must be rejected by every other mode before any
+    // SQLite handle/read can trigger recovery of the original hot journal.
+    if (!this.webBudget && existed && fileApplicationId(this.filename) === WEB_BUDGET_APPLICATION_ID)
+      throw new DomainError('invalid_store_mode', 'A web-only ledger requires its explicit mode and authorization.', 409);
+    if (this.webBudget && existed) assertWebFile(this.filename);
+    if (this.legacyRecords && !existed && !create)
+      throw new DomainError('ledger_missing', 'An existing authorized ledger is required.', 409);
+    if (this.filename !== ':memory:') mkdirSync(dirname(this.filename), { recursive: true, mode: 0o700 });
+    this.db = new DatabaseSync(this.filename);
+    this.closed = false;
+    this.depth = 0;
+    this.savepointSequence = 0;
+    try {
+      if (this.webBudget) {
+        this.db.exec('PRAGMA busy_timeout=30000; PRAGMA synchronous=FULL');
+        const version = this.db.prepare('SELECT sqlite_version() AS version').get().version.split('.').map(Number);
+        if (version[0] < 3 || version[0] === 3 && (version[1] < 51 || version[1] === 51 && version[2] < 3))
+          throw new DomainError('unsupported_sqlite', 'Ledger accounting requires SQLite >= 3.51.3.', 500);
+        this.transaction(() => {
+          if (newWebFile) {
+            if (this.db.prepare('SELECT 1 FROM sqlite_schema LIMIT 1').get())
+              throw new DomainError('unsupported_ledger_schema', 'The exclusively created file must be empty.', 409);
+            this.db.exec('PRAGMA main.application_id=' + WEB_BUDGET_APPLICATION_ID);
+            for (const sql of Object.values(WEB_TABLES)) this.db.exec(sql);
+            this.db.exec("CREATE INDEX records_by_kind_time ON records(kind,created_at,id); INSERT INTO store_meta VALUES ('schema_version','2'),('mutation_sequence','0')");
+            this.db.prepare('INSERT INTO store_meta VALUES (?,?)').run('web_budget_mode',
+              canonicalJson({ mode: WEB_BUDGET_MODE, authorization: this.webBudgetIdentity }));
+            this.save('budget_authorizations', { ...this.webBudgetIdentity, appliedAt: new Date().toISOString() });
+          }
+          this.assertWebBudgetSchema();
+        });
+        return;
+      }
+      // Other Store modes must not mutate a separately authorized web ledger.
+      if (this.db.prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name='store_meta'").get() &&
+          this.db.prepare("SELECT 1 FROM store_meta WHERE key='web_budget_mode'").get())
+        throw new DomainError('invalid_store_mode', 'A web-only ledger requires its explicit mode and authorization.', 409);
+      // Validate before any schema or journal write. Never re-establish old order
+      // from rowid, and never create business_meta beside the legacy counter.
+      if (this.legacyRecords && existed) {
+        for (const table of ['records', 'store_meta', ...(this.legacyLedger ? ['budget_settings', 'budget_requests'] : [])]) {
+          if (!this.db.prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name=?").get(table))
+            throw new DomainError('unsupported_ledger_schema', 'The existing ledger is incomplete.', 409);
+        }
+        if (this.db.prepare("SELECT value FROM store_meta WHERE key='schema_version'").get()?.value !== '2')
+          throw new DomainError('unsupported_ledger_schema', 'Only the established v2 ledger is supported.', 409);
+        const sequence = this.currentSequence();
+        for (const row of this.db.prepare('SELECT body FROM records').all()) {
+          const value = JSON.parse(row.body);
+          for (const field of ['createdSequence', 'updatedSequence']) {
+            if (!Number.isSafeInteger(value[field]) || value[field] < 1 || value[field] > sequence)
+              throw new DomainError('invalid_sequence', 'Existing records exceed the established ledger order.', 409);
+          }
+          if (value.createdSequence > value.updatedSequence)
+            throw new DomainError('invalid_sequence', 'Existing record order is inconsistent.', 409);
+        }
+      }
+      if (this.legacyRecords) {
+        const version = this.db.prepare('SELECT sqlite_version() AS version').get().version.split('.').map(Number);
+        if (version[0] < 3 || version[0] === 3 && (version[1] < 51 || version[1] === 51 && version[2] < 3))
+          throw new DomainError('unsupported_sqlite', 'Ledger accounting requires SQLite >= 3.51.3.', 500);
+      }
+      this.db.exec(`
+        PRAGMA busy_timeout=30000;
+        PRAGMA journal_mode=WAL;
+        PRAGMA synchronous=FULL;
+        CREATE TABLE IF NOT EXISTS records (
+          kind TEXT NOT NULL, id TEXT NOT NULL,
+          revision INTEGER NOT NULL CHECK(revision > 0),
+          created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+          body TEXT NOT NULL CHECK(json_valid(body)), PRIMARY KEY(kind,id)
+        );
+        CREATE INDEX IF NOT EXISTS records_by_kind_time ON records(kind,created_at,id);
+        CREATE TABLE IF NOT EXISTS ${this.metaTable} (key TEXT PRIMARY KEY,value TEXT NOT NULL);
+        INSERT OR IGNORE INTO ${this.metaTable} VALUES ('schema_version','${this.legacyRecords ? '2' : '1'}');
+        INSERT OR IGNORE INTO ${this.metaTable} VALUES ('mutation_sequence','0');
+      `);
+      if (this.db.prepare(`SELECT value FROM ${this.metaTable} WHERE key='schema_version'`).get().value !== (this.legacyRecords ? '2' : '1'))
+        throw new DomainError('unsupported_store_schema', 'Unsupported business store schema.', 500);
+      this.currentSequence();
+      if (this.filename !== ':memory:') chmodSync(this.filename, 0o600);
+    } catch (error) {
+      this.db.close(); this.closed = true; throw error;
+    }
+  }
+
+  assertWebBudgetIdentity() {
+    this.assertOpen();
+    const expected = this.webBudgetIdentity;
+    if (this.db.prepare('PRAGMA main.application_id').get().application_id !== WEB_BUDGET_APPLICATION_ID)
+      throw new DomainError('web_budget_identity_conflict', 'The web ledger format does not match.', 409);
+    const marker = this.db.prepare("SELECT value FROM store_meta WHERE key='web_budget_mode'").get()?.value;
+    if (!expected || marker !== canonicalJson({ mode: WEB_BUDGET_MODE, authorization: expected }))
+      throw new DomainError('web_budget_identity_conflict', 'The declared web ledger identity does not match.', 409);
+    const authority = this.get('budget_authorizations', expected.id);
+    if (!authority || canonicalJson(authority.specification) !== canonicalJson(expected.specification))
+      throw new DomainError('web_authorization_conflict', 'The explicit web authorization does not match.', 409);
+  }
+
+  assertWebBudgetSchema() {
+    const schema = this.db.prepare("SELECT name,sql FROM sqlite_schema WHERE type IN ('table','view','trigger') ORDER BY name").all();
+    if (schema.length !== Object.keys(WEB_TABLES).length ||
+        schema.some(row => !WEB_TABLES[row.name] || normalizedSql(row.sql) !== normalizedSql(WEB_TABLES[row.name])) ||
+        this.db.prepare("SELECT value FROM store_meta WHERE key='schema_version'").get()?.value !== '2')
+      throw new DomainError('unsupported_ledger_schema', 'Only the explicit web-only ledger schema is supported.', 409);
+    this.assertWebBudgetIdentity();
+    const sequence = this.currentSequence();
+    for (const row of this.db.prepare('SELECT kind,id,revision,body FROM records').all()) {
+      const value = JSON.parse(row.body);
+      if (row.kind !== 'budget_authorizations' || row.id !== this.webBudgetIdentity.id ||
+          value.id !== row.id || value.revision !== row.revision)
+        throw new DomainError('unsupported_ledger_schema', 'Unexpected web authorization records.', 409);
+      if (['createdSequence', 'updatedSequence'].some(field =>
+        !Number.isSafeInteger(value[field]) || value[field] < 1 || value[field] > sequence) ||
+        value.createdSequence > value.updatedSequence)
+        throw new DomainError('invalid_sequence', 'Existing authorization order is inconsistent.', 409);
+    }
+  }
+
+  assertOpen() {
+    if (this.closed) throw new DomainError('store_closed', 'The store is closed.', 503);
+  }
+
+  currentSequence() {
+    this.assertOpen();
+    const raw = this.db.prepare(`SELECT value FROM ${this.metaTable} WHERE key='mutation_sequence'`).get()?.value;
+    const value = Number(raw);
+    if (raw === undefined || !Number.isSafeInteger(value) || value < 0)
+      throw new DomainError('invalid_sequence', 'The mutation sequence is invalid.', 500);
+    return value;
+  }
+
+  transaction(fn) {
+    this.assertOpen();
+    if (typeof fn !== 'function' || fn.constructor?.name === 'AsyncFunction')
+      throw new DomainError('async_transaction', 'Transactions require a synchronous callback.', 400);
+    const nested = this.depth > 0, savepoint = `business_sp_${++this.savepointSequence}`;
+    this.db.exec(nested ? `SAVEPOINT ${savepoint}` : 'BEGIN IMMEDIATE');
+    this.depth++;
+    try {
+      const result = fn();
+      if (result && typeof result.then === 'function') {
+        Promise.resolve(result).catch(() => {});
+        throw new DomainError('async_transaction', 'Transactions cannot return a Promise.', 400);
+      }
+      this.db.exec(nested ? `RELEASE SAVEPOINT ${savepoint}` : 'COMMIT');
+      return result;
+    } catch (error) {
+      try { this.db.exec(nested ? `ROLLBACK TO SAVEPOINT ${savepoint}; RELEASE SAVEPOINT ${savepoint}` : 'ROLLBACK'); }
+      catch (rollbackError) { error.rollbackError = rollbackError.message; }
+      throw error;
+    } finally { this.depth--; }
+  }
+
+  get(kind, id) {
+    this.assertOpen(); identity(kind, 'Record kind'); identity(id, 'Record id');
+    const row = this.db.prepare('SELECT body FROM records WHERE kind=? AND id=?').get(kind, id);
+    return row ? JSON.parse(row.body) : null;
+  }
+
+  list(kind, { limit = 1000, offset = 0, order = 'asc', where = {} } = {}) {
+    this.assertOpen(); identity(kind, 'Record kind');
+    if (!Number.isSafeInteger(limit) || limit < 0 || limit > 100000 ||
+        !Number.isSafeInteger(offset) || offset < 0 || !['asc', 'desc'].includes(order))
+      throw new DomainError('invalid_pagination', 'Invalid offset, limit or ordering.', 400);
+    const filter = filters(where), direction = order === 'asc' ? 'ASC' : 'DESC';
+    return this.db.prepare(`SELECT body FROM records WHERE kind=?${filter.sql}
+      ORDER BY rowid ${direction} LIMIT ? OFFSET ?`)
+      .all(kind, ...filter.parameters, limit, offset).map(row => JSON.parse(row.body));
+  }
+
+  listAll(kind, { where = {}, maxRecords = 100000 } = {}) {
+    identity(kind, 'Record kind');
+    if (!Number.isSafeInteger(maxRecords) || maxRecords < 1 || maxRecords > 100000)
+      throw new DomainError('invalid_limit', 'Full scans allow 1 to 100000 records.', 400);
+    return this.transaction(() => {
+      const filter = filters(where);
+      const count = this.db.prepare(`SELECT COUNT(*) AS total FROM records WHERE kind=?${filter.sql}`)
+        .get(kind, ...filter.parameters).total;
+      if (count > maxRecords)
+        throw new DomainError('record_scan_capacity', 'No partial result was returned.', 409, { kind, count, maxRecords });
+      return this.list(kind, { where, limit: count });
+    });
+  }
+
+  save(kind, record, { expectedRevision = null } = {}) {
+    this.assertOpen(); identity(kind, 'Record kind');
+    const copy = jsonClone(record);
+    if (!copy || typeof copy !== 'object' || Array.isArray(copy))
+      throw new DomainError('invalid_record', 'A record must be a plain object.', 400);
+    identity(copy.id, 'Record id');
+    if (expectedRevision !== null && (!Number.isSafeInteger(expectedRevision) || expectedRevision < 1))
+      throw new DomainError('invalid_revision', 'An explicit positive revision is required.', 400);
+    return this.transaction(() => {
+      const existing = this.get(kind, copy.id);
+      if (existing && IMMUTABLE.has(kind))
+        throw new DomainError('immutable_record', 'Original sources and delivery references cannot be rewritten.');
+      if ((expectedRevision === null && existing) ||
+          (expectedRevision !== null && existing?.revision !== expectedRevision))
+        throw new DomainError('revision_conflict', 'Record changed or creation identity already exists.');
+      const now = new Date().toISOString(), sequence = this.currentSequence() + 1;
+      if (!Number.isSafeInteger(sequence)) throw new DomainError('sequence_exhausted', 'Mutation sequence exhausted.', 500);
+      this.db.prepare(`UPDATE ${this.metaTable} SET value=? WHERE key='mutation_sequence'`).run(String(sequence));
+      const saved = { ...copy, revision: (existing?.revision ?? 0) + 1,
+        createdAt: existing?.createdAt ?? now, updatedAt: now,
+        createdSequence: existing?.createdSequence ?? sequence, updatedSequence: sequence,
+        ...(this.legacyRecords ? { sequenceEstablishedBy: existing?.sequenceEstablishedBy || 'native' } : {}) };
+      if (existing) {
+        const result = this.db.prepare('UPDATE records SET revision=?,updated_at=?,body=? WHERE kind=? AND id=? AND revision=?')
+          .run(saved.revision, now, JSON.stringify(saved), kind, saved.id, expectedRevision);
+        if (result.changes !== 1) throw new DomainError('revision_conflict', 'Record changed before save.');
+      } else this.db.prepare('INSERT INTO records VALUES (?,?,?,?,?,?)')
+        .run(kind, saved.id, saved.revision, saved.createdAt, saved.updatedAt, JSON.stringify(saved));
+      return jsonClone(saved);
+    });
+  }
+
+  close() {
+    if (!this.closed) { this.db.close(); this.closed = true; }
+  }
+}

package/src/tree/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/tree/attribution.mjs

@@ -0,0 +1,120 @@
+import { CONTRACT, canonicalJson, digest, fail } from './contracts.mjs';
+import { TreeService } from './tree.mjs';
+
+export class AttributionService {
+  constructor({ repository, sources, contextBuilder, jobs, modelOwner, modelConfig, cancelJob, timers = { setTimeout, clearTimeout } }) {
+    Object.assign(this, { repo: repository, sources, builder: contextBuilder, jobs, owner: modelOwner, modelConfig, cancelJob, timers }); this.pending = new Map();
+  }
+  existing(sessionId, nativeTurn) { return this.repo.get('tree_turns', digest(['turn', sessionId, nativeTurn])); }
+  selection(sessionId) { return this.repo.meta().attributionSelections?.[sessionId] ?? { nodeId: null, revision: 0 }; }
+  candidateNodes(at = this.repo.now(), branchId = null) {
+    const service = new TreeService({ repository: this.repo, context: () => ({ actor: { kind: 'program', id: 'tree-attribution' } }) });
+    const now = Date.parse(at);
+    const rows = this.repo.list('tree_nodes', n => !n.deleted).filter(node => {
+      if (branchId && !this.repo.ancestors(node.id).some(n => n.id === branchId)) return false;
+      if (node.id === branchId || node.pinned === true || ['active', 'paused'].includes(node.status)) return true;
+      const owner = node.statusOrigin === 'cascade' && node.cascadeFromId ? this.repo.get('tree_nodes', node.cascadeFromId) : node;
+      return now - Date.parse(owner.statusChangedAt ?? owner.updatedAt) <= service.parameter('retentionDays', owner.id) * 86400000;
+    }).sort((a, b) => Number(b.pinned === true) - Number(a.pinned === true) || a.id.localeCompare(b.id));
+    return rows;
+  }
+  capacity(sessionId) {
+    const selection = this.selection(sessionId), selected = selection.nodeId && this.repo.get('tree_nodes', selection.nodeId);
+    const selectionMissing = Boolean(selection.nodeId && (!selected || selected.deleted));
+    const totalCount = this.candidateNodes().length, count = selection.nodeId ? selectionMissing ? 0 : this.candidateNodes(this.repo.now(), selection.nodeId).length : totalCount;
+    return { limit: 2000, totalCount, count, selection, selectionMissing, blocked: selectionMissing || count > 2000,
+      path: selected && !selected.deleted ? this.repo.ancestors(selected.id).map(n => ({ id: n.id, name: n.name })) : [],
+      pending: Object.values(this.repo.meta().attributionPending ?? {}).filter(p => p.sessionId === sessionId && p.state !== 'consumed').map(p => ({ id: p.id, state: p.state, revision: p.revision, text: p.preview, nativeTurn: p.nativeTurn })) };
+  }
+  candidates(at = this.repo.now(), sessionId = null) {
+    const selection = this.selection(sessionId);
+    if (selection.nodeId && (!this.repo.get('tree_nodes', selection.nodeId) || this.repo.get('tree_nodes', selection.nodeId).deleted)) fail('CANDIDATE_CAPACITY', '选定的目标已不存在，请重新选择一支目标后继续。');
+    const rows = this.candidateNodes(at, selection.nodeId);
+    if (rows.length > 2000) fail('CANDIDATE_CAPACITY', `当前范围有${rows.length}个候选，超过2000个；请选择一支更小的目标后继续，尚未调用模型。`);
+    return rows.map(node => ({ id: node.id, name: node.name, status: node.status, statusOrigin: node.statusOrigin, path: this.repo.ancestors(node.id).map(n => ({ id: n.id, name: n.name })), oneLine: this.builder.summary(node)?.oneLine ?? '', revision: node.revision }));
+  }
+  freeze(sessionId, nativeTurn, messages) {
+    const userSources = this.sources.claimed(sessionId, messages); if (!userSources.length) fail('PROGRAM_NOT_USER', 'Only a new actual human batch needs attribution');
+    const prior = this.repo.list('tree_turns', t => t.sessionId === sessionId && t.nativeTurn < nativeTurn).sort((a, b) => b.nativeTurn - a.nativeTurn)[0];
+    const selection = this.selection(sessionId), candidates = this.candidates(this.repo.now(), sessionId), candidateIds = new Set(candidates.map(n => n.id));
+    const previousNodeIds = (prior?.nodeIds ?? [selection.nodeId ?? this.repo.rootId()]).filter(id => candidateIds.has(id)), scopeNodes = previousNodeIds.length ? previousNodeIds : [selection.nodeId ?? this.repo.rootId()];
+    const context = this.builder.build(scopeNodes, 'attribution');
+    // The explicit branch is the complete discovery range for this judgement.
+    // Ancestor knowledge is inherited, but the global discovery list is omitted.
+    if (selection.nodeId) context.segments = context.segments.filter(s => s.key !== 'global-overview');
+    const priorAnswer = prior ? this.sources.turn(sessionId, prior.nativeTurn).sources.filter(s => s.origin === 'model' && this.sources.resolve(s.ref)).at(-1) : null;
+    const sources = [...userSources, ...(priorAnswer ? [priorAnswer] : [])], knownItems = this.builder.activeItems(context.ancestorPaths.flat(), 'attribution').map(({ item }) => ({ id: item.id, version: item.activeVersion, nodeId: item.nodeId, kind: item.kind, userProtected: item.userProtected }));
+    // Candidate node revisions also change when an unrelated turn is linked.
+    // Recheck the actual candidate fields atomically at commit instead of
+    // rejecting a correct judgment on every unrelated bookkeeping update.
+    const revisions = {};
+    for (const i of knownItems) revisions[`tree_items:${i.id}`] = this.repo.get('tree_items', i.id).revision;
+    return { input: { inputVersion: CONTRACT, role: 'attribution', scope: { nodeIds: scopeNodes, ancestorPaths: context.ancestorPaths, treeRevision: context.treeRevision }, sources, knownItems,
+      allowedIds: { nodeIds: candidates.map(n => n.id), fileIds: [], subjectIds: [] }, changeReceipts: [], candidates,
+      context: context.segments, currentTurn: { sessionId, nativeTurn, userSourceIds: userSources.map(s => s.id), selectionRevision: selection.revision, selectedBranchId: selection.nodeId } }, revisions, scopeNodes };
+  }
+  applyResult(result, { job, requestId }) {
+    const input = job.input, { sessionId, nativeTurn, userSourceIds } = input.currentTurn;
+    const old = this.existing(sessionId, nativeTurn);
+    if (old) fail('JOB_STALE', 'This turn was already assigned, corrected or routed by a deadline fallback');
+    if (this.selection(sessionId).revision !== (input.currentTurn.selectionRevision ?? 0)) fail('JOB_STALE', '用户已改变本聊天的目标范围，本次旧判断不再采用');
+    if (input.currentTurn.selectedBranchId && input.currentTurn.selectedBranchId !== this.repo.rootId() && result.actions.some(a => a.action === 'create')) fail('ATTRIBUTION_RANGE', '选定分支时只能在候选父目标下创建子目标，不能在范围外新建');
+    return this.repo.transaction(() => {
+      if (this.existing(sessionId, nativeTurn) || this.selection(sessionId).revision !== (input.currentTurn.selectionRevision ?? 0)) fail('JOB_STALE', 'Turn or selected branch changed while the model ran');
+      const current = this.candidates(this.repo.now(), sessionId);
+      const meaning = candidates => candidates.map(({ revision: _revision, ...candidate }) => candidate);
+      if (canonicalJson(meaning(current)) !== canonicalJson(meaning(input.candidates))) fail('JOB_STALE', 'Attribution candidate information changed while the model ran');
+      const expected = { ...job.inputRevisionSet, ...Object.fromEntries(current.map(n => [`tree_nodes:${n.id}`, n.revision])) };
+      const resolve = id => { const source = input.sources.find(s => s.id === id); if (!source || !this.sources.resolve(source.ref)) fail('JOB_STALE', 'Attribution source changed'); return source.ref; };
+      const refs = userSourceIds.map(resolve), tree = new TreeService({ repository: this.repo, resolveSource: ref => this.sources.resolve(ref), context: () => ({ actor: { kind: 'model', id: job.id, role: 'attribution' }, nodeIds: input.scope.nodeIds, candidateNodeIds: input.allowedIds.nodeIds }) });
+      return tree.applyAttribution({ requestId, expected, input: { sessionId, nativeTurn, userSourceRefs: refs, sourceRefs: refs,
+        actions: result.actions, statusChanges: result.statusChanges.map(s => ({ nodeId: s.nodeId, status: s.status, sourceRefs: [resolve(s.sourceId)] })), attributionRunId: job.id } });
+    });
+  }
+  fallback(sessionId, nativeTurn, messages, reason, runId = null) {
+    const old = this.existing(sessionId, nativeTurn); if (old) return old;
+    const refs = this.sources.claimed(sessionId, messages).map(s => s.ref); if (!refs.length) fail('PROGRAM_NOT_USER', 'No human original to route');
+    const tree = new TreeService({ repository: this.repo, resolveSource: ref => this.sources.resolve(ref), context: () => ({ actor: { kind: 'program', id: 'tree-attribution' } }) });
+    const branchId = this.selection(sessionId).nodeId;
+    tree.applyAttribution({ requestId: digest(['attribution-fallback', sessionId, nativeTurn]), expected: {}, input: { sessionId, nativeTurn, userSourceRefs: refs, sourceRefs: refs, actions: branchId ? [{ action: 'continue', nodeId: branchId }] : [], statusChanges: [], failure: reason.slice(0, 2000), attributionRunId: runId } });
+    return this.existing(sessionId, nativeTurn);
+  }
+  attribute(request) {
+    const key = digest([request.sessionId, request.nativeTurn]); if (this.pending.has(key)) return this.pending.get(key);
+    const promise = this.#attribute(request); this.pending.set(key, promise); void promise.finally(() => this.pending.delete(key)).catch(() => {}); return promise;
+  }
+  cancelPending(jobId, reason) {
+    const current = this.jobs.get(jobId);
+    if (['queued', 'prepared', 'submitted', 'validated'].includes(current.status)) this.jobs.transition(jobId, 'cancelled', { cancellationReason: reason });
+    if (['committed', 'cancelled', 'failed', 'stale', 'unknown'].includes(current.status)) return;
+    const result = this.cancelJob(jobId);
+    if (result?.then) { void Promise.resolve(result).catch(() => {}); fail('CANCELLATION_REQUIRED', 'Cancellation callback must be synchronous'); }
+  }
+  async #attribute({ sessionId, nativeTurn, messages, signal, agent, modelSelection }) {
+    signal?.throwIfAborted(); const old = this.existing(sessionId, nativeTurn); if (old) return old;
+    if (!messages.some(m => m.source?.kind === 'user')) return null;
+    if (typeof this.cancelJob !== 'function') fail('CANCELLATION_REQUIRED', 'Attribution needs an owned synchronous cancellation callback');
+    let job, timer, abort;
+    try {
+      const frozen = this.freeze(sessionId, nativeTurn, messages);
+      job = this.jobs.enqueue({ role: 'attribution', key: `${sessionId}:${nativeTurn}`, nodeIds: frozen.scopeNodes, input: frozen.input, revisionSet: frozen.revisions,
+        config: this.modelConfig(agent, modelSelection), trigger: { kind: 'human_input', producerRole: 'user', origin: 'user', nativeSessionId: sessionId, nativeTurn, ordinal: this.repo.meta().lastEventOrdinal } });
+      const cancelled = new Promise((_, reject) => {
+        const stop = code => {
+          try { this.cancelPending(job.id, code); } catch (error) { reject(error); return; }
+          reject(Object.assign(new Error(code), { code }));
+        };
+        timer = this.timers.setTimeout(() => stop('ATTRIBUTION_DEADLINE'), 12000); abort = () => stop('ATTRIBUTION_ABORTED'); signal?.addEventListener('abort', abort, { once: true });
+        if (signal?.aborted) abort();
+      });
+      await Promise.race([this.owner.run(job.id), cancelled]); signal?.throwIfAborted();
+      const turn = this.existing(sessionId, nativeTurn); if (turn) return turn;
+      const result = this.jobs.get(job.id); this.cancelPending(job.id, 'ATTRIBUTION_UNAVAILABLE');
+      return this.fallback(sessionId, nativeTurn, messages, `Attribution ${result.status}: ${canonicalJson(result.error ?? {})}`, job.id);
+    } catch (error) {
+      if (job) { try { this.cancelPending(job.id, error.code ?? 'ATTRIBUTION_UNAVAILABLE'); } catch (cancelError) { error = cancelError; } }
+      if (signal?.aborted || ['ATTRIBUTION_ABORTED', 'CANDIDATE_CAPACITY'].includes(error.code)) throw error;
+      return this.fallback(sessionId, nativeTurn, messages, `${error.code ?? 'ATTRIBUTION_UNAVAILABLE'}: ${error.message}`, job?.id ?? null);
+    } finally { if (timer !== undefined) this.timers.clearTimeout(timer); if (abort) signal?.removeEventListener('abort', abort); }
+  }
+}

package/src/tree/clusters.mjs

@@ -0,0 +1,61 @@
+import { canonicalJson, digest, fail, oneOf } from './contracts.mjs';
+
+const actor = { kind: 'program', id: 'tree-clusters' };
+export class ClusterService {
+  constructor({ repository, signals }) { this.repo = repository; this.signals = signals; }
+  group(category, polarity) {
+    return this.signals.episodes().filter(e => e.state !== 'control' && e.signals.some(s => s.category === category && s.polarity === polarity)).sort((a, b) => a.ordinal - b.ordinal || a.id.localeCompare(b.id));
+  }
+  signature(episodes) { return digest(episodes.map(e => [e.id, e.nodeIds, e.beforeRefs, e.reactionRefs, e.resolutionRefs, e.signals.map(s => s.id).sort()])); }
+  scope(episodes) {
+    const paths = [...new Set(episodes.flatMap(e => e.nodeIds))].map(id => this.repo.ancestors(id).map(n => n.id));
+    return paths[0]?.filter(id => paths.every(p => p.includes(id))).at(-1) ?? this.repo.rootId();
+  }
+  candidate(category, polarity) {
+    oneOf(polarity, ['negative', 'strong'], 'cluster polarity');
+    const history = this.repo.list('tree_clusters', c => c.category === category && c.polarity === polarity).sort((a, b) => a.epoch - b.epoch);
+    const previous = history.at(-1), all = this.group(category, polarity);
+    if (previous?.status === 'candidate') {
+      const selected = all.filter(e => previous.episodeIds.includes(e.id));
+      if (this.signature(selected) === previous.evidenceHash) return previous;
+      // Corrected evidence cannot retain an old pending diagnosis.
+      this.repo.command('invalidateClusterCandidate', { requestId: digest(['cluster-stale', previous.id, previous.revision]), expected: { ['tree_clusters:' + previous.id]: previous.revision }, input: { clusterId: previous.id } }, actor, () => {
+        this.repo.save('tree_clusters', { ...previous, status: 'stale', needsRecheck: true }, previous.revision); return { clusterId: previous.id };
+      });
+    }
+    const reviewed = history.filter(c => ['common', 'reviewed_none'].includes(c.status) && !c.needsRecheck).at(-1);
+    const watermark = reviewed?.reviewWatermark ?? 0, episodes = all.filter(e => e.ordinal > watermark);
+    if (episodes.length < 3) return null;
+    const epoch = (previous?.epoch ?? 0) + 1, evidenceHash = this.signature(episodes), id = digest(['cluster', category, polarity, epoch, evidenceHash]);
+    const controls = polarity === 'strong' ? this.signals.episodes().filter(e => e.state === 'control' && e.category === category && e.nodeIds.some(id => episodes.some(s => s.nodeIds.includes(id)))) : [];
+    return this.repo.command('createClusterCandidate', { requestId: id, expected: {}, input: { category, polarity, epoch, evidenceHash } }, actor, () => {
+      this.repo.save('tree_clusters', { id, category, polarity, epoch, episodeIds: episodes.map(e => e.id), status: 'candidate', methodIds: [], reviewWatermark: watermark,
+        triggerWatermark: Math.max(...episodes.map(e => e.ordinal)), recurrenceCount: reviewed?.recurrenceCount ?? 0, previousClusterId: reviewed?.id ?? null,
+        previousMethodIds: reviewed?.methodIds ?? [], evidenceHash, nodeId: this.scope(episodes), controlIds: controls.map(e => e.id), needsRecheck: false }); return { clusterId: id };
+    }).result.clusterId && this.repo.get('tree_clusters', id);
+  }
+  assertCurrent(cluster) {
+    const current = this.repo.get('tree_clusters', cluster.id), episodes = this.group(cluster.category, cluster.polarity).filter(e => cluster.episodeIds.includes(e.id));
+    if (current?.revision !== cluster.revision || current.status !== 'candidate' || this.signature(episodes) !== cluster.evidenceHash) fail('JOB_STALE', 'Cluster evidence or category correction changed');
+    return episodes;
+  }
+  freeze(cluster) {
+    const episodes = this.assertCurrent(cluster), controls = this.signals.episodes().filter(e => cluster.controlIds.includes(e.id));
+    return { ...cluster, episodes: episodes.map(e => this.signals.material(e)), controls: controls.map(e => this.signals.material(e)) };
+  }
+  review({ clusterId, clusterVersion, verdict, commonality, evidence }, { job, requestId, methodIds = [], recurrence = null }) {
+    const cluster = this.repo.get('tree_clusters', clusterId);
+    if (!cluster || cluster.revision !== clusterVersion) fail('JOB_STALE', 'Cluster version changed');
+    this.assertCurrent(cluster); oneOf(verdict, ['common', 'none'], 'cluster verdict');
+    if (verdict === 'none' && (methodIds.length || recurrence) || verdict === 'common' && !commonality.trim()) fail('CLUSTER_DIAGNOSIS', 'No common cause cannot create a method or recurrence claim');
+    const evidenceSources = evidence.map(id => job.input.sources.find(s => s.id === id));
+    if (evidenceSources.some(s => !s)) fail('OUTPUT_REFERENCE', 'Unknown cluster evidence');
+    const episodeRefs = this.assertCurrent(cluster).map(e => e.reactionRefs);
+    if (episodeRefs.filter(refs => refs.some(ref => evidenceSources.some(s => digest(s.ref) === digest(ref)))).length < 3) fail('CLUSTER_EVIDENCE', 'Diagnosis needs three distinct original episodes');
+    if (recurrence && (!cluster.previousMethodIds.includes(recurrence.methodId) || !job.input.knownItems.some(i => i.id === recurrence.methodId && i.version === recurrence.methodVersion) || !recurrence.expectation)) fail('CLUSTER_RECURRENCE', 'Recurrence requires an explicit current method and expectation binding');
+    return this.repo.command('reviewCluster', { requestId, expected: { ['tree_clusters:' + cluster.id]: clusterVersion }, input: { clusterId, verdict, commonality, evidence, methodIds, recurrence } }, { kind: 'model', id: job.id, role: 'verification' }, () => {
+      this.repo.save('tree_clusters', { ...cluster, status: verdict === 'none' ? 'reviewed_none' : 'common', commonality, evidenceRefs: evidenceSources.map(s => s.ref), methodIds,
+        reviewWatermark: cluster.triggerWatermark, recurrence, recurrenceCount: cluster.recurrenceCount + (recurrence ? 1 : 0), needsRecheck: false }, cluster.revision); return { clusterId, verdict };
+    }).result;
+  }
+}