@panaversity/ksor 0.0.18 → 0.0.19

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @panaversity/ksor
 
+## 0.0.19
+
+### Patch Changes
+
+- aa4bdce: Record why the vector index is unused, and what fixing it would cost
+
+  Diagnosis only — no serving behaviour changes. Answers are unaffected, and were
+  already correct: the query plans a sequential scan, and a sequential scan is
+  EXACT. What grows with the corpus is the work, not the error.
+
+  The cause recorded until now — a window function, then joins and predicates
+  Postgres cannot estimate — was incomplete. Testing each clause on its own shows
+  a cost mispricing underneath: a full sequential pass over 20,000 chunks,
+  including 20,000 1536-dimension distance computations, is priced at 1904 for
+  work that takes ~130 ms, while the HNSW scan's startup cost alone is 2137.
+
+  A restructured arm reaches 36 ms against 648 ms — but only with `ef_search` at
+  pgvector's default, which is the setting where the index missed the true nearest
+  neighbour for 1 query in 100 on a bed with real cluster structure, dropping the
+  top-1 similarity by 0.99. Against this record's ~0.01 abstention separation,
+  that flips an abstention: the corpus holds the answer and the door says it does
+  not. The speed and the approximation cannot be separated, so taking them is an
+  owner decision rather than a tuning change.
+
+  Both the current plan and the fix path are now pinned by tests, so neither can
+  drift unnoticed.
+
+- b9f3d00: A citation pin no longer outlives a restriction
+
+  A snapshot token pins a generation so a citation keeps resolving to the same
+  bytes. It was also deciding the _audience_ question — evaluating `visibility` on
+  the pinned row — so a document restricted after the token was issued kept reading
+  in full for the token's life, to a caller the record had just closed it to.
+
+  Three routes refused it and one served it, on the same surface, in the same
+  second: `outline` omitted it, `search` filtered it, an unpinned `read` refused it,
+  and `read` with a pre-flip token returned the whole document.
+
+  The generation pointers are why the obvious guard missed it. A flip sets
+  `rollback_generation` to the generation just superseded, so a pre-flip pin is
+  exactly the rollback pointer — servable by design, and the check that narrows a
+  pin to {active, rollback} passed it.
+
+  **Governance is now read from the record as it stands.** A pin still decides
+  which generation's content is served; it no longer decides whether the caller may
+  have it. A document the record no longer contains cannot be resurrected by one
+  either. Unpinned reads are unaffected — with nothing pinned, the two generations
+  are the same one and the check is an identity.
+
+  The cost is deliberate: a citation can stop resolving within the token's 30
+  minutes when the record restricts what it points at. That is what "the record
+  changed" should look like. The alternative is a window in which a withdrawal is
+  not a withdrawal.
+
 ## 0.0.18
 
 ### Patch Changes

package/dist/cli.mjs

@@ -15,7 +15,7 @@ import { bodyLimit } from "hono/body-limit";
 import { execFileSync, spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
 import { readFile, readdir, stat } from "node:fs/promises";
-//#region ../content-gateway/dist/main-Deg5kd9y.mjs
+//#region ../content-gateway/dist/main-DDeyGVjK.mjs
 /**
 * A connection could not be ESTABLISHED in time — retryable.
 *
@@ -2053,6 +2053,28 @@ g AS (
         (SELECT active_generation FROM corpora
           WHERE tenant_id = $1 AND corpus_id = $2)
     ) AS gen
+),
+-- The generation the record is on RIGHT NOW, which decides governance even when
+-- content is served from a pinned one.
+--
+-- A snapshot pin exists so a citation keeps resolving to the same bytes. It used
+-- to decide the audience question too, by evaluating visibility on the pinned
+-- row — so a document restricted after the token was issued kept reading in full
+-- for the token's life, while outline, search and an unpinned read all
+-- refused it in the same second. servableGenerations could not catch it: a
+-- flip sets rollback_generation to the generation just superseded, so a pre-flip
+-- pin IS the rollback pointer and is servable by design (issue #87).
+--
+-- Pins yield. A citation may stop resolving within the token's life, which is
+-- what "the record changed" should look like — the alternative is a window in
+-- which a withdrawal is not a withdrawal, and decision 19 says a surface that
+-- refuses must refuse everywhere, which includes its own fourth route.
+--
+-- When nothing is pinned this is the SAME generation as g, so the join is an
+-- identity and no unpinned read changes behaviour.
+live AS (
+    SELECT active_generation AS gen FROM corpora
+     WHERE tenant_id = $1 AND corpus_id = $2
 )`;
 /** Candidates by LEAF slug ($4), each with its full root path (for suffix disambiguation). */
 const NODE_BY_SLUG_SQL = `
@@ -2082,7 +2104,12 @@ SELECT n.node_id, n.slug, n.title, n.stable_id, n.path, n.generation, n.permalin
 FROM tree n
 JOIN content_nodes self ON self.node_id = n.node_id AND self.tenant_id = $1
                        AND self.generation = n.generation
-WHERE n.slug = $4 AND ${DENY$1} AND ${audienceAllowed$1("self")}
+-- INNER join, so a document the record no longer contains cannot be
+-- resurrected by a pin either: no live row, no read.
+JOIN live ON TRUE
+JOIN content_nodes now ON now.tenant_id = $1 AND now.generation = live.gen
+                      AND now.stable_id = self.stable_id
+WHERE n.slug = $4 AND ${DENY$1} AND ${audienceAllowed$1("now")}
 ORDER BY n.path`;
 const ALIAS_SQL = `
 WITH ${GEN}
@@ -2099,8 +2126,11 @@ const NODE_BY_STABLE_ID_SQL = `
 WITH RECURSIVE ${GEN}, ${DENIED_CTE$1}
 SELECT n.node_id, n.slug, n.title, n.stable_id, n.stable_id::text AS path, n.generation, n.permalink
 FROM content_nodes n JOIN g ON n.generation = g.gen
+JOIN live ON TRUE
+JOIN content_nodes now ON now.tenant_id = $1 AND now.generation = live.gen
+                      AND now.stable_id = n.stable_id
 WHERE n.tenant_id = $1 AND n.stable_id = $4 AND n.status = 'published' AND ${DENY$1}
-  AND ${AUDIENCE_ALLOWED$1}`;
+  AND ${audienceAllowed$1("now")}`;
 const DOCUMENT_CHUNKS_SQL = `
 WITH ${GEN}
 SELECT c.ordinal, COALESCE(c.heading_path_text, ''), c.content

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "description": "Knowledge System of Record — compile governed markdown into a static site for people and an MCP server for AI agents, with citations and measured abstention.",
   "keywords": [
     "abstention",