@volter/supercode-interchange 0.1.22 → 0.1.24

package/reduction-diff.mjs

@@ -0,0 +1,165 @@
+// Persisted FileReadDiffed views use diffy 0.5.0's default line algorithm:
+// bidirectional Myers, deletion-then-insertion compaction and three context
+// lines. Keep its choices here rather than changing old logs' token figures.
+// Derived from diffy (MIT/Apache-2.0); see LICENSE-diffy-MIT.
+const lines = value => value.match(/[^\n]*\n|[^\n]+$/gu) ?? [];
+const range = (type, old, fresh, length) => ({ type, old, fresh, length });
+function common(a, b, aStart, bStart, aLength, bLength, suffix = false) {
+  let count = 0;
+  while (count < Math.min(aLength, bLength)
+    && a[aStart + (suffix ? aLength - count - 1 : count)] === b[bStart + (suffix ? bLength - count - 1 : count)]) count++;
+  return count;
+}
+
+function diff(old, fresh) {
+  const forward = new Map(), backward = new Map(), result = [], get = (map, key) => map.get(key) ?? 0;
+  function middle(a, b, n, m) {
+    const delta = n - m, odd = Math.abs(delta) % 2 === 1;
+    forward.set(1, 0); backward.set(1, 0);
+    for (let d = 0; d < Math.ceil((n + m) / 2) + 1; d++) {
+      for (let k = d; k >= -d; k -= 2) {
+        let x = k === -d || k !== d && get(forward, k - 1) < get(forward, k + 1)
+          ? get(forward, k + 1) : get(forward, k - 1) + 1;
+        let y = x - k; const xStart = x, yStart = y;
+        if (x <= n && y >= 0 && y <= m) {
+          const count = common(old, fresh, a + x, b + y, n - x, m - y); x += count; y += count;
+        }
+        forward.set(k, x);
+        if (odd && Math.abs(k - delta) <= d - 1 && x + get(backward, -(k - delta)) >= n) return [xStart, yStart];
+      }
+      for (let k = d; k >= -d; k -= 2) {
+        let x = k === -d || k !== d && get(backward, k - 1) < get(backward, k + 1)
+          ? get(backward, k + 1) : get(backward, k - 1) + 1;
+        let y = x - k; const xStart = x, yStart = y;
+        if (x < n && y >= 0 && y < m) {
+          const count = common(old, fresh, a, b, n - x, m - y, true); x += count; y += count;
+        }
+        backward.set(k, x);
+        if (!odd && Math.abs(k - delta) <= d && x + get(forward, -(k - delta)) >= n) return [n - x, m - y];
+        // The other end of the backward snake is not needed: conquer splits
+        // at its beginning and finds its equality in the recursive calls.
+        void xStart; void yStart;
+      }
+    }
+    throw new Error('unable to find a middle diff snake');
+  }
+  // Explicit continuation stack preserves conquer's prefix/left/right/suffix
+  // order without making a large transcript consume the JavaScript call stack.
+  const stack = [{ a: 0, b: 0, n: old.length, m: fresh.length }];
+  while (stack.length) {
+    const item = stack.pop();
+    if (item.type) { result.push(item); continue; }
+    let { a, b, n, m } = item;
+    const prefix = common(old, fresh, a, b, n, m);
+    if (prefix) result.push(range('equal', a, b, prefix));
+    a += prefix; b += prefix; n -= prefix; m -= prefix;
+    const suffix = common(old, fresh, a, b, n, m, true);
+    if (suffix) stack.push(range('equal', a + n - suffix, b + m - suffix, suffix));
+    n -= suffix; m -= suffix;
+    if (!n && !m) continue;
+    if (!n) result.push(range('insert', a, b, m));
+    else if (!m) result.push(range('delete', a, b, n));
+    else {
+      const [x, y] = middle(a, b, n, m);
+      stack.push({ a: a + x, b: b + y, n: n - x, m: m - y });
+      stack.push({ a, b, n: x, m: y });
+    }
+  }
+  return result;
+}
+
+function compact(ranges, old, fresh) {
+  const growUp = (r, count) => { r.old -= count; r.fresh -= count; r.length += count; };
+  const growDown = (r, count) => { r.length += count; };
+  const shift = (r, count) => { if (r.type !== 'insert') r.old += count; if (r.type !== 'delete') r.fresh += count; };
+  function up(pointer) {
+    while (pointer > 0) {
+      const current = ranges[pointer], previous = ranges[pointer - 1];
+      if (previous.type === 'equal') {
+        const insert = current.type === 'insert';
+        const source = insert ? fresh : old, start = insert ? current.fresh : current.old;
+        const other = insert ? old : fresh, otherStart = insert ? previous.old : previous.fresh;
+        const count = common(source, other, start, otherStart, current.length, previous.length, true);
+        if (count) {
+          if (ranges[pointer + 1]?.type === 'equal') growUp(ranges[pointer + 1], count);
+          else ranges.splice(pointer + 1, 0, range('equal',
+            insert ? previous.old + previous.length - count : current.old + current.length - count,
+            insert ? current.fresh + current.length - count : previous.fresh + previous.length - count, count));
+          shift(current, -count); previous.length -= count;
+          if (!previous.length) { ranges.splice(pointer - 1, 1); pointer--; }
+        } else if (!previous.length) { ranges.splice(pointer - 1, 1); pointer--; }
+        else break;
+      } else if (previous.type !== current.type) {
+        ranges[pointer - 1] = current; ranges[pointer] = previous; pointer--;
+      } else { growDown(previous, current.length); ranges.splice(pointer, 1); pointer--; }
+    }
+    return pointer;
+  }
+  function down(pointer) {
+    while (pointer + 1 < ranges.length) {
+      const current = ranges[pointer], next = ranges[pointer + 1];
+      if (next.type === 'equal') {
+        const insert = current.type === 'insert';
+        const source = insert ? fresh : old, start = insert ? current.fresh : current.old;
+        const other = insert ? old : fresh, otherStart = insert ? next.old : next.fresh;
+        const count = common(source, other, start, otherStart, current.length, next.length);
+        if (count) {
+          if (ranges[pointer - 1]?.type === 'equal') growDown(ranges[pointer - 1], count);
+          else {
+            ranges.splice(pointer, 0, range('equal', insert ? next.old : current.old, insert ? current.fresh : next.fresh, count)); pointer++;
+          }
+          shift(current, count); shift(next, count); next.length -= count;
+          if (!next.length) ranges.splice(pointer + 1, 1);
+        } else if (!next.length) ranges.splice(pointer + 1, 1);
+        else break;
+      } else if (next.type !== current.type) {
+        ranges[pointer] = next; ranges[pointer + 1] = current; pointer++;
+      } else { growDown(current, next.length); ranges.splice(pointer + 1, 1); }
+    }
+    return pointer;
+  }
+  for (const type of ['delete', 'insert']) for (let pointer = 0; pointer < ranges.length; pointer++) {
+    if (ranges[pointer].type === type) pointer = down(up(pointer));
+  }
+  return ranges;
+}
+
+/** Byte spelling matches the native default patch, including blank context
+ * suppression, one-line ranges and the missing-newline marker. */
+export function reductionUnifiedDiff(original, modified) {
+  const old = lines(original), fresh = lines(modified), scripts = [];
+  let a = 0, b = 0, script;
+  for (const item of compact(diff(old, fresh), old, fresh)) {
+    if (item.type === 'equal') {
+      a += item.length; b += item.length;
+      if (script) { scripts.push(script); script = null; }
+    } else {
+      script ??= { oldStart: a, oldEnd: a, newStart: b, newEnd: b };
+      if (item.type === 'delete') { a += item.length; script.oldEnd += item.length; }
+      else { b += item.length; script.newEnd += item.length; }
+    }
+  }
+  if (script) scripts.push(script);
+  let output = '--- original\n+++ modified\n';
+  const end = s => { const count = Math.min(3, Math.max(0, old.length - s.oldEnd), Math.max(0, fresh.length - s.newEnd)); return [s.oldEnd + count, s.newEnd + count]; };
+  const hunkRange = (start, length) => length === 1 ? String(start + 1) : `${start + (length > 0 ? 1 : 0)},${length}`;
+  const lineText = (sign, value) => (sign === ' ' && value === '\n' ? value : sign + value)
+    + (value.endsWith('\n') ? '' : '\n\\n');
+  for (let index = 0; index < scripts.length; index++) {
+    let current = scripts[index];
+    const startA = Math.max(0, current.oldStart - 3), startB = Math.max(0, current.newStart - 3);
+    let [endA, endB] = end(current), content = '';
+    for (const value of fresh.slice(startB, current.newStart)) content += lineText(' ', value);
+    while (true) {
+      for (const value of old.slice(current.oldStart, current.oldEnd)) content += lineText('-', value);
+      for (const value of fresh.slice(current.newStart, current.newEnd)) content += lineText('+', value);
+      const next = scripts[index + 1];
+      if (!next || Math.max(0, Math.min(next.oldStart, old.length - 1) - 3) >= endA) break;
+      for (const value of fresh.slice(current.newEnd, next.newStart)) content += lineText(' ', value);
+      current = next; index++; [endA, endB] = end(current);
+    }
+    for (const value of fresh.slice(current.newEnd, endB)) content += lineText(' ', value);
+    output += `@@ -${hunkRange(startA, endA - startA)} +${hunkRange(startB, endB - startB)} @@\n${content}`;
+  }
+  return output;
+}

