@stigmer/server 3.14.0-dev.20260910084630

package/src/store/postgres/tsquery.ts

@@ -0,0 +1,80 @@
+/**
+ * tsquery rendering and score normalization — the Postgres driver's
+ * engine-specific half of the search read contract (DD-009: the Store
+ * interface carries engine-neutral terms and wire-ready 0–1 scores; each
+ * driver renders its own engine's syntax and normalizes its own engine's
+ * ranking). The sqlite counterpart is sqlite/fts5.ts.
+ *
+ * Declared seam semantics implemented here (interface.ts SearchIndexQuery):
+ * each term matches as a token, a SINGLE term is a prefix match, multiple
+ * terms compose with AND. Tokenization/stemming is driver-relative — this
+ * driver uses the 'english' text search config (Snowball stemming, the
+ * closest analog to FTS5's porter tokenizer), declared once here and in
+ * the migration's generated tsvector.
+ *
+ * Weighting: the sqlite driver's bm25 vector spans FIVE columns (kind=1,
+ * resource_id=0, name=10, description=5, tags=5); Postgres setweight has
+ * exactly FOUR classes (A–D), so a one-to-one mapping is impossible.
+ * DD-009 makes ranking driver-relative — the only cross-driver requirement
+ * (interface.ts SearchIndexEntry) is that name weighs highest. This driver
+ * maps name=A, tags=B, description=C; kind and resource_id are not part of
+ * the searchable document at all (their FTS5 weights, 1 and 0, made them
+ * near-noise there too).
+ *
+ * Proven by __tests__/tsquery.test.ts (rendering/sanitization/
+ * normalization tables, the fts5.test.ts pattern) and
+ * search.conformance.test.ts on local-postgres.
+ */
+
+/**
+ * Renders the tsquery expression for engine-neutral search terms: every
+ * term individually quoted as a lexeme string (tsquery operator syntax —
+ * &, |, !, <->, parentheses — becomes literal text inside quotes);
+ * embedded single quotes and backslashes stripped (either would terminate
+ * or escape the quoted lexeme); a term left empty by stripping is dropped.
+ * A SINGLE surviving term gets a trailing `:*` for prefix matching (valid
+ * on quoted lexemes) — the prefix decision counts terms AFTER
+ * sanitization, mirroring the Go-ported FTS5 order. Multi-term
+ * expressions compose with explicit `&` (AND).
+ *
+ * Terms that sanitize to nothing render "" — to_tsquery rejects an empty
+ * expression, which surfaces as the same store failure the FTS5 driver
+ * produces for such queries (behavior preserved, not beautified).
+ */
+export function renderTsQueryExpression(terms: readonly string[]): string {
+  const quoted: string[] = [];
+  for (const term of terms) {
+    const clean = term.replaceAll("'", "").replaceAll("\\", "");
+    if (clean === "") {
+      continue;
+    }
+    quoted.push(`'${clean}'`);
+  }
+
+  if (quoted.length === 0) {
+    return "";
+  }
+  if (quoted.length === 1) {
+    return `${quoted[0]}:*`;
+  }
+  return quoted.join(" & ");
+}
+
+/**
+ * ts_rank → the wire's 0–1 (higher = better). ts_rank with default
+ * normalization is already higher-is-better and effectively small-positive
+ * (typically well under 1; unbounded above only in pathological
+ * documents), so the mapping is a clamp — absolute values and cross-driver
+ * ordering are explicitly NOT contract (DD-009), only deterministic
+ * ordering within this driver is. List mode never reaches this function
+ * (its score is pinned exactly 1.0 by the driver).
+ */
+export function normalizeTsRankScore(tsRank: number): number {
+  if (tsRank < 0) {
+    return 0;
+  }
+  if (tsRank > 1) {
+    return 1;
+  }
+  return tsRank;
+}

package/src/store/proto-fields.ts

