@panaversity/ksor 0.0.57 → 0.0.59

package/dist/{gateway-api-C0vL3oOK-D24n786A.mjs → gateway-api-CEsb-e8z-Ch6oMaq2.mjs}

@@ -6,7 +6,7 @@ import { z, z as z$1 } from "zod";
 import path, { join } from "node:path";
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import pg from "pg";
-//#region ../content-gateway/dist/gateway-api-C0vL3oOK.mjs
+//#region ../content-gateway/dist/gateway-api-CEsb-e8z.mjs
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
 /**
@@ -9238,6 +9238,15 @@ var OpenAiEmbeddingProvider = class {
 * directly, so it is not ported.)
 */
 /**
+* The stable first stderr line for a missing provider key, on BOTH planes:
+* `ksor serve` (through the gateway's `bootErrorLines`) and `ksor ingest` /
+* `ksor calibrate` (the write plane's `fail`). Exit 3 either way — the key is
+* the operator's environment — but an exit code is not a name, and this was
+* the one refusal in the first-hour path that printed its sentence with no
+* slug above it (found live, 2026-09-02).
+*/
+const PROVIDER_KEY_MISSING = "ksor-provider-key-missing";
+/**
 * A key-needing provider was built without an API key. A TYPED error (mirrors
 * EmbeddingSpaceMismatch) so a composition root classifies the missing-key case
 * by TYPE, not by string-matching this message — the exact prose-coupling scar
@@ -9245,6 +9254,7 @@ var OpenAiEmbeddingProvider = class {
 * exit-code mapping no longer breaks when it is reworded.
 */
 var MissingProviderKeyError = class extends Error {
+	slug = PROVIDER_KEY_MISSING;
 	providerName;
 	keyEnv;
 	/**
@@ -9577,6 +9587,34 @@ function keywordAbstains(topRank, config) {
 	if (config.keywordFloor === null) return topRank === null;
 	return topRank === null || topRank < config.keywordFloor;
 }
+const PUBLISHED_SQL = `
+SELECT c.active_generation AS generation,
+       r.source_commit,
+       (SELECT count(*)::int FROM content_nodes n
+         WHERE n.tenant_id = c.tenant_id AND n.generation = c.active_generation) AS nodes
+  FROM corpora c
+  LEFT JOIN ingestion_runs r
+    ON r.tenant_id = c.tenant_id AND r.corpus_id = c.corpus_id
+   AND r.generation = c.active_generation
+ WHERE c.tenant_id = $1 AND c.corpus_id = $2`;
+/**
+* One statement on an already-scoped client, so a readiness probe can read it
+* in place of its own `SELECT 1` and keep the answer fresh without a second
+* statement per probe.
+*/
+async function readPublished(client, instance) {
+	const row = (await client.query(PUBLISHED_SQL, [instance.tenantId, instance.corpusId])).rows[0];
+	const generation = Number(row?.generation ?? 0);
+	if (row === void 0 || generation === 0) return null;
+	return {
+		generation,
+		nodes: Number(row.nodes ?? 0),
+		sourceCommit: row.source_commit ?? "unspecified"
+	};
+}
+async function publishedGeneration(pool, instance) {
+	return runRead(pool, instance.tenantId, (client) => readPublished(client, instance));
+}
 /** The serving subset of the schema CHECK vocabulary. */
 const READ_ACTIONS = /* @__PURE__ */ new Set([
 	"similarity_searched",
@@ -10551,6 +10589,39 @@ async function search(ctx, query, k = 10) {
 		textSearchConfig: inst.textSearchConfig,
 		pinnedGeneration: null
 	};
+	if (await runRead(ctx.pool, inst.tenantId, async (client) => {
+		const r = await client.query("SELECT active_generation FROM corpora WHERE tenant_id = $1 AND corpus_id = $2", [inst.tenantId, inst.corpusId]);
+		return Number(r.rows[0]?.active_generation ?? 0);
+	}, servingScope(ctx)) === 0) {
+		const audited = await logRead(ctx.pool, {
+			tenantId: inst.tenantId,
+			corpusId: inst.corpusId,
+			actor,
+			action: "search_abstained",
+			instanceDigest: ctx.instanceDigest,
+			detail: {
+				...actScope(ctx),
+				abstained: true,
+				result_count: 0,
+				query_chars: queryChars,
+				k,
+				k_effective: kb,
+				top_cosine: null,
+				degraded: false
+			}
+		});
+		return {
+			ok: false,
+			abstained: false,
+			reason: "unpublished",
+			gate: gateState(inst),
+			top_cosine: null,
+			hits: [],
+			snapshot: null,
+			...kNote === void 0 ? {} : { k_note: kNote },
+			...audited ? {} : { audit: "degraded" }
+		};
+	}
 	let queryVector = null;
 	let degradedReason;
 	let embedFailed = false;
@@ -10602,11 +10673,7 @@ async function search(ctx, query, k = 10) {
 				degraded: degradedReason !== void 0
 			}
 		});
-		const unpublished = generation === void 0 && await runRead(ctx.pool, inst.tenantId, async (client) => {
-			const r = await client.query("SELECT active_generation FROM corpora WHERE tenant_id = $1 AND corpus_id = $2", [inst.tenantId, inst.corpusId]);
-			return Number(r.rows[0]?.active_generation ?? 0) === 0;
-		}, servingScope(ctx));
-		const reason = embedFailed ? "unavailable" : unpublished ? "unpublished" : "abstained";
+		const reason = embedFailed ? "unavailable" : "abstained";
 		return {
 			ok: false,
 			abstained: reason === "abstained",
@@ -11156,4 +11223,4 @@ function readHandler(ctx) {
 	};
 }
 //#endregion
-export { parseViewer as A, tallyHandlers as B, contentPoolMin as C, outlineHandler as D, keyRingFromEnv as E, recordIsUndescribed as F, z$1 as G, validateViewer as H, runProbe as I, searchHandler as L, prewarmPool as M, providerKeyEnv as N, parseInstanceText as O, readHandler as P, servingPolicy as R, contentPool as S, instancePathOf as T, withPgRetry as U, tlsPosture as V, withProbeDeadline as W, assertGovernanceServable as _, GovernanceGateError as a, checkEmbeddingSpace as b, McpServer$1 as c, READ_ONLY as d, READ_OUTPUT as f, TextSearchConfigMismatch as g, TRUST_TIERS as h, FLOOR as i, pooledEndpointFor as j, parseTrustFloor as k, MissingProviderKeyError as l, SchemaVersionError as m, ContentStoreError as n, MAX_OUTLINE_LIMIT as o, SEARCH_OUTPUT as p, EmbeddingSpaceMismatch as r, MAX_SEARCH_K as s, AudienceError as t, OUTLINE_OUTPUT as u, assertSchemaCompatible as v, embedQueryVlit as w, composeInstructions as x, buildShippedProvider as y, storedTextSearchConfig as z };
+export { parseViewer as A, servingPolicy as B, contentPoolMin as C, outlineHandler as D, keyRingFromEnv as E, readHandler as F, withPgRetry as G, tallyHandlers as H, readPublished as I, withProbeDeadline as K, recordIsUndescribed as L, prewarmPool as M, providerKeyEnv as N, parseInstanceText as O, publishedGeneration as P, runProbe as R, contentPool as S, instancePathOf as T, tlsPosture as U, storedTextSearchConfig as V, validateViewer as W, assertGovernanceServable as _, GovernanceGateError as a, checkEmbeddingSpace as b, McpServer$1 as c, READ_ONLY as d, READ_OUTPUT as f, TextSearchConfigMismatch as g, TRUST_TIERS as h, FLOOR as i, pooledEndpointFor as j, parseTrustFloor as k, MissingProviderKeyError as l, SchemaVersionError as m, ContentStoreError as n, MAX_OUTLINE_LIMIT as o, SEARCH_OUTPUT as p, z$1 as q, EmbeddingSpaceMismatch as r, MAX_SEARCH_K as s, AudienceError as t, OUTLINE_OUTPUT as u, assertSchemaCompatible as v, embedQueryVlit as w, composeInstructions as x, buildShippedProvider as y, searchHandler as z };

package/dist/gateway.d.mts

@@ -1,7 +1,7 @@
 import { CallToolResult, McpServer as McpServer$1, StandardSchemaWithJSON } from "@modelcontextprotocol/server";
 import { z as z$1 } from "zod";
 import pg from "pg";
-//#region ../content-gateway/dist/gateway-api-CEnK8Bc8.d.mts
+//#region ../content-gateway/dist/gateway-api-Cla3mzJ0.d.mts
 //#region src/instructions.d.ts
 /**
  * Has the owner said what this record is FOR yet?
@@ -16,7 +16,7 @@ import pg from "pg";
 declare function recordIsUndescribed(authored: string): boolean;
 declare function composeInstructions(authored: string): string;
 //#endregion
-//#region ../content/dist/index-D-xEl8mz.d.mts
+//#region ../content/dist/index-gfAuwbwI.d.mts
 declare const TRUST_TIERS: readonly ["unverified", "machine-confirmed", "human-reviewed"];
 type TrustTier = (typeof TRUST_TIERS)[number];
 //#endregion

package/dist/gateway.mjs

@@ -1,2 +1,2 @@
-import { D as outlineHandler, F as recordIsUndescribed, G as z$1, L as searchHandler, P as readHandler, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, h as TRUST_TIERS, i as FLOOR, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, s as MAX_SEARCH_K, u as OUTLINE_OUTPUT, x as composeInstructions } from "./gateway-api-C0vL3oOK-D24n786A.mjs";
+import { D as outlineHandler, F as readHandler, L as recordIsUndescribed, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, h as TRUST_TIERS, i as FLOOR, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, q as z$1, s as MAX_SEARCH_K, u as OUTLINE_OUTPUT, x as composeInstructions, z as searchHandler } from "./gateway-api-CEsb-e8z-Ch6oMaq2.mjs";
 export { FLOOR, MAX_OUTLINE_LIMIT, MAX_SEARCH_K, McpServer$1 as McpServer, OUTLINE_OUTPUT, READ_ONLY, READ_OUTPUT, SEARCH_OUTPUT, TRUST_TIERS, composeInstructions, outlineHandler, readHandler, recordIsUndescribed, searchHandler, z$1 as z };

package/docs/building.md

@@ -0,0 +1,157 @@
+---
+title: Building
+status: draft
+---
+
+# `ksor build`, and handing the record to something else
+
+`ksor build` is the database-free verb that makes the SITE correct: it
+regenerates every `index.md` in memory, runs the record checker, and on green
+writes the indexes whose bytes changed plus `build.lock.json` — the provenance
+every machine artefact stamps. `pnpm build` in a scaffold runs it before the
+site build, so most owners never type it. The verb's own page is
+`ksor build --help`; the flags that matter here:
+
+```bash
+ksor build                                 # check, regenerate, write the lock
+ksor build --as-of 2026-09-01T00:00:00Z    # pin the instant lifecycle is judged at
+ksor build --strict                        # refuse an uncommitted input (a release)
+ksor build --bundles                       # also write one OKF bundle per viewer
+```
+
+A refusal exits `1` with its slug on the first stderr line and writes nothing.
+
+## `--bundles`: one OKF bundle per viewer
+
+The record is an OKF bundle in the KSoR Profile, so `knowledge/` handed to any
+OKF consumer already reads as a conformant bundle. What it does NOT do is
+respect audience: the committed tree holds every document for every reader,
+drafts and internal ones included, because anyone with the repository has the
+files anyway. `--bundles` is the projection for the case where you hand the
+record to someone who should see only part of it.
+
+For `public`, and for each audience `X` registered in `.ksor/governance.yaml`,
+it writes `.ksor/out/bundles/<viewer>/` built for the viewer list
+`[public, X]` exactly — the same admission the site and the MCP door use, taken
+from the lock's own `admitted` set:
+
+- the admitted concepts only: `stable`, past `effective_from`, before
+  `stale_after`, not taken down, audience overlapping;
+- their companions (`x.summary.md`, `x.flashcards.yaml`, …) beside them;
+- the assets their bodies reference — an image nothing published mentions does
+  not travel;
+- every `index.md` regenerated for that filtered tree, with `okf_version` at
+  the root, so a folder with nothing admitted has no index and no bullet in
+  its parent;
+- frontmatter verbatim, unknown keys preserved, bytes unchanged.
+
+No byte of a concept excluded for AUDIENCE reaches a bundle: not its title, its
+path, its description, a companion of it, or an asset only it references. The
+test that holds this greps the emitted tree for the excluded document rather
+than inspecting it by name, because a bundle is the one projection that leaves
+the building. What makes it byte-complete is the record checker, not this
+command: a link, a supersession pointer or a companion body reaching a narrower
+audience is refused as `ksor-link-widens` before a bundle is ever planned, so a
+body copied verbatim cannot name what its own readers may not open.
+
+An exclusion for a LIFECYCLE or LEDGER reason — a draft, a document not yet
+effective, one past `stale_after`, one taken down — is narrower on purpose. The
+body is copied verbatim, never rewritten, so if a held document links to one of
+those, the excluded path ships inside that link. It is [reported per
+bundle](#what-it-will-tell-you) rather than edited away: rewriting a body would
+make the bundle a derivative instead of a copy you can hash against the record,
+and the reader who sees the path is already entitled to that audience.
+
+```
+.ksor/out/bundles/
+├── build.lock.json        # a copy — the bundles travel with the build that made them
+├── public/
+│   ├── index.md           # okf_version: "0.2", bullets for what public may read
+│   ├── what-is-a-ksor.md
+│   ├── what-is-a-ksor.summary.md
+│   └── surfaces/
+│       ├── index.md
+│       └── …
+└── internal/              # the viewer [public, internal]: everything above, plus
+    ├── index.md
+    ├── board-pay.md
+    └── …
+```
+
+The directory is REPLACED on every `--bundles` run, so a bundle for an audience
+the policy no longer registers does not sit beside the fresh ones. It is
+gitignored by the scaffold's `.ksor/*` rule; nothing under it is the record.
+
+### What the lock records
+
+`build.lock.json` carries `bundles[]` — one `{ viewer, sha256, files }` per
+viewer — on EVERY build, whether or not `--bundles` was passed. The bundles are
+a function of what the lock already hashes, so recording them does not depend
+on the flag and does not move `build_id`. The digest is sha256 over the JSON of
+the bundle's sorted `[path, sha256]` pairs, stated this plainly so a recipient
+holding only the directory can recompute it and match it to a publication:
+
+```js
+import { createHash } from "node:crypto";
+const sha = (b) => createHash("sha256").update(b).digest("hex");
+const pairs = files // [[relativePath, bytes], …] — every file in the bundle
+  .map(([rel, bytes]) => [rel, sha(bytes)])
+  .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+const digest = sha(JSON.stringify(pairs)); // equals lock.bundles[i].sha256
+```
+
+### What it will tell you
+
+A body is copied verbatim, never rewritten. If an admitted document links to a
+concept the bundle excludes for a lifecycle or ledger reason — a draft, one not
+yet effective, one past its review date, one taken down — the link dangles for
+that bundle's reader, and the build says so on stdout:
+
+```
+  wrote .ksor/out/bundles/public/ — the OKF bundle for viewer [public], 8 file(s)
+    policies/board-pay.md links to policies/purchase-approval.md, which this bundle excludes — the link dangles for its reader
+```
+
+A link that would widen AUDIENCE never gets this far: the record checker
+refuses it (`ksor-link-widens`) before any bundle is planned, because a public
+document naming an internal one leaks the name whether or not the target
+travels.
+
+Two refusals come from the bundles, and both run on EVERY build, with or
+without the flag — the lock records `bundles[]` either way, and a digest for a
+directory the tool refuses to write would be provenance for something that
+cannot exist.
+
+An audience identifier is a directory name here, so one that cannot be a path
+segment is refused before anything is written:
+
+```
+error: ksor-audience-identifier-invalid
+```
+
+Name audiences in plain words — a letter or a digit first, then letters,
+digits, `-`, `_` and `.` — in `.ksor/governance.yaml` and in every
+`ksor.audience` list. That first-character rule is why `../escape`, `.hidden`
+and `-x` are all refused, and `build.lock.json` is refused too: the lock copy
+sits beside the bundle directories.
+
+Two registered audiences that differ only in case — `internal` and `Internal` —
+are two viewers and one directory on macOS and on Windows, whose filesystems
+are case-insensitive by default. The second bundle written would merge into the
+first, leaving a directory holding concepts the viewer named on it may not read
+and a lock digest that no longer describes it, so they are refused on every
+platform alike:
+
+```
+error: ksor-audience-identifier-collides
+```
+
+Give each audience a name that differs by more than case. `public` is reserved,
+casefolded too.
+
+### What it is not
+
+It is not import: reading a foreign bundle into a record is not built. And it
+is not the site or the door — a bundle carries no `llms.txt`, no search index,
+no citations. It is the record, filtered to one viewer, in the format the record
+is already written in.

package/docs/deploying.md

@@ -314,8 +314,8 @@ correct for a genuinely public record or one behind your own gateway; it is not
 way to make a deploy go green.
 
 The alternative is a real authorization server — `KSOR_SSO_URL`,
-`KSOR_MCP_RESOURCE_URL`, `KSOR_JWT_ALLOWED_AUDIENCES`, with worked recipes for two
-of them in [authorization.md](./authorization.md).
+`KSOR_MCP_RESOURCE_URL`, `KSOR_JWT_ALLOWED_AUDIENCES`, with worked recipes for
+four of them in [authorization.md](./authorization.md).
 
 ### Set this on any container host
 
@@ -378,7 +378,14 @@ to anyone who types the URL, so there is nothing for rebinding to steal.
 database: it regenerates every `index.md`, runs the record checker, and writes
 `build.lock.json` — commit it — which every machine artefact stamps. A refusal
 stops the build before a byte is written; `--strict` also refuses an
-uncommitted input. Takedowns reach the site through the committed ledger
+uncommitted input. One refusal reads git: a `stable` document whose body
+changed while its `generated.at` did not ADVANCE — left alone, or moved
+backward — is `ksor-generated-stale`, compared against every committed version
+of the file, so when you edit a published document, move the stamp forward and
+re-approve. A checkout without history cannot
+read those versions; the build then prints `change-control: not checked` (or,
+on a shallow clone, how many versions it did read) beside the `source:` line
+instead of passing quietly. Takedowns reach the site through the committed ledger
 (`.ksor/takedowns.yaml`), which is a file in the repository — so the site build
 needs no `KSOR_DB_URL` at all.
 
@@ -573,7 +580,7 @@ auth-off default, and that refusal is the last real step of a deployment. Two
 ways past it:
 
 - **Configure the SSO door** — `KSOR_SSO_URL`, `KSOR_MCP_RESOURCE_URL`,
-  `KSOR_JWT_ALLOWED_AUDIENCES`. Worked recipes for two different authorization
+  `KSOR_JWT_ALLOWED_AUDIENCES`. Worked recipes for four different authorization
   servers: [authorization.md](./authorization.md).
 - **Set `KSOR_AUTH=disabled-public`** — a deliberate decision that
   serves your whole record to anyone who can reach the port. Correct for a
@@ -585,13 +592,18 @@ Check which one you got. `/health` says so plainly:
 ```json
 {
   "corpus_id": "book",
-  "abstain_gate": "OFF (no floor declared — will not refuse out-of-corpus questions)",
+  "generation": "1 · 81 nodes · source 3807493d3f2f1b4c2e6b0a9d8c7f6e5d4c3b2a10",
+  "abstain_gate": "OFF — no floor calibrated; out-of-corpus questions will be answered, not refused",
   "embedding_space": "gemini-embedding-001/d1536 ok",
   "auth": "disabled"
 }
 ```
 
 `"auth":"disabled"` on a public host means the second option is in effect.
+`"generation"` is what the door is serving — `NONE — nothing published; run
+pnpm refresh` on a record that was provisioned and never ingested, which is
+where skipping the publish step leaves it — and it is re-read on every
+readiness probe, so a `refresh` after boot shows here without a restart.
 
 ## What a cold start costs
 

package/docs/index.md

@@ -43,6 +43,10 @@ instead of their training memory. The corpus grows with each implemented verb.
     `system/gateways/content.ts` is emitted, adopter-owned and deletable; it
     decides tool names, what the record says it covers, and how much of the
     caller's context an answer costs. Includes the measurements.
+  - **[building.md](./building.md)** — `ksor build`, and `--bundles`: one OKF
+    bundle per viewer under `.ksor/out/bundles/`, holding only what that
+    viewer's machine surfaces publish, for handing the record to another
+    system with no ksor in the loop. Includes how the lock records each one.
   - **[deploying.md](./deploying.md)** — getting both surfaces onto a host. The
     scaffold emits a `Dockerfile` that names no vendor, and a `vercel.json` that
     points at it to put the site and the MCP door behind one domain. Includes
@@ -57,14 +61,14 @@ instead of their training memory. The corpus grows with each implemented verb.
     which a dependency bump reaches a project already scaffolded. Includes the
     list of files migrate does NOT carry, so you know what to diff by hand.
   - **[authorization.md](./authorization.md)** — putting the record behind an
-    authorization server, with worked recipes for two of them, executed rather
-    than written. `ksor serve` refuses to boot unauthenticated on a public bind,
+    authorization server, with worked recipes for four of them — two self-hosted,
+    one hosted, one an organisation's own — executed rather than written. `ksor serve` refuses to boot unauthenticated on a public bind,
     so this is the last step of a deployment, not an optional hardening pass.
 - Exit codes are a contract: `1` refused (first stderr line is a stable
   slug such as `error: bad-name`, followed by a remedy), `2` designed but
   not implemented, `3` the environment cannot run ksor
   (`error: unsupported-platform`, `error: broken-install`,
-  `error: environment`).
+  `error: ksor-provider-key-missing`, `error: environment`).
 - The package root exports the CLI contract: `exitCodes`, `verbs`, and
   `resolveCommand`.
 

package/docs/ingesting.md

@@ -50,7 +50,7 @@ root**, where `instance.md` and `package.json` live.
 
 ```sh
 pnpm provision   # ksor schema --apply, then ksor grant
-pnpm refresh     # ksor ingest --flip, then ksor gc
+pnpm refresh     # ksor build, then ksor ingest --flip, then ksor gc
 ```
 
 `provision` is separate because applying DDL and granting ingest are acts an
@@ -88,6 +88,26 @@ website's lock was fixed for exactly this once already, after deleting a
 denial's four lines republished the document with the committed lock still
 validating; ingest had the same hole, found by review before anyone hit it.
 
+## When ingest says generated.at is stale
+
+`ksor ingest` runs the same change-control check `ksor build` runs (KSP R23;
+the scaffold's `pnpm check` does not — it is the format gate, and reads no
+document history): a `stable` document whose body differs from a committed version
+that was `stable`, without `generated.at` having advanced past that version's,
+is refused `ksor-generated-stale`, before anything is written. The stamp dates
+the text, so leaving it alone and moving it backward are refused alike.
+The fix is the one it prints — set `generated.at` to an instant after the edit,
+then re-approve, because `ksor.approval.at` may not precede it — and the check
+reads every committed version of the file, so an edit committed without a bump
+is refused on a clean tree too.
+
+Ingest reads git for this, and a container that received the record without
+its `.git` cannot. It then prints `change-control: not checked` on stderr and
+continues: a check that could not run is reported, never counted as passed.
+Who approved is still checked against the policy alone — every envelope says
+`approval.checked: "policy"` — because R22 and R25 wait on an identity the
+platform can vouch for.
+
 ## What a generation is
 
 Each ingest builds a **fresh generation** — invisible until activated — and
@@ -204,7 +224,10 @@ LLM, and question synthesis is Gemini-only today — so a record on
 refused here for a Google key. That is a real gap, stated rather than papered
 over; the zero-LLM door below avoids it entirely and is the better choice on a
 free-tier key anyway, because a free key allows only a few generations a minute
-and a bigger corpus makes that worse, not better.
+and a bigger corpus makes that worse, not better. Zero-LLM is not zero-key: the
+questions are still embedded, so the embedding provider's own key
+(`GEMINI_API_KEY` or `OPENAI_API_KEY`, whichever `embedding.provider` names) is
+still required — only the question synthesis is skipped.
 
 Write your own in-corpus questions, one per line, and pass them:
 
@@ -289,9 +312,12 @@ decision in this project's own gold rather than a threshold somebody picked.
 Run it on a schedule, or in your own CI beside `ksor build`. Three things to
 know about what it is:
 
-- **It never fails a run.** It always exits 0. A stale floor wants
-  re-measuring, and failing a build for one would make the shortest way out
-  deleting `vector_floor` — turning the gate off entirely to clear the error.
+- **A verdict never fails a run.** STEADY, WATCH and no-data all exit 0: a
+  stale floor wants re-measuring, and failing a build for one would make the
+  shortest way out deleting `vector_floor` — turning the gate off entirely to
+  clear the error. What does exit non-zero is the environment, the same way it
+  does for every verb: 3 when `KSOR_DB_URL` is unset or the database is
+  unreachable, 1 on a bad flag. Put it in CI knowing that.
 - **It reads traffic, so it needs traffic**, and it says so rather than
   reporting a healthy-looking nothing. It also cannot see questions nobody
   asked: it can tell you the floor has gone permissive, never that it is too
@@ -326,7 +352,11 @@ pull request is refused exactly as the verb would refuse it.
 Lifting a takedown is `--revoke <entry-id>` — the id of the LEDGER ENTRY, not
 the stable id. The denial that created it prints the id, `ksor takedown
 --ledger` lists it, and it is written in `.ksor/takedowns.yaml`; none of the
-three needs a database, because the ledger is a file in the repository. The
+three needs a database, because the ledger is a file in the repository —
+`--ledger` reads that file and never asks for a DSN, whatever `instance.md`
+declares. (`--list` is a question about the door's rows, so it reads them when
+the DSN is set; with none it lists the ledger's denials, each labelled
+`not applied (no database)`.) The
 ledger is append-only: a revocation is a new entry, never a deleted line, and a
 build whose ledger shrank against its own git history is refused.
 

package/docs/tool-surface.md

@@ -144,9 +144,6 @@ made it answer from.
   only things that can prove a passage came from the governed record. A
   hand-written one returning fabricated hits with plausible `stable_id`s would
   pass every shape check there is.
-- **The output schemas.** `SEARCH_OUTPUT`, `OUTLINE_OUTPUT`, `READ_OUTPUT` carry
-  `provenance`, each hit's `governance`, the `snapshot` token and `gate`. A
-  record that reshaped them would still look like a KSoR and no longer be one.
 - **The output schemas.** `SEARCH_OUTPUT`, `OUTLINE_OUTPUT`, `READ_OUTPUT` carry
   `provenance`, each hit's `governance`, the `snapshot` token, `gate`, and
   `audit`. A record that reshaped them would still look like a KSoR and no

package/docs/upgrading.md

@@ -45,6 +45,7 @@ easier to read when nothing else is uncommitted.
 | `.gitignore`                                    | the entries a new release needs negated                                                     |
 | `.agents/` and `.claude/` format-checker        | the emitted checker, so your own `pnpm check` and your CI agree with the tool               |
 | root `package.json` **scripts**                 | scripts a release broke — a removed flag, a step that now needs `ksor build` in front of it |
+| `build.lock.json`                               | DELETED when this ksor cannot read it — see below                                           |
 | `system/site/**`                                | **only with `--write-site`** — every file of the site this release emits                    |
 
 `--write-site` is the one to remember, because it is the only path by which a
@@ -54,6 +55,19 @@ security bump reaches an existing project: the site's `package.json` is where
 It is an **update, never a creation**. A record with no `system/site` of its own
 is not given one.
 
+### A lock a newer ksor cannot read is deleted, never rewritten
+
+`build.lock.json` gains fields as the record's surfaces grow, and `ksor build`
+REFUSES a lock missing one (`ksor-lock-invalid`) instead of regenerating it: the
+lock is also a takedown baseline, and a baseline nothing can parse is one that
+quietly holds nothing. So the file has to GO before the first build on a new
+ksor, and step 3 is what removes it — the diff shows the deletion like any
+other. Step 4 then writes the current one.
+
+Skip the migration and step 4 tells you the same thing: `ksor build` exits 1
+naming the file, and so does `pnpm build`, which runs it first. Nothing is lost
+— a lock is computed from the tree, never edited.
+
 ### The site manifest is merged, not replaced
 
 Every other file under `system/site` is reissued whole. `system/site/package.json`
@@ -76,7 +90,7 @@ These are yours, and no release touches them. Diff them against a fresh
 - `pnpm-workspace.yaml` / `.npmrc` and any lockfile
 
 ```sh
-npx @panaversity/ksor@latest init /tmp/fresh
+(cd /tmp && npx @panaversity/ksor@latest init fresh)   # init takes a NAME, not a path
 diff -ru /tmp/fresh/vercel.json ./vercel.json
 ```
 
@@ -97,7 +111,7 @@ that supplies it. Two you will meet often:
 
 ## After it applies
 
-`pnpm build` regenerates every index and rewrites `build.lock.json`; `pnpm check`
+`pnpm build` regenerates every index and writes a fresh `build.lock.json`; `pnpm check`
 runs the record checker that shipped with the new tool. If you serve the record,
 `ksor schema --apply` and then a full `pnpm refresh` publish a generation the new
 door can read — and a calibrated `vector_floor` measured under an older serving

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.57",
+  "version": "0.0.59",
   "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",