package/reduction-log.mjs

@@ -0,0 +1,177 @@
+// Persisted reduction records, not a compactor: this reader never creates a
+// reduction, edits a source session or consults a model/tool/filesystem.
+import { blake3 } from '@noble/hashes/blake3.js';
+import { messageWire, parsedArguments, ROLES } from './message.mjs';
+import { nativeDuplicateObjectKeys, nativeInteger, parseNativeJson, stringifyNativeJson } from './native-json.mjs';
+
+export const REDUCTION_SENTINEL = '[sc-reduced';
+export const REDUCTION_METADATA_KEY = 'sc.reduction';
+export const REDUCTION_KINDS = Object.freeze(['ToolOutputTruncated', 'FileReadElided', 'ImageRedacted',
+  'TurnsCleared', 'ToolInputElided', 'OutputNormalized', 'FileReadDiffed', 'DuplicateOutput', 'Superseded']);
+const stubKinds = new Set(['tool-output', 'file-read', 'image', 'turns-cleared', 'tool-input',
+  'output-normalized', 'file-read-diffed', 'duplicate', 'superseded']);
+const fail = text => { throw new TypeError(`invalid reduction log: ${text}`); };
+const isObject = value => value != null && typeof value === 'object' && !Array.isArray(value);
+function object(value, fields, context) {
+  if (!isObject(value)) fail(`${context} must be an object`);
+  for (const key of nativeDuplicateObjectKeys(value)) if (fields.includes(key)) fail(`${context} has duplicate field ${key}`);
+}
+function text(value, key) { if (typeof value[key] !== 'string') fail(`${key} must be a string`); }
+function optionalText(value, key) { if (value[key] != null) text(value, key); }
+function unsigned(value, key, maximum = (1n << 64n) - 1n) {
+  const number = nativeInteger(value, String(key));
+  if (number == null || number < 0n || number > maximum) fail(`${key} must be an unsigned integer`);
+  return number;
+}
+function array(value, key) { if (!Array.isArray(value[key])) fail(`${key} must be an array`); return value[key]; }
+function address(value) {
+  object(value, ['index', 'role'], 'message address'); unsigned(value, 'index');
+  if (!ROLES.includes(value.role)) fail('message address role must be system, user, assistant or tool');
+}
+function pointer(value) {
+  object(value, ['addr', 'span', 'content_hash'], 'sidecar pointer'); address(value.addr); text(value, 'content_hash');
+  if (value.span != null) {
+    if (!Array.isArray(value.span) || value.span.length !== 2) fail('pointer span must be a pair');
+    unsigned(value.span, 0); unsigned(value.span, 1);
+  }
+}
+function readEntry(value) {
+  object(value, ['path', 'addr', 'content_hash', 'mtime'], 'read-log entry');
+  text(value, 'path'); address(value.addr); text(value, 'content_hash');
+  if (value.mtime != null && nativeInteger(value, 'mtime', { signed: true }) == null) fail('mtime must be an i64');
+}
+function summary(value) {
+  if (value == null) return;
+  object(value, ['model_id', 'prompt_version', 'summary_hash'], 'span summary');
+  for (const key of ['model_id', 'prompt_version', 'summary_hash']) text(value, key);
+}
+function kind(value) {
+  if (!isObject(value) || Object.keys(value).length !== 1 || nativeDuplicateObjectKeys(value).length) fail('kind must contain exactly one variant');
+  const name = Object.keys(value)[0], data = value[name];
+  const fields = {
+    ToolOutputTruncated: ['original_bytes', 'kept_bytes'],
+    FileReadElided: ['path', 'read_log'], ImageRedacted: ['part_index'], TurnsCleared: ['first', 'last', 'summary'],
+    ToolInputElided: ['original_bytes', 'path', 'content_hash', 'call_id', 'field'],
+    OutputNormalized: ['original_bytes', 'normalized_bytes'],
+    FileReadDiffed: ['path', 'base', 'base_hash', 'new_hash', 'original_bytes', 'diff_bytes'],
+    DuplicateOutput: ['canonical', 'original_bytes'], Superseded: ['by', 'original_bytes'],
+  }[name];
+  if (fields == null) fail(`unknown kind ${name}`);
+  object(data, fields, name);
+  for (const key of fields) {
+    if (['original_bytes', 'kept_bytes', 'part_index', 'first', 'last', 'normalized_bytes', 'diff_bytes'].includes(key)) unsigned(data, key);
+    else if (['base', 'canonical', 'by'].includes(key)) address(data[key]);
+    else if (key === 'read_log') readEntry(data[key]);
+    else if (key === 'summary') summary(data[key]);
+    else if (key === 'path' && name === 'ToolInputElided') optionalText(data, key);
+    else text(data, key);
+  }
+}
+function reduction(value) {
+  object(value, ['id', 'kind', 'ptr', 'placeholder'], 'reduction');
+  text(value, 'id'); kind(value.kind); pointer(value.ptr); text(value, 'placeholder');
+}
+const passCounts = ['candidate_count', 'candidate_original_bytes', 'applied_count', 'applied_original_bytes',
+  'suppressed_by_later_pass_count', 'suppressed_by_later_pass_bytes', 'standalone_saved_bytes', 'standalone_saved_tokens',
+  'marginal_saved_bytes', 'marginal_saved_tokens', 'suppressed_bytes', 'suppressed_tokens', 'retained_bytes', 'retained_tokens'];
+const aggregateCounts = ['full_bytes', 'view_bytes', 'full_tokens', 'view_tokens', 'aggregate_saved_bytes',
+  'aggregate_saved_tokens', 'standalone_saved_bytes', 'standalone_saved_tokens', 'overlap_suppressed_bytes', 'overlap_suppressed_tokens'];
+function attribution(value) {
+  if (value == null) return;
+  object(value, [...aggregateCounts, 'passes'], 'attribution');
+  for (const key of aggregateCounts) unsigned(value, key);
+  for (const pass of array(value, 'passes')) {
+    object(pass, ['kind', 'enabled', ...passCounts], 'pass attribution'); text(pass, 'kind');
+    if (typeof pass.enabled !== 'boolean') fail('pass enabled must be a boolean');
+    for (const key of passCounts) unsigned(pass, key);
+  }
+}
+
+export const emptyReductionLog = () => ({ reductions: [], expanded: [], read_log: [], attribution: null });
+
+/** Direct typed serde reads reject duplicate known fields and float counts;
+ * optional history/attribution fields retain their backwards-compatible defaults. */
+export function readReductionLog(textValue) {
+  const log = parseNativeJson(textValue);
+  object(log, ['reductions', 'expanded', 'read_log', 'attribution'], 'log');
+  array(log, 'reductions').forEach(reduction); array(log, 'read_log').forEach(readEntry);
+  if (Object.hasOwn(log, 'expanded')) array(log, 'expanded').forEach(reduction);
+  else log.expanded = [];
+  attribution(log.attribution);
+  return log;
+}
+
+export const reductionContentHash = value => Buffer.from(blake3(typeof value === 'string' ? Buffer.from(value) : value)).toString('hex');
+export const messageWireText = message => stringifyNativeJson(messageWire(message));
+export const estimateViewTokens = messages => messages.reduce((sum, message) => sum + BigInt(Math.ceil(Buffer.byteLength(messageWireText(message)) / 4)), 0n);
+
+function verifyHash(ptr, actual) {
+  if (actual !== ptr.content_hash) throw new Error(`sidecar pointer hash mismatch: expected ${ptr.content_hash}, got ${actual}`);
+}
+const debugRole = role => role[0].toUpperCase() + role.slice(1);
+function resolveMessage(ptr, messages) {
+  const index = nativeInteger(ptr.addr, 'index');
+  if (index >= BigInt(messages.length)) throw new Error(`invert: sidecar has no message at index ${index} (reduction pointer unresolvable)`);
+  const message = messages[Number(index)];
+  if (message.role !== ptr.addr.role) throw new Error(`invert: role mismatch at sidecar index ${index}: pointer expects ${debugRole(ptr.addr.role)}, sidecar has ${debugRole(message.role)}`);
+  return message;
+}
+
+/** Validate every applied and expanded pointer before a caller can export.
+ * Auxiliary diff/dedup provenance is informational, as in the native verifier. */
+export function verifyReductionLog(log, messages) {
+  for (const record of [...log.reductions, ...log.expanded]) {
+    const name = Object.keys(record.kind)[0], data = record.kind[name], ptr = record.ptr;
+    try {
+      let original;
+      if (name === 'TurnsCleared') {
+        const first = nativeInteger(data, 'first'), last = nativeInteger(data, 'last');
+        if (first <= last && last >= BigInt(messages.length)) {
+          const missing = first >= BigInt(messages.length) ? first : BigInt(messages.length);
+          throw new Error(`invert: sidecar has no message at index ${missing} (turns-cleared range unresolvable)`);
+        }
+        const range = first > last ? [] : messages.slice(Number(first), Number(last) + 1);
+        if (range.length && range[0].role !== ptr.addr.role) throw new Error(`invert: role mismatch at sidecar index ${first}: pointer expects ${debugRole(ptr.addr.role)}, sidecar has ${debugRole(range[0].role)}`);
+        original = Buffer.concat(range.map(message => Buffer.from(messageWireText(message))));
+      } else {
+        const message = resolveMessage(ptr, messages), index = nativeInteger(ptr.addr, 'index');
+        if (name === 'ImageRedacted') {
+          const partIndex = nativeInteger(data, 'part_index'), parts = message.content_parts;
+          if (parts == null || partIndex >= BigInt(parts.length)) throw new Error(`invert: sidecar message at index ${index} has no content part ${partIndex}`);
+          original = stringifyNativeJson(parts[Number(partIndex)]);
+        } else if (name === 'ToolInputElided') {
+          const call = message.tool_calls?.find(call => call.id === data.call_id);
+          if (call == null) throw new Error(`invert: sidecar message at index ${index} has no tool_call with id ${data.call_id}`);
+          let argumentsValue;
+          try { argumentsValue = parsedArguments(call); }
+          catch (error) { throw new Error(`invert: tool_call ${data.call_id} arguments are not valid JSON: ${error.message}`); }
+          if (!isObject(argumentsValue) || typeof argumentsValue[data.field] !== 'string') throw new Error(`invert: tool_call ${data.call_id} has no string field \`${data.field}\``);
+          original = argumentsValue[data.field];
+        } else original = message.content ?? '';
+      }
+      verifyHash(ptr, reductionContentHash(original));
+    } catch (error) { throw new Error(`reduction ${record.id} unresolvable against the sidecar: ${error.message}`, { cause: error }); }
+  }
+}
+
+export function parseReductionStub(line) {
+  const match = /^\[sc-reduced ([^ ]+) (r[0-9]{4}-[0-9a-f]{4}): ([^\]\n]+)\]$/u.exec(line);
+  return match && match[0] === line && stubKinds.has(match[1]) ? { kind: match[1], id: match[2], summary: match[3] } : null;
+}
+const stringHasStub = text => {
+  const lines = text.split('\n');
+  return lines.some((line, index) => parseReductionStub(index < lines.length - 1 && line.endsWith('\r') ? line.slice(0, -1) : line));
+};
+function jsonHasStub(value) {
+  if (typeof value === 'string') return stringHasStub(value);
+  if (Array.isArray(value)) return value.some(jsonHasStub);
+  return isObject(value) && Object.values(value).some(jsonHasStub);
+}
+export function rejectReducedSidecar(session) {
+  const leaked = session.messages.some(message => stringHasStub(message.content ?? '') || jsonHasStub(message.content_parts)
+    || message.tool_calls?.some(call => {
+      try { return jsonHasStub(parseNativeJson(call.function.arguments)); }
+      catch { return stringHasStub(call.function.arguments); }
+    }));
+  if (leaked) throw new Error(`export_session_spliced: refusing to export — the sidecar contains a grammar-valid reduction stub beginning with ${JSON.stringify(REDUCTION_SENTINEL)}; a reduced view leaked into an export path that must only read the full-fidelity sidecar`);
+}

