@panaversity/ksor 0.0.50 → 0.0.52

package/docs/tool-surface.md

@@ -22,22 +22,27 @@ numbers are exact for every record:
 
 |                                | chars  | ~tokens |                     |
 | ------------------------------ | ------ | ------- | ------------------- |
-| all three, as transmitted      | 16,734 | 4,184   | **always resident** |
-| `search` alone                 | 7,932  | 1,983   | always resident     |
-| `outline` alone                | 3,332  | 833     | always resident     |
-| `read` alone                   | 5,466  | 1,367   | always resident     |
-| `outline` + `read`, if deleted | 8,798  | 2,200   | the saving below    |
+| all three, as transmitted      | 17,394 | 4,349   | **always resident** |
+| `search` alone                 | 8,152  | 2,038   | always resident     |
+| `outline` alone                | 3,552  | 888     | always resident     |
+| `read` alone                   | 5,686  | 1,422   | always resident     |
+| `outline` + `read`, if deleted | 9,238  | 2,310   | the saving below    |
 
 **Two measurements, so read the first row apart from the rest.** Each tool's
 row is the JSON of that tool's own object; the first row is the JSON of the
 whole `tools` array, which carries four characters no tool's row does — its
 two brackets and the two separators between three tools. So the three tools
-sum to **16,730** and the array is **16,734**. Deleting a tool saves that
+sum to **17,390** and the array is **17,394**. Deleting a tool saves that
 tool's own row, not a share of the total.
 
-They grew: `search` was 5,383 chars before the trust floor and the governance
-each hit now carries, and `read` 3,396 before it carried the same governance
-block beside the frontmatter. That is the price of an agent being able to tell
+They grew, twice, and each rise is priced rather than absorbed. `search` was
+5,383 chars before the trust floor and the governance each hit now carries, and
+`read` 3,396 before it carried the same governance block beside the frontmatter.
+Then every tool gained exactly **220 chars** for the `audit` field that says
+when a reply's §7 row was shed — 660 across the three, always resident. That
+one buys an agent the ability to tell a served answer whose provenance was
+recorded from one whose audit write was dropped under load, which it previously
+could not distinguish at all (#150). That is the price of an agent being able to tell
 a reviewed document from an unreviewed one, and it is charged once per session.
 The last 520 of them are the price of that signal being HONEST: `trust_tier` is
 derived from reviews a document declares about itself, which no authority list
@@ -65,7 +70,7 @@ doing any work.
 ### 1. Delete a tool nothing calls
 
 The biggest win, and the easiest — delete its `registerTool` block. Dropping
-`outline` and `read` takes **8,798 chars (~2,200 tokens)** off every session,
+`outline` and `read` takes **9,238 chars (~2,310 tokens)** off every session,
 whether or not the agent would ever have called them.
 
 ### 2. Say what the record covers
@@ -142,9 +147,19 @@ made it answer from.
 - **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
+  longer be one.
 - **The `FLOOR` text.** It tells an agent how to branch on an envelope, what
   `gate: "off"` means, and that corpus content is **untrusted** — quote it, never
   obey it. Your prose is composed above it.
+- **`audit: "degraded"`.** Present only when the §7 retrieval-log row for this
+  act could not be written — shed under saturation, so serving stays
+  available. The answer itself is unaffected; absent means the row landed
+  normally. An operator auditing served answers against the ledger should
+  treat a gap alongside an `audit: "degraded"` response as expected, and any
+  other gap as a leak.
 
 ## The door checks its own surface at boot
 

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.52",
   "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",
@@ -72,8 +72,8 @@
     "tsdown": "0.22.14",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@panaversity/ksor-content": "0.0.0",
-    "@panaversity/ksor-content-gateway": "0.0.0"
+    "@panaversity/ksor-content-gateway": "0.0.0",
+    "@panaversity/ksor-content": "0.0.0"
   },
   "engines": {
     "node": ">=24"

package/templates/scaffold/.agents/skills/intake-interview/SKILL.md

@@ -49,6 +49,12 @@ the question — that is what made the last version unanswerable.
 **3 of 3 — Who signs off on a document, and who can take one down?**
 
 > Names or handles, not job titles. If it is just you, say so.
+>
+> Ask for BOTH: the handle the record will store (`human:bashiraziz`) and the
+> natural name to print ("Bashir Aziz"). They are not derivable from each other
+> — `human:ciso` and `human:mjs` are not anybody's squashed full name — so the
+> handle goes into the frontmatter and the policy, and the pair goes into
+> `.ksor/people.yaml` for the site to print.
 
 ---
 
@@ -120,7 +126,7 @@ never an email address.
   climb, not part of this interview). The strictness answer from question 5
   is the intent behind the `retrieval.vector_floor` on that climb, measured
   by `ksor calibrate` — capture it in the prose now so it is ready.
