@panaversity/ksor 0.0.49 → 0.0.51

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # @panaversity/ksor
 
+## 0.0.51
+
+### Patch Changes
+
+- 6478ca4: Test infrastructure only — nothing an adopter installs behaves differently.
+
+  Every database-tier suite now bootstraps its scratch database under a name
+  unique to the run (`ksor_<slug>_<base36 ms>_<6 hex>`) instead of a fixed one.
+  Fixed names meant two runs against one Postgres — a second `pnpm test:db`, a CI
+  matrix job, an agent running the tier alongside a person — dropped each other's
+  database `WITH (FORCE)` mid-test, which surfaced as a missing table or a short
+  row count and read as flakiness. A new reaper (`scripts/db-reaper.ts`, the
+  tier's globalSetup) drops what an interrupted run leaks, and guard rule 12 keeps
+  the naming from drifting back.
+
+- c466d4b: The scaffold moves to Fumadocs `16.15.4` (`fumadocs-core`, `fumadocs-ui`) and
+  `fumadocs-mdx` `15.4.0`.
+
+  Maintenance, not a fix — no advisory pushed it, and `npm audit` was already
+  clean. It is taken now because the four behaviours the scaffold cites BY VERSION
+  were re-verified against the new bytes rather than assumed, and each holds:
+  `CalloutType` is still the same six values (`fumadocs-ui/dist/components/callout.d.ts`);
+  `resolveHref` still resolves only the `./` and `../` forms and returns everything
+  else untouched, which is why the record keeps its own resolver; `remark-code-tab`
+  still honours `tab-group` on the `CodeBlockTabs` branch only, which is why the
+  scaffold picks that branch; and the search engine is still ZBSearch, so the
+  `language` option stays absent. Those citations now name `16.15.4`.
+
+  `fumadocs-ui` pins `fumadocs-core` exactly, so the two always move together;
+  `fumadocs-mdx@15.4.0` requires `fumadocs-core ^16.15.3`, which is what makes this
+  one change rather than three. Nothing else moves with it — Fumadocs peers Next as
+  a range (`16.x.x`). The committed pnpm lockfile is regenerated to match.
+
+- 69d57f2: `ksor migrate --write-site` no longer deletes dependencies the adopter added to
+  their site.
+
+  Every file under `system/site` is offered as a whole-file replacement, which is
+  right for the copied rule modules and wrong for `system/site/package.json` — a
+  register ksor and the adopter both write in. Copying it whole removed anything
+  they had added, inside the same hunk that carried a pin bump, so a project could
+  stop building on the release meant to fix it. It is now merged per section: the
+  entries ksor ships move to this release's versions, the adopter's own survive,
+  and an entry ksor no longer ships is left alone rather than deleted (the tool
+  cannot tell one it retired from one they added).
+
+  Adds `docs/upgrading.md`, which ships in the tarball: the four-step path, the
+  table of what migrate carries, the list of files it does not — so an adopter
+  knows what to diff by hand — and the refusals to expect.
+
+- 4b077aa: The scaffold pins Next `16.3.3`, clearing three high-severity advisories a
+  fresh `npm install` reported (#207).
+
+  `next@16.2.9` pulled `sharp@0.34.5` and `postcss@8.4.31`; the advisories are
+  against those, not against anything the scaffold declares, so the bump that
+  fixes them is Next's own. Measured on a fresh scaffold from the published CLI:
+  `npm audit` goes from **3 high to 0**, the static build takes 41.8s and emits
+  its 22 pages, and `llms.txt` carries its 5 entries unchanged. `16.3.3` is not
+  semver-major and Fumadocs peers Next as a range (`16.x.x`), so nothing else
+  moves with it. The committed pnpm lockfile is regenerated to match — the half
+  that would otherwise break an adopter whose CI installs frozen.
+
+  An existing project takes both across with
+  `ksor migrate --write-site`, which offers every file of `system/site` this
+  release emits — the pin and the config among them. It prints the diff and
+  changes nothing without `--write`.
+
+  The scaffold's `next.config.mjs` also sets `agentRules: false`. From Next 16.3,
+  a `next dev` that detects a coding agent writes `AGENTS.md` and `CLAUDE.md` into
+  the Next project root — which here is `system/site`, where the record's own
+  hygiene rule refuses markdown (`ksor-site-holds-content`: the site renders the
+  record, it never holds it). Left on, an adopter's `pnpm dev` turned their own
+  `pnpm check` red without their touching anything.
+
+## 0.0.50
+
+### Patch Changes
+
+- f27f947: The three embed tuning variables now take effect when set in `.env`.
+  `KSOR_EMBED_TIMEOUT_S`, `KSOR_QUERY_EMBED_TIMEOUT_S` and `KSOR_EMBED_CACHE_MAX`
+  were read once at module load — before the CLI applies `.env` in `main()` — so
+  a value set there was silently ignored and the default stood. An adopter who
+  set `KSOR_EMBED_CACHE_MAX` to fit a small runtime, for instance, still got the
+  ~250 MB default cache and could OOM in production with nothing pointing at why.
+  The reads now happen at use. Exported shell variables were unaffected and still
+  are.
+
 ## 0.0.49
 
 ### Patch Changes

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { n as resolveCommand, r as verbs, t as exitCodes } from "./src-dqpI-p1a.mjs";
-import { A as parseViewer, B as tlsPosture, C as contentPoolMin, D as outlineHandler, E as keyRingFromEnv, F as runProbe$1, H as withPgRetry$1, I as searchHandler, L as servingPolicy$1, M as prewarmPool, N as readHandler, O as parseInstanceText$1, P as recordIsUndescribed, R as storedTextSearchConfig, S as contentPool$1, T as instancePathOf$1, U as withProbeDeadline$1, V as validateViewer, W as z$1, _ as assertGovernanceServable$1, a as GovernanceGateError$1, b as checkEmbeddingSpace$1, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, g as TextSearchConfigMismatch, h as TRUST_TIERS$1, i as FLOOR, j as pooledEndpointFor, k as parseTrustFloor, l as MissingProviderKeyError$1, m as SchemaVersionError, n as ContentStoreError$1, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, r as EmbeddingSpaceMismatch$1, t as AudienceError$1, u as OUTLINE_OUTPUT, v as assertSchemaCompatible, w as embedQueryVlit, x as composeInstructions, y as buildShippedProvider$1, z as tallyHandlers } from "./gateway-api-8DkVCYYi-Bo0_Y1Y3.mjs";
+import { A as parseViewer, B as tlsPosture, C as contentPoolMin, D as outlineHandler, E as keyRingFromEnv, F as runProbe$1, H as withPgRetry$1, I as searchHandler, L as servingPolicy$1, M as prewarmPool, N as readHandler, O as parseInstanceText$1, P as recordIsUndescribed, R as storedTextSearchConfig, S as contentPool$1, T as instancePathOf$1, U as withProbeDeadline$1, V as validateViewer, W as z$1, _ as assertGovernanceServable$1, a as GovernanceGateError$1, b as checkEmbeddingSpace$1, c as McpServer$1, d as READ_ONLY, f as READ_OUTPUT, g as TextSearchConfigMismatch, h as TRUST_TIERS$1, i as FLOOR, j as pooledEndpointFor, k as parseTrustFloor, l as MissingProviderKeyError$1, m as SchemaVersionError, n as ContentStoreError$1, o as MAX_OUTLINE_LIMIT, p as SEARCH_OUTPUT, r as EmbeddingSpaceMismatch$1, t as AudienceError$1, u as OUTLINE_OUTPUT, v as assertSchemaCompatible, w as embedQueryVlit, x as composeInstructions, y as buildShippedProvider$1, z as tallyHandlers } from "./gateway-api-D8HlLys2-Ca8OnwLn.mjs";
 import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { InMemoryTransport, LATEST_PROTOCOL_VERSION, createMcpHandler } from "@modelcontextprotocol/server";
@@ -17,7 +17,7 @@ import { Document, YAMLParseError, isCollection, isMap, isPair, isSeq, parseAllD
 import { parseArgs } from "node:util";
 import { readFile } from "node:fs/promises";
 import { execFileSync, spawnSync } from "node:child_process";
-//#region ../content-gateway/dist/main-BXNvtHqd.mjs
+//#region ../content-gateway/dist/main-DMCMO8ye.mjs
 /**
 * The default registration — and the ORIGINAL of the file `ksor init` emits.
 *
@@ -4709,7 +4709,7 @@ async function withPgRetry(op, options = {}) {
 	throw lastError;
 }
 //#endregion
-//#region ../content/dist/commands-C3D7buZN.mjs
+//#region ../content/dist/commands-BNxmBRjs.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -5787,11 +5787,12 @@ async function topOneScore(client, scope, queryVector) {
 	})).rows[0]?.[0];
 	return raw === void 0 || raw === null ? null : toNumber(raw, "score");
 }
-const EMBED_TIMEOUT_S = envFloat("KSOR_EMBED_TIMEOUT_S", 60, 1);
+/** The per-request HTTP timeout for a document (ingest/batch) embed. */
+const EMBED_TIMEOUT_S = () => envFloat("KSOR_EMBED_TIMEOUT_S", 60, 1);
 /** Oracle env var: SOR_QUERY_EMBED_TIMEOUT_S. Note: query-embed.ts reads the
 * SAME variable with a different default (5.0) as its hard wall clock — two
 * deliberate reads, carried from the oracle (embedding.py:62 vs query_embed.py:44). */
-const QUERY_EMBED_TIMEOUT_S = envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 10, 1);
+const QUERY_EMBED_TIMEOUT_S = () => envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 10, 1);
 /** The text we embed for a chunk: the readable hierarchical heading path, then the content. */
 function embedInput(title, headingPath, content) {
 	const path = headingPath ? (title ? title + " > " : "") + headingPath.replaceAll("/", " > ").replaceAll("-", " ").trim() : title;
@@ -6213,8 +6214,8 @@ function buildShippedProvider(name, opts) {
 		dim: opts.dim ?? 1536,
 		documentTaskLabel: EMBED_TASK_DOCUMENT,
 		queryTaskLabel: EMBED_TASK_QUERY,
-		documentTimeoutS: EMBED_TIMEOUT_S,
-		queryTimeoutS: QUERY_EMBED_TIMEOUT_S
+		documentTimeoutS: EMBED_TIMEOUT_S(),
+		queryTimeoutS: QUERY_EMBED_TIMEOUT_S()
 	});
 }
 /** Written to yield ZERO ROWS, never an error, when the schema is absent. */
