pilotswarm-horizon-store 0.2.2

package/migrations/0004_facts_procs.sql

@@ -0,0 +1,253 @@
+-- 0004_facts_procs — ALL relational + vector data access (03-design §1: no
+-- inline SQL in the provider; the 04 §6 M1 grep guard enforces it).
+--
+-- ACL convention (every read): the access predicate is part of the WHERE
+-- clause, evaluated BEFORE ranking/LIMIT (01 §4.2 — never a post-filter).
+-- Parameters: p_reader (caller session), p_granted (spawn-tree session ids),
+-- p_unrestricted, p_scope ('accessible'|'shared'|'session'|'descendants').
+--
+-- Tokens: {{SCHEMA}}.
+
+-- ── write ────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION "{{SCHEMA}}".facts_store(
+    p_scope_key  TEXT,
+    p_key        TEXT,
+    p_value      JSONB,
+    p_agent_id   TEXT,
+    p_session_id TEXT,
+    p_shared     BOOLEAN,
+    p_tags       TEXT[]
+) RETURNS void
+LANGUAGE sql AS $$
+    INSERT INTO "{{SCHEMA}}".facts (scope_key, key, value, agent_id, session_id, shared, transient, tags, updated_at)
+    VALUES (p_scope_key, p_key, p_value, p_agent_id, p_session_id, p_shared, NOT p_shared, coalesce(p_tags, '{}'), now())
+    ON CONFLICT (scope_key) DO UPDATE SET
+        value = EXCLUDED.value, agent_id = EXCLUDED.agent_id, tags = EXCLUDED.tags,
+        shared = EXCLUDED.shared, transient = EXCLUDED.transient, updated_at = now();
+$$;
+
+CREATE OR REPLACE FUNCTION "{{SCHEMA}}".facts_delete(p_scope_key TEXT) RETURNS boolean
+LANGUAGE sql AS $$
+    WITH del AS (DELETE FROM "{{SCHEMA}}".facts WHERE scope_key = p_scope_key RETURNING 1)
+    SELECT count(*) > 0 FROM del;
+$$;
+
+CREATE OR REPLACE FUNCTION "{{SCHEMA}}".facts_delete_session(p_session_id TEXT) RETURNS int
+LANGUAGE sql AS $$
+    WITH del AS (DELETE FROM "{{SCHEMA}}".facts WHERE shared = FALSE AND session_id = p_session_id RETURNING 1)
+    SELECT count(*)::int FROM del;
+$$;
+
+-- ── ACL predicate (shared by the read/search procs) ─────────────────────────
+
+CREATE OR REPLACE FUNCTION "{{SCHEMA}}".facts_acl(
+    f_shared BOOLEAN, f_session_id TEXT,
+    p_reader TEXT, p_granted TEXT[], p_unrestricted BOOLEAN, p_scope TEXT
+) RETURNS boolean
+LANGUAGE sql IMMUTABLE AS $$
+    SELECT CASE
+        WHEN p_unrestricted THEN TRUE
+        WHEN p_scope = 'shared' THEN f_shared
+        WHEN p_scope = 'session' THEN (NOT f_shared AND f_session_id = p_reader)
+        WHEN p_scope = 'descendants' THEN (NOT f_shared AND f_session_id = ANY (coalesce(p_granted, '{}')))
+        ELSE (f_shared OR f_session_id = p_reader OR f_session_id = ANY (coalesce(p_granted, '{}')))
+    END;
+$$;
+
+-- ── read ─────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION "{{SCHEMA}}".facts_read(
+    p_reader       TEXT,
+    p_granted      TEXT[],
+    p_unrestricted BOOLEAN,
+    p_scope        TEXT,
+    p_key_pattern  TEXT,
+    p_scope_keys   TEXT[],
+    p_tags         TEXT[],
+    p_agent_id     TEXT,
+    p_limit        INT
+) RETURNS SETOF "{{SCHEMA}}".facts
+LANGUAGE sql STABLE AS $$
+    SELECT f.* FROM "{{SCHEMA}}".facts f
+    WHERE "{{SCHEMA}}".facts_acl(f.shared, f.session_id, p_reader, p_granted, p_unrestricted, p_scope)
+      AND (p_key_pattern IS NULL OR f.key LIKE p_key_pattern)
+      AND (p_scope_keys IS NULL OR f.scope_key = ANY (p_scope_keys))
+      AND (p_tags IS NULL OR f.tags @> p_tags)
+      AND (p_agent_id IS NULL OR f.agent_id = p_agent_id)
+    ORDER BY f.updated_at DESC
+    LIMIT p_limit;
+$$;
+
+-- ── stats (namespace-bucketed, in SQL — not in Node) ─────────────────────────
+
+CREATE OR REPLACE FUNCTION "{{SCHEMA}}".facts_stats(
+    p_mode        TEXT,        -- 'session' | 'sessions' | 'shared'
+    p_session_ids TEXT[]
+) RETURNS TABLE (
+    namespace TEXT, fact_count BIGINT, total_value_bytes BIGINT,
+    oldest_created_at TIMESTAMPTZ, newest_updated_at TIMESTAMPTZ
+)
+LANGUAGE sql STABLE AS $$
+    SELECT
+        CASE WHEN split_part(f.key, '/', 1) IN ('skills', 'asks', 'intake', 'config')
+             THEN split_part(f.key, '/', 1) ELSE '(other)' END AS namespace,
+        count(*) AS fact_count,
+        sum(octet_length(f.value::text))::bigint AS total_value_bytes,
+        min(f.created_at) AS oldest_created_at,
+        max(f.updated_at) AS newest_updated_at
+    FROM "{{SCHEMA}}".facts f
+    WHERE CASE p_mode
+        WHEN 'shared'   THEN f.shared
+        WHEN 'session'  THEN (NOT f.shared AND f.session_id = p_session_ids[1])
+        WHEN 'sessions' THEN (NOT f.shared AND f.session_id = ANY (coalesce(p_session_ids, '{}')))
+        ELSE FALSE
+    END
+    GROUP BY 1;
+$$;
+
+-- ── lexical search (BM25 via pg_textsearch — verified on live HorizonDB) ────
+-- `search_text <@> to_bm25query(q, idx)` yields the NEGATIVE BM25 score
+-- (0 = no match), so: match ⇔ d < 0, rank = -d, best-first = ORDER BY d ASC.
+-- The ACL predicate sits in the same WHERE — before ranking and LIMIT.
+
+CREATE OR REPLACE FUNCTION "{{SCHEMA}}".facts_search_lexical(
+    p_query        TEXT,
+    p_reader       TEXT,
+    p_granted      TEXT[],
+    p_unrestricted BOOLEAN,
+    p_scope        TEXT,
+    p_ns_prefix    TEXT,
+    p_tags         TEXT[],
+    p_pool         INT
+) RETURNS TABLE (
+    scope_key TEXT, key TEXT, value JSONB, agent_id TEXT, session_id TEXT,
+    shared BOOLEAN, tags TEXT[], created_at TIMESTAMPTZ, updated_at TIMESTAMPTZ,
+    rank DOUBLE PRECISION
+)
+LANGUAGE sql STABLE AS $$
+    SELECT f.scope_key, f.key, f.value, f.agent_id, f.session_id,
+           f.shared, f.tags, f.created_at, f.updated_at,
+           (-(f.search_text <@> q.bq))::double precision AS rank
+    FROM "{{SCHEMA}}".facts f,
+         (SELECT to_bm25query(p_query, '{{SCHEMA}}.idx_facts_lexical') AS bq) q
+    WHERE (f.search_text <@> q.bq) < 0
+      AND "{{SCHEMA}}".facts_acl(f.shared, f.session_id, p_reader, p_granted, p_unrestricted, p_scope)
+      AND (p_ns_prefix IS NULL OR f.key LIKE p_ns_prefix)
+      AND (p_tags IS NULL OR f.tags @> p_tags)
+    ORDER BY f.search_text <@> q.bq ASC
+    LIMIT p_pool;
+$$;
+
+-- ── semantic search (pgvector cosine; model-matched rows only — 01 §5.2) ────
+
+CREATE OR REPLACE FUNCTION "{{SCHEMA}}".facts_search_semantic(
+    p_vec          vector,
+    p_model        TEXT,
+    p_reader       TEXT,
+    p_granted      TEXT[],
+    p_unrestricted BOOLEAN,
+    p_scope        TEXT,
+    p_ns_prefix    TEXT,
+    p_tags         TEXT[],
+    p_min          DOUBLE PRECISION,
+    p_pool         INT
+) RETURNS TABLE (
+    scope_key TEXT, key TEXT, value JSONB, agent_id TEXT, session_id TEXT,
+    shared BOOLEAN, tags TEXT[], created_at TIMESTAMPTZ, updated_at TIMESTAMPTZ,
+    sim DOUBLE PRECISION
+)
+LANGUAGE sql STABLE AS $$
+    SELECT f.scope_key, f.key, f.value, f.agent_id, f.session_id,
+           f.shared, f.tags, f.created_at, f.updated_at,
+           (1 - (f.embedding <=> p_vec))::double precision AS sim
+    FROM "{{SCHEMA}}".facts f
+    WHERE f.embedding IS NOT NULL
+      AND f.embedding_model IS NOT DISTINCT FROM p_model     -- mismatched model ⇒ treated as NULL embedding
+      AND "{{SCHEMA}}".facts_acl(f.shared, f.session_id, p_reader, p_granted, p_unrestricted, p_scope)
+      AND (p_ns_prefix IS NULL OR f.key LIKE p_ns_prefix)
+      AND (p_tags IS NULL OR f.tags @> p_tags)
+      AND (1 - (f.embedding <=> p_vec)) >= coalesce(p_min, 0)
+    ORDER BY f.embedding <=> p_vec ASC
+    LIMIT p_pool;
+$$;
+
+-- ── similarFacts (kNN of a known fact; anchor ACL-checked IN the proc) ──────
+-- An existing-but-inaccessible anchor yields zero rows, byte-identical to an
+-- unknown key (01 §4.3 — no similarity oracle). Neighbours must carry the
+-- anchor's embedding_model (cross-model vectors are not comparable); when
+-- p_model is supplied (an endpoint is configured) the anchor must match it too.
+
+CREATE OR REPLACE FUNCTION "{{SCHEMA}}".facts_similar(
+    p_scope_key    TEXT,
+    p_model        TEXT,
+    p_reader       TEXT,
+    p_granted      TEXT[],
+    p_unrestricted BOOLEAN,
+    p_scope        TEXT,
+    p_ns_prefix    TEXT,
+    p_min          DOUBLE PRECISION,
+    p_k            INT
+) RETURNS TABLE (
+    scope_key TEXT, key TEXT, value JSONB, agent_id TEXT, session_id TEXT,
+    shared BOOLEAN, tags TEXT[], created_at TIMESTAMPTZ, updated_at TIMESTAMPTZ,
+    sim DOUBLE PRECISION
+)
+LANGUAGE sql STABLE AS $$
+    WITH anchor AS (
+        SELECT a.embedding, a.embedding_model
+        FROM "{{SCHEMA}}".facts a
+        WHERE a.scope_key = p_scope_key
+          AND a.embedding IS NOT NULL
+          AND (p_model IS NULL OR a.embedding_model IS NOT DISTINCT FROM p_model)
+          AND "{{SCHEMA}}".facts_acl(a.shared, a.session_id, p_reader, p_granted, p_unrestricted, p_scope)
+    )
+    SELECT f.scope_key, f.key, f.value, f.agent_id, f.session_id,
+           f.shared, f.tags, f.created_at, f.updated_at,
+           (1 - (f.embedding <=> a.embedding))::double precision AS sim
+    FROM "{{SCHEMA}}".facts f, anchor a
+    WHERE f.scope_key <> p_scope_key
+      AND f.embedding IS NOT NULL
+      AND f.embedding_model IS NOT DISTINCT FROM a.embedding_model
+      AND "{{SCHEMA}}".facts_acl(f.shared, f.session_id, p_reader, p_granted, p_unrestricted, p_scope)
+      AND (p_ns_prefix IS NULL OR f.key LIKE p_ns_prefix)
+      AND (1 - (f.embedding <=> a.embedding)) >= coalesce(p_min, 0)
+    ORDER BY f.embedding <=> a.embedding ASC
+    LIMIT p_k;
+$$;
+
+-- ── crawl tracking (PRIVILEGED harvester surface — 01 §6.6) ─────────────────
+-- No access context: the crawler reads everything by design. The mark is
+-- guarded against the read→mark TOCTOU race: a stamp applies only WHERE
+-- content_hash still equals the supplied hash; mismatches are skipped.
+
+CREATE OR REPLACE FUNCTION "{{SCHEMA}}".facts_read_uncrawled(
+    p_ns_prefix TEXT,
+    p_limit     INT
+) RETURNS SETOF "{{SCHEMA}}".facts
+LANGUAGE sql STABLE AS $$
+    SELECT f.* FROM "{{SCHEMA}}".facts f
+    WHERE f.last_crawled_at IS NULL
+      AND (p_ns_prefix IS NULL OR f.key LIKE p_ns_prefix)
+    ORDER BY f.id
+    LIMIT p_limit;
+$$;
+
+CREATE OR REPLACE FUNCTION "{{SCHEMA}}".facts_mark_crawled(p_stamps JSONB)
+RETURNS TABLE (marked INT, skipped INT)
+LANGUAGE sql AS $$
+    WITH stamps AS (
+        SELECT e->>'scopeKey' AS scope_key, e->>'contentHash' AS content_hash
+        FROM jsonb_array_elements(p_stamps) e
+    ),
+    upd AS (
+        UPDATE "{{SCHEMA}}".facts f
+           SET last_crawled_at = now()
+          FROM stamps s
+         WHERE f.scope_key = s.scope_key
+           AND f.content_hash = s.content_hash
+        RETURNING f.scope_key
+    )
+    SELECT (SELECT count(*) FROM upd)::int AS marked,
+           ((SELECT count(*) FROM stamps) - (SELECT count(*) FROM upd))::int AS skipped;
+$$;

