@volter/supercode-interchange 0.1.22 → 0.1.24

package/hermes-read-validation.mjs

@@ -0,0 +1,170 @@
+// Validation dependencies of the Hermes activity home projection. These
+// validators interpret the complete files before a ledger can prove activity.
+import { nativeInteger, nativeNumberKind, parseNativeJson, stringifyNativeJsonMember } from './native-json.mjs';
+import { hermesRowText } from './hermes-fires.mjs';
+
+export const hermesObject = value => value != null && typeof value === 'object' && !Array.isArray(value);
+export const hermesRefuse = (file, key, message) => { throw new Error(`${file}${key ? ` [${key}]` : ''}: ${message}`); };
+// Serde's derived structs also admit positional sequences. Preserve numeric
+// facts when addressing their fields, instead of coercing a float to integer.
+export function hermesStructValue(file, key, value, fields) {
+  if (!Array.isArray(value)) return value;
+  if (value.length > fields.length) hermesRefuse(file, key, 'too many struct fields');
+  return parseNativeJson(`{${value.map((_, index) => `${JSON.stringify(fields[index])}:${stringifyNativeJsonMember(value, String(index))}`).join(',')}}`);
+}
+const required = (file, key, value) => typeof value === 'string' && value !== '' ? value : hermesRefuse(file, key, 'expected a non-empty string');
+const optional = (file, key, value) => value == null ? null : typeof value === 'string' ? value : hermesRefuse(file, key, 'expected a string');
+const map = (file, key, value) => hermesObject(value) ? value : hermesRefuse(file, key, 'expected an object');
+const boolean = (file, key, value) => value == null || typeof value === 'boolean' ? value : hermesRefuse(file, key, 'expected a boolean');
+const unsigned = (parent, key) => nativeInteger(parent, key)
+  ?? (nativeNumberKind(parent, key) == null && Number.isSafeInteger(parent[key]) && parent[key] >= 0 ? BigInt(parent[key]) : null);
+const keys = (file, key, value, allowed) => {
+  map(file, key, value);
+  for (const name of Object.keys(value)) if (!allowed.includes(name)) hermesRefuse(file, `${key}.${name}`, 'unknown key');
+};
+
+export function validateHermesWorker(file, worker) {
+  if (worker == null) return;
+  keys(file, 'worker', worker, ['harness', 'model', 'reasoning_effort', 'preset', 'cwd', 'env', 'permission', 'home', 'surface', 'capacity']);
+  required(file, 'worker.harness', worker.harness);
+  for (const name of ['model', 'reasoning_effort', 'preset']) optional(file, `worker.${name}`, worker[name]);
+  const cwd = Object.hasOwn(worker, 'cwd') ? required(file, 'worker.cwd', worker.cwd) : '.';
+  if (cwd.startsWith('/') || cwd.split('/').includes('..')) hermesRefuse(file, 'worker.cwd', 'must be a relative path inside the profile');
+  if (Object.hasOwn(worker, 'env')) for (const [name, value] of Object.entries(map(file, 'worker.env', worker.env))) {
+    if (typeof value !== 'string') hermesRefuse(file, `worker.env.${name}`, 'expected a string (a secret is written `${NAME}`)');
+  }
+  if (Object.hasOwn(worker, 'permission')) {
+    const permission = worker.permission;
+    keys(file, 'worker.permission', permission, ['timeout_seconds', 'default', 'unattended']);
+    if (Object.hasOwn(permission, 'timeout_seconds')) {
+      const value = unsigned(permission, 'timeout_seconds');
+      if (value == null || value < 1n) hermesRefuse(file, 'worker.permission.timeout_seconds', 'expected an integer >= 1');
+    }
+    if (Object.hasOwn(permission, 'default') && !['deny', 'allow'].includes(permission.default)) hermesRefuse(file, 'worker.permission.default', 'expected deny|allow');
+    if (Object.hasOwn(permission, 'unattended') && !['deny', 'approve'].includes(permission.unattended)) hermesRefuse(file, 'worker.permission.unattended', 'expected deny|approve');
+  }
+  for (const [name, allowed] of [['home', ['profile', 'user']], ['surface', ['headless', 'pane']]]) {
+    const value = optional(file, `worker.${name}`, worker[name]);
+    if (value != null && !allowed.includes(value)) hermesRefuse(file, `worker.${name}`, `expected ${allowed.join('|')}`);
+  }
+  if (Object.hasOwn(worker, 'capacity')) {
+    const value = unsigned(worker, 'capacity');
+    if (value == null || value < 1n || value > 0xffffffffn) hermesRefuse(file, 'worker.capacity', 'expected an integer >= 1');
+  }
+}
+
+export function hermesDelivery(file, key, word, extra = null) {
+  if (word == null) return null;
+  if (typeof word !== 'string' || word === '') hermesRefuse(file, key, 'expected a delivery word');
+  if (['origin', 'local', 'home'].includes(word)) return { kind: word };
+  const parts = word.split(':'), additional = hermesObject(extra) ? extra : {};
+  return { kind: 'explicit', platform: parts[0],
+    chat_id: (parts[1] ?? hermesRowText(additional, 'chat_id')) || null,
+    thread_id: (parts[2] ?? hermesRowText(additional, 'thread_id')) || null };
+}
+
+function validateRepeat(file, key, value) {
+  if (value == null || typeof value === 'boolean' || typeof value === 'number') return;
+  map(file, key, value);
+  if (value.times != null) {
+    const times = unsigned(value, 'times');
+    if (times == null || times < 1n) hermesRefuse(file, `${key}.times`, 'expected null or an integer >= 1');
+  }
+  if (Object.hasOwn(value, 'completed') && unsigned(value, 'completed') == null) hermesRefuse(file, `${key}.completed`, 'expected an integer >= 0');
+}
+
+function decodeJob(file, raw) {
+  map(file, '', raw);
+  const id = required(file, 'id', raw.id), key = name => `${id}.${name}`;
+  const schedule = map(file, key('schedule'), raw.schedule);
+  if (schedule.kind === 'once') required(file, key('schedule.run_at'), schedule.run_at);
+  else if (schedule.kind === 'interval') {
+    if (typeof schedule.minutes !== 'number' || !(schedule.minutes > 0)) hermesRefuse(file, key('schedule.minutes'), 'expected a positive number');
+  } else if (schedule.kind === 'cron') {
+    required(file, key('schedule.expr'), schedule.expr); optional(file, key('schedule.tz'), schedule.tz);
+  } else hermesRefuse(file, key('schedule.kind'), 'expected once|interval|cron');
+  for (const name of ['prompt', 'workdir', 'model', 'machine', 'next_run_at', 'last_run_at', 'last_status', 'created_at']) optional(file, key(name), raw[name]);
+  if (raw.context_from != null && typeof raw.context_from !== 'string' && !Array.isArray(raw.context_from)) hermesRefuse(file, key('context_from'), 'expected a job id, a list of job ids, or "self"');
+  const origin = hermesObject(raw.origin) ? {
+    platform: required(file, key('origin.platform'), raw.origin.platform),
+    chat_id: optional(file, key('origin.chat_id'), raw.origin.chat_id),
+    thread_id: optional(file, key('origin.thread_id'), raw.origin.thread_id),
+  } : null;
+  const deliver = hermesDelivery(file, key('deliver'), raw.deliver) ?? { kind: 'local' };
+  hermesDelivery(file, key('failure_deliver'), raw.failure_deliver);
+  boolean(file, key('attach_to_session'), raw.attach_to_session); boolean(file, key('enabled'), raw.enabled);
+  const target = optional(file, key('session_target'), raw.session_target);
+  if (target != null && !['main', 'current', 'isolated'].includes(target) && !target.startsWith('session:')) hermesRefuse(file, key('session_target'), 'expected main|current|isolated|session:<id>');
+  validateRepeat(file, key('repeat'), raw.repeat);
+  return { id, origin, deliver };
+}
+
+export function hermesJobValues(file, value) {
+  let rows;
+  if (Array.isArray(value)) rows = value;
+  else if (hermesObject(value) && Array.isArray(value.jobs)) rows = value.jobs;
+  else if (hermesObject(value) && hermesObject(value.jobs)) rows = Object.keys(value.jobs).map(id => {
+    const raw = hermesObject(value.jobs[id]) ? value.jobs[id] : {};
+    // Reparse rather than spread so integral REAL and exact integer facts stay
+    // distinct when a keyed-envelope id replaces the record's id.
+    const members = Object.keys(raw).filter(key => key !== 'id').map(key => `${JSON.stringify(key)}:${stringifyNativeJsonMember(raw, key)}`);
+    return parseNativeJson(`{${[`"id":${JSON.stringify(id)}`, ...members].join(',')}}`);
+  });
+  else hermesRefuse(file, '', 'expected an array of jobs or {"jobs": [...]}');
+  return rows;
+}
+
+export function hermesJobRecords(file, value) {
+  const jobs = new Map();
+  const rows = hermesJobValues(file, value);
+  for (const row of rows) {
+    const job = decodeJob(file, row);
+    if (jobs.has(job.id)) hermesRefuse(file, job.id, 'duplicate job id');
+    jobs.set(job.id, job);
+  }
+  return jobs;
+}
+
+export function validateHermesRoutes(file, value) {
+  if (!Array.isArray(value)) return;
+  value.forEach((route, index) => {
+    const key = `profile_routes[${index}]`;
+    map(file, key, route); optional(file, `${key}.name`, route.name);
+    required(file, `${key}.platform`, route.platform);
+    required(file, `${key}.${route.agent == null ? 'profile' : 'agent'}`, route.agent ?? route.profile);
+  });
+}
+
+export function validateHermesChannels(file, value) {
+  if (value === undefined) return;
+  for (const [platform, channel] of Object.entries(map(file, 'platforms', value))) {
+    map(file, `platforms.${platform}`, channel); boolean(file, `platforms.${platform}.enabled`, channel.enabled);
+  }
+}
+
+export function validateHermesSubscriptions(file, value) {
+  for (const [name, subscription] of Object.entries(map(file, '', value))) {
+    map(file, name, subscription);
+    for (const field of ['prompt', 'description', 'created_at', 'secret']) optional(file, `${name}.${field}`, subscription[field]);
+    hermesDelivery(file, `${name}.deliver`, subscription.deliver, subscription.deliver_extra);
+  }
+}
+
+export function validateHermesBudgets(file, value) {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) hermesRefuse(file, 'budgets', 'expected an array');
+  value.forEach((raw, index) => {
+    const key = `budgets[${index}]`;
+    const budget = hermesStructValue(file, key, raw, ['period', 'limit']);
+    map(file, key, budget);
+    if (!['run', 'day', 'month'].includes(budget.period)) hermesRefuse(file, `${key}.period`, 'expected run|day|month');
+    const limit = map(file, `${key}.limit`, hermesStructValue(file, `${key}.limit`, budget.limit, ['tokens', 'cost']));
+    if (limit.tokens != null && unsigned(limit, 'tokens') == null) hermesRefuse(file, `${key}.limit.tokens`, 'expected an unsigned integer');
+    if (limit.cost != null) {
+      const cost = map(file, `${key}.limit.cost`, hermesStructValue(file, `${key}.limit.cost`, limit.cost, ['amount', 'currency', 'source']));
+      if (typeof cost.amount !== 'number') hermesRefuse(file, `${key}.limit.cost.amount`, 'expected a number');
+      if (typeof cost.currency !== 'string') hermesRefuse(file, `${key}.limit.cost.currency`, 'expected a string');
+      optional(file, `${key}.limit.cost.source`, cost.source);
+    }
+  });
+}

