@shadowforge0/aquifer-memory 1.6.0 → 1.8.0

package/schema/014-v1-checkpoint-runs.sql

@@ -0,0 +1,349 @@
+-- Aquifer v1 rolling checkpoint ledger
+-- Requires: 007-v1-foundation.sql, 008-session-finalizations.sql, and 010-v1-finalization-review.sql
+-- Usage: replace ${schema} with actual schema name
+--
+-- Adds additive checkpoint-run audit tables plus scope FK/snapshot support on
+-- session_finalizations. This does not change serving truth or promotion.
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_scopes_tenant_row
+  ON ${schema}.scopes (tenant_id, id);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_session_finalizations_tenant_row
+  ON ${schema}.session_finalizations (tenant_id, id);
+
+ALTER TABLE ${schema}.scopes
+  DROP CONSTRAINT IF EXISTS scopes_scope_kind_check;
+
+ALTER TABLE ${schema}.scopes
+  ADD CONSTRAINT scopes_scope_kind_check
+  CHECK (scope_kind IN (
+    'global','user','workspace','project','event','session',
+    'host_runtime','assistant_instance','repo','task'
+  ));
+
+ALTER TABLE ${schema}.session_finalizations
+  ADD COLUMN IF NOT EXISTS scope_id BIGINT,
+  ADD COLUMN IF NOT EXISTS scope_snapshot JSONB NOT NULL DEFAULT '{}'::jsonb;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.session_finalizations'::regclass
+       AND conname = 'session_finalizations_scope_snapshot_object_check'
+  ) THEN
+    ALTER TABLE ${schema}.session_finalizations
+      ADD CONSTRAINT session_finalizations_scope_snapshot_object_check
+      CHECK (jsonb_typeof(scope_snapshot) = 'object');
+  END IF;
+END;
+$$;
+
+UPDATE ${schema}.session_finalizations sf
+   SET scope_id = s.id
+  FROM ${schema}.scopes s
+ WHERE sf.scope_id IS NULL
+   AND sf.scope_kind IS NOT NULL
+   AND sf.scope_key IS NOT NULL
+   AND s.tenant_id = sf.tenant_id
+   AND s.scope_kind = sf.scope_kind
+   AND s.scope_key = sf.scope_key;
+
+UPDATE ${schema}.session_finalizations sf
+   SET scope_snapshot = jsonb_strip_nulls(
+         jsonb_build_object(
+           'scopeId', COALESCE(sf.scope_id, s.id),
+           'scopeKind', COALESCE(sf.scope_kind, s.scope_kind),
+           'scopeKey', COALESCE(sf.scope_key, s.scope_key),
+           'contextKey', COALESCE(sf.context_key, s.context_key),
+           'topicKey', COALESCE(sf.topic_key, s.topic_key),
+           'parentScopeId', s.parent_scope_id,
+           'inheritanceMode', s.inheritance_mode,
+           'activeFrom', s.active_from,
+           'activeTo', s.active_to
+         )
+       )
+  FROM ${schema}.scopes s
+ WHERE sf.scope_id = s.id
+   AND sf.tenant_id = s.tenant_id
+   AND sf.scope_snapshot = '{}'::jsonb;
+
+UPDATE ${schema}.session_finalizations
+   SET scope_snapshot = jsonb_strip_nulls(
+         jsonb_build_object(
+           'scopeId', scope_id,
+           'scopeKind', scope_kind,
+           'scopeKey', scope_key,
+           'contextKey', context_key,
+           'topicKey', topic_key
+         )
+       )
+ WHERE scope_snapshot = '{}'::jsonb
+   AND (
+     scope_id IS NOT NULL
+     OR scope_kind IS NOT NULL
+     OR scope_key IS NOT NULL
+     OR context_key IS NOT NULL
+     OR topic_key IS NOT NULL
+   );
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.session_finalizations'::regclass
+       AND conname = 'session_finalizations_scope_fk'
+  ) THEN
+    ALTER TABLE ${schema}.session_finalizations
+      ADD CONSTRAINT session_finalizations_scope_fk
+      FOREIGN KEY (tenant_id, scope_id)
+      REFERENCES ${schema}.scopes (tenant_id, id)
+      ON DELETE RESTRICT
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+CREATE INDEX IF NOT EXISTS idx_session_finalizations_scope
+  ON ${schema}.session_finalizations (tenant_id, scope_id, finalized_at DESC, updated_at DESC)
+  WHERE scope_id IS NOT NULL;
+
+COMMENT ON COLUMN ${schema}.session_finalizations.scope_id IS
+  'Resolved v1 scope row for this finalization when the producer knows it.';
+
+COMMENT ON COLUMN ${schema}.session_finalizations.scope_snapshot IS
+  'Compact scope audit snapshot captured at finalization time; serving still reads live curated memory.';
+
+CREATE TABLE IF NOT EXISTS ${schema}.checkpoint_runs (
+  id                         BIGSERIAL    PRIMARY KEY,
+  tenant_id                  TEXT         NOT NULL DEFAULT 'default',
+  scope_id                   BIGINT       NOT NULL,
+  checkpoint_key             TEXT         NOT NULL CHECK (btrim(checkpoint_key) <> ''),
+  from_finalization_id_exclusive BIGINT   NOT NULL DEFAULT 0 CHECK (from_finalization_id_exclusive >= 0),
+  to_finalization_id_inclusive BIGINT,
+  status                     TEXT         NOT NULL DEFAULT 'pending'
+                               CHECK (status IN (
+                                 'pending','processing','finalized','failed','skipped'
+                               )),
+  window_start               TIMESTAMPTZ,
+  window_end                 TIMESTAMPTZ,
+  scope_snapshot             JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  checkpoint_text            TEXT,
+  checkpoint_payload         JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  error                      TEXT,
+  metadata                   JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  claimed_at                 TIMESTAMPTZ,
+  finalized_at               TIMESTAMPTZ,
+  created_at                 TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  updated_at                 TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  CHECK (jsonb_typeof(scope_snapshot) = 'object'),
+  CHECK (jsonb_typeof(checkpoint_payload) = 'object'),
+  CHECK (jsonb_typeof(metadata) = 'object'),
+  CHECK (
+    to_finalization_id_inclusive IS NULL
+    OR to_finalization_id_inclusive > from_finalization_id_exclusive
+  ),
+  CHECK (
+    (window_start IS NULL AND window_end IS NULL)
+    OR (
+      window_start IS NOT NULL
+      AND window_end IS NOT NULL
+      AND window_end > window_start
+    )
+  )
+);
+
+ALTER TABLE ${schema}.checkpoint_runs
+  ADD COLUMN IF NOT EXISTS from_finalization_id_exclusive BIGINT,
+  ADD COLUMN IF NOT EXISTS to_finalization_id_inclusive BIGINT;
+
+UPDATE ${schema}.checkpoint_runs
+   SET from_finalization_id_exclusive = COALESCE(
+         from_finalization_id_exclusive,
+         substring(checkpoint_key FROM 'finalization:([0-9]+)-')::bigint,
+         0
+       ),
+       to_finalization_id_inclusive = COALESCE(
+         to_finalization_id_inclusive,
+         substring(checkpoint_key FROM '-([0-9]+)$')::bigint
+       )
+ WHERE from_finalization_id_exclusive IS NULL
+    OR to_finalization_id_inclusive IS NULL;
+
+ALTER TABLE ${schema}.checkpoint_runs
+  ALTER COLUMN from_finalization_id_exclusive SET DEFAULT 0;
+
+ALTER TABLE ${schema}.checkpoint_runs
+  ALTER COLUMN from_finalization_id_exclusive SET NOT NULL;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.checkpoint_runs'::regclass
+       AND conname = 'checkpoint_runs_from_finalization_nonnegative_check'
+  ) THEN
+    ALTER TABLE ${schema}.checkpoint_runs
+      ADD CONSTRAINT checkpoint_runs_from_finalization_nonnegative_check
+      CHECK (from_finalization_id_exclusive >= 0)
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.checkpoint_runs'::regclass
+       AND conname = 'checkpoint_runs_finalization_range_order_check'
+  ) THEN
+    ALTER TABLE ${schema}.checkpoint_runs
+      ADD CONSTRAINT checkpoint_runs_finalization_range_order_check
+      CHECK (
+        to_finalization_id_inclusive IS NULL
+        OR to_finalization_id_inclusive > from_finalization_id_exclusive
+      )
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_checkpoint_runs_identity
+  ON ${schema}.checkpoint_runs (tenant_id, scope_id, checkpoint_key);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_checkpoint_runs_scope_range
+  ON ${schema}.checkpoint_runs (
+    tenant_id, scope_id, from_finalization_id_exclusive, to_finalization_id_inclusive
+  )
+  WHERE to_finalization_id_inclusive IS NOT NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_checkpoint_runs_tenant_row
+  ON ${schema}.checkpoint_runs (tenant_id, id);
+
+CREATE INDEX IF NOT EXISTS idx_checkpoint_runs_status
+  ON ${schema}.checkpoint_runs (tenant_id, status, updated_at DESC, id DESC);
+
+CREATE INDEX IF NOT EXISTS idx_checkpoint_runs_scope_window
+  ON ${schema}.checkpoint_runs (tenant_id, scope_id, window_end DESC, updated_at DESC, id DESC);
+
+CREATE INDEX IF NOT EXISTS idx_checkpoint_runs_scope_finalization_range
+  ON ${schema}.checkpoint_runs (
+    tenant_id, scope_id, from_finalization_id_exclusive, to_finalization_id_inclusive, status
+  )
+  WHERE to_finalization_id_inclusive IS NOT NULL;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.checkpoint_runs'::regclass
+       AND conname = 'checkpoint_runs_scope_fk'
+  ) THEN
+    ALTER TABLE ${schema}.checkpoint_runs
+      ADD CONSTRAINT checkpoint_runs_scope_fk
+      FOREIGN KEY (tenant_id, scope_id)
+      REFERENCES ${schema}.scopes (tenant_id, id)
+      ON DELETE RESTRICT
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+COMMENT ON TABLE ${schema}.checkpoint_runs IS
+  'Rolling checkpoint audit ledger. Runs summarize scope-bounded source finalizations without changing serving truth.';
+
+CREATE TABLE IF NOT EXISTS ${schema}.checkpoint_run_sources (
+  id               BIGSERIAL    PRIMARY KEY,
+  tenant_id        TEXT         NOT NULL DEFAULT 'default',
+  checkpoint_run_id BIGINT      NOT NULL,
+  finalization_id  BIGINT       NOT NULL,
+  source_index     INTEGER      NOT NULL CHECK (source_index >= 0),
+  scope_id         BIGINT,
+  scope_snapshot   JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  session_row_id   BIGINT,
+  session_id       TEXT,
+  transcript_hash  TEXT,
+  summary_row_id   BIGINT,
+  finalized_at     TIMESTAMPTZ,
+  metadata         JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  created_at       TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  updated_at       TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  CHECK (jsonb_typeof(scope_snapshot) = 'object'),
+  CHECK (jsonb_typeof(metadata) = 'object')
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_checkpoint_run_sources_position
+  ON ${schema}.checkpoint_run_sources (tenant_id, checkpoint_run_id, source_index);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_checkpoint_run_sources_finalization
+  ON ${schema}.checkpoint_run_sources (tenant_id, checkpoint_run_id, finalization_id);
+
+CREATE INDEX IF NOT EXISTS idx_checkpoint_run_sources_scope
+  ON ${schema}.checkpoint_run_sources (tenant_id, scope_id, finalized_at DESC, id DESC)
+  WHERE scope_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_checkpoint_run_sources_lookup
+  ON ${schema}.checkpoint_run_sources (tenant_id, finalization_id, created_at DESC);
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.checkpoint_run_sources'::regclass
+       AND conname = 'checkpoint_run_sources_run_fk'
+  ) THEN
+    ALTER TABLE ${schema}.checkpoint_run_sources
+      ADD CONSTRAINT checkpoint_run_sources_run_fk
+      FOREIGN KEY (tenant_id, checkpoint_run_id)
+      REFERENCES ${schema}.checkpoint_runs (tenant_id, id)
+      ON DELETE CASCADE
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.checkpoint_run_sources'::regclass
+       AND conname = 'checkpoint_run_sources_finalization_fk'
+  ) THEN
+    ALTER TABLE ${schema}.checkpoint_run_sources
+      ADD CONSTRAINT checkpoint_run_sources_finalization_fk
+      FOREIGN KEY (tenant_id, finalization_id)
+      REFERENCES ${schema}.session_finalizations (tenant_id, id)
+      ON DELETE CASCADE
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.checkpoint_run_sources'::regclass
+       AND conname = 'checkpoint_run_sources_scope_fk'
+  ) THEN
+    ALTER TABLE ${schema}.checkpoint_run_sources
+      ADD CONSTRAINT checkpoint_run_sources_scope_fk
+      FOREIGN KEY (tenant_id, scope_id)
+      REFERENCES ${schema}.scopes (tenant_id, id)
+      ON DELETE RESTRICT
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+COMMENT ON TABLE ${schema}.checkpoint_run_sources IS
+  'Per-checkpoint source lineage. Each row captures the finalization input used to build a rolling checkpoint.';

