@shadowforge0/aquifer-memory 1.5.9 → 1.6.0

package/schema/009-v1-assertion-plane.sql

@@ -0,0 +1,193 @@
+-- Aquifer v1 structured assertion plane
+-- Requires: 001-base.sql, 007-v1-foundation.sql, and 008-session-finalizations.sql
+-- Usage: replace ${schema} with actual schema name
+--
+-- This migration is additive. It introduces a new v1 structured assertion
+-- table and related integrity guards without repurposing legacy 004-facts rows.
+
+-- =========================================================================
+-- Scope tenant safety: prevent future cross-tenant ancestry leakage
+-- =========================================================================
+CREATE UNIQUE INDEX IF NOT EXISTS idx_scopes_tenant_row
+  ON ${schema}.scopes (tenant_id, id);
+
+CREATE OR REPLACE FUNCTION ${schema}.scope_parent_tenant_guard()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+DECLARE
+  parent_tenant TEXT;
+BEGIN
+  IF NEW.parent_scope_id IS NULL THEN
+    RETURN NEW;
+  END IF;
+
+  SELECT tenant_id
+    INTO parent_tenant
+    FROM ${schema}.scopes
+   WHERE id = NEW.parent_scope_id;
+
+  IF parent_tenant IS NOT NULL AND parent_tenant <> NEW.tenant_id THEN
+    RAISE EXCEPTION
+      'scope parent tenant mismatch: child tenant=% parent scope id=% parent tenant=%',
+      NEW.tenant_id, NEW.parent_scope_id, parent_tenant
+      USING ERRCODE = '23514';
+  END IF;
+
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS trg_scopes_parent_tenant_guard
+  ON ${schema}.scopes;
+
+CREATE TRIGGER trg_scopes_parent_tenant_guard
+  BEFORE INSERT OR UPDATE OF tenant_id, parent_scope_id
+  ON ${schema}.scopes
+  FOR EACH ROW
+  EXECUTE FUNCTION ${schema}.scope_parent_tenant_guard();
+
+-- =========================================================================
+-- fact_assertions_v1: structured assertion plane for curated memory
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS ${schema}.fact_assertions_v1 (
+  id                 BIGSERIAL    PRIMARY KEY,
+  tenant_id          TEXT         NOT NULL DEFAULT 'default',
+  canonical_key      TEXT         NOT NULL CHECK (btrim(canonical_key) <> ''),
+  scope_id           BIGINT       NOT NULL REFERENCES ${schema}.scopes(id) ON DELETE RESTRICT,
+  subject_entity_id  BIGINT,
+  predicate          TEXT         NOT NULL CHECK (btrim(predicate) <> ''),
+  object_kind        TEXT         NOT NULL
+                       CHECK (object_kind IN ('entity','value','none')),
+  object_entity_id   BIGINT,
+  object_value_json  JSONB,
+  qualifiers_json    JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  valid_from         TIMESTAMPTZ,
+  valid_to           TIMESTAMPTZ,
+  observed_at        TIMESTAMPTZ,
+  stale_after        TIMESTAMPTZ,
+  accepted_at        TIMESTAMPTZ,
+  revoked_at         TIMESTAMPTZ,
+  superseded_at      TIMESTAMPTZ,
+  status             TEXT         NOT NULL DEFAULT 'candidate'
+                       CHECK (status IN (
+                         'candidate','active','stale','superseded','revoked',
+                         'tombstoned','quarantined','archived'
+                       )),
+  authority          TEXT         NOT NULL DEFAULT 'llm_inference'
+                       CHECK (authority IN (
+                         'user_explicit','executable_evidence','verified_summary',
+                         'llm_inference','raw_transcript','manual','system'
+                       )),
+  assertion_hash     TEXT         NOT NULL CHECK (btrim(assertion_hash) <> ''),
+  superseded_by      BIGINT       REFERENCES ${schema}.fact_assertions_v1(id) ON DELETE SET NULL,
+  version_id         BIGINT       REFERENCES ${schema}.versions(id) ON DELETE SET NULL,
+  metadata           JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  created_at         TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  updated_at         TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  CHECK (valid_to IS NULL OR valid_from IS NULL OR valid_to > valid_from),
+  CHECK (revoked_at IS NULL OR accepted_at IS NULL OR revoked_at >= accepted_at),
+  CHECK (superseded_at IS NULL OR accepted_at IS NULL OR superseded_at >= accepted_at),
+  CHECK (NOT (revoked_at IS NOT NULL AND superseded_at IS NOT NULL)),
+  CHECK (
+    (object_kind = 'entity' AND object_entity_id IS NOT NULL AND object_value_json IS NULL)
+    OR (object_kind = 'value' AND object_entity_id IS NULL AND object_value_json IS NOT NULL)
+    OR (object_kind = 'none' AND object_entity_id IS NULL AND object_value_json IS NULL)
+  )
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_fact_assertions_v1_tenant_row
+  ON ${schema}.fact_assertions_v1 (tenant_id, id);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_fact_assertions_v1_active_canonical
+  ON ${schema}.fact_assertions_v1 (tenant_id, canonical_key)
+  WHERE status = 'active';
+
+CREATE INDEX IF NOT EXISTS idx_fact_assertions_v1_scope_status
+  ON ${schema}.fact_assertions_v1 (tenant_id, scope_id, status, observed_at DESC, id);
+
+CREATE INDEX IF NOT EXISTS idx_fact_assertions_v1_hash
+  ON ${schema}.fact_assertions_v1 (tenant_id, assertion_hash);
+
+CREATE INDEX IF NOT EXISTS idx_fact_assertions_v1_superseded_by
+  ON ${schema}.fact_assertions_v1 (superseded_by)
+  WHERE superseded_by IS NOT NULL;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.fact_assertions_v1'::regclass
+       AND conname = 'fact_assertions_v1_scope_tenant_fk'
+  ) THEN
+    ALTER TABLE ${schema}.fact_assertions_v1
+      ADD CONSTRAINT fact_assertions_v1_scope_tenant_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}.fact_assertions_v1 IS
+  'v1 structured assertion plane. New table; does not reuse legacy 004-facts rows.';
+
+-- =========================================================================
+-- memory_records: structured-assertion linkage + system-time lifecycle fields
+-- =========================================================================
+ALTER TABLE ${schema}.memory_records
+  ADD COLUMN IF NOT EXISTS backing_fact_id BIGINT,
+  ADD COLUMN IF NOT EXISTS observed_at TIMESTAMPTZ,
+  ADD COLUMN IF NOT EXISTS revoked_at TIMESTAMPTZ,
+  ADD COLUMN IF NOT EXISTS superseded_at TIMESTAMPTZ;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_records_tenant_row
+  ON ${schema}.memory_records (tenant_id, id);
+
+CREATE INDEX IF NOT EXISTS idx_memory_records_backing_fact
+  ON ${schema}.memory_records (tenant_id, backing_fact_id)
+  WHERE backing_fact_id IS NOT NULL;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.memory_records'::regclass
+       AND conname = 'memory_records_scope_tenant_fk'
+  ) THEN
+    ALTER TABLE ${schema}.memory_records
+      ADD CONSTRAINT memory_records_scope_tenant_fk
+      FOREIGN KEY (tenant_id, scope_id)
+      REFERENCES ${schema}.scopes (tenant_id, id)
+      ON DELETE RESTRICT
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.memory_records'::regclass
+       AND conname = 'memory_records_backing_fact_tenant_fk'
+  ) THEN
+    ALTER TABLE ${schema}.memory_records
+      ADD CONSTRAINT memory_records_backing_fact_tenant_fk
+      FOREIGN KEY (tenant_id, backing_fact_id)
+      REFERENCES ${schema}.fact_assertions_v1 (tenant_id, id)
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+-- =========================================================================
+-- compaction_runs: source/output coverage fields for auditability
+-- =========================================================================
+ALTER TABLE ${schema}.compaction_runs
+  ADD COLUMN IF NOT EXISTS source_coverage JSONB NOT NULL DEFAULT '{}'::jsonb,
+  ADD COLUMN IF NOT EXISTS output_coverage JSONB NOT NULL DEFAULT '{}'::jsonb;

