@jhizzard/termdeck 1.0.14 → 1.1.1

package/packages/server/src/setup/mnestra-migrations/017_memory_sessions_session_metadata.sql

@@ -3,7 +3,7 @@
 -- Sprint 51.6 T3 (TermDeck v1.0.2 hotfix wave). Brings the canonical engram
 -- memory_sessions schema in line with the rag-system writer's column set so
 -- TermDeck's bundled session-end hook can write a uniform shape on both
--- fresh-canonical installs and Joshua's daily-driver petvetbid (where the
+-- fresh-canonical installs and Joshua's daily-driver the reference Mnestra project (where the
 -- columns were already added by hand when rag-system bootstrap ran).
 --
 -- Why: until v1.0.2 the bundled hook only wrote memory_items. The actual
@@ -17,7 +17,7 @@
 -- the schema it expects exists everywhere.
 --
 -- Idempotent — safe on:
---   1. petvetbid (where these columns are already present from hand-applied
+--   1. the reference Mnestra project (where these columns are already present from hand-applied
 --      DDL Joshua ran when setting up rag-system; the IF NOT EXISTS guards
 --      no-op on every column).
 --   2. Fresh canonical installs that ran migrations 001-016 only (the canonical
@@ -26,11 +26,11 @@
 --
 -- The unique constraint on session_id is wrapped in a do-block because
 -- ADD CONSTRAINT does not support IF NOT EXISTS in PostgreSQL. Joshua's
--- petvetbid already has the constraint as memory_sessions_session_id_key
+-- the reference Mnestra project already has the constraint as memory_sessions_session_id_key
 -- (auto-named by the rag-system bootstrap); this block detects that name
 -- and skips re-adding.
 --
--- session_id is added NULLABLE on canonical installs even though petvetbid's
+-- session_id is added NULLABLE on canonical installs even though the reference Mnestra project's
 -- existing constraint is NOT NULL. Adding NOT NULL via ALTER TABLE on a
 -- table with existing rows would fail; the bundled hook always supplies
 -- session_id at write time, so nullability is non-blocking. A future sprint
@@ -56,7 +56,7 @@ alter table public.memory_sessions
 -- Unique constraint on session_id. Skip if any unique constraint on
 -- (session_id) is already in place — covers both the canonical name
 -- memory_sessions_session_id_key and any alternate name from a manual
--- ALTER TABLE Joshua may have run on petvetbid.
+-- ALTER TABLE Joshua may have run on the reference Mnestra project.
 do $$
 declare
   has_unique boolean;

package/packages/server/src/setup/mnestra-migrations/018_rumen_processed_at.sql

@@ -19,7 +19,7 @@
 --   1. Joshua's daily-driver (pre-Sprint-53; column will be added with
 --      every existing memory_sessions row at NULL → all become candidates
 --      on the first post-deploy tick, which is the desired bootstrap).
---   2. Brad's jizzard-brain (Linux SSH; same shape, same null-bootstrap).
+--   2. Linux SSH installs (same shape, same null-bootstrap).
 --   3. Fresh canonical installs (post-mig-017 schema; column added on
 --      first run, no rows to backfill).
 --   4. Re-runs (ADD COLUMN IF NOT EXISTS + CREATE INDEX IF NOT EXISTS).

package/packages/server/src/setup/mnestra-migrations/019_security_hardening.sql

@@ -0,0 +1,190 @@
+-- Mnestra v0.4.6 — security hardening (revised from 0.4.4 / 0.4.5).
+--
+-- Source: external Supabase-advisor sweep by Brad Heath / Nacho Money LLC,
+-- 2026-05-06. See docs/SECURITY-HARDENING-2026-05-06.md for the full flag
+-- and root-cause analysis. The standing rule lives in the global Claude
+-- Code instructions: "MANDATORY: Supabase RLS + privilege hygiene".
+--
+-- Two corrections folded into this revision:
+--
+--   A. **search_path must include `extensions`.** The 0.4.4/0.4.5 version of
+--      this migration set search_path = public, pg_catalog on the memory_*
+--      RPCs. Supabase >= 2024 installs pgvector in the `extensions` schema,
+--      so the `<=>` cosine-distance operator becomes unreachable from those
+--      RPCs after the alter — semantic recall fails with "operator does not
+--      exist: extensions.vector <=> extensions.vector". Confirmed live
+--      against the reference Mnestra project on 2026-05-06; fixed by
+--      including `extensions` in search_path.
+--
+--   B. **Schema-generation-aware.** Some Mnestra installs are on the older
+--      "memory_items-only" generation — they have memory_items /
+--      memory_relationships / memory_sessions + the 6 memory_* RPCs, but
+--      NOT the layered-memory tables (mnestra_session_memory,
+--      mnestra_developer_memory, mnestra_project_memory, mnestra_commands)
+--      and NOT the mnestra_doctor_* SECURITY DEFINER probes. The 0.4.4 / 0.4.5
+--      migration body assumed the layered shape and threw "relation does
+--      not exist" / "function does not exist" mid-migration on older
+--      installs. Brad caught this on three of his projects (Structural,
+--      aetheria-payroll, aetheria-phase1) and worked around with a
+--      signature-agnostic DO-block subset.
+--
+--      This revision restructures every section as defensive lookups
+--      against pg_class / pg_proc / pg_views, so each statement only fires
+--      when its target exists. The migration runs cleanly on:
+--        - layered-memory generation (Josh's reference project): full fix
+--        - memory_items-only generation (Brad's three projects): function
+--          hardening only; mnestra_*-targeting statements are skipped
+--        - mixed generation: each statement applies to whatever exists
+--
+-- Closes four hole classes (where applicable to the install's schema
+-- generation):
+--
+--   1. Permissive PUBLIC INSERT RLS on mnestra_{commands,developer_memory,
+--      project_memory,session_memory}. Created by Supabase Studio's
+--      "Allow insert for all" default-policy template at table-creation
+--      time. Anyone with the project's anon key could write directly to
+--      memory tables, poisoning the corpus or session-id-squatting.
+--
+--   2. PUBLIC EXECUTE on every Mnestra function. Postgres defaults
+--      function EXECUTE to PUBLIC; the explicit `grant ... to service_role`
+--      in earlier migrations is additive, not exclusive.
+--
+--   3. Mutable search_path on memory_* and mnestra_doctor_* functions
+--      (Supabase lint 0011).
+--
+--   4. mnestra_recent_activity SECURITY DEFINER view (Supabase lint 0010)
+--      with anon+authenticated SELECT.
+--
+-- Backward-compat: zero behavior change for any Mnestra installation that
+-- follows the documented architecture (service-role writes via MCP server).
+-- service_role keeps EXECUTE on every function and SELECT on the view.
+--
+-- Idempotent: every section guards on object existence and uses
+-- IF EXISTS / signature-agnostic patterns. Re-running this migration is
+-- safe and is in fact the recommended way to upgrade a 0.4.4/0.4.5 install
+-- to pick up the search_path fix.
+
+-- ====================================================================
+-- 1. Drop permissive PUBLIC INSERT policies on mnestra_* tables, when
+--    those tables exist on this install. Skipped silently on older
+--    memory_items-only schema generation.
+-- ====================================================================
+
+do $$
+declare
+  tbl text;
+  tables text[] := array[
+    'mnestra_commands',
+    'mnestra_developer_memory',
+    'mnestra_project_memory',
+    'mnestra_session_memory'
+  ];
+begin
+  foreach tbl in array tables loop
+    if to_regclass(format('public.%I', tbl)) is not null then
+      execute format('drop policy if exists "Allow insert for all" on public.%I', tbl);
+    end if;
+  end loop;
+end $$;
+
+-- ====================================================================
+-- 2 + 3. Revoke EXECUTE from public + anon + authenticated AND pin
+-- search_path on every Mnestra function. Signature-agnostic — iterates
+-- pg_proc to apply to whatever functions exist on this install. Covers
+-- memory_*, match_memories, expand_memory_neighborhood, and
+-- mnestra_doctor_*.
+--
+-- search_path includes `extensions` for the pgvector operator and
+-- pg_catalog for built-ins; doctor functions don't use vectors but the
+-- inclusion is harmless and keeps every Mnestra function uniform.
+-- ====================================================================
+
+do $$
+declare
+  fn record;
+  sig text;
+begin
+  for fn in
+    select n.nspname,
+           p.proname,
+           pg_get_function_identity_arguments(p.oid) as ident_args
+      from pg_proc p
+      join pg_namespace n on n.oid = p.pronamespace
+     where n.nspname = 'public'
+       and p.prokind = 'f'
+       and (
+         p.proname like 'memory_%'
+         or p.proname in ('match_memories', 'expand_memory_neighborhood')
+         or p.proname like 'mnestra_doctor_%'
+       )
+  loop
+    sig := format('%I.%I(%s)', fn.nspname, fn.proname, fn.ident_args);
+    execute format('revoke execute on function %s from public, anon, authenticated', sig);
+    execute format('alter function %s set search_path = public, extensions, pg_catalog', sig);
+    -- service_role keeps EXECUTE; the revoke above only targets public/anon/authenticated.
+  end loop;
+end $$;
+
+-- ====================================================================
+-- 4. Recreate mnestra_recent_activity view without SECURITY DEFINER and
+-- restrict SELECT to service_role. Skipped silently if the view doesn't
+-- exist or any of the three underlying tables are missing.
+-- ====================================================================
+
+do $$
+begin
+  if to_regclass('public.mnestra_session_memory') is not null
+     and to_regclass('public.mnestra_project_memory') is not null
+     and to_regclass('public.mnestra_developer_memory') is not null
+  then
+    drop view if exists public.mnestra_recent_activity;
+
+    execute $view$
+      create view public.mnestra_recent_activity as
+        select 'session'::text as layer, id, session_id, event_type, payload, project, developer_id, "timestamp", created_at from public.mnestra_session_memory
+        union all
+        select 'project'::text as layer, id, session_id, event_type, payload, project, developer_id, "timestamp", created_at from public.mnestra_project_memory
+        union all
+        select 'developer'::text as layer, id, session_id, event_type, payload, project, developer_id, "timestamp", created_at from public.mnestra_developer_memory
+        order by 8 desc
+        limit 100
+    $view$;
+
+    revoke all on public.mnestra_recent_activity from public, anon, authenticated;
+    grant select on public.mnestra_recent_activity to service_role;
+  end if;
+end $$;
+
+-- ====================================================================
+-- Post-apply verification (run separately in Studio SQL editor):
+--
+--   -- Should return zero rows:
+--   with bad_policies as (
+--     select policyname from pg_policies
+--      where schemaname='public' and tablename like 'mnestra_%'
+--        and ('public' = any(roles) or roles = '{}')
+--        and (with_check='true' or qual='true')
+--   ),
+--   public_exec as (
+--     select p.proname from pg_proc p join pg_namespace n on n.oid=p.pronamespace
+--      where n.nspname='public'
+--        and (p.proname like 'mnestra_doctor_%' or p.proname like 'memory_%'
+--             or p.proname in ('match_memories','expand_memory_neighborhood'))
+--        and has_function_privilege('public', p.oid, 'EXECUTE')
+--   ),
+--   mutable_path as (
+--     select p.proname from pg_proc p join pg_namespace n on n.oid=p.pronamespace
+--      where n.nspname='public' and p.prokind='f'
+--        and (p.proname like 'memory_%' or p.proname like 'mnestra_doctor_%')
+--        and not exists (
+--          select 1 from unnest(coalesce(p.proconfig,'{}'::text[])) c
+--          where c like 'search_path=%'
+--        )
+--   )
+--   select 'BAD_POLICY' as kind, policyname as detail from bad_policies
+--   union all select 'PUBLIC_EXEC', proname from public_exec
+--   union all select 'MUTABLE_SEARCH_PATH', proname from mutable_path;
+--
+-- Verified zero rows on the reference Mnestra project on 2026-05-06.
+-- Smoke test: select count(*) from memory_hybrid_search('smoke', array_fill(0::real, ARRAY[1536])::vector, 1) → 1 row, no operator-resolution error.
+-- ====================================================================

package/packages/server/src/setup/mnestra-migrations/020_migration_tracking.sql

@@ -0,0 +1,57 @@
+-- 020_migration_tracking.sql
+-- Adds durable tracking of which Mnestra migrations have been applied to a project,
+-- so upgrade paths can compute (bundled - applied) and apply only the diff.
+-- Sprint 61 (TermDeck Convergence Keystone), Mnestra 0.4.7.
+--
+-- Why this exists: prior to 020, the mnestra/rumen wizards re-applied every
+-- bundled migration on every invocation, relying on per-migration
+-- `IF NOT EXISTS` / `CREATE OR REPLACE` idempotency to avoid duplicate work.
+-- That works for a fresh install but doesn't tell the wizard which migrations
+-- the live database is missing — so a user running `npm install -g @latest`
+-- against an existing project gets the new package files without any way to
+-- detect schema drift. Class A (schema drift on package upgrade) per
+-- termdeck/docs/INSTALLER-PITFALLS.md.
+--
+-- Shape:
+--   - `filename`        text PK — the bundled migration filename, e.g.
+--                                 `015_source_agent.sql`. PK because each
+--                                 bundled file applies at most once.
+--   - `applied_at`      timestamptz — wall-clock time of apply. Backfilled
+--                                 rows (rows seeded by the post-020 backfill
+--                                 probe for migrations applied pre-020) use
+--                                 epoch (1970-01-01T00:00:00Z) as a sentinel.
+--   - `checksum`        text — SHA-256 of the bundled file content at apply
+--                                 time. Lets future runs detect bundle drift
+--                                 without auto-overwriting the live schema.
+--   - `schema_version`  text — optional free-text marker. Backfill rows use
+--                                 the literal `'backfill'` so audit queries
+--                                 can distinguish them.
+--
+-- RLS posture: ENABLE ROW LEVEL SECURITY + REVOKE ALL FROM PUBLIC. No
+-- policies are intentional — anon and authenticated have NO access, full
+-- stop. service_role bypasses RLS in Postgres by default, which is the only
+-- caller that should ever touch this table (the migration runner connects
+-- via DATABASE_URL using service-role credentials).
+--
+-- Idempotent: re-applying this migration on a project that already has the
+-- table is a no-op (CREATE TABLE IF NOT EXISTS, ALTER TABLE ... ENABLE RLS
+-- is a no-op when already enabled, REVOKE/GRANT are idempotent).
+
+CREATE TABLE IF NOT EXISTS public.mnestra_migrations (
+  filename       text PRIMARY KEY,
+  applied_at     timestamptz NOT NULL DEFAULT now(),
+  checksum       text NOT NULL,
+  schema_version text
+);
+
+ALTER TABLE public.mnestra_migrations ENABLE ROW LEVEL SECURITY;
+
+-- Service-role-only. anon and authenticated have NO access (no policies = denied by RLS).
+-- Service role bypasses RLS by default; the table is queried only by the migration runner
+-- which uses the service-role key.
+
+REVOKE ALL ON public.mnestra_migrations FROM PUBLIC;
+GRANT  ALL ON public.mnestra_migrations TO service_role;
+
+COMMENT ON TABLE public.mnestra_migrations IS
+  'Tracking table for applied Mnestra migrations. service_role-only; RLS-on; no policies.';

package/packages/server/src/setup/mnestra-migrations/021_project_tag_canonicalize_claimguard.sql

@@ -0,0 +1,175 @@
+-- 021_project_tag_canonicalize_claimguard.sql
+-- Sprint 62 T2 — finishes the gorgias / gorgias-ticket-monitor → claimguard
+-- rename that migration 012 (Sprint 41 T2) explicitly scoped out.
+--
+-- Why this exists:
+--   Same project (the ClaimGuard repo at ~/Documents/Unagi/gorgias-ticket-monitor)
+--   was tagged three ways across history. As of 2026-05-08:
+--     - 'claimguard'              ~29 rows  (newest tag, written by the
+--                                            post-Sprint-41 PROJECT_MAP)
+--     - 'gorgias-ticket-monitor' ~245 rows  (mid tag, the on-disk dir name)
+--     - 'gorgias'                ~541 rows  (oldest tag, pre-Sprint-41)
+--
+--   Migration 012's §"What this migration does NOT do" called out the merge
+--   as a separate cleanup pass:
+--
+--     - Does NOT consolidate duplicate tags like 'gorgias' vs
+--       'gorgias-ticket-monitor', 'pvb' vs 'PVB', or 'mnestra' vs 'engram'.
+--       Visible in `SELECT project, count(*) FROM memory_items GROUP BY
+--       project` but a separate cleanup pass.
+--
+--   That separate pass is 021. Sprint 21 T2's earlier rename plan never
+--   landed; Sprint 35's harness-hook fix addressed the upstream PROJECT_MAP
+--   so new rows tag correctly, and Sprint 62 T2 (this migration) closes the
+--   historical-corpus gap so memory_recall(project="claimguard") returns the
+--   full ~815-row history rather than just the post-Sprint-41 tail.
+--
+-- The companion T2 invariant test at
+-- termdeck/tests/project-tag-invariant.test.js currently skips the claimguard
+-- invariant via `deferredToSprint35`; with 021 applied that invariant would
+-- pass cleanly if un-deferred. Un-deferring is out of T2's lane (test edits
+-- are owned by orchestrator close-out).
+--
+-- Why the *project*-column merge and not a content-keyword rebucket: rows
+-- already-tagged 'gorgias' or 'gorgias-ticket-monitor' carry definitive
+-- project provenance — the row is from the ClaimGuard project by virtue of
+-- the writer's prior tag, regardless of content keywords. We are not
+-- inferring; we are renaming an exact-match tag set that the SOURCE-BRIEF
+-- and 012's prologue both confirm refer to the same on-disk codebase.
+--
+-- Idempotence:
+--   The UPDATE is gated by `WHERE project IN ('gorgias','gorgias-ticket-monitor')`.
+--   After the first apply those rows carry project='claimguard', so a re-run
+--   matches zero rows — RAISE NOTICE prints 0 and the migration succeeds. The
+--   bundled migration runner (packages/server/src/setup/migration-runner.js)
+--   also checksums applied migrations into mnestra_migrations (table from
+--   020) and skips re-application by filename, so the in-runner path is
+--   idempotent at two layers.
+--
+-- RLS posture:
+--   memory_items has RLS enabled (per migration 019 security hardening), but
+--   service_role bypasses RLS. The migration runner authenticates as
+--   service_role via DATABASE_URL, so the UPDATE lands without policy
+--   changes. This migration does NOT touch policies or roles.
+--
+-- Reversibility:
+--   Down-migration is documented at the bottom (commented). Splitting the
+--   merged set back into three is destructive — once project='claimguard'
+--   replaces the prior values, the row provenance for which tag it ORIGINALLY
+--   carried is gone (no audit column tracks pre-image). Reversal requires
+--   restore from a pg_dump snapshot taken before the migration was applied.
+--   Do NOT attempt heuristic reversal.
+--
+-- Application:
+--   Applied via the bundled migration runner using node-postgres
+--   client.query(). DO blocks + GET DIAGNOSTICS ROW_COUNT (no psql
+--   metacommands — \gset / \echo / etc are not supported in client.query).
+--   Manual fallback: `psql "$DATABASE_URL" -f 021_project_tag_canonicalize_claimguard.sql`.
+
+BEGIN;
+
+-- ============================================================
+-- AUDIT BEFORE
+-- ============================================================
+DO $$
+DECLARE
+  before_claimguard               int;
+  before_gorgias                  int;
+  before_gorgias_ticket_monitor   int;
+  before_total_three              int;
+BEGIN
+  SELECT count(*) INTO before_claimguard
+    FROM public.memory_items WHERE project = 'claimguard';
+  SELECT count(*) INTO before_gorgias
+    FROM public.memory_items WHERE project = 'gorgias';
+  SELECT count(*) INTO before_gorgias_ticket_monitor
+    FROM public.memory_items WHERE project = 'gorgias-ticket-monitor';
+  before_total_three := before_claimguard + before_gorgias + before_gorgias_ticket_monitor;
+  RAISE NOTICE '[021-canonicalize] BEFORE  claimguard=% gorgias=% gorgias-ticket-monitor=%  (sum=%)',
+    before_claimguard, before_gorgias, before_gorgias_ticket_monitor, before_total_three;
+END $$;
+
+-- ============================================================
+-- CANONICALIZE — gorgias + gorgias-ticket-monitor → claimguard
+--
+-- Single-statement UPDATE on the project column. No content scoping required:
+-- the source tags refer unambiguously to the ClaimGuard project per Sprint 41
+-- T2's analysis (012's prologue) and the SOURCE-BRIEF for Sprint 62 §1.
+-- ============================================================
+DO $$
+DECLARE
+  affected_count integer;
+BEGIN
+  UPDATE public.memory_items
+     SET project = 'claimguard'
+   WHERE project IN ('gorgias', 'gorgias-ticket-monitor');
+  GET DIAGNOSTICS affected_count = ROW_COUNT;
+  RAISE NOTICE '[021-canonicalize] canonicalized % memory_items rows  (gorgias + gorgias-ticket-monitor) -> claimguard',
+    affected_count;
+END $$;
+
+-- ============================================================
+-- AUDIT AFTER + CONSERVATION CHECK
+-- ============================================================
+DO $$
+DECLARE
+  after_claimguard               int;
+  after_gorgias                  int;
+  after_gorgias_ticket_monitor   int;
+BEGIN
+  SELECT count(*) INTO after_claimguard
+    FROM public.memory_items WHERE project = 'claimguard';
+  SELECT count(*) INTO after_gorgias
+    FROM public.memory_items WHERE project = 'gorgias';
+  SELECT count(*) INTO after_gorgias_ticket_monitor
+    FROM public.memory_items WHERE project = 'gorgias-ticket-monitor';
+  RAISE NOTICE '[021-canonicalize] AFTER   claimguard=% gorgias=% gorgias-ticket-monitor=%',
+    after_claimguard, after_gorgias, after_gorgias_ticket_monitor;
+  IF after_gorgias <> 0 OR after_gorgias_ticket_monitor <> 0 THEN
+    RAISE EXCEPTION
+      '[021-canonicalize] post-apply invariant violated: expected zero rows in gorgias / gorgias-ticket-monitor, got gorgias=% gorgias-ticket-monitor=%',
+      after_gorgias, after_gorgias_ticket_monitor;
+  END IF;
+END $$;
+
+COMMIT;
+
+-- ============================================================
+-- POST-APPLY: verification queries (NOT part of the migration; run separately
+-- to confirm the merge took, the invariant tests stay green, and the recall
+-- path returns the full history). Each query is safe to run repeatedly.
+-- ============================================================
+--
+-- 1. Tag distribution after migration — claimguard should be the only
+--    bucket among the three; gorgias / gorgias-ticket-monitor should be 0:
+--      SELECT project, count(*) FROM public.memory_items
+--       WHERE project IN ('claimguard', 'gorgias', 'gorgias-ticket-monitor')
+--       GROUP BY project ORDER BY project;
+--
+-- 2. Confirm no orphan rows remain under either legacy tag (these should
+--    return 0):
+--      SELECT count(*) FROM public.memory_items
+--       WHERE project IN ('gorgias', 'gorgias-ticket-monitor');
+--
+-- 3. Spot-check that the merged set carries content from all three
+--    historical eras (look for varied dates, varied source_types):
+--      SELECT date_trunc('week', created_at) AS week, count(*)
+--        FROM public.memory_items
+--       WHERE project = 'claimguard'
+--       GROUP BY 1 ORDER BY 1;
+--
+-- 4. Confirm the project-tag invariant test for claimguard would now pass
+--    if un-deferred (rows whose content matches gorgias-ticket-monitor or
+--    Unagi/ identifiers should be top-tagged claimguard):
+--      SELECT project, count(*) FROM public.memory_items
+--       WHERE content ILIKE '%gorgias-ticket-monitor%'
+--          OR content ILIKE '%Unagi/%'
+--       GROUP BY project ORDER BY count(*) DESC LIMIT 5;
+--
+-- DOWN-MIGRATION (manual, NOT auto-applied):
+--   Splitting the merged set back into three is non-trivial (no source-of-
+--   truth on which rows were originally which tag — provenance is lost when
+--   the UPDATE replaces the project string). If a roll-back is needed,
+--   restore from a pg_dump taken before this migration was applied. Do NOT
+--   attempt to reverse via heuristic — the row provenance is destroyed by
+--   the merge.

package/packages/server/src/setup/mnestra-migrations/022_source_agent_backfill.sql

@@ -0,0 +1,182 @@
+-- 022_source_agent_backfill.sql
+-- Sprint 62 T3 (TermDeck) — backfill source_agent for pre-Sprint-50 NULL rows
+-- where the writer can be inferred from row shape, NOT from content content-marker
+-- inspection. Mnestra 0.4.9 (release-pending; orchestrator bumps at sprint close).
+--
+-- Why this exists:
+--   Sprint 50 introduced source_agent (migration 015). Pre-Sprint-50 rows
+--   have source_agent IS NULL and are silently excluded from filtered
+--   memory_recall queries (per the recall tool's docstring: "NULL-source-
+--   agent rows ... are excluded when this filter is set" — see
+--   src/recall.ts:165-169).
+--
+--   2026-05-08 production probe: 6,381 of 6,483 active memory_items rows
+--   (~98%) have source_agent IS NULL — far above the SOURCE-BRIEF estimate
+--   of "3,000+". Filtered recall has been blind to most of the corpus for
+--   roughly the entire post-Sprint-50 window.
+--
+--   Migration 015 already backfilled session_summary NULL rows -> 'claude'
+--   (015 lines 48-51), so the NULL universe today is exclusively non-
+--   session_summary types. This migration closes the slice where the
+--   writer can be inferred from row shape (architectural / schema /
+--   structural evidence), and deliberately leaves the remaining slice
+--   NULL — to be reached via the additive include_null_source recall
+--   flag rather than by speculative attribution.
+--
+-- Design principle: row-shape attribution, not content-marker attribution.
+--   The original SOURCE-BRIEF proposed content-marker predicates (ILIKE
+--   '%[T-CODEX]%' etc). Sampling proved this unsafe: 100% of NULL rows
+--   matching codex/gemini/grok markers are Claude *describing* those
+--   agents, never authored by them. Marker == "row mentions agent",
+--   not "row authored by agent".
+--
+--   Instead, this migration attributes by the (source_type, has_path,
+--   has_session) tuple — schema-level fingerprints that map 1:1 to the
+--   writer architecture, and that 50+ randomly-sampled rows confirm.
+--
+-- Predicate plan (each with explicit evidence chain):
+--
+--   A. NULL + source_type IN (decision, bug_fix, architecture, preference,
+--      code_context) -> 'claude'.
+--      Architectural evidence: pre-Sprint-50, only Claude shipped a
+--      memory_remember client. The mcp__memory__memory_remember and
+--      mcp__mnestra__memory_remember surfaces both ran exclusively in
+--      Claude sessions. Codex/Gemini/Grok memory_remember capabilities
+--      did not exist until the Sprint 51 per-agent MCP wiring (see
+--      memory: "MCP server wiring patterns for Codex, Gemini, and Grok
+--      CLIs (verified 2026-05-04 ... follow-up to Sprint 51.6's "Codex
+--      MCP not wired" gap)"). All NULL rows of these source_types are
+--      pre-Sprint-50 and therefore architecturally Claude.
+--      Schema fingerprint: 100% of these rows have source_file_path IS NULL
+--      AND source_session_id IS NULL — bare memory_remember shape.
+--      Sample confirmation: 28-row sample showed 100% Claude-summary writing
+--      pattern (project context, dated entries, file:line evidence — the
+--      recognizable Claude memory_remember signature).
+--      Expected count: 560.
+--
+--   B. NULL + source_type='fact' + source_session_id IS NOT NULL -> 'claude'.
+--      Schema evidence: source_session_id is a Claude session UUID format
+--      (matches the existing claude/session_summary tagged rows; same
+--      shape: has_path=false, has_session=true). The Claude SessionEnd
+--      hook is the only writer that populates source_session_id with a
+--      Claude UUID. Other writers either set source_file_path (rag-extractor)
+--      or leave both NULL (bare memory_remember).
+--      Expected count: 4,587.
+--
+--   D. NULL + source_type='document_chunk' -> 'orchestrator'.
+--      Structural evidence: 951/951 rows have source_file_path set + JSONB
+--      metadata containing chunkIndex + heading keys — unmistakable
+--      rag-system batch-chunker output. The chunker is not an LLM session;
+--      'orchestrator' is the appropriate non-LLM tag per the source_agent
+--      enum (claude|codex|gemini|grok|orchestrator).
+--      Path buckets:
+--        513 rows ~/.gemini/antigravity/scratch/* (Gemini scratch docs the
+--                 rag-extractor ingested — Gemini wrote the source MD,
+--                 but the rag-extractor wrote the row.)
+--        429 rows ~/Documents/* (project docs ingested directly).
+--          9 rows ~/.claude/projects/*/memory/MEMORY.md (auto-memory MD
+--                 ingested by the rag-extractor).
+--      All four buckets are extractor-written, not LLM-written. The
+--      original document author is preserved in source_file_path; the
+--      row writer is the extractor.
+--      Expected count: 951.
+--
+-- Predicate deliberately NOT applied (response to T4-CODEX 20:43 ET concern):
+--   C. NULL + source_type='fact' + source_session_id IS NULL +
+--      source_file_path IS NULL.
+--      These 283 rows are bare memory_remember calls without session
+--      attribution. Sampling (10 rows) showed 100% Claude content pattern,
+--      but they lack the schema fingerprint that makes A/B/D structurally
+--      definitive — there is no architectural lock that PREVENTS a
+--      non-Claude writer from producing this shape (e.g., a manual psql
+--      insert, a non-MCP REST call, or an early rag-extractor variant
+--      that omitted source_file_path).
+--      Migration 015 lines 24-30 explicitly preserved provenance
+--      uncertainty for non-session_summary historical rows; broad
+--      attribution here would erase that bright line. Per T4-CODEX
+--      AUDIT-CONCERN (Sprint 62, 20:43 ET), these rows stay NULL and
+--      are reached via the additive include_null_source recall path
+--      added in src/recall.ts under this same sprint.
+--      Residual NULL after this migration: 283 rows = 4.4% of corpus.
+--      Acceptance target: <5%. Met.
+--
+-- Total backfill: 6,098 rows (A + B + D). Acceptance: residual NULL < 5%
+-- of corpus (4.4% expected; well under threshold).
+--
+-- What this migration deliberately does NOT do:
+--   * Touch session_summary rows (015 already attributed those).
+--   * Touch already-tagged rows (every UPDATE is gated by source_agent IS NULL).
+--   * Use content-marker predicates (sampling proved unreliable; markers
+--     describe agents, not authors).
+--   * Backfill the inferential-only slice (Predicate C, see above).
+--
+-- Idempotent: every UPDATE has WHERE source_agent IS NULL, so re-running
+-- is a no-op on already-tagged rows. Safe to re-apply.
+--
+-- Reversibility: this migration tags rows but does not modify content,
+-- type, or any other column. To revert (in a future migration), run:
+--   UPDATE public.memory_items
+--      SET source_agent = NULL
+--    WHERE source_agent IN ('claude', 'orchestrator')
+--      AND created_at < '2026-05-09'
+--      AND source_type != 'session_summary';  -- preserve 015's backfill
+--
+-- RLS posture (per global CLAUDE.md RLS hygiene gates 1-5): this is a
+-- DO block, not a CREATE FUNCTION. Runs as the migration runner's role
+-- (service_role, which bypasses RLS). search_path is set explicitly to
+-- defend against schema-shadow attacks during execution. No new policies,
+-- no new function executable surface.
+
+set search_path = public, pg_catalog;
+
+do $$
+declare
+  pred_a integer := 0;
+  pred_b integer := 0;
+  pred_d integer := 0;
+  remaining integer;
+  total_rows integer;
+begin
+  -- Predicate A: structural attribution by source_type for non-fact, non-document_chunk
+  -- types. Architectural lock: pre-Sprint-50 only Claude shipped a memory_remember
+  -- client. NULL rows of these types are therefore unambiguously Claude.
+  update public.memory_items
+     set source_agent = 'claude'
+   where source_agent is null
+     and source_type in ('decision', 'bug_fix', 'architecture', 'preference', 'code_context');
+  get diagnostics pred_a = row_count;
+
+  -- Predicate B: fact rows with Claude-session attribution. source_session_id
+  -- is the Claude SessionEnd hook's UUID; same shape as the existing tagged
+  -- claude/session_summary rows.
+  update public.memory_items
+     set source_agent = 'claude'
+   where source_agent is null
+     and source_type = 'fact'
+     and source_session_id is not null;
+  get diagnostics pred_b = row_count;
+
+  -- Predicate D: rag-system document chunks -> 'orchestrator' (non-LLM batch writer).
+  -- All 951 rows carry source_file_path + chunkIndex/heading metadata — the
+  -- rag-extractor's deterministic fingerprint.
+  update public.memory_items
+     set source_agent = 'orchestrator'
+   where source_agent is null
+     and source_type = 'document_chunk';
+  get diagnostics pred_d = row_count;
+
+  select count(*) into remaining
+    from public.memory_items
+   where source_agent is null;
+
+  select count(*) into total_rows from public.memory_items;
+
+  raise notice '[022] backfill complete: A(claude/typed)=% B(claude/fact+session)=% D(orchestrator/doc_chunk)=% remaining_null=% / % total (acceptance: <5%%)',
+    pred_a, pred_b, pred_d, remaining, total_rows;
+  raise notice '[022] residual NULL = bare memory_remember fact rows (no session, no path); reach via include_null_source recall flag';
+end$$;
+
+-- Refresh the column comment to reflect 015 + 022 together as the partial-
+-- backfill story, and document the residual + the recall flag escape hatch.
+comment on column public.memory_items.source_agent is
+  'Agent that produced this memory: claude|codex|gemini|grok|orchestrator|NULL. Populated at write time by per-agent SessionEnd writers from Sprint 50 onward. Pre-Sprint-50 NULL rows backfilled by migration 015 (session_summary -> claude) and migration 022 (decision/bug_fix/architecture/preference/code_context -> claude; fact w/ source_session_id -> claude; document_chunk -> orchestrator). Residual NULL = bare-call fact rows without session or path attribution; intentionally preserved per migration 015''s provenance bright line. Reach those via memory_recall include_null_source=true.';