package/schema/015-v1-evidence-items.sql

@@ -0,0 +1,92 @@
+-- Aquifer v1 retrieval-grade evidence items
+-- Requires: 001-base.sql, 007-v1-foundation.sql, 008-session-finalizations.sql
+-- Usage: replace ${schema} with actual schema name
+
+CREATE TABLE IF NOT EXISTS ${schema}.evidence_items (
+  id                         BIGSERIAL    PRIMARY KEY,
+  tenant_id                  TEXT         NOT NULL DEFAULT 'default',
+  source_kind                TEXT         NOT NULL
+                               CHECK (source_kind IN (
+                                 'session','session_summary','turn_embedding','insight',
+                                 'entity_state','evidence_item','raw_event','external'
+                               )),
+  source_ref                 TEXT         NOT NULL CHECK (btrim(source_ref) <> ''),
+  session_row_id             BIGINT       REFERENCES ${schema}.sessions(id) ON DELETE SET NULL,
+  turn_embedding_id          BIGINT       REFERENCES ${schema}.turn_embeddings(id) ON DELETE SET NULL,
+  summary_row_id             BIGINT       REFERENCES ${schema}.session_summaries(session_row_id) ON DELETE SET NULL,
+  created_by_finalization_id BIGINT       REFERENCES ${schema}.session_finalizations(id) ON DELETE SET NULL,
+  excerpt_text               TEXT         NOT NULL CHECK (btrim(excerpt_text) <> ''),
+  excerpt_hash               TEXT         NOT NULL CHECK (btrim(excerpt_hash) <> ''),
+  embedding                  vector(1024),
+  search_tsv                 TSVECTOR,
+  metadata                   JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  created_at                 TIMESTAMPTZ  NOT NULL DEFAULT now()
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_evidence_items_dedupe
+  ON ${schema}.evidence_items (tenant_id, source_kind, source_ref, excerpt_hash);
+
+CREATE INDEX IF NOT EXISTS idx_evidence_items_source
+  ON ${schema}.evidence_items (tenant_id, source_kind, source_ref);
+
+CREATE INDEX IF NOT EXISTS idx_evidence_items_finalization
+  ON ${schema}.evidence_items (tenant_id, created_by_finalization_id)
+  WHERE created_by_finalization_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_evidence_items_search_tsv
+  ON ${schema}.evidence_items USING GIN (search_tsv);
+
+CREATE INDEX IF NOT EXISTS idx_evidence_items_excerpt_trgm
+  ON ${schema}.evidence_items USING GIN (excerpt_text gin_trgm_ops);
+
+CREATE OR REPLACE FUNCTION ${schema}.evidence_items_search_tsv_update()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  BEGIN
+    NEW.search_tsv := to_tsvector('zhcfg', COALESCE(NEW.excerpt_text, ''));
+  EXCEPTION WHEN undefined_object OR undefined_function THEN
+    NEW.search_tsv := to_tsvector('simple', COALESCE(NEW.excerpt_text, ''));
+  END;
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS trg_evidence_items_search_tsv
+  ON ${schema}.evidence_items;
+
+CREATE TRIGGER trg_evidence_items_search_tsv
+  BEFORE INSERT OR UPDATE OF excerpt_text
+  ON ${schema}.evidence_items
+  FOR EACH ROW
+  EXECUTE FUNCTION ${schema}.evidence_items_search_tsv_update();
+
+ALTER TABLE ${schema}.evidence_refs
+  ADD COLUMN IF NOT EXISTS evidence_item_id BIGINT;
+
+CREATE INDEX IF NOT EXISTS idx_evidence_refs_evidence_item
+  ON ${schema}.evidence_refs (tenant_id, evidence_item_id)
+  WHERE evidence_item_id IS NOT NULL;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+    FROM pg_constraint
+    WHERE conrelid = '${schema}.evidence_refs'::regclass
+      AND conname = 'evidence_refs_evidence_item_fk'
+  ) THEN
+    ALTER TABLE ${schema}.evidence_refs
+      ADD CONSTRAINT evidence_refs_evidence_item_fk
+      FOREIGN KEY (evidence_item_id)
+      REFERENCES ${schema}.evidence_items(id)
+      ON DELETE SET NULL;
+  END IF;
+END$$;
+
+COMMENT ON TABLE ${schema}.evidence_items IS
+  'Retrieval-grade evidence units. Unlike coarse session_summary refs, these are searchable anchors that can support individual memory_records.';
+
+COMMENT ON COLUMN ${schema}.evidence_refs.evidence_item_id IS
+  'Optional typed link to a retrieval-grade evidence item. source_kind/source_ref remain the audit-compatible source identity.';