package/schema/010-v1-finalization-review.sql

@@ -0,0 +1,160 @@
+-- Aquifer v1 finalization review and lineage
+-- Requires: 001-base.sql, 007-v1-foundation.sql, 008-session-finalizations.sql, 009-v1-assertion-plane.sql
+-- Usage: replace ${schema} with actual schema name
+--
+-- Finalization must leave a human-reviewable artifact and row-level lineage.
+-- DB storage alone is not treated as usable runtime memory.
+
+-- =========================================================================
+-- Finalization ledger: explicit human review and minimal SessionStart text
+-- =========================================================================
+ALTER TABLE ${schema}.session_finalizations
+  ADD COLUMN IF NOT EXISTS summary_text TEXT,
+  ADD COLUMN IF NOT EXISTS structured_summary JSONB NOT NULL DEFAULT '{}'::jsonb,
+  ADD COLUMN IF NOT EXISTS human_review_text TEXT,
+  ADD COLUMN IF NOT EXISTS session_start_text TEXT;
+
+COMMENT ON COLUMN ${schema}.session_finalizations.human_review_text IS
+  'Human-facing finalization review: concise summary of what was made active, left open, quarantined, and excluded.';
+
+COMMENT ON COLUMN ${schema}.session_finalizations.session_start_text IS
+  'Minimal active curated context eligible for SessionStart injection; excludes raw transcript/debug/audit fields.';
+
+-- =========================================================================
+-- Lifecycle semantics: incorrect is an explicit non-serving state
+-- =========================================================================
+ALTER TABLE ${schema}.memory_records
+  DROP CONSTRAINT IF EXISTS memory_records_status_check;
+
+ALTER TABLE ${schema}.memory_records
+  ADD CONSTRAINT memory_records_status_check
+  CHECK (status IN (
+    'candidate','active','stale','superseded','revoked',
+    'tombstoned','quarantined','archived','incorrect'
+  ));
+
+ALTER TABLE ${schema}.fact_assertions_v1
+  DROP CONSTRAINT IF EXISTS fact_assertions_v1_status_check;
+
+ALTER TABLE ${schema}.fact_assertions_v1
+  ADD CONSTRAINT fact_assertions_v1_status_check
+  CHECK (status IN (
+    'candidate','active','stale','superseded','revoked',
+    'tombstoned','quarantined','archived','incorrect'
+  ));
+
+-- =========================================================================
+-- Row-level finalization lineage
+-- =========================================================================
+ALTER TABLE ${schema}.memory_records
+  ADD COLUMN IF NOT EXISTS created_by_finalization_id BIGINT;
+
+ALTER TABLE ${schema}.fact_assertions_v1
+  ADD COLUMN IF NOT EXISTS created_by_finalization_id BIGINT;
+
+ALTER TABLE ${schema}.evidence_refs
+  ADD COLUMN IF NOT EXISTS created_by_finalization_id BIGINT;
+
+CREATE INDEX IF NOT EXISTS idx_memory_records_created_by_finalization
+  ON ${schema}.memory_records (tenant_id, created_by_finalization_id)
+  WHERE created_by_finalization_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_fact_assertions_created_by_finalization
+  ON ${schema}.fact_assertions_v1 (tenant_id, created_by_finalization_id)
+  WHERE created_by_finalization_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_evidence_refs_created_by_finalization
+  ON ${schema}.evidence_refs (tenant_id, created_by_finalization_id)
+  WHERE created_by_finalization_id IS NOT NULL;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.memory_records'::regclass
+       AND conname = 'memory_records_created_by_finalization_fk'
+  ) THEN
+    ALTER TABLE ${schema}.memory_records
+      ADD CONSTRAINT memory_records_created_by_finalization_fk
+      FOREIGN KEY (created_by_finalization_id)
+      REFERENCES ${schema}.session_finalizations (id)
+      ON DELETE SET NULL
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.fact_assertions_v1'::regclass
+       AND conname = 'fact_assertions_created_by_finalization_fk'
+  ) THEN
+    ALTER TABLE ${schema}.fact_assertions_v1
+      ADD CONSTRAINT fact_assertions_created_by_finalization_fk
+      FOREIGN KEY (created_by_finalization_id)
+      REFERENCES ${schema}.session_finalizations (id)
+      ON DELETE SET NULL
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.evidence_refs'::regclass
+       AND conname = 'evidence_refs_created_by_finalization_fk'
+  ) THEN
+    ALTER TABLE ${schema}.evidence_refs
+      ADD CONSTRAINT evidence_refs_created_by_finalization_fk
+      FOREIGN KEY (created_by_finalization_id)
+      REFERENCES ${schema}.session_finalizations (id)
+      ON DELETE SET NULL
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+-- =========================================================================
+-- Candidate ledger: every extracted item has an action and reason
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS ${schema}.finalization_candidates (
+  id                   BIGSERIAL    PRIMARY KEY,
+  tenant_id            TEXT         NOT NULL DEFAULT 'default',
+  finalization_id      BIGINT       NOT NULL REFERENCES ${schema}.session_finalizations(id) ON DELETE CASCADE,
+  session_id           TEXT,
+  candidate_index      INTEGER      NOT NULL,
+  action               TEXT         NOT NULL
+                         CHECK (action IN (
+                           'promote','quarantine','skip','skipped','supersede','error'
+                         )),
+  reason               TEXT,
+  memory_type          TEXT,
+  canonical_key        TEXT,
+  summary              TEXT,
+  payload              JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  provenance           JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  memory_record_id     BIGINT,
+  fact_assertion_id    BIGINT,
+  created_at           TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  updated_at           TIMESTAMPTZ  NOT NULL DEFAULT now()
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_finalization_candidates_position
+  ON ${schema}.finalization_candidates (tenant_id, finalization_id, candidate_index);
+
+CREATE INDEX IF NOT EXISTS idx_finalization_candidates_action
+  ON ${schema}.finalization_candidates (tenant_id, action, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_finalization_candidates_memory
+  ON ${schema}.finalization_candidates (tenant_id, memory_record_id)
+  WHERE memory_record_id IS NOT NULL;
+
+COMMENT ON TABLE ${schema}.finalization_candidates IS
+  'Per-finalization candidate ledger. Promoted, skipped, quarantined, and incorrect candidates remain auditable without becoming runtime memory.';

package/schema/011-v1-compaction-claim.sql

@@ -0,0 +1,46 @@
+-- Aquifer v1 compaction claim/apply guard
+-- Requires: 007-v1-foundation.sql and 009-v1-assertion-plane.sql
+-- Usage: replace ${schema} with actual schema name
+--
+-- Adds the minimum DB contract needed before compaction_runs can coordinate
+-- daily/weekly/monthly apply workers. This remains a ledger/claim guard; it
+-- does not create or promote aggregate memory.
+
+ALTER TABLE ${schema}.compaction_runs
+  ADD COLUMN IF NOT EXISTS claimed_at TIMESTAMPTZ,
+  ADD COLUMN IF NOT EXISTS worker_id TEXT,
+  ADD COLUMN IF NOT EXISTS apply_token TEXT;
+
+ALTER TABLE ${schema}.compaction_runs
+  DROP CONSTRAINT IF EXISTS compaction_runs_status_check;
+
+ALTER TABLE ${schema}.compaction_runs
+  ADD CONSTRAINT compaction_runs_status_check
+  CHECK (status IN ('planned','applying','applied','failed','skipped'));
+
+ALTER TABLE ${schema}.compaction_runs
+  DROP CONSTRAINT IF EXISTS compaction_runs_applying_claim_check;
+
+ALTER TABLE ${schema}.compaction_runs
+  ADD CONSTRAINT compaction_runs_applying_claim_check
+  CHECK (
+    status <> 'applying'
+    OR (
+      claimed_at IS NOT NULL
+      AND worker_id IS NOT NULL
+      AND btrim(worker_id) <> ''
+      AND apply_token IS NOT NULL
+      AND btrim(apply_token) <> ''
+    )
+  );
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_compaction_runs_one_live_apply
+  ON ${schema}.compaction_runs (tenant_id, cadence, period_start, period_end, policy_version)
+  WHERE status = 'applying';
+
+CREATE INDEX IF NOT EXISTS idx_compaction_runs_claims
+  ON ${schema}.compaction_runs (tenant_id, cadence, status, claimed_at DESC)
+  WHERE status = 'applying';
+
+COMMENT ON COLUMN ${schema}.compaction_runs.apply_token IS
+  'Opaque per-claim token. Apply/finalize code must present the claimed token before mutating memory.';

package/schema/012-v1-compaction-lease.sql

@@ -0,0 +1,39 @@
+-- Aquifer v1 compaction claim lease guard
+-- Requires: 011-v1-compaction-claim.sql
+-- Usage: replace ${schema} with actual schema name
+--
+-- Adds row-level lease expiry for compaction claims. Lease expiry is a DB
+-- timestamp fact, not a caller-clock interpretation of claimed_at.
+
+ALTER TABLE ${schema}.compaction_runs
+  ADD COLUMN IF NOT EXISTS lease_expires_at TIMESTAMPTZ,
+  ADD COLUMN IF NOT EXISTS reclaimed_at TIMESTAMPTZ,
+  ADD COLUMN IF NOT EXISTS reclaimed_by_worker_id TEXT;
+
+UPDATE ${schema}.compaction_runs
+   SET lease_expires_at = claimed_at + interval '600 seconds'
+ WHERE status = 'applying'
+   AND claimed_at IS NOT NULL
+   AND lease_expires_at IS NULL;
+
+ALTER TABLE ${schema}.compaction_runs
+  DROP CONSTRAINT IF EXISTS compaction_runs_applying_lease_check;
+
+ALTER TABLE ${schema}.compaction_runs
+  ADD CONSTRAINT compaction_runs_applying_lease_check
+  CHECK (
+    status <> 'applying'
+    OR (
+      lease_expires_at IS NOT NULL
+      AND lease_expires_at > claimed_at
+    )
+  );
+
+CREATE INDEX IF NOT EXISTS idx_compaction_runs_claim_lease
+  ON ${schema}.compaction_runs (
+    tenant_id, cadence, period_start, period_end, policy_version, lease_expires_at
+  )
+  WHERE status = 'applying';
+
+COMMENT ON COLUMN ${schema}.compaction_runs.lease_expires_at IS
+  'DB-time expiry for the current apply claim. Competing workers may reclaim only after this timestamp.';

package/schema/013-v1-compaction-lineage.sql

@@ -0,0 +1,193 @@
+-- Aquifer v1 compaction lineage and candidate ledger
+-- Requires: 007-v1-foundation.sql, 009-v1-assertion-plane.sql, and 012-v1-compaction-lease.sql
+-- Usage: replace ${schema} with actual schema name
+--
+-- Aggregate compaction candidates must remain auditable before promotion and
+-- every promoted row must point back to the compaction run that created it.
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_compaction_runs_tenant_row
+  ON ${schema}.compaction_runs (tenant_id, id);
+
+ALTER TABLE ${schema}.memory_records
+  ADD COLUMN IF NOT EXISTS created_by_compaction_run_id BIGINT;
+
+ALTER TABLE ${schema}.fact_assertions_v1
+  ADD COLUMN IF NOT EXISTS created_by_compaction_run_id BIGINT;
+
+ALTER TABLE ${schema}.evidence_refs
+  ADD COLUMN IF NOT EXISTS created_by_compaction_run_id BIGINT;
+
+CREATE INDEX IF NOT EXISTS idx_memory_records_created_by_compaction_run
+  ON ${schema}.memory_records (tenant_id, created_by_compaction_run_id)
+  WHERE created_by_compaction_run_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_fact_assertions_created_by_compaction_run
+  ON ${schema}.fact_assertions_v1 (tenant_id, created_by_compaction_run_id)
+  WHERE created_by_compaction_run_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_evidence_refs_created_by_compaction_run
+  ON ${schema}.evidence_refs (tenant_id, created_by_compaction_run_id)
+  WHERE created_by_compaction_run_id IS NOT NULL;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.memory_records'::regclass
+       AND conname = 'memory_records_created_by_compaction_run_fk'
+  ) THEN
+    ALTER TABLE ${schema}.memory_records
+      ADD CONSTRAINT memory_records_created_by_compaction_run_fk
+      FOREIGN KEY (tenant_id, created_by_compaction_run_id)
+      REFERENCES ${schema}.compaction_runs (tenant_id, id)
+      ON DELETE SET NULL
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.fact_assertions_v1'::regclass
+       AND conname = 'fact_assertions_created_by_compaction_run_fk'
+  ) THEN
+    ALTER TABLE ${schema}.fact_assertions_v1
+      ADD CONSTRAINT fact_assertions_created_by_compaction_run_fk
+      FOREIGN KEY (tenant_id, created_by_compaction_run_id)
+      REFERENCES ${schema}.compaction_runs (tenant_id, id)
+      ON DELETE SET NULL
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.evidence_refs'::regclass
+       AND conname = 'evidence_refs_created_by_compaction_run_fk'
+  ) THEN
+    ALTER TABLE ${schema}.evidence_refs
+      ADD CONSTRAINT evidence_refs_created_by_compaction_run_fk
+      FOREIGN KEY (tenant_id, created_by_compaction_run_id)
+      REFERENCES ${schema}.compaction_runs (tenant_id, id)
+      ON DELETE SET NULL
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+CREATE TABLE IF NOT EXISTS ${schema}.compaction_candidates (
+  id                   BIGSERIAL    PRIMARY KEY,
+  tenant_id            TEXT         NOT NULL DEFAULT 'default',
+  compaction_run_id    BIGINT       NOT NULL,
+  candidate_index      INTEGER      NOT NULL,
+  candidate_hash       TEXT         NOT NULL CHECK (btrim(candidate_hash) <> ''),
+  action               TEXT         NOT NULL DEFAULT 'planned'
+                         CHECK (action IN (
+                           'planned','promote','quarantine','skip','skipped','error'
+                         )),
+  reason               TEXT,
+  memory_type          TEXT,
+  canonical_key        TEXT,
+  scope_kind           TEXT,
+  scope_key            TEXT,
+  context_key          TEXT,
+  topic_key            TEXT,
+  summary              TEXT,
+  payload              JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  source_memory_ids    BIGINT[]     NOT NULL DEFAULT ARRAY[]::BIGINT[],
+  source_canonical_keys JSONB       NOT NULL DEFAULT '[]'::jsonb,
+  memory_record_id     BIGINT,
+  fact_assertion_id    BIGINT,
+  created_at           TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  updated_at           TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  CHECK (jsonb_typeof(source_canonical_keys) = 'array'),
+  CHECK (jsonb_array_length(source_canonical_keys) = cardinality(source_memory_ids))
+);
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.compaction_candidates'::regclass
+       AND conname = 'compaction_candidates_run_fk'
+  ) THEN
+    ALTER TABLE ${schema}.compaction_candidates
+      ADD CONSTRAINT compaction_candidates_run_fk
+      FOREIGN KEY (tenant_id, compaction_run_id)
+      REFERENCES ${schema}.compaction_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}.compaction_candidates'::regclass
+       AND conname = 'compaction_candidates_memory_fk'
+  ) THEN
+    ALTER TABLE ${schema}.compaction_candidates
+      ADD CONSTRAINT compaction_candidates_memory_fk
+      FOREIGN KEY (tenant_id, memory_record_id)
+      REFERENCES ${schema}.memory_records (tenant_id, id)
+      ON DELETE SET NULL
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1
+      FROM pg_constraint
+     WHERE conrelid = '${schema}.compaction_candidates'::regclass
+       AND conname = 'compaction_candidates_fact_fk'
+  ) THEN
+    ALTER TABLE ${schema}.compaction_candidates
+      ADD CONSTRAINT compaction_candidates_fact_fk
+      FOREIGN KEY (tenant_id, fact_assertion_id)
+      REFERENCES ${schema}.fact_assertions_v1 (tenant_id, id)
+      ON DELETE SET NULL
+      NOT VALID;
+  END IF;
+END;
+$$;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_compaction_candidates_position
+  ON ${schema}.compaction_candidates (tenant_id, compaction_run_id, candidate_index);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_compaction_candidates_hash
+  ON ${schema}.compaction_candidates (tenant_id, compaction_run_id, candidate_hash);
+
+CREATE INDEX IF NOT EXISTS idx_compaction_candidates_action
+  ON ${schema}.compaction_candidates (tenant_id, action, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_compaction_candidates_memory
+  ON ${schema}.compaction_candidates (tenant_id, memory_record_id)
+  WHERE memory_record_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_compaction_candidates_fact
+  ON ${schema}.compaction_candidates (tenant_id, fact_assertion_id)
+  WHERE fact_assertion_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_compaction_candidates_sources
+  ON ${schema}.compaction_candidates USING GIN (source_memory_ids);
+
+COMMENT ON TABLE ${schema}.compaction_candidates IS
+  'Per-compaction-run aggregate candidate ledger. Planned, promoted, skipped, quarantined, and errored candidates remain auditable without bypassing promotion.';
+
+COMMENT ON COLUMN ${schema}.memory_records.created_by_compaction_run_id IS
+  'Compaction run that formally promoted this memory, if any. Planner-only candidates do not set this column.';