package/reduction-view.mjs

@@ -0,0 +1,145 @@
+// Only reapply recorded reductions. Runtime candidate selection, freshness,
+// compaction, escalation and policy remain with their separate owner.
+import { cloneNativeJson, nativeInteger } from './native-json.mjs';
+import { createMessage } from './message.mjs';
+import { REDUCTION_METADATA_KEY } from './reduction-log.mjs';
+import { reductionUnifiedDiff } from './reduction-diff.mjs';
+
+/** Native terminal-noise normalizer: unrecognized/truncated escapes survive. */
+export function normalizeReductionOutput(input) {
+  const rows = [[]]; let row = 0, column = 0;
+  const write = value => { for (const char of value) { while (rows[row].length < column) rows[row].push(' '); rows[row][column++] = char; } };
+  const parameter = (text, fallback) => {
+    const digits = text.split(/[;:]/u, 1)[0].replace(/[^0-9]/gu, '');
+    const value = digits ? BigInt(digits) : null;
+    return value == null || value > 0xffffffffn ? fallback : Number(value);
+  };
+  for (let at = 0; at < input.length;) {
+    if (input[at] === '\r') { column = 0; at++; }
+    else if (input[at] === '\n') { row++; rows[row] ??= []; column = 0; at++; }
+    else if (input[at] === '\x1b' && input[at + 1] === '[') {
+      let end = at + 2;
+      while (end < input.length && input.charCodeAt(end) >= 0x30 && input.charCodeAt(end) <= 0x3f) end++;
+      if (end === input.length || input.charCodeAt(end) < 0x40 || input.charCodeAt(end) > 0x7e) { write(input.slice(at)); break; }
+      const params = input.slice(at + 2, end), final = input[end];
+      if (final === 'm' || ['h', 'l'].includes(final) && params.startsWith('?')) { /* recognized no rendered effect */ }
+      else if (final === 'K') {
+        const mode = parameter(params, 0);
+        if (mode === 0) rows[row].length = Math.min(column, rows[row].length);
+        else if (mode === 1) for (let cell = 0; cell < Math.min(column + 1, rows[row].length); cell++) rows[row][cell] = ' ';
+        else rows[row] = [];
+      } else if (final === 'A') row = Math.max(0, row - Math.max(1, parameter(params, 1)));
+      else if (final === 'B') row = Math.min(row + Math.max(1, parameter(params, 1)), rows.length - 1);
+      else if (final === 'G') column = Math.max(0, parameter(params, 1) - 1);
+      else write(input.slice(at, end + 1));
+      at = end + 1;
+    } else if (input[at] === '\x1b' && input[at + 1] === ']') {
+      let end = at + 2;
+      while (end < input.length && input[end] !== '\x07' && !(input[end] === '\x1b' && input[end + 1] === '\\')) end++;
+      end = Math.min(input.length, end + (input[end] === '\x07' ? 1 : 2)); write(input.slice(at, end)); at = end;
+    } else {
+      const start = at++;
+      while (at < input.length && !['\r', '\n', '\x1b'].includes(input[at])) at++;
+      write(input.slice(start, at));
+    }
+  }
+  return rows.map(value => value.join('')).join('\n');
+}
+
+// Locate the original string token at the top level. Replacing its token
+// preserves whitespace, key order, other arguments and number spellings.
+function replaceArgument(text, field, replacement) {
+  const whitespace = () => { while (/[\x20\t\r\n]/u.test(text[at] ?? '') && at < text.length) at++; };
+  let at = 0;
+  function stringToken() {
+    const start = at;
+    if (text[at++] !== '"') return null;
+    while (at < text.length) {
+      if (text[at] === '\\') at += 2;
+      else if (text[at++] === '"') return [start, at];
+    }
+    return null;
+  }
+  function skipValue() {
+    if (text[at] === '"') return stringToken() != null;
+    if (['[', '{'].includes(text[at])) {
+      const close = text[at++] === '[' ? ']' : '}';
+      while (at < text.length) {
+        if (text[at] === close) { at++; return true; }
+        if (text[at] === '"') { if (!stringToken()) return false; }
+        else if (['[', '{'].includes(text[at])) { if (!skipValue()) return false; }
+        else at++;
+      }
+      return false;
+    }
+    const start = at;
+    while (at < text.length && !/[\x20\t\r\n,}\]]/u.test(text[at])) at++;
+    return at !== start;
+  }
+  whitespace(); if (text[at++] !== '{') return null;
+  while (at < text.length) {
+    whitespace(); if (text[at] === '}') return null;
+    const key = stringToken(); if (!key) return null;
+    // The native byte scanner compares the literal key body, not a decoded
+    // spelling (e.g. an escaped key can verify yet remain unreplaced).
+    const name = text.slice(key[0] + 1, key[1] - 1);
+    whitespace(); if (text[at++] !== ':') return null;
+    whitespace();
+    if (name === field) {
+      const token = stringToken(); if (!token) return null;
+      return text.slice(0, token[0]) + JSON.stringify(replacement) + text.slice(token[1]);
+    }
+    if (!skipValue()) return null;
+    whitespace(); if (text[at++] !== ',') return null;
+  }
+  return null;
+}
+
+/** Mirrors project_messages with the CLI's reapply-only policy. Expanded
+ * records are verified elsewhere but deliberately remain unreduced here. */
+export function reapplyReductionLog(messages, log) {
+  const view = cloneNativeJson(messages), clears = [];
+  for (const record of log.reductions) {
+    const kind = Object.keys(record.kind)[0], data = record.kind[kind];
+    if (kind === 'TurnsCleared') { clears.push(record); continue; }
+    const index = nativeInteger(record.ptr.addr, 'index');
+    if (index >= BigInt(view.length)) continue;
+    const message = view[Number(index)];
+    if (kind === 'ToolOutputTruncated' && message.content != null) {
+      const original = Buffer.from(message.content), kept = record.ptr.span == null ? 0n : nativeInteger(record.ptr.span, '0');
+      const boundary = Number(kept > BigInt(original.length) ? BigInt(original.length) : kept);
+      // Native slicing requires a UTF-8 character boundary; refuse a corrupt
+      // kept span instead of silently introducing a replacement character.
+      const prefix = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(original.subarray(0, boundary));
+      message.content = prefix + '\n\n' + record.placeholder;
+    } else if (kind === 'OutputNormalized' && message.content != null) message.content = normalizeReductionOutput(message.content) + '\n\n' + record.placeholder;
+    else if (['FileReadElided', 'DuplicateOutput', 'Superseded'].includes(kind)) message.content = record.placeholder;
+    else if (kind === 'ImageRedacted') {
+      const index = nativeInteger(data, 'part_index');
+      if (message.content_parts != null && index < BigInt(message.content_parts.length)) message.content_parts[Number(index)] = { type: 'text', text: record.placeholder };
+    } else if (kind === 'FileReadDiffed') {
+      const base = nativeInteger(data.base, 'index');
+      const old = base >= BigInt(messages.length) ? null : messages[Number(base)].content, fresh = messages[Number(index)].content;
+      if (old == null || fresh == null) continue;
+      message.content = record.placeholder + '\n' + reductionUnifiedDiff(old, fresh);
+    } else if (kind === 'ToolInputElided') {
+      const call = message.tool_calls?.find(call => call.id === data.call_id);
+      if (call == null) continue;
+      const spliced = replaceArgument(call.function.arguments, data.field, record.placeholder);
+      if (spliced == null) continue;
+      call.function.arguments = spliced;
+    }
+    message.metadata[REDUCTION_METADATA_KEY] = record.id;
+  }
+  clears.sort((a, b) => {
+    const left = nativeInteger(a.kind.TurnsCleared, 'first'), right = nativeInteger(b.kind.TurnsCleared, 'first');
+    return left > right ? -1 : left < right ? 1 : 0;
+  });
+  for (const record of clears) {
+    const first = nativeInteger(record.kind.TurnsCleared, 'first'), last = nativeInteger(record.kind.TurnsCleared, 'last');
+    if (first > last || last >= BigInt(view.length)) continue;
+    const placeholder = createMessage('system', record.placeholder); placeholder.metadata[REDUCTION_METADATA_KEY] = record.id;
+    view.splice(Number(first), Number(last - first + 1n), placeholder);
+  }
+  return view;
+}