@@ -13058,9 +13059,10 @@ function siteChanges(root, templatesDir, stamps) {
 				continue;
 			}
 			if (!SITE_TEXT_EXTENSIONS.has(path.extname(entry.name))) continue;
-			const after = applyProse(readFileSync(abs, "utf8").replaceAll("KSOR-STAMP-NAME", stamps.name).replaceAll("KSOR-STAMP-VERSION", stamps.version), manager);
+			const rendered = applyProse(readFileSync(abs, "utf8").replaceAll("KSOR-STAMP-NAME", stamps.name).replaceAll("KSOR-STAMP-VERSION", stamps.version), manager);
 			const target = path.join(root, child);
 			const before = existsSync(target) ? readFileSync(target, "utf8") : null;
+			const after = child === "system/site/package.json" && before !== null ? mergeSiteManifest(before, rendered) : rendered;
 			if (before !== after) out.push({
 				path: child,
 				before,
@@ -13072,6 +13074,61 @@ function siteChanges(root, templatesDir, stamps) {
 	return out;
 }
 /**
+* The site manifest, merged: what ksor pins wins, what the adopter added stays.
+*
+* Applied per SECTION rather than per file. `dependencies`, `devDependencies`
+* and `scripts` are registers with two authors — ksor owns the entries it ships
+* (they are what the emitted site is built and tested against, and a security
+* bump reaches an existing project through exactly this path), and the adopter
+* owns everything else in them. A key ksor no longer ships is left alone rather
+* than deleted: this cannot tell one it retired from one the adopter added.
+*
+* Unparseable on either side falls back to the template, which is the same
+* whole-file offer every other site file gets — a diff, gated on `--write`.
+*/
+function mergeSiteManifest(before, template) {
+	const parse = (text) => {
+		try {
+			const value = JSON.parse(text);
+			return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+		} catch {
+			return null;
+		}
+	};
+	const mine = parse(before);
+	const theirs = parse(template);
+	if (mine === null || theirs === null) return template;
+	const section = (key) => {
+		const a = mine[key];
+		const b = theirs[key];
+		const table = (v) => typeof v === "object" && v !== null && !Array.isArray(v) ? v : null;
+		const ours = table(b);
+		const adopters = table(a);
+		if (ours === null) return adopters ?? void 0;
+		if (adopters === null) return ours;
+		const merged = {};
+		for (const [name, version] of Object.entries(adopters)) merged[name] = name in ours ? ours[name] : version;
+		for (const [name, version] of Object.entries(ours)) if (!(name in merged)) merged[name] = version;
+		return merged;
+	};
+	const MERGED = [
+		"dependencies",
+		"devDependencies",
+		"scripts"
+	];
+	const out = {
+		...mine,
+		...theirs
+	};
+	for (const key of MERGED) {
+		const value = section(key);
+		if (value === void 0) delete out[key];
+		else out[key] = value;
+	}
+	const eol = before.includes("\r\n") ? "\r\n" : "\n";
+	return `${JSON.stringify(out, null, indentOf(before)).replaceAll("\n", eol)}${/\r?\n$/.test(before) ? eol : ""}`;
+}
+/**
 * Which manager this repository was scaffolded for, from what it committed.
 * `ksor init` reads `npm_config_user_agent` — the run that scaffolds is the
 * run that knows — but a migration is a different run, so it reads the tree.

package/dist/{gateway-api-8DkVCYYi-Bo0_Y1Y3.mjs → gateway-api-D8HlLys2-Ca8OnwLn.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-8DkVCYYi.mjs
+//#region ../content-gateway/dist/gateway-api-D8HlLys2.mjs
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
 /**
@@ -8769,11 +8769,12 @@ function validate$1(ring, token, scope, nowMs = Date.now()) {
 		reason: null
 	};
 }
-const EMBED_TIMEOUT_S = envFloat("KSOR_EMBED_TIMEOUT_S", 60, 1);
+/** The per-request HTTP timeout for a document (ingest/batch) embed. */
+const EMBED_TIMEOUT_S = () => envFloat("KSOR_EMBED_TIMEOUT_S", 60, 1);
 /** Oracle env var: SOR_QUERY_EMBED_TIMEOUT_S. Note: query-embed.ts reads the
 * SAME variable with a different default (5.0) as its hard wall clock — two
 * deliberate reads, carried from the oracle (embedding.py:62 vs query_embed.py:44). */
-const QUERY_EMBED_TIMEOUT_S = envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 10, 1);
+const QUERY_EMBED_TIMEOUT_S = () => envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 10, 1);
 function l2Normalize(v) {
 	const norm = Math.sqrt(v.reduce((acc, x) => acc + x * x, 0));
 	return norm === 0 ? v : v.map((x) => x / norm);
@@ -9120,8 +9121,8 @@ function buildShippedProvider(name, opts) {
 		dim: opts.dim ?? 1536,
 		documentTaskLabel: EMBED_TASK_DOCUMENT,
 		queryTaskLabel: EMBED_TASK_QUERY,
-		documentTimeoutS: EMBED_TIMEOUT_S,
-		queryTimeoutS: QUERY_EMBED_TIMEOUT_S
+		documentTimeoutS: EMBED_TIMEOUT_S(),
+		queryTimeoutS: QUERY_EMBED_TIMEOUT_S()
 	});
 }
 /** Written to yield ZERO ROWS, never an error, when the schema is absent. */