package/schema/016-v1-evidence-ref-multi-item.sql

@@ -0,0 +1,19 @@
+-- Aquifer v1 evidence refs can point at multiple retrieval-grade evidence items
+-- Requires: 007-v1-foundation.sql, 015-v1-evidence-items.sql
+-- Usage: replace ${schema} with actual schema name
+
+DROP INDEX IF EXISTS ${schema}.idx_evidence_refs_dedupe;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_evidence_refs_source_dedupe
+  ON ${schema}.evidence_refs (tenant_id, owner_kind, owner_id, source_kind, source_ref, relation_kind)
+  WHERE evidence_item_id IS NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_evidence_refs_evidence_item_dedupe
+  ON ${schema}.evidence_refs (tenant_id, owner_kind, owner_id, evidence_item_id, relation_kind)
+  WHERE evidence_item_id IS NOT NULL;
+
+COMMENT ON INDEX ${schema}.idx_evidence_refs_source_dedupe IS
+  'Legacy/coarse provenance dedupe for refs that do not yet point at retrieval-grade evidence_items.';
+
+COMMENT ON INDEX ${schema}.idx_evidence_refs_evidence_item_dedupe IS
+  'Allows multiple evidence_items for the same owner/source while deduping each typed evidence item link.';

package/schema/017-v1-memory-record-embeddings.sql