package/migrations/0005_embedder_workflow.sql

@@ -0,0 +1,119 @@
+-- 0005_embedder_workflow — pg_durable grant + the eternal batch-embedding
+-- loop builder (03-design §3).
+--
+-- The loop is ONE durable instance per schema (label hz-embed-cron:<schema>):
+--
+--   df.loop( df.seq( df.sleep(interval),
+--            df.as(df.sql(<batch select>), 'batch'),
+--            df.if_rows('batch',
+--                df.seq(df.as(df.http(url, POST, '$batch.body', hdrs), 'resp'),
+--                       df.sql(<zip-back update>)),
+--                df.sql('SELECT 1')) ) )
+--
+-- One HTTP request per BATCH (array-input API), never per fact — no df-in-df.
+--
+-- Config snapshot semantics: endpoint config lives in durable vars
+-- (hz_<schema>_url/_model/...; written by configureEmbedder). This builder
+-- reads them via df.getvar() and bakes LITERALS into the workflow definition,
+-- so the running instance captures config at df.start exactly like {var}
+-- substitution would — and configureEmbedder restarts the loop to apply
+-- changes. (Literal-baking avoids the whole-body '{var}' escaping risk
+-- flagged in 03-design §7 for everything except the body, which must be the
+-- runtime step result '$batch.body'.)
+--
+-- Write-back guard: last_embedded_hash is set from the hashes captured at
+-- SELECT time ($batch.hashes), never the row's current content_hash — a fact
+-- edited mid-flight stays pending (01 §5.3).
+--
+-- Tokens: {{SCHEMA}}.
+
+CREATE EXTENSION IF NOT EXISTS pg_durable;
+
+DO $$
+BEGIN
+    PERFORM df.grant_usage(current_user, true, false);
+EXCEPTION WHEN OTHERS THEN
+    NULL;  -- may already be granted / insufficient privilege; surfaced by preconditions if it matters
+END $$;
+
+CREATE OR REPLACE FUNCTION "{{SCHEMA}}".embedder_workflow(p_interval int, p_batch int)
+RETURNS text
+LANGUAGE plpgsql AS $fn$
+DECLARE
+    v_url        text;
+    v_model      text;
+    v_key        text;
+    v_keyhdr     text;
+    v_bearer     text;
+    v_inputfield text;
+    v_timeout    int;
+    v_headers    jsonb;
+    v_batch_sql  text;
+    v_zip_sql    text;
+BEGIN
+    v_url        := df.getvar('hz_{{SCHEMA}}_url');
+    v_model      := df.getvar('hz_{{SCHEMA}}_model');
+    v_key        := df.getvar('hz_{{SCHEMA}}_key');
+    v_keyhdr     := coalesce(df.getvar('hz_{{SCHEMA}}_keyhdr'), 'api-key');
+    v_bearer     := coalesce(df.getvar('hz_{{SCHEMA}}_bearer'), 'false');
+    v_inputfield := coalesce(df.getvar('hz_{{SCHEMA}}_inputfield'), 'input');
+    v_timeout    := coalesce(df.getvar('hz_{{SCHEMA}}_timeout'), '30')::int;
+
+    IF v_url IS NULL OR v_model IS NULL THEN
+        RAISE EXCEPTION 'embedder not configured: call configureEmbedder first (durable vars hz_{{SCHEMA}}_url / hz_{{SCHEMA}}_model missing)';
+    END IF;
+
+    v_headers := jsonb_build_object('content-type', 'application/json');
+    IF v_key IS NOT NULL AND v_key <> '' THEN
+        v_headers := v_headers || jsonb_build_object(
+            v_keyhdr,
+            CASE WHEN v_bearer = 'true' THEN 'Bearer ' || v_key ELSE v_key END
+        );
+    END IF;
+
+    -- Batch select: ONE row (or zero when nothing pending — HAVING) carrying
+    -- the ready-to-send body plus positional ids/hashes for the zip-back.
+    -- Pending = NULL embedding, stale hash, or model mismatch (01 §5.2).
+    v_batch_sql := format(
+        $q$SELECT jsonb_build_object(%L, jsonb_agg(t.txt ORDER BY t.id), 'model', %L)::text AS body,
+                  array_agg(t.id ORDER BY t.id)::text   AS ids,
+                  array_agg(t.content_hash ORDER BY t.id)::text AS hashes
+           FROM (SELECT id, content_hash, coalesce(search_text, '') AS txt
+                 FROM "{{SCHEMA}}".facts
+                 WHERE embedding IS NULL
+                    OR last_embedded_hash IS DISTINCT FROM content_hash
+                    OR embedding_model IS DISTINCT FROM %L
+                 ORDER BY id
+                 LIMIT %s) t
+           HAVING count(*) > 0$q$,
+        v_inputfield, v_model, v_model, greatest(p_batch, 1));
+
+    -- Zip-back: data[i] ↔ ids[i] positionally (WITH ORDINALITY); write the
+    -- SELECT-time hash, stamp the model.
+    v_zip_sql := format(
+        $q$WITH resp AS (SELECT ($resp::jsonb->>'body')::jsonb AS j),
+                emb  AS (SELECT v.ord, v.e->'embedding' AS vec
+                         FROM resp, jsonb_array_elements(resp.j->'data') WITH ORDINALITY AS v(e, ord)),
+                tgt  AS (SELECT u.id, u.h, u.ord
+                         FROM unnest(($batch.ids)::bigint[], ($batch.hashes)::text[]) WITH ORDINALITY AS u(id, h, ord))
+           UPDATE "{{SCHEMA}}".facts f
+              SET embedding          = (emb.vec)::text::vector,
+                  embedded_at        = now(),
+                  embedding_model    = %L,
+                  last_embedded_hash = tgt.h
+             FROM emb JOIN tgt ON tgt.ord = emb.ord
+            WHERE f.id = tgt.id$q$,
+        v_model);
+
+    RETURN df.loop(
+        df.seq(
+            df.sleep(greatest(p_interval, 1)::bigint),
+            df.seq(
+                df.as(df.sql(v_batch_sql), 'batch'),
+                df.if_rows('batch',
+                    df.seq(
+                        df.as(df.http(v_url, 'POST', '$batch.body', v_headers, v_timeout), 'resp'),
+                        df.sql(v_zip_sql)),
+                    df.sql('SELECT 1')))),
+        NULL);
+END $fn$;

