@shadowforge0/aquifer-memory 1.3.0 → 1.5.8

package/pipeline/extract-state-changes.js

@@ -0,0 +1,205 @@
+'use strict';
+
+// Extract temporal state-change facts from session content.
+//
+// Input: message array + entity context (name→id map) + LLM.
+// Output: array of change objects ready to feed entity-state.applyChanges().
+//
+// Strict rules baked into the prompt:
+//   - Only "已發生 / past-tense / 完成式" transitions — reject tentative
+//     ("I might / I was thinking about / let's consider").
+//   - Must have explicit time anchor ("on 2026-04-18", "as of today",
+//     "this morning") — tag to session started_at if only "now".
+//   - attribute must be stable snake_case path (version.stable,
+//     editor.preference, runtime.node.version).
+//   - value must be JSON-serialisable (strings, numbers, bools, nested OK).
+//   - confidence ∈ [0,1]; default 0.7, any < threshold is dropped by caller.
+
+const ATTRIBUTE_RE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
+
+function defaultStateChangePrompt(messages, ctx = {}) {
+  const conversation = messages
+    .map(m => `[${m.role}] ${typeof m.content === 'string' ? m.content : JSON.stringify(m.content)}`)
+    .join('\n');
+  const entityList = ctx.entities && ctx.entities.length
+    ? ctx.entities.map(e => `  - "${e.name}" (id=${e.id})`).join('\n')
+    : '  (no entities resolved yet)';
+  const sessionTime = ctx.sessionStartedAt || new Date().toISOString();
+
+  return `You extract TEMPORAL STATE-CHANGE FACTS from a conversation.
+A state change means "this specific attribute of this specific entity CHANGED its value at a specific moment."
+
+## Strict rules
+
+1. Only extract CHANGES — not first-observations, not opinions, not preferences merely mentioned.
+2. Only PAST-TENSE / COMPLETED transitions. Reject tentative language:
+   - REJECT: "I might try", "I was thinking about", "let's consider", "maybe", "probably", "planning to"
+   - ACCEPT: "I upgraded", "switched to", "changed to", "升到", "改成", "換成", "現在用", "已經改"
+3. Must have explicit TIME ANCHOR — exact date, "today", "this morning", "as of", "自 X 起"
+   If only implicit "now", use ctx.sessionStartedAt as valid_from.
+4. attribute MUST be a STABLE snake_case path (lowercase, dots as separators):
+   - GOOD: version.stable, editor.preference, runtime.node.version, indexing.pgvector.strategy
+   - BAD: "Version Stable", "My Editor", "editor-pref"
+5. Each change MUST match an entity in the list below by entity_name (exact match preferred, alias OK).
+   If no matching entity exists, DROP the change silently.
+6. value must be JSON-serialisable. Wrap scalars plain (e.g. "1.3.0"), objects as {key: v}.
+
+## Output
+
+Emit ONE JSON object, no prose, no code fence, no commentary:
+
+{
+  "state_changes": [
+    {
+      "entity_name": "<must match list>",
+      "attribute": "<snake_case.dotted.path>",
+      "value": <any JSON>,
+      "valid_from": "<ISO8601 timestamp>",
+      "time_anchor_text": "<the phrase that anchors the time>",
+      "evidence_text": "<the sentence that states the change, <= 240 chars>",
+      "confidence": <0..1>
+    }
+  ]
+}
+
+If no changes, output: {"state_changes": []}
+
+## Entities in scope
+
+${entityList}
+
+## Session started at: ${sessionTime}
+
+## Conversation
+
+${conversation}
+`;
+}
+
+// Attempt to recover a JSON object from LLM output — some models wrap in
+// code fences, some prepend "Here is the JSON:" etc. Tolerant but strict
+// about the resulting shape.
+function extractJsonBlock(text) {
+  if (!text || typeof text !== 'string') return null;
+  // Strip triple-backtick fences if present.
+  let s = text.trim();
+  const fenceMatch = s.match(/```(?:json)?\s*([\s\S]*?)```/);
+  if (fenceMatch) s = fenceMatch[1].trim();
+  // Take the substring from the first { to the last }.
+  const first = s.indexOf('{');
+  const last = s.lastIndexOf('}');
+  if (first < 0 || last < first) return null;
+  const candidate = s.slice(first, last + 1);
+  try {
+    return JSON.parse(candidate);
+  } catch {
+    return null;
+  }
+}
+
+// Normalize one raw LLM-emitted change. Returns { entityName, ... } with the
+// human-facing name intact — resolution to entity_id happens in the caller
+// (enrich) after entity upsert, so state extraction itself doesn't need
+// a populated id lookup.
+function normalizeChange(raw, ctx) {
+  if (!raw || typeof raw !== 'object') return null;
+  const name = typeof raw.entity_name === 'string' ? raw.entity_name.trim() : null;
+  if (!name) return null;
+
+  // If a scope whitelist is passed, reject names not on it (case-insensitive).
+  if (ctx.scopeNames && !ctx.scopeNames.has(name.toLowerCase())) return null;
+
+  const attribute = typeof raw.attribute === 'string' ? raw.attribute.trim() : '';
+  if (!ATTRIBUTE_RE.test(attribute)) return null;
+
+  if (raw.value === undefined) return null;  // explicit null is OK
+
+  const validFromDate = new Date(raw.valid_from || raw.validFrom || ctx.sessionStartedAt);
+  if (!Number.isFinite(validFromDate.getTime())) return null;
+
+  let confidence = raw.confidence;
+  if (typeof confidence !== 'number' || !Number.isFinite(confidence)) confidence = 0.7;
+  if (confidence < 0) confidence = 0;
+  if (confidence > 1) confidence = 1;
+
+  const evidenceText = typeof raw.evidence_text === 'string' ? raw.evidence_text.slice(0, 240) : '';
+
+  return {
+    entityName: name,
+    attribute,
+    value: raw.value,
+    validFrom: validFromDate.toISOString(),
+    evidenceText,
+    confidence,
+    source: 'llm',
+    evidenceSessionId: ctx.evidenceSessionId || null,
+    sessionRowId: ctx.sessionRowId ?? null,
+  };
+}
+
+async function extractStateChanges(messages, {
+  llmFn,
+  promptFn,
+  entities = [],            // [{id, name, aliases?: []}]
+  sessionStartedAt,
+  evidenceSessionId,
+  sessionRowId,
+  confidenceThreshold = 0.7,
+  timeoutMs = 10000,
+  maxOutputTokens = 600,
+  logger,
+} = {}) {
+  if (!llmFn) return { changes: [], warnings: ['no_llm'] };
+  if (!entities.length) return { changes: [], warnings: ['no_entities_in_scope'] };
+
+  // Build case-insensitive name whitelist (entity name + aliases).
+  const scopeNames = new Set();
+  for (const e of entities) {
+    if (!e || !e.name) continue;
+    scopeNames.add(String(e.name).toLowerCase());
+    for (const a of (e.aliases || [])) {
+      if (typeof a === 'string') scopeNames.add(a.toLowerCase());
+    }
+  }
+
+  const buildPrompt = promptFn || defaultStateChangePrompt;
+  const prompt = buildPrompt(messages, { entities, sessionStartedAt });
+
+  const warnings = [];
+  let rawResponse;
+  try {
+    // Simple timeout wrapper — llmFn signature in this repo is (prompt) => string.
+    rawResponse = await Promise.race([
+      llmFn(prompt, { maxTokens: maxOutputTokens }),
+      new Promise((_, rej) => setTimeout(() => rej(new Error('llm_timeout')), timeoutMs)),
+    ]);
+  } catch (e) {
+    if (logger && logger.warn) logger.warn(`[extract-state-changes] llm call failed: ${e.message}`);
+    return { changes: [], warnings: [`llm_error: ${e.message}`] };
+  }
+
+  const parsed = extractJsonBlock(rawResponse);
+  if (!parsed || !Array.isArray(parsed.state_changes)) {
+    if (logger && logger.warn) logger.warn(`[extract-state-changes] malformed output, dropping batch`);
+    return { changes: [], warnings: ['malformed_json'] };
+  }
+
+  const ctx = { scopeNames, sessionStartedAt, evidenceSessionId, sessionRowId };
+  const changes = [];
+  let dropped = 0;
+  for (const raw of parsed.state_changes) {
+    const n = normalizeChange(raw, ctx);
+    if (!n) { dropped++; continue; }
+    if (n.confidence < confidenceThreshold) { dropped++; continue; }
+    changes.push(n);
+  }
+  if (dropped > 0) warnings.push(`dropped_${dropped}_invalid_or_low_confidence`);
+  return { changes, warnings };
+}
+
+module.exports = {
+  defaultStateChangePrompt,
+  extractJsonBlock,
+  normalizeChange,
+  extractStateChanges,
+};

