Fix re-critique: complete SQL bridge rename, runnable rebuild recipe, readiness-probe doc

- Finish the createEmbedRegistrySqlClient -> createRawSqlClient rename at
  the four remaining internal call sites (search.ts:11,521,639,
  capture.ts:29,503) and delete the now-unused deprecated alias — the
  symbol was never exported, so it had no external consumer to protect.
- The rebuild recipe (fts-language.ts error text + IMPLEMENTATION.md) wrapped
  CREATE INDEX CONCURRENTLY inside BEGIN/COMMIT, which Postgres has rejected
  unconditionally since 8.2 (not version-dependent, as previously claimed).
  Verified against a live postgres:16 container: the wrapped form fails with
  "CREATE INDEX CONCURRENTLY cannot run inside a transaction block"; the
  split form (BEGIN/ALTER/ALTER/COMMIT, then CONCURRENTLY as its own
  statement) succeeds. Both error sites now share one verified recipe via
  rebuildColumnRecipe().
- The schema-qualified-config error previously said "see the recipe below"
  with nothing below it in the thrown string; it now includes the same
  recipe inline.
- Documented the FTS verification gap explicitly (mount-time comment in
  knowledge.ts, IMPLEMENTATION.md x2): the serving-path check is lazy and
  memoized, not boot-time — a host that neither runs runKnowledgeMigrations
  nor wires its own readiness probe learns about a language mismatch on the
  first real query, not at mount. Not re-architected, per instructions —
  made explicit instead.

Claude-Session: https://claude.ai/code/session_017GTgGzn5xAwvkU2GAPAHpF

Author: TheGreatAxios

IMPLEMENTATION.md

@@ -41,6 +41,12 @@ routes; each reads identity from the context (`caller(c)`) and guards via
 singletons except the logger). Nothing has import-time side effects, so unit
 tests exercise the routes and services directly without a listening server.
 
+Mounting does **not** verify the FTS language against the database at boot —
+see the `knowledge_chunk` section below. A host is expected to either run
+`runKnowledgeMigrations` itself (which verifies) or wire its own readiness
+probe to call `verifyFtsLanguage`; without one of those, a language mismatch
+surfaces as a runtime failure on the plane's first query, not at mount time.
+
 ## Config
 
 There are two config types, both in the SDK:
@@ -136,33 +142,45 @@ read-only against the catalog: `runKnowledgeMigrations` checks after
 applying (the deploy step), and the knowledge plane runs the same check
 once, memoized, before its first query (the serving path) — so a mismatch
 or unmigrated schema fails loudly on first use regardless of who ran the
-migrations. Hosts with a readiness probe can call the exported
-`verifyFtsLanguage` there instead. Chunks are **never** reused across
-versions — every new version gets a fresh full insert of its own chunks.
+migrations. **The serving-path check only runs when something actually
+calls it** — `search()`/`capture()` invoke it lazily and memoize the result,
+but nothing forces that first call to happen at boot. A host that mounts the
+engine without running `runKnowledgeMigrations` itself and without wiring a
+readiness probe will not learn about a language mismatch until the first
+real query or capture fails — not at startup. Hosts that want a boot-time
+guarantee **must** call the exported `verifyFtsLanguage` from their own
+readiness probe; it is not optional belt-and-suspenders, it is the only way
+to get a boot-time check if this SDK instance isn't the one that migrated.
+Chunks are **never** reused across versions — every new version gets a
+fresh full insert of its own chunks.
 
 **Changing `FTS_LANGUAGE` on an already-migrated database** (the mismatch
 `verifyFtsLanguage` throws on) requires rebuilding the generated column —
 `runKnowledgeMigrations` only applies new files and will not retroactively
-alter an existing one. One-time recipe:
+alter an existing one. One-time recipe (verified against a live
+`postgres:16` instance):
 
 ```sql
 BEGIN;
+DROP INDEX IF EXISTS knowledge_chunk_text_fts_idx;
 ALTER TABLE knowledge_chunk DROP COLUMN text_fts;
 ALTER TABLE knowledge_chunk ADD COLUMN text_fts tsvector
   GENERATED ALWAYS AS (to_tsvector('<new_language>', "text")) STORED;
-CREATE INDEX CONCURRENTLY knowledge_chunk_text_fts_idx ON knowledge_chunk USING gin (text_fts);
 COMMIT;
+
+-- Separate statement/connection — CREATE INDEX CONCURRENTLY is rejected
+-- inside any transaction block, unconditionally, since Postgres 8.2. It
+-- cannot be combined with the BEGIN/COMMIT block above.
+CREATE INDEX CONCURRENTLY knowledge_chunk_text_fts_idx ON knowledge_chunk USING gin (text_fts);
 ```
 
 Both `ALTER TABLE` statements take an `ACCESS EXCLUSIVE` lock and force a
 full table rewrite (dropping then re-adding a `STORED` generated column
 always rewrites) — plan for a stall on `knowledge_chunk` for the duration on