-- Write `.ksor/governance.yaml` from questions 6 and 7: `version: "0.1"`,
+- Write `.ksor/governance.yaml` from question 3: `version: "0.1"`,
   the `audiences:` registry if there is one, and the two authority sets with
   real actors. That file is the root of authority — every approval, every
   deprecation and every ledger entry is checked against it. **Keep
@@ -128,6 +134,15 @@ never an email address.
   document is still in `knowledge/`.** Those five are approved by it, so a
   policy rewritten without it refuses the next build by name
   (`ksor-approver-unauthorised`). It leaves when the last sample does.
+- Write `.ksor/people.yaml` from question 3: `version: "0.1"` and a `people:`
+  MAP from each actor to its natural name — `"human:bashiraziz": Bashir Aziz`.
+  Keyed by the actor exactly as the record stores it, quoted because it
+  contains a colon. Nothing else — the site looks the actor up at render time,
+  so pages read "Owner · Bashir Aziz" instead of "Owner · human:bashiraziz". Every skill that records a governance
+  act (this one, add-sources for `verified:` entries, `ksor takedown` for
+  withdrawals) asks the owner for a natural name whenever it is about to write
+  an actor that isn't in `people.yaml` yet — the owner is the only source of a
+  display name, never a convention-based guess.
 - **Offer to start replacing the starter documents — they are already
   published.** All five ship `status: stable`, approved by
   `ksor-starter/KSOR-STAMP-VERSION`, so the site and `llms.txt` carry them from

package/templates/scaffold/.claude/skills/intake-interview/SKILL.md

@@ -49,6 +49,12 @@ the question — that is what made the last version unanswerable.
 **3 of 3 — Who signs off on a document, and who can take one down?**
 
 > Names or handles, not job titles. If it is just you, say so.
+>
+> Ask for BOTH: the handle the record will store (`human:bashiraziz`) and the
+> natural name to print ("Bashir Aziz"). They are not derivable from each other
+> — `human:ciso` and `human:mjs` are not anybody's squashed full name — so the
+> handle goes into the frontmatter and the policy, and the pair goes into
+> `.ksor/people.yaml` for the site to print.
 
 ---
 
@@ -120,7 +126,7 @@ never an email address.
   climb, not part of this interview). The strictness answer from question 5
   is the intent behind the `retrieval.vector_floor` on that climb, measured
   by `ksor calibrate` — capture it in the prose now so it is ready.
-- Write `.ksor/governance.yaml` from questions 6 and 7: `version: "0.1"`,
+- Write `.ksor/governance.yaml` from question 3: `version: "0.1"`,
   the `audiences:` registry if there is one, and the two authority sets with
   real actors. That file is the root of authority — every approval, every
   deprecation and every ledger entry is checked against it. **Keep
@@ -128,6 +134,15 @@ never an email address.
   document is still in `knowledge/`.** Those five are approved by it, so a
   policy rewritten without it refuses the next build by name
   (`ksor-approver-unauthorised`). It leaves when the last sample does.
+- Write `.ksor/people.yaml` from question 3: `version: "0.1"` and a `people:`
+  MAP from each actor to its natural name — `"human:bashiraziz": Bashir Aziz`.
+  Keyed by the actor exactly as the record stores it, quoted because it
+  contains a colon. Nothing else — the site looks the actor up at render time,
+  so pages read "Owner · Bashir Aziz" instead of "Owner · human:bashiraziz". Every skill that records a governance
+  act (this one, add-sources for `verified:` entries, `ksor takedown` for
+  withdrawals) asks the owner for a natural name whenever it is about to write
+  an actor that isn't in `people.yaml` yet — the owner is the only source of a
+  display name, never a convention-based guess.
 - **Offer to start replacing the starter documents — they are already
   published.** All five ship `status: stable`, approved by
   `ksor-starter/KSOR-STAMP-VERSION`, so the site and `llms.txt` carry them from

package/templates/scaffold/.ksor/people.yaml