@@ -9991,9 +9992,46 @@ async function outline(client, scope, options = {}) {
 		generation: pinned ?? rows[0]?.generation ?? null
 	};
 }
-let cacheMax = envInt("KSOR_EMBED_CACHE_MAX", 1e4, 1);
-/** Oracle env var: SOR_QUERY_EMBED_TIMEOUT_S. */
-const EMBED_WALL_TIMEOUT_S = envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 5, .1);
+/**
+* Query-embedding cache, converted from the oracle (sor-agentfactory @
+* b554f91, sor_content/lib/query_embed.py): L1 in-process LRU + SINGLE-FLIGHT
+* (concurrent identical misses share ONE paid embed), keyed with
+* model + task + dim so a model or dimension bump can never serve a stale
+* vector. Whitespace collapses; case does NOT fold (folding would change the
+* embedded text).
+*
+* A tiny CIRCUIT BREAKER guards the provider: after an embed failure, further
+* misses raise immediately for a short cooldown (cache hits still serve) —
+* during an outage every request degrades to keyword-only instantly instead
+* of each unique query paying its own failed attempt against a provider that
+* is already down. The breaker is keyed per SPACE (modelId, dim), like the
+* keys: a failing provider A must not degrade a healthy provider B.
+*
+* Conversion notes (decision 6):
+* - The oracle's optional Redis L2 (fail-open both directions, TTL
+*   SOR_EMBED_CACHE_TTL, the `sor:emb:*` key scheme) is DROPPED — it was
+*   multi-instance infrastructure; the L1 + single-flight carry a
+*   single-process deployment. It returns, if ever, with real multi-instance
+*   serving — nothing here forecloses it.
+* - The oracle's waiter-shield (`asyncio.shield`) and owner-cancel handling
+*   protected the shared future from one caller's cancellation. JS promises
+*   are not cancellable, so sharing the promise IS the whole mechanism: no
+*   caller can cancel another, and there is no owner-cancelled path to map.
+* - `asyncio.wait_for` CANCELLED the embed on timeout; a JS promise cannot be
+*   cancelled, so on timeout the losing call is abandoned (its settlement is
+*   still observed, so it can never surface as an unhandled rejection) and
+*   runs out its own HTTP timeout in the background.
+* - The breaker clock is Date.now() (ms) rather than a monotonic clock — the
+*   10 s cooldown is coarse, and fake-timer tests need the system clock.
+*/
+/** Oracle env var: SOR_EMBED_CACHE_MAX. */
+let memoizedCacheMax;
+function currentCacheMax() {
+	return memoizedCacheMax ??= envInt("KSOR_EMBED_CACHE_MAX", 1e4, 1);
+}
+/** Oracle env var: SOR_QUERY_EMBED_TIMEOUT_S. Read at use, not at module load
+* — see the cache-max note above. */
+const EMBED_WALL_TIMEOUT_S = () => envFloat("KSOR_QUERY_EMBED_TIMEOUT_S", 5, .1);
 const cache = /* @__PURE__ */ new Map();
 const inflight = /* @__PURE__ */ new Map();
 const breakerOpenUntilByMs = /* @__PURE__ */ new Map();