package/schema/001-base.sql

@@ -3,6 +3,95 @@
 
 CREATE EXTENSION IF NOT EXISTS vector;
 CREATE EXTENSION IF NOT EXISTS pg_trgm;
+
+-- Chinese text search: prefer pg_jieba (dict.txt.big Traditional-aware, proper
+-- word segmentation via jiebaqry search-engine mode that expands compounds into
+-- multi-granularity tokens). Fall back to zhparser if jieba not installed; else
+-- migration silently uses the simple tokenizer (trigram primary path unaffected).
+-- Extension install errors (missing .so, non-superuser, OOM, etc.) are caught
+-- per-extension so one failure doesn't prevent the other from being tried.
+DO $$
+BEGIN
+  BEGIN
+    CREATE EXTENSION IF NOT EXISTS pg_jieba;
+  EXCEPTION WHEN OTHERS THEN
+    RAISE NOTICE '[aquifer] pg_jieba install skipped (%); trying zhparser', SQLERRM;
+  END;
+  BEGIN
+    CREATE EXTENSION IF NOT EXISTS zhparser;
+  EXCEPTION WHEN OTHERS THEN
+    RAISE NOTICE '[aquifer] zhparser install skipped (%); Chinese FTS will use simple tokenizer', SQLERRM;
+  END;
+END$$;
+
+-- Build/upgrade zhcfg in the public namespace (where Aquifer consumers resolve
+-- `to_tsvector('zhcfg', ...)` from). State machine:
+--   S1: jieba present, no zhcfg in public           -> CREATE zhcfg (COPY = jiebaqry)
+--   S2: jieba absent, zhparser present, no zhcfg    -> CREATE zhcfg zhparser + simple mapping
+--   S3: jieba present, zhcfg backed by zhparser     -> DROP + CREATE (COPY = jiebaqry)
+--   S4: zhcfg already jieba-backed                  -> noop
+--   S9: no backing extension but zhcfg still there  -> rebuild against best available, or drop
+--
+-- zhcfg is a database-wide object; acquire a transaction-scoped global advisory
+-- lock so concurrent migrate() calls on different Aquifer schemas in the same
+-- database don't race on the DROP/CREATE. The lock auto-releases at COMMIT.
+-- Key: hash of 'aquifer:zhcfg' truncated to PG advisory-lock int4 range.
+--
+-- Queries restrict to the public namespace to avoid ambiguity if operators have
+-- created same-named text search configs elsewhere.
+DO $$
+DECLARE
+  have_jieba boolean := EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'pg_jieba');
+  have_zhparser boolean := EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'zhparser');
+  public_oid oid := (SELECT oid FROM pg_namespace WHERE nspname = 'public');
+  zhcfg_parser text := NULL;
+BEGIN
+  PERFORM pg_advisory_xact_lock(1434531247);  -- stable global key
+
+  IF public_oid IS NOT NULL THEN
+    SELECT p.prsname INTO zhcfg_parser
+    FROM pg_ts_config c JOIN pg_ts_parser p ON c.cfgparser = p.oid
+    WHERE c.cfgname = 'zhcfg' AND c.cfgnamespace = public_oid
+    LIMIT 1;
+  END IF;
+
+  BEGIN
+    IF have_jieba AND (zhcfg_parser IS NULL OR zhcfg_parser = 'zhparser') THEN
+      -- S1 / S3: promote to jieba
+      IF zhcfg_parser = 'zhparser' THEN
+        EXECUTE 'DROP TEXT SEARCH CONFIGURATION public.zhcfg';
+      END IF;
+      EXECUTE 'CREATE TEXT SEARCH CONFIGURATION public.zhcfg ( COPY = public.jiebaqry )';
+
+    ELSIF have_zhparser AND zhcfg_parser IS NULL THEN
+      -- S2: zhparser-only new install.  `eng` covers English tokens that zhparser
+      -- emits for Latin words in mixed-language text; without it they'd be dropped.
+      EXECUTE 'CREATE TEXT SEARCH CONFIGURATION public.zhcfg (PARSER = zhparser)';
+      EXECUTE 'ALTER TEXT SEARCH CONFIGURATION public.zhcfg
+        ADD MAPPING FOR n,v,a,i,e,l,j,nr,ns,nt,nz,vd,vn,m,r,t,c,p,u,d,o,y,w,x,q,b,k,s,f,h,g,eng WITH simple';
+
+    ELSIF NOT have_jieba AND NOT have_zhparser AND zhcfg_parser IS NOT NULL THEN
+      -- S9: backing extension dropped but zhcfg stayed; any `to_tsvector('zhcfg',...)`
+      -- would throw "parser does not exist" and break the FTS trigger.
+      -- Safer to remove zhcfg and let consumers fall back to 'simple'.
+      EXECUTE 'DROP TEXT SEARCH CONFIGURATION public.zhcfg';
+      RAISE WARNING '[aquifer] zhcfg removed: neither pg_jieba nor zhparser is installed; Chinese FTS falls back to simple';
+
+    ELSIF NOT have_jieba AND have_zhparser AND zhcfg_parser NOT IN ('zhparser') THEN
+      -- S9 partial: jieba gone but zhparser available; rebuild on zhparser.
+      EXECUTE 'DROP TEXT SEARCH CONFIGURATION public.zhcfg';
+      EXECUTE 'CREATE TEXT SEARCH CONFIGURATION public.zhcfg (PARSER = zhparser)';
+      EXECUTE 'ALTER TEXT SEARCH CONFIGURATION public.zhcfg
+        ADD MAPPING FOR n,v,a,i,e,l,j,nr,ns,nt,nz,vd,vn,m,r,t,c,p,u,d,o,y,w,x,q,b,k,s,f,h,g,eng WITH simple';
+      RAISE WARNING '[aquifer] zhcfg rebuilt on zhparser: pg_jieba no longer installed';
+    END IF;
+  EXCEPTION WHEN OTHERS THEN
+    -- Ownership mismatch, concurrent-modify race, dependency blocking DROP, etc.
+    -- Don't abort the entire migrate(); leave zhcfg as-is and warn.
+    RAISE WARNING '[aquifer] zhcfg (re)build skipped (%); existing config left untouched', SQLERRM;
+  END;
+END$$;
+
 CREATE SCHEMA IF NOT EXISTS ${schema};
 
 -- =========================================================================