-a populated database; run in a maintenance window. `CREATE INDEX
-CONCURRENTLY` cannot run inside the same transaction as the `ALTER`s on some
-Postgres versions — if it errors there, `COMMIT` the `ALTER`s first and run
-the index creation as a separate statement. Only unqualified `pg_catalog`
-config names are supported; a schema-qualified config on this column is
-rejected explicitly by `verifyFtsLanguage` rather than silently mis-parsed.
+a populated database; run in a maintenance window. Only unqualified
+`pg_catalog` config names are supported; a schema-qualified config on this
+column is rejected explicitly by `verifyFtsLanguage` (with this same recipe
+in the error) rather than silently mis-parsed.
 
 ### `knowledge_entity` / `knowledge_edge`
 Lightweight graph rows. `knowledge_entity` has no unique constraint; dedupe on

src/core/embed-sql.ts

@@ -16,6 +16,3 @@ export function createRawSqlClient(sql: RawSql): EmbedRegistrySqlClient {
     },
   };
 }
-
-/** @deprecated Use `createRawSqlClient` — same bridge, name predates its FTS use. */
-export const createEmbedRegistrySqlClient = createRawSqlClient;

src/core/fts-language.ts

@@ -51,6 +51,32 @@ export function createFtsVerification(
     }));
 }
 
+/**
+ * The one-time column-rebuild recipe, shared by every error that needs to
+ * point an operator at it. `CREATE INDEX CONCURRENTLY` is deliberately its
+ * own statement, outside the `BEGIN`/`COMMIT` block: Postgres has rejected
+ * CONCURRENTLY inside a transaction block unconditionally since 8.2 (not a
+ * version-dependent quirk) — wrapping it in the same transaction as the
+ * ALTERs makes this recipe fail outright instead of fixing anything.
+ * Verified against a real postgres:16 container before being written here.
+ */
+function rebuildColumnRecipe(language: string): string {
+  return (
+    `  BEGIN;\n` +
+    `  DROP INDEX IF EXISTS knowledge_chunk_text_fts_idx;\n` +
+    `  ALTER TABLE knowledge_chunk DROP COLUMN text_fts;\n` +
+    `  ALTER TABLE knowledge_chunk ADD COLUMN text_fts tsvector\n` +
+    `    GENERATED ALWAYS AS (to_tsvector('${language}', "text")) STORED;\n` +
+    `  COMMIT;\n\n` +
+    `  -- Separate statement/connection — CANNOT run inside the transaction\n` +
+    `  -- above, or any transaction block, ever:\n` +
+    `  CREATE INDEX CONCURRENTLY knowledge_chunk_text_fts_idx ON knowledge_chunk USING gin (text_fts);\n\n` +
+    `Both ALTER TABLE statements take an ACCESS EXCLUSIVE lock and rewrite the table ` +
+    `(DROP COLUMN then re-adding a STORED generated column forces a full rewrite) — ` +
+    `expect a stall on this table for the duration on a populated database; run during a maintenance window.`
+  );
+}
+
 export interface FtsVerifySqlClient {
   query: (sql: string, params: readonly unknown[]) => Promise<Array<Record<string, unknown>>>;
 }