package/migrations/0006_facts_read_uncrawled_embedded_gate.sql

@@ -0,0 +1,33 @@
+-- 0006_facts_read_uncrawled_embedded_gate — add an OPTIONAL embedding gate to
+-- the crawl-queue read (01 §5.2 / §6.6 harvester surface).
+--
+-- Why: the harvester now refines the graph with similarity search over each
+-- fact's STORED embedding (facts_similar). A fact with no embedding yet cannot
+-- be similarity-refined, so handing it to the harvester early produces a
+-- thinner graph. With p_embedded_only => TRUE the queue read SKIPS facts whose
+-- embedding is still NULL; they stay uncrawled and reappear on a later turn
+-- once the in-DB embed loop (0005) has filled them in. The ungated 2-arg
+-- behaviour is preserved as the default (FALSE) so the done-check and any
+-- embedding-less deployment keep draining the whole queue.
+--
+-- Signature change (added param) cannot be done with CREATE OR REPLACE, so the
+-- old 2-arg function is dropped first; the new 3-arg form has a DEFAULT so the
+-- prior 2-arg call sites bind unchanged.
+--
+-- Tokens: {{SCHEMA}}.
+
+DROP FUNCTION IF EXISTS "{{SCHEMA}}".facts_read_uncrawled(TEXT, INT);
+
+CREATE OR REPLACE FUNCTION "{{SCHEMA}}".facts_read_uncrawled(
+    p_ns_prefix     TEXT,
+    p_limit         INT,
+    p_embedded_only BOOLEAN DEFAULT FALSE
+) RETURNS SETOF "{{SCHEMA}}".facts
+LANGUAGE sql STABLE AS $$
+    SELECT f.* FROM "{{SCHEMA}}".facts f
+    WHERE f.last_crawled_at IS NULL
+      AND (p_ns_prefix IS NULL OR f.key LIKE p_ns_prefix)
+      AND (NOT p_embedded_only OR f.embedding IS NOT NULL)
+    ORDER BY f.id
+    LIMIT p_limit;
+$$;