package/hermes-read-workflow.mjs

@@ -0,0 +1,164 @@
+// The workflow dependency of a Hermes home read. It validates the committed
+// statechart as data; it never dispatches an actor or evaluates an expression.
+import { hermesObject, hermesRefuse, hermesStructValue } from './hermes-read-validation.mjs';
+
+const own = (object, key) => Object.hasOwn(object, key);
+const fail = (file, key, message) => hermesRefuse(file, key, message);
+const object = (file, key, value) => hermesObject(value) ? value : fail(file, key, 'expected an object');
+const string = (file, key, value) => typeof value === 'string' ? value : fail(file, key, 'expected a string');
+const expr = (file, key, value) => value === null || ['string', 'number', 'boolean'].includes(typeof value) ? value : fail(file, key, 'an expression is a string or a literal');
+const required = (file, key, parent, field, check) => own(parent, field) ? check(file, `${key}.${field}`, parent[field]) : fail(file, `${key}.${field}`, 'missing field');
+const optional = (file, key, parent, field, check) => parent[field] == null ? null : check(file, `${key}.${field}`, parent[field]);
+const defaulted = (file, key, parent, field, check) => own(parent, field) ? check(file, `${key}.${field}`, parent[field]) : null;
+function strict(file, key, value, allowed) {
+  object(file, key, value);
+  for (const name of Object.keys(value)) if (!allowed.includes(name)) fail(file, `${key}.${name}`, 'unknown field');
+}
+function array(file, key, value, check) {
+  if (!Array.isArray(value)) fail(file, key, 'expected an array');
+  value.forEach((item, index) => check(file, `${key}[${index}]`, item));
+}
+function map(file, key, value, check) {
+  object(file, key, value);
+  for (const [name, item] of Object.entries(value)) check(file, `${key}.${name}`, item);
+}
+const strings = (file, key, value) => array(file, key, value, string);
+const expressions = (file, key, value) => array(file, key, value, expr);
+const expressionMap = (file, key, value) => map(file, key, value, expr);
+const valueMap = (file, key, value) => object(file, key, value);
+
+function action(file, key, value) {
+  if (typeof value !== 'string' && (!hermesObject(value) || Object.keys(value).length !== 1)) fail(file, key, 'an action is a name or a one-key map');
+}
+const actions = (file, key, value) => array(file, key, value, action);
+function validation(file, key, value) {
+  object(file, key, value); required(file, key, value, 'expr', expr); required(file, key, value, 'message', string);
+}
+function transition(file, key, value) {
+  object(file, key, value);
+  for (const field of ['from', 'by']) defaulted(file, key, value, field, strings);
+  optional(file, key, value, 'guard', expr);
+  defaulted(file, key, value, 'validate', (f, k, v) => array(f, k, v, validation));
+  for (const field of ['target', 'description']) optional(file, key, value, field, string);
+  defaulted(file, key, value, 'actions', actions);
+}
+const transitions = (file, key, value) => array(file, key, value, transition);
+const transitionMap = (file, key, value) => map(file, key, value, transitions);
+function delayed(file, key, value) { transition(file, key, value); required(file, key, value, 'after', expr); }
+function run(file, key, value) {
+  object(file, key, value);
+  for (const field of ['role', 'session']) required(file, key, value, field, string);
+  defaulted(file, key, value, 'prompt', string); optional(file, key, value, 'prompt_file', string);
+  defaulted(file, key, value, 'skills', strings); defaulted(file, key, value, 'limits', expressionMap);
+}
+function status(file, key, value) {
+  object(file, key, value);
+  for (const field of ['stored_as', 'description', 'run_role', 'resume_as']) optional(file, key, value, field, string);
+  optional(file, key, value, 'run', run);
+  for (const field of ['entry', 'exit']) defaulted(file, key, value, field, actions);
+  defaulted(file, key, value, 'on', transitionMap); defaulted(file, key, value, 'always', transitions);
+  defaulted(file, key, value, 'after', (f, k, v) => array(f, k, v, delayed));
+}
+const statusMap = (file, key, value) => map(file, key, value, status);
+// CapFilter (crates/interchange/src/orchestration/workflow.rs) in its declaration order, which a sequence-form struct
+// follows: `dispatch` an optional boolean, every other key a name or a list of names.
+const filterNames = ['card', 'model', 'harness', 'assignee', 'status', 'stored', 'machine', 'board'];
+const filterFields = ['dispatch', ...filterNames];
+function filter(file, key, value) {
+  strict(file, key, value, filterFields);
+  optional(file, key, value, 'dispatch', (f, k, v) => typeof v === 'boolean' ? v : fail(f, k, 'expected a boolean'));
+  for (const field of filterNames) defaulted(file, key, value, field, (f, k, v) => typeof v === 'string' ? v : strings(f, k, v));
+}
+function reserve(file, key, value) {
+  strict(file, key, value, ['for', 'slots']); required(file, key, value, 'for', filter); required(file, key, value, 'slots', expr);
+}
+function capacity(file, key, value) {
+  strict(file, key, value, ['name', 'scope', 'counts', 'where', 'unless', 'max', 'reserve']);
+  required(file, key, value, 'name', string);
+  required(file, key, value, 'scope', (f, k, v) => ['global', 'board', 'machine', 'profile'].includes(v) ? v : fail(f, k, 'unknown scope'));
+  required(file, key, value, 'counts', (f, k, v) => ['runs', 'cards', 'sessions', 'turns', 'starts'].includes(v) ? v : fail(f, k, 'unknown count'));
+  for (const field of ['where', 'unless']) defaulted(file, key, value, field, filter);
+  required(file, key, value, 'max', expr); optional(file, key, value, 'reserve', reserve);
+}
+function dispatch(file, key, value) {
+  strict(file, key, value, ['tick', 'start', 'eligible', 'order', 'capacity']);
+  required(file, key, value, 'tick', expr); required(file, key, value, 'start', string); optional(file, key, value, 'eligible', expr);
+  defaulted(file, key, value, 'order', expressions); defaulted(file, key, value, 'capacity', (f, k, v) => array(f, k, v, capacity));
+}
+function runMachine(file, key, value) {
+  object(file, key, value); optional(file, key, value, 'recurring_role', string);
+  defaulted(file, key, value, 'limits', expressionMap); defaulted(file, key, value, 'roles', (f, k, v) => map(f, k, v, run));
+  defaulted(file, key, value, 'states', statusMap); defaulted(file, key, value, 'initial', string);
+  for (const field of ['on', 'outcomes']) defaulted(file, key, value, field, transitionMap);
+}
+function storageRule(file, key, value) { object(file, key, value); required(file, key, value, 'guard', expr); required(file, key, value, 'status', string); }
+
+const listShape = child => ({ list: child }), mapShape = child => ({ map: child });
+const validationShape = { fields: ['expr', 'message'] };
+const transitionShape = { fields: ['from', 'by', 'guard', 'validate', 'target', 'actions', 'description'], children: { validate: listShape(validationShape) } };
+const transitionMapShape = mapShape(listShape(transitionShape));
+const runShape = { fields: ['role', 'session', 'prompt', 'prompt_file', 'skills', 'limits'] };
+const statusShape = { fields: ['stored_as', 'description', 'run', 'run_role', 'resume_as', 'entry', 'exit', 'on', 'always', 'after'], children: {
+  run: runShape, on: transitionMapShape, always: listShape(transitionShape),
+  // A flattened transition has only a mapping deserializer.
+  after: listShape({ children: { validate: listShape(validationShape) } }),
+} };
+const filterShape = { fields: filterFields };
+const capacityShape = { fields: ['name', 'scope', 'counts', 'where', 'unless', 'max', 'reserve'], children: {
+  where: filterShape, unless: filterShape, reserve: { fields: ['for', 'slots'], children: { for: filterShape } },
+} };
+const workflowShape = { fields: ['run', 'verbs', 'derived', 'relations', 'flags', 'stored_as', 'losses', 'description', 'params', 'roles', 'initial', 'statuses', 'on', 'dispatch', 'notify'], children: {
+  run: { fields: ['recurring_role', 'limits', 'roles', 'states', 'initial', 'on', 'outcomes'], children: { roles: mapShape(runShape), states: mapShape(statusShape), on: transitionMapShape, outcomes: transitionMapShape } },
+  verbs: transitionMapShape, initial: listShape(transitionShape), statuses: mapShape(statusShape), on: transitionMapShape,
+  stored_as: listShape({ fields: ['guard', 'status'] }),
+  dispatch: { fields: ['tick', 'start', 'eligible', 'order', 'capacity'], children: { capacity: listShape(capacityShape) } },
+} };
+function normalize(file, key, value, shape) {
+  if (value == null) return value;
+  if (shape.list) return Array.isArray(value) ? value.map((item, index) => normalize(file, `${key}[${index}]`, item, shape.list)) : value;
+  if (shape.map) {
+    if (hermesObject(value)) for (const name of Object.keys(value)) value[name] = normalize(file, `${key}.${name}`, value[name], shape.map);
+    return value;
+  }
+  if (shape.fields) value = hermesStructValue(file, key, value, shape.fields);
+  if (hermesObject(value)) for (const [name, child] of Object.entries(shape.children ?? {})) if (own(value, name)) value[name] = normalize(file, `${key}.${name}`, value[name], child);
+  return value;
+}
+
+export function validateHermesWorkflow(file, value) {
+  value = normalize(file, '', value, workflowShape);
+  object(file, '', value); optional(file, '', value, 'run', runMachine);
+  for (const field of ['verbs', 'on']) defaulted(file, '', value, field, transitionMap);
+  for (const field of ['derived', 'roles']) defaulted(file, '', value, field, expressionMap);
+  for (const field of ['relations', 'flags', 'params']) defaulted(file, '', value, field, valueMap);
+  defaulted(file, '', value, 'stored_as', (f, k, v) => array(f, k, v, storageRule)); defaulted(file, '', value, 'losses', strings);
+  optional(file, '', value, 'description', string);
+  required(file, '', value, 'initial', transitions); required(file, '', value, 'statuses', statusMap); required(file, '', value, 'dispatch', dispatch);
+  defaulted(file, '', value, 'notify', (f, k, v) => map(f, k, v, (ff, kk, vv) => map(ff, kk, vv, string)));
+
+  const known = (target, statuses, message) => {
+    if (target != null && !target.startsWith('{{') && !own(statuses, target)) fail(file, '', `${message} ${target}`);
+  };
+  const check = rows => { for (const row of rows ?? []) known(row.target, value.statuses, 'no status'); };
+  check(value.initial);
+  for (const rows of Object.values(value.verbs ?? {})) {
+    check(rows);
+    for (const row of rows) for (const source of row.from ?? []) if (!own(value.statuses, source)) fail(file, '', `no source status ${source}`);
+  }
+  const machine = value.run;
+  if (machine != null) {
+    const states = machine.states ?? {};
+    if (!own(states, machine.initial ?? '')) fail(file, '', `no initial run state ${machine.initial ?? ''}`);
+    for (const rows of Object.values(machine.outcomes ?? {})) check(rows);
+    const rules = [...Object.values(machine.on ?? {}), ...Object.values(states).flatMap(state => Object.values(state.on ?? {}))];
+    for (const rows of rules) for (const row of rows) known(row.target, states, 'no run state');
+    for (const [name, spec] of Object.entries(machine.roles ?? {})) if (!own(value.roles ?? {}, spec.role)) fail(file, '', `run ${name}: no role ${spec.role}`);
+  }
+  for (const rows of Object.values(value.on ?? {})) check(rows);
+  for (const [name, state] of Object.entries(value.statuses)) {
+    if (state.run_role != null && !own(machine?.roles ?? {}, state.run_role)) fail(file, '', `${name}: no run specification ${state.run_role}`);
+    for (const rows of Object.values(state.on ?? {})) check(rows);
+    check(state.always); check(state.after);
+    if (state.run != null && !own(value.roles ?? {}, state.run.role)) fail(file, '', `${name}: its run names no role ${state.run.role}`);
+  }
+}

