@volter/supercode-interchange 0.0.0-stage → 0.1.0

package/query.mjs

@@ -0,0 +1,150 @@
+import { selectedHarnesses } from './homes.mjs';
+import { repositoryFamily, sameRepositoryFamily, workspaceScope } from './workspace.mjs';
+import { hermesMirrorKey, includeHermesMirror } from './hermes-mirror.mjs';
+import { finalizeNouns } from './metadata.mjs';
+import { nativeTrim } from './text.mjs';
+import { parseNativeJson, nativeInteger } from './native-json.mjs';
+
+export const descriptorKey = (row) => JSON.stringify([row.locator.harness, row.locator.session_id]);
+const cursorKey = (row) => [row.updated_at_ms ?? null, row.locator.harness, row.locator.session_id];
+const utf8Order = (left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right));
+
+export function descriptorOrder(left, right) {
+  const a = left.updated_at_ms, b = right.updated_at_ms;
+  if (a !== b) {
+    if (a == null) return 1;
+    if (b == null) return -1;
+    return a > b ? -1 : 1;
+  }
+  return utf8Order(left.locator.harness, right.locator.harness) || utf8Order(left.locator.session_id, right.locator.session_id);
+}
+
+export function descriptorMatches(row, search) {
+  return [row.locator.harness, row.locator.session_id, row.title, row.cwd, row.model]
+    .some((value) => typeof value === 'string' && value.toLowerCase().includes(search));
+}
+
+/** Clone before rolling up; a query never changes the owner's raw rows. */
+function rollUp(rows, includeChildren) {
+  const byId = new Map(rows.map((row) => [descriptorKey(row), row]));
+  const updates = new Map(), counts = new Map();
+  for (const row of rows) {
+    let parent = row.parent_session_id;
+    let root = null;
+    const seen = new Set();
+    while (parent != null && !seen.has(parent)) {
+      seen.add(parent);
+      const ancestor = byId.get(JSON.stringify([row.locator.harness, parent]));
+      if (!ancestor) break;
+      root = ancestor;
+      parent = ancestor.parent_session_id;
+    }
+    if (root) {
+      counts.set(root, (counts.get(root) ?? 0) + 1);
+      if (row.updated_at_ms != null) updates.set(root, Math.max(updates.get(root) ?? 0, row.updated_at_ms));
+    }
+  }
+  for (const [root, updated] of updates) root.updated_at_ms = Math.max(root.updated_at_ms ?? 0, updated);
+  for (const [root, count] of counts) root.child_session_count = count;
+  return includeChildren ? rows : rows.filter((row) => row.parent_session_id == null);
+}
+
+function familyRows(rows, rootId) {
+  // The native family selector addresses a native id rather than a locator.
+  const parents = new Map(rows.map((row) => [row.locator.session_id, row.parent_session_id]));
+  return rows.filter((row) => {
+    let current = row.locator.session_id;
+    const seen = new Set();
+    while (current != null && !seen.has(current)) {
+      if (current === rootId) return true;
+      seen.add(current); current = parents.get(current);
+    }
+    return false;
+  });
+}
+
+/** Filter the raw metadata index before page enrichment, matching the native
+ * catalog's scan scope, lineage projection, filter order and stable order. */
+export function projectMetadata(query, descriptors, { hermesMirrors } = {}) {
+  if (query.search_previews) throw new Error('preview search requires discovery, not a metadata-only index projection');
+  const selected = new Set(selectedHarnesses(query));
+  const scope = workspaceScope(query);
+  let rows = [...descriptors].filter((row) => selected.has(row.locator.harness)
+    && (row.locator.harness !== 'hermes' || includeHermesMirror(hermesMirrors?.get(hermesMirrorKey(row)), selected))
+    && (!scope || scope(row))).map((row) => finalizeNouns(row));
+  rows = rollUp(rows, query.include_child_sessions === true);
+  if (query.root_session_id != null) rows = familyRows(rows, query.root_session_id);
+  if (query.workspace_family != null) {
+    const wanted = repositoryFamily(query.workspace_family);
+    const admitted = new Map();
+    rows = rows.filter((row) => {
+      if (row.cwd == null) return false;
+      if (!admitted.has(row.cwd)) admitted.set(row.cwd, sameRepositoryFamily(repositoryFamily(row.cwd), wanted));
+      return admitted.get(row.cwd);
+    });
+  }
+  const profile = query.profile == null ? null : nativeTrim(query.profile);
+  if (profile) rows = rows.filter((row) => row.profile === profile);
+  if (query.updated_after_ms != null) rows = rows.filter((row) => row.updated_at_ms != null && row.updated_at_ms >= query.updated_after_ms);
+  if (query.updated_before_ms != null) rows = rows.filter((row) => row.updated_at_ms != null && row.updated_at_ms <= query.updated_before_ms);
+  rows.sort(descriptorOrder);
+  const search = query.query == null ? null : nativeTrim(query.query).toLowerCase();
+  if (search) rows = rows.filter((row) => descriptorMatches(row, search));
+  return rows;
+}
+
+/** Discovery's existing hex JSON tuple cursor. It is unrelated to a database
+ * change-stream cursor and becomes stale when its exact row no longer matches. */
+export function encodeDiscoveryCursor(row) {
+  return Buffer.from(JSON.stringify(cursorKey(row))).toString('hex');
+}
+
+export function decodeDiscoveryCursor(cursor) {
+  try {
+    if (typeof cursor !== 'string' || cursor.length % 2 !== 0 || !/^[0-9a-f]*$/i.test(cursor)) throw new Error();
+    // Buffer's UTF-8 decoder replaces invalid bytes; the native JSON parser
+    // refuses them. Decode fatally before parsing the tuple.
+    const value = parseNativeJson(new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(Buffer.from(cursor, 'hex')));
+    if (!Array.isArray(value) || value.length !== 3 || !(value[0] === null || (nativeInteger(value, '0') != null && Number.isSafeInteger(value[0]) && value[0] >= 0))
+      || typeof value[1] !== 'string' || typeof value[2] !== 'string') throw new Error();
+    return value;
+  } catch { throw new Error('discovery cursor is invalid'); }
+}
+
+export function paginateDescriptors(query, rows) {
+  let start = 0;
+  if (query.cursor != null) {
+    const key = JSON.stringify(decodeDiscoveryCursor(query.cursor));
+    const at = rows.findIndex((row) => JSON.stringify(cursorKey(row)) === key);
+    if (at < 0) throw new Error('discovery cursor is stale or invalid');
+    start = at + 1;
+  }
+  if (query.limit != null && (!Number.isSafeInteger(query.limit) || query.limit < 0)) throw new Error('discovery limit must be a nonnegative integer');
+  const end = query.limit == null ? rows.length : Math.min(rows.length, start + query.limit);
+  const sessions = rows.slice(start, end);
+  return { sessions, next_cursor: end < rows.length && sessions.length ? encodeDiscoveryCursor(sessions.at(-1)) : null };
+}
+
+export function discoveryReceipt(query, sessions, totalMatched, truncated, searchedPreviews = false) {
+  let oldest = null, newest = null;
+  for (const row of sessions) {
+    if (row.updated_at_ms == null) continue;
+    oldest = oldest == null ? row.updated_at_ms : Math.min(oldest, row.updated_at_ms);
+    newest = newest == null ? row.updated_at_ms : Math.max(newest, row.updated_at_ms);
+  }
+  return {
+    ...(searchedPreviews ? { searched_previews: true } : {}),
+    ...(query.updated_after_ms != null ? { requested_after_ms: query.updated_after_ms } : {}),
+    ...(query.updated_before_ms != null ? { requested_before_ms: query.updated_before_ms } : {}),
+    ...(query.limit != null ? { requested_limit: query.limit } : {}),
+    ...(oldest != null ? { oldest_returned_ms: oldest } : {}),
+    ...(newest != null ? { newest_returned_ms: newest } : {}),
+    returned: sessions.length, total_matched: totalMatched, truncated,
+  };
+}
+
+export function projectMetadataPage(query, descriptors, options) {
+  const rows = projectMetadata(query, descriptors, options);
+  const page = paginateDescriptors(query, rows);
+  return { ...page, receipt: discoveryReceipt(query, page.sessions, rows.length, page.next_cursor != null) };
+}

