checkpoint: matrix-agent-validated (2026-04-25)

Architectural snapshot of the lakehouse codebase at the point where the
full matrix-driven agent loop with Mem0 versioning + deletion was
validated end-to-end.

WHAT THIS REPO IS
A clean single-commit snapshot of the lakehouse code. Heavy test data
(.parquet datasets, vector indexes) excluded — see REPLICATION.md for
regen path. Full lakehouse history at git.agentview.dev/profit/lakehouse.

WHAT WAS PROVEN
- Vector retrieval across multi-corpora matrix (chicago_permits + entity
  briefs + sec_tickers + distilled procedural + llm_team runs)
- Observer hand-review (cloud + heuristic fallback) gating each candidate
- Local-model agent loop (qwen3.5:latest) with tool use + scratchpad
- Playbook seal on success → next-iter retrieval surfaces it as preamble
- Mem0 versioning + deletion in pathway_memory:
    * UPSERT: ADD on new workflow, UPDATE bumps replay_count on identical
    * REVISE: chains versions, parent.superseded_at + superseded_by stamped
    * RETIRE: marks specific trace retired with reason, excluded from retrieval
    * HISTORY: walks chain root→tip, cycle-safe

KEY DIRECTORIES
- crates/vectord/src/pathway_memory.rs — Mem0 ops live here
- crates/vectord/src/playbook_memory.rs — original Mem0 reference
- tests/agent_test/ — local-model agent harness + PRD + session archives
- scripts/dump_raw_corpus.sh — MinIO bucket dump (raw test corpus)
- scripts/vectorize_raw_corpus.ts — corpus → vector indexes
- scripts/analyze_chicago_contracts.ts — real inference pipeline
- scripts/seal_agent_playbook.ts — Mem0 upsert from agent traces

Replication: see REPLICATION.md for Debian 13 clean install + cloud-only
adaptation (no local Ollama).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

tests/multi-agent/gen_staffer_demo.ts