package/hermes-read-yaml.mjs

@@ -0,0 +1,68 @@
+// YAML 1.2 file values enter the Hermes read projection with integer and
+// float facts intact. A tagged value remains a tagged one-key JSON mapping.
+import { isAlias, isMap, isScalar, isSeq, parseDocument } from 'yaml';
+import { setNativeFloat, setNativeInteger, stringifyNativeJsonMember } from './native-json.mjs';
+import { hermesRefuse } from './hermes-read-validation.mjs';
+
+const standard = new Set(['str', 'null', 'bool', 'int', 'float', 'seq', 'map'].map(name => `tag:yaml.org,2002:${name}`));
+const memberOrder = new WeakMap();
+export const hermesYamlKeys = value => memberOrder.get(value) ?? Object.keys(value);
+const set = (object, key, entry) => {
+  if (entry.kind === 'integer') setNativeInteger(object, key, entry.whole);
+  else if (entry.kind === 'float') setNativeFloat(object, key, entry.value);
+  else Object.defineProperty(object, key, { value: entry.value, enumerable: true, writable: true, configurable: true });
+};
+function scalar(value) {
+  if (typeof value === 'bigint') {
+    if (value >= -(1n << 63n) && value <= (1n << 64n) - 1n) return { kind: 'integer', whole: value, value: Number(value) };
+    const number = Number(value); return { kind: 'float', value: Number.isFinite(number) ? number : null };
+  }
+  return typeof value === 'number' ? { kind: 'float', value: Number.isFinite(value) ? value : null } : { value };
+}
+
+export function readHermesYaml(file, text) {
+  const document = parseDocument(text, { version: '1.2', schema: 'core', intAsBigInt: true, uniqueKeys: true, logLevel: 'silent' });
+  if (document.errors.length) hermesRefuse(file, '', `YAML: ${document.errors[0].message}`);
+  const active = new Set();
+  const visit = (node, depth = 0) => {
+    if (node == null) return { value: null };
+    if (depth >= 128 || active.has(node)) hermesRefuse(file, '', 'YAML: recursive value');
+    if (isAlias(node)) {
+      const resolved = node.resolve(document);
+      if (!resolved) hermesRefuse(file, '', 'YAML: unresolved alias');
+      active.add(node);
+      try { return visit(resolved, depth + 1); } finally { active.delete(node); }
+    }
+    active.add(node);
+    try {
+      let entry;
+      if (isScalar(node)) entry = scalar(node.value);
+      else if (isSeq(node)) {
+        const value = [];
+        node.items.forEach((item, index) => set(value, String(index), visit(item, depth + 1)));
+        entry = { value };
+      } else if (isMap(node)) {
+        const value = Object.create(null), members = new Map();
+        for (const pair of node.items) {
+          const key = visit(pair.key, depth + 1);
+          let name;
+          if (typeof key.value === 'string' || typeof key.value === 'boolean') name = String(key.value);
+          else if (typeof key.value === 'number' && Number.isFinite(key.value)) {
+            const holder = {}; set(holder, 'key', key); name = stringifyNativeJsonMember(holder, 'key');
+          } else hermesRefuse(file, '', 'YAML: key must be a string');
+          members.set(name, visit(pair.value, depth + 1));
+        }
+        for (const [name, member] of members) set(value, name, member);
+        memberOrder.set(value, [...members.keys()]);
+        entry = { value };
+      } else hermesRefuse(file, '', 'YAML: unsupported value');
+      if (node.tag && !standard.has(node.tag)) {
+        const value = Object.create(null), tag = node.tag.startsWith('!') ? node.tag : `!${node.tag}`;
+        set(value, tag, entry); entry = { value };
+      }
+      return entry;
+    } finally { active.delete(node); }
+  };
+  const value = visit(document.contents).value;
+  return value == null ? Object.create(null) : value;
+}