@@ -10037,10 +10075,11 @@ function breakerOpenUntil(provider) {
 	return breakerOpenUntilByMs.get(spaceKey(provider)) ?? 0;
 }
 function withWallClock(work) {
+	const wallTimeoutS = EMBED_WALL_TIMEOUT_S();
 	return new Promise((resolve, reject) => {
 		const timer = setTimeout(() => {
-			reject(new QueryEmbedTimeoutError(`query embed exceeded the ${EMBED_WALL_TIMEOUT_S}s wall clock — treated as a provider failure (degrade to keyword-only)`));
-		}, EMBED_WALL_TIMEOUT_S * 1e3);
+			reject(new QueryEmbedTimeoutError(`query embed exceeded the ${wallTimeoutS}s wall clock — treated as a provider failure (degrade to keyword-only)`));
+		}, wallTimeoutS * 1e3);
 		work.then((value) => {
 			clearTimeout(timer);
 			resolve(value);
@@ -10061,7 +10100,7 @@ async function embedMiss(normalized, key, provider) {
 		const literal = vlit(vec);
 		cache.delete(key);
 		cache.set(key, literal);
-		while (cache.size > cacheMax) {
+		while (cache.size > currentCacheMax()) {
 			const oldest = cache.keys().next().value;
 			if (oldest === void 0) break;
 			cache.delete(oldest);

package/dist/gateway.mjs

@@ -1,2 +1,2 @@
-import { D as outlineHandler, I as searchHandler, N as readHandler, P as recordIsUndescribed, W as z$1, 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-8DkVCYYi-Bo0_Y1Y3.mjs";
+import { D as outlineHandler, I as searchHandler, N as readHandler, P as recordIsUndescribed, W as z$1, 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-D8HlLys2-Ca8OnwLn.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/index.md

@@ -51,6 +51,11 @@ instead of their training memory. The corpus grows with each implemented verb.
     current. Serving does not publish, so a first deploy with no ingest serves
     an empty record; this is the page that explains why, where ingest belongs
     (never inside the container), and how the abstention gate gets turned on.
+  - **[upgrading.md](./upgrading.md)** — moving an existing record onto a newer
+    ksor. `ksor migrate` offers a diff and changes nothing without `--write`;
+    `--write-site` is the one flag to remember, because it is the only path by
+    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,

package/docs/upgrading.md

@@ -0,0 +1,106 @@
+---
+title: Upgrading a record to a newer ksor
+status: draft
+---
+
+# Upgrading a record to a newer ksor
+
+Your repository is yours. `ksor init` copied files into it and stopped owning
+them the moment it did (decision 4), so upgrading is never something a release
+does to you — it is `ksor migrate` **offering** a diff you read and apply.
+
+Nothing here changes a byte until you pass `--write`.
+
+## The four steps
+
+```sh
+# 1. take the new tool
+pnpm add -w @panaversity/ksor@latest       # npm i / bun add — whichever scaffolded this
+
+# 2. read what it would change
+pnpm exec ksor migrate --instance instance.md --write-site
+
+# 3. apply it
+pnpm exec ksor migrate --instance instance.md --write-site --write --actor human:<your-id>
+
+# 4. rebuild, and check
+pnpm build && pnpm check
+```
+
+`--actor` is required for step 3 whenever the migration touches governance, and
+the tool will not guess one: a ledger entry that names a person who was never
+there is worse than no entry (decision 21). Use the identifier your
+`.ksor/governance.yaml` already knows you by.
+
+Run step 2 on a clean working tree. The diff is the review, and it is much
+easier to read when nothing else is uncommitted.
+
+## What `migrate` carries
+
+|                                                 |                                                                                             |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `instance.md`                                   | the format bump and the keys that moved                                                     |
+| `knowledge/**`                                  | frontmatter into the current profile — statuses, audiences, the trust block, instants       |
+| `.ksor/takedowns.yaml`, `.ksor/governance.yaml` | the ledger and the policy, including denials that lived only in a database                  |
+| `.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 |
+| `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
+security bump reaches an existing project: the site's `package.json` is where
+`next`, `react` and the Fumadocs pins live, and nothing else updates them.
+
+It is an **update, never a creation**. A record with no `system/site` of its own
+is not given one.
+
+### The site manifest is merged, not replaced
+
+Every other file under `system/site` is reissued whole. `system/site/package.json`
+is not, because it is a register with two authors: ksor owns the entries it
+ships, you own everything else. So a dependency or script you added survives the
+upgrade, and the pins ksor ships move to the new versions. An entry ksor no
+longer ships is left alone rather than deleted — the tool cannot tell one it
+retired from one you added.
+
+## What `migrate` does not carry
+
+These are yours, and no release touches them. Diff them against a fresh
+`ksor init` in a scratch directory when a release note says they changed:
+
+- `Dockerfile` and `.dockerignore`
+- `vercel.json` (or whatever your host reads)
+- `.github/workflows/validate.yml`
+- `.env.example`
+- `README.md`, `AGENTS.md`, `CLAUDE.md` at the repository root
+- `pnpm-workspace.yaml` / `.npmrc` and any lockfile
+
+```sh
+npx @panaversity/ksor@latest init /tmp/fresh
+diff -ru /tmp/fresh/vercel.json ./vercel.json
+```
+
+## What refuses, and why that is the point
+
+`migrate` stops rather than inventing. `ksor-migrate-underivable` names the one
+thing it cannot know — a title, a description, a `generated.at`, or the actor
+behind a takedown it found in a database — and tells you the flag or the edit
+that supplies it. Two you will meet often:
+
+- **A record that declares `database:`** refuses until `KSOR_DB_URL` is
+  exported, because denials living only in that database would be republished by
+  a migration that never read them. Export it, or remove `database:` if the
+  record no longer has one.
+- **`approved` documents become `draft`** unless `--approve-by <actor>` says who
+  approves them in the same act. Approval is a human act and a migration is not
+  a human.
+
+## After it applies
+
+`pnpm build` regenerates every index and rewrites `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
+predicate must be re-measured with `ksor calibrate`, because a floor measured
+against a different predicate is a declared-but-uncalibrated floor and the door
+will refuse every search until it is replaced.

package/package.json

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