package/migrations/0007_embed_key_value_text.sql

@@ -0,0 +1,122 @@
+-- 0007_embed_key_value_text — embed the KEY + the FULL VALUE, not the
+-- cherry-picked search_text columns (03-design §3, embed-input correctness).
+--
+-- WHY. The 0005 embedder built its per-fact input from `search_text`, a STORED
+-- generated column that concatenates only a fixed set of conventional value
+-- fields:
+--
+--   coalesce(key,'') || ' ' || value->>'name' || ' ' || value->>'description'
+--                    || ' ' || value->>'text' || ' ' || value->>'body'
+--                    || ' ' || value->>'subject'
+--
+-- For a fact whose value uses ANY other shape — e.g. a harvested document
+-- stored as { "title": ..., "content": ... } — none of those fields match, so
+-- search_text collapses to essentially just the key and the embedding carries
+-- almost no signal. The vector column then exists but is useless for semantic /
+-- hybrid retrieval and for the harvester's facts_similar refinement (0006).
+--
+-- FIX. Embed `key` + a delimiter + the WHOLE value rendered as text, so the
+-- embedding represents the entire fact regardless of value shape:
+--
+--   coalesce(key,'') || E'\n' || coalesce(value::text,'')
+--
+-- This mirrors how content_hash already keys off `key || value::text` (0001):
+-- the embed input now covers exactly what the hash covers, so "content changed
+-- ⇒ re-embed" stays coherent. `search_text` (lexical/BM25) is intentionally
+-- left unchanged — this migration only changes the EMBEDDING input text.
+--
+-- Only the `t.txt` projection inside v_batch_sql changes versus 0005; the loop
+-- shape, batching, config-var reads, and zip-back write-back are identical. This
+-- is a CREATE OR REPLACE of the workflow BUILDER. A loop instance that is
+-- already running was baked from the old function body at df.start and will keep
+-- using the old text until it is cancelled and restarted (configureEmbedder
+-- restart, stopEmbedder + startEmbedder, or a fresh deploy after the schema +
+-- durable instance are dropped). New deployments pick it up immediately.
+--
+-- Tokens: {{SCHEMA}}.
+
+CREATE OR REPLACE FUNCTION "{{SCHEMA}}".embedder_workflow(p_interval int, p_batch int)
+RETURNS text
+LANGUAGE plpgsql AS $fn$
+DECLARE
+    v_url        text;
+    v_model      text;
+    v_key        text;
+    v_keyhdr     text;
+    v_bearer     text;
+    v_inputfield text;
+    v_timeout    int;
+    v_headers    jsonb;
+    v_batch_sql  text;
+    v_zip_sql    text;
+BEGIN
+    v_url        := df.getvar('hz_{{SCHEMA}}_url');
+    v_model      := df.getvar('hz_{{SCHEMA}}_model');
+    v_key        := df.getvar('hz_{{SCHEMA}}_key');
+    v_keyhdr     := coalesce(df.getvar('hz_{{SCHEMA}}_keyhdr'), 'api-key');
+    v_bearer     := coalesce(df.getvar('hz_{{SCHEMA}}_bearer'), 'false');
+    v_inputfield := coalesce(df.getvar('hz_{{SCHEMA}}_inputfield'), 'input');
+    v_timeout    := coalesce(df.getvar('hz_{{SCHEMA}}_timeout'), '30')::int;
+
+    IF v_url IS NULL OR v_model IS NULL THEN
+        RAISE EXCEPTION 'embedder not configured: call configureEmbedder first (durable vars hz_{{SCHEMA}}_url / hz_{{SCHEMA}}_model missing)';
+    END IF;
+
+    v_headers := jsonb_build_object('content-type', 'application/json');
+    IF v_key IS NOT NULL AND v_key <> '' THEN
+        v_headers := v_headers || jsonb_build_object(
+            v_keyhdr,
+            CASE WHEN v_bearer = 'true' THEN 'Bearer ' || v_key ELSE v_key END
+        );
+    END IF;
+
+    -- Batch select: ONE row (or zero when nothing pending — HAVING) carrying
+    -- the ready-to-send body plus positional ids/hashes for the zip-back.
+    -- Pending = NULL embedding, stale hash, or model mismatch (01 §5.2).
+    --
+    -- Embed input (CHANGED in 0007): key + delimiter + the FULL value as text,
+    -- so any value shape is represented — not just the search_text fields.
+    v_batch_sql := format(
+        $q$SELECT jsonb_build_object(%L, jsonb_agg(t.txt ORDER BY t.id), 'model', %L)::text AS body,
+                  array_agg(t.id ORDER BY t.id)::text   AS ids,
+                  array_agg(t.content_hash ORDER BY t.id)::text AS hashes
+           FROM (SELECT id, content_hash,
+                        coalesce(key, '') || E'\n' || coalesce(value::text, '') AS txt
+                 FROM "{{SCHEMA}}".facts
+                 WHERE embedding IS NULL
+                    OR last_embedded_hash IS DISTINCT FROM content_hash
+                    OR embedding_model IS DISTINCT FROM %L
+                 ORDER BY id
+                 LIMIT %s) t
+           HAVING count(*) > 0$q$,
+        v_inputfield, v_model, v_model, greatest(p_batch, 1));
+
+    -- Zip-back: data[i] ↔ ids[i] positionally (WITH ORDINALITY); write the
+    -- SELECT-time hash, stamp the model. (Unchanged from 0005.)
+    v_zip_sql := format(
+        $q$WITH resp AS (SELECT ($resp::jsonb->>'body')::jsonb AS j),
+                emb  AS (SELECT v.ord, v.e->'embedding' AS vec
+                         FROM resp, jsonb_array_elements(resp.j->'data') WITH ORDINALITY AS v(e, ord)),
+                tgt  AS (SELECT u.id, u.h, u.ord
+                         FROM unnest(($batch.ids)::bigint[], ($batch.hashes)::text[]) WITH ORDINALITY AS u(id, h, ord))
+           UPDATE "{{SCHEMA}}".facts f
+              SET embedding          = (emb.vec)::text::vector,
+                  embedded_at        = now(),
+                  embedding_model    = %L,
+                  last_embedded_hash = tgt.h
+             FROM emb JOIN tgt ON tgt.ord = emb.ord
+            WHERE f.id = tgt.id$q$,
+        v_model);
+
+    RETURN df.loop(
+        df.seq(
+            df.sleep(greatest(p_interval, 1)::bigint),
+            df.seq(
+                df.as(df.sql(v_batch_sql), 'batch'),
+                df.if_rows('batch',
+                    df.seq(
+                        df.as(df.http(v_url, 'POST', '$batch.body', v_headers, v_timeout), 'resp'),
+                        df.sql(v_zip_sql)),
+                    df.sql('SELECT 1')))),
+        NULL);
+END $fn$;