spine-framework 0.3.144 → 0.4.0

package/.framework/migrations/046_security_missing_rls.sql

@@ -0,0 +1,79 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/046_security_missing_rls.sql:security_missing_rls:file" type="file" identity="security_missing_rls" parent="~/.framework/migrations/046_security_missing_rls.sql"]
+-- CIL[DOC-MACRO purpose="Enable RLS on the nine tables that currently expose all rows to any PostgREST caller"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Enable row level security on account_paths, invites, alerts, observability, integration_routes, test_runs, test_cases, test_results, and _spine_migrations with policies matching each table's intended consumer"]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/migrations/006_security_hardening_rls.sql,.framework/migrations/045_security_critical_rls.sql,.framework/migrations/035_rate_limits.sql"]
+-- CIL[DOC-CONTRACT inputs="none" outputs="RLS enabled + policies created" errors="SQL errors if referenced objects are missing" side_effects="Blocks direct PostgREST reads/writes previously allowed by missing RLS"]
+-- CIL[DOC-MICRO logic_summary="account_paths is system-admin read (get_accessible_accounts SECURITY DEFINER still serves all lookups); invites/alerts/observability get account-scoped access on account_id; integration_routes/test_*/_spine_migrations are service_role-only infrastructure with no tenant use case" notable_decisions="all existing consumers use adminDb which bypasses RLS entirely — these policies only gate direct PostgREST access via the anon/user keys; service_role policies are declared explicitly for documentation even though service_role holds BYPASSRLS"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+-- account_paths: the tenant-hierarchy closure table. Reading it directly
+-- reveals every parent/child relationship without going through
+-- get_accessible_accounts(). That SECURITY DEFINER function continues to serve
+-- all legitimate lookups; direct reads are system-admin only.
+ALTER TABLE public.account_paths ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY account_paths_read ON public.account_paths FOR SELECT
+  USING (public.person_is_system_admin(public.current_actor_id()));
+
+CREATE POLICY account_paths_service_role ON public.account_paths FOR ALL
+  TO service_role USING (true) WITH CHECK (true);
+
+-- invites: invitation metadata is scoped to the issuing account. Invite tokens
+-- themselves live on people.data (validated server-side via adminDb), so
+-- account-scoped access covers admin list/revoke without exposing tokens.
+ALTER TABLE public.invites ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY invites_access ON public.invites FOR ALL
+  USING (account_id IN (SELECT public.get_accessible_accounts(public.current_actor_id())))
+  WITH CHECK (account_id IN (SELECT public.get_accessible_accounts(public.current_actor_id())));
+
+CREATE POLICY invites_service_role ON public.invites FOR ALL
+  TO service_role USING (true) WITH CHECK (true);
+
+-- alerts: account-scoped operational alerts.
+ALTER TABLE public.alerts ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY alerts_access ON public.alerts FOR ALL
+  USING (account_id IN (SELECT public.get_accessible_accounts(public.current_actor_id())))
+  WITH CHECK (account_id IN (SELECT public.get_accessible_accounts(public.current_actor_id())));
+
+CREATE POLICY alerts_service_role ON public.alerts FOR ALL
+  TO service_role USING (true) WITH CHECK (true);
+
+-- observability: account-scoped telemetry (agent runs, traces). Written only
+-- via adminDb; account members can read their own telemetry.
+ALTER TABLE public.observability ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY observability_access ON public.observability FOR ALL
+  USING (account_id IN (SELECT public.get_accessible_accounts(public.current_actor_id())))
+  WITH CHECK (account_id IN (SELECT public.get_accessible_accounts(public.current_actor_id())));
+
+CREATE POLICY observability_service_role ON public.observability FOR ALL
+  TO service_role USING (true) WITH CHECK (true);
+
+-- test_runs / test_cases / test_results / _spine_migrations:
+-- internal infrastructure consumed exclusively by adminDb in system-cron.ts,
+-- tests.ts, system.ts, and cli. No tenant-facing use case — service_role only
+-- (matching the rate_limits precedent in 035). integration_routes is not
+-- covered — 004 drops it as dead schema.
+ALTER TABLE public.test_runs ENABLE ROW LEVEL SECURITY;
+CREATE POLICY test_runs_service_role ON public.test_runs FOR ALL
+  TO service_role USING (true) WITH CHECK (true);
+
+ALTER TABLE public.test_cases ENABLE ROW LEVEL SECURITY;
+CREATE POLICY test_cases_service_role ON public.test_cases FOR ALL
+  TO service_role USING (true) WITH CHECK (true);
+
+ALTER TABLE public.test_results ENABLE ROW LEVEL SECURITY;
+CREATE POLICY test_results_service_role ON public.test_results FOR ALL
+  TO service_role USING (true) WITH CHECK (true);
+
+ALTER TABLE public._spine_migrations ENABLE ROW LEVEL SECURITY;
+CREATE POLICY spine_migrations_service_role ON public._spine_migrations FOR ALL
+  TO service_role USING (true) WITH CHECK (true);
+-- CIL[DOC-VECTOR type="context" content="purpose='Enable RLS on nine tables that were fully exposed to PostgREST.'; No verified external callers; imports: none"]
+-- CIL[DOC-VECTOR type="blast_radius" content="Direct PostgREST access to account_paths/invites/alerts/observability/integration_routes/test_*/_spine_migrations is now gated; adminDb consumers unaffected (service_role bypasses RLS)" status="ready"]
+-- CIL[DOC-VECTOR type="configuration" content="Depends on public.current_actor_id, public.person_is_system_admin, public.get_accessible_accounts; requires account_id column on invites/alerts/observability" status="ready"]
+-- CIL[DOC-VECTOR type="constraint" content="Any client that read these tables via anon/user keys must move to a function path or accept denial" status="ready"]
+-- CIL[END stable_id="~/.framework/migrations/046_security_missing_rls.sql:security_missing_rls:file"]

package/.framework/migrations/047_people_updated_by.sql

@@ -0,0 +1,27 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/047_people_updated_by.sql:people_updated_by:file" type="file" identity="people_updated_by" parent="~/.framework/migrations/047_people_updated_by.sql"]
+-- CIL[DOC-MACRO purpose="Add updated_by to entity tables missing it so admin-data PATCH stops failing for human callers"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Add nullable uuid updated_by columns to people, watchers, and attachments — the three entity tables that follow the created_by/updated_by audit convention but lacked the column"]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/functions/admin-data.ts,.framework/migrations/045_security_critical_rls.sql,.framework/migrations/046_security_missing_rls.sql"]
+-- CIL[DOC-CONTRACT inputs="none" outputs="Three new nullable uuid columns" errors="none — add column if not exists is idempotent" side_effects="Enables admin-data to stamp updated_by on PATCH for people/watchers/attachments"]
+-- CIL[DOC-MICRO logic_summary="admin-data's update handler unconditionally writes updated_by for every non-raw entity; PATCH on these three tables failed with a schema-cache error for human callers. Column shape matches sibling tables (items/accounts/threads/messages/links): nullable uuid, no FK — created_by/updated_by across the schema are plain uuid markers, not enforced references" notable_decisions="nullable and unindexed because no read path queries by updated_by today; kept people/watchers/attachments together since they share the identical gap"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+-- Migration 047: add updated_by to entity tables that follow the created_by/
+-- updated_by audit convention but are missing the column. admin-data's update
+-- handler unconditionally writes updated_by for every non-raw entity, so PATCH
+-- on people/watchers/attachments currently fails for human callers with
+-- "Could not find the 'updated_by' column ... in the schema cache".
+
+alter table public.people       add column if not exists updated_by uuid;
+alter table public.watchers     add column if not exists updated_by uuid;
+alter table public.attachments  add column if not exists updated_by uuid;
+
+comment on column public.people.updated_by      is 'Person id of the last updater; written by admin-data update handler';
+comment on column public.watchers.updated_by    is 'Person id of the last updater; written by admin-data update handler';
+comment on column public.attachments.updated_by is 'Person id of the last updater; written by admin-data update handler';
+-- CIL[DOC-VECTOR type="context" content="purpose='Fix admin-data PATCH failures on people/watchers/attachments by adding the missing updated_by column.'; No verified external callers; imports: none"]
+-- CIL[DOC-VECTOR type="blast_radius" content="Human-caller updates via admin-data to people (user settings modal), watchers, and attachments now succeed instead of failing with a schema-cache error" status="ready"]
+-- CIL[DOC-VECTOR type="configuration" content="None — plain ALTER TABLE; admin-data update handler consumes the column automatically" status="ready"]
+-- CIL[DOC-VECTOR type="constraint" content="Column is a plain uuid marker with no FK, matching the created_by convention across the schema" status="ready"]
+-- CIL[END stable_id="~/.framework/migrations/047_people_updated_by.sql:people_updated_by:file"]

package/.framework/migrations/048_watcher_last_seen_at.sql

@@ -0,0 +1,24 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/048_watcher_last_seen_at.sql:watcher_last_seen_at:file" type="file" identity="watcher_last_seen_at" parent="~/.framework/migrations/048_watcher_last_seen_at.sql"]
+-- CIL[DOC-MACRO purpose="Declare last_seen_at in the watcher type design_schema so read sanitize and update validation accept it"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Merge the last_seen_at field definition into the watcher type's design_schema.fields and validation_schema.fields"]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/functions/_shared/permissions.ts,custom/apps/*/hooks/useWatchers.ts"]
+-- CIL[DOC-CONTRACT inputs="none" outputs="watcher type accepts data.last_seen_at on read/write" errors="none — jsonb_set with create_missing is idempotent" side_effects="Unread tracking (markSeen/hasUnreadActivity) works for watcher rows"]
+-- CIL[DOC-MICRO logic_summary="sanitizeRecordData strips data keys not declared in design_schema.fields on read, and validateUpdatePermissions rejects them on PATCH — so watcher.data.last_seen_at (written by downstream markSeen hooks) was dropped both ways. Declaring the field makes it readable and writable for roles with record update (member, support). Non-system field: system fields are record columns, last_seen_at lives in data." notable_decisions="type rows are global (kind+slug unique) so updating the single watcher row covers every account"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+update public.types
+set design_schema = jsonb_set(
+      design_schema,
+      '{fields,last_seen_at}',
+      '{"data_type":"datetime","label":"Last Seen","required":false,"validation":null}'::jsonb,
+      true
+    ),
+    validation_schema = jsonb_set(
+      coalesce(validation_schema, '{"fields":{}}'::jsonb),
+      '{fields,last_seen_at}',
+      '{"data_type":"datetime","required":false}'::jsonb,
+      true
+    )
+where kind = 'watcher' and slug = 'watcher';
+-- CIL[END stable_id="~/.framework/migrations/048_watcher_last_seen_at.sql:watcher_last_seen_at:file"]

package/.framework/migrations/049_security_blocklist.sql

@@ -0,0 +1,148 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/049_security_blocklist.sql:security_blocklist:file" type="file" identity="security_blocklist" parent="~/.framework/migrations/049_security_blocklist.sql"]
+-- CIL[DOC-MACRO purpose="Platform security layer: security_blocklist table, person geo RPCs, and schema declarations for security fields"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Create public.security_blocklist (platform-wide denylist for person/account/email/email_domain/ip), person_touch_geo + person_record_registration_geo RPCs for IP capture, and declare registration/last-seen geo fields plus AO injection flags in the affected type design_schemas"]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/functions/_shared/security.ts,.framework/functions/_shared/middleware.ts,.framework/functions/invites.ts,.framework/functions/security.ts"]
+-- CIL[DOC-CONTRACT inputs="none" outputs="security_blocklist table, person_touch_geo + person_record_registration_geo functions, declared type fields" errors="none — CREATE IF NOT EXISTS / jsonb_set are idempotent" side_effects="Middleware geo stamping + blocklist enforcement + security admin report work"]
+-- CIL[DOC-MICRO logic_summary="Blocklist rows are (type, value) unique with severity/expiry; geo fields live in people.data so no schema change; jsonb_set declares them on the person/ao types so admin-data sanitize doesn't strip them on read" notable_decisions="RLS service_role-only: blocklist reads/writes happen exclusively through _shared/security.ts and functions/security.ts; starter disposable-domain rows seed the email_domain check"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+-- ── security_blocklist ─────────────────────────────────────────────
+-- Platform-wide denylist. Enforced at three chokepoints:
+--   registration (invites.completeRegistration), authenticated request
+--   (middleware.createHandler), public request IP (createPublicHandler).
+CREATE TABLE IF NOT EXISTS public.security_blocklist (
+  id          uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+  type        text        NOT NULL CHECK (type IN ('ip', 'email', 'email_domain', 'person_id', 'account_id')),
+  value       text        NOT NULL,
+  severity    text        NOT NULL DEFAULT 'hard' CHECK (severity IN ('soft', 'hard')),
+  reason      text,
+  banned_by   uuid,
+  expires_at  timestamptz,
+  revoked_at  timestamptz,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (type, value)
+);
+
+CREATE INDEX IF NOT EXISTS idx_security_blocklist_lookup
+  ON public.security_blocklist (type, value)
+  WHERE revoked_at IS NULL;
+
+ALTER TABLE public.security_blocklist ENABLE ROW LEVEL SECURITY;
+
+-- Service-role only: all reads/writes flow through _shared/security.ts
+-- (adminDb) and functions/security.ts (system-admin gated).
+DROP POLICY IF EXISTS security_blocklist_service_role ON public.security_blocklist;
+CREATE POLICY security_blocklist_service_role ON public.security_blocklist
+  FOR ALL TO service_role USING (true) WITH CHECK (true);
+
+-- ── person_touch_geo ───────────────────────────────────────────────
+-- Fire-and-forget last-seen geo stamp, called from middleware on every
+-- authenticated request. Single-statement merge; does not touch
+-- updated_at (record content did not change).
+CREATE OR REPLACE FUNCTION public.person_touch_geo(p_person_id uuid, p_ip text, p_country text)
+RETURNS void
+LANGUAGE sql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  UPDATE public.people
+  SET data = data || jsonb_build_object(
+    'last_ip', p_ip,
+    'last_country', p_country,
+    'last_seen_at', now()
+  )
+  WHERE id = p_person_id;
+$$;
+
+REVOKE ALL ON FUNCTION public.person_touch_geo(uuid, text, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.person_touch_geo(uuid, text, text) FROM anon;
+REVOKE ALL ON FUNCTION public.person_touch_geo(uuid, text, text) FROM authenticated;
+GRANT EXECUTE ON FUNCTION public.person_touch_geo(uuid, text, text) TO service_role;
+
+-- ── person_record_registration_geo ─────────────────────────────────
+-- First-seen geo stamp, called from invites.completeRegistration.
+-- COALESCE keeps the FIRST recorded values (a later registration attempt
+-- must not overwrite the original signup IP).
+CREATE OR REPLACE FUNCTION public.person_record_registration_geo(p_person_id uuid, p_ip text, p_country text)
+RETURNS void
+LANGUAGE sql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  UPDATE public.people
+  SET data = data || jsonb_build_object(
+    'registration_ip', coalesce(data->>'registration_ip', p_ip),
+    'registration_country', coalesce(data->>'registration_country', p_country)
+  )
+  WHERE id = p_person_id;
+$$;
+
+REVOKE ALL ON FUNCTION public.person_record_registration_geo(uuid, text, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.person_record_registration_geo(uuid, text, text) FROM anon;
+REVOKE ALL ON FUNCTION public.person_record_registration_geo(uuid, text, text) FROM authenticated;
+GRANT EXECUTE ON FUNCTION public.person_record_registration_geo(uuid, text, text) TO service_role;
+
+-- ── Declare geo/security fields on the person type ─────────────────
+-- Without declaration, admin-data sanitizeRecordData strips these data
+-- keys on read (same failure mode as watcher.last_seen_at, migration 048).
+update public.types
+set design_schema = jsonb_set(
+      design_schema,
+      '{fields}',
+      (design_schema->'fields') || '{
+        "registration_ip":       {"data_type":"text","label":"Registration IP","required":false,"validation":null},
+        "registration_country":  {"data_type":"text","label":"Registration Country","required":false,"validation":null},
+        "last_ip":               {"data_type":"text","label":"Last IP","required":false,"validation":null},
+        "last_country":          {"data_type":"text","label":"Last Country","required":false,"validation":null},
+        "last_seen_at":          {"data_type":"datetime","label":"Last Seen","required":false,"validation":null}
+      }'::jsonb,
+      true
+    ),
+    validation_schema = jsonb_set(
+      coalesce(validation_schema, '{"fields":{}}'::jsonb),
+      '{fields}',
+      (coalesce(validation_schema, '{"fields":{}}'::jsonb)->'fields') || '{
+        "registration_ip":       {"data_type":"text","required":false},
+        "registration_country":  {"data_type":"text","required":false},
+        "last_ip":               {"data_type":"text","required":false},
+        "last_country":          {"data_type":"text","required":false},
+        "last_seen_at":          {"data_type":"datetime","required":false}
+      }'::jsonb,
+      true
+    )
+where kind = 'person' and slug = 'person';
+
+-- ── Declare injection flags on Answer Once types ───────────────────
+update public.types
+set design_schema = jsonb_set(
+      design_schema,
+      '{fields}',
+      (design_schema->'fields') || '{
+        "injection_detected": {"data_type":"boolean","label":"Injection Detected","required":false,"validation":null},
+        "injection_pattern":  {"data_type":"text","label":"Injection Pattern","required":false,"validation":null}
+      }'::jsonb,
+      true
+    ),
+    validation_schema = jsonb_set(
+      coalesce(validation_schema, '{"fields":{}}'::jsonb),
+      '{fields}',
+      (coalesce(validation_schema, '{"fields":{}}'::jsonb)->'fields') || '{
+        "injection_detected": {"data_type":"boolean","required":false},
+        "injection_pattern":  {"data_type":"text","required":false}
+      }'::jsonb,
+      true
+    )
+where slug in ('ao_ticket_message', 'ao_support_ticket');
+
+-- ── Starter disposable-email domain denylist ───────────────────────
+INSERT INTO public.security_blocklist (type, value, severity, reason)
+SELECT 'email_domain', d, 'hard', 'Disposable email provider'
+FROM (VALUES
+  ('mailinator.com'), ('tempmail.com'), ('temp-mail.org'),
+  ('guerrillamail.com'), ('10minutemail.com'), ('yopmail.com'),
+  ('maildrop.cc'), ('sharklasers.com'), ('dispostable.com'),
+  ('trashmail.com'), ('getnada.com'), ('mailnesia.com')
+) AS v(d)
+ON CONFLICT (type, value) DO NOTHING;
+-- CIL[END stable_id="~/.framework/migrations/049_security_blocklist.sql:security_blocklist:file"]

package/.framework/migrations/050_notifications.sql

@@ -0,0 +1,49 @@
+-- ── notifications: durable notification-delivery records ─────────────────────
+-- send_notification previously wrote into watchers, which is a SUBSCRIPTION
+-- table (target_type/target_id/person_id, unique per target+person) — not a
+-- delivery log. This table holds actual deliveries: one row per recipient per
+-- notification. watchers stays the "who is subscribed" record; notifications is
+-- "what was sent".
+
+CREATE TABLE IF NOT EXISTS public.notifications (
+  id           uuid        PRIMARY KEY DEFAULT gen_random_uuid(),
+  account_id   uuid        NOT NULL REFERENCES public.accounts(id),
+  person_id    uuid        NOT NULL,               -- recipient
+  source_type  text        NOT NULL DEFAULT 'pipeline_execution',
+  source_id    text,                               -- pipeline execution / request id (not always a uuid)
+  target_type  text,                               -- entity the notification concerns
+  target_id    uuid,
+  message      text        NOT NULL,
+  data         jsonb       NOT NULL DEFAULT '{}',
+  is_read      boolean     NOT NULL DEFAULT false,
+  read_at      timestamptz,
+  created_at   timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_notifications_inbox
+  ON public.notifications (account_id, person_id, is_read, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_notifications_target
+  ON public.notifications (target_type, target_id);
+
+ALTER TABLE public.notifications ENABLE ROW LEVEL SECURITY;
+
+-- Recipients read and mark-read their own notifications. Delivery inserts go
+-- through adminDb (service_role) from pipeline-runner / agent-runner.
+DROP POLICY IF EXISTS notifications_recipient_read ON public.notifications;
+CREATE POLICY notifications_recipient_read ON public.notifications FOR SELECT
+  USING (person_id = public.current_actor_id());
+
+DROP POLICY IF EXISTS notifications_recipient_update ON public.notifications;
+CREATE POLICY notifications_recipient_update ON public.notifications FOR UPDATE
+  USING (person_id = public.current_actor_id())
+  WITH CHECK (person_id = public.current_actor_id());
+
+-- Account members can see deliveries into their workspace (admin/audit views).
+DROP POLICY IF EXISTS notifications_account_read ON public.notifications;
+CREATE POLICY notifications_account_read ON public.notifications FOR SELECT
+  USING (account_id IN (SELECT public.get_accessible_accounts(public.current_actor_id())));
+
+DROP POLICY IF EXISTS notifications_service_role ON public.notifications;
+CREATE POLICY notifications_service_role ON public.notifications
+  FOR ALL TO service_role USING (true) WITH CHECK (true);

package/.framework/migrations/051_message_agent_fields.sql

@@ -0,0 +1,74 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/051_message_agent_fields.sql:message_agent_fields:file" type="file" identity="message_agent_fields" parent="~/.framework/migrations/051_message_agent_fields.sql"]
+-- CIL[DOC-MACRO purpose="Declare agent-written data keys on support_reply/community_reply so read sanitize stops stripping citations and evidence metadata"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Merge the full set of agent-runner-written data fields into the support_reply and community_reply message types' design_schema.fields and validation_schema.fields"]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/functions/_shared/permissions.ts,.framework/functions/_shared/agent-runner.ts,custom/apps/demo/views/CustomerView.tsx,custom/apps/portal/pages/TicketsPage.tsx"]
+-- CIL[DOC-CONTRACT inputs="none" outputs="support_reply/community_reply message rows (existing and new) expose cited_sources, evidence_state and tool-step keys on admin-data reads" errors="none — jsonb concat merge and restamp are idempotent" side_effects="customer transcripts render cited-source chips, the grounded badge, and step narration identically on the feed and self-poll paths"]
+-- CIL[DOC-MICRO logic_summary="agent-runner persists cited_sources/evidence_state/tools_used/tool-step keys into message.data, but sanitizeRecordData drops undeclared data.* keys for non-system-admin readers — so fetchThreadMessages silently returned retrieved_sources-only rows and CustomerView fell back to rendering all retrieved candidates as cited chips (8 chips for 1 citation). Same failure mode as watcher.last_seen_at (048) and person geo fields (049). Field shape mirrors sibling retrieved_sources: system-stamped, read-only for every record role." notable_decisions="types are global (kind+slug unique) so updating support_reply/community_reply covers demo and portal installs; ao_ticket_message already declares the full set and is skipped"]
+-- CIL[DOC-LEARNING topic="stamped_schema" content="Types gain fields on two levels: updating public.types.design_schema only helps NEW records — runtime records snapshot design_schema/validation_schema at creation and must be restamped (see scripts/restamp-ao-record-schemas.ts pattern). Separately, once a field has a validation_schema entry, admin-data display-formats it on read (formatFieldData stringifies json, booleans become 'Yes'/'No') — consumers must parse defensively"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.95" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+update public.types
+set design_schema = jsonb_set(
+      design_schema,
+      '{fields}',
+      (design_schema->'fields') || '{
+        "cited_sources":     {"data_type":"json","label":"Cited Sources","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "evidence_state":    {"data_type":"text","label":"Evidence State","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "evidence_found":    {"data_type":"boolean","label":"Evidence Found","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "mean_similarity":   {"data_type":"number","label":"Mean Similarity","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "tools_used":        {"data_type":"json","label":"Tools Used","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "human_reply":       {"data_type":"boolean","label":"Human Reply","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "tool":              {"data_type":"text","label":"Tool","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "params":            {"data_type":"json","label":"Tool Params","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "tool_call_id":      {"data_type":"text","label":"Tool Call ID","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "result":            {"data_type":"json","label":"Tool Result","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "details_truncated": {"data_type":"boolean","label":"Details Truncated","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "error":             {"data_type":"text","label":"Error","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "max_turns":         {"data_type":"number","label":"Max Turns","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "turn_count":        {"data_type":"number","label":"Turn Count","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "phase":             {"data_type":"text","label":"Phase","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "analysis_summary":  {"data_type":"textarea","label":"Analysis Summary","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "case_analysis_id":  {"data_type":"text","label":"Case Analysis ID","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}},
+        "confidence_score":  {"data_type":"number","label":"Confidence Score","system":true,"permissions":{"member":["read"],"support":["read"],"member_admin":["read"],"support_admin":["read"],"system_admin":["read"]}}
+      }'::jsonb,
+      true
+    ),
+    validation_schema = jsonb_set(
+      coalesce(validation_schema, '{"fields":{}}'::jsonb),
+      '{fields}',
+      (coalesce(validation_schema, '{"fields":{}}'::jsonb)->'fields') || '{
+        "cited_sources":     {"data_type":"json","required":false},
+        "evidence_state":    {"data_type":"text","required":false},
+        "evidence_found":    {"data_type":"boolean","required":false},
+        "mean_similarity":   {"data_type":"number","required":false},
+        "tools_used":        {"data_type":"json","required":false},
+        "human_reply":       {"data_type":"boolean","required":false},
+        "tool":              {"data_type":"text","required":false},
+        "params":            {"data_type":"json","required":false},
+        "tool_call_id":      {"data_type":"text","required":false},
+        "result":            {"data_type":"json","required":false},
+        "details_truncated": {"data_type":"boolean","required":false},
+        "error":             {"data_type":"text","required":false},
+        "max_turns":         {"data_type":"number","required":false},
+        "turn_count":        {"data_type":"number","required":false},
+        "phase":             {"data_type":"text","required":false},
+        "analysis_summary":  {"data_type":"textarea","required":false},
+        "case_analysis_id":  {"data_type":"text","required":false},
+        "confidence_score":  {"data_type":"number","required":false}
+      }'::jsonb,
+      true
+    )
+where kind = 'message' and slug in ('support_reply', 'community_reply');
+
+-- Restamp existing message records — design_schema/validation_schema are
+-- snapshotted onto each record at creation, so the type-level update alone
+-- leaves historical rows still stripping the new fields on read.
+update public.messages m
+set design_schema = t.design_schema,
+    validation_schema = t.validation_schema
+from public.types t
+where m.type_id = t.id
+  and t.kind = 'message'
+  and t.slug in ('support_reply', 'community_reply');
+-- CIL[END stable_id="~/.framework/migrations/051_message_agent_fields.sql:message_agent_fields:file"]