package/retained-projection.mjs

@@ -120,6 +120,15 @@ export class RetainedMetadataProjection {
     }
   }
 
+  /** The sessions one part holds rows for now: what a change to that part can have moved, without a pass over every
+   * row a window holds. A part that holds no row any longer re-projected its sessions (`updatePart`), so they read as
+   * changed rows, not through this. */
+  keysFor(source, part) {
+    const keys = new Set();
+    for (const origin of this.parts.get(partKey(source, part)) ?? []) keys.add(descriptorKey(this.origins.get(origin).descriptor));
+    return keys;
+  }
+
   partsFor(key) {
     return new Set([...(this.candidates.get(key) ?? [])].map((origin) => {
       const row = this.origins.get(origin); return partKey(row.source, row.part);

package/routes-read.mjs

@@ -0,0 +1,103 @@
+// Recorded routing inventory after the owning codec's complete home read.
+// This projects precedence; it neither resolves traffic nor changes a route.
+import { isAbsolute } from 'node:path';
+import { resolveHarnessHomes } from './homes.mjs';
+import { profilePathJoin as join, profilePathParent as parent } from './profile-paths.mjs';
+import { readRouteFolderHome } from './hermes-read-home.mjs';
+import { readOpenclawRouteHome } from './openclaw-profile-home.mjs';
+import { nativeDuplicateObjectKeys, nativeInteger, nativeNumberKind, parseNativeJson, stringifyNativeJsonMember } from './native-json.mjs';
+
+export const ROUTE_HARNESSES = Object.freeze(['hermes', 'openclaw', 'orchestrator']);
+const object = value => value != null && typeof value === 'object' && !Array.isArray(value);
+const compare = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b));
+const refuse = (message, rpcCode = -32602) => { throw Object.assign(new Error(message), { rpcCode }); };
+const filesystem = (path, cwd) => !path.length || isAbsolute(path) || process.platform === 'win32' && /^[A-Za-z]:/u.test(path) ? path : join(cwd, path);
+function struct(value, fields, name) {
+  if (Array.isArray(value)) {
+    if (value.length > fields.length) refuse(`${name} has too many fields`);
+    return parseNativeJson(`{${value.map((_, at) => `${JSON.stringify(fields[at])}:${stringifyNativeJsonMember(value, String(at))}`).join(',')}}`);
+  }
+  if (!object(value)) refuse(`${name} must be a struct`);
+  if (nativeDuplicateObjectKeys(value).some(key => fields.includes(key))) refuse(`${name} has a duplicate field`);
+  return value;
+}
+function query(params, context) {
+  const selected = struct(params, ['harness', 'profile', 'homes'], 'routes params');
+  for (const key of ['harness', 'profile']) if (selected[key] != null && typeof selected[key] !== 'string') refuse(`${key} must be a string`);
+  const homes = resolveHarnessHomes(context.env);
+  if (Object.hasOwn(selected, 'homes')) {
+    const supplied = struct(selected.homes, Object.keys(homes), 'homes');
+    for (const key of Object.keys(homes)) if (Object.hasOwn(supplied, key)) {
+      if (typeof supplied[key] !== 'string') refuse(`homes.${key} must be a string`);
+      homes[key] = supplied[key];
+    }
+  }
+  if (selected.harness != null && !ROUTE_HARNESSES.includes(selected.harness)) refuse(`\`${selected.harness}\` has no routing concept; \`routes.list\` is supported for: ${ROUTE_HARNESSES.join(', ')}`, -32020);
+  return { harness: selected.harness ?? null, profile: selected.profile ?? null, homes };
+}
+function text(row, key, hermes = false) {
+  const value = row?.[key];
+  if (typeof value === 'string') return value;
+  if (typeof value !== 'number') return null;
+  // The folder codec trims integral REALs with its saturating i64 cast;
+  // OpenClaw keeps Number::to_string, including its float spelling.
+  if (hermes && nativeNumberKind(row, key) === 'float' && Number.isInteger(value) && Math.abs(value) < 1e21) {
+    const low = -(1n << 63n), high = (1n << 63n) - 1n;
+    return String(value <= Number(low) ? low : value >= Number(high) ? high : BigInt(value));
+  }
+  return stringifyNativeJsonMember(row, key);
+}
+const field = (match, key, value) => { if (value != null) match[key] = value; };
+function folderRows(harness, supplied, cwd) {
+  const home = harness === 'hermes' ? parent(supplied) ?? '.' : supplied;
+  let profiles; try { profiles = readRouteFolderHome(filesystem(home, cwd), harness); } catch { return []; }
+  const rows = [];
+  for (const name of [...profiles.keys()].sort((a, b) => Number(a !== 'default') - Number(b !== 'default') || compare(a, b))) {
+    const source = join(name === 'default' ? home : join(join(home, 'profiles'), name), 'config.yaml');
+    for (const route of profiles.get(name)) {
+      const match = {};
+      field(match, 'platform', route.platform || null);
+      field(match, 'guild', text(route, 'guild_id', true));
+      field(match, 'chat_id', text(route, 'chat_id', true));
+      field(match, 'thread_id', text(route, 'thread_id', true));
+      const specificity = Number(match.thread_id != null) * 8 + Number(match.chat_id != null) * 4 + Number(match.guild != null) * 2;
+      rows.push({ harness, target: route.agent ?? route.profile, match, specificity, default: false, source });
+    }
+    if (name === 'default') rows.push({ harness, target: 'default', match: {}, specificity: 0, default: true, source });
+  }
+  return rows;
+}
+function openclawRows(home, cwd) {
+  let loaded; try { loaded = readOpenclawRouteHome(filesystem(home, cwd)); } catch { return []; }
+  const source = join(home, 'openclaw.json');
+  const bindings = loaded.bindings.flatMap((binding, at) => object(binding) && typeof binding.agentId === 'string'
+    ? [{ binding, index: Object.hasOwn(binding, 'index') ? nativeInteger(binding, 'index') : BigInt(at) }] : []);
+  // Residue's explicit index replaces the codec's original binding index.
+  // None sorts first, and the sort is stable for equal keys.
+  bindings.sort((a, b) => a.index === b.index ? 0 : a.index == null ? -1 : b.index == null ? 1 : a.index < b.index ? -1 : 1);
+  const rows = bindings.map(({ binding }) => {
+    const raw = object(binding.match) ? binding.match : {}, peer = object(raw.peer) ? raw.peer : {}, match = {};
+    field(match, 'platform', typeof raw.channel === 'string' && raw.channel ? raw.channel : null);
+    field(match, 'account', text(raw, 'accountId'));
+    field(match, 'guild', text(raw, 'guildId'));
+    field(match, 'team', text(raw, 'teamId'));
+    field(match, 'chat_id', text(peer, 'id'));
+    field(match, 'peer_kind', typeof peer.kind === 'string' ? peer.kind : null);
+    const roles = Array.isArray(raw.roles) ? raw.roles.filter(value => typeof value === 'string') : [];
+    if (roles.length) match.roles = roles;
+    const specificity = match.chat_id === '*' ? 6 : match.chat_id != null ? match.peer_kind === 'parent' ? 7 : 8
+      : match.guild != null ? roles.length ? 5 : 4 : match.team != null ? 3 : match.account != null ? 2 : match.platform != null ? 1 : 0;
+    const agent = binding.agentId === loaded.defaultAgent ? 'default' : binding.agentId;
+    const target = !Object.hasOwn(binding, 'agent_id') ? binding.agentId : typeof binding.agent_id === 'string' ? binding.agent_id : loaded.profiles.get(agent)?.id ?? agent;
+    return { harness: 'openclaw', target, match, specificity, default: false, source };
+  });
+  rows.push({ harness: 'openclaw', target: loaded.defaultAgent, match: {}, specificity: 0, default: true, source });
+  return rows;
+}
+export function listRoutes(params, { env = process.env, cwd = process.cwd() } = {}) {
+  const selected = query(params, { env, cwd });
+  const routes = ROUTE_HARNESSES.flatMap(harness => selected.harness != null && selected.harness !== harness ? []
+    : harness === 'openclaw' ? openclawRows(selected.homes.openclaw, cwd) : folderRows(harness, selected.homes[harness], cwd));
+  return { schema: 'supercode.routes.v1', routes: routes.filter(row => selected.profile == null || row.target === selected.profile)
+    .sort((a, b) => compare(a.harness, b.harness) || b.specificity - a.specificity || compare(a.target, b.target)) };
+}