@panaversity/ksor 0.0.50 → 0.0.51

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # @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

package/dist/cli.mjs

@@ -13059,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,
@@ -13073,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/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.50",
+  "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",