@@ -0,0 +1,212 @@
+/**
+ * Proto reflection helpers shared by every store driver — ports the private
+ * helpers in the retired Go server's backend/libs/go/store/sqlite/store.go
+ * (extractFieldValue :991, toSnakeCase :1027, extractLabelValue :951, git
+ * history) plus the kind-name mapping Go got from `kind.String()`.
+ *
+ * Lived at sqlite/proto-fields.ts through Phase 1; promoted here when the
+ * Postgres driver became the second consumer (the codecs/gocompat
+ * second-consumer rule) — by then five modules OUTSIDE the driver already
+ * imported it, so the move also restores the layering the path implied.
+ * Nothing in this module is engine-specific: both drivers store resources
+ * as marshaled proto bytes and implement the find* contracts as
+ * deserialize-and-scan (the interface documents the full-scan semantics).
+ *
+ * The kind's PROTO NAME is a physical-layout constant: it is the value of
+ * the `kind` column in every table the Go server ever wrote, so every
+ * driver must produce the identical string for the identical enum value —
+ * byte-pinned by __tests__/proto-fields.test.ts.
+ */
+import { enumToJson } from "@bufbuild/protobuf";
+import type { DescField, DescMessage, MessageShape } from "@bufbuild/protobuf";
+import { fromBinary } from "@bufbuild/protobuf";
+import { reflect } from "@bufbuild/protobuf/reflect";
+import type { ReflectMessage } from "@bufbuild/protobuf/reflect";
+import type { Message } from "@bufbuild/protobuf";
+
+import {
+  ApiResourceKind,
+  ApiResourceKindSchema,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+/**
+ * The kind's proto enum value name (Go: kind.String()), e.g.
+ * ApiResourceKind.organization → "organization". An unknown value throws
+ * (enumToJson's own error) — an unknown kind reaching storage is a
+ * programming error, never data.
+ */
+export function apiResourceKindName(kind: ApiResourceKind): string {
+  return enumToJson(ApiResourceKindSchema, kind) as string;
+}
+
+/**
+ * Extracts a field value as a string by dot-notation path (e.g.
+ * "spec.executionId"). Path parts match the proto field name directly,
+ * then fall back through camelCase→snake_case — exactly Go's two-probe
+ * lookup, so the same fieldPath strings the Go callers pass keep working.
+ * Returns "" when the path does not resolve.
+ */
+export function extractFieldValue(
+  schema: DescMessage,
+  msg: Message,
+  fieldPath: string,
+): string {
+  const parts = fieldPath.split(".");
+  let current: ReflectMessage = reflect(schema, msg);
+
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]!;
+    const field = findFieldByProtoName(current, part);
+    if (field === undefined) {
+      return "";
+    }
+
+    if (i === parts.length - 1) {
+      return scalarString(current, field);
+    }
+
+    if (field.fieldKind !== "message") {
+      return "";
+    }
+    current = current.get(field);
+  }
+
+  return "";
+}
+
+/**
+ * Reads metadata.labels[labelKey] via reflection; "" when the metadata
+ * field, the labels map, or the key is absent. Works for any API resource
+ * carrying the standard metadata.labels field.
+ */
+export function extractLabelValue(
+  schema: DescMessage,
+  msg: Message,
+  labelKey: string,
+): string {
+  const root = reflect(schema, msg);
+
+  const metadataField = root.fields.find((f) => f.name === "metadata");
+  if (metadataField === undefined || metadataField.fieldKind !== "message") {
+    return "";
+  }
+  const metadata = root.get(metadataField);
+
+  const labelsField = metadata.fields.find((f) => f.name === "labels");
+  if (labelsField === undefined || labelsField.fieldKind !== "map") {
+    return "";
+  }
+  const labels = metadata.get(labelsField);
+  const value = labels.get(labelKey);
+  return typeof value === "string" ? value : "";
+}
+
+/**
+ * The findByField scan every driver shares: deserialize each stored blob,
+ * probe fieldPath, return the FIRST match (scan order is the driver's row
+ * order — Go's semantics). Malformed records are skipped, as Go does.
+ * Returns undefined when nothing matches — the driver owns the typed
+ * not-found error (it knows the kind name for the message).
+ */
+export function scanForFieldMatch<Desc extends DescMessage>(
+  rows: Iterable<Uint8Array>,
+  schema: Desc,
+  fieldPath: string,
+  value: string,
+): MessageShape<Desc> | undefined {
+  for (const data of rows) {
+    let msg: MessageShape<Desc>;
+    try {
+      msg = fromBinary(schema, data);
+    } catch {
+      continue; // skip malformed records, as Go does
+    }
+    if (extractFieldValue(schema, msg, fieldPath) === value) {
+      return msg;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The findAllByLabel scan every driver shares: deserialize each stored
+ * blob, keep the ORIGINAL bytes of rows whose metadata.labels[labelKey]
+ * equals labelValue (callers receive stored bytes, not re-marshaled ones).
+ * Malformed records are skipped, as Go does.
+ */
+export function filterRowsByLabel<Desc extends DescMessage>(
+  rows: Iterable<Uint8Array>,
+  schema: Desc,
+  labelKey: string,
+  labelValue: string,
+): Uint8Array[] {
+  const results: Uint8Array[] = [];
+  for (const data of rows) {
+    let msg: MessageShape<Desc>;
+    try {
+      msg = fromBinary(schema, data);
+    } catch {
+      continue;
+    }
+    if (extractLabelValue(schema, msg, labelKey) === labelValue) {
+      results.push(data);
+    }
+  }
+  return results;
+}
+
+function findFieldByProtoName(
+  message: ReflectMessage,
+  part: string,
+): DescField | undefined {
+  return (
+    message.fields.find((f) => f.name === part) ??
+    message.fields.find((f) => f.name === toSnakeCase(part))
+  );
+}
+
+/**
+ * Field value → string, mirroring Go protoreflect.Value.String() for the
+ * kinds the callers use: strings pass through, numbers/bools/enums print
+ * their primitive form. List/map/message values are not addressable as
+ * terminal path parts in Go either — they return "".
+ */
+function scalarString(message: ReflectMessage, field: DescField): string {
+  if (field.fieldKind === "list" || field.fieldKind === "map") {
+    return "";
+  }
+  if (field.fieldKind === "message") {
+    return "";
+  }
+  // Enum values reflect as their numbers — matching Go, whose
+  // protoreflect.Value.String() prints an enum's number, not its name.
+  const value = message.get(field);
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "bigint") {
+    return String(value);
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  if (value instanceof Uint8Array) {
+    // Go's Value.String() on bytes stringifies the raw bytes; no store
+    // caller queries a bytes field, so latin1 is a faithful stand-in.
+    return Buffer.from(value).toString("latin1");
+  }
+  return "";
+}
+
+/** camelCase → snake_case (Go toSnakeCase): "executionId" → "execution_id". */
+export function toSnakeCase(value: string): string {
+  let result = "";
+  for (let i = 0; i < value.length; i++) {
+    const ch = value[i]!;
+    if (i > 0 && ch >= "A" && ch <= "Z") {
+      result += "_";
+    }
+    result += ch;
+  }
+  return result.toLowerCase();
+}

package/src/store/rfc3339.ts

@@ -0,0 +1,12 @@
+/**
+ * RFC-3339 UTC, whole seconds (Go time.RFC3339) — the ledger's house
+ * convention for lexicographic comparison of recorded_at / completed_at
+ * strings. Both drivers stamp the same shape so a timestamp written by
+ * one is comparable (and parseable) on the other.
+ *
+ * Lived as a private helper in sqlite/store.ts through Phase 1; promoted
+ * here when the Postgres driver became the second consumer.
+ */
+export function rfc3339Seconds(date: Date): string {
+  return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}

package/src/store/sqlite/__tests__/fixtures/go-v6-database.sql

@@ -0,0 +1,150 @@
+-- Generated by scripts/regen-go-db-fixture.sh — a REAL Go-created
+-- stigmer database at schema v6, for the TS driver's migration-
+-- adoption tests (sub-project DD-002). Do not edit by hand.
+/* WARNING: Script requires that SQLITE_DBCONFIG_DEFENSIVE be disabled */
+PRAGMA foreign_keys=OFF;
+BEGIN TRANSACTION;
+CREATE TABLE schema_version (
+			version INTEGER PRIMARY KEY,
+			applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+		);
+INSERT INTO schema_version VALUES(1,'2026-08-23 11:43:54');
+INSERT INTO schema_version VALUES(2,'2026-08-23 11:43:54');
+INSERT INTO schema_version VALUES(3,'2026-08-23 11:43:54');
+INSERT INTO schema_version VALUES(4,'2026-08-23 11:43:54');
+INSERT INTO schema_version VALUES(5,'2026-08-23 11:43:54');
+INSERT INTO schema_version VALUES(6,'2026-08-23 11:43:54');
+CREATE TABLE resources (
+			kind TEXT NOT NULL,
+			id TEXT NOT NULL,
+			data BLOB NOT NULL,
+			updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+			PRIMARY KEY (kind, id)
+		) WITHOUT ROWID;
+INSERT INTO resources VALUES('organization','acme',X'0a1574656e616e63792e737469676d65722e61692f7631120c4f7267616e697a6174696f6e1a120a0441636d65120461636d651a0461636d65220d0a0b66697874757265206f7267','2026-08-23 11:43:54');
+CREATE TABLE resource_audit (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			kind TEXT NOT NULL,
+			resource_id TEXT NOT NULL,
+			data BLOB NOT NULL,
+			archived_at TEXT NOT NULL DEFAULT (datetime('now')),
+			version_hash TEXT,
+			tag TEXT
+		);
+INSERT INTO resource_audit VALUES(1,'organization','acme',X'0a1574656e616e63792e737469676d65722e61692f7631120c4f7267616e697a6174696f6e1a120a0441636d65120461636d651a0461636d65220d0a0b66697874757265206f7267','2026-08-23 11:43:54','hash-v1','stable');
+PRAGMA writable_schema=ON;
+INSERT INTO sqlite_schema(type,name,tbl_name,rootpage,sql)VALUES('table','search_index','search_index',0,'CREATE VIRTUAL TABLE search_index USING fts5(
+			kind,
+			resource_id UNINDEXED,
+			name,
+			description,
+			tags,
+			org UNINDEXED,
+			visibility UNINDEXED,
+			created_at UNINDEXED,
+			tokenize=''porter unicode61''
+		)');
+CREATE TABLE IF NOT EXISTS 'search_index_data'(id INTEGER PRIMARY KEY, block BLOB);
+INSERT INTO search_index_data VALUES(1,X'010100010200000000');
+INSERT INTO search_index_data VALUES(10,X'000000000101010001010101');
+INSERT INTO search_index_data VALUES(137438953473,X'0000002c043061636d01060102020106666978747572010601030201036f726701060103030402616e010202040a0d0a');
+CREATE TABLE IF NOT EXISTS 'search_index_idx'(segid, term, pgno, PRIMARY KEY(segid, term)) WITHOUT ROWID;
+INSERT INTO search_index_idx VALUES(1,X'',2);
+CREATE TABLE IF NOT EXISTS 'search_index_content'(id INTEGER PRIMARY KEY, c0, c1, c2, c3, c4, c5, c6, c7);
+INSERT INTO search_index_content VALUES(1,'organization','acme','Acme','fixture org','','acme','visibility_org',1755648000);
+CREATE TABLE IF NOT EXISTS 'search_index_docsize'(id INTEGER PRIMARY KEY, sz BLOB);
+INSERT INTO search_index_docsize VALUES(1,X'0100010200000000');
+CREATE TABLE IF NOT EXISTS 'search_index_config'(k PRIMARY KEY, v) WITHOUT ROWID;
+INSERT INTO search_index_config VALUES('version',4);
+CREATE TABLE bootstrap_state (
+			key TEXT PRIMARY KEY,
+			value TEXT NOT NULL,
+			updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+		) WITHOUT ROWID;
+INSERT INTO bootstrap_state VALUES('seedpack_version','1.1.0','2026-08-23 11:43:54');
+CREATE TABLE workflow_execution_events (
+			execution_id TEXT NOT NULL,
+			sequence_number INTEGER NOT NULL,
+			event_type TEXT NOT NULL,
+			task_name TEXT NOT NULL DEFAULT '',
+			data BLOB NOT NULL,
+			created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+			PRIMARY KEY (execution_id, sequence_number)
+		);
+INSERT INTO workflow_execution_events VALUES('wfe_fixture',1,'task_started','step-a',X'0a','2026-08-23T11:43:54.152Z');
+INSERT INTO workflow_execution_events VALUES('wfe_fixture',2,'task_completed','step-a',X'0b','2026-08-23T11:43:54.152Z');
+CREATE TABLE schedule_runs (
+			schedule_id TEXT NOT NULL,
+			org TEXT NOT NULL DEFAULT '',
+			nominal_fire_time TEXT NOT NULL,
+			origin TEXT NOT NULL,
+			outcome TEXT NOT NULL,
+			reason TEXT NOT NULL DEFAULT '',
+			execution_id TEXT NOT NULL DEFAULT '',
+			recorded_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+			completed_at TEXT NOT NULL DEFAULT '',
+			PRIMARY KEY (schedule_id, nominal_fire_time, origin)
+		);
+INSERT INTO schedule_runs VALUES('sch_fixture','acme','2026-08-20T00:00:00Z','cron','completed','','','2026-08-20T00:00:01Z','2026-08-20T00:00:05Z');
+CREATE TABLE signal_dedupe (
+			id TEXT PRIMARY KEY,
+			org TEXT NOT NULL,
+			idempotency_key TEXT NOT NULL,
+			execution_id TEXT NOT NULL,
+			signal_name TEXT NOT NULL,
+			status TEXT NOT NULL DEFAULT 'CLAIMED',
+			created_at TEXT NOT NULL DEFAULT (datetime('now')),
+			delivered_at TEXT,
+			expires_at TEXT NOT NULL
+		);
+INSERT INTO signal_dedupe VALUES('acme:fixture-key','acme','fixture-key','wfe_fixture','resume','DELIVERED','2026-08-23T11:43:54.152777Z','2026-08-23T11:43:54.153385Z','2026-08-24T11:43:54.153385Z');
+CREATE TABLE oauth_grant (
+			identity_account_id    TEXT NOT NULL,
+			resource_id            TEXT NOT NULL,
+			resource_kind          TEXT NOT NULL DEFAULT '',
+			org_id                 TEXT NOT NULL DEFAULT '',
+			access_token_expires_at INTEGER NOT NULL DEFAULT 0,
+			client_id              TEXT NOT NULL DEFAULT '',
+			auth_method            TEXT NOT NULL DEFAULT '',
+			token_endpoint         TEXT NOT NULL DEFAULT '',
+			access_token_env_var   TEXT NOT NULL DEFAULT '',
+			refresh_token_env_var  TEXT NOT NULL DEFAULT '',
+			environment_id         TEXT NOT NULL DEFAULT '',
+			created_at             INTEGER NOT NULL,
+			updated_at             INTEGER NOT NULL,
+			PRIMARY KEY (identity_account_id, resource_id, org_id)
+		);
+INSERT INTO oauth_grant VALUES('ida_fixture','mcp_fixture','mcp_server','acme',0,'client-1','mcp_oauth','https://example.test/token','TOKEN','','env_fixture',1787485434,1787485434);
+CREATE TABLE pending_oauth_state (
+			state               TEXT PRIMARY KEY,
+			code_verifier       TEXT NOT NULL,
+			client_id           TEXT NOT NULL DEFAULT '',
+			client_secret       TEXT NOT NULL DEFAULT '',
+			token_endpoint      TEXT NOT NULL DEFAULT '',
+			mcp_server_id       TEXT NOT NULL,
+			identity_account_id TEXT NOT NULL,
+			target_env_var      TEXT NOT NULL DEFAULT '',
+			auth_method         TEXT NOT NULL DEFAULT '',
+			token_auth_method   TEXT NOT NULL DEFAULT '',
+			redirect_uri        TEXT NOT NULL DEFAULT '',
+			org                 TEXT NOT NULL DEFAULT '',
+			created_at          INTEGER NOT NULL
+		);
+INSERT INTO pending_oauth_state VALUES('state-fixture','enc:v1:sealed','client-1','','https://example.test/token','mcp_fixture','ida_fixture','TOKEN','mcp_oauth','','http://127.0.0.1/cb','acme',1755648000);
+INSERT INTO sqlite_sequence VALUES('resource_audit',1);
+CREATE INDEX idx_resources_kind_id ON resources(kind, id);
+CREATE INDEX idx_audit_resource ON resource_audit(kind, resource_id);
+CREATE INDEX idx_audit_hash ON resource_audit(kind, resource_id, version_hash);
+CREATE INDEX idx_audit_tag ON resource_audit(kind, resource_id, tag, archived_at DESC);
+CREATE INDEX idx_wfee_execution_type
+			ON workflow_execution_events(execution_id, event_type);
+CREATE INDEX idx_wfee_execution_task
+			ON workflow_execution_events(execution_id, task_name);
+CREATE INDEX idx_schedule_runs_recency
+			ON schedule_runs(schedule_id, recorded_at DESC);
+CREATE INDEX idx_signal_dedupe_org ON signal_dedupe(org)
+	;
+CREATE INDEX idx_signal_dedupe_expires ON signal_dedupe(expires_at)
+	;
+PRAGMA writable_schema=OFF;
+COMMIT;

package/src/store/sqlite/__tests__/fts5.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Pins the sqlite driver's engine-specific search half (fts5.ts) against
+ * Go's sqlite_search_query_store_test.go tables — MATCH rendering and
+ * bm25 normalization, case-for-case — recomposed for the DD-009 seam:
+ * the table inputs pass through the search service's engine-neutral
+ * tokenization (goTrimSpace/goFields) so every pinned OUTPUT byte stays
+ * identical to the pre-redraw escapeFTS5Query's. The driver-level
+ * querySearchIndex read coverage moved to the shared contract suite
+ * (../../__tests__/store-contract.ts) with the T01 D-4 extraction — its
+ * semantics are engine-neutral and both drivers must satisfy them.
+ */
+import { describe, expect, it } from "vitest";
+
+import { goFields, goTrimSpace } from "../../../gocompat/trim.js";
+import { normalizeBm25Score, renderFts5MatchExpression } from "../fts5.js";
+
+/** The service's tokenization composed with the driver's rendering —
+ *  the exact pipeline a raw query traverses since the seam redraw. */
+function renderFromRawQuery(query: string): string {
+  return renderFts5MatchExpression(goFields(goTrimSpace(query)));
+}
+
+describe("renderFts5MatchExpression (Go's escaping table, case-for-case)", () => {
+  const cases: Array<[name: string, input: string, expected: string]> = [
+    ["empty query", "", ""],
+    ["single word", "kubernetes", `"kubernetes"*`],
+    ["multiple words", "kubernetes deployment", `"kubernetes" "deployment"`],
+    ["whitespace trimmed", "  hello  ", `"hello"*`],
+    ["AND treated as literal", "foo AND bar", `"foo" "AND" "bar"`],
+    ["OR treated as literal", "foo OR bar", `"foo" "OR" "bar"`],
+    ["NOT treated as literal", "foo NOT bar", `"foo" "NOT" "bar"`],
+    ["NEAR treated as literal", "foo NEAR bar", `"foo" "NEAR" "bar"`],
+    ["colon in single token", "server:skill-creator", `"server:skill-creator"*`],
+    ["colon with simple term", "name:kubernetes", `"name:kubernetes"*`],
+    [
+      "colon in multi-word query",
+      "find server:something here",
+      `"find" "server:something" "here"`,
+    ],
+    ["dash in token", "mcp-server", `"mcp-server"*`],
+    ["leading dash", "-excluded", `"-excluded"*`],
+    ["dash in multi-word", "mcp-server deployment", `"mcp-server" "deployment"`],
+    ["asterisk in token", "kube*", `"kube*"*`],
+    ["parentheses", "NEAR(a b)", `"NEAR(a" "b)"`],
+    ["brackets", "test[0]", `"test[0]"*`],
+    ["caret", "^boost", `"^boost"*`],
+    ["embedded quotes stripped", `foo"bar`, `"foobar"*`],
+    ["only quotes", `"""`, ""],
+    [
+      "mixed specials multi-word",
+      `server:x mcp-server kube*`,
+      `"server:x" "mcp-server" "kube*"`,
+    ],
+  ];
+  for (const [name, input, expected] of cases) {
+    it(name, () => {
+      expect(renderFromRawQuery(input)).toBe(expected);
+    });
+  }
+
+  it("the prefix decision counts terms AFTER sanitization (Go's order)", () => {
+    // Two input terms, one sanitizes away — the survivor is a SINGLE
+    // term and keeps prefix matching.
+    expect(renderFts5MatchExpression(["foo", `"""`])).toBe(`"foo"*`);
+  });
+});
+
+describe("normalizeBm25Score (Go's table)", () => {
+  const cases: Array<[bm25: number, min: number, max: number]> = [
+    [0, 1.0, 1.0],
+    [1.0, 1.0, 1.0],
+    [-1.0, 0.8, 1.0],
+    [-5.0, 0.4, 0.6],
+    [-15.0, 0, 0.1],
+  ];
+  for (const [bm25, min, max] of cases) {
+    it(`bm25 ${bm25} → [${min}, ${max}]`, () => {
+      const score = normalizeBm25Score(bm25);
+      expect(score).toBeGreaterThanOrEqual(min);
+      expect(score).toBeLessThanOrEqual(max);
+    });
+  }
+});