@@ -61,7 +150,9 @@ CREATE TABLE IF NOT EXISTS ${schema}.session_summaries (
   ended_at                 TIMESTAMPTZ,
   summary_text             TEXT,
   structured_summary       JSONB        NOT NULL DEFAULT '{}',
-  embedding                vector,
+  -- Sized so HNSW can build at migrate time; 1024 matches ollama bge-m3 default.
+  -- Coerce DO block below upgrades pre-1.5.2 unsized columns.
+  embedding                vector(1024),
   search_tsv               TSVECTOR,
   search_text              TEXT,
   access_count             INT          NOT NULL DEFAULT 0,
@@ -99,18 +190,48 @@ CREATE INDEX IF NOT EXISTS idx_summaries_embedding
   ON ${schema}.session_summaries (session_row_id)
   WHERE embedding IS NOT NULL;
 
+-- Coerce pre-1.5.2 unsized `vector` column to sized so HNSW can be built.
+-- pgvector requires a dim on the COLUMN, not just the data. Dim priority:
+-- existing row dim > `aquifer.embedding_dim` GUC > 1024 default.
+DO $$
+DECLARE
+  is_unsized BOOLEAN;
+  existing_dim INT;
+  target_dim INT;
+BEGIN
+  SELECT format_type(atttypid, atttypmod) = 'vector'
+    INTO is_unsized
+    FROM pg_attribute
+    WHERE attrelid = '${schema}.session_summaries'::regclass
+      AND attname = 'embedding';
+
+  IF is_unsized THEN
+    EXECUTE 'SELECT vector_dims(embedding) FROM ${schema}.session_summaries WHERE embedding IS NOT NULL LIMIT 1'
+      INTO existing_dim;
+    target_dim := COALESCE(
+      existing_dim,
+      NULLIF(current_setting('aquifer.embedding_dim', true), '')::int,
+      1024
+    );
+    EXECUTE 'ALTER TABLE ${schema}.session_summaries ALTER COLUMN embedding TYPE vector('
+         || target_dim::text
+         || ') USING embedding::vector('
+         || target_dim::text
+         || ')';
+    RAISE NOTICE '[aquifer] session_summaries.embedding coerced from unsized vector to vector(%)', target_dim;
+  END IF;
+END$$;
+
 -- HNSW approximate nearest-neighbor index for cosine-distance vector search.
--- Without this, ORDER BY embedding <=> $vec degrades to seq scan at scale.
--- Requires pgvector >= 0.5.0. HNSW cannot build on an empty unsized `vector`
--- column (can't infer dim), so we defer on failure — re-running migrate()
--- after the first insert will finish the job.
+-- Column is sized via CREATE TABLE or the coerce block above, so the index
+-- builds on fresh installs too. Safety-net EXCEPTION handlers stay for the
+-- genuine recoverable failures; invalid_parameter_value is intentionally
+-- NOT caught — it used to mask the unsized-column schema bug.
 DO $$
 BEGIN
   BEGIN
     EXECUTE 'CREATE INDEX IF NOT EXISTS idx_summaries_embedding_hnsw ON ${schema}.session_summaries USING hnsw (embedding vector_cosine_ops)';
   EXCEPTION
-    WHEN invalid_parameter_value THEN
-      RAISE NOTICE '[aquifer] HNSW index on session_summaries.embedding deferred; re-run migrate() after the first embedded row';
     WHEN feature_not_supported THEN
       RAISE NOTICE '[aquifer] HNSW not available on this pgvector; upgrade to >= 0.5.0 for index-accelerated vector search';
     WHEN out_of_memory THEN
@@ -155,11 +276,28 @@ BEGIN
   INTO facts_text
   FROM jsonb_array_elements(COALESCE(ss->'important_facts', '[]'::jsonb)) AS elem;
 
-  NEW.search_tsv :=
-    setweight(to_tsvector('simple', title_text), 'A') ||
-    setweight(to_tsvector('simple', overview_text || ' ' || topics_text || ' ' || decisions_text), 'B') ||
-    setweight(to_tsvector('simple', COALESCE(NEW.summary_text, '')), 'C') ||
-    setweight(to_tsvector('simple', open_loops_text || ' ' || facts_text), 'D');
+  -- Use zhcfg if available (Chinese segmentation — pg_jieba jiebaqry on new
+  -- installs, zhparser as legacy fallback; zhcfg name is a stable indirection
+  -- managed by the DO block above). Else fall back to simple tokenizer.
+  -- The per-row IF EXISTS lookup hits a tiny fully-cached system catalog
+  -- (pg_ts_config, ~12 rows) — effectively free. Chose this over migrate-time
+  -- codegen because installing pg_jieba POST-install immediately benefits new
+  -- inserts without requiring a manual re-migrate.
+  IF EXISTS (SELECT 1 FROM pg_ts_config
+             WHERE cfgname = 'zhcfg'
+               AND cfgnamespace = 'public'::regnamespace) THEN
+    NEW.search_tsv :=
+      setweight(to_tsvector('zhcfg', title_text), 'A') ||
+      setweight(to_tsvector('zhcfg', overview_text || ' ' || topics_text || ' ' || decisions_text), 'B') ||
+      setweight(to_tsvector('zhcfg', COALESCE(NEW.summary_text, '')), 'C') ||
+      setweight(to_tsvector('zhcfg', open_loops_text || ' ' || facts_text), 'D');
+  ELSE
+    NEW.search_tsv :=
+      setweight(to_tsvector('simple', title_text), 'A') ||
+      setweight(to_tsvector('simple', overview_text || ' ' || topics_text || ' ' || decisions_text), 'B') ||
+      setweight(to_tsvector('simple', COALESCE(NEW.summary_text, '')), 'C') ||
+      setweight(to_tsvector('simple', open_loops_text || ' ' || facts_text), 'D');
+  END IF;
 
   NEW.search_text :=
     title_text || ' ' || overview_text || ' ' || topics_text || ' ' ||
@@ -198,7 +336,9 @@ CREATE TABLE IF NOT EXISTS ${schema}.turn_embeddings (
   role             TEXT         NOT NULL DEFAULT 'user' CHECK (role = 'user'),
   content_text     TEXT         NOT NULL,
   content_hash     TEXT         NOT NULL,
-  embedding        vector       NOT NULL,
+  -- Sized so HNSW can build at migrate time. Coerce DO block below upgrades
+  -- pre-1.5.2 unsized columns.
+  embedding        vector(1024) NOT NULL,
   created_at       TIMESTAMPTZ  NOT NULL DEFAULT now(),
   UNIQUE (session_row_id, message_index)
 );
@@ -209,15 +349,45 @@ CREATE INDEX IF NOT EXISTS idx_turn_emb_session_row
 CREATE INDEX IF NOT EXISTS idx_turn_emb_tenant_agent
   ON ${schema}.turn_embeddings (tenant_id, agent_id, source);
 
+-- Coerce pre-1.5.2 unsized `vector` column for turn_embeddings.
+-- NOT NULL so every row has a dim; existing_dim should always resolve.
+DO $$
+DECLARE
+  is_unsized BOOLEAN;
+  existing_dim INT;
+  target_dim INT;
+BEGIN
+  SELECT format_type(atttypid, atttypmod) = 'vector'
+    INTO is_unsized
+    FROM pg_attribute
+    WHERE attrelid = '${schema}.turn_embeddings'::regclass
+      AND attname = 'embedding';
+
+  IF is_unsized THEN
+    EXECUTE 'SELECT vector_dims(embedding) FROM ${schema}.turn_embeddings WHERE embedding IS NOT NULL LIMIT 1'
+      INTO existing_dim;
+    target_dim := COALESCE(
+      existing_dim,
+      NULLIF(current_setting('aquifer.embedding_dim', true), '')::int,
+      1024
+    );
+    EXECUTE 'ALTER TABLE ${schema}.turn_embeddings ALTER COLUMN embedding TYPE vector('
+         || target_dim::text
+         || ') USING embedding::vector('
+         || target_dim::text
+         || ')';
+    RAISE NOTICE '[aquifer] turn_embeddings.embedding coerced from unsized vector to vector(%)', target_dim;
+  END IF;
+END$$;
+
 -- HNSW approximate nearest-neighbor index for turn-level vector search.
--- See notes on session_summaries.embedding HNSW above.
+-- See notes on session_summaries.embedding HNSW above. invalid_parameter_value
+-- intentionally NOT caught — it used to mask the unsized-column schema bug.
 DO $$
 BEGIN
   BEGIN
     EXECUTE 'CREATE INDEX IF NOT EXISTS idx_turn_emb_embedding_hnsw ON ${schema}.turn_embeddings USING hnsw (embedding vector_cosine_ops)';
   EXCEPTION
-    WHEN invalid_parameter_value THEN
-      RAISE NOTICE '[aquifer] HNSW index on turn_embeddings.embedding deferred; re-run migrate() after the first embedded row';
     WHEN feature_not_supported THEN
       RAISE NOTICE '[aquifer] HNSW not available on this pgvector; upgrade to >= 0.5.0 for index-accelerated vector search';
     WHEN out_of_memory THEN

package/schema/002-entities.sql

@@ -23,7 +23,10 @@ CREATE TABLE IF NOT EXISTS ${schema}.entities (
   entity_scope    TEXT         NOT NULL DEFAULT 'default',
   created_by      TEXT,
   metadata        JSONB        NOT NULL DEFAULT '{}',
-  embedding       vector,
+  -- Sized so future HNSW index on entities.embedding builds cleanly. No HNSW
+  -- currently — entity lookup is name-trgm, not vector. Coerce block below
+  -- upgrades pre-1.5.2 installs.
+  embedding       vector(1024),
   first_seen_at   TIMESTAMPTZ  NOT NULL DEFAULT now(),
   last_seen_at    TIMESTAMPTZ  NOT NULL DEFAULT now()
 );
@@ -48,6 +51,37 @@ BEGIN
 END$$;
 ALTER TABLE ${schema}.entities ALTER COLUMN entity_scope SET NOT NULL;
 
+-- Coerce pre-1.5.2 unsized `vector` column to sized for HNSW-ready shape.
+-- Mirrors the session_summaries / turn_embeddings / insights coerce blocks.
+DO $$
+DECLARE
+  is_unsized BOOLEAN;
+  existing_dim INT;
+  target_dim INT;
+BEGIN
+  SELECT format_type(atttypid, atttypmod) = 'vector'
+    INTO is_unsized
+    FROM pg_attribute
+    WHERE attrelid = '${schema}.entities'::regclass
+      AND attname = 'embedding';
+
+  IF is_unsized THEN
+    EXECUTE 'SELECT vector_dims(embedding) FROM ${schema}.entities WHERE embedding IS NOT NULL LIMIT 1'
+      INTO existing_dim;
+    target_dim := COALESCE(
+      existing_dim,
+      NULLIF(current_setting('aquifer.embedding_dim', true), '')::int,
+      1024
+    );
+    EXECUTE 'ALTER TABLE ${schema}.entities ALTER COLUMN embedding TYPE vector('
+         || target_dim::text
+         || ') USING embedding::vector('
+         || target_dim::text
+         || ')';
+    RAISE NOTICE '[aquifer] entities.embedding coerced from unsized vector to vector(%)', target_dim;
+  END IF;
+END$$;
+
 -- Unique constraint: entity identity is (tenant, name, scope)
 -- Drop legacy agent-based constraint if it exists
 DROP INDEX IF EXISTS ${schema}.idx_entities_tenant_name_agent;

package/schema/004-completion.sql

@@ -90,7 +90,11 @@ LANGUAGE plpgsql
 AS $$
 BEGIN
   NEW.search_text := COALESCE(NEW.text, '') || ' ' || COALESCE(NEW.metadata::text, '');
-  NEW.search_tsv  := setweight(to_tsvector('simple', COALESCE(NEW.text, '')), 'A');
+  IF EXISTS (SELECT 1 FROM pg_ts_config WHERE cfgname = 'zhcfg') THEN
+    NEW.search_tsv := setweight(to_tsvector('zhcfg', COALESCE(NEW.text, '')), 'A');
+  ELSE
+    NEW.search_tsv := setweight(to_tsvector('simple', COALESCE(NEW.text, '')), 'A');
+  END IF;
   RETURN NEW;
 END;
 $$;
@@ -184,9 +188,15 @@ BEGIN
     COALESCE(NEW.text, '') || ' ' ||
     COALESCE(NEW.metadata::text, '');
 
-  NEW.search_tsv :=
-    setweight(to_tsvector('simple', COALESCE(NEW.category, '')), 'B') ||
-    setweight(to_tsvector('simple', COALESCE(NEW.text, '')), 'A');
+  IF EXISTS (SELECT 1 FROM pg_ts_config WHERE cfgname = 'zhcfg') THEN
+    NEW.search_tsv :=
+      setweight(to_tsvector('zhcfg', COALESCE(NEW.category, '')), 'B') ||
+      setweight(to_tsvector('zhcfg', COALESCE(NEW.text, '')), 'A');
+  ELSE
+    NEW.search_tsv :=
+      setweight(to_tsvector('simple', COALESCE(NEW.category, '')), 'B') ||
+      setweight(to_tsvector('simple', COALESCE(NEW.text, '')), 'A');
+  END IF;
 
   RETURN NEW;
 END;
@@ -310,9 +320,15 @@ BEGIN
     COALESCE(NEW.reason_text, '') || ' ' ||
     COALESCE(NEW.metadata::text, '');
 
-  NEW.search_tsv :=
-    setweight(to_tsvector('simple', COALESCE(NEW.decision_text, '')), 'A') ||
-    setweight(to_tsvector('simple', COALESCE(NEW.reason_text, '')), 'B');
+  IF EXISTS (SELECT 1 FROM pg_ts_config WHERE cfgname = 'zhcfg') THEN
+    NEW.search_tsv :=
+      setweight(to_tsvector('zhcfg', COALESCE(NEW.decision_text, '')), 'A') ||
+      setweight(to_tsvector('zhcfg', COALESCE(NEW.reason_text, '')), 'B');
+  ELSE
+    NEW.search_tsv :=
+      setweight(to_tsvector('simple', COALESCE(NEW.decision_text, '')), 'A') ||
+      setweight(to_tsvector('simple', COALESCE(NEW.reason_text, '')), 'B');
+  END IF;
 
   RETURN NEW;
 END;

package/schema/005-entity-state-history.sql

@@ -0,0 +1,87 @@
+-- entity_state_history: temporal state-change tracking on entities.
+--
+-- Captures discrete attribute transitions (e.g. version.stable=1.2.1 -> 1.3.0,
+-- editor.preference=vim -> nvim). Designed as additive overlay on the entities
+-- table; DROP-clean — no triggers/functions/views, removing this table leaves
+-- the rest of Aquifer untouched.
+--
+-- See spec.md Q3 and ~/.claude/develop-runs/20260419-142432-aquifer-memory-routes/.
+
+CREATE TABLE IF NOT EXISTS ${schema}.entity_state_history (
+  id                  BIGSERIAL PRIMARY KEY,
+  tenant_id           TEXT          NOT NULL DEFAULT 'default',
+  agent_id            TEXT          NOT NULL DEFAULT 'main',
+  entity_id           BIGINT        NOT NULL
+    REFERENCES ${schema}.entities(id) ON DELETE CASCADE,
+  session_row_id      BIGINT
+    REFERENCES ${schema}.sessions(id) ON DELETE SET NULL,
+  evidence_session_id TEXT,
+  attribute           TEXT          NOT NULL CHECK (btrim(attribute) <> ''),
+  value               JSONB         NOT NULL,
+  valid_from          TIMESTAMPTZ   NOT NULL,
+  valid_to            TIMESTAMPTZ,
+  evidence_text       TEXT          NOT NULL DEFAULT '',
+  confidence          NUMERIC(4,3)  NOT NULL DEFAULT 0.7
+    CHECK (confidence >= 0 AND confidence <= 1),
+  source              TEXT          NOT NULL DEFAULT 'llm'
+    CHECK (source IN ('llm', 'manual', 'infra')),
+  idempotency_key     TEXT,
+  supersedes_state_id BIGINT
+    REFERENCES ${schema}.entity_state_history(id) ON DELETE SET NULL,
+  created_at          TIMESTAMPTZ   NOT NULL DEFAULT now(),
+  CHECK (valid_to IS NULL OR valid_to > valid_from)
+);
+
+-- Partial UNIQUE: only one "current" (valid_to IS NULL) row per
+-- (tenant, agent, entity, attribute). This is the temporal invariant —
+-- two open intervals on the same key would mean the table is corrupt.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_entity_state_history_current
+  ON ${schema}.entity_state_history (tenant_id, agent_id, entity_id, attribute)
+  WHERE valid_to IS NULL;
+
+-- Idempotency: same caller-supplied key writes once. Partial allows NULL keys
+-- (manual writes don't always need them).
+CREATE UNIQUE INDEX IF NOT EXISTS idx_entity_state_history_idempotency
+  ON ${schema}.entity_state_history (idempotency_key)
+  WHERE idempotency_key IS NOT NULL;
+
+-- Hot path: history-by-attribute timeline scan, newest-first.
+CREATE INDEX IF NOT EXISTS idx_entity_state_history_entity_attr_time
+  ON ${schema}.entity_state_history
+     (tenant_id, agent_id, entity_id, attribute, valid_from DESC, id DESC);
+
+-- Hot path: full history for an entity (no attribute filter).
+CREATE INDEX IF NOT EXISTS idx_entity_state_history_entity_time
+  ON ${schema}.entity_state_history
+     (tenant_id, agent_id, entity_id, valid_from DESC, id DESC);
+
+-- Diagnostic: trace all state changes captured from a single session.
+CREATE INDEX IF NOT EXISTS idx_entity_state_history_evidence_session
+  ON ${schema}.entity_state_history
+     (tenant_id, agent_id, evidence_session_id, created_at DESC)
+  WHERE evidence_session_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_entity_state_history_session_row
+  ON ${schema}.entity_state_history (session_row_id)
+  WHERE session_row_id IS NOT NULL;
+
+COMMENT ON TABLE ${schema}.entity_state_history IS
+  'Bi-temporal state changes on entities. Each row = one (entity, attribute) value valid over [valid_from, valid_to). NULL valid_to = current. supersedes_state_id chains supersession history.';
+
+COMMENT ON COLUMN ${schema}.entity_state_history.attribute IS
+  'Stable snake_case path identifying what changed (e.g. version.stable, editor.preference, runtime.node.version). Caller-defined; treat as opaque key.';
+
+COMMENT ON COLUMN ${schema}.entity_state_history.valid_from IS
+  'When the new value became true in the real world (not when it was observed). Use evidence anchor; fall back to session started_at if unspecified.';
+
+COMMENT ON COLUMN ${schema}.entity_state_history.valid_to IS
+  'NULL = currently valid. Otherwise, the timestamp at which a successor row took over. Closed intervals must satisfy valid_to > valid_from.';
+
+COMMENT ON COLUMN ${schema}.entity_state_history.idempotency_key IS
+  'Caller-supplied dedupe key. Default: sha256(tenant, agent, entity, attribute, canonical_json(value), valid_from, source). Replay safe.';
+
+COMMENT ON COLUMN ${schema}.entity_state_history.supersedes_state_id IS
+  'Chain pointer to the row this one closed (set valid_to on). NULL if this is the first known value for (entity, attribute).';
+
+COMMENT ON COLUMN ${schema}.entity_state_history.evidence_session_id IS
+  'Session that produced this evidence (text-level session_id, not session_row_id). For audit / re-extraction.';