@ngockhoale/ukit 3.0.6 → 3.0.8

package/src/core/observability/schema/registry.js

@@ -0,0 +1,223 @@
+// Frozen semantic-name + reason-code registry — SPEC §5 DF-FR03, §7.
+//
+// Lifecycle: entries are append-only. A breaking semantic change (renamed
+// meaning, changed unit, narrowed privacy) requires a NEW name or a new
+// SCHEMA_VERSION major — never an in-place edit of an existing entry.
+// `introduced_version` records the schema version that first defined the
+// entry; the registry test asserts it on every entry so later additions are
+// always new, dated entries.
+//
+// `privacy_class` is the default ceiling for the semantic name; a record's
+// own `privacy_class` may raise it (e.g. a trace carrying user content) but
+// sanitizers treat the registry value as the floor of scrutiny.
+
+import { PRIVACY_CLASSES } from './constants.js';
+
+const V1 = '1';
+
+export const SEMANTIC_REGISTRY = Object.freeze({
+  'execution.started': {
+    definition: 'An execution unit (task/episode) began. Span root for the execution.',
+    privacy_class: 'internal',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+  'execution.completed': {
+    definition: 'An execution unit finished successfully. Payload carries outcome and duration.',
+    privacy_class: 'internal',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+  'execution.failed': {
+    definition: 'An execution unit terminated with failure. Payload carries error_code.',
+    privacy_class: 'internal',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+  'execution.blocked': {
+    definition: 'An execution unit stopped on an unmet precondition or gate.',
+    privacy_class: 'internal',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+  'tool.started': {
+    definition: 'A tool invocation began. Payload may name the tool; arguments stay redacted.',
+    privacy_class: 'sensitive',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+  'tool.completed': {
+    definition: 'A tool invocation finished. Payload carries duration; output stays redacted.',
+    privacy_class: 'sensitive',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+  'tool.failed': {
+    definition: 'A tool invocation failed. Payload carries error_code; stderr stays redacted.',
+    privacy_class: 'sensitive',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+  'model.started': {
+    definition: 'A model attempt began. Payload carries attempt_index.',
+    privacy_class: 'internal',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+  'model.completed': {
+    definition: 'A model attempt finished. Payload carries duration and typed resource usage.',
+    privacy_class: 'internal',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+  'model.failed': {
+    definition: 'A model attempt failed. Payload carries error_code and typed resource usage.',
+    privacy_class: 'internal',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+  'cache.hit': {
+    definition: 'A cache lookup resolved from cache. Payload identifies the cache seam, not content.',
+    privacy_class: 'internal',
+    retention_hint: 'aggregate',
+    introduced_version: V1,
+  },
+  'cache.miss': {
+    definition: 'A cache lookup did not resolve from cache.',
+    privacy_class: 'internal',
+    retention_hint: 'aggregate',
+    introduced_version: V1,
+  },
+  'verification.completed': {
+    definition: 'A verification step ran to completion. Payload carries the verdict, not raw output.',
+    privacy_class: 'internal',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+  'context.item.injected': {
+    definition: 'A context item (e.g. user correction) entered the episode. Kind only, never content.',
+    privacy_class: 'sensitive',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+  'decision.made': {
+    definition: 'An optimization or routing decision was recorded with experiment provenance.',
+    privacy_class: 'internal',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+  'telemetry.dropped': {
+    definition: 'Telemetry records were dropped or sampled. Payload carries reason_code and count.',
+    privacy_class: 'internal',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+  'telemetry.recovered': {
+    definition: 'Previously incomplete telemetry recovered (e.g. partial tail repaired).',
+    privacy_class: 'internal',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+  'telemetry.redacted': {
+    definition: 'A record or field was redacted before persistence. Payload carries the field path.',
+    privacy_class: 'internal',
+    retention_hint: 'retain',
+    introduced_version: V1,
+  },
+});
+
+// Error/wait/reason vocabulary: codes + definitions, no free-text grouping.
+// Used by payload.error_code, payload.reason_code and payload.wait_code.
+export const REASON_CODES = Object.freeze({
+  TOOL_TIMEOUT: {
+    definition: 'A tool or model call exceeded its deadline.',
+    introduced_version: V1,
+  },
+  AUTH_FAILED: {
+    definition: 'Authentication or authorization was rejected by the provider.',
+    introduced_version: V1,
+  },
+  RATE_LIMITED: {
+    definition: 'The provider or host throttled the request.',
+    introduced_version: V1,
+  },
+  MODEL_ERROR: {
+    definition: 'The model endpoint returned an error response.',
+    introduced_version: V1,
+  },
+  NETWORK_ERROR: {
+    definition: 'A transport-level failure prevented the call.',
+    introduced_version: V1,
+  },
+  QUEUE_OVERFLOW: {
+    definition: 'The emit queue exceeded its bound; records were dropped.',
+    introduced_version: V1,
+  },
+  SAMPLED_OUT: {
+    definition: 'The record was excluded by the configured sampling policy.',
+    introduced_version: V1,
+  },
+  HOST_BLIND: {
+    definition: 'The host does not expose the field; value stays explicitly unknown.',
+    introduced_version: V1,
+  },
+  FLUSH_FAILED: {
+    definition: 'A recorder flush could not persist its batch; user task unaffected.',
+    introduced_version: V1,
+  },
+  DISK_FULL: {
+    definition: 'The storage volume rejected a write for lack of space.',
+    introduced_version: V1,
+  },
+  PERMISSION_DENIED: {
+    definition: 'The filesystem or OS denied the operation.',
+    introduced_version: V1,
+  },
+  SCHEMA_MISMATCH: {
+    definition: 'A record or bundle failed schema validation.',
+    introduced_version: V1,
+  },
+  CHECKSUM_MISMATCH: {
+    definition: 'A segment or bundle digest did not match its manifest.',
+    introduced_version: V1,
+  },
+  PARTIAL_TAIL: {
+    definition: 'A segment ended mid-record; the tail was truncated on recovery.',
+    introduced_version: V1,
+  },
+  ROTATED: {
+    definition: 'A segment was rotated out by retention or cap policy.',
+    introduced_version: V1,
+  },
+  REDACTED_FIELD: {
+    definition: 'A payload field was removed by the privacy gate before persistence.',
+    introduced_version: V1,
+  },
+  USER_CANCELLED: {
+    definition: 'The user aborted the operation.',
+    introduced_version: V1,
+  },
+  GATE_BLOCKED: {
+    definition: 'A completion or security gate stopped the execution.',
+    introduced_version: V1,
+  },
+  WAITING_ON_TOOL: {
+    definition: 'The span is waiting on a tool result.',
+    introduced_version: V1,
+  },
+  WAITING_ON_MODEL: {
+    definition: 'The span is waiting on a model response.',
+    introduced_version: V1,
+  },
+  WAITING_ON_USER: {
+    definition: 'The span is waiting on user input.',
+    introduced_version: V1,
+  },
+});
+
+// Guard: registry privacy classes must stay inside the frozen vocabulary.
+for (const [name, entry] of Object.entries(SEMANTIC_REGISTRY)) {
+  if (!PRIVACY_CLASSES.includes(entry.privacy_class)) {
+    throw new Error(`semantic registry entry ${name} has unknown privacy_class ${entry.privacy_class}`);
+  }
+}

package/src/core/observability/schema/validate.js

@@ -0,0 +1,227 @@
+// validateSemanticRecord — SPEC §8 contract.
+//
+//   validateSemanticRecord(record, context?) → { ok: boolean, errors: string[] }
+//
+// Validates one semantic envelope against SCHEMA_VERSION 1. Never throws:
+// malformed input returns { ok: false, errors }. Unknown optional fields are
+// tolerated (DF-FR03); unknown REQUIRED-field values (schema_version,
+// record_type, semantic_name, vocabularies) are rejected.
+//
+// `context` is optional cross-record state for stream validation:
+//   { knownSpanIds?: Set<string>, seenSequences?: Set<string> }
+// knownSpanIds holds span_ids already observed in the trace; seenSequences
+// holds `${boot_id}|${writer_id}|${sequence}` keys. The validator only READS
+// context — callers add the record's own span/sequence after accepting it.
+// Without context, per-record checks still run; cross-record checks are
+// skipped rather than invented (the validator never fabricates causality).
+
+import {
+  SCHEMA_VERSION,
+  REQUIRED_ENVELOPE_FIELDS,
+  RECORD_TYPES,
+  PRIVACY_CLASSES,
+  IMPORTANCE_LEVELS,
+  RESOURCE_SOURCES,
+  CONFIDENCE_TYPES,
+} from './constants.js';
+import { SEMANTIC_REGISTRY, REASON_CODES } from './registry.js';
+
+const OPTIONAL_ID_FIELDS = ['trace_id', 'span_id', 'parent_span_id', 'execution_id', 'session_id', 'project_ref'];
+const REASON_CODE_FIELDS = ['error_code', 'reason_code', 'wait_code'];
+const ISO_8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function validateOrigin(record, errors) {
+  const origin = record.origin;
+  switch (record.record_type) {
+    case 'fact':
+      // Observed facts carry no provenance origin; an origin field, if present,
+      // must still be an object so downstream readers can rely on its shape.
+      if (origin !== undefined && origin !== null && !isPlainObject(origin)) {
+        errors.push('origin must be an object when present');
+      }
+      return;
+    case 'derived':
+      if (!isPlainObject(origin)) {
+        errors.push('record_type "derived" requires origin with derived_from');
+        return;
+      }
+      if (!Array.isArray(origin.derived_from) || origin.derived_from.length === 0) {
+        errors.push('origin.derived_from must be a non-empty array of source record refs');
+      }
+      return;
+    case 'evaluation':
+      if (!isPlainObject(origin)) {
+        errors.push('record_type "evaluation" requires origin with evaluator and confidence');
+        return;
+      }
+      if (!isNonEmptyString(origin.evaluator)) {
+        errors.push('origin.evaluator must name the evaluator that produced the judgment');
+      }
+      if (!CONFIDENCE_TYPES.includes(origin.confidence)) {
+        errors.push(`origin.confidence must be one of ${CONFIDENCE_TYPES.join('|')} (got ${JSON.stringify(origin.confidence)})`);
+      }
+      return;
+    case 'decision':
+      if (!isPlainObject(origin)) {
+        errors.push('record_type "decision" requires origin with experiment provenance');
+        return;
+      }
+      if (!isNonEmptyString(origin.experiment)) {
+        errors.push('origin.experiment must reference the experiment the decision belongs to');
+      }
+      return;
+    default:
+      return;
+  }
+}
+
+function validatePayload(payload, errors) {
+  if (payload.resource !== undefined && payload.resource !== null) {
+    const resource = payload.resource;
+    if (!isPlainObject(resource)) {
+      errors.push('payload.resource must be an object {value, source}');
+    } else {
+      if (!RESOURCE_SOURCES.includes(resource.source)) {
+        errors.push(`payload.resource.source must be one of ${RESOURCE_SOURCES.join('|')} (got ${JSON.stringify(resource.source)})`);
+      }
+      if (resource.value !== null && resource.value !== undefined && typeof resource.value !== 'number') {
+        errors.push('payload.resource.value must be a number or null (null only with source UNKNOWN)');
+      }
+      if (typeof resource.value === 'number' && resource.source === 'UNKNOWN') {
+        errors.push('payload.resource.value must be null when source is UNKNOWN — unknown is never 0');
+      }
+    }
+  }
+  for (const field of REASON_CODE_FIELDS) {
+    const code = payload[field];
+    if (code !== undefined && code !== null && !REASON_CODES[code]) {
+      errors.push(`payload.${field} ${JSON.stringify(code)} is not in the reason-code registry`);
+    }
+  }
+  if (payload.confidence !== undefined && !CONFIDENCE_TYPES.includes(payload.confidence)) {
+    errors.push(`payload.confidence must be one of ${CONFIDENCE_TYPES.join('|')}`);
+  }
+  if (payload.telemetry_complete !== undefined && typeof payload.telemetry_complete !== 'boolean') {
+    errors.push('payload.telemetry_complete must be a boolean');
+  }
+}
+
+export function validateSemanticRecord(record, context) {
+  const errors = [];
+
+  if (!isPlainObject(record)) {
+    return { ok: false, errors: ['record must be a plain object'] };
+  }
+
+  for (const field of REQUIRED_ENVELOPE_FIELDS) {
+    if (record[field] === undefined || record[field] === null) {
+      errors.push(`missing required field: ${field}`);
+    }
+  }
+  // Bail early on missing requireds — type checks below assume presence.
+  if (errors.length > 0) {
+    return { ok: false, errors };
+  }
+
+  if (!Number.isInteger(record.schema_version)) {
+    errors.push('schema_version must be an integer');
+  } else if (record.schema_version !== SCHEMA_VERSION) {
+    errors.push(`unsupported schema version: ${record.schema_version} (supported: ${SCHEMA_VERSION})`);
+  }
+
+  if (!RECORD_TYPES.includes(record.record_type)) {
+    errors.push(`record_type must be one of ${RECORD_TYPES.join('|')} (got ${JSON.stringify(record.record_type)})`);
+  }
+
+  if (!isNonEmptyString(record.semantic_name)) {
+    errors.push('semantic_name must be a non-empty string');
+  } else if (!SEMANTIC_REGISTRY[record.semantic_name]) {
+    errors.push(`unknown semantic name: ${record.semantic_name}`);
+  }
+
+  if (!isNonEmptyString(record.record_id)) errors.push('record_id must be a non-empty string');
+  if (!isNonEmptyString(record.boot_id)) errors.push('boot_id must be a non-empty string');
+  if (!isNonEmptyString(record.writer_id)) errors.push('writer_id must be a non-empty string');
+
+  if (!Number.isInteger(record.sequence) || record.sequence < 0) {
+    errors.push('sequence must be a non-negative integer');
+  }
+
+  // Strict ISO-8601 (RFC 3339 profile) — Date.parse alone accepts non-ISO
+  // strings like 'Jan 1, 2026', which would diverge from the JSON-schema
+  // mirror's `format: date-time`.
+  if (typeof record.wall_time_utc !== 'string'
+    || !ISO_8601_RE.test(record.wall_time_utc)
+    || Number.isNaN(Date.parse(record.wall_time_utc))) {
+    errors.push('wall_time_utc must be an ISO-8601 timestamp string');
+  }
+
+  if (record.monotonic_ns !== undefined && record.monotonic_ns !== null) {
+    if (typeof record.monotonic_ns !== 'number' || !Number.isFinite(record.monotonic_ns) || record.monotonic_ns < 0) {
+      errors.push('monotonic_ns must be a non-negative number when present');
+    }
+  }
+
+  if (!IMPORTANCE_LEVELS.includes(record.importance)) {
+    errors.push(`importance must be one of ${IMPORTANCE_LEVELS.join('|')} (got ${JSON.stringify(record.importance)})`);
+  }
+  if (!PRIVACY_CLASSES.includes(record.privacy_class)) {
+    errors.push(`privacy_class must be one of ${PRIVACY_CLASSES.join('|')} (got ${JSON.stringify(record.privacy_class)})`);
+  } else {
+    // Registry privacy floor: a record may raise (restrict) its class above
+    // the registry entry's rank but never lower it — sanitizers treat the
+    // registry value as the floor of scrutiny.
+    const entry = SEMANTIC_REGISTRY[record.semantic_name];
+    if (entry && PRIVACY_CLASSES.indexOf(record.privacy_class) < PRIVACY_CLASSES.indexOf(entry.privacy_class)) {
+      errors.push(`privacy_class ${JSON.stringify(record.privacy_class)} is below the registry floor ${entry.privacy_class} for ${record.semantic_name}`);
+    }
+  }
+
+  for (const field of OPTIONAL_ID_FIELDS) {
+    const value = record[field];
+    if (value !== undefined && value !== null && typeof value !== 'string') {
+      errors.push(`${field} must be a string or null`);
+    }
+  }
+
+  if (!isPlainObject(record.payload)) {
+    errors.push('payload must be an object');
+  } else {
+    validatePayload(record.payload, errors);
+  }
+
+  if (RECORD_TYPES.includes(record.record_type)) {
+    validateOrigin(record, errors);
+  }
+
+  // Cross-record checks — only when the caller supplies stream context.
+  if (context) {
+    const parent = record.parent_span_id;
+    if (typeof parent === 'string' && parent.length > 0) {
+      // A parent link is a causality claim: it needs monotonic evidence —
+      // wall_time_utc alone never orders records across writers/clocks.
+      if (record.monotonic_ns === undefined || record.monotonic_ns === null) {
+        errors.push('parent_span_id asserts causality but monotonic_ns is absent — wall time alone cannot order records');
+      }
+      if (context.knownSpanIds && !context.knownSpanIds.has(parent)) {
+        errors.push(`orphan parent_span_id: ${parent} not observed in this trace`);
+      }
+    }
+    if (context.seenSequences && Number.isInteger(record.sequence)) {
+      const key = `${record.boot_id}|${record.writer_id}|${record.sequence}`;
+      if (context.seenSequences.has(key)) {
+        errors.push(`duplicate sequence ${record.sequence} for writer ${record.writer_id} boot ${record.boot_id}`);
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}

package/src/core/observability/segments/internal.js

@@ -0,0 +1,241 @@
+/**
+ * internal.js (TASK-006) — shared helpers for the segment store.
+ *
+ * Not part of the SPEC §8 public surface. Owns: on-disk layout constants,
+ * bounded-IO wrapper, path-safety resolution, state file, checksums, and
+ * segment enumeration. Public modules: readSegments.js, recovery.js,
+ * retention.js.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const ACTIVE_FILE = 'active.jsonl';
+export const STATE_FILE = '_state.json';
+export const QUARANTINE_DIR = 'quarantine';
+export const SEALED_RE = /^seg-(\d+)-([A-Za-z0-9_-]+)-([A-Za-z0-9_-]+)\.jsonl$/;
+
+export const DEFAULT_IO_TIMEOUT_MS = 5000;
+
+export const DEFAULT_POLICY = Object.freeze({
+  maxSegmentBytes: 8 * 1024 * 1024,
+  maxSegmentAgeMs: 24 * 60 * 60 * 1000,
+  maxTotalBytes: 256 * 1024 * 1024,
+  ioTimeoutMs: DEFAULT_IO_TIMEOUT_MS,
+});
+
+export function policyOf(policy) {
+  return { ...DEFAULT_POLICY, ...(policy || {}) };
+}
+
+export function nowOf(policy) {
+  return policy && Number.isFinite(policy.now) ? policy.now : Date.now();
+}
+
+export function ioTimeoutMsOf(policy) {
+  const v = policy && policy.ioTimeoutMs;
+  return Number.isFinite(v) ? v : DEFAULT_IO_TIMEOUT_MS;
+}
+
+/** Bounded IO: rejects with { code: 'IO_TIMEOUT' } after ms. ms <= 0 → immediate. */
+export function withTimeout(promise, ms) {
+  if (ms <= 0) {
+    return Promise.reject(Object.assign(new Error('io timeout'), { code: 'IO_TIMEOUT' }));
+  }
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(Object.assign(new Error('io timeout'), { code: 'IO_TIMEOUT' }));
+    }, ms);
+    if (timer.unref) timer.unref();
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+/** Map an fs/timeout error to a static reason code. */
+export function ioReason(err) {
+  if (err && err.code === 'IO_TIMEOUT') return 'io_timeout';
+  const code = err && err.code ? String(err.code).toLowerCase() : 'io_error';
+  return `io_${code}`;
+}
+
+/** True when a raw path string carries a '..' segment. */
+export function hasTraversal(rawPath) {
+  return String(rawPath).split(/[\\/]+/).includes('..');
+}
+
+/**
+ * Resolve a storage root safely.
+ *  - rejects '..' segments outright (unsafe_root)
+ *  - resolves symlinks; the real path must stay inside the real parent dir,
+ *    so a symlinked root cannot escape its storage location
+ *  - missing root is fine (exists:false) — callers create or treat as empty
+ *
+ * → { ok: true, root, exists } | { ok: false, reason }
+ */
+export async function resolveRoot(root, timeoutMs = DEFAULT_IO_TIMEOUT_MS) {
+  if (typeof root !== 'string' || root.length === 0) {
+    return { ok: false, reason: 'unsafe_root' };
+  }
+  if (hasTraversal(root)) {
+    return { ok: false, reason: 'unsafe_root' };
+  }
+  const resolved = path.resolve(root);
+  const parent = path.dirname(resolved);
+  let parentReal;
+  try {
+    parentReal = await withTimeout(fs.promises.realpath(parent), timeoutMs);
+  } catch (err) {
+    return { ok: false, reason: ioReason(err) };
+  }
+  let real;
+  try {
+    real = await withTimeout(fs.promises.realpath(resolved), timeoutMs);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return { ok: true, root: resolved, exists: false };
+    }
+    return { ok: false, reason: ioReason(err) };
+  }
+  // realpath canonicalizes the parent too (e.g. /var → /private/var on macOS),
+  // so containment is checked against the real parent, not the literal path.
+  if (real !== path.join(parentReal, path.basename(resolved))) {
+    return { ok: false, reason: 'unsafe_root' };
+  }
+  return { ok: true, root: real, exists: true };
+}
+
+/**
+ * Resolve an existing file inside its directory with the same containment
+ * rule as resolveRoot. → { ok: true, path } | { ok: false, reason }
+ */
+export async function resolveFileInDir(filePath, timeoutMs = DEFAULT_IO_TIMEOUT_MS) {
+  if (typeof filePath !== 'string' || filePath.length === 0 || hasTraversal(filePath)) {
+    return { ok: false, reason: 'unsafe_path' };
+  }
+  const resolved = path.resolve(filePath);
+  const parent = path.dirname(resolved);
+  let parentReal;
+  try {
+    parentReal = await withTimeout(fs.promises.realpath(parent), timeoutMs);
+  } catch (err) {
+    return { ok: false, reason: ioReason(err) };
+  }
+  let real;
+  try {
+    real = await withTimeout(fs.promises.realpath(resolved), timeoutMs);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { ok: false, reason: 'not_found' };
+    return { ok: false, reason: ioReason(err) };
+  }
+  if (real !== path.join(parentReal, path.basename(resolved))) {
+    return { ok: false, reason: 'unsafe_path' };
+  }
+  return { ok: true, path: real };
+}
+
+export function metaPathFor(segmentPath) {
+  return segmentPath.replace(/\.jsonl$/, '.meta.json');
+}
+
+export function sha256Buffer(buf) {
+  return 'sha256:' + crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+const STATE_DEFAULTS = Object.freeze({
+  next_segment_seq: 1,
+  expired_segments: 0,
+  quarantined_segments: 0,
+  disabled: false,
+  active_since_ms: null,
+});
+
+/** Best-effort state read; corrupt/missing state degrades to defaults. */
+export async function readState(root, timeoutMs = DEFAULT_IO_TIMEOUT_MS) {
+  try {
+    const raw = await withTimeout(fs.promises.readFile(path.join(root, STATE_FILE), 'utf8'), timeoutMs);
+    const parsed = JSON.parse(raw);
+    return { ...STATE_DEFAULTS, ...(parsed && typeof parsed === 'object' ? parsed : {}) };
+  } catch {
+    return { ...STATE_DEFAULTS };
+  }
+}
+
+export async function writeState(root, state, timeoutMs = DEFAULT_IO_TIMEOUT_MS) {
+  try {
+    await withTimeout(
+      fs.promises.writeFile(path.join(root, STATE_FILE), JSON.stringify(state, null, 2)),
+      timeoutMs,
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function sanitizeNameComponent(value) {
+  const s = typeof value === 'string' && value.length > 0 ? value : 'unknown';
+  return s.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 64) || 'unknown';
+}
+
+/**
+ * Enumerate the segment directory.
+ * → { ok: true, sealed: [{ name, seq, path, size }], active: { path, size } | null,
+ *     skipped: [{ name, reason }] }
+ *   | { ok: false, reason }
+ * Symlinks are never followed — reported as skipped. Foreign .jsonl files that
+ * match neither the active nor sealed naming scheme are skipped, never read.
+ */
+export async function listSegments(root, timeoutMs = DEFAULT_IO_TIMEOUT_MS) {
+  let entries;
+  try {
+    entries = await withTimeout(fs.promises.readdir(root, { withFileTypes: true }), timeoutMs);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { ok: true, sealed: [], active: null, skipped: [] };
+    return { ok: false, reason: ioReason(err) };
+  }
+  const sealed = [];
+  const skipped = [];
+  let active = null;
+  for (const entry of entries) {
+    const name = entry.name;
+    if (name === QUARANTINE_DIR || name === STATE_FILE || name.endsWith('.meta.json')) continue;
+    if (!name.endsWith('.jsonl')) continue;
+    if (entry.isSymbolicLink()) {
+      skipped.push({ name, reason: 'symlink_skipped' });
+      continue;
+    }
+    if (!entry.isFile()) {
+      skipped.push({ name, reason: 'not_regular_file' });
+      continue;
+    }
+    const full = path.join(root, name);
+    let size = 0;
+    try {
+      size = (await withTimeout(fs.promises.stat(full), timeoutMs)).size;
+    } catch {
+      skipped.push({ name, reason: 'stat_failed' });
+      continue;
+    }
+    if (name === ACTIVE_FILE) {
+      active = { path: full, size };
+      continue;
+    }
+    const m = SEALED_RE.exec(name);
+    if (m) {
+      sealed.push({ name, seq: Number.parseInt(m[1], 10), path: full, size });
+    } else {
+      skipped.push({ name, reason: 'unrecognized_segment_name' });
+    }
+  }
+  sealed.sort((a, b) => a.seq - b.seq || a.name.localeCompare(b.name));
+  return { ok: true, sealed, active, skipped };
+}
+
+/** Total bytes held in live .jsonl segment files (meta/state excluded). */
+export function totalSegmentBytes(listing) {
+  let total = listing.active ? listing.active.size : 0;
+  for (const seg of listing.sealed) total += seg.size;
+  return total;
+}