package/retained-projection.mjs

@@ -0,0 +1,128 @@
+import { descriptorKey, descriptorOrder, projectMetadata, paginateDescriptors, discoveryReceipt } from './query.mjs';
+
+const order = (a, b) => a.rank - b.rank || Buffer.compare(Buffer.from(a.part), Buffer.from(b.part))
+  || Buffer.compare(Buffer.from(a.row_key), Buffer.from(b.row_key));
+const originKey = (row) => JSON.stringify([row.source, row.part, row.row_key]);
+const partKey = (source, part) => JSON.stringify([source, part]);
+
+/** A retained query owns one ordered metadata projection, shared by windows
+ * with the same filters. An ordinary part update replaces only its connected
+ * lineage components; pagination copies the requested window alone. Source
+ * rows are references to the owner's committed immutable descriptor values. */
+export class RetainedMetadataProjection {
+  constructor(query, sources, records, metrics = {}) {
+    this.metrics = metrics; metrics.projection_rebuilds = (metrics.projection_rebuilds ?? 0) + 1;
+    this.query = query; this.ranks = new Map(sources.map((source, rank) => [source, rank]));
+    this.origins = new Map(); this.parts = new Map(); this.candidates = new Map(); this.raw = new Map();
+    this.ids = new Map(); this.edges = new Map(); this.projected = new Map(); this.ordered = [];
+    for (const row of records) this.#add(row);
+    for (const key of this.candidates.keys()) this.#winner(key);
+    for (const row of this.raw.values()) this.#link(row.descriptor, 1);
+    const initial = this.#project([...this.raw.keys()]);
+    this.ordered = initial;
+    for (const row of initial) this.projected.set(descriptorKey(row), row);
+  }
+
+  #add(record) {
+    const row = { ...record, rank: this.ranks.get(record.source) }, origin = originKey(row), key = descriptorKey(row.descriptor);
+    this.origins.set(origin, row);
+    if (!this.parts.has(partKey(row.source, row.part))) this.parts.set(partKey(row.source, row.part), new Set());
+    this.parts.get(partKey(row.source, row.part)).add(origin);
+    if (!this.candidates.has(key)) this.candidates.set(key, new Set());
+    this.candidates.get(key).add(origin);
+  }
+
+  #winner(key) {
+    const candidates = [...(this.candidates.get(key) ?? [])].map((origin) => this.origins.get(origin)).sort(order);
+    if (!candidates.length) { this.raw.delete(key); return; }
+    // snapshot's deduplication keeps the last value, but the first occurrence
+    // determines map iteration order (including native cross-harness families).
+    this.raw.set(key, { ...candidates.at(-1), first: candidates[0] });
+  }
+
+  #edge(from, to, delta) {
+    if (!this.edges.has(from)) this.edges.set(from, new Map());
+    const held = this.edges.get(from), count = (held.get(to) ?? 0) + delta;
+    if (count) held.set(to, count); else held.delete(to);
+    if (!held.size) this.edges.delete(from);
+  }
+
+  #link(row, delta) {
+    const id = row.locator.session_id, key = descriptorKey(row);
+    if (delta > 0) {
+      if (!this.ids.has(id)) this.ids.set(id, new Set());
+      this.ids.get(id).add(key);
+    } else {
+      const held = this.ids.get(id); held?.delete(key); if (!held?.size) this.ids.delete(id);
+    }
+    if (row.parent_session_id != null) {
+      this.#edge(id, row.parent_session_id, delta); this.#edge(row.parent_session_id, id, delta);
+    }
+  }
+
+  #component(ids) {
+    const pending = [...ids], seen = new Set(), keys = new Set();
+    while (pending.length) {
+      const id = pending.pop(); if (seen.has(id)) continue; seen.add(id);
+      for (const key of this.ids.get(id) ?? []) keys.add(key);
+      for (const parent of this.edges.get(id)?.keys() ?? []) pending.push(parent);
+    }
+    return keys;
+  }
+
+  #project(keys) {
+    const records = keys.map((key) => this.raw.get(key)).filter(Boolean).sort((a, b) => order(a.first, b.first));
+    this.metrics.projected_metadata_rows = (this.metrics.projected_metadata_rows ?? 0) + records.length;
+    const mirrors = new Map(records.filter((row) => row.mirror != null).map((row) =>
+      [JSON.stringify([row.descriptor.locator.storage.path, row.descriptor.locator.session_id]), row.mirror]));
+    return projectMetadata(this.query, records.map((row) => row.descriptor), { hermesMirrors: mirrors });
+  }
+
+  #at(row) {
+    let low = 0, high = this.ordered.length;
+    while (low < high) {
+      const mid = low + Math.floor((high - low) / 2);
+      if (descriptorOrder(this.ordered[mid], row) < 0) low = mid + 1; else high = mid;
+    }
+    return low;
+  }
+
+  updatePart(source, part, records) {
+    this.metrics.projection_part_updates = (this.metrics.projection_part_updates ?? 0) + 1;
+    const slot = partKey(source, part), before = [...(this.parts.get(slot) ?? [])], incoming = [...records], touched = new Set();
+    for (const origin of before) touched.add(descriptorKey(this.origins.get(origin).descriptor));
+    for (const row of incoming) touched.add(descriptorKey(row.descriptor));
+    const ids = new Set([...touched].map((key) => JSON.parse(key)[1])), affected = this.#component(ids);
+    for (const key of touched) if (this.raw.has(key)) this.#link(this.raw.get(key).descriptor, -1);
+    for (const origin of before) {
+      const row = this.origins.get(origin), key = descriptorKey(row.descriptor);
+      this.candidates.get(key).delete(origin); this.origins.delete(origin);
+      if (!this.candidates.get(key).size) this.candidates.delete(key);
+    }
+    this.parts.delete(slot);
+    for (const row of incoming) this.#add(row);
+    for (const key of touched) {
+      this.#winner(key); if (this.raw.has(key)) this.#link(this.raw.get(key).descriptor, 1);
+    }
+    for (const key of this.#component(ids)) affected.add(key);
+    for (const key of touched) affected.add(key);
+    for (const key of affected) {
+      const old = this.projected.get(key);
+      if (old) { this.ordered.splice(this.#at(old), 1); this.projected.delete(key); }
+    }
+    for (const row of this.#project([...affected])) {
+      this.ordered.splice(this.#at(row), 0, row); this.projected.set(descriptorKey(row), row);
+    }
+  }
+
+  partsFor(key) {
+    return new Set([...(this.candidates.get(key) ?? [])].map((origin) => {
+      const row = this.origins.get(origin); return partKey(row.source, row.part);
+    }));
+  }
+
+  page(query) {
+    const page = paginateDescriptors(query, this.ordered);
+    return { ...page, receipt: discoveryReceipt(query, page.sessions, this.ordered.length, page.next_cursor != null) };
+  }
+}

package/source-files.mjs

@@ -0,0 +1,190 @@
+import { stat } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { withSessionFile, parseJsonLine, fileFingerprint, sameFingerprint, appendableFingerprint, readHeaderRecords } from './file-io.mjs';
+import { catalogTimestamp, finalizeNouns, applyHeaderRecord } from './metadata.mjs';
+import { readColdMetadataTail, advanceMetadataTail } from './jsonl.mjs';
+import { nativeObjectKeys, nativeInteger } from './native-json.mjs';
+import { nativeTrim } from './text.mjs';
+
+const missing = (error) => error.code === 'ENOENT' || error.code === 'ENOTDIR';
+const string = (value) => typeof value === 'string' ? value : null;
+
+/** Optional means absent, never unreadable. Malformed JSON has the native
+ * empty/default meaning; an unreadable source remains an owner failed part. */
+export async function optionalFile(path, work, metrics) {
+  try { return { path, ...await withSessionFile(path, work, metrics) }; }
+  catch (error) { if (missing(error)) return { path, missing: true, result: null }; throw error; }
+}
+
+export function readSourceJson(path, metrics) {
+  return optionalFile(path, async (reader) => parseJsonLine(await reader.read(0, reader.size), { strictUtf8: true }), metrics);
+}
+
+/** A compound descriptor includes every auxiliary identity, including an
+ * absent optional source. Check them again before returning a commit unit. */
+export async function verifySources(sources) {
+  for (const source of sources) {
+    let info;
+    try { info = await stat(source.path, { bigint: true }); }
+    catch (error) { if (!missing(error)) throw error; }
+    if (source.missing ? info == null : info != null && sameFingerprint(source.fingerprint, fileFingerprint(info))) continue;
+    throw Object.assign(new Error(`${source.path} changed during a compound metadata read; previous index rows are retained`), { code: 'ESTALE' });
+  }
+}
+
+export async function readGeminiProjects(root, metrics) {
+  const source = await readSourceJson(join(root, 'projects.json'), metrics);
+  const object = source.result?.projects, projects = new Map();
+  if (object != null && typeof object === 'object' && !Array.isArray(object)) {
+    // The shipped CLI enables preserve_order, including numeric object keys.
+    for (const cwd of nativeObjectKeys(object)) if (typeof object[cwd] === 'string') projects.set(object[cwd], cwd);
+  }
+  return { source, projects };
+}
+
+async function geminiHeader(reader) {
+  const bytes = await reader.read(0, Math.min(64 * 1024, reader.size));
+  const newline = bytes.indexOf(10), end = newline < 0 ? bytes.length : newline;
+  const header = parseJsonLine(bytes.subarray(0, end), { strictUtf8: true });
+  if (typeof header?.sessionId !== 'string') throw new Error(`${reader.path} has no Gemini sessionId header`);
+  const after = newline < 0 ? bytes.length : newline + 1;
+  const decoration = bytes.subarray(after, Math.min(bytes.length, after + 4 * 1024));
+  let model = null, modelTerminated = false;
+  for (const { line, terminated } of splitLines(decoration)) {
+    let value;
+    try { value = parseJsonLine(line, { strictUtf8: true }); } catch { break; }
+    if (value?.type !== 'user' && value?.type !== 'gemini') continue;
+    model = string(value.model);
+    if (model != null) { modelTerminated = terminated; break; }
+  }
+  const budgetEnded = after + decoration.length >= 64 * 1024 || decoration.length >= 4 * 1024;
+  return { header: { session_id: header.sessionId, model }, header_frozen: (newline >= 0 || bytes.length >= 64 * 1024) && (budgetEnded || (model != null && modelTerminated)) };
+}
+
+function* splitLines(bytes) {
+  let from = 0, end;
+  while ((end = bytes.indexOf(10, from)) >= 0) { yield { line: bytes.subarray(from, end), terminated: true }; from = end + 1; }
+  if (from < bytes.length) yield { line: bytes.subarray(from), terminated: false };
+}
+
+export async function readGemini(path, { projects, previous, metrics } = {}) {
+  if (basename(dirname(path)) !== 'chats') return null;
+  if (!(projects instanceof Map)) throw new Error('Gemini metadata requires its watched projects map');
+  return withSessionFile(path, async (reader) => {
+    const old = previous?.result?.state;
+    const unchanged = sameFingerprint(previous?.fingerprint, reader.fingerprint);
+    const append = old?.appendable && appendableFingerprint(previous?.fingerprint, reader.fingerprint);
+    const head = old && (unchanged || (append && old.header_frozen))
+      ? { header: old.header, header_frozen: old.header_frozen } : await geminiHeader(reader);
+    const tail = unchanged ? old : append ? await advanceMetadataTail(reader, 'gemini', old) : await readColdMetadataTail(reader, 'gemini');
+    const cwd = projects.get(basename(dirname(dirname(path)))) ?? null;
+    return {
+      descriptor: finalizeNouns({ locator: { harness: 'gemini', session_id: head.header.session_id, storage: { kind: 'file', path } },
+        cwd, title: null, model: head.header.model, updated_at_ms: tail.facts.last_turn_ms ?? reader.modified_ms, message_count: null }),
+      state: { ...tail, ...head },
+    };
+  }, metrics);
+}
+
+/** Percent decoding preserves '+' and rejects malformed escapes and UTF-8,
+ * matching the native folder decoder rather than form-url decoding. */
+export function decodeWorkspaceFolder(encoded) {
+  try { return decodeURIComponent(encoded); } catch { return null; }
+}
+
+export async function readGrok(sessionDir, { metrics, previous } = {}) {
+  const cwd = decodeWorkspaceFolder(basename(dirname(sessionDir)));
+  if (cwd == null) return null;
+  const summary = await readSourceJson(join(sessionDir, 'summary.json'), metrics);
+  const path = join(sessionDir, 'chat_history.jsonl');
+  const transcript = await withSessionFile(path, (reader) => {
+    const value = summary.result;
+    const count = nativeInteger(value, 'num_chat_messages');
+    if (count != null && count > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error(`${summary.path} has an inexact native message count`);
+    const title = string(value?.generated_title);
+    return {
+      descriptor: finalizeNouns({ locator: { harness: 'grok', session_id: basename(sessionDir), storage: { kind: 'file', path } },
+        cwd, title: title === '' ? null : title, model: string(value?.current_model_id),
+        updated_at_ms: catalogTimestamp(value?.updated_at) ?? reader.modified_ms,
+        message_count: count == null ? null : Number(count) }),
+      state: previous?.result?.state ?? {},
+    };
+  }, metrics);
+  await verifySources([summary]);
+  return { ...transcript, sources: [summary] };
+}
+
+async function nativeStoreHeader(reader) {
+  const result = { session_id: null, cwd: null, model: null, title: null, topic: null, parent_session_id: null, trigger: null };
+  let source = null;
+  const records = await readHeaderRecords(reader);
+  for (const value of records) {
+    if (source == null) {
+      source = string(value?.source);
+      if (source === 'claude_code') source = 'claude-code';
+      result.session_id ??= string(value?.session_id);
+    }
+    if (source != null) applyHeaderRecord(result, value, source);
+    if (result.cwd != null && result.model != null) break;
+  }
+  return { header: result, header_frozen: records.scan.terminated && (records.scan.exhausted || (result.cwd != null && result.model != null)) };
+}
+
+async function nativeStoreFile(path, previous, metrics, { header: wantHeader = true, tail: wantTail = true } = {}) {
+  return optionalFile(path, async (reader) => {
+    const unchanged = sameFingerprint(previous?.fingerprint, reader.fingerprint);
+    const old = previous?.result?.state;
+    if (unchanged && (!wantTail || old?.tail_read) && (!wantHeader || previous.result?.header_read)) return previous.result;
+    const append = old?.appendable && appendableFingerprint(previous?.fingerprint, reader.fingerprint);
+    const tail = unchanged && old?.tail_read ? old : wantTail
+      ? append ? await advanceMetadataTail(reader, 'supercode', old) : await readColdMetadataTail(reader, 'supercode')
+      : { facts: { last_turn_ms: null }, offset: reader.size, trailing: '', appendable: false };
+    const retainHead = previous?.result?.header_read && (unchanged || (append && old.header_frozen));
+    const head = retainHead ? { header: previous.result.header, header_frozen: old.header_frozen }
+      : wantHeader ? await nativeStoreHeader(reader) : { header: null, header_frozen: false };
+    return { header: head.header, header_read: retainHead || wantHeader,
+      state: { ...tail, tail_read: Boolean(wantTail || (unchanged && old?.tail_read)), header_frozen: head.header_frozen } };
+  }, metrics);
+}
+
+async function optionalStat(path) {
+  let info;
+  try { info = await stat(path, { bigint: true }); }
+  catch (error) { if (missing(error)) return { path, missing: true, result: null }; throw error; }
+  return { path, file: info.isFile(), fingerprint: fileFingerprint(info), result: null,
+    modified_ms: info.isFile() && info.mtimeNs >= 0n ? Number(info.mtimeNs / 1_000_000n) : null };
+}
+
+/** A .meta.json owns the native name/title. The sidecar owns the header and
+ * first-choice turn clock; the locator names the transcript while it exists,
+ * otherwise the surviving sidecar. No reduction content is translated here. */
+export async function readSupercode(metaPath, root, { previous, metrics } = {}) {
+  const meta = await readSourceJson(metaPath, metrics);
+  const info = meta.result;
+  if (typeof info?.name !== 'string' || (info.title !== undefined && typeof info.title !== 'string')) return { descriptor: null, sources: [meta] };
+  const archived = resolve(dirname(metaPath)) !== resolve(root);
+  const name = `${info.name}.jsonl`, base = archived ? join(root, 'archived') : root;
+  const path = isAbsolute(name) ? name : join(base, name);
+  const sidecarPath = path.slice(0, -'.jsonl'.length) + '.sidecar.jsonl';
+  const previousByPath = new Map((previous?.sources ?? []).map((source) => [source.path, source]));
+  const transcriptInfo = await optionalStat(path);
+  // Preserve read_native_store_header_as's existing filename rule: when the
+  // locator is itself a sidecar, its adjacent authoritative sidecar has the
+  // doubled suffix. The usual case has no doubled file and uses the locator.
+  const doubledPath = sidecarPath.slice(0, -'.jsonl'.length) + '.sidecar.jsonl';
+  const doubled = transcriptInfo.file ? null : await nativeStoreFile(doubledPath, previousByPath.get(doubledPath), metrics, { tail: false });
+  const sidecar = await nativeStoreFile(sidecarPath, previousByPath.get(sidecarPath), metrics, { header: doubled == null || doubled.missing });
+  const transcript = !transcriptInfo.file || (!sidecar.missing && sidecar.result?.state.facts.last_turn_ms != null) ? transcriptInfo
+    : await nativeStoreFile(path, previousByPath.get(path), metrics, { header: sidecar.missing, tail: sidecar.result?.state.facts.last_turn_ms == null });
+  const files = [meta, transcriptInfo, sidecar, transcript, ...(doubled ? [doubled] : [])];
+  await verifySources(files);
+  const content = doubled && !doubled.missing ? doubled : sidecar.missing ? transcript : sidecar;
+  const header = content.result?.header;
+  return {
+    descriptor: finalizeNouns({ locator: { harness: 'supercode', session_id: info.name, storage: { kind: 'file', path: transcriptInfo.file ? path : sidecarPath } },
+      cwd: header?.cwd ?? null, title: info.title != null && nativeTrim(info.title) ? info.title : null, model: header?.model ?? null,
+      updated_at_ms: sidecar.result?.state.facts.last_turn_ms ?? transcript.result?.state.facts.last_turn_ms ?? transcript.modified_ms ?? sidecar.modified_ms ?? null,
+      message_count: null }),
+    sources: [...new Map(files.map((source) => [source.path, source])).values()],
+  };
+}

package/source-layout.mjs

@@ -0,0 +1,92 @@
+import { realpath } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { sourceEntries, sourceStat } from './store-registry.mjs';
+import { readCompressedCodex, refreshUncompressedJsonl } from './jsonl.mjs';
+import { readGemini, readGrok, readSupercode } from './source-files.mjs';
+import { readOpenClaw } from './openclaw.mjs';
+
+export const FILE_HARNESSES = Object.freeze(['claude-code', 'codex', 'pi', 'openclaw', 'grok', 'gemini', 'supercode']);
+export const STORE_HARNESSES = Object.freeze(['opencode', 'goose', 'hermes', 'orchestrator']);
+
+/** Resolve existing ancestors too, so an absent root and its later creation
+ * use the same physical path as platform watch events. Refused metadata is
+ * not interpreted as absence. */
+export async function normalizedSourcePath(path) {
+  let at = resolve(path), rest = [];
+  for (;;) {
+    try { return join(await realpath(at), ...rest.reverse()); }
+    catch (error) { if (!['ENOENT', 'ENOTDIR'].includes(error.code)) throw error; }
+    const parent = dirname(at);
+    if (parent === at) return resolve(path);
+    rest.push(basename(at)); at = parent;
+  }
+}
+
+export function pathUnder(root, path) {
+  const part = relative(root, path);
+  return part === '' || (!isAbsolute(part) && part !== '..' && !part.startsWith(`..${sep}`));
+}
+
+export function fileRoot(harness, homes) {
+  return FILE_HARNESSES.includes(harness) ? homes[harness === 'claude-code' ? 'claude_code' : harness] : null;
+}
+
+/** The key is the file that owns a metadata read, not every adjacent file
+ * whose event can invalidate it. Supercode's meta file owns its saved name. */
+export async function sessionPartFor(harness, root, path) {
+  const name = basename(path);
+  if (harness === 'claude-code' || harness === 'pi') return name.endsWith('.jsonl') ? path : null;
+  if (harness === 'codex') return name.endsWith('.jsonl') || name.endsWith('.jsonl.zst') ? path : null;
+  if (harness === 'openclaw') return name.endsWith('.jsonl') && !name.endsWith('.trajectory.jsonl') ? path : null;
+  if (harness === 'gemini') return name.endsWith('.jsonl') && pathUnder(join(root, 'tmp'), path) ? path : null;
+  if (harness === 'grok') {
+    const part = relative(root, path).split(sep);
+    return pathUnder(root, path) && part.length >= 3 ? join(root, part[0], part[1], 'chat_history.jsonl') : null;
+  }
+  if (harness === 'supercode' && [root, join(root, 'archived')].includes(dirname(path))) {
+    const suffix = ['.meta.json', '.sidecar.jsonl', '.jsonl'].find((ending) => name.endsWith(ending));
+    return suffix ? join(dirname(path), `${name.slice(0, -suffix.length)}.meta.json`) : null;
+  }
+  return null;
+}
+
+/** The owner installs each directory watch before its listing. A refused
+ * child refuses this listing as a whole; its previously held rows stand.
+ * Following real directory identities ends symlink cycles. */
+export async function listSessionParts(harness, root, { folder = root, beforeDirectory = async () => {}, metrics = {} } = {}) {
+  const walked = new Set(), parts = new Set(), directories = new Set();
+  async function visit(dir) {
+    const info = await sourceStat(dir);
+    if (!info?.isDirectory()) return;
+    const real = await normalizedSourcePath(dir);
+    if (walked.has(real)) return;
+    walked.add(real); directories.add(real);
+    await beforeDirectory(real);
+    metrics.directories_listed = (metrics.directories_listed ?? 0) + 1;
+    for (const name of await sourceEntries(dir)) {
+      const path = join(dir, name), entry = await sourceStat(path);
+      if (entry?.isDirectory()) await visit(path);
+      else if (entry?.isFile()) {
+        const part = await sessionPartFor(harness, root, await normalizedSourcePath(path));
+        if (part != null) parts.add(part);
+      }
+    }
+  }
+  await visit(folder);
+  return { parts, directories };
+}
+
+/** All readers return one cache/descriptor unit. Cache identities and offsets
+ * are committed beside the descriptor by the daemon, never by this library. */
+export async function readFileMetadata(harness, root, path, { previous, projects, nativeTopic, metrics = {} } = {}) {
+  let cache;
+  if (['claude-code', 'codex', 'pi'].includes(harness)) cache = harness === 'codex' && path.endsWith('.zst')
+    ? await readCompressedCodex(path, { nativeTopic, metrics, previous })
+    : await refreshUncompressedJsonl(path, harness, previous, { nativeTopic, metrics });
+  else if (harness === 'openclaw') cache = await readOpenClaw(path, { previous, metrics });
+  else if (harness === 'gemini') cache = await readGemini(path, { previous, projects, metrics });
+  else if (harness === 'grok') cache = await readGrok(dirname(path), { previous, metrics });
+  else if (harness === 'supercode') cache = await readSupercode(path, root, { previous, metrics });
+  else throw new Error(`no file metadata reader for ${harness}`);
+  return { descriptor: cache?.result?.descriptor ?? cache?.descriptor ?? null, cache };
+}

package/sqlite-reader.mjs

@@ -0,0 +1,75 @@
+import { DatabaseSync } from 'node:sqlite';
+import { fileFingerprint } from './file-io.mjs';
+import { sourceStat } from './store-registry.mjs';
+import { verifySources } from './source-files.mjs';
+import { parseNativeJson } from './native-json.mjs';
+
+/** Only DB and WAL mutations affect the stored read mark. SHM is SQLite's
+ * reader coordination file and never schedules transcript/index work. */
+export async function storeFingerprints(path) {
+  const sources = [];
+  for (const file of [path, `${path}-wal`]) {
+    const info = await sourceStat(file);
+    sources.push(info ? { path: file, fingerprint: fileFingerprint(info) } : { path: file, missing: true });
+  }
+  return sources;
+}
+
+/** One read-only connection and one synchronous snapshot. A changed DB/WAL
+ * refuses the commit unit, leaving the owner's prior rows and retry visible.
+ * No foreign writer, journal-mode setter or extension loading is permitted. */
+export async function readStore(path, work, metrics = {}) {
+  const sources = await storeFingerprints(path);
+  if (sources[0].missing) throw Object.assign(new Error(`${path} is not present`), { code: 'ENOENT' });
+  const db = new DatabaseSync(path, { readOnly: true, allowExtension: false });
+  metrics.stores_read = (metrics.stores_read ?? 0) + 1;
+  let result;
+  try {
+    db.exec('PRAGMA busy_timeout=0; BEGIN');
+    result = work(db);
+    if (result != null && typeof result.then === 'function') throw new Error('a foreign-store snapshot must be synchronous');
+    db.exec('COMMIT');
+  } finally { db.close(); }
+  await verifySources(sources);
+  return { result, sources };
+}
+
+export function statement(db, sql) {
+  const prepared = db.prepare(sql);
+  prepared.setReadBigInts(true);
+  return prepared;
+}
+
+export function tableColumns(db, table) {
+  // Callers provide only these fixed native schema identifiers.
+  if (!['session', 'sessions', 'messages'].includes(table)) throw new Error('unknown catalog schema table');
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((row) => row.name));
+}
+
+export function text(value, nullable = false) {
+  if (nullable && value == null) return null;
+  if (typeof value !== 'string') throw new Error('foreign session store returned a non-text native column');
+  return value;
+}
+
+export function unsigned(value) {
+  if (value == null) return null;
+  if (typeof value !== 'bigint' && !Number.isSafeInteger(value)) throw new Error('foreign session store returned a non-integer native column');
+  if (value < 0) return null;
+  const number = Number(value);
+  if (!Number.isSafeInteger(number)) throw new Error('foreign session integer exceeds the exact Node wire range');
+  return number;
+}
+
+export function integer(value, nullable = false) {
+  if (nullable && value == null) return null;
+  // Every prepared native-column statement uses setReadBigInts. A Number is
+  // a SQLite REAL even when numerically integral; rusqlite's i64 read refuses it.
+  if (typeof value !== 'bigint') throw new Error('foreign session store returned a non-INTEGER native column');
+  return value;
+}
+
+export function jsonColumn(value) {
+  if (typeof value !== 'string') return null;
+  try { return parseNativeJson(value); } catch { return null; }
+}