@@ -0,0 +1,124 @@
+// Phase 23 demo — 4 staffer personas × 3 contract scenarios each.
+// Same contracts run against different staffers to measure competence
+// differential. After the batch, findNeighbors should rank top-staffer
+// playbooks above junior-staffer playbooks for similar scenarios.
+//
+// Output: 12 spec files under tests/multi-agent/scenarios/staffer_demo/
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+// Per-staffer tool_level mirrors the real-world asymmetry: senior gets
+// the most powerful stack, trainee gets the least. The architectural
+// question is whether the playbook inheritance is strong enough to let
+// the trainee still produce usable outcomes when the big tools are off.
+const STAFFERS = [
+  { id: "S-001", name: "Maria Chen",   tenure_months: 48, role: "senior"  as const, tool_level: "full"    as const },
+  { id: "S-002", name: "James Park",   tenure_months: 14, role: "mid"     as const, tool_level: "local"   as const },
+  { id: "S-003", name: "Sam Torres",   tenure_months: 4,  role: "junior"  as const, tool_level: "basic"   as const },
+  { id: "S-004", name: "Alex Rivera",  tenure_months: 1,  role: "trainee" as const, tool_level: "minimal" as const },
+];
+
+// Three contract shapes — one downtown assembly, one warehouse ramp,
+// one emergency recovery. Different cities to vary the sig_hash.
+const CONTRACTS = [
+  {
+    tag: "nashville_downtown",
+    client: "Riverline Logistics — Nashville Downtown Build-Out",
+    city: "Nashville", state: "TN",
+    contract: {
+      deadline: "2026-05-19",
+      budget_total_usd: 180000,
+      budget_per_hour_max: 32,
+      local_bonus_per_hour: 4,
+      local_bonus_radius_mi: 75,
+      fill_requirement: "paramount" as const,
+    },
+    events: [
+      { kind: "baseline_fill", at: "07:00", role: "Welder",             count: 4 },
+      { kind: "expansion",     at: "08:30", role: "Packaging Operator", count: 6 },
+      { kind: "baseline_fill", at: "09:00", role: "Shipping Clerk",     count: 2 },
+      { kind: "emergency",     at: "13:00", role: "Welder",             count: 2, deadline: "15:00" },
+      { kind: "misplacement",  at: "15:30", role: "Packaging Operator", count: 1, replaces_event: "08:30" },
+    ],
+  },
+  {
+    tag: "joliet_warehouse",
+    client: "Midway Distribution — Joliet DC Ramp",
+    city: "Joliet", state: "IL",
+    contract: {
+      deadline: "2026-05-12",
+      budget_total_usd: 120000,
+      budget_per_hour_max: 28,
+      local_bonus_per_hour: 3,
+      local_bonus_radius_mi: 50,
+      fill_requirement: "preferred" as const,
+    },
+    events: [
+      { kind: "baseline_fill", at: "07:00", role: "Warehouse Associate", count: 5 },
+      { kind: "recurring",     at: "10:00", role: "Forklift Operator",   count: 3 },
+      { kind: "expansion",     at: "12:30", role: "Picker",              count: 4 },
+      { kind: "misplacement",  at: "15:00", role: "Forklift Operator",   count: 1, replaces_event: "10:00" },
+    ],
+  },
+  {
+    tag: "indianapolis_assembly",
+    client: "Pioneer Assembly — Indianapolis Plant Expansion",
+    city: "Indianapolis", state: "IN",
+    contract: {
+      deadline: "2026-05-26",
+      budget_total_usd: 220000,
+      budget_per_hour_max: 30,
+      local_bonus_per_hour: 5,
+      local_bonus_radius_mi: 60,
+      fill_requirement: "paramount" as const,
+    },
+    events: [
+      { kind: "baseline_fill", at: "07:30", role: "Assembler",        count: 6 },
+      { kind: "recurring",     at: "09:30", role: "Quality Tech",     count: 2 },
+      { kind: "expansion",     at: "11:00", role: "Machine Operator", count: 5 },
+      { kind: "emergency",     at: "14:00", role: "Machine Operator", count: 3, deadline: "16:00" },
+      { kind: "misplacement",  at: "16:00", role: "Assembler",        count: 1, replaces_event: "07:30" },
+    ],
+  },
+];
+
+async function main() {
+  const outDir = "tests/multi-agent/scenarios/staffer_demo";
+  await mkdir(outDir, { recursive: true });
+  const manifest: Array<{ file: string; staffer: string; contract: string; client: string }> = [];
+  let day = 0;
+  for (const staffer of STAFFERS) {
+    for (const ct of CONTRACTS) {
+      day += 1;
+      const date = new Date(Date.now() + day * 86400000).toISOString().split("T")[0];
+      const spec = {
+        client: ct.client,
+        date,
+        contract: ct.contract,
+        staffer,
+        events: ct.events.map(e => ({
+          ...e,
+          city: ct.city,
+          state: ct.state,
+          shift_start: `${e.at} ${e.at.startsWith("0") ? "AM" : "PM"}`,
+          scenario_note: `Staffed by ${staffer.name} (${staffer.role}, ${staffer.tenure_months}mo). Contract deadline ${ct.contract.deadline}, fill=${ct.contract.fill_requirement}.`,
+        })),
+      };
+      const fname = `${staffer.id}_${ct.tag}.json`;
+      await writeFile(join(outDir, fname), JSON.stringify(spec, null, 2));
+      manifest.push({ file: fname, staffer: staffer.name, contract: ct.tag, client: ct.client });
+    }
+  }
+  await writeFile(
+    join(outDir, "manifest.json"),
+    JSON.stringify({ count: manifest.length, scenarios: manifest }, null, 2),
+  );
+  console.log(`✓ ${manifest.length} staffer-demo specs → ${outDir}/`);
+  for (const m of manifest) console.log(`   ${m.file} — ${m.staffer} × ${m.contract}`);
+}
+
+main().catch(e => {
+  console.error("gen_staffer_demo failed:", (e as Error).message);
+  process.exit(1);
+});