okengine 0.19.0 → 0.19.1

package/site/content/docs/elements/store/sql.mdx

@@ -291,11 +291,12 @@ import { eq } from "drizzle-orm";
 import { db, notes } from "@/schema";
 
 export const get = on(
-  http.get(),
-  flow({
+  http.get({
     in: z.object({ id: z.string() }),
     out: z.object({ id: z.string(), title: z.string() }),
     errors: { NotFound: z.object({ id: z.string() }) },
+  }),
+  flow({
     do: async ({ id }, fx) => {
       const [note] = await fx.store(db).select().from(notes).where(eq(notes.id, id));
       if (!note) return fx.fail("NotFound", { id });
@@ -317,10 +318,11 @@ import { z } from "zod";
 import { db, notes } from "@/schema";
 
 export const create = on(
-  http.post(),
-  flow({
+  http.post({
     in: z.object({ title: z.string().min(1) }),
     out: z.object({ id: z.string(), title: z.string() }),
+  }),
+  flow({
     do: async ({ title }, fx) => {
       const id = fx.id();
       const [row] = await fx.store(db).insert(notes).values({ id, title }).returning();
@@ -344,13 +346,14 @@ import { eq } from "drizzle-orm";
 import { db, notes } from "@/schema";
 
 export const update = on(
-  http.patch(),
-  flow({
+  http.patch({
     in: z.object({
       id: z.string(),
       title: z.string().min(1).optional(),
     }),
     errors: { NotFound: z.object({ id: z.string() }) },
+  }),
+  flow({
     do: async ({ id, title }, fx) => {
       if (title !== undefined) {
         await fx.store(db).update(notes).set({ title }).where(eq(notes.id, id));
@@ -376,9 +379,10 @@ import { z } from "zod";
 import { db, notes } from "@/schema";
 
 export const remove = on(
-  http.delete(),
-  flow({
+  http.delete({
     in: z.object({ id: z.string() }),
+  }),
+  flow({
     do: async ({ id }, fx) => {
       await fx.store(db).delete(notes, id);
       return fx.json.empty();
@@ -422,11 +426,11 @@ prefer them for live feeds. Offset is fine for admin tables.
 Default is insert-once. Pass `{ onExisting: "update" }` to overwrite a match:
 
 ```typescript title="src/flows/notes/ensure.ts"
-import { flow } from "okengine";
+import { call } from "okengine";
 import { z } from "zod";
 import { db, notes } from "@/schema";
 
-export const ensureWelcome = flow("notes.ensureWelcome", {
+export const ensureWelcome = call("notes.ensureWelcome", {
   in: z.object({ title: z.string() }),
   do: async ({ title }, fx) => {
     const result = await fx.store(db).upsert(

package/site/content/docs/elements/vault/config.mdx

@@ -48,9 +48,12 @@ import { member } from "@/core/gate";
 import { publicAppUrl, noteCreatedMail } from "@/core";
 
 export const create = on(
-  http.post().gate(member),
+  http
+    .post({
+      in: z.object({ email: z.string().email() }),
+    })
+    .gate(member),
   flow({
-    in: z.object({ email: z.string().email() }),
     do: async ({ email }, fx) => {
       const origin = await fx.vault.get(publicAppUrl);
       await fx.send(noteCreatedMail, {

package/site/content/docs/elements/vault/rotation.mdx

@@ -93,10 +93,13 @@ import { gate } from "okengine";
 const operator = gate.policy("operator", ({ operator: op }) => !!op);
 
 export const rotateStripe = on(
-  http.post().gate(operator),
+  http
+    .post({
+      in: z.object({ value: z.string().min(1) }),
+    })
+    .gate(operator),
   flow({
     plane: "operator",
-    in: z.object({ value: z.string().min(1) }),
     effects: { secrets: ["STRIPE_KEY"] },
     do: async ({ value }, fx) => {
       const result = await fx.vault.rotate("STRIPE_KEY", value);

package/site/content/docs/elements/vault/secrets.mdx

@@ -51,9 +51,12 @@ import { member } from "@/core/gate";
 import { stripeKey } from "@/core/vault";
 
 export const charge = on(
-  http.post().gate(member),
+  http
+    .post({
+      in: z.object({ amount: z.number().int().positive() }),
+    })
+    .gate(member),
   flow({
-    in: z.object({ amount: z.number().int().positive() }),
     do: async ({ amount }, fx) => {
       const key = await fx.vault.get(stripeKey);
       const stripe = new Stripe(key.reveal());

package/site/content/docs/index.mdx

@@ -23,29 +23,14 @@ Master the mental model before exploring features:
 
 <Cards>
   <Card
-    title="The Problem"
-    description="Three unrelated features that hit the exact same wall, and the timeline that shows why."
-    href="/docs/understand/the-problem"
-  />
-  <Card
-    title="The Model"
-    description="The one rule that removes the disagreement between systems — stated plainly, in two parts."
-    href="/docs/understand/the-model"
-  />
-  <Card
-    title="The Vocabulary"
-    description="The eight things the door recognizes — what each one replaces, and why nothing else made the cut."
-    href="/docs/understand/the-vocabulary"
-  />
-  <Card
-    title="The Anatomy"
-    description="The five pieces behind on(trigger, flow) — on, trigger, flow, do, and fx — explained one at a time."
-    href="/docs/understand/the-anatomy"
+    title="The Architecture"
+    description="Why backends drift apart, the one rule that stops it, and the five pieces behind every Flow."
+    href="/docs/understand/the-architecture"
   />
   <Card
     title="Try It"
     description="From an empty folder to a Flow running in the Console — one sitting, minimal detour."
-    href="/docs/ai/try-it"
+    href="/docs/understand/try-it"
   />
 </Cards>
 

package/site/content/docs/reference/cli.mdx

@@ -211,7 +211,7 @@ oke db search-backfill notes --batch 500
 - [Configuration](/docs/reference/configuration) — `oke.config.ts` drivers and ports
 - [Environment Variables](/docs/reference/environment-variables) — what Compose writes
 - [Security](/docs/reference/security) — Host / Origin / `allowedHosts`
-- [The Model](/docs/understand/the-model) — one contract; `oke doctor --diff` reviews it
+- [The Architecture](/docs/understand/the-architecture) — one contract; `oke doctor --diff` reviews it
 - [Vault](/docs/elements/vault) — `oke vault` rotate / unseal
 
 ## Next

package/site/content/docs/reference/fx.mdx

@@ -28,9 +28,10 @@ import { z } from "zod";
 import { db, notes } from "@/schema";
 
 export const create = on(
-  http.post(),
-  flow({
+  http.post({
     in: z.object({ title: z.string().min(1) }),
+  }),
+  flow({
     do: async ({ title }, fx) => {
       const id = fx.id();
       await fx.store(db).insert(notes).values({ id, title });

package/site/content/docs/reference/security.mdx

@@ -172,7 +172,7 @@ the family.
 
 - [CLI](/docs/reference/cli) — `oke dev`, `oke console claim-code`
 - [Gate](/docs/elements/gate) — policies, API keys, tenancy
-- [The Model](/docs/understand/the-model) — one shape, one door, fixed vocabulary
+- [The Architecture](/docs/understand/the-architecture) — one shape, one door, fixed vocabulary
 - [Errors](/docs/reference/errors) — `CrossPlaneError`, `SessionError`, `AttenuationError`
 - [Environment Variables](/docs/reference/environment-variables) — `OKE_CONSOLE_SECRET`
 
@@ -192,6 +192,6 @@ the family.
   <Card
     title="The Model"
     description="One shape for every trigger, one door for every effect."
-    href="/docs/understand/the-model"
+    href="/docs/understand/the-architecture"
   />
 </Cards>

package/site/content/docs/understand/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Understand",
   "icon": "Compass",
-  "pages": ["the-problem", "the-model", "the-vocabulary", "the-anatomy"]
+  "pages": ["the-architecture", "try-it"]
 }

package/site/content/docs/understand/the-architecture.mdx

@@ -0,0 +1,264 @@
+---
+title: "The Architecture"
+description: "Why backends drift apart, the one rule that stops it, and the five pieces behind every Flow."
+icon: "Compass"
+---
+
+Four lines ship the signup flow. Eight months later it is six files that disagree about retries, audits, and who is allowed to do what.
+
+This page shows that drift, the one rule that stops it, and the exact anatomy behind every Flow — in one sitting.
+
+<Callout title="The Law">
+  Every backend behavior is a Flow: `on(Trigger) → Effects`. One species; triggers are typed values.
+  All world access goes through `fx`.
+</Callout>
+
+## The problem: three features, same wall
+
+**A signup flow.** A user registers. Send them a welcome email:
+
+```typescript
+app.post("/signup", async (req, res) => {
+  const user = await db.users.create(req.body);
+  await sendMail(user.email, "Welcome!", welcomeTemplate(user));
+  res.json(user);
+});
+```
+
+It works. It ships. Then a traffic spike, a silent failure, a compliance question, and a double-submit turn those four lines into six files — endpoint, queue, worker, Redis connection, mail client, audit table — that never agreed with each other about anything.
+
+**A payment webhook.** A provider confirms a charge. Mark the order paid. Simple — until the provider retries the same webhook twice during a network hiccup, and "mark the order paid" needs to somehow know it already ran.
+
+**A nightly report.** Summarize yesterday's activity and email it to managers. Trivial — until a manager's access gets revoked at 11:58pm and the report that runs at midnight has no idea the permission it checked when the feature was built isn't the permission that holds right now.
+
+Three teams. Three domains. Nobody on any of them talked to the other two. And all three land on the identical fork: **something has to happen later, exactly once, provably — and nothing in the original four lines said what "provably" would end up costing.**
+
+### Follow one all the way through
+
+Two weeks later, a launch drives a traffic spike, the mail provider starts returning `429`, and signups start failing because an unrelated email is slow. You move the send off the request path:
+
+```typescript
+app.post("/signup", async (req, res) => {
+  const user = await db.users.create(req.body);
+  emailQueue.add("welcome", { userId: user.id });
+  res.json(user);
+});
+```
+
+The endpoint is fast again. It's also no longer one system — it's an endpoint, a queue, a worker, and a Redis connection nobody else on the team knew existed until a missing `REDIS_URL` broke staging.
+
+<SixSystemsDrift />
+
+From here the same pattern repeats on a longer clock. A support ticket reveals a job failed silently — nobody had configured retries, so you add them, and now a specific number (3? 5? with what backoff?) lives in a file that nobody will remember the reasoning for in six weeks. Compliance asks for proof of every email sent — you add a table written to from inside the worker, and now that worker has two jobs instead of one, quietly capable of disagreeing with itself if the second write fails. Someone double-clicks submit — two jobs enqueue, two emails send, and idempotency becomes a fact that has to live in two systems that were never introduced to each other.
+
+None of these were mistakes. Each one was the correct call, made by a competent engineer, in direct response to something that actually happened.
+
+### What's actually going on
+
+Look at what the six resulting files have in common: none of them agree with each other about the same three things. What counts as "done." What happens on failure. Who's allowed to do this at all.
+
+That's the real cost — not the number of tools, but what sits between them:
+
+- **Failure means something different in each one.** A queue retry, an HTTP 500, and a rejected promise from a mail SDK are three unrelated shapes that all happen to mean "this didn't work."
+- **Permission has no fixed address.** It lives wherever whoever wrote that file remembered to put it — which means a reviewer can't point at one place and ask "is this checked?"
+- **Two systems both think they own the same fact.** The database says an order is paid. The already-running webhook handler doesn't know that yet. Nothing keeps them honest with each other in the gap.
+- **Nobody can see the whole thing at once.** There is no file, diagram, or dashboard where "the signup flow" exists as one object — only as the sum of files that happen to call each other.
+
+What would have to be true on day one for month eight to never happen?
+
+## The model: one rule, in two parts
+
+Every seam above came from the same root cause: each system involved had its own idea of when it should run and what it was allowed to touch, and nothing forced those ideas to agree with each other.
+
+OKE removes the disagreement by removing the choice. It's one rule, in two parts.
+
+**First: every trigger reduces to the same shape.** An HTTP request, a scheduled tick, a queue message, a database change — whatever wakes the code up, what follows has one identical anatomy: `on(Trigger) → Effects`. Not four systems that happen to look similar. One system, with four ways to wake it up.
+
+**Second: every effect passes through one door.** Nothing is allowed to touch a database, send an email, check a permission, or read the clock on its own — all of it goes through a single surface. Not because that's tidier. Because it's the only way retries, auditing, idempotency, and permission checks stop being infrastructure every team reinvents at the exact moment they get burned by not having it.
+
+<FlowShape />
+
+That's the whole model. Not a bigger toolbox — a smaller number of things that are allowed to happen at all.
+
+### What OKE is — and isn't
+
+OKE is a backend programming model: behavior is expressed as Flows, effects are captured through `fx`, and the compiler turns that model into a versioned Manifest that powers the rest of the backend.
+
+| OKE is not …                                  | OKE is …                                                                |
+| --------------------------------------------- | ----------------------------------------------------------------------- |
+| Another queue, ORM, or mailer to wire up      | One Flow species every trigger wakes up                                 |
+| A toolbox of forty clients with forty configs | Eight elements with irreducible physics — nothing else gets added       |
+| A platform you deploy into                    | TypeScript you host; Client, Console, and MCP derive from your Manifest |
+
+One shape for every trigger, one door for every effect, a fixed vocabulary for what the door allows — that's what this project built. It's called **OKE**.
+
+<sub>
+  *OKE isn't an acronym for anything in the code. It comes from Omq Khafi — the organization this
+  engine grew out of — with "Engine" appended: **O**mq **K**hafi **E**ngine.*
+</sub>
+
+## The vocabulary: eight elements, closed set
+
+The door from the last section isn't open-ended — it recognizes a fixed set of things it's willing to do. Each one made the cut because it has _irreducible physics_: behavior that breaks if you tried to fake it using one of the others.
+
+<Features />
+
+| Element     | What it is           | What it replaces                                                        |
+| ----------- | -------------------- | ----------------------------------------------------------------------- |
+| **Flow**    | Execution & behavior | endpoint, handler, consumer, job, workflow, webhook                     |
+| **Signal**  | Data in motion       | queue, pub/sub, stream, websocket, SSE, event bus                       |
+| **Store**   | Data at rest         | relational database, cache, key-value store, file storage, search index |
+| **Clock**   | Time & schedules     | cron, every, delay, durable sleep, timeout                              |
+| **Gate**    | Permission to act    | auth, session, tenancy, RBAC, scope, rate limit, public                 |
+| **Vault**   | Protected knowledge  | secrets, encryption keys, rotation, environment variables               |
+| **Channel** | Reaching a human     | transactional email, SMS, push notifications, receipts                  |
+| **AI**      | Machine intelligence | model calls, structured prompts, embeddings, agents, RAG                |
+
+Read the right column as the honest answer to "what would I have reached for before this?" Every item in it is a separate tool with its own configuration, its own failure modes, and its own place to go wrong.
+
+The left column is the same ground, covered by something with one shared door and one shared set of guarantees. Where that distinction is real, it gets a name. Where it isn't, it doesn't — which is why the list stops at eight instead of growing indefinitely.
+
+## The anatomy: five pieces behind every Flow
+
+Everything a Flow does reduces to one line:
+
+```typescript
+on(
+  trigger,
+  flow({
+    do: (input, fx) => {
+      /* ... */
+    },
+  }),
+);
+```
+
+If that line doesn't mean much yet, that's what this section is for. Five pieces make it up. We'll take them one at a time, then put them together using a complete signup example.
+
+### `on(...)` — wires a trigger to a flow
+
+`on` does exactly one thing: it connects "something that can happen" to "code that should run when it does." Nothing executes until this connection exists.
+
+```typescript
+on(someTrigger, someFlow);
+```
+
+That's the whole job. The interesting parts are what goes in each slot.
+
+### A trigger — the answer to "when"
+
+The first argument to `on` is the trigger: whatever wakes the code up. A trigger doesn't run any of your logic — it only answers one question: _when should this happen?_
+
+```typescript
+http.post(); // path from the file tree — e.g. src/flows/users/signup.ts → POST /users/signup
+```
+
+There are five kinds of trigger in total — the table at the end of this page lists them. For now: the trigger is the _when_, and it's the only thing that changes between an endpoint, a scheduled job, and everything else.
+
+<FlowTriggers />
+
+### `flow(...)` — the actual unit of work
+
+The second argument to `on` is a Flow — declared with the `flow()` function. It answers _what_: what work is this, and what does it promise about its inputs and outputs?
+
+```typescript
+flow({
+  do: /* the actual code — next */,
+});
+```
+
+Omit the name on tree files — the compiler stamps `unit.export` (e.g. `users.signup`).
+Pass `flow("users.signup", { … })` only for control: barrels, stable names across
+moves, or call-only Flows you `fx.call` by name.
+
+### `do` — the code that actually runs
+
+`do` is a function you write. It answers _how_. It receives two things: `input` (your data) and `fx` (next). Everything your Flow actually does lives here.
+
+```typescript
+do: async (input, fx) => {
+  return { ok: true };
+};
+```
+
+### `fx` — the only door to the outside world
+
+`fx` is the second argument to `do`, and it's the piece the other four exist to protect. The rule is simple and absolute: **your Flow is not allowed to read a database, send an email, check a clock, or touch anything outside itself except through `fx`.**
+
+```typescript
+do: async (input, fx) => {
+  const user = await fx.store(db).insert(users).values(input); // the database, through fx
+  await fx.send(welcomeEmail, { to: user.email }); // another system, through fx
+  return user;
+};
+```
+
+This one rule is what made the month-8 drift above avoidable: if `fx` is the only door, retries, auditing, and idempotency stop being separate systems teams build by hand, and become properties of the one boundary everything already passes through.
+
+### Putting the five pieces together
+
+Here is the complete signup flow, with every piece labeled where it sits:
+
+```typescript title="src/flows/users/signup.ts"
+export const signup = on(
+  http.post(), // ← trigger: when (stamped POST /users/signup)
+  flow({
+    // ↑ flow: what (stamped users.signup)
+    do: async (input, fx) => {
+      // ← do: how
+      const user = await fx.store(db).insert(users).values(input); // ← fx: the only way out
+      await fx.send(welcomeEmail, { to: user.email, data: { name: user.name } });
+      return user;
+    },
+  }),
+);
+```
+
+<Callout title="Call-only flows">
+  A `flow(...)` declared without `on(...)` around it is internal — nothing outside your code can
+  start it. Other flows invoke it directly with `fx.call(flowRef, input)`.
+</Callout>
+
+### Checking it against the timeline
+
+Nothing about the code above looks more complicated than the four lines that started the drift — because it isn't. The difference only shows up when the same pressure from that timeline hits it. Every fork was really the same question — _is this safe to retry, safe to audit, safe to run twice?_ — and now it has one home:
+
+| Then: a new system per incident                                      | Now: one door, fixed answer                                             |
+| -------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| **Week 2 spike** — hand-build a queue + worker to run the send later | Running later, safely, is asked of the trigger or the effect itself     |
+| **Month 2 silence** — a retry count in a worker nobody remembers     | Retries are a property of the `fx` boundary every effect passes through |
+| **Month 4 audit** — a `sent_emails` table written by hand from a job | What was sent is already known — nothing sends outside `fx`             |
+| **Month 6 double-submit** — dedup split across a queue and a DB      | One call through one door — no second path for a duplicate              |
+
+None of that required new code beyond what's above. It required the four lines to already be the kind of thing where those questions have a fixed answer, instead of a new one invented per team, per incident.
+
+### Five kinds of trigger
+
+`flow`, `do`, and `fx` never change shape. Only the trigger does — and there are exactly five kinds, one per element that can independently wake a Flow up:
+
+| Trigger                                             | Element | Starts When                      |
+| --------------------------------------------------- | ------- | -------------------------------- |
+| `http.post()` (path from file tree)                 | Flow    | A request arrives                |
+| `clock("name", { every: "10m" })`                   | Clock   | A time interval elapses          |
+| `signal.once("name", {…})` / `.broadcast` / `.live` | Signal  | Another flow announces something |
+| `db.table(users).changed("email")`                  | Store   | A database row changes           |
+| `mcp.tool("name")`                                  | AI      | An AI agent calls it             |
+
+The Elements section walks through each element in depth — this is just enough to recognize them when you see them.
+
+## Where this goes next
+
+You now hold the whole model: the drift, the rule, the eight elements, the five-piece anatomy. Don't read more — run it. From an empty folder to this exact signup Flow answering a real request, in one sitting:
+
+<Cards>
+  <Card
+    title="Try It"
+    description="From an empty folder to a Flow running in the Console — one sitting, minimal detour."
+    href="/docs/understand/try-it"
+  />
+  <Card
+    title="Elements"
+    description="When you're back: Flow, Signal, Store, Clock, Gate, Vault, Channel, AI — each in depth."
+    href="/docs/elements"
+  />
+</Cards>

package/src/bench/REPORT.md

@@ -180,13 +180,16 @@ Artifact: `G15-postgres-degradation-…json` (+ extra stress-level artifacts)
 ## G17 — Hybrid SQL search (BM25 / LSH / fusion)
 
 **Command:** `OKE_BENCH=1 OKE_TEST_POSTGRES=1 DATABASE_URL=$DATABASE_URL bun test ./src/bench/g17-hybrid-search.bench.ts --timeout 3600000`  
-**Date:** 2026-09-10 · **Engine:** Bun 1.4.2 · **Postgres:** 16.15 (dedicated live instance, not PGlite)  
-**Hardware:** Apple M4, 24 GB · trend-analysis only (not SLA; macOS ≠ Linux prod)  
-**Artifact:** `g17-hybrid-search-1789039639500.json`
+**Hardware:** Apple M4, 24 GB · trend-analysis only (not SLA; macOS ≠ Linux prod)
 
-Synthetic 32-dim embeddings (deterministic hash bag — not a production model). Modes: text-only (BM25/GIN), vector-only (LSH buckets + cosine), hybrid (RRF k=60). Recall = precision@10 of the LSH/hybrid path vs **exact brute-force cosine** on the same in-memory vectors.
+Synthetic 32-dim embeddings (deterministic hash bag — not a production model). Modes: text-only (BM25/GIN), vector-only (LSH + cosine), hybrid (RRF k=60). Recall = precision@10 of the LSH/hybrid path vs **exact brute-force cosine** on the same in-memory vectors.
 
-### Latency (p50 / p99 ms)
+### Before — v0.19.0 (2026-09-10)
+
+**Postgres:** 16.15 · **Artifact:** `g17-hybrid-search-1789039639500.json`  
+Query path: K=64 bucket equality plus Hamming-1 (`= ANY(65 buckets)`), oversample ≤50.
+
+#### Latency (p50 / p99 ms)
 
 | N    | text p50 | text p99 | vector p50 | vector p99 | hybrid p50 | hybrid p99 |
 | ---- | -------- | -------- | ---------- | ---------- | ---------- | ---------- |
@@ -195,7 +198,7 @@ Synthetic 32-dim embeddings (deterministic hash bag — not a production model).
 | 100k | 39.86    | 59.73    | 57.05      | 126.14     | 52.08      | 288.09     |
 | 1M   | 877.57   | 2243.68  | 1165.5     | 3370.19    | 649.14     | 1861.91    |
 
-### Recall — LSH approx vs exact cosine (precision@10)
+#### Recall — LSH approx vs exact cosine (precision@10)
 
 | N    | vector P@10 | hybrid P@10 | exact cosine p50 (ms) | approx p50 (ms) |
 | ---- | ----------- | ----------- | --------------------- | --------------- |
@@ -204,22 +207,50 @@ Synthetic 32-dim embeddings (deterministic hash bag — not a production model).
 | 100k | **0.000**   | **0.000**   | ~36                   | ~54             |
 | 1M   | 0.008       | **0.000**   | ~445                  | ~600            |
 
-**Honest verdict:** on this corpus the random-hyperplane LSH path (K=64, Hamming-1 neighbors, candidate oversample ≤50) does **not** recover the exact cosine top-10. Treat built-in LSH as a cheap candidate generator for hybrid fusion — **not** a drop-in for HNSW/pgvector recall. Prefer BM25-only or an external `store.index` (`pgvector` / Meilisearch) when semantic recall matters.
+**Root cause (not an LSH-vs-HNSW tradeoff):** write-time and query-time buckets were byte-identical; `neighborBuckets` did emit 65 probes; `= ANY(?::bigint[])` matched stored rows. Hamming-1 at K=64 cannot see true neighbors. On this generator, same-topic docs sit at cosine ≈0.96 / Hamming ~5; a topic-string query vs those docs is cosine ≈0.82 / expected Hamming ~12. P(Hamming ≤ 1) at K=64 is ~10⁻⁵. A 40-row hand case recovered **0/10** exact neighbors via Hamming-1 and **10/10** via Hamming-rank + cosine. The hash-bag embedding is clustered (8 topics, near-duplicate bodies) — that makes exact top-10 at large N a lottery among the cluster, but it does **not** explain the zero collapse at N=40.
+
+The 2026-09-10 EXPLAIN (Seq Scan, `tsv @@ q OR lsh = ANY(…)`) was a separate planner finding on that query shape.
+
+### After — Hamming-rank candidate path (2026-09-11)
+
+**Date:** 2026-09-11 · **Engine:** Bun 1.4.2 · **Postgres:** 16 (dedicated live instance, not PGlite)  
+**Artifact:** `g17-hybrid-search-1789135622349.json`  
+Fix: UNION of GIN lexical `LIMIT` and SimHash k-NN (`ORDER BY bit_count((lsh # query)::bit(64)) LIMIT oversample`). Same K=64, same oversample formula `max(limit×5, 50)` capped at 500. Not a K/oversample paper-over.
+
+#### Latency (p50 / p99 ms)
+
+| N    | text p50 | text p99 | vector p50 | vector p99 | hybrid p50 | hybrid p99 |
+| ---- | -------- | -------- | ---------- | ---------- | ---------- | ---------- |
+| 1k   | 0.88     | 2.8      | 1.27       | 2.37       | 1.28       | 1.54       |
+| 10k  | 4.5      | 17.21    | 9.36       | 29.03      | 6.88       | 32.48      |
+| 100k | 21.03    | 27.61    | 30.61      | 49.8       | 34.08      | 89.99      |
+| 1M   | 305.61   | 377.7    | 388.98     | 548.36     | 391.96     | 469.76     |
+
+#### Recall — LSH approx vs exact cosine (precision@10)
+
+| N    | vector P@10 | hybrid P@10 | exact cosine p50 (ms) | approx p50 (ms) |
+| ---- | ----------- | ----------- | --------------------- | --------------- |
+| 1k   | 0.167       | 0.117       | 0.6 / 0.41            | 1.25 / 1.3      |
+| 10k  | 0.100       | 0.017       | ~6                    | ~9              |
+| 100k | 0.017       | 0.008       | ~45                   | ~32             |
+| 1M   | 0.017       | 0.000       | ~535                  | ~363            |
+
+**Honest verdict after the fix:** the near-total collapse at 10k/100k is gone on the vector path (smooth 0.17 → 0.10 → 0.017). Remaining low precision@10 vs exact cosine is the real K=64 SimHash + 50-candidate oversample tradeoff on this near-duplicate hash-bag corpus — not a hashing mismatch. Still **not** a drop-in for HNSW/pgvector. Prefer BM25-only or an external `store.index` (`pgvector` / Meilisearch) when semantic recall matters.
 
-### EXPLAIN (ANALYZE, BUFFERS) at N=100k
+### EXPLAIN (ANALYZE, BUFFERS) at N=100k (after)
 
-Postgres 16 chose a **Seq Scan** with a Filter on `__oke_tsv @@ plainto_tsquery(…) OR __oke_lsh_body = ANY(…)` (Limit 50; execution ~0.27 ms; shared hit=27). GIN + LSH B-tree indexes exist; the planner did **not** emit BitmapOr on this hardware/stats for the measured query. Do not claim BitmapOr from design alone — re-check `EXPLAIN` on production data volumes and `ANALYZE`d tables.
+UNION Append (~14.7 ms): **Bitmap Index Scan** on the GIN tsvector (50 lexical rows) plus **Parallel Seq Scan** + top-N heapsort on `bit_count((lsh # query)::bit(64))` (50 SimHash-nearest). Hamming-rank cannot use the LSH B-tree (equality index). Do not claim BitmapOr from design alone — re-check `EXPLAIN` on production data volumes and `ANALYZE`d tables.
 
 ### Backfill kill / resume (50k pre-populated rows)
 
-| Metric                             | Value  |
-| ---------------------------------- | ------ |
-| Kill after embeds                  | 2,000  |
-| Embeds at kill                     | 2,000  |
-| Kill wall                          | 726 ms |
-| Resume wall (re-run to completion) | 29.3 s |
-| Final embedded rows                | 50,000 |
+| Metric                             | Before (2026-09-10) | After (2026-09-11) |
+| ---------------------------------- | ------------------- | ------------------ |
+| Kill after embeds                  | 2,000               | 2,000              |
+| Embeds at kill                     | 2,000               | 2,000              |
+| Kill wall                          | 726 ms              | 732 ms             |
+| Resume wall (re-run to completion) | 29.3 s              | 28.3 s             |
+| Final embedded rows                | 50,000              | 50,000             |
 
 Re-running `oke db search-backfill` after interrupt completed idempotently (safe re-entry; DF/stats rebuilt).
 
-**Issues recorded in artifact:** eight low-recall notes (all sizes). No product fix applied mid-bench — numbers stand as measured.
+**Issues recorded in after artifact:** eight low-recall notes (P@10 still < 0.3 at every size — honest SimHash-vs-exact remainder, not the Hamming-1 zero collapse).

package/src/bench/g17-hybrid-search.bench.ts

@@ -31,7 +31,6 @@ import {
   deserializePlanes,
   lshBucket,
   lshBucketToSql,
-  neighborBuckets,
 } from "../elements/store/search-lsh.ts";
 import { runSqlSearch, type SearchColumnMeta } from "../elements/store/search-runtime.ts";
 import { resolveLivePg } from "./lib/infra.ts";
@@ -404,24 +403,25 @@ describe.skipIf(!ENABLED)("G17 hybrid search", () => {
           const kPlanes = Number(prow["k"] ?? LSH_DEFAULT_K);
           const planes = deserializePlanes(Buffer.from(prow["planes"] as Buffer), kPlanes);
           const bucket = lshBucket(qVec, planes);
-          const buckets = neighborBuckets(bucket, kPlanes).map((b) => lshBucketToSql(b));
-          const explainSql = `EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
-            SELECT id FROM ${TABLE}
-            WHERE ${OKE_TSV_COL} @@ plainto_tsquery('english', $1)
-               OR ${lshColumn("body")} = ANY($2::bigint[])
-            LIMIT 50`;
+          const bucketSql = lshBucketToSql(bucket);
           // Bun.SQL uses ? placeholders — fall back to interpolated literals for EXPLAIN only.
           const safeQ = TOPICS[0]!.replaceAll("'", "''");
-          const bucketList = buckets.join(",");
           const explainRows = await conn.query(
             `EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
-             SELECT id FROM ${TABLE}
-             WHERE ${OKE_TSV_COL} @@ plainto_tsquery('english', '${safeQ}')
-                OR ${lshColumn("body")} = ANY(ARRAY[${bucketList}]::bigint[])
-             LIMIT 50`,
+             (
+               SELECT id FROM ${TABLE}
+               WHERE ${OKE_TSV_COL} @@ plainto_tsquery('english', '${safeQ}')
+               LIMIT 50
+             )
+             UNION
+             (
+               SELECT id FROM ${TABLE}
+               WHERE ${lshColumn("body")} IS NOT NULL
+               ORDER BY bit_count((${lshColumn("body")} # ${bucketSql}::bigint)::bit(64)) ASC NULLS LAST
+               LIMIT 50
+             )`,
           );
           explainText = explainRows.map((r) => String(Object.values(r)[0] ?? "")).join("\n");
-          void explainSql;
           console.log("G17 EXPLAIN (ANALYZE, BUFFERS):\n" + explainText);
           if (!/Bitmap|Index|Seq Scan|BitmapOr|Bitmap Heap/i.test(explainText)) {
             issues.push("EXPLAIN text lacked recognizable Postgres plan nodes");