@gregiteen/ssss-cli 0.11.0 → 0.11.2

package/scripts/audit-registry-field-usage.mjs

@@ -57,6 +57,12 @@ const KNOWN_NON_ENGINE_KEYS = new Set([
   'optional_fields', 'type', 'registry',
   'portability', // consumed by src/registry.mjs resolvePortability() + src/bundle.mjs export filtering, not write-time validation
   'resource', // extension-defined resource_bound metadata, consumed by src/bundle.mjs provisioning
+  'description', // human documentation on a primitive definition, same role as `notes`; never enforced at write time
+  // Product-side projection metadata. The SSSS engine never reads these: they are
+  // consumed by the host application's own projector to decide which target tables
+  // a document feeds and how (see festech.live SsssGenericProjector.ts). Kept in the
+  // extension registry so a product's projection contract travels with its types.
+  'projection_strategy', 'projection_targets',
 ]);
 
 function loadAllPrimitiveDefs() {

package/scripts/autolink.mjs

@@ -23,6 +23,7 @@
  *                 [--max-per-target N] [--min-len N] [--index]
  *                 [--include-headings] [--concurrency N]
  */
+import { parseFrontmatter } from '../src/frontmatter.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -85,21 +86,15 @@ function splitFrontmatter(content) {
   };
 }
 
-/** Pull title / name / slug / aliases[] out of a YAML frontmatter block (no dep). */
+/** Pull title / name / slug / aliases[] out of a frontmatter block (fences included). */
 function readMeta(fm) {
-  const scalar = (k) => {
-    const m = fm.match(new RegExp(`^${k}:\\s*(.+)$`, 'm'));
-    return m ? m[1].trim().replace(/^["']|["']$/g, '') : null;
+  const data = parseFrontmatter(fm.replace(/^---[^\n]*\n/, '').replace(/\n---[^\n]*\n?$/, '\n'));
+  const text = (v) => (typeof v === 'string' && v ? v : null);
+  const aliases = Array.isArray(data.aliases) ? data.aliases : typeof data.aliases === 'string' ? [data.aliases] : [];
+  return {
+    title: text(data.title), name: text(data.name), slug: text(data.slug),
+    aliases: aliases.map((x) => String(x).trim()).filter(Boolean)
   };
-  const meta = { title: scalar('title'), name: scalar('name'), slug: scalar('slug'), aliases: [] };
-  // aliases: inline [a, b] or YAML block list
-  const inline = fm.match(/^aliases:\s*\[(.*)\]\s*$/m);
-  if (inline) meta.aliases = inline[1].split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
-  else {
-    const block = fm.match(/^aliases:\s*\n((?:\s*-\s*.+\n?)+)/m);
-    if (block) meta.aliases = block[1].split('\n').map(l => l.replace(/^\s*-\s*/, '').trim().replace(/^["']|["']$/g, '')).filter(Boolean);
-  }
-  return meta;
 }
 
 function buildGlossary(files, root) {

package/scripts/check-events-streaming.mjs

@@ -34,7 +34,52 @@ try {
   await assert.rejects(new JsonlEventStore(root).append(third), /Duplicate event_id/);
   fs.appendFileSync(file, '{invalid JSON}\n');
   await assert.rejects(new JsonlEventStore(root).append(make(4)), SyntaxError);
-  console.log(JSON.stringify({ ok: true, boundedReads: true, utf8: true, cursor: true, duplicate: true, corruptFailClosed: true, largestRead }));
+
+  // Rotation: an append-only log must stay bounded, and rotating it must not
+  // reorder, drop or duplicate a single event. Live-first ordering was a real
+  // bug: archives hold the OLDER events, so they replay first.
+  const rotateRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ssss-event-rotate-'));
+  try {
+    const cap = 2048;
+    const store = new JsonlEventStore(rotateRoot, { maxBytes: cap });
+    const total = 40;
+    const expected = [];
+    for (let i = 0; i < total; i++) {
+      const event = createCanonicalEvent({
+        workspace_id: 'default', action: 'event', subject: `subject-${i}`,
+        principal: { id: 'test', kind: 'service' }, operation_id: `operation-${i}`,
+        idempotency_key: `key-${i}`, payload: { filler: 'b'.repeat(400) }
+      });
+      expected.push(event.event_id);
+      await store.append(event);
+    }
+    const live = path.join(rotateRoot, 'default.jsonl');
+    assert.ok(fs.statSync(live).size <= cap, 'Live log exceeded the rotation cap');
+    const segments = fs.readdirSync(rotateRoot).filter(name => /^default\.\d+\.jsonl$/.test(name));
+    assert.ok(segments.length > 0, 'Expected the log to rotate at least once');
+
+    const replayed = [];
+    for await (const entry of store.replay({ workspaceId: 'default' })) replayed.push(entry.event.event_id);
+    assert.deepEqual(replayed, expected, 'Rotation reordered, dropped or duplicated events');
+
+    // A cursor must resume a stable position across rotation.
+    const from = 12;
+    const resumed = [];
+    for await (const entry of store.replay({ workspaceId: 'default', cursor: from })) resumed.push(entry.cursor);
+    assert.deepEqual(resumed, Array.from({ length: total - from }, (_, i) => from + i + 1), 'Cursor resume shifted across rotation');
+
+    // Uniqueness must survive rotation: the index is rebuilt from archives.
+    await assert.rejects(new JsonlEventStore(rotateRoot, { maxBytes: cap }).append(
+      createCanonicalEvent({
+        event_id: expected[0], workspace_id: 'default', action: 'event', subject: 'dupe',
+        principal: { id: 'test', kind: 'service' }, operation_id: 'operation-dupe',
+        idempotency_key: 'key-dupe', payload: {}
+      })
+    ), /Duplicate event_id/, 'Rotation lost duplicate detection');
+    console.log(JSON.stringify({ ok: true, boundedReads: true, utf8: true, cursor: true, duplicate: true, corruptFailClosed: true, largestRead, rotation: { segments: segments.length, ordered: true, capped: true } }));
+  } finally {
+    fs.rmSync(rotateRoot, { recursive: true });
+  }
 } finally {
   Buffer.alloc = originals.alloc; fs.readFileSync = originals.readFileSync; fs.readSync = originals.readSync;
   fs.rmSync(root, { recursive: true });

package/scripts/check-frontmatter.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// Regression checks for src/frontmatter.mjs: the dependency-free parser must read
+// the YAML that real tools (Total Recall via js-yaml, editors, agents) write.
+import assert from 'node:assert/strict';
+import { parseFrontmatter, parseDocument, serializeDocument } from '../src/frontmatter.mjs';
+
+const parse = (...lines) => parseFrontmatter(lines.join('\n') + '\n');
+let passed = 0;
+const check = (name, fn) => { fn(); passed++; console.log(`  ✅ ${name}`); };
+
+check('hyphenated and dotted keys are kept', () => {
+  assert.deepEqual(parse('allowed-tools: [Read, Bash]', 'a.b: 1', 'my key: v'),
+    { 'allowed-tools': ['Read', 'Bash'], 'a.b': 1, 'my key': 'v' });
+});
+
+check('a colon without a following space is part of the value, not a key', () => {
+  assert.deepEqual(parse('tags:', '  - context:universal', '  - kind:rule', 'url: http://x.io/a:b'),
+    { tags: ['context:universal', 'kind:rule'], url: 'http://x.io/a:b' });
+  assert.deepEqual(parse('tags: [context:universal, b]'), { tags: ['context:universal', 'b'] });
+});
+
+check('quoted commas and brackets survive inline arrays', () => {
+  assert.deepEqual(parse('k: ["a", "b, c", \'d, e\', "[x]"]'), { k: ['a', 'b, c', 'd, e', '[x]'] });
+});
+
+check('JSON flow maps and arrays of JSON objects parse', () => {
+  assert.deepEqual(parse('decay: {"half_life_days":180,"floor":0.5}'), { decay: { half_life_days: 180, floor: 0.5 } });
+  assert.deepEqual(parse('x_citations: [{"source":"cli","title":"a, b","url":"https://e.io/?q=1"}]'),
+    { x_citations: [{ source: 'cli', title: 'a, b', url: 'https://e.io/?q=1' }] });
+  assert.deepEqual(parse('m: {a: 1, b: [x, y], c: {d: true}}'), { m: { a: 1, b: ['x', 'y'], c: { d: true } } });
+  assert.deepEqual(parse('e: {}', 'f: []'), { e: {}, f: [] });
+});
+
+check('malformed flow values fall back to the raw text', () => {
+  assert.deepEqual(parse('k: [a, b'), { k: '[a, b' });
+});
+
+check('wrapped plain and quoted scalars fold into one value', () => {
+  assert.deepEqual(parse('description: This is a long', '  description that wraps', 'next: 1'),
+    { description: 'This is a long description that wraps', next: 1 });
+  assert.deepEqual(parse('q: "one', '  two"', 'n: 2'), { q: 'one two', n: 2 });
+  assert.deepEqual(parse('l:', '  - first', '    second', '  - third'), { l: ['first second', 'third'] });
+});
+
+check('inline comments are stripped from plain values only', () => {
+  assert.deepEqual(parse('a: Ship it # todo', 'b: "keep # this"', 'c: x#y', 'd: 5 # five', 'e: # nothing'),
+    { a: 'Ship it', b: 'keep # this', c: 'x#y', d: 5, e: {} });
+});
+
+check('same-indent block lists and list items with block scalars parse', () => {
+  assert.deepEqual(parse('tags:', '- a', '- b', 'next: 1'), { tags: ['a', 'b'], next: 1 });
+  assert.deepEqual(parse('related:', '  - >-', '    folded', '    text', '  - plain'),
+    { related: ['folded text', 'plain'] });
+});
+
+check('arrays of maps keep nested children and wrapped values', () => {
+  assert.deepEqual(parse('items:', '  - name: x', '    sub:', '      a: 1', '    z: 2', '  - name: y'),
+    { items: [{ name: 'x', sub: { a: 1 }, z: 2 }, { name: 'y' }] });
+  assert.deepEqual(parse('items:', '  - source:', '      kind: a', '    n: 1'), { items: [{ source: { kind: 'a' }, n: 1 }] });
+});
+
+check('YAML double-quoted escapes decode (\\U, \\x, \\e)', () => {
+  assert.deepEqual(parse('t: "\\U0001F534 \\x41 \\e"'), { t: '\u{1F534} A \x1b' });
+});
+
+check('folded block scalars keep the break around more-indented lines', () => {
+  assert.deepEqual(parse('c: >', '  a', '    b', '', '  c'), { c: 'a\n  b\n\nc\n' });
+  assert.deepEqual(parse('c: >-', '  a', '  b', '', '  c'), { c: 'a b\nc' });
+});
+
+check('numbers, codes and booleans keep their types', () => {
+  assert.deepEqual(parse('a: 07003', 'b: 12', 'c: 1.5', 'd: 1e3', 'e: True', 'f: NULL', 'g: 0x1F'),
+    { a: '07003', b: 12, c: 1.5, d: 1000, e: true, f: null, g: 31 });
+});
+
+check('unusual bare keys, nested sequences and keep-chomped blanks parse', () => {
+  assert.deepEqual(parse('users:', '  a@b.com:', '    n: 1', 'last*seen: x'), { users: { 'a@b.com': { n: 1 } }, 'last*seen': 'x' });
+  assert.deepEqual(parse('head:', '  - - meta', '    - http-equiv: refresh', '      content: go'),
+    { head: [['meta', { 'http-equiv': 'refresh', content: 'go' }]] });
+  assert.deepEqual(parse('c: |+', '', 'next: 1'), { c: '\n', next: 1 });
+});
+
+check('single-line files with literal \\n are repaired on read', () => {
+  const flat = '---\\ntype: "memory"\\ntags: ["a","b"]\\n---\\nBody line\\nTwo';
+  const { data, body } = parseDocument(flat);
+  assert.deepEqual(data, { type: 'memory', tags: ['a', 'b'] });
+  assert.equal(body, 'Body line\nTwo\n');
+  // A real multi-line document that merely mentions \\n is untouched.
+  assert.equal(parseDocument('---\nk: a\\nb\n---\n').data.k, 'a\\nb');
+});
+
+check('strict mode throws on malformed YAML that lenient mode skips', () => {
+  const bad = ': : :\nnot: [valid\n';
+  assert.doesNotThrow(() => parseFrontmatter(bad));
+  assert.throws(() => parseFrontmatter(bad, { strict: true }), SyntaxError);
+  assert.throws(() => parseFrontmatter('k: "open\nj: 1\n', { strict: true }), SyntaxError);
+  assert.throws(() => parseFrontmatter('a: 1\n  b: 2\n', { strict: true }), SyntaxError);
+  assert.deepEqual(parseFrontmatter('a: [1, 2]\nb: {c: d}\n', { strict: true }), { a: [1, 2], b: { c: 'd' } });
+  assert.doesNotThrow(() => parseFrontmatter(bad)); // strict does not leak into later calls
+});
+
+check('serialize → parse round-trips tricky values', () => {
+  const data = {
+    'allowed-tools': ['Read', 'Bash'],
+    note: 'a, b: c # d',
+    tags: ['context:universal', 'x, y', '-lead', '07003', 'true'],
+    nested: { 'odd key': { n: 1 }, list: [[1, 2], [{ a: 'b, c' }]] },
+    cites: [{ source: 'cli', title: 'a, b' }],
+    empty: [],
+    multi: 'line one\nline two'
+  };
+  const doc = serializeDocument(data, 'body\n');
+  assert.deepEqual(parseDocument(doc).data, data);
+  assert.equal(serializeDocument(parseDocument(doc).data, 'body\n'), doc);
+});
+
+console.log(`\n  ${passed}/${passed} frontmatter parser checks passed`);

package/scripts/cmd-export.mjs

@@ -52,6 +52,9 @@ export async function run(argv) {
       version: flags['bundle-version'] || '0.1.0',
       exporter: flags.exporter || DEFAULT_EXPORTER,
       requiredExtensions: flags.ext || [],
+      // --ext also scopes the registry load: a registry directory may hold
+      // unrelated product extensions that collide by name (§5.6).
+      ...(flags.ext && flags.ext.length ? { registryNames: flags.ext } : {}),
       ...(flags['exported-at'] ? { exportedAt: flags['exported-at'] } : {}),
     });
   } catch (err) { die(err.message); }

package/scripts/cmd-import.mjs

@@ -31,6 +31,10 @@ const HELP = usage({
 export async function run(argv) {
   if (wantsHelp(argv)) { console.log(HELP); return; }
   const { positionals, flags } = parseArgs(argv, { booleans: ['dry-run'], multi: ['param'] });
+  // Extension namespaces this import must resolve. Seeded from the bundle's own
+  // `required_extensions` so the engine loads exactly the namespace the vault was
+  // exported against, rather than every extension in the registry directory.
+  let registryNames = null;
   if (!flags.vault) die('import needs --vault <dir>.\n\n' + HELP);
   const vault = path.resolve(flags.vault);
   fs.mkdirSync(vault, { recursive: true });
@@ -45,6 +49,8 @@ export async function run(argv) {
     if (!file) die('import needs a bundle file (or --plan).\n\n' + HELP);
     if (!fs.existsSync(file)) die(`no such file: ${file}`);
     const bundle = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const declared = bundle?.manifest?.required_extensions;
+    if (Array.isArray(declared) && declared.length) registryNames = declared;
     const prov = provisionBundle(bundle, {
       parameters: parseKeyValues(flags.param),
       workspaceId: flags.workspace || 'ws-provision',
@@ -60,7 +66,7 @@ export async function run(argv) {
     envelopes = prov.plan;
   }
 
-  const engine = createEngine({ registryDir: flags.registry });
+  const engine = createEngine({ registryDir: flags.registry, ...(registryNames ? { registryNames } : {}) });
   const result = await importBundle(envelopes, vault, engine);
   const failed = result.results.filter((r) => !r.success);
   if (flags['dry-run']) {

package/src/bundle.mjs

@@ -19,6 +19,7 @@ import crypto from 'node:crypto';
 import {
   loadRegistries,
   resolvePortability,
+  resolvePrimitiveDefinition,
   validateDataConstraints,
   validateReferenceConstraints,
 } from './registry.mjs';
@@ -141,11 +142,15 @@ function walkVault(vaultRoot) {
 export function exportBundle(vaultRoot, opts = {}) {
   const { profile = 'backup', registryDir, name = 'untitled', description = '', version = '0.1.0',
     exporter = DEFAULT_EXPORTER, requiredExtensions = [], parameters = [], provisioning = [],
-    sourceWorkspaceId, exportedAt = '1970-01-01T00:00:00.000Z' } = opts;
+    sourceWorkspaceId, exportedAt = '1970-01-01T00:00:00.000Z', registryNames } = opts;
   const includes = PROFILE_INCLUDES[profile];
   if (!includes) throw new Error(`Unknown export profile '${profile}'. Use backup | template | sale.`);
 
-  const { types, core } = loadRegistries(registryDir);
+  // When a caller names the extension namespaces this vault belongs to, load only
+  // those. Unrelated product extensions may share a primitive name, which is a
+  // legitimate load-time collision when loaded together (§5.6).
+  const registrySet = loadRegistries(registryDir, registryNames ? { only: registryNames } : {});
+  const { types, core } = registrySet;
   const dropped = [];
   const kept = [];
   const inventory = {};
@@ -161,7 +166,7 @@ export function exportBundle(vaultRoot, opts = {}) {
   for (const document of vaultDocuments.values()) {
     const base = path.basename(document.path);
     if (base === 'index.md' || base === 'log.md') continue;
-    const definition = types.get(document.data.type);
+    const definition = resolvePrimitiveDefinition(registrySet, document.data.type);
     if (!definition) throw new Error(`Cannot export '${document.path}': unknown type '${document.data.type || '(missing)'}'.`);
     const issues = [
       ...validateDataConstraints(definition, document.data, core.universal_frontmatter?.required || ['type']),
@@ -237,8 +242,23 @@ export function exportBundle(vaultRoot, opts = {}) {
  */
 export function validateBundle(bundle, opts = {}) {
   const errors = [];
-  const { types, core, extensions } = loadRegistries(opts.registryDir);
   const m = bundle && bundle.manifest;
+  // Scope the registry load to the extensions this bundle declares. A registry
+  // directory may hold unrelated product extensions that collide by name (§5.6);
+  // the bundle's own `required_extensions` is the authority on what it needs.
+  const declaredExtensions = Array.isArray(m?.required_extensions) ? m.required_extensions : [];
+  const only = opts.registryNames || (declaredExtensions.length && !opts.loadAllExtensions ? declaredExtensions : null);
+  // A bundle may name an extension this host does not have. That is a validation
+  // error to report, not a crash: fall back to the default composition so the
+  // remaining checks still run and the caller sees every problem at once.
+  let registrySet;
+  try {
+    registrySet = loadRegistries(opts.registryDir, only ? { only } : {});
+  } catch (err) {
+    if (!only || !/is not present in/.test(err.message)) throw err;
+    registrySet = loadRegistries(opts.registryDir);
+  }
+  const { types, core, extensions } = registrySet;
   if (!m || typeof m !== 'object' || Array.isArray(m)) {
     return { valid: false, errors: ['bundle has no object manifest'] };
   }
@@ -340,7 +360,7 @@ export function validateBundle(bundle, opts = {}) {
       const base = path.basename(document.path);
       if (base === 'index.md' || base === 'log.md') continue;
       const { data } = document;
-      const def = types.get(data.type);
+      const def = resolvePrimitiveDefinition(registrySet, data.type);
       if (!def) {
         errors.push(`file '${document.path}' declares unknown type '${data.type || '(missing)'}'`);
         continue;
@@ -370,7 +390,7 @@ export function validateBundle(bundle, opts = {}) {
     }
   }
   for (const document of bundleDocuments.values()) {
-    const definition = types.get(document.data.type);
+    const definition = resolvePrimitiveDefinition(registrySet, document.data.type);
     const issues = validateReferenceConstraints(
       definition,
       document.data,
@@ -511,12 +531,12 @@ export async function importBundle(plan, vaultRoot, engine) {
     return {
       ok: true,
       committed: 0,
-      wouldCommit: preflight.filter((result) => !result.replay).length,
+      wouldCommit: preflight.filter((result) => !result.replay && !result.unchanged).length,
       results: preflight,
     };
   }
   const results = [];
   for (const env of plan) results.push(await engine.processOperation(env, vaultRoot, operationOptions));
-  const committed = results.filter((r) => r.success && !r.replay && !r.dry_run).length;
+  const committed = results.filter((r) => r.success && !r.replay && !r.dry_run && !r.unchanged).length;
   return { ok: results.every((r) => r.success), committed, wouldCommit: 0, results };
 }

package/src/engine.mjs

@@ -96,7 +96,10 @@ class LegacyLeaseAdapter {
 }
 
 export function createEngine(options = {}) {
-  const registrySet = options.registrySet || loadRegistries(options.registryDir);
+  // `registryNames` scopes the load to specific extension namespaces: a registry
+  // directory may hold unrelated product extensions that collide by name (§5.6).
+  const registrySet = options.registrySet
+    || loadRegistries(options.registryDir, options.registryNames ? { only: options.registryNames } : {});
   const validator = options.validator || createValidator({ registrySet });
   const kernels = new Map();
   const legacyLease = typeof options.leaseStore === 'string' ? new LegacyLeaseAdapter(options.leaseStore) : options.leaseStore;

package/src/events.mjs

@@ -126,11 +126,74 @@ export class JsonlEventStore {
     fs.mkdirSync(root, { recursive: true });
     this.root = fs.realpathSync(root);
     this.lockOptions = options.lock || {};
+    // Rotation cap in bytes per live log (SSSS_EVENT_MAX_BYTES, default 32 MiB,
+    // 0 disables). Without it a single append-only log grows without bound --
+    // one reached 653 MB and made the vault impossible to back up, because
+    // GitHub hard-rejects blobs over 100 MB.
+    const cap = Number(options.maxBytes ?? process.env.SSSS_EVENT_MAX_BYTES ?? 32 * 1024 * 1024);
+    this.maxBytes = Number.isFinite(cap) && cap >= 0 ? cap : 32 * 1024 * 1024;
   }
   #file(workspaceId) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(workspaceId || '')) throw new Error('Unsafe event workspace_id.');
     return path.join(this.root, `${workspaceId}.jsonl`);
   }
+  /**
+   * Archive segments for one workspace, in replay order.
+   *
+   * Segments are named `<workspaceId>.<seq>.jsonl` with a fixed-width
+   * zero-padded sequence, and replay() concatenates live-then-archives rather
+   * than relying on a plain alphabetical sort -- `default.0001.jsonl` sorts
+   * BEFORE `default.jsonl`, which would replay archived events out of order.
+   */
+  #archives(workspaceId) {
+    const prefix = `${workspaceId}.`;
+    const suffix = '.jsonl';
+    let names;
+    try { names = fs.readdirSync(this.root); } catch { return []; }
+    return names
+      .filter((n) => n.startsWith(prefix) && n.endsWith(suffix) && /^\d+$/.test(n.slice(prefix.length, -suffix.length)))
+      .sort((a, b) => {
+        const ai = Number(a.slice(prefix.length, -suffix.length));
+        const bi = Number(b.slice(prefix.length, -suffix.length));
+        return ai - bi;
+      })
+      .map((n) => path.join(this.root, n));
+  }
+  /**
+   * Moves the live log aside once it passes the cap, preserving every byte and
+   * the original line order. The live file is renamed, never rewritten or
+   * truncated, so no consumer holding a cursor loses a record: archives hold
+   * strictly older events and replay() yields archives first, then live.
+   *
+   * The duplicate-event_id index is rebuilt from the archives on demand by
+   * #index(), so uniqueness survives rotation.
+   */
+  #rotate(file, workspaceId) {
+    if (this.maxBytes <= 0) return 0;
+    let size;
+    try { size = fs.lstatSync(file).size; } catch { return 0; }
+    if (size <= this.maxBytes) return 0;
+    // Continue the sequence from the highest existing archive rather than the
+    // count, so a gap (a manually removed segment) cannot cause a collision.
+    const existing = this.#archives(workspaceId);
+    let seq = 1;
+    for (const p of existing) {
+      const m = /\.(\d+)\.jsonl$/.exec(p);
+      if (m) seq = Math.max(seq, Number(m[1]) + 1);
+    }
+    const target = path.join(this.root, `${workspaceId}.${String(seq).padStart(4, '0')}.jsonl`);
+    if (fs.existsSync(target)) return 0;
+    try {
+      fs.renameSync(file, target);
+      this.#indexes.delete(file);
+      this.#indexes.delete(target);
+      return 1;
+    } catch {
+      // Leave the oversized log in place rather than lose it; the next append
+      // retries. Growth stays bounded by the cap check on every append.
+      return 0;
+    }
+  }
   #index(file) {
     let stat;
     try { stat = fs.lstatSync(file); }
@@ -142,7 +205,21 @@ export class JsonlEventStore {
     if (stat.isSymbolicLink()) throw new Error('Symlinked event logs are forbidden.');
     const cached = this.#indexes.get(file);
     if (cached && sameStat(cached.stat, stat)) return cached;
-    const index = loadIndex(file);
+    // Duplicate detection spans the live log AND every archive segment:
+    // rotating a log must never let an already-recorded event_id be appended
+    // again. Archives are immutable, so their ids are collected once per
+    // rebuild; only the live file's stat decides when a rebuild is needed.
+    const ids = new Set();
+    const workspaceId = path.basename(file, '.jsonl');
+    for (const archive of this.#archives(workspaceId)) {
+      let archiveStat;
+      try { archiveStat = fs.lstatSync(archive); } catch { continue; }
+      if (archiveStat.isSymbolicLink()) throw new Error('Symlinked event logs are forbidden.');
+      for (const id of loadIndex(archive).ids) ids.add(id);
+    }
+    const live = loadIndex(file);
+    for (const id of live.ids) ids.add(id);
+    const index = { ids, stat };
     this.#indexes.set(file, index);
     return index;
   }
@@ -153,29 +230,44 @@ export class JsonlEventStore {
   #appendLocked(file, event) {
     const index = this.#index(file);
     if (index.ids.has(event.event_id)) throw new Error(`Duplicate event_id '${event.event_id}'.`);
+    // Rotate before writing so the live log never exceeds the cap by more than
+    // a single line. Safe under the append lock: no other writer is mid-append.
+    const rotated = this.#rotate(file, event.workspace_id);
     const line = `${JSON.stringify(event)}\n`;
     this.#indexes.delete(file);
+    const before = rotated ? null : index.stat;
     const fd = openLog(file, APPEND_FLAGS, 0o600);
     let after;
     try {
       fs.writeFileSync(fd, line);
       after = fs.fstatSync(fd);
     } finally { fs.closeSync(fd); }
-    // Keep the index only when the log grew by exactly this line on the same
-    // file; otherwise a writer that skips the lock interleaved, and the next
-    // append rebuilds.
-    const before = index.stat;
+    // Cache the index only when the log grew by exactly this line on the same
+    // file. After a rotation the live file is brand new, so the previous stat
+    // is meaningless and the next append rebuilds from the archives instead.
     const expectedSize = (before?.size || 0) + Buffer.byteLength(line);
-    if (after.size === expectedSize && (!before || (before.dev === after.dev && before.ino === after.ino))) {
+    if (!rotated && after.size === expectedSize && (!before || (before.dev === after.dev && before.ino === after.ino))) {
       index.ids.add(event.event_id);
       this.#indexes.set(file, { ids: index.ids, stat: after });
     }
     return structuredClone(event);
   }
   async *replay(options = {}) {
+    // Replay order is archives-then-live, oldest first. A plain alphabetical
+    // sort would put `default.0001.jsonl` before `default.jsonl` (correct by
+    // accident) but break as soon as a workspace has a name that sorts after a
+    // digit, and live-first would replay new events before old ones.
     const files = options.workspaceId
-      ? [this.#file(options.workspaceId)]
-      : fs.readdirSync(this.root).filter((name) => name.endsWith('.jsonl')).sort().map((name) => path.join(this.root, name));
+      ? [...this.#archives(options.workspaceId), this.#file(options.workspaceId)]
+      : (() => {
+          const names = fs.readdirSync(this.root).filter((name) => name.endsWith('.jsonl'));
+          const workspaces = new Set();
+          for (const name of names) {
+            const m = /^([A-Za-z0-9][A-Za-z0-9._-]{0,127}?)(?:\.\d+)?\.jsonl$/.exec(name);
+            if (m) workspaces.add(m[1]);
+          }
+          return [...workspaces].sort().flatMap((w) => [...this.#archives(w), this.#file(w)]);
+        })();
     let cursor = 0;
     for (const file of files) {
       if (!fs.existsSync(file)) continue;