onbuzz 4.5.0 → 4.6.1

package/src/core/__tests__/flowTemplates.test.js

@@ -0,0 +1,311 @@
+/**
+ * Verifies every starter flow template:
+ *   - passes the v2 schema validator (so users can save it as-is)
+ *   - passes lint with zero warnings (no unbound placeholders, no
+ *     missing required edges)
+ *   - has a unique key + a non-empty label and description
+ *
+ * If a template ever ships broken, this test fails loud.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import { STARTER_TEMPLATES, getTemplateByKey } from '../../../web-ui/src/utils/flowTemplates.js';
+import { validateFlowDefinition } from '../flowSchema.js';
+import { lintFlow } from '../flowLint.js';
+
+describe('STARTER_TEMPLATES — registry shape', () => {
+  test('exposes at least 3 templates', () => {
+    expect(STARTER_TEMPLATES.length).toBeGreaterThanOrEqual(3);
+  });
+
+  test('every template has key, label, description, flow', () => {
+    for (const t of STARTER_TEMPLATES) {
+      expect(typeof t.key).toBe('string');
+      expect(t.key.length).toBeGreaterThan(0);
+      expect(typeof t.label).toBe('string');
+      expect(t.label.length).toBeGreaterThan(0);
+      expect(typeof t.description).toBe('string');
+      expect(t.description.length).toBeGreaterThan(0);
+      expect(t.flow).toBeDefined();
+    }
+  });
+
+  test('keys are unique', () => {
+    const keys = STARTER_TEMPLATES.map(t => t.key);
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+
+  test('getTemplateByKey returns the right one + null for unknown', () => {
+    const first = STARTER_TEMPLATES[0];
+    expect(getTemplateByKey(first.key)).toBe(first);
+    expect(getTemplateByKey('nonexistent-key-xyz')).toBe(null);
+  });
+});
+
+describe('STARTER_TEMPLATES — every template validates clean', () => {
+  for (const t of STARTER_TEMPLATES) {
+    test(`"${t.key}" passes schema validator`, () => {
+      const r = validateFlowDefinition(t.flow);
+      if (!r.ok) {
+        // Print errors for easier debugging
+        // eslint-disable-next-line no-console
+        console.error(`Template ${t.key} schema errors:`, r.errors);
+      }
+      expect(r.ok).toBe(true);
+    });
+
+    test(`"${t.key}" lint warnings are ONLY 'unbound-agent' (user picks agents after loading)`, () => {
+      // Templates ship with empty agentIds so users pick their own
+      // agents. Every other lint rule (unbound placeholder, unbound
+      // required input) must still pass — otherwise the template is
+      // genuinely broken.
+      const r = lintFlow(t.flow);
+      const otherWarnings = r.warnings.filter(w => w.kind !== 'unbound-agent');
+      if (otherWarnings.length > 0) {
+        // eslint-disable-next-line no-console
+        console.error(`Template ${t.key} non-agent lint warnings:`, otherWarnings);
+      }
+      expect(otherWarnings).toEqual([]);
+    });
+
+    test(`"${t.key}" is marked as v2 (schemaVersion: 2)`, () => {
+      expect(t.flow.schemaVersion).toBe(2);
+    });
+
+    // Phase 7: every template ships with rich contracts so users
+    // see the value immediately without filling in fields.
+
+    test(`"${t.key}" has a non-empty flow.description (FLOW GOAL)`, () => {
+      expect(typeof t.flow.description).toBe('string');
+      expect(t.flow.description.trim().length).toBeGreaterThan(20);
+    });
+
+    test(`"${t.key}" — every agent node has non-empty data.instructions`, () => {
+      const agentNodes = t.flow.nodes.filter(n => n.type === 'agent');
+      expect(agentNodes.length).toBeGreaterThan(0);
+      for (const n of agentNodes) {
+        expect(typeof n.data?.instructions).toBe('string');
+        expect(n.data.instructions.trim().length).toBeGreaterThan(20);
+      }
+    });
+
+    test(`"${t.key}" — every declared input/output has a non-empty description`, () => {
+      for (const node of t.flow.nodes) {
+        for (const kind of ['inputs', 'outputs']) {
+          const arr = node[kind];
+          if (!Array.isArray(arr)) continue;
+          for (const field of arr) {
+            expect(typeof field.description).toBe('string');
+            expect(field.description.trim().length).toBeGreaterThan(0);
+          }
+        }
+      }
+    });
+
+    test(`"${t.key}" — agent node outputs include an example for json/list types (where most useful)`, () => {
+      // Examples are most valuable for opaque types where the model
+      // would otherwise guess shape. Strict for json + list types.
+      for (const node of t.flow.nodes.filter(n => n.type === 'agent')) {
+        for (const out of (node.outputs || [])) {
+          if (out.type === 'json' || out.type === 'list<text>' || out.type === 'file[]') {
+            expect(out.example).toBeDefined();
+          }
+        }
+      }
+    });
+
+    // ---- Phase 7 audit: producer ↔ consumer description alignment ----
+    //
+    // For each edge, BOTH the source output and target input must have
+    // a meaningful description (≥40 chars). Catches the "consumer is
+    // too terse" failure mode where the producer says "shape is
+    // {a,b,c}" and the consumer just says "from upstream" — leaving
+    // the consuming agent without enough context to use the data well.
+    test(`"${t.key}" — every edge has descriptions on BOTH ends (≥40 chars each)`, () => {
+      const findField = (nodeId, kind, fieldName) => {
+        const node = t.flow.nodes.find(n => n.id === nodeId);
+        return (node?.[kind] || []).find(f => f.name === fieldName);
+      };
+
+      for (const edge of (t.flow.edges || [])) {
+        if (!edge.sourceField || !edge.targetField) continue; // v1 edges
+        const src = findField(edge.source, 'outputs', edge.sourceField);
+        const dst = findField(edge.target, 'inputs',  edge.targetField);
+        expect(src).toBeDefined();
+        expect(dst).toBeDefined();
+        const where = `${edge.source}.${edge.sourceField} → ${edge.target}.${edge.targetField}`;
+        // Producer description present and substantial
+        if (!(src.description && src.description.length >= 40)) {
+          // eslint-disable-next-line no-console
+          console.error(`Edge "${where}" — producer description too thin: ${JSON.stringify(src.description)}`);
+        }
+        expect(typeof src.description).toBe('string');
+        expect(src.description.length).toBeGreaterThanOrEqual(40);
+        // Consumer description present and substantial
+        if (!(dst.description && dst.description.length >= 40)) {
+          // eslint-disable-next-line no-console
+          console.error(`Edge "${where}" — consumer description too thin: ${JSON.stringify(dst.description)}`);
+        }
+        expect(typeof dst.description).toBe('string');
+        expect(dst.description.length).toBeGreaterThanOrEqual(40);
+      }
+    });
+
+    // Phase 7 audit: catch the linear-research class of bug — output
+    // node receives a one-token field as the user-facing context.
+    // If the output node's input is wired to a `text` field whose
+    // example is shorter than ~10 chars, that's almost certainly the
+    // wrong wire (e.g. wiring "verdict: 'approved'" instead of the
+    // full article).
+    test(`"${t.key}" — output node receives a substantive context payload`, () => {
+      const outputNode = t.flow.nodes.find(n => n.type === 'output');
+      if (!outputNode) return;
+      const inboundEdges = (t.flow.edges || []).filter(e => e.target === outputNode.id);
+      for (const edge of inboundEdges) {
+        if (!edge.sourceField) continue;
+        const sourceNode = t.flow.nodes.find(n => n.id === edge.source);
+        const sourceOutput = (sourceNode?.outputs || []).find(o => o.name === edge.sourceField);
+        if (!sourceOutput) continue;
+        // If the source output has an example, the example must be
+        // substantive — not a single token like "approved".
+        if (sourceOutput.example !== undefined && typeof sourceOutput.example === 'string') {
+          if (sourceOutput.example.length < 20) {
+            // eslint-disable-next-line no-console
+            console.error(
+              `Output node "${outputNode.id}" receives "${edge.source}.${edge.sourceField}" whose example is only "${sourceOutput.example}" — likely wrong wire (user will see this short token as the entire flow output).`
+            );
+          }
+          expect(sourceOutput.example.length).toBeGreaterThanOrEqual(20);
+        }
+      }
+    });
+  }
+});
+
+// ---- Per-template behavioural locks ----
+//
+// The generic checks above guarantee schema/lint/Phase-7 hygiene across
+// every template. The blocks below lock the specific behaviour each new
+// template exists to demonstrate — so a refactor can't silently drop the
+// feature that justifies the template's existence.
+
+describe('Template "support-triage" — feature locks', () => {
+  const triage = getTemplateByKey('support-triage');
+
+  test('exists', () => {
+    expect(triage).not.toBeNull();
+  });
+
+  test('has the four specialist-pipeline nodes (classifier, specialist, formatter, plus io)', () => {
+    const ids = triage.flow.nodes.map(n => n.id);
+    expect(ids).toEqual(expect.arrayContaining(['classifier', 'specialist', 'formatter', 'in', 'out']));
+  });
+
+  test('classifier emits the three routing fields (category enum, urgency number, sentiment enum)', () => {
+    const classifier = triage.flow.nodes.find(n => n.id === 'classifier');
+    const outputNames = (classifier.outputs || []).map(o => o.name);
+    expect(outputNames).toEqual(expect.arrayContaining(['category', 'urgency', 'sentiment']));
+    const urgency = classifier.outputs.find(o => o.name === 'urgency');
+    expect(urgency.type).toBe('number');
+  });
+
+  test('classifier has a tight timeout (≤30s) — fast classification is the whole point', () => {
+    const classifier = triage.flow.nodes.find(n => n.id === 'classifier');
+    expect(classifier.execution?.timeoutMs).toBeDefined();
+    expect(classifier.execution.timeoutMs).toBeLessThanOrEqual(30000);
+  });
+
+  test('specialist has a longer timeout (≥60s) — resolution work needs more headroom than classification', () => {
+    const specialist = triage.flow.nodes.find(n => n.id === 'specialist');
+    expect(specialist.execution?.timeoutMs).toBeDefined();
+    expect(specialist.execution.timeoutMs).toBeGreaterThanOrEqual(60000);
+  });
+
+  test('flow has retry policy (queue robustness across transient failures)', () => {
+    expect(triage.flow.execution?.maxRetries).toBeDefined();
+    expect(triage.flow.execution.maxRetries).toBeGreaterThan(0);
+  });
+
+  test('all three classifier outputs reach the specialist (typed routing)', () => {
+    const edges = triage.flow.edges.filter(e => e.source === 'classifier' && e.target === 'specialist');
+    const fields = edges.map(e => e.sourceField).sort();
+    expect(fields).toEqual(['category', 'sentiment', 'urgency']);
+  });
+
+  test('formatter receives both the resolution AND the sentiment (tone-matching contract)', () => {
+    const inbound = triage.flow.edges.filter(e => e.target === 'formatter');
+    const targetFields = inbound.map(e => e.targetField).sort();
+    expect(targetFields).toEqual(['resolution', 'sentiment']);
+  });
+
+  test('output node receives the polished reply (formatter.reply), not raw resolution', () => {
+    const out = triage.flow.nodes.find(n => n.id === 'out');
+    const inbound = triage.flow.edges.find(e => e.target === out.id);
+    expect(inbound.source).toBe('formatter');
+    expect(inbound.sourceField).toBe('reply');
+  });
+});
+
+describe('Template "spec-plan-implement-verify" — feature locks', () => {
+  const sp = getTemplateByKey('spec-plan-implement-verify');
+
+  test('exists', () => {
+    expect(sp).not.toBeNull();
+  });
+
+  test('has the four-stage autonomous-coding pipeline (pm → architect → implementer → verifier)', () => {
+    const ids = sp.flow.nodes.map(n => n.id);
+    expect(ids).toEqual(expect.arrayContaining(['pm', 'architect', 'implementer', 'verifier', 'in', 'out']));
+  });
+
+  test('PM produces structured requirements (json), not free prose', () => {
+    const pm = sp.flow.nodes.find(n => n.id === 'pm');
+    const requirements = (pm.outputs || []).find(o => o.name === 'requirements');
+    expect(requirements).toBeDefined();
+    expect(requirements.type).toBe('json');
+  });
+
+  test('architect produces a typed file list (the implementer\'s contract — most important guarantee in this flow)', () => {
+    const architect = sp.flow.nodes.find(n => n.id === 'architect');
+    const files = (architect.outputs || []).find(o => o.name === 'files');
+    expect(files).toBeDefined();
+    // Either json (a structured list) or list-of-something is acceptable;
+    // the value comes from being structured — not a prose blob.
+    expect(['json', 'list<text>']).toContain(files.type);
+  });
+
+  test('implementer receives the architect\'s files list AND the prose plan (typed handoff prevents drift)', () => {
+    const inbound = sp.flow.edges.filter(e => e.target === 'implementer');
+    const targets = inbound.map(e => e.targetField).sort();
+    expect(targets).toEqual(['files', 'plan']);
+    // Both must come from the architect — the implementer can't take a
+    // file list from anywhere else.
+    expect(inbound.every(e => e.source === 'architect')).toBe(true);
+  });
+
+  test('implementer has the longest timeout (≥5min) and ≥2 retries — code generation is the slow + flaky step', () => {
+    const implementer = sp.flow.nodes.find(n => n.id === 'implementer');
+    expect(implementer.execution?.timeoutMs).toBeGreaterThanOrEqual(300000);
+    expect(implementer.execution?.maxRetries).toBeGreaterThanOrEqual(2);
+  });
+
+  test('verifier has zero retries (deterministic step — re-running tests on the same code is wasted work)', () => {
+    const verifier = sp.flow.nodes.find(n => n.id === 'verifier');
+    expect(verifier.execution?.maxRetries).toBe(0);
+  });
+
+  test('verifier emits all three required signals: passed (boolean), failures (list<text>), report (text)', () => {
+    const verifier = sp.flow.nodes.find(n => n.id === 'verifier');
+    const byName = Object.fromEntries((verifier.outputs || []).map(o => [o.name, o]));
+    expect(byName.passed?.type).toBe('boolean');
+    expect(byName.failures?.type).toBe('list<text>');
+    expect(byName.report?.type).toBe('text');
+  });
+
+  test('output node receives the human-readable report (text) — type-compatible with the output node', () => {
+    const out = sp.flow.nodes.find(n => n.id === 'out');
+    const inbound = sp.flow.edges.find(e => e.target === out.id);
+    expect(inbound.source).toBe('verifier');
+    expect(inbound.sourceField).toBe('report');
+  });
+});

package/src/core/__tests__/flowTypes.test.js

@@ -0,0 +1,147 @@
+/**
+ * flowTypes — type registry + compat matrix that backs Flows v2 typed I/O.
+ *
+ * Why these tests exist: edges in v2 connect a *typed output* to a *typed
+ * input*. The compatibility matrix decides which connections are allowed.
+ * Get this wrong and either:
+ *   - too lax: agents receive payloads they can't parse (silent break)
+ *   - too strict: trivial-looking flows refuse to connect (UX paper-cut)
+ *
+ * The matrix below is the contract. Every cell is justified by a test.
+ *
+ * Allowed implicit conversions (no cast node needed):
+ *   - exact match               always
+ *   - any scalar  → text        (auto-stringify; text is the universal sink)
+ *   - any         → json        (everything wraps as a JSON value)
+ *   - file        → file[]      (singleton-as-list; common ergonomic case)
+ *   - text        → list<text>  (single-line as 1-element list)
+ *
+ * Disallowed (must use an explicit cast/transform node):
+ *   - text/number/json → file or file[]   (text is not a path)
+ *   - file → text                          (don't auto-read file contents)
+ *   - number ← text (parse direction)     (lossy; force user to declare)
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import {
+  TYPES,
+  isKnownType,
+  isCompatible,
+  describeCompat,
+} from '../flowTypes.js';
+
+describe('TYPES registry', () => {
+  test('exposes the v2 minimum types', () => {
+    expect(TYPES).toEqual(expect.arrayContaining([
+      'text', 'number', 'boolean', 'json', 'file', 'file[]', 'list<text>',
+    ]));
+  });
+
+  test('isKnownType true for declared types', () => {
+    for (const t of TYPES) expect(isKnownType(t)).toBe(true);
+  });
+
+  test('isKnownType false for unknown types', () => {
+    for (const bad of ['', null, undefined, 'string', 'int', 'list', 'list<json>', 'TEXT']) {
+      expect(isKnownType(bad)).toBe(false);
+    }
+  });
+});
+
+describe('isCompatible — exact match', () => {
+  test('every type is compatible with itself', () => {
+    for (const t of TYPES) expect(isCompatible(t, t)).toBe(true);
+  });
+});
+
+describe('isCompatible — text as universal sink', () => {
+  test.each([
+    ['number', 'text'],
+    ['boolean', 'text'],
+    ['json', 'text'],   // JSON.stringify is well-defined
+  ])('%s → text is allowed (auto-stringify)', (from, to) => {
+    expect(isCompatible(from, to)).toBe(true);
+  });
+
+  test('file → text is NOT allowed (would auto-read; surprising)', () => {
+    expect(isCompatible('file', 'text')).toBe(false);
+  });
+
+  test('file[] → text is NOT allowed', () => {
+    expect(isCompatible('file[]', 'text')).toBe(false);
+  });
+});
+
+describe('isCompatible — json as universal sink', () => {
+  test.each(['text', 'number', 'boolean', 'list<text>'])(
+    '%s → json is allowed (wraps as JSON value)',
+    (from) => { expect(isCompatible(from, 'json')).toBe(true); }
+  );
+
+  test('file → json is NOT allowed (don\'t auto-read)', () => {
+    expect(isCompatible('file', 'json')).toBe(false);
+  });
+});
+
+describe('isCompatible — file singleton-as-list', () => {
+  test('file → file[] is allowed (singleton-as-list)', () => {
+    expect(isCompatible('file', 'file[]')).toBe(true);
+  });
+
+  test('file[] → file is NOT allowed (lossy: which one?)', () => {
+    expect(isCompatible('file[]', 'file')).toBe(false);
+  });
+});
+
+describe('isCompatible — text → list<text>', () => {
+  test('text → list<text> is allowed (1-element list)', () => {
+    expect(isCompatible('text', 'list<text>')).toBe(true);
+  });
+
+  test('list<text> → text is NOT allowed (lossy: how to join?)', () => {
+    expect(isCompatible('list<text>', 'text')).toBe(false);
+  });
+});
+
+describe('isCompatible — disallowed pairs (require cast node)', () => {
+  test.each([
+    ['text', 'number'],     // parse — declare it
+    ['text', 'boolean'],    // parse — declare it
+    ['text', 'file'],       // text is not a path
+    ['text', 'file[]'],
+    ['json', 'file'],
+    ['number', 'file'],
+    ['boolean', 'number'],  // would silently coerce
+  ])('%s → %s is rejected', (from, to) => {
+    expect(isCompatible(from, to)).toBe(false);
+  });
+});
+
+describe('isCompatible — defensive', () => {
+  test('unknown source type returns false', () => {
+    expect(isCompatible('blob', 'text')).toBe(false);
+  });
+  test('unknown target type returns false', () => {
+    expect(isCompatible('text', 'blob')).toBe(false);
+  });
+  test('null/undefined return false', () => {
+    expect(isCompatible(null, 'text')).toBe(false);
+    expect(isCompatible('text', null)).toBe(false);
+    expect(isCompatible(undefined, undefined)).toBe(false);
+  });
+});
+
+describe('describeCompat — diagnostic messages', () => {
+  test('returns a usable explanation for incompatible pairs', () => {
+    const msg = describeCompat('file', 'text');
+    expect(typeof msg).toBe('string');
+    expect(msg.length).toBeGreaterThan(0);
+    expect(msg.toLowerCase()).toContain('file');
+    expect(msg.toLowerCase()).toContain('text');
+  });
+
+  test('returns null/empty for compatible pairs', () => {
+    const msg = describeCompat('text', 'text');
+    expect(msg === null || msg === '' || msg === undefined).toBe(true);
+  });
+});

package/src/core/__tests__/flowVersionStore.test.js

@@ -0,0 +1,123 @@
+/**
+ * FlowVersionStore — append-only history of flow definitions.
+ *
+ * Layout:
+ *   <baseDir>/<flowId>/v-<n>.json   (n is monotonically increasing)
+ *
+ * On every PUT to a flow, the webServer also writes a new version
+ * snapshot. Versions are immutable once written. listVersions returns
+ * { version, savedAt } metadata sorted ascending. loadVersion reads
+ * the full snapshot. rollback reads version N and lets the caller
+ * persist it as the live record (the store itself is read/write of
+ * the version archive — the actual "live record swap" stays in the
+ * webServer route so we don't tangle responsibilities).
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import path from 'path';
+import os from 'os';
+import { promises as fs } from 'fs';
+import { FlowVersionStore } from '../flowVersionStore.js';
+
+let tmpRoot;
+beforeEach(async () => {
+  tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'flow-version-test-'));
+});
+afterEach(async () => {
+  try { await fs.rm(tmpRoot, { recursive: true, force: true }); } catch {}
+});
+
+const newStore = () => new FlowVersionStore({ baseDir: tmpRoot });
+
+describe('FlowVersionStore — recordVersion', () => {
+  test('first version is 1', async () => {
+    const store = newStore();
+    const v = await store.recordVersion('f1', { id: 'f1', name: 'A', nodes: [], edges: [] });
+    expect(v.version).toBe(1);
+    expect(typeof v.savedAt).toBe('string');
+  });
+
+  test('subsequent versions increment monotonically', async () => {
+    const store = newStore();
+    const v1 = await store.recordVersion('f1', { id: 'f1', name: 'A', nodes: [], edges: [] });
+    const v2 = await store.recordVersion('f1', { id: 'f1', name: 'A2', nodes: [], edges: [] });
+    const v3 = await store.recordVersion('f1', { id: 'f1', name: 'A3', nodes: [], edges: [] });
+    expect([v1.version, v2.version, v3.version]).toEqual([1, 2, 3]);
+  });
+
+  test('versions for different flow IDs are independent', async () => {
+    const store = newStore();
+    const a1 = await store.recordVersion('a', { name: 'a' });
+    const b1 = await store.recordVersion('b', { name: 'b' });
+    const a2 = await store.recordVersion('a', { name: 'a2' });
+    expect(a1.version).toBe(1);
+    expect(b1.version).toBe(1);
+    expect(a2.version).toBe(2);
+  });
+
+  test('records include savedAt ISO timestamp', async () => {
+    const store = newStore();
+    const v = await store.recordVersion('f1', { name: 'A' });
+    expect(v.savedAt).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+  });
+});
+
+describe('FlowVersionStore — listVersions', () => {
+  test('returns [] for unknown flow', async () => {
+    const store = newStore();
+    expect(await store.listVersions('ghost')).toEqual([]);
+  });
+
+  test('returns metadata sorted ascending', async () => {
+    const store = newStore();
+    await store.recordVersion('f1', { name: 'v1' });
+    await store.recordVersion('f1', { name: 'v2' });
+    await store.recordVersion('f1', { name: 'v3' });
+    const list = await store.listVersions('f1');
+    expect(list.map(v => v.version)).toEqual([1, 2, 3]);
+    for (const v of list) {
+      expect(typeof v.savedAt).toBe('string');
+      expect(v.name).toBeDefined();
+    }
+  });
+});
+
+describe('FlowVersionStore — loadVersion', () => {
+  test('returns the exact snapshot persisted', async () => {
+    const store = newStore();
+    const flow = { id: 'f1', name: 'A', nodes: [{ id: 'n1' }], edges: [] };
+    await store.recordVersion('f1', flow);
+    const loaded = await store.loadVersion('f1', 1);
+    expect(loaded.flow).toEqual(flow);
+    expect(loaded.version).toBe(1);
+    expect(loaded.savedAt).toBeDefined();
+  });
+
+  test('returns null for unknown version', async () => {
+    const store = newStore();
+    expect(await store.loadVersion('f1', 99)).toBe(null);
+  });
+});
+
+describe('FlowVersionStore — defensive', () => {
+  test('refuses path-traversal in flowId', async () => {
+    const store = newStore();
+    await expect(store.recordVersion('../escape', { name: 'x' })).rejects.toThrow();
+  });
+
+  test('handles flow id with slashes/colons via sanitization', async () => {
+    const store = newStore();
+    const v = await store.recordVersion('flow:complex/id', { name: 'x' });
+    expect(v.version).toBe(1);
+    const list = await store.listVersions('flow:complex/id');
+    expect(list).toHaveLength(1);
+  });
+
+  test('does not mutate the input flow object', async () => {
+    const store = newStore();
+    const flow = { id: 'f', name: 'orig', nodes: [] };
+    const snap = JSON.parse(JSON.stringify(flow));
+    await store.recordVersion('f', flow);
+    expect(flow).toEqual(snap);
+  });
+});

package/src/core/__tests__/orchestrator.test.js

@@ -80,6 +80,44 @@ describe('Orchestrator', () => {
     );
   });
 
+  // ───── Cross-component wiring (regression locks) ─────
+
+  describe('toolsRegistry exposure', () => {
+    // Background: webServer's FlowExecutor init reads `this.orchestrator?.toolsRegistry`
+    // (webServer.js:574) to find the JobDoneTool singleton and call
+    // setFlowExecutor on it. Without that wiring, JobDoneTool's
+    // Phase 8 contract validation silently no-ops because
+    // `this.flowExecutor` stays undefined, and partial job-done calls
+    // fall through to the legacy pendingTasks rejection path. The fix
+    // is `index.js` setting `this.orchestrator.toolsRegistry =
+    // this.toolsRegistry` after the orchestrator is constructed.
+    // This test locks that contract: orchestrator must accept and
+    // expose a toolsRegistry assignment so the webServer lookup works.
+
+    test('exposes toolsRegistry after external assignment', () => {
+      const fakeRegistry = {
+        getTool: jest.fn().mockReturnValue({
+          setFlowExecutor: jest.fn(),
+        }),
+      };
+      orchestrator.toolsRegistry = fakeRegistry;
+
+      // Simulate the webServer lookup at webServer.js:574
+      const found = orchestrator?.toolsRegistry?.getTool?.('jobdone');
+      expect(found).toBeDefined();
+      expect(typeof found.setFlowExecutor).toBe('function');
+      expect(orchestrator.toolsRegistry).toBe(fakeRegistry);
+    });
+
+    test('toolsRegistry lookup yields undefined when not wired (smoke)', () => {
+      // If a future refactor breaks the wiring, this lookup pattern
+      // returns undefined — which is exactly the failure mode that
+      // caused Phase 8 to silently no-op for an entire process lifetime.
+      // Keeping this assertion makes the failure mode visible.
+      expect(orchestrator.toolsRegistry).toBeUndefined();
+    });
+  });
+
   // ───── Request Routing ─────
 
   describe('processRequest routing', () => {