@panaversity/ksor 0.0.51 → 0.0.52

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @panaversity/ksor
 
+## 0.0.52
+
+### Patch Changes
+
+- 1e60b9d: The site prints natural names for the actors a record cites, where the record
+  declares them.
+
+  A governed page led with a slug — "Owner · human:bashiraziz" — on every owner,
+  trust, approval and withdrawal line. `.ksor/people.yaml` maps an actor to the
+  name a page should print, and the site substitutes it at render time. An actor
+  with no entry renders exactly as stored: no splitting, no camelCase guessing,
+  no derivation. A display name is the one thing in a governance line that cannot
+  be computed — `bashiraziz` is equally "Bashir Aziz" and "Bashira Ziz" — so the
+  owner is its only source.
+
+  A MAP keyed by the whole identifier, not a list of names a handle is derived
+  from. The derivation could only ever match a handle that IS somebody's squashed
+  full name, so `human:ciso`, `human:audit-lead` and `human:mjs` — most of the
+  actors in a real record — had no expressible name at all; and it collided, since
+  two different people can squash to one handle.
+
+  Deliberately NOT part of `.ksor/governance.yaml`. That file is the root of
+  authority: its key set is closed so nothing can sit 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 the
+  next site build as `ksor-lock-stale`. Appearing in `people.yaml` confers no
+  authority; it only changes what is printed, and nothing cross-checks the two
+  lists, because a person who leaves the authority list is still the recorded
+  approver of everything they approved.
+
+- f23cddc: `ksor calibrate --check` reports whether a declared abstention floor is still
+  holding, from the record's own traffic.
+
+  A floor is measured once and the record then grows. As it does, questions that
+  used to be out-of-corpus start scoring above a fixed number, so the record
+  answers what it used to refuse — no error, nothing logged, and the same
+  `gate: { floor: … }` in every envelope. AGENTS.md forbids copying a calibrated
+  constant between corpora; the same reasoning applies across time within one
+  corpus, and nothing enforced it (#182).
+
+  It needs no telemetry and no new dependency: every search already leaves an
+  audit row carrying the gate's own signal, on both sides of the gate, so this is
+  one indexed query — no provider key, no embedding call, no LLM. It reports the
+  abstain rate, the percentiles of answered top scores, and how many answers
+  landed within 0.01 of the floor (the size of the decision in this project's own
+  gold, not a threshold somebody picked).
+
+  **It never fails a run**, and that is the design rather than a limitation. A
+  stale floor wants re-measuring; failing a build for one would make the shortest
+  way out deleting `vector_floor` — turning the abstention gate off entirely to
+  clear the error, which is the escape `build/lifecycle-notice.ts` refuses to
+  create for a passed review date. It is also a monitor and not a measurement: it
+  can say a floor has gone permissive against real traffic, never that it is too
+  strict for questions nobody asked, and it says so rather than reporting a
+  healthy-looking nothing on a record no one queries.
+
+- a403e19: the served envelope now discloses when a §7 audit row could not be written (issue #150)
+
 ## 0.0.51
 
 ### 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-D8HlLys2-Ca8OnwLn.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-Ck1l_Sgs-B-_wMYLB.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-DMCMO8ye.mjs
+//#region ../content-gateway/dist/main-mQtKKwyj.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-BNxmBRjs.mjs
+//#region ../content/dist/commands-Cb63_n_A.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a
@@ -9743,6 +9743,122 @@ function pct(fraction) {
 	return `${(fraction * 100).toFixed(0)}%`;
 }
 /**
+* How close to the floor an answer has to be to count as marginal.
+*
+* 0.01 is not a tuned threshold — it is the size of the decision in this
+* record's own gold, quoted rather than invented: in-corpus at 0.730 / 0.671
+* against a scope-adjacent near-miss at 0.683 (`evals/behavioural.db.test.ts`),
+* so a hundredth of a cosine is the smallest difference that has ever changed
+* an answer here. An answer inside that band is one the floor barely admitted.
+*/
+const MARGIN_BAND = .01;
+/** Nearest-rank percentile over a sorted ascending list. */
+function percentile(sorted, q) {
+	if (sorted.length === 0) return null;
+	return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(q * sorted.length) - 1))] ?? null;
+}
+/**
+* Characterise the traffic against the declared floor.
+*
+* Two numbers carry the verdict, and both are reported whatever it says,
+* because the verdict is a reading aid and the numbers are the evidence:
+*
+*   the ABSTAIN RATE       — a gate that has stopped refusing anything is
+*                            either serving a record that now covers its
+*                            traffic, or a floor that has fallen behind it.
+*   the MARGINAL SHARE     — answers the floor barely admitted. These are the
+*                            ones that would flip if the number moved at all,
+*                            so a large share means the answer set turns on a
+*                            constant measured against a smaller corpus.
+*
+* `watch` is deliberately not called "stale". This cannot tell the two causes
+* apart — only a re-measurement can — so it names what it saw and says what to
+* run.
+*/
+function driftReport(floor, samples) {
+	const answeredScores = samples.filter((s) => !s.abstained).map((s) => s.topCosine).sort((a, b) => a - b);
+	const abstained = samples.length - answeredScores.length;
+	const marginal = answeredScores.filter((score) => score - floor <= .010000001).length;
+	const marginalShare = answeredScores.length === 0 ? 0 : marginal / answeredScores.length;
+	const abstainRate = samples.length === 0 ? 0 : abstained / samples.length;
+	const base = {
+		floor,
+		samples: samples.length,
+		abstained,
+		answered: answeredScores.length,
+		marginal,
+		marginalShare,
+		abstainRate,
+		p05: percentile(answeredScores, .05),
+		p50: percentile(answeredScores, .5),
+		p95: percentile(answeredScores, .95)
+	};
+	if (samples.length < 30) return {
+		...base,
+		verdict: "no-data",
+		why: `only ${samples.length} logged search(es) — too few to characterise; this reports traffic, so a record nobody queries says nothing rather than looking healthy`
+	};
+	if (marginalShare >= .2) return {
+		...base,
+		verdict: "watch",
+		why: `${marginal} of ${answeredScores.length} answers scored within ${MARGIN_BAND} of the floor — the answer set turns on this exact number`
+	};
+	if (abstained === 0) return {
+		...base,
+		verdict: "watch",
+		why: `the gate refused none of ${samples.length} searches — either the record now covers its traffic, or the floor has fallen behind it, and only a re-measurement tells them apart`
+	};
+	return {
+		...base,
+		verdict: "steady",
+		why: `${abstained} of ${samples.length} searches were refused, and ${marginal} answer(s) sat within ${MARGIN_BAND} of the floor`
+	};
+}
+/** The report as the CLI prints it. Numbers first; the verdict is a reading aid. */
+function renderDrift(report, window) {
+	const pct = (n) => `${(n * 100).toFixed(1)}%`;
+	const score = (n) => n === null ? "—" : n.toFixed(3);
+	const lines = [
+		`floor drift — ${window}`,
+		`  declared vector_floor  ${report.floor.toFixed(3)}`,
+		`  searches logged        ${report.samples}  (${report.answered} answered, ${report.abstained} abstained)`,
+		`  abstain rate           ${pct(report.abstainRate)}`,
+		`  answered top score     p05 ${score(report.p05)}  p50 ${score(report.p50)}  p95 ${score(report.p95)}`,
+		`  within ${MARGIN_BAND} of floor    ${report.marginal}  (${pct(report.marginalShare)} of answers)`,
+		`  verdict                ${report.verdict.toUpperCase()} — ${report.why}`
+	];
+	if (report.verdict === "watch") lines.push("", "  This is traffic, not a calibration: it cannot tell a record that grew", "  from a floor that fell behind. Re-measure to find out —", "    ksor calibrate --instance instance.md --queries-file <your questions>", "  and paste the floor it prints if it differs from the declared one.");
+	return `${lines.join("\n")}\n`;
+}
+/**
+* The logged searches for this corpus, newest `days` days.
+*
+* Only rows carrying a NUMERIC `top_cosine`: an audit row shed under
+* saturation, or one written before that detail existed, is ABSENT rather than
+* counted as a zero — a shed row is a gap in the evidence, and scoring it as
+* zero would drag every statistic here toward a number nobody measured, in the
+* direction that makes a floor look safer than it is.
+*
+* Scoped by CORPUS as well as tenant, for the reason `readLedger` records: a
+* tenant serving two corpora would otherwise measure one record's floor
+* against the other's traffic. Read through `runAuditRead` — the serving role
+* has no SELECT on this table at all, deliberately, and widening that to read
+* a monitor would trade an audit guarantee for a convenience.
+*/
+const DRIFT_SQL = `
+SELECT (detail->>'top_cosine')::float8 AS top_cosine,
+       action = 'search_abstained'     AS abstained
+  FROM retrieval_log
+ WHERE tenant_id = $1
+   AND corpus_id = $2
+   AND action IN ('similarity_searched','search_abstained')
+   AND created_at > now() - ($3 || ' days')::interval
+   AND jsonb_typeof(detail->'top_cosine') = 'number'
+ ORDER BY created_at DESC
+ LIMIT $4`;
+/** How many rows one check reads at most — a bound, so a busy record cannot make this expensive. */
+const DRIFT_LIMIT = 5e3;
+/**
 * Out-of-corpus probes scoring at or above the weakest in-corpus question,
 * worst first — the ones that decided the verdict. Empty when the measurement
 * separated, because then nothing held it open.
@@ -9939,9 +10055,14 @@ Usage:
       when the tree is in a repository; --source-commit overrides it.
   ksor calibrate --instance PATH [--queries-file PATH] [--ooc-file PATH]
                  [--generation N] [--per-node N] [--min-chars N]
+  ksor calibrate --instance PATH --check [--days N]
       Measure the abstention floor for this corpus and report it. A
       measurement that does not separate in-corpus from out-of-corpus prints
       the diagnosis and NO floor: there is no safe number to paste.
+      --check reads the record's OWN logged searches instead and reports how
+      the declared floor is holding against them — no provider key, no
+      embedding call, no LLM. A monitor, never a gate: it says what to
+      re-measure and always exits 0.
   ksor grant --instance PATH [--revoke]
       Authorize ingest for the instance's tenant (the row row-level security
       requires), or withdraw it. Idempotent; reports the state it established.
@@ -10292,13 +10413,19 @@ async function calibrateCommand(args) {
 			"ooc-file": { type: "string" },
 			generation: { type: "string" },
 			"per-node": { type: "string" },
-			"min-chars": { type: "string" }
+			"min-chars": { type: "string" },
+			check: {
+				type: "boolean",
+				default: false
+			},
+			days: { type: "string" }
 		}
 	});
 	const instance = loadInstance(values.instance);
 	if (typeof instance === "number") return instance;
 	const dsn = resolveDsn(instance);
 	if (typeof dsn === "number") return dsn;
+	if (values.check === true) return await checkFloorDrift(instance, dsn, values.days);
 	const provider = composeProvider(instance);
 	if (typeof provider === "number") return provider;
 	let queries = null;
@@ -10327,6 +10454,47 @@ async function calibrateCommand(args) {
 	if (advice !== null) process.stdout.write(advice);
 	return 0;
 }
+/** How many days of traffic one --check reads. Bounded so a busy record cannot make it expensive. */
+const DRIFT_DEFAULT_DAYS = 30;
+/**
+* `ksor calibrate --check` — is the declared floor still holding?
+*
+* Reads the record's OWN logged searches (`retrieval_log.detail.top_cosine`,
+* which is written on both sides of the gate) instead of measuring the corpus
+* again, so it needs no provider key, no embedding call and no LLM. That is
+* why it runs BEFORE the provider is composed: a check that demanded a vendor
+* key would be one an adopter never puts in CI.
+*
+* ALWAYS EXITS 0. A stale floor wants re-measuring; failing a run for one would
+* make the shortest way out deleting `vector_floor`, which turns the abstention
+* gate off entirely to clear the error — the same escape `lifecycle-notice.ts`
+* refuses to create for a passed review date.
+*/
+async function checkFloorDrift(instance, dsn, daysArg) {
+	const floor = instance.abstain.vectorFloor;
+	if (floor === null) {
+		process.stdout.write("floor drift: no floor declared — this record's gate is OFF, so out-of-corpus questions are answered rather than refused.\n  fix: run `ksor calibrate` and paste the retrieval block it prints\n");
+		return 0;
+	}
+	if (floor === "uncalibrated") {
+		process.stdout.write("floor drift: vector_floor is `uncalibrated` — the door refuses every search until a measured number replaces it.\n  fix: run `ksor calibrate` and paste the retrieval block it prints\n");
+		return 0;
+	}
+	const days = daysArg === void 0 ? DRIFT_DEFAULT_DAYS : intFlag("--days", daysArg);
+	const samples = (await withPool(dsn, (pool) => runAuditRead(pool, instance.tenantId, async (client) => {
+		return (await client.query(DRIFT_SQL, [
+			instance.tenantId,
+			instance.corpusId,
+			String(days),
+			DRIFT_LIMIT
+		])).rows;
+	}))).map((row) => ({
+		topCosine: row.top_cosine,
+		abstained: row.abstained
+	}));
+	process.stdout.write(renderDrift(driftReport(floor, samples), `last ${days} day(s)`));
+	return 0;
+}
 async function grantCommand(args) {
 	const { values } = parseArgs({
 		args,

package/dist/{gateway-api-D8HlLys2-Ca8OnwLn.mjs → gateway-api-Ck1l_Sgs-B-_wMYLB.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-D8HlLys2.mjs
+//#region ../content-gateway/dist/gateway-api-Ck1l_Sgs.mjs
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __require = /* #__PURE__ */ (() => createRequire(import.meta.url))();
 /**
@@ -10383,7 +10383,7 @@ async function search(ctx, query, k = 10) {
 	}
 	if (abstained) {
 		const generation = hits[0]?.generation;
-		await logRead(ctx.pool, {
+		const audited = await logRead(ctx.pool, {
 			tenantId: inst.tenantId,
 			corpusId: inst.corpusId,
 			actor,
@@ -10415,7 +10415,8 @@ async function search(ctx, query, k = 10) {
 			hits: [],
 			snapshot: generation === void 0 ? null : snapshotEnvelope(ctx, generation),
 			...kNote === void 0 ? {} : { k_note: kNote },
-			...degradedReason === void 0 ? {} : { degraded_reason: degradedReason }
+			...degradedReason === void 0 ? {} : { degraded_reason: degradedReason },
+			...audited ? {} : { audit: "degraded" }
 		};
 	}
 	const budget = Math.min(SEARCH_BUDGET_CHARS, inst.maximumResponseCharacters);
@@ -10447,7 +10448,7 @@ async function search(ctx, query, k = 10) {
 		});
 	}
 	const generation = hits[0]?.generation ?? 0;
-	await logRead(ctx.pool, {
+	const audited = await logRead(ctx.pool, {
 		tenantId: inst.tenantId,
 		corpusId: inst.corpusId,
 		actor,
@@ -10480,7 +10481,8 @@ async function search(ctx, query, k = 10) {
 		...truncated === 0 ? {} : { note: `${truncated} lower-ranked hit(s) dropped by the response budget — narrow the query or use the read tool` },
 		...advisory ? { content_advisory: CONTENT_ADVISORY } : {},
 		...kNote === void 0 ? {} : { k_note: kNote },
-		...degradedReason === void 0 ? {} : { degraded_reason: degradedReason }
+		...degradedReason === void 0 ? {} : { degraded_reason: degradedReason },
+		...audited ? {} : { audit: "degraded" }
 	};
 }
 const DOCUMENT_BUDGET_CHARS = 28e4;
@@ -10580,7 +10582,7 @@ async function readDocument(ctx, slug, options = {}) {
 	const textChars = codePointLength(text);
 	const totalChars = scoped.reduce((n, c) => n + codePointLength(c.content), 0);
 	const sections = [...new Set(scoped.map((c) => c.headingPath.split("/")[0] ?? "").filter((s) => s !== ""))];
-	await logRead(ctx.pool, {
+	const audited = await logRead(ctx.pool, {
 		tenantId: inst.tenantId,
 		corpusId: inst.corpusId,
 		actor,
@@ -10618,7 +10620,8 @@ async function readDocument(ctx, slug, options = {}) {
 			note: window.nextHeading === null ? "windowed — this is the last window (next is null)" : "windowed — continue with from_heading set to this response's next (it carries its own scope; do not also resend heading)"
 		} : {},
 		...instructionLike(text) || instructionLike(frontmatter ?? "") ? { content_advisory: CONTENT_ADVISORY } : {},
-		snapshot_status: refreshed ?? (pinned === null ? "unpinned" : "pinned")
+		snapshot_status: refreshed ?? (pinned === null ? "unpinned" : "pinned"),
+		...audited ? {} : { audit: "degraded" }
 	};
 }
 async function outlineDocuments(ctx, options = {}) {
@@ -10642,7 +10645,7 @@ async function outlineDocuments(ctx, options = {}) {
 	}), servingScope(ctx));
 	const has_more = rows.length > limit;
 	if (has_more) rows.length = limit;
-	await logRead(ctx.pool, {
+	const audited = await logRead(ctx.pool, {
 		tenantId: inst.tenantId,
 		corpusId: inst.corpusId,
 		actor,
@@ -10659,6 +10662,7 @@ async function outlineDocuments(ctx, options = {}) {
 	});
 	return {
 		...rows.some((r) => instructionLike(r.title) || instructionLike(r.headingPath ?? "")) ? { content_advisory: CONTENT_ADVISORY } : {},
+		...audited ? {} : { audit: "degraded" },
 		has_more,
 		limit,
 		offset,
@@ -10820,7 +10824,8 @@ const SEARCH_OUTPUT = z.object({
 	note: z.string().optional(),
 	k_note: z.string().optional(),
 	degraded_reason: z.string().optional().describe("Why retrieval was degraded. \"embed_unavailable\" = the provider is down and this record gates on a cosine floor, so nothing could be served. \"embed_unavailable_keyword_only\" = the provider is down and this record declares no floor, so these hits come from keyword search alone and rank differently."),
-	content_advisory: z.string().optional()
+	content_advisory: z.string().optional(),
+	audit: z.enum(["degraded"]).optional().describe("Present only when the §7 audit row for this act could not be written (shed under saturation). The answer is unaffected; absent means the row landed normally.")
 });
 const OUTLINE_OUTPUT = z.object({
 	nodes: z.array(z.object({
@@ -10838,7 +10843,8 @@ const OUTLINE_OUTPUT = z.object({
 	limit: z.number().int().describe("Rows this page could hold."),
 	offset: z.number().int().describe("Rows skipped to produce this page."),
 	next_offset: z.number().int().nullable().describe("Pass as offset to get the next page; null when this is the last one."),
-	has_more: z.boolean().describe("True when rows were cut at limit — the record has more, this list is partial.")
+	has_more: z.boolean().describe("True when rows were cut at limit — the record has more, this list is partial."),
+	audit: z.enum(["degraded"]).optional().describe("Present only when the §7 audit row for this act could not be written (shed under saturation). The answer is unaffected; absent means the row landed normally.")
 });
 const READ_OUTPUT = z.object({
 	slug: z.string(),
@@ -10856,7 +10862,8 @@ const READ_OUTPUT = z.object({
 	est_tokens: z.number().optional(),
 	total_est_tokens: z.number().optional(),
 	note: z.string().optional(),
-	content_advisory: z.string().optional()
+	content_advisory: z.string().optional(),
+	audit: z.enum(["degraded"]).optional().describe("Present only when the §7 audit row for this act could not be written (shed under saturation). The answer is unaffected; absent means the row landed normally.")
 });
 function toolError(error) {
 	return {

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-D8HlLys2-Ca8OnwLn.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-Ck1l_Sgs-B-_wMYLB.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/ingesting.md

@@ -230,6 +230,53 @@ belongs on the in-corpus side — moving it separates the measurement. Sometimes
 it is a genuine near-miss the corpus cannot separate, and then the floor
 correctly stays uncalibrated.
 
+### The floor goes stale as the record grows
+
+A floor is measured once, against the corpus as it stood that day, and then the
+record grows. As it does, questions that used to be out-of-corpus start scoring
+above a fixed number — so the record answers what it used to refuse, with no
+error, nothing logged, and the same `gate: { floor: … }` in every envelope. The
+guarantee weakens in silence, in the dangerous direction.
+
+You do not need telemetry to see it. Every search already leaves a row carrying
+the gate's own signal, on both sides of it, so the check reads the record's own
+traffic:
+
+```sh
+pnpm exec ksor calibrate --instance instance.md --check
+```
+
+No provider key, no embedding call, no LLM — one indexed query:
+
+```
+floor drift — last 30 day(s)
+  declared vector_floor  0.550
+  searches logged        112  (100 answered, 12 abstained)
+  abstain rate           10.7%
+  answered top score     p05 0.552  p50 0.810  p95 0.890
+  within 0.01 of floor    40  (40.0% of answers)
+  verdict                WATCH — 40 of 100 answers scored within 0.01 of the floor
+```
+
+Two numbers carry it. The **abstain rate**: a gate that has stopped refusing
+anything is either serving a record that now covers its traffic, or a floor that
+has fallen behind it. And the **share of answers within 0.01 of the floor** —
+the ones that would flip if the number moved at all, 0.01 being the size of the
+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.
+- **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
+  strict.
+- **It is not a calibration.** When it says WATCH, re-run `ksor calibrate` —
+  that is the measurement, and it is the thing that produces a new number.
+
 ## Withdrawing a document
 
 A takedown is a committed ledger entry FIRST and a database row second, written

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/package.json

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

package/templates/scaffold/system/site/components/governance.tsx

@@ -4,6 +4,8 @@ import { DocumentActions } from "@/components/document-actions";
 import { Clock } from "lucide-react";
 import type { ReactElement } from "react";
 
+import { displayActor } from "@/lib/actor-display";
+import { peopleBook } from "@/lib/people";
 import {
   badgeAddsToStatus,
   badgeText,
@@ -257,7 +259,7 @@ export function GovernanceMeta({
             <Chip text={trust.tier} />
             {trust.by === null ? null : (
               <span className="font-normal text-fd-muted-foreground">
-                {trust.by}
+                {displayActor(trust.by, peopleBook())}
                 {trust.at === null ? null : <> · {day(trust.at)}</>}
               </span>
             )}
@@ -286,7 +288,7 @@ export function GovernanceMeta({
           Links keep full strength: `Replaces` points at the document this one
           superseded, and that is an action rather than a fact. */}
       <dl className="mt-2.5 flex flex-wrap items-baseline gap-x-8 gap-y-2.5 empty:mt-0 [&_a]:text-fd-foreground [&_dd]:font-normal [&_dd]:text-fd-muted-foreground">
-        {owner === null ? null : <Fact label="Owner">{owner}</Fact>}
+        {owner === null ? null : <Fact label="Owner">{displayActor(owner, peopleBook())}</Fact>}
         {/* Who let this into the record. `ksor.approval` is what makes a `stable`
           document stable at all (record spec §2.2), so a page that showed the
           word and not the signature would be publishing the claim without its
@@ -294,7 +296,7 @@ export function GovernanceMeta({
         {approval === null ? null : (
           <Fact label="Approved">
             <>
-              {approval.by} · {day(approval.at)}
+              {displayActor(approval.by, peopleBook())} · {day(approval.at)}
             </>
           </Fact>
         )}
@@ -307,7 +309,7 @@ export function GovernanceMeta({
         {deprecated === null ? null : (
           <Fact label="Withdrawn">
             <>
-              {deprecated.by} · {day(deprecated.at)}
+              {displayActor(deprecated.by, peopleBook())} · {day(deprecated.at)}
             </>
           </Fact>
         )}

package/templates/scaffold/system/site/lib/actor-display.ts

@@ -0,0 +1,53 @@
+/**
+ * Turn a stored actor identifier into the string the page prints.
+ *
+ * KSoR stores actors as `human:<handle>`, `process:<id>`, `team:<id>` or
+ * `<producer>/<version>`. Those forms are right for machines — the checker
+ * parses them, `.ksor/governance.yaml` lists actors by them, and the whole
+ * authority model depends on them — but a public-facing page shouldn't lead
+ * with a slug. This module bridges the two.
+ *
+ * ONE-WAY RULE. If `.ksor/people.yaml` maps this exact identifier to a name, we
+ * print `Human: Bashir Aziz`. If it does not, we print the identifier unchanged
+ * (`human:bashiraziz`, `ksor-starter/0.0.47`). No convention-based splitting,
+ * no camelCase / kebab-case guessing, and no derivation of a handle from a
+ * name: an owner is the only source of a display name.
+ *
+ * A producer actor (`<producer>/<version>`) has no `<kind>:` prefix and no
+ * natural name to look up, so it passes through unchanged — which is correct:
+ * a tool that approved a document should be named plainly, not humanised.
+ *
+ * NO IMPORTS: a leaf, like `lifecycle-rule.ts`. The phone book is handed in by
+ * the caller rather than reached for, so the rule can be exercised without a
+ * record on disk — and so nothing pulls a filesystem read in behind it.
+ */
+
+/** The prefixes KSoR's actor grammar defines, in the case the site prints. */
+const KIND_LABELS: Record<string, string> = {
+  human: "Human",
+  process: "Process",
+  team: "Team",
+};
+
+/**
+ * The display form of an actor. An actor that does not appear in
+ * `.ksor/people.yaml` renders exactly as stored, so nothing regresses on a
+ * record that has declared no names — which is every record until an owner
+ * says otherwise.
+ */
+export function displayActor(actor: string, people: ReadonlyMap<string, string>): string {
+  const colonAt = actor.indexOf(":");
+  if (colonAt === -1) {
+    // No `<kind>:` prefix — this is a producer like `ksor-starter/0.0.47`.
+    // Print it unchanged: humanising a tool's identifier would misread.
+    return actor;
+  }
+  // Looked up by the WHOLE identifier, not the bare handle: `human:ops` and
+  // `team:ops` are different actors, and a phone book keyed on `ops` would
+  // print one of them under the other's name.
+  const name = people.get(actor) ?? null;
+  if (name === null) return actor;
+  const kind = actor.slice(0, colonAt);
+  const kindLabel = KIND_LABELS[kind] ?? kind.charAt(0).toUpperCase() + kind.slice(1);
+  return `${kindLabel}: ${name}`;
+}

package/templates/scaffold/system/site/lib/people.ts

@@ -0,0 +1,82 @@
+/**
+ * Natural names for the actors this record cites — the site's phone book.
+ *
+ * A MAP keyed by the actor as stored (`human:bashiraziz`, `team:legal-ops`),
+ * not a list of names a handle is derived from. The derivation was the defect:
+ * `name.replace(/\s+/g, "").toLowerCase()` can only ever match a handle that
+ * IS somebody's squashed full name, so `human:ciso`, `human:audit-lead` and
+ * `human:mjs` — most of the actors in a real record — had no expressible name
+ * at all. It also collided: "Bashir Aziz" and "Bashira Ziz" both derive
+ * `bashiraziz`, which would print one person's name on the other's governance
+ * act. A map has neither problem, and duplicate keys are refused by the parser
+ * rather than resolved by whichever came last.
+ *
+ * ONE-WAY. The identifier is what the record stores, cites and checks against
+ * the policy; this is only what a page prints. Nothing reads a name back into
+ * an actor, and no authority follows from appearing here — which is why this is
+ * a file of its own and not a block in `.ksor/governance.yaml`: that file is
+ * the root of authority, its key set is closed on purpose, and its digest is
+ * hashed into `build.lock.json`, so correcting the spelling of someone's name
+ * there would refuse the next site build as `ksor-lock-stale`.
+ *
+ * Read from the project root rather than the process's cwd: `next build` runs
+ * in `system/site`, so a cwd-relative path found nothing and the feature was
+ * inert in exactly the builds that publish.
+ *
+ * Read AT USE and memoised, not at module load. A module-load `readFileSync`
+ * makes importing this module a filesystem act — it runs wherever the module is
+ * pulled in, including from a test that wants nothing but the display rule, and
+ * it fixes the answer before anything has had a chance to say where the record
+ * is. That is the same defect the env-tuning knobs had (#149/#194), one file
+ * over.
+ */
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import { parseAllDocuments } from "yaml";
+
+import { projectRoot } from "./shared";
+
+const PEOPLE_YAML = path.join(projectRoot, ".ksor", "people.yaml");
+
+function loadPeople(): ReadonlyMap<string, string> {
+  let text: string;
+  try {
+    text = readFileSync(PEOPLE_YAML, "utf8");
+  } catch {
+    // Optional: its absence means "no natural names declared".
+    return new Map();
+  }
+  try {
+    const docs = parseAllDocuments(text.replace(/^/, ""), {
+      schema: "core",
+      uniqueKeys: true,
+      logLevel: "silent",
+    });
+    const value: unknown = docs[0]?.toJS();
+    if (typeof value !== "object" || value === null) return new Map();
+    const table = (value as { people?: unknown }).people;
+    if (typeof table !== "object" || table === null || Array.isArray(table)) return new Map();
+    const out = new Map<string, string>();
+    for (const [actor, name] of Object.entries(table as Record<string, unknown>)) {
+      // A blank value is an entry someone started and left; printing "" would
+      // erase the identifier rather than replace it.
+      if (typeof name === "string" && name.trim() !== "") out.set(actor.trim(), name.trim());
+    }
+    return out;
+  } catch {
+    return new Map();
+  }
+}
+
+let cached: ReadonlyMap<string, string> | null = null;
+
+/**
+ * What this record has declared. Memoised per process: the file is authored,
+ * not runtime state, and a static build renders many pages from one read.
+ */
+export function peopleBook(): ReadonlyMap<string, string> {
+  cached ??= loadPeople();
+  return cached;
+}