@@ -0,0 +1,25 @@
+-- Aquifer v1 current-memory semantic recall anchors
+-- Requires: 007-v1-foundation.sql
+-- Usage: replace ${schema} with actual schema name
+
+ALTER TABLE ${schema}.memory_records
+  ADD COLUMN IF NOT EXISTS embedding vector(1024);
+
+DO $$
+BEGIN
+  BEGIN
+    EXECUTE 'CREATE INDEX IF NOT EXISTS idx_memory_records_embedding_hnsw
+      ON ${schema}.memory_records USING hnsw (embedding vector_cosine_ops)
+      WHERE status = ''active'' AND visible_in_recall = true AND embedding IS NOT NULL';
+  EXCEPTION
+    WHEN undefined_object THEN
+      RAISE WARNING '[aquifer] pgvector HNSW operator class unavailable; memory_records semantic recall will use lexical/coarse anchors until vector index is available';
+    WHEN out_of_memory THEN
+      RAISE WARNING '[aquifer] HNSW build on memory_records.embedding ran out of memory; raise maintenance_work_mem and re-run migrate()';
+    WHEN program_limit_exceeded THEN
+      RAISE WARNING '[aquifer] HNSW build on memory_records.embedding exceeded an internal limit; inspect pgvector logs';
+  END;
+END$$;
+
+COMMENT ON COLUMN ${schema}.memory_records.embedding IS
+  'Optional current-memory embedding used by curated semantic/hybrid session_recall. Legacy summaries remain evidence anchors, not current truth.';