package/hermes-store.mjs

@@ -72,7 +72,7 @@ export { lineage as hermesLineageKind, nouns as hermesSessionNouns };
 export async function readHermesStore(path, { metrics = {} } = {}) {
   return readStore(path, (db) => {
     statement(db, 'SELECT count(*) FROM sessions').get();
-    const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map((row) => row.name));
+    const tables = new Set(statement(db, "SELECT name FROM sqlite_master WHERE type='table'").all().map((row) => row.name));
     if (!['sessions', 'messages', 'schema_version'].every((table) => tables.has(table))) return { rows: [], mirrors: new Map() };
     const columns = tableColumns(db, 'sessions');
     const extendedSchema = extendedColumns.every((column) => columns.has(column));

package/homes.mjs

@@ -1,9 +1,9 @@
 import { userInfo } from 'node:os';
-import { join } from 'node:path';
+import { join as nativeDefaultJoin } from 'node:path';
 
 /** Native HarnessHomes defaults. An empty selected harness home is present;
  * only HOME itself uses the nonempty rule from interchange::user_home. */
-export function resolveHarnessHomes(env = process.env) {
+export function resolveHarnessHomes(env = process.env, { joinPath: join = nativeDefaultJoin } = {}) {
   const accountHome = () => { try { return userInfo().homedir || '.'; } catch { return '.'; } };
   const home = env.HOME || (process.platform === 'win32' && env.USERPROFILE) || accountHome();
   const data = env.XDG_DATA_HOME ?? join(home, '.local', 'share');

package/index.d.ts

@@ -23,7 +23,11 @@ export interface SessionDescriptor {
   recurrence?: { job_id: string; kind: string };
   cross_surface?: { state: string; platform?: string; error?: string };
   workspace?: { kind: 'repo' | 'channel' | 'none'; value?: string };
+  /** Read-only live display facts, never permission to answer a native request. */
+  pending_request?: Record<string, unknown> | null;
+  pending_request_unavailable?: SessionReadFailure;
 }
+export interface SessionReadFailure { code: string | null; message: string; errors?: SessionReadFailure[] }
 export interface DiscoveryQuery {
   homes?: Partial<HarnessHomes>; harnesses?: HarnessId[];
   workspace?: string | null; workspace_subtree?: boolean; workspace_family?: string | null;
@@ -69,6 +73,13 @@ export function projectMetadataPage(query: DiscoveryQuery, descriptors: Iterable
  * of SDK clients or mutate a foreign harness's store. */
 export type IndexMetrics = Record<string, number>;
 export interface FileFingerprint { device: string; inode: string; size: string; mtime_ns: string }
+export interface SessionFileReader {
+  path: string; size: number; fingerprint: FileFingerprint; modified_ms: number | null;
+  read(position: number, length: number, options?: { appended?: boolean }): Promise<Buffer>;
+}
+/** Checked nonblocking regular-file admission, fixed-size ranges and final stamps;
+ * native symlinks and append-only growth remain supported. Close is awaited. */
+export function withSessionFile<T>(path: string, work: (reader: SessionFileReader) => T | Promise<T>, metrics?: IndexMetrics): Promise<{ result: T; fingerprint: FileFingerprint; size: number; modified_ms: number | null }>;
 export interface SourceStamp { path: string; missing?: boolean; fingerprint?: FileFingerprint }
 export interface FileReadCache {
   fingerprint?: FileFingerprint; size?: number; modified_ms?: number | null;
@@ -94,7 +105,8 @@ export function sameFingerprint(left?: FileFingerprint | null, right?: FileFinge
 export function verifySources(sources: SourceStamp[]): Promise<void>;
 export function storeFingerprints(path: string): Promise<SourceStamp[]>;
 export function readGeminiProjects(root: string, metrics?: IndexMetrics): Promise<{ source: SourceStamp; projects: Map<string, string> }>;
-export function readSourceJson(path: string, metrics?: IndexMetrics): Promise<SourceStamp & { result: unknown }>;
+/** `previous` must be the in-process result of an earlier call; deserialized copies are reread. */
+export function readSourceJson(path: string, metrics?: IndexMetrics, previous?: SourceStamp & { result: unknown }): Promise<SourceStamp & { result: unknown }>;
 export interface StoreRead<T> { sources: SourceStamp[]; result: T }
 export function readForeignStore(harness: HarnessId, path: string, options?: { previousMarks?: Map<string, string>; metrics?: IndexMetrics }): Promise<StoreRead<{ marks: Map<string, string>; rows: SessionDescriptor[]; removed: string[] }>>;
 export function readHermesStore(path: string, options?: { metrics?: IndexMetrics }): Promise<StoreRead<{ rows: SessionDescriptor[]; mirrors: NonNullable<MetadataProjectionOptions['hermesMirrors']> }>>;
@@ -125,6 +137,7 @@ export function filedUnderOwnKey(descriptor: SessionDescriptor): boolean;
 export class RetainedMetadataProjection {
   constructor(query: DiscoveryQuery, sources: string[], records: Iterable<IndexMetadataRecord>, metrics?: IndexMetrics);
   updatePart(source: string, part: string, records: Iterable<IndexMetadataRecord>): void;
+  keysFor(source: string, part: string): Set<string>;
   partsFor(key: string): Set<string>;
   page(query: DiscoveryQuery): DiscoveryPage;
 }

package/index.mjs

@@ -7,7 +7,7 @@ export {
 } from './query.mjs';
 export { FILE_HARNESSES, STORE_HARNESSES, normalizedSourcePath, pathUnder, fileRoot, sessionPartFor, listSessionParts, readFileMetadata, metadataReaderVersion } from './source-layout.mjs';
 export { sourceStat, sourceEntries, selectStoreFiles, storeRegistryDirectories } from './store-registry.mjs';
-export { fileFingerprint, sameFingerprint } from './file-io.mjs';
+export { fileFingerprint, sameFingerprint, withSessionFile } from './file-io.mjs';
 export { verifySources, readGeminiProjects, readSourceJson } from './source-files.mjs';
 export { storeFingerprints } from './sqlite-reader.mjs';
 export { readForeignStore } from './foreign-store.mjs';