@shadowforge0/aquifer-memory 1.5.12 → 1.6.0

package/package.json

@@ -1,38 +1,49 @@
 {
   "name": "@shadowforge0/aquifer-memory",
-  "version": "1.5.12",
+  "version": "1.6.0",
   "description": "PG-native long-term memory for AI agents. Turn-level embedding, hybrid RRF ranking, optional knowledge graph. MCP server, CLI, and library API.",
   "main": "index.js",
   "files": [
     "index.js",
+    "README_TW.md",
+    "README_CN.md",
+    "aquifer.config.example.json",
     "core/",
     "pipeline/",
     "schema/",
-    "consumers/",
-    "consumers/miranda/",
+    "consumers/cli.js",
+    "consumers/mcp.js",
+    "consumers/claude-code.js",
+    "consumers/codex.js",
+    "consumers/codex-handoff.js",
+    "consumers/openclaw-plugin.js",
+    "consumers/opencode.js",
+    "consumers/shared/",
     "consumers/default/",
     "consumers/openclaw-ext/",
-    "docs/",
+    "docs/getting-started.md",
+    "docs/postprocess-contract.md",
+    "docs/setup.md",
+    ".env.example",
     "scripts/backfill-canonical-key.js",
     "scripts/diagnose-fts-zh.js",
     "scripts/diagnose-vector.js",
-    "scripts/drop-entity-state-history.sql",
-    "scripts/drop-insights.sql",
+    "scripts/codex-recovery.js",
     "scripts/extract-insights-from-recent-sessions.js",
     "scripts/find-dburl-hints.js",
-    "scripts/install-openclaw.sh",
     "scripts/smoke.mjs"
   ],
   "bin": {
-    "aquifer": "./consumers/cli.js"
+    "aquifer": "consumers/cli.js"
   },
   "exports": {
     ".": "./index.js",
     "./consumers/mcp": "./consumers/mcp.js",
     "./consumers/openclaw-plugin": "./consumers/openclaw-plugin.js",
     "./consumers/opencode": "./consumers/opencode.js",
+    "./consumers/codex-handoff": "./consumers/codex-handoff.js",
     "./consumers/claude-code": "./consumers/claude-code.js",
-    "./consumers/miranda": "./consumers/miranda/index.js",
+    "./consumers/codex": "./consumers/codex.js",
     "./consumers/default": "./consumers/default/index.js",
     "./consumers/openclaw-ext": "./consumers/openclaw-ext/index.js",
     "./consumers/shared/config": "./consumers/shared/config.js",
@@ -41,6 +52,7 @@
     "./consumers/shared/normalize": "./consumers/shared/normalize.js",
     "./consumers/shared/ingest": "./consumers/shared/ingest.js",
     "./consumers/shared/recall-format": "./consumers/shared/recall-format.js",
+    "./consumers/shared/summary-parser": "./consumers/shared/summary-parser.js",
     "./consumers/shared/llm-autodetect": "./consumers/shared/llm-autodetect.js"
   },
   "repository": {
@@ -55,8 +67,10 @@
   "scripts": {
     "test": "node --test test/*.test.js",
     "test:integration": "node --test test/integration.test.js",
-    "lint": "eslint index.js core/*.js consumers/*.js consumers/shared/*.js consumers/miranda/*.js consumers/miranda/prompts/*.js consumers/default/*.js consumers/default/prompts/*.js consumers/openclaw-ext/*.js pipeline/*.js pipeline/consolidation/*.js scripts/*.js test/*.js",
-    "prepare": "git config core.hooksPath .githooks 2>/dev/null || true"
+    "test:release:package": "node --test test/package-surface.test.js test/mcp-manifest.test.js",
+    "test:release:db": "node -e \"if (!process.env.AQUIFER_TEST_DB_URL) { console.error('AQUIFER_TEST_DB_URL is required for test:release:db'); process.exit(1); }\" && node --test test/consumer-mcp.integration.test.js test/consumer-cli.integration.test.js test/codex-finalization-serving.integration.test.js",
+    "lint": "eslint index.js core/*.js consumers/cli.js consumers/mcp.js consumers/claude-code.js consumers/codex.js consumers/codex-handoff.js consumers/openclaw-plugin.js consumers/opencode.js consumers/shared/*.js consumers/default/*.js consumers/default/prompts/*.js consumers/openclaw-ext/*.js pipeline/*.js pipeline/consolidation/*.js scripts/*.js test/*.js",
+    "hooks:install": "git config core.hooksPath .githooks"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/pipeline/normalize/adapters/codex.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Codex CLI adapter — maps Codex rollout JSONL entries into the same
+ * intermediate shape used by the shared normalize pipeline.
+ */
+
+const { MAX_NARRATION_CHARS } = require('../constants');
+const { parseTimestamp } = require('../timestamp');
+
+function extractCodexText(content) {
+    if (!Array.isArray(content)) return '';
+    return content
+        .filter(item => item && item.type === 'output_text' && typeof item.text === 'string')
+        .map(item => item.text.trim())
+        .filter(Boolean)
+        .join('\n\n');
+}
+
+function codexToolName(entry) {
+    const payload = entry?.payload || {};
+    if (entry?.type === 'response_item' && payload.type === 'function_call') {
+        return payload.name || payload.call_id || 'function_call';
+    }
+    return null;
+}
+
+function nextCodexEntryIsTool(rawEntries, idx) {
+    for (let j = idx + 1; j < rawEntries.length; j++) {
+        const toolName = codexToolName(rawEntries[j]);
+        if (toolName) return true;
+        const payload = rawEntries[j]?.payload || {};
+        if (rawEntries[j]?.type === 'event_msg' && payload.type === 'user_message') return false;
+        if (
+            rawEntries[j]?.type === 'response_item'
+            && payload.type === 'message'
+            && payload.role === 'assistant'
+            && payload.phase === 'final_answer'
+        ) return false;
+    }
+    return false;
+}
+
+module.exports = {
+    name: 'codex',
+
+    detect(entry) {
+        return entry?.type === 'session_meta'
+            || entry?.type === 'turn_context'
+            || entry?.type === 'event_msg'
+            || entry?.type === 'response_item';
+    },
+
+    toIntermediate(entry, ctx) {
+        const { idx, rawEntries } = ctx;
+        const payload = entry?.payload || {};
+
+        if (entry?.type === 'event_msg' && payload.type === 'user_message') {
+            const text = String(payload.message || '').trim();
+            return {
+                idx,
+                role: 'user',
+                text,
+                timestamp: parseTimestamp(entry),
+                toolNames: [],
+                commandName: null,
+                isInterrupt: false,
+                adapterSkip: null,
+            };
+        }
+
+        const toolName = codexToolName(entry);
+        if (toolName) return { idx, toolNames: [toolName], adapterSkip: 'toolOnly' };
+
+        if (entry?.type === 'response_item' && payload.type === 'message' && payload.role === 'assistant') {
+            const text = extractCodexText(payload.content);
+            const toolNames = [];
+            if (!text) return { idx, toolNames, adapterSkip: 'empty' };
+
+            if (
+                payload.phase === 'commentary'
+                && text.length < MAX_NARRATION_CHARS
+                && nextCodexEntryIsTool(rawEntries, idx)
+            ) {
+                return { idx, toolNames, adapterSkip: 'narration' };
+            }
+
+            return {
+                idx,
+                role: 'assistant',
+                text,
+                timestamp: parseTimestamp(entry),
+                toolNames,
+                commandName: null,
+                isInterrupt: false,
+                adapterSkip: null,
+            };
+        }
+
+        return { idx, toolNames: [], adapterSkip: 'nonMessage' };
+    },
+
+    routinePatterns: [],
+
+    skipCommands: [],
+};

package/pipeline/normalize/detect.js

@@ -2,14 +2,15 @@
 
 const gatewayAdapter = require('./adapters/gateway');
 const claudeCodeAdapter = require('./adapters/claude-code');
+const codexAdapter = require('./adapters/codex');
 
-const ADAPTERS = [gatewayAdapter, claudeCodeAdapter];
+const ADAPTERS = [gatewayAdapter, claudeCodeAdapter, codexAdapter];
 
 /**
  * Auto-detect the client type from raw session entries.
  * Samples the first 5 entries and picks the adapter with the most matches.
  * @param {any[]} rawEntries
- * @returns {string} Client name ('gateway' | 'claude-code')
+ * @returns {string} Client name ('gateway' | 'claude-code' | 'codex')
  * @throws {Error} If entries are empty, no adapter matches, or detection is ambiguous
  */
 function detectClient(rawEntries) {

package/schema/001-base.sql

@@ -160,6 +160,9 @@ CREATE TABLE IF NOT EXISTS ${schema}.session_summaries (
   updated_at               TIMESTAMPTZ  NOT NULL DEFAULT now()
 );
 
+ALTER TABLE ${schema}.session_summaries
+  ALTER COLUMN model DROP NOT NULL;
+
 -- Cleanup legacy segment-era schema artifacts so migrate() converges old installs.
 -- Wrapped because the implicit sequence on session_segments can be referenced from
 -- other schemas (e.g. bench/staging created via CREATE TABLE LIKE), which would

package/schema/007-v1-foundation.sql

@@ -0,0 +1,273 @@
+-- Aquifer v1 curated-memory foundation
+-- Requires: 001-base.sql applied first
+-- Usage: replace ${schema} with actual schema name
+--
+-- This migration is additive. It creates a sidecar curated-memory plane while
+-- leaving the existing 1.5.x sessions/session_summaries/turn_embeddings path
+-- untouched. Legacy session tables remain evidence/source material until a
+-- later serving-mode switch.
+
+-- =========================================================================
+-- Scopes: explicit applicability boundary for curated memory
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS ${schema}.scopes (
+  id                 BIGSERIAL    PRIMARY KEY,
+  tenant_id          TEXT         NOT NULL DEFAULT 'default',
+  scope_kind         TEXT         NOT NULL
+                       CHECK (scope_kind IN (
+                         'global','user','workspace','project','event','session',
+                         'host_runtime','assistant_instance'
+                       )),
+  scope_key          TEXT         NOT NULL CHECK (btrim(scope_key) <> ''),
+  parent_scope_id    BIGINT       REFERENCES ${schema}.scopes(id) ON DELETE SET NULL,
+  inheritance_mode   TEXT         NOT NULL DEFAULT 'defaultable'
+                       CHECK (inheritance_mode IN ('exclusive','defaultable','additive','non_inheritable')),
+  context_key        TEXT,
+  topic_key          TEXT,
+  metadata           JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  active_from        TIMESTAMPTZ,
+  active_to          TIMESTAMPTZ,
+  created_at         TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  CHECK (active_to IS NULL OR active_from IS NULL OR active_to > active_from)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_scopes_tenant_kind_key
+  ON ${schema}.scopes (tenant_id, scope_kind, scope_key);
+
+CREATE INDEX IF NOT EXISTS idx_scopes_parent
+  ON ${schema}.scopes (parent_scope_id)
+  WHERE parent_scope_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_scopes_context_topic
+  ON ${schema}.scopes (tenant_id, context_key, topic_key)
+  WHERE context_key IS NOT NULL OR topic_key IS NOT NULL;
+
+COMMENT ON TABLE ${schema}.scopes IS
+  'v1 curated-memory scope tree. Scope controls applicability; default is not global promotion.';
+
+-- =========================================================================
+-- Versions: policy/model/schema provenance for deterministic replay
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS ${schema}.versions (
+  id              BIGSERIAL    PRIMARY KEY,
+  tenant_id       TEXT         NOT NULL DEFAULT 'default',
+  version_kind    TEXT         NOT NULL
+                    CHECK (version_kind IN (
+                      'schema','normalizer','extractor','promotion_policy',
+                      'embedding_model','ranker','bootstrap_policy','recall_policy','other'
+                    )),
+  version         TEXT         NOT NULL CHECK (btrim(version) <> ''),
+  version_hash    TEXT         NOT NULL CHECK (btrim(version_hash) <> ''),
+  active          BOOLEAN      NOT NULL DEFAULT false,
+  metadata        JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  released_at     TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  retired_at      TIMESTAMPTZ,
+  created_at      TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  CHECK (retired_at IS NULL OR retired_at >= released_at)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_versions_tenant_kind_hash
+  ON ${schema}.versions (tenant_id, version_kind, version_hash);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_versions_one_active_per_kind
+  ON ${schema}.versions (tenant_id, version_kind)
+  WHERE active;
+
+COMMENT ON TABLE ${schema}.versions IS
+  'v1 replay metadata for schema, normalizer, extractor, promotion, embedding, ranker, and bootstrap policies.';
+
+-- =========================================================================
+-- Memory records: runtime-visible curated memory
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS ${schema}.memory_records (
+  id                    BIGSERIAL    PRIMARY KEY,
+  tenant_id             TEXT         NOT NULL DEFAULT 'default',
+  memory_type           TEXT         NOT NULL
+                          CHECK (memory_type IN (
+                            'fact','state','decision','preference','constraint',
+                            'entity_note','open_loop','conclusion'
+                          )),
+  canonical_key         TEXT         NOT NULL CHECK (btrim(canonical_key) <> ''),
+  scope_id              BIGINT       NOT NULL REFERENCES ${schema}.scopes(id) ON DELETE RESTRICT,
+  context_key           TEXT,
+  topic_key             TEXT,
+  title                 TEXT,
+  summary               TEXT         NOT NULL DEFAULT '',
+  payload               JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  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'
+                          )),
+  accepted_at           TIMESTAMPTZ,
+  valid_from            TIMESTAMPTZ,
+  valid_to              TIMESTAMPTZ,
+  stale_after           TIMESTAMPTZ,
+  superseded_by         BIGINT       REFERENCES ${schema}.memory_records(id) ON DELETE SET NULL,
+  version_id            BIGINT       REFERENCES ${schema}.versions(id) ON DELETE SET NULL,
+  visible_in_bootstrap  BOOLEAN      NOT NULL DEFAULT false,
+  visible_in_recall     BOOLEAN      NOT NULL DEFAULT false,
+  rank_features         JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  search_tsv            TSVECTOR,
+  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 (
+    status = 'active'
+    OR (visible_in_bootstrap = false AND visible_in_recall = false)
+  )
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_records_active_canonical
+  ON ${schema}.memory_records (tenant_id, canonical_key)
+  WHERE status = 'active';
+
+CREATE INDEX IF NOT EXISTS idx_memory_records_scope_bootstrap
+  ON ${schema}.memory_records (tenant_id, scope_id, status, visible_in_bootstrap, accepted_at DESC, id)
+  WHERE visible_in_bootstrap;
+
+CREATE INDEX IF NOT EXISTS idx_memory_records_scope_recall
+  ON ${schema}.memory_records (tenant_id, scope_id, status, visible_in_recall, context_key, topic_key)
+  WHERE visible_in_recall;
+
+CREATE INDEX IF NOT EXISTS idx_memory_records_superseded_by
+  ON ${schema}.memory_records (superseded_by)
+  WHERE superseded_by IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_memory_records_search_tsv
+  ON ${schema}.memory_records USING GIN (search_tsv)
+  WHERE visible_in_recall;
+
+CREATE OR REPLACE FUNCTION ${schema}.memory_records_search_tsv_update()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  NEW.search_tsv :=
+    to_tsvector('simple',
+      COALESCE(NEW.title, '') || ' ' ||
+      COALESCE(NEW.summary, '') || ' ' ||
+      COALESCE(NEW.context_key, '') || ' ' ||
+      COALESCE(NEW.topic_key, '')
+    );
+  NEW.updated_at := now();
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS trg_memory_records_search_tsv
+  ON ${schema}.memory_records;
+
+CREATE TRIGGER trg_memory_records_search_tsv
+  BEFORE INSERT OR UPDATE OF title, summary, context_key, topic_key
+  ON ${schema}.memory_records
+  FOR EACH ROW
+  EXECUTE FUNCTION ${schema}.memory_records_search_tsv_update();
+
+COMMENT ON TABLE ${schema}.memory_records IS
+  'v1 curated memory serving source. bootstrap/session_recall read this plane when curated serving mode is enabled.';
+
+-- =========================================================================
+-- Evidence refs: provenance links to legacy or future evidence sources
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS ${schema}.evidence_refs (
+  id             BIGSERIAL    PRIMARY KEY,
+  tenant_id      TEXT         NOT NULL DEFAULT 'default',
+  owner_kind     TEXT         NOT NULL
+                   CHECK (owner_kind IN ('memory_record','fact','candidate')),
+  owner_id       BIGINT       NOT NULL,
+  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) <> ''),
+  relation_kind  TEXT         NOT NULL DEFAULT 'supporting'
+                   CHECK (relation_kind IN ('primary','supporting','contradicting','derived_from','imported_from')),
+  weight         REAL         NOT NULL DEFAULT 1.0 CHECK (weight >= 0),
+  metadata       JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  created_at     TIMESTAMPTZ  NOT NULL DEFAULT now()
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_evidence_refs_dedupe
+  ON ${schema}.evidence_refs (tenant_id, owner_kind, owner_id, source_kind, source_ref, relation_kind);
+
+CREATE INDEX IF NOT EXISTS idx_evidence_refs_owner
+  ON ${schema}.evidence_refs (tenant_id, owner_kind, owner_id);
+
+CREATE INDEX IF NOT EXISTS idx_evidence_refs_source
+  ON ${schema}.evidence_refs (tenant_id, source_kind, source_ref);
+
+COMMENT ON TABLE ${schema}.evidence_refs IS
+  'Append-only provenance links. Source may point to legacy sessions today or evidence_items/raw_events later.';
+
+-- =========================================================================
+-- Feedback: append-only v1 feedback events, not truth mutation
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS ${schema}.feedback (
+  id                 BIGSERIAL    PRIMARY KEY,
+  tenant_id          TEXT         NOT NULL DEFAULT 'default',
+  target_kind        TEXT         NOT NULL
+                       CHECK (target_kind IN ('memory_record','fact','candidate','recall_result','bootstrap','session')),
+  target_id          TEXT         NOT NULL CHECK (btrim(target_id) <> ''),
+  feedback_type      TEXT         NOT NULL
+                       CHECK (feedback_type IN (
+                         'helpful','irrelevant','scope_mismatch',
+                         'confirm','stale','superseded','incorrect','conflict','expired',
+                         'promote','pin','unpin','authority_mismatch','sensitive','archive'
+                       )),
+  actor_kind         TEXT         NOT NULL DEFAULT 'user'
+                       CHECK (actor_kind IN ('user','agent','system','curator')),
+  actor_id           TEXT,
+  query_fingerprint  TEXT,
+  note               TEXT,
+  metadata           JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  created_at         TIMESTAMPTZ  NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_feedback_target
+  ON ${schema}.feedback (tenant_id, target_kind, target_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_feedback_type
+  ON ${schema}.feedback (tenant_id, feedback_type, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_feedback_query
+  ON ${schema}.feedback (tenant_id, query_fingerprint)
+  WHERE query_fingerprint IS NOT NULL;
+
+COMMENT ON TABLE ${schema}.feedback IS
+  'Append-only v1 feedback events. Feedback may affect ranking/review, not memory truth.';
+
+-- =========================================================================
+-- Compaction runs: deterministic daily/weekly/monthly consolidation ledger
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS ${schema}.compaction_runs (
+  id                 BIGSERIAL    PRIMARY KEY,
+  tenant_id          TEXT         NOT NULL DEFAULT 'default',
+  cadence            TEXT         NOT NULL CHECK (cadence IN ('session','daily','weekly','monthly','manual')),
+  period_start       TIMESTAMPTZ  NOT NULL,
+  period_end         TIMESTAMPTZ  NOT NULL,
+  input_hash         TEXT         NOT NULL CHECK (btrim(input_hash) <> ''),
+  policy_version     TEXT         NOT NULL DEFAULT 'v1',
+  status             TEXT         NOT NULL DEFAULT 'planned'
+                        CHECK (status IN ('planned','applied','failed','skipped')),
+  output             JSONB        NOT NULL DEFAULT '{}'::jsonb,
+  error              TEXT,
+  created_at         TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  applied_at         TIMESTAMPTZ,
+  CHECK (period_end > period_start)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_compaction_runs_dedupe
+  ON ${schema}.compaction_runs (tenant_id, cadence, period_start, period_end, input_hash, policy_version);
+
+CREATE INDEX IF NOT EXISTS idx_compaction_runs_status
+  ON ${schema}.compaction_runs (tenant_id, cadence, status, period_end DESC);
+
+COMMENT ON TABLE ${schema}.compaction_runs IS
+  'v1 deterministic consolidation ledger. Runs record candidates/status updates; they do not bypass promotion policy.';

package/schema/008-session-finalizations.sql

@@ -0,0 +1,50 @@
+-- Aquifer v1 session finalization ledger
+-- Requires: 001-base.sql and 007-v1-foundation.sql applied first
+-- Usage: replace ${schema} with actual schema name
+
+CREATE TABLE IF NOT EXISTS ${schema}.session_finalizations (
+  id                 BIGSERIAL    PRIMARY KEY,
+  tenant_id          TEXT         NOT NULL DEFAULT 'default',
+  session_row_id     BIGINT       NOT NULL REFERENCES ${schema}.sessions(id) ON DELETE CASCADE,
+  source             TEXT         NOT NULL DEFAULT 'api',
+  host               TEXT         NOT NULL DEFAULT 'codex',
+  agent_id           TEXT         NOT NULL DEFAULT 'main',
+  session_id         TEXT         NOT NULL CHECK (btrim(session_id) <> ''),
+  transcript_hash    TEXT         NOT NULL CHECK (btrim(transcript_hash) <> ''),
+  phase              TEXT         NOT NULL DEFAULT 'curated_memory_v1',
+  mode               TEXT         NOT NULL DEFAULT 'handoff'
+                       CHECK (mode IN (
+                         'handoff','session_end','session_start_recovery','afterburn','manual'
+                       )),
+  status             TEXT         NOT NULL DEFAULT 'pending'
+                       CHECK (status IN (
+                         'pending','processing','finalized','failed','skipped','declined','deferred'
+                       )),
+  finalizer_model    TEXT,
+  scope_kind         TEXT,
+  scope_key          TEXT,
+  context_key        TEXT,
+  topic_key          TEXT,
+  summary_row_id     BIGINT,
+  memory_result      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()
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_session_finalizations_identity
+  ON ${schema}.session_finalizations (
+    tenant_id, source, agent_id, session_id, transcript_hash, phase
+  );
+
+CREATE INDEX IF NOT EXISTS idx_session_finalizations_status
+  ON ${schema}.session_finalizations (tenant_id, host, status, updated_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_session_finalizations_session
+  ON ${schema}.session_finalizations (tenant_id, agent_id, session_id, updated_at DESC);
+
+COMMENT ON TABLE ${schema}.session_finalizations IS
+  'v1 finalization ledger. DB is source of truth; local consumer markers are recovery hints only.';