@@ -106,26 +132,16 @@ export async function verifyFtsLanguage(
     throw new Error(
       `knowledge_chunk.text_fts was built with the schema-qualified text search config "${schema}.${applied}", ` +
         `but FTS_LANGUAGE only supports unqualified pg_catalog configs. ` +
-        `Either drop the schema qualification (move/alias the config into pg_catalog) or rebuild the column — see the recipe below.`,
+        `Either drop the schema qualification (move/alias the config into pg_catalog), or rebuild the column ` +
+        `under an unqualified config name:\n\n${rebuildColumnRecipe(ftsLanguage)}`,
     );
   }
   if (applied !== ftsLanguage) {
     throw new Error(
       `FTS language mismatch: knowledge_chunk.text_fts was built with "${applied}" but the configuration says "${ftsLanguage}". ` +
         `Search would silently stem queries differently than the index.\n\n` +
-        `To rebuild the column under the new language:\n` +
-        `  BEGIN;\n` +
-        `  ALTER TABLE knowledge_chunk DROP COLUMN text_fts;\n` +
-        `  ALTER TABLE knowledge_chunk ADD COLUMN text_fts tsvector\n` +
-        `    GENERATED ALWAYS AS (to_tsvector('${ftsLanguage}', "text")) STORED;\n` +
-        `  CREATE INDEX CONCURRENTLY knowledge_chunk_text_fts_idx ON knowledge_chunk USING gin (text_fts);\n` +
-        `  COMMIT;\n\n` +
-        `Both ALTER TABLE statements take an ACCESS EXCLUSIVE lock and rewrite the table ` +
-        `(DROP COLUMN then re-adding a STORED generated column forces a full rewrite) — ` +
-        `expect a stall on this table for the duration on a populated database; run during a ` +
-        `maintenance window. CREATE INDEX CONCURRENTLY cannot run inside the same transaction as ` +
-        `the ALTERs on some Postgres versions — if it errors there, commit the ALTERs first, then ` +
-        `run the index creation separately. Or, fix FTS_LANGUAGE back to "${applied}" instead.`,
+        `To rebuild the column under the new language:\n\n${rebuildColumnRecipe(ftsLanguage)}\n\n` +
+        `Or, fix FTS_LANGUAGE back to "${applied}" instead.`,
     );
   }
 }

src/knowledge.ts

@@ -63,8 +63,13 @@ export function createKnowledgePlane(config: KnowledgeConfig): KnowledgePlane {
   // (Hibernate validate / Rails check_all_pending!): the mount is
   // synchronous, so "before accepting traffic" becomes a memoized check
   // awaited by the first query. Read-only; migration stays a deploy step.
-  // Hosts with a real readiness probe can call verifyFtsLanguage there
-  // instead — this memo then resolves against an already-verified schema.
+  // NOTE this is a lazy check, not a boot-time one: nothing forces it to run
+  // until the first real search()/capture() call, so a host that neither
+  // runs runKnowledgeMigrations itself nor wires a readiness probe will not
+  // learn about a language mismatch until that first call fails. A host
+  // that wants a real boot-time guarantee MUST call the exported
+  // verifyFtsLanguage from its own readiness probe — this memo then
+  // resolves instantly against the already-verified schema.
   const ensureVerified = createFtsVerification(
     createRawSqlClient(sql),
     engineConfig.ftsLanguage ?? DEFAULT_FTS_LANGUAGE,

src/services/capture.ts

@@ -26,7 +26,7 @@ import type {
   EntityHint,
 } from "../core/schemas/adapted-document.ts";
 import type { KnowledgeEdgeHint } from "../core/schemas/entity-edge.ts";
-import { createEmbedRegistrySqlClient } from "../core/embed-sql.ts";
+import { createRawSqlClient } from "../core/embed-sql.ts";
 import { activateEmbedModel } from "../core/embed-model-registry.ts";
 import { EmbedClientConfigSchema, type EmbedClientConfig } from "../core/embed-client.ts";
 import { embedChunks, type EmbeddableChunk } from "../core/embed-worker.ts";
@@ -500,7 +500,7 @@ async function embedInsertedChunksWithConfig(
   if (chunks.length === 0) return { degraded: false };
 
   try {
-    const client = createEmbedRegistrySqlClient(sql);
+    const client = createRawSqlClient(sql);
 
     const activeTable = await activateEmbedModel(
       client,

src/services/search.ts

@@ -8,7 +8,7 @@ import {
   knowledgeEdge,
   knowledgeVersion,
 } from "../db/schema.ts";
-import { createEmbedRegistrySqlClient } from "../core/embed-sql.ts";
+import { createRawSqlClient } from "../core/embed-sql.ts";
 import {
   cosineDistanceExpr,
   EMBED_TABLE_NAME_PATTERN,
@@ -518,7 +518,7 @@ export async function fetchDenseCandidates(
 
   if (query === "") return null;
 
-  const embedSqlClient = createEmbedRegistrySqlClient(rawSql);
+  const embedSqlClient = createRawSqlClient(rawSql);
   const activeTable = await resolveActiveEmbedTable(embedSqlClient, tenantId);
   if (!activeTable) return null;
 
@@ -636,7 +636,7 @@ async function fetchChunkVectors(
 ): Promise<Map<string, number[]>> {
   if (chunkIds.length === 0) return new Map();
 
-  const embedSqlClient = createEmbedRegistrySqlClient(rawSql);
+  const embedSqlClient = createRawSqlClient(rawSql);
   const activeTable = await resolveActiveEmbedTable(embedSqlClient, tenantId);
   if (!activeTable) return new Map();