package/schema/018-v1-finalization-candidate-envelope.sql

@@ -0,0 +1,39 @@
+-- Aquifer v1 finalization candidate envelope
+-- Requires: 008-session-finalizations.sql, 010-v1-finalization-review.sql
+-- Usage: replace ${schema} with actual schema name
+--
+-- The candidate envelope is producer material, not serving truth. It records
+-- the structured synthesis input/output that core finalization validated before
+-- promoting active current memory.
+
+ALTER TABLE ${schema}.session_finalizations
+  ADD COLUMN IF NOT EXISTS candidate_envelope JSONB NOT NULL DEFAULT '{}'::jsonb,
+  ADD COLUMN IF NOT EXISTS candidate_envelope_hash TEXT,
+  ADD COLUMN IF NOT EXISTS candidate_envelope_version TEXT,
+  ADD COLUMN IF NOT EXISTS coverage JSONB NOT NULL DEFAULT '{}'::jsonb;
+
+COMMENT ON COLUMN ${schema}.session_finalizations.candidate_envelope IS
+  'Structured current-memory candidate envelope produced by handoff/recovery synthesis; producer material, not serving truth.';
+
+COMMENT ON COLUMN ${schema}.session_finalizations.candidate_envelope_hash IS
+  'Stable hash of the candidate envelope used for audit and replay comparison.';
+
+COMMENT ON COLUMN ${schema}.session_finalizations.candidate_envelope_version IS
+  'Version of the producer envelope contract, for example handoff_current_memory_synthesis_v1.';
+
+COMMENT ON COLUMN ${schema}.session_finalizations.coverage IS
+  'Coverage metadata for partial transcript, previous bootstrap, checkpoint, or other synthesis inputs.';
+
+CREATE INDEX IF NOT EXISTS idx_session_finalizations_candidate_envelope_hash
+  ON ${schema}.session_finalizations (tenant_id, candidate_envelope_hash)
+  WHERE candidate_envelope_hash IS NOT NULL;
+
+ALTER TABLE ${schema}.finalization_candidates
+  ADD COLUMN IF NOT EXISTS candidate_hash TEXT;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_finalization_candidates_hash
+  ON ${schema}.finalization_candidates (tenant_id, finalization_id, candidate_hash)
+  WHERE candidate_hash IS NOT NULL;
+
+COMMENT ON COLUMN ${schema}.finalization_candidates.candidate_hash IS
+  'Stable per-candidate hash. candidate_index remains an ordered audit position.';