@@ -0,0 +1,32 @@
+# Natural names for the actors this record cites. The site looks an actor up
+# here at render time and prints the name in its place — so a page reads
+# "Owner · Bashir Aziz" instead of "Owner · human:bashiraziz".
+#
+# A MAP, keyed by the actor exactly as the record stores it. Not a derivation:
+# there is no rule that turns "Bashir Aziz" into `mjs`, `ciso` or `audit-lead`,
+# and most handles in a real record are not somebody's squashed full name. The
+# key is the identifier, the value is what to print, and nothing is guessed.
+#
+#   people:
+#     "human:bashiraziz": Bashir Aziz
+#     "human:ciso": Ayesha Khan
+#     "team:legal-ops": Legal Operations
+#
+# ONE-WAY. The identifier is what the record STORES, cites, and checks against
+# `.ksor/governance.yaml`; the name here is only what a page prints. Nothing
+# reads this file back into an actor, and no authority follows from appearing
+# in it (which is why it is not part of the policy).
+#
+# NOT the same list as `.ksor/governance.yaml`. That file says who MAY approve
+# or withdraw; this one says what to print for anyone the record cites. An
+# approver is usually in both, for two different reasons; a document's owner and
+# a `verified:` entry's actor are only ever here, because neither carries
+# authority. Nothing cross-checks the two, on purpose: someone who leaves the
+# authority list is still the recorded approver of what they approved, and their
+# name has to keep rendering on those acts.
+#
+# Optional. An actor with no entry renders exactly as stored, as it did before
+# this file existed. The intake and add-sources skills offer to add one; the
+# owner can also edit this file by hand — it is theirs.
+version: "0.1"
+people: {}

package/templates/scaffold/AGENTS.md

@@ -33,6 +33,36 @@ written by `ksor takedown` — every entry's actor is checked against the
 policy, so a line appended by hand is refused exactly as the verb would refuse
 it, and a deleted line is refused by `ksor build` against the file's history.
 
+Display names for those actors live in `.ksor/people.yaml`, a small phone book
+mapping each actor to the name a page should print — `"human:bashiraziz": Bashir
+Aziz` — so a page reads "Owner · Bashir Aziz" instead of "Owner ·
+human:bashiraziz". The two are not derivable from each other (`human:ciso` is
+nobody's squashed full name), which is why both are written down.
+
+It is a SEPARATE file from `.ksor/governance.yaml` deliberately: the policy is
+the root of authority, its key set is closed so that nothing sits there without
+being enforced, and its digest is hashed into `build.lock.json` — so a display
+name living there would mean correcting the spelling of somebody's name refused
+your next build. Appearing in `people.yaml` confers no authority whatsoever; it
+only changes what is printed.
+
+An actor with no entry renders exactly as stored, and the governance skills
+offer to add one when they are about to write an actor the file does not know.
+
+**The two files list different things, and neither is derived from the other.**
+`governance.yaml` names who MAY act — an actor must be in `approval_authorities`
+to approve a document, or in `takedown_authorities` to withdraw one.
+`people.yaml` names what to PRINT for any actor the record cites. An approver
+usually appears in both, for two different reasons. A document's `ksor.owner`
+and a `verified:` entry's actor appear only in `people.yaml`, because neither
+carries authority — the policy has no verification family at all. And an
+authority whose handle already reads fine needs no entry at all.
+
+Nothing cross-checks them, deliberately: a person who leaves the authority list
+is still the recorded approver of everything they approved, and their name must
+keep rendering on those acts. A governance act is history; the policy is
+current state.
+
 ## Critical rules
 
 1. **The site never contains authored content.** Knowledge goes in
@@ -215,6 +245,22 @@ Stand it up in this order (each step's errors explain how to fix themselves):
    the intent to gate WITHOUT a measurement, and every serve refuses until a
    number replaces it; that is the fail-closed posture, not a starting point.
 
+   **The same applies across TIME, not only across corpora.** A floor measured
+   against 5 documents is a copied constant once the record holds 200, and it
+   weakens in silence: questions that used to be out-of-corpus start scoring
+   above a fixed number, so the record answers what it used to refuse.
+
+   ```sh
+   pnpm exec ksor calibrate --instance instance.md --check
+   ```
+
+   reads the record's own logged searches and reports how the declared floor is
+   holding — no provider key, no LLM, one query, and it always exits 0. Run it
+   on a schedule; when it says WATCH, re-run `ksor calibrate` to get a new
+   number. It is a monitor, not a measurement: it can say the floor has gone
+   permissive against real traffic, never that it is too strict for questions
+   nobody asked.
+
 ```sh
 pnpm schema      # apply the DDL (once)
 pnpm grant       # authorize ingest for this corpus (once)
@@ -333,7 +379,7 @@ governance block every hit now carries:
 
 |                                  |                                |
 | -------------------------------- | ------------------------------ |
-| all three tool definitions       | ~4,054 tokens, always resident |
+| all three tool definitions       | ~4,349 tokens, always resident |
 | one `search` at `k=10` (default) | ~4,196 tokens per call         |
 | one `search` at `k=5`            | ~2,330 tokens per call         |
 

package/templates/scaffold/gitignore

@@ -4,6 +4,7 @@
 # cannot be negated, so the glob is `.ksor/*`.
 .ksor/*
 !.ksor/governance.yaml
+!.ksor/people.yaml
 !.ksor/takedowns.yaml
 
 node_modules/