@polderlabs/bizar 6.3.0 → 7.0.0

package/cli/__tests__/cost-gate.test.mjs

@@ -0,0 +1,301 @@
+/**
+ * cli/__tests__/cost-gate.test.mjs
+ *
+ * F-035 — tests for cli/cost-gate.mjs (atomic SQLite-backed room budget tracker).
+ *
+ * Uses Node's built-in `node:test`. No external framework.
+ *
+ * Coverage:
+ *   1. registerRoom — idempotent, accepts valid cap, rejects invalid.
+ *   2. status — reflects spentUsd / remaining correctly.
+ *   3. listRooms — returns every room with up-to-date totals.
+ *   4. reserve → commit: happy path, final remaining matches.
+ *   5. reserve → release: spentUsd stays 0, remaining recovers.
+ *   6. BUDGET_EXCEEDED: refusal when projected > cap.
+ *   7. Reservation expiry: state flips to 'expired' on sweepExpired.
+ *   8. Late commit: COMMIT_AFTER_EXPIRY warning + 'committed_post_expiry' state.
+ *   9. Concurrent reserves: one succeeds, the other BUDGET_EXCEEDEDs (BEGIN
+ *      IMMEDIATE atomicity).
+ *  10. ALREADY_FINALIZED on double commit / double release.
+ *  11. ROOM_NOT_FOUND path.
+ *  12. Expiry clamping [5s, 300s] per ADR-164.1 §3.2.
+ */
+
+import { test, describe, before, afterEach, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const {
+  CostGate,
+  RESERVATION_EXPIRY_FLOOR_MS,
+  RESERVATION_EXPIRY_CEILING_MS,
+  clampReservationExpiry,
+} = await import('../cost-gate.mjs');
+
+let tmpdir_created = false;
+let tmp;
+
+before(() => {
+  if (!tmpdir_created) {
+    tmp = mkdtempSync(join(tmpdir(), 'bizar-cost-gate-'));
+    tmpdir_created = true;
+  }
+});
+
+afterEach(() => {
+  // each test creates its own gate; nothing to clean up
+});
+
+function freshGate(clock) {
+  const dbPath = join(tmp, `gate-${Math.random().toString(36).slice(2, 8)}-${Date.now()}.db`);
+  return new CostGate({
+    dbPath,
+    clock: clock || (() => Date.now()),
+  });
+}
+
+describe('registerRoom()', () => {
+  let gate;
+  beforeEach(() => { gate = freshGate(); });
+  afterEach(() => gate.close());
+
+  test('inserts a new room', () => {
+    const r = gate.registerRoom('titan-cluster', 50);
+    assert.equal(r.ok, true);
+    assert.equal(r.roomId, 'titan-cluster');
+    assert.equal(r.capUsd, 50);
+  });
+
+  test('upsert on conflict — idempotent', () => {
+    gate.registerRoom('titan-cluster', 50);
+    gate.registerRoom('titan-cluster', 75); // raises cap
+    const s = gate.status('titan-cluster');
+    assert.equal(s.capUsd, 75);
+  });
+
+  test('rejects invalid roomId', () => {
+    assert.throws(() => gate.registerRoom('', 10), /roomId/);
+    assert.throws(() => gate.registerRoom(null, 10), /roomId/);
+  });
+
+  test('rejects negative cap', () => {
+    assert.throws(() => gate.registerRoom('r', -1), /capUsd/);
+    assert.throws(() => gate.registerRoom('r', NaN), /capUsd/);
+  });
+});
+
+describe('status() and listRooms()', () => {
+  let gate;
+  beforeEach(() => { gate = freshGate(); });
+  afterEach(() => gate.close());
+
+  test('status returns null for unknown room', () => {
+    assert.equal(gate.status('nope'), null);
+  });
+
+  test('status reflects spentUsd and remaining correctly', () => {
+    gate.registerRoom('alpha', 100);
+    gate.reserve('alpha', 'tester', 30);
+    // Capture txId deterministically for the commit
+    const rsv = gate.reserve('alpha', 'tester', 10);
+    gate.commit(rsv.txId, 10);
+    const s = gate.status('alpha');
+    assert.equal(s.spentUsd, 10, 'only the committed 10 is spent');
+    assert.equal(s.reservedUsd, 30, 'the 30 reservation is still live');
+    assert.equal(s.remainingUsd, 100 - 10 - 30);
+    assert.ok(s.txCount >= 2);
+  });
+
+  test('listRooms returns every registered room', () => {
+    gate.registerRoom('a', 1);
+    gate.registerRoom('b', 2);
+    gate.registerRoom('c', 3);
+    const all = gate.listRooms();
+    const ids = all.map((r) => r.roomId).sort();
+    assert.deepEqual(ids, ['a', 'b', 'c']);
+  });
+});
+
+describe('reserve → commit happy path', () => {
+  let gate;
+  beforeEach(() => { gate = freshGate(); });
+  afterEach(() => gate.close());
+
+  test('reserve then commit with smaller amount', () => {
+    gate.registerRoom('r', 100);
+    const rsv = gate.reserve('r', 'agent1', 40);
+    assert.equal(rsv.ok, true);
+    assert.ok(rsv.txId.startsWith('tx-'));
+    const cm = gate.commit(rsv.txId, 25);
+    assert.equal(cm.ok, true);
+    assert.equal(cm.committed, true);
+    const s = gate.status('r');
+    assert.equal(s.spentUsd, 25);
+    assert.equal(s.remainingUsd, 75);
+  });
+
+  test('reserve then commit with same amount', () => {
+    gate.registerRoom('r', 100);
+    const rsv = gate.reserve('r', 'agent1', 40);
+    const cm = gate.commit(rsv.txId, 40);
+    assert.equal(cm.committed, true);
+    assert.equal(gate.status('r').spentUsd, 40);
+  });
+});
+
+describe('reserve → release', () => {
+  let gate;
+  beforeEach(() => { gate = freshGate(); });
+  afterEach(() => gate.close());
+
+  test('release frees the budget without charging it', () => {
+    gate.registerRoom('r', 100);
+    const rsv = gate.reserve('r', 'a', 30);
+    const rel = gate.release(rsv.txId);
+    assert.equal(rel.ok, true);
+    assert.equal(rel.released, true);
+    const s = gate.status('r');
+    assert.equal(s.spentUsd, 0);
+    assert.equal(s.reservedUsd, 0);
+    assert.equal(s.remainingUsd, 100);
+  });
+
+  test('release on already-released tx returns ALREADY_FINALIZED', () => {
+    gate.registerRoom('r', 100);
+    const rsv = gate.reserve('r', 'a', 10);
+    gate.release(rsv.txId);
+    const rel = gate.release(rsv.txId);
+    assert.equal(rel.ok, false);
+    assert.equal(rel.error, 'ALREADY_FINALIZED');
+  });
+});
+
+describe('BUDGET_EXCEEDED refusal', () => {
+  let gate;
+  beforeEach(() => { gate = freshGate(); });
+  afterEach(() => gate.close());
+
+  test('refuses reserve that would exceed cap', () => {
+    gate.registerRoom('r', 100);
+    const r1 = gate.reserve('r', 'a', 80);
+    assert.equal(r1.ok, true);
+    const r2 = gate.reserve('r', 'a', 30);
+    assert.equal(r2.ok, false);
+    assert.equal(r2.error, 'BUDGET_EXCEEDED');
+    assert.equal(r2.capUsd, 100);
+    assert.equal(r2.committed, 0);
+    assert.equal(r2.reserved, 80);
+  });
+
+  test('committing an exact-fit reservation is allowed (with epsilon)', () => {
+    gate.registerRoom('r', 100);
+    const rsv = gate.reserve('r', 'a', 100);
+    assert.equal(rsv.ok, true);
+    assert.equal(rsv.remainingAfterReserve, 0);
+  });
+});
+
+describe('expiry + late commit', () => {
+  let gate;
+  let now;
+  beforeEach(() => {
+    now = 1_700_000_000_000;
+    gate = freshGate(() => now);
+  });
+  afterEach(() => gate.close());
+
+  test('sweepExpired flips reserved rows to expired', () => {
+    gate.registerRoom('r', 100);
+    const rsv = gate.reserve('r', 'a', 10, { expiryMs: 5_000 });
+    assert.equal(rsv.ok, true);
+    now += 6_000; // past expiry
+    const swept = gate.sweepExpired();
+    assert.equal(swept, 1);
+    const tx = gate.listTransactions('r').find((t) => t.tx_id === rsv.txId);
+    assert.equal(tx.kind, 'expired');
+  });
+
+  test('commit after expiry returns COMMIT_AFTER_EXPIRY warning + spends the actual amount', () => {
+    gate.registerRoom('r', 100);
+    const rsv = gate.reserve('r', 'a', 10, { expiryMs: 5_000 });
+    now += 6_000; // past expiry
+    const cm = gate.commit(rsv.txId, 7.5);
+    assert.equal(cm.ok, true);
+    assert.equal(cm.warned, 'COMMIT_AFTER_EXPIRY');
+    const tx = gate.listTransactions('r').find((t) => t.tx_id === rsv.txId);
+    assert.equal(tx.kind, 'committed_post_expiry');
+    const s = gate.status('r');
+    assert.equal(s.spentUsd, 7.5);
+    assert.equal(s.remainingUsd, 92.5);
+  });
+
+  test('commit twice returns ALREADY_FINALIZED', () => {
+    gate.registerRoom('r', 100);
+    const rsv = gate.reserve('r', 'a', 10);
+    gate.commit(rsv.txId, 8);
+    const cm2 = gate.commit(rsv.txId, 8);
+    assert.equal(cm2.ok, false);
+    assert.equal(cm2.error, 'ALREADY_FINALIZED');
+  });
+});
+
+describe('CONCURRENT reserve race (BEGIN IMMEDIATE atomicity)', () => {
+  test('only one of N concurrent reserves can exceed the cap when strictly under', () => {
+    const gate = freshGate();
+    try {
+      gate.registerRoom('cr', 10);
+      // Fire 10 reserves of $1.50 against a $10 cap. The first 6
+      // succeed ($9 projected); the 7th hits BUDGET_EXCEEDED. We use
+      // a tight loop so they pile up against the immediate write lock.
+      const results = [];
+      for (let i = 0; i < 20; i++) {
+        const r = gate.reserve('cr', `caller-${i}`, 1.5);
+        results.push(r);
+      }
+      const ok = results.filter((r) => r.ok).length;
+      const denied = results.filter((r) => !r.ok).length;
+      assert.equal(ok + denied, 20);
+      assert.equal(ok, 6, `expected 6 reserves to fit (6 × $1.50 = $9 ≤ $10), got ${ok}`);
+      assert.equal(denied, 14);
+      assert.ok(
+        results.some((r) => !r.ok && r.error === 'BUDGET_EXCEEDED'),
+        'at least one must hit BUDGET_EXCEEDED',
+      );
+      const s = gate.status('cr');
+      assert.equal(s.reservedUsd, 9);
+      assert.equal(s.spentUsd, 0);
+    } finally {
+      gate.close();
+    }
+  });
+});
+
+describe('ROOM_NOT_FOUND', () => {
+  let gate;
+  beforeEach(() => { gate = freshGate(); });
+  afterEach(() => gate.close());
+
+  test('reserve returns ROOM_NOT_FOUND', () => {
+    const r = gate.reserve('nope', 'a', 10);
+    assert.equal(r.ok, false);
+    assert.equal(r.error, 'ROOM_NOT_FOUND');
+  });
+});
+
+describe('clampReservationExpiry — ADR-164.1 §3.2', () => {
+  test('floors at 5_000 ms', () => {
+    assert.equal(clampReservationExpiry(100), RESERVATION_EXPIRY_FLOOR_MS);
+  });
+  test('caps at 300_000 ms', () => {
+    assert.equal(clampReservationExpiry(60 * 60 * 1000), RESERVATION_EXPIRY_CEILING_MS);
+  });
+  test('passes through valid values', () => {
+    assert.equal(clampReservationExpiry(30_000), 30_000);
+  });
+  test('uses 60_000 ms default for undefined', () => {
+    assert.equal(clampReservationExpiry(undefined), 60_000);
+  });
+});

package/cli/__tests__/feature-list-bridge.test.mjs

@@ -0,0 +1,371 @@
+/**
+ * cli/__tests__/feature-list-bridge.test.mjs
+ *
+ * F-035 — tests for cli/feature-list-bridge.mjs (claim protocol over
+ * feature_list.json).
+ *
+ * Uses Node's built-in `node:test`. No external framework.
+ *
+ * Coverage:
+ *   1. claim — first claim succeeds; second claim rejected ALREADY_CLAIMED.
+ *   2. release — reverts to unclaimed; subsequent release errors.
+ *   3. handoff — moves claimant to recipient atomically.
+ *   4. steal — moves claimant with a stealReason recorded in history.
+ *   5. transition — claimStatus moves through allowed states.
+ *   6. list — filters by status, claimantId, type.
+ *   7. Bad transition — non-allowed status change errors.
+ *   8. unknown feature — NOT_FOUND.
+ *   9. Persistence: round-trips through file storage.
+ */
+
+import { test, describe, before, after, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { mkdtempSync, writeFileSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const {
+  FeatureListBridge,
+  CLAIM_STATUSES,
+  STEAL_REASONS,
+  ClaimError,
+} = await import('../feature-list-bridge.mjs');
+
+// ── Fixture loader ────────────────────────────────────────────────────
+
+let tmp;
+let bridgeFactory;
+
+function writeFixture(dir, name, features) {
+  const file = join(dir, name);
+  const payload = { $schema: 'https://bizar.dev/schemas/feature_list.v1.json', features };
+  writeFileSync(file, JSON.stringify(payload, null, 2));
+  return file;
+}
+
+const minimalFeature = (id, extra = {}) => ({
+  id,
+  behavior: `Behavior for ${id}`,
+  verification: 'make check',
+  state: 'not_started',
+  layer: 'L1',
+  category: 'core',
+  created: '2026-07-11',
+  ...extra,
+});
+
+before(() => {
+  tmp = mkdtempSync(join(tmpdir(), 'bizar-bridge-'));
+  bridgeFactory = (filePath) => new FeatureListBridge({
+    filePath,
+    backup: false, // speed up tests
+  });
+});
+
+after(() => {
+  if (tmp && existsSync(tmp)) rmSync(tmp, { recursive: true, force: true });
+});
+
+// ── claim ─────────────────────────────────────────────────────────────
+
+describe('claim()', () => {
+  let file;
+  let br;
+  beforeEach(() => {
+    file = writeFixture(tmp, `claim-${Math.random().toString(36).slice(2, 8)}.json`, [
+      minimalFeature('F-A'),
+      minimalFeature('F-B', { state: 'passing' }),
+    ]);
+    br = bridgeFactory(file);
+  });
+  afterEach(() => { /* tmp cleaned in after() */ });
+
+  test('first claim succeeds', () => {
+    const result = br.claim('F-A', { type: 'human', id: 'odin', name: 'Odin' }, 'first-run');
+    assert.equal(result.ok, true);
+    const f = result.feature;
+    assert.equal(f.claimant.id, 'odin');
+    assert.equal(f.claimStatus, 'claimed');
+    assert.ok(f.claimedAt);
+    assert.equal(f.claimReason, 'first-run');
+    assert.equal(f.claimHistory.length, 1);
+    assert.equal(f.claimHistory[0].event, 'claim');
+  });
+
+  test('second claim rejected with ALREADY_CLAIMED', () => {
+    br.claim('F-A', { type: 'human', id: 'odin', name: 'Odin' }, 'first-run');
+    assert.throws(
+      () => br.claim('F-A', { type: 'agent', id: 'tyr' }, 'second-run'),
+      (err) => err instanceof ClaimError && err.code === 'ALREADY_CLAIMED',
+    );
+  });
+
+  test('claim against unknown feature rejected with NOT_FOUND', () => {
+    assert.throws(
+      () => br.claim('F-NONE', { type: 'agent', id: 'x' }, ''),
+      (err) => err instanceof ClaimError && err.code === 'NOT_FOUND',
+    );
+  });
+
+  test('claim rejects malformed claimant', () => {
+    assert.throws(
+      () => br.claim('F-A', { type: 'robot', id: 'x' }, ''),
+      (err) => err instanceof ClaimError && err.code === 'BAD_CLAIMANT',
+    );
+  });
+
+  test('can re-claim a completed feature', () => {
+    br.claim('F-A', { type: 'human', id: 'odin' }, '');
+    br.transition('F-A', 'completed', { id: 'odin' }, '');
+    // released -> re-claimable
+    const r2 = br.claim('F-A', { type: 'agent', id: 'tyr' }, 'second life');
+    assert.equal(r2.ok, true);
+  });
+});
+
+// ── release ───────────────────────────────────────────────────────────
+
+describe('release()', () => {
+  let file;
+  let br;
+  beforeEach(() => {
+    file = writeFixture(tmp, `rel-${Math.random().toString(36).slice(2, 8)}.json`, [minimalFeature('F-X')]);
+    br = bridgeFactory(file);
+  });
+
+  test('release after claim sets status to unclaimed', () => {
+    br.claim('F-X', { type: 'human', id: 'odin' }, '');
+    const result = br.release('F-X', { id: 'odin' }, 'done');
+    assert.equal(result.ok, true);
+    assert.equal(result.feature.claimStatus, 'unclaimed');
+    assert.equal(result.feature.claimant, null);
+    assert.equal(result.feature.claimHistory.length, 2);
+  });
+
+  test('release without claim errors with NOT_CLAIMED', () => {
+    assert.throws(
+      () => br.release('F-X', { id: 'odin' }, ''),
+      (err) => err instanceof ClaimError && err.code === 'NOT_CLAIMED',
+    );
+  });
+
+  test('release with wrong claimant errors with WRONG_CLAIMANT', () => {
+    br.claim('F-X', { type: 'human', id: 'odin' }, '');
+    assert.throws(
+      () => br.release('F-X', { id: 'tyr' }, ''),
+      (err) => err instanceof ClaimError && err.code === 'WRONG_CLAIMANT',
+    );
+  });
+});
+
+// ── handoff ───────────────────────────────────────────────────────────
+
+describe('handoff()', () => {
+  let file;
+  let br;
+  beforeEach(() => {
+    file = writeFixture(tmp, `h-${Math.random().toString(36).slice(2, 8)}.json`, [minimalFeature('F-H')]);
+    br = bridgeFactory(file);
+  });
+
+  test('handoff moves claimant', () => {
+    br.claim('F-H', { type: 'human', id: 'odin' }, '');
+    const result = br.handoff(
+      'F-H',
+      { type: 'human', id: 'odin' },
+      { type: 'agent', id: 'tyr', name: 'Tyr' },
+      'context finished',
+    );
+    assert.equal(result.ok, true);
+    assert.equal(result.feature.claimant.id, 'tyr');
+    assert.equal(result.feature.claimStatus, 'claimed');
+    // history: claim + handoff-initiated + handoff-accepted
+    const events = result.feature.claimHistory.map((e) => e.event);
+    assert.deepEqual(events, ['claim', 'handoff-initiated', 'handoff-accepted']);
+  });
+
+  test('handoff with no current claim errors', () => {
+    assert.throws(
+      () => br.handoff(
+        'F-H',
+        { type: 'human', id: 'odin' },
+        { type: 'agent', id: 'tyr' },
+        '',
+      ),
+      (err) => err instanceof ClaimError && err.code === 'NOT_CLAIMED',
+    );
+  });
+});
+
+// ── steal ─────────────────────────────────────────────────────────────
+
+describe('steal()', () => {
+  let file;
+  let br;
+  beforeEach(() => {
+    file = writeFixture(tmp, `s-${Math.random().toString(36).slice(2, 8)}.json`, [minimalFeature('F-S')]);
+    br = bridgeFactory(file);
+  });
+
+  test('steal moves the claim', () => {
+    br.claim('F-S', { type: 'human', id: 'odin' }, '');
+    for (const reason of STEAL_REASONS) {
+      // Steal a fresh feature for each reason to avoid ALREADY_CLAIMED.
+      const f = minimalFeature(`F-S-${reason}`);
+      const fFile = writeFixture(tmp, `s-${reason}.json`, [f]);
+      const subBridge = bridgeFactory(fFile);
+      subBridge.claim(`F-S-${reason}`, { type: 'agent', id: 'previous' }, '');
+      const result = subBridge.steal(`F-S-${reason}`, { type: 'agent', id: 'tyr' }, reason);
+      assert.equal(result.ok, true);
+      assert.equal(result.previousClaimant.id, 'previous');
+      assert.equal(result.feature.claimant.id, 'tyr');
+      assert.equal(result.stealReason, reason);
+      assert.ok(
+        result.feature.claimHistory.some((e) => e.event === 'steal' && e.reason === reason),
+      );
+    }
+  });
+
+  test('steal rejects unknown reason', () => {
+    br.claim('F-S', { type: 'human', id: 'odin' }, '');
+    assert.throws(
+      () => br.steal('F-S', { type: 'agent', id: 'tyr' }, 'bogus-reason'),
+      (err) => err instanceof ClaimError && err.code === 'UNKNOWN_STEAL_REASON',
+    );
+  });
+});
+
+// ── transition ────────────────────────────────────────────────────────
+
+describe('transition()', () => {
+  let file;
+  let br;
+  beforeEach(() => {
+    file = writeFixture(tmp, `t-${Math.random().toString(36).slice(2, 8)}.json`, [minimalFeature('F-T')]);
+    br = bridgeFactory(file);
+  });
+
+  test('claim → active → paused → active → completed', () => {
+    br.claim('F-T', { type: 'human', id: 'odin' }, '');
+    br.transition('F-T', 'active', { id: 'odin' }, '');
+    assert.equal(br.get('F-T').claimStatus, 'active');
+    br.transition('F-T', 'paused', { id: 'odin' }, 'lunch');
+    assert.equal(br.get('F-T').claimStatus, 'paused');
+    br.transition('F-T', 'active', { id: 'odin' }, '');
+    assert.equal(br.get('F-T').claimStatus, 'active');
+    br.transition('F-T', 'completed', { id: 'odin' }, '');
+    assert.equal(br.get('F-T').claimStatus, 'completed');
+  });
+
+  test('illegal transition rejected', () => {
+    br.claim('F-T', { type: 'human', id: 'odin' }, '');
+    // claimed → blocked is NOT in ALLOWED_TRANSITIONS['claimed']
+    assert.throws(
+      () => br.transition('F-T', 'blocked', { id: 'odin' }, ''),
+      (err) => err instanceof ClaimError && err.code === 'BAD_TRANSITION',
+    );
+  });
+
+  test('unknown status rejected', () => {
+    br.claim('F-T', { type: 'human', id: 'odin' }, '');
+    assert.throws(
+      () => br.transition('F-T', 'bogus', { id: 'odin' }, ''),
+      (err) => err instanceof ClaimError && err.code === 'UNKNOWN_STATUS',
+    );
+  });
+});
+
+// ── list ──────────────────────────────────────────────────────────────
+
+describe('list()', () => {
+  let file;
+  let br;
+  beforeEach(() => {
+    file = writeFixture(tmp, `l-${Math.random().toString(36).slice(2, 8)}.json`, [
+      minimalFeature('F-1'),
+      minimalFeature('F-2'),
+      minimalFeature('F-3'),
+      minimalFeature('F-4'),
+    ]);
+    br = bridgeFactory(file);
+  });
+
+  test('claims 2, handoffs 1, steals 1 — list filters', () => {
+    br.claim('F-1', { type: 'human', id: 'odin' }, '');
+    br.claim('F-2', { type: 'agent', id: 'tyr' }, '');
+    br.claim('F-3', { type: 'human', id: 'odin' }, '');
+    br.handoff('F-3', { type: 'human', id: 'odin' }, { type: 'agent', id: 'tyr' }, '');
+    br.claim('F-4', { type: 'human', id: 'mimir' }, '');
+    br.steal('F-4', { type: 'agent', id: 'tyr' }, 'voluntary');
+
+    const all = br.list();
+    assert.equal(all.length, 4);
+    const claimed = br.list({ status: 'claimed' });
+    assert.equal(claimed.length, 4, 'all four are claimed at this point');
+    const humanClaims = br.list({ claimedByHuman: true });
+    // All four claimants are human-type except F-2 (initial agent) and F-3 (after handoff).
+    // Once F-3 is handed off it has an agent claimant. F-4 was stolen by an agent.
+    const humanIds = humanClaims.map((f) => f.id);
+    assert.ok(humanIds.includes('F-1'), 'F-1 stayed human');
+    assert.ok(!humanIds.includes('F-4'), 'F-4 is now an agent claim');
+
+    const byOdin = br.list({ claimantId: 'odin' });
+    assert.equal(byOdin.length, 1, 'only F-1 still belongs to odin');
+    assert.equal(byOdin[0].id, 'F-1');
+  });
+
+  test('list with no filters returns every feature', () => {
+    const all = br.list();
+    assert.equal(all.length, 4);
+  });
+});
+
+// ── Persistence ───────────────────────────────────────────────────────
+
+describe('persistence', () => {
+  test('bridges are independent — each gets its own file', () => {
+    const file = writeFixture(tmp, `p-${Math.random().toString(36).slice(2, 6)}.json`, [minimalFeature('F-P')]);
+    const a = bridgeFactory(file);
+    a.claim('F-P', { type: 'human', id: 'odin' }, '');
+    const b = bridgeFactory(file);
+    assert.equal(b.get('F-P').claimant.id, 'odin');
+    assert.equal(b.get('F-P').claimStatus, 'claimed');
+  });
+
+  test('atomic write produces a parseable file', () => {
+    const file = writeFixture(tmp, `pw-${Math.random().toString(36).slice(2, 6)}.json`, [minimalFeature('F-PW')]);
+    const a = bridgeFactory(file);
+    a.claim('F-PW', { type: 'agent', id: 'first' }, '');
+    a.release('F-PW', { id: 'first' }, 'round-trip test');
+    a.claim('F-PW', { type: 'agent', id: 'second' }, 're-claim after release');
+    // verify file is valid JSON
+    const txt = readFileSync(file, 'utf8');
+    const data = JSON.parse(txt);
+    assert.ok(Array.isArray(data.features));
+    assert.equal(data.features.length, 1);
+    const f = data.features[0];
+    assert.equal(f.claimant.id, 'second');
+    assert.equal(f.claimStatus, 'claimed');
+    assert.ok(Array.isArray(f.claimHistory));
+    assert.equal(f.claimHistory.length, 3);
+  });
+});
+
+// ── CLAIM_STATUSES + STEAL_REASONS shape ──────────────────────────────
+
+describe('exported constants', () => {
+  test('CLAIM_STATUSES matches the spec', () => {
+    assert.deepEqual(
+      [...CLAIM_STATUSES].sort(),
+      ['active', 'blocked', 'claimed', 'completed', 'handoff-pending', 'paused', 'unclaimed'].sort(),
+    );
+  });
+
+  test('STEAL_REASONS matches the spec', () => {
+    assert.deepEqual(
+      [...STEAL_REASONS].sort(),
+      ['blocked-timeout', 'overloaded', 'stale', 'voluntary'].sort(),
+    );
+  });
+});