@panaversity/ksor 0.0.50 → 0.0.52

package/CHANGELOG.md

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

@@ -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,
@@ -13059,9 +13227,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 +13242,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-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/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/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