@panaversity/ksor 0.0.53 → 0.0.55

package/CHANGELOG.md

@@ -1,5 +1,333 @@
 # @panaversity/ksor
 
+## 0.0.55
+
+### Patch Changes
+
+- 4ecf549: Test infrastructure only — nothing an adopter installs behaves differently.
+
+  The behavioural evals scored a missing `top_cosine` as `-1`. When a provider
+  rate-limits, the read plane degrades to keyword-only by design, so searches
+  answer with no score — and the assertions then compared sentinels, reporting a
+  vendor outage as "the abstention floor is broken". Four CI failures in a day
+  read that way before anyone looked past the assertion. A missing score now
+  refuses, naming the cause, and never invents the number that is absent.
+
+- e476197: Fix the hello-world tutorial, which could not be completed as written.
+
+  Three defects, all found by walking the published 0.0.54 rather than by reading:
+
+  - Step 3's document declared `type: Policy`. `Policy` is a reserved type, so the
+    record demands `sources` — `ksor build`, `npm run check` and the dev server all
+    refused it, and steps 4 through 10 were unreachable. It is now `type: Document`,
+    the type the profile promises never to reserve, with a note on why and on what
+    an agent should do when it reaches for a reserved one.
+  - Step 1 scaffolds with `npx`, which emits an **npm** project, and every command
+    after it said `pnpm`. On that project `pnpm install && pnpm dev` fails with
+    `sh: next: command not found`. All sixteen commands are npm's now, and the step
+    that explains manager detection says which one the rest of the tutorial speaks.
+  - The captured outputs had been trimmed after capture, in a document whose second
+    paragraph promises they were "pasted as it appeared": `ksor serve`'s boot report
+    was missing the `trust` line it has always printed, the build outputs were
+    missing their timestamp, `source:` and `wrote` lines, and the port-conflict
+    refusal was quoted offering `pnpm serve` where it says `ksor serve`.
+
+  The walk also surfaced that `ksor init` leaves a repo with no commits, so every
+  reader's first build prints `source: unspecified`. Rather than hide it, the
+  tutorial now shows it and folds `git commit` into the approval step — which is
+  where provenance belongs anyway, and which lets the second build print a real
+  commit sha.
+
+  The tutorial also said `.mcp.json`'s "first is Neon's" and named the second
+  server nowhere, and said nothing about the Neon server acting on the whole Neon
+  account. Both are fixed here for the tutorial; the emitted scaffold's copies of
+  the same two defects are fixed separately.
+
+  Only the tutorial and the test that pins its prompts changed; nothing an adopter
+  installs behaves differently.
+
+- ae49524: Stop a spent OpenAI balance from quarantining content and flipping a generation,
+  and name the right variable when a provider key is missing.
+
+  **The serious one.** `insufficient_quota` — OpenAI's answer to an exhausted
+  balance, which arrives as 429 like an ordinary rate limit — was classified
+  non-retryable, correctly, because no amount of waiting adds credit. But
+  "non-retryable" is what the ingest drain reads as **poison chunk**: it
+  binary-splits the batch down to singletons and marks each `failed`. A spent
+  balance arrives on _every_ chunk, so a run walked the queue quarantining
+  everything it touched; if the failed fraction stayed under
+  `MAX_FAILED_FRACTION` (2%), `generationReady` admitted it and the generation
+  **flipped** — publishing a record in which exactly the passages the owner had
+  just edited were unsearchable, `ksor ingest` exit 0, the billing reason visible
+  only in `chunks.embed_error`. The same event on Gemini aborts the run, so
+  switching provider silently changed what a spent quota does.
+
+  The drain now has three answers instead of two: retryable (abort, chunks stay
+  pending), **fatal** (abort the same way, but without spending five backoffs
+  first — the account is what is wrong, not the passage), and everything else
+  (binary-split to the poison chunk). `isFatal` is optional on `EmbeddingProvider`,
+  so a provider that cannot tell keeps the old two-kind behaviour and Gemini's
+  path is unchanged.
+
+  **The missing-key refusal names the variable.** `ksor serve` on an
+  `embedding.provider: openai` record said `embedding provider "openai" needs an
+API key and none was supplied` and stopped — while `ksor serve --help`,
+  `env.example` and `docs/deploying.md` all named `GEMINI_API_KEY`, which that
+  door does not read. The registry row already held `keyEnv`; it now reaches the
+  operator (`— set OPENAI_API_KEY`), and all three documents describe the choice
+  instead of one vendor.
+
+  **`ksor calibrate`'s Gemini requirement is stated rather than papered over.**
+  Question synthesis is Gemini-only today, so a record embedding with
+  `OPENAI_API_KEY` is still refused for a Google key when calibrating through the
+  synthesized door. That gap is now said plainly in the refusal and in
+  `docs/ingesting.md`, which taught calibration without mentioning it. The
+  `--queries-file` door avoids it entirely.
+
+  **The OpenAI live test announces itself.** It is gated on `OPENAI_API_KEY`, no
+  workflow supplied one, and a false `describe.runIf` contributes nothing to a run
+  — so the suite its own header calls "the tripwire for vendor drift" was absent
+  from CI and reported as absent by nobody. It now prints `skipped — set
+OPENAI_API_KEY`, the way Gemini's does, and CI passes the secret so the tripwire
+  arms the moment one is added.
+
+  Found by an adversarial review of this week's commits.
+
+- ff99eb5: Hash `.ksor/people.yaml` into `build_id`, so the two surfaces of one build
+  cannot publish different provenance.
+
+  The phone book added in 0.0.53 rewrites the actor printed on every Owner,
+  Approved, Withdrawn and Trust row — `displayActor` replaces `human:contractor-a`
+  with "Human: Jane Doe, VP Compliance", and the identifier does not appear on the
+  page at all. It was hashed by nothing. `.ksor/governance.yaml` and
+  `.ksor/takedowns.yaml` are both in `build_id`; this one was left out, on the
+  stated reasoning that including it would refuse the next site build after a
+  spelling correction.
+
+  That is the trade critical rule 1 forbids, and the consequence was reachable
+  without doing anything unusual: edit a name, `pnpm check` stays green,
+  `ksor build` emits a byte-identical lock, and the deployed page publishes an
+  approver the `/md/` twin stamped with that same `build_id` contradicts. An
+  auditor reconciling the page against the lock finds nothing wrong, because the
+  string they are auditing was never covered by it.
+
+  Now: `people_sha256` joins `policy_sha256` and `ledger_sha256` in the lock and
+  in `build_id`; `.ksor/people.yaml` joins the inputs that move `source_commit`;
+  and the site's staleness gate compares it like the other three, so an edit the
+  lock never saw refuses with `ksor-lock-stale` naming the file. Refusing until
+  `ksor build` is re-run is the behaviour, not a regression — it is what every
+  other published byte already does.
+
+  Two things found alongside it, in the same file:
+
+  - `people.ts` claimed "duplicate keys are refused by the parser rather than
+    resolved by whichever came last". They were not. `uniqueKeys: true` makes the
+    parser RECORD a duplicate; `toJS()` still resolves last-wins, and nothing read
+    the errors — so two entries for one actor published the second person's name
+    on the first person's approval, the precise collision the map replaced a name
+    derivation to avoid. A duplicate now drops the whole book, and identifiers are
+    published instead.
+  - The rule lived behind a module that reads `instance.md` on import, so it could
+    only be tested by building a record on disk — which is why it shipped asserted
+    by a comment. It is now a leaf, `lib/people-rule.ts`, with the shipped
+    function under test.
+
+  **Upgrading:** a lock written before this refuses with `ksor-lock-invalid`
+  naming `people_sha256`; run `ksor build` and commit the lock it writes.
+
+  Found by an adversarial review of this week's commits.
+
+- b45d477: Say what the scaffold's `.mcp.json` attaches to an adopter's coding agent, and
+  stop the README telling them to destroy it.
+
+  `ksor init` emits `.mcp.json` with two servers. The emitted README and AGENTS.md
+  both said "the first is Neon" and named the second nowhere — so
+  `agentfactory-system-of-record`, a Panaversity-operated endpoint, was wired into
+  every adopter's coding agent with no emitted document mentioning it. `.mcp.json`
+  attaches servers to the agent that OPERATES the record; a server nobody
+  documented is a capability nobody reviewed.
+
+  Both are now named, with what each is and that either may be deleted. The second
+  is described as what it is: a read-only example record that is **not** the
+  adopter's and that nothing in the project depends on.
+
+  The Neon step also said only that the server exists. It acts on the Neon
+  _account_ — an agent holding it can create and delete projects and branches — so
+  the README and AGENTS.md now say that before handing over a prompt that runs
+  against real infrastructure, and point at Neon's own documentation for the
+  scopes rather than paraphrasing them.
+
+  And the "Test the door with an actual agent" section told the adopter to _write_
+  `.mcp.json` with a file containing only `test-record` — overwriting the Neon
+  entry the same README depends on two sections earlier — and then closed with
+  "Delete `.mcp.json`, or keep it". It now shows the entry to **add**, and says not
+  to delete the file.
+
+  A guard derived from `mcp.json` itself asserts every server key appears in both
+  emitted documents, so adding a server and saying nothing fails on the server
+  that was added. Mutation-tested: unnaming the second server turns both red.
+
+  Found by an adversarial review of this week's commits. Whether the scaffold
+  should ship a second, vendor-operated MCP record at all is an owner question and
+  is untouched here.
+
+- 5283084: Test infrastructure only — nothing an adopter installs behaves differently.
+
+  A skill's `description` is its trigger and nothing measured it (#30). Every
+  prompt the hello world tells a reader to say is now matched to a shipped skill
+  or recorded as needing none, and each skill's trigger phrases are pinned — so
+  narrowing one, the failure mode where a skill silently stops firing, goes red
+  naming the phrase. The model-scored half of that issue is untouched.
+
+## 0.0.54
+
+### Patch Changes
+
+- 3f55e91: `ksor calibrate` names the free-tier path when a quota refuses it, and the
+  calibration text model moves to `gemini-3.7-flash`.
+
+  Walked on a real free-tier key: embedding is free of charge and a first corpus
+  embeds fine (23 chunks, 0 failed), but the DEFAULT calibration door writes one
+  probe question per sampled passage with an LLM — and the free tier allows five
+  generations a minute. So the documented way to turn on the product's headline
+  feature failed, surfacing the vendor's sentence and nothing else.
+
+  Two quotas reach that code and they need opposite answers: the generation cap is
+  a wall no wait clears (the remedy is `--queries-file`, the zero-LLM door), and
+  the embedding cap is a per-minute window (the remedy is to wait, and the usual
+  cause is an ingest immediately before). Both are now named, with why. A 429 this
+  does not recognise is re-thrown untouched — an invented remedy is worse than the
+  vendor's own message.
+
+  `docs/ingesting.md` documents the zero-LLM door where the reader meets the
+  command, including how to choose the questions: the floor is set by the weakest
+  one, so a vague question drags it down and a question the record cannot answer
+  invalidates the measurement.
+
+  The text model moves `gemini-2.5-flash` → `gemini-3.7-flash`. Cheap, unlike the
+  embedding model: it only writes probe questions, so nothing stored is
+  re-computed and no floor is invalidated — and the door is recorded beside every
+  number, which is what stops two measurements being compared as one experiment.
+
+  **And calibration now embeds on the patient retry.** It used the READ plane's
+  door, which never retries a 429 — correct for a live search, which should
+  degrade to keyword-only in under a second rather than stall a reader behind
+  backoff, and wrong for a measurement nobody is waiting on. So a free-tier key
+  that rate-limited mid-run refused the whole calibration. The intent stays
+  `query` (a floor must be measured through the label the door searches with);
+  only the retry policy moves, to the one `isRetryable`'s own comment describes
+  for batch work. Calibration's text generation already took that path, so this
+  was the two halves of one act disagreeing.
+
+- dd6371b: Two things: a false claim removed from a shipped page, and the scaffold gains
+  `.mcp.json`.
+
+  **The false claim.** `docs/deploying.md` told adopters "The MCP surface already
+  applies the audience scope **per request**", under the heading of the very
+  requirement it does not meet. It does not: `content-gateway/src/compose.ts`
+  reads `KSOR_AUDIENCE` from the environment once at boot into a per-process
+  viewer, and the request path never touches it — `docs/authorization.md` says so
+  plainly ("Any caller holding a valid token gets the whole record") and
+  `specs/ksor/serve/spec.md` names per-request visibility filtering as out of
+  scope. A reader who believed the page would point every caller at one door and
+  serve them the restricted half. The page now says what the door does — one
+  viewer per door, so one process per audience — and separates the audit it does
+  give (a `retrieval_log` row naming the verified caller) from the authorization
+  it does not. A docs-truth assertion now fails on the claim itself, not merely on
+  a command that no longer exists.
+
+  **`.mcp.json`.** The scaffold's closed root set gains one member: the MCP
+  servers a coding agent may reach from the project. It ships with Neon's, which
+  turns the step the tool could never do for an adopter — provision a Postgres,
+  enable pgvector, produce a connection string — into four real tool calls
+  (`create_project`, `run_sql`, `create_branch`, `get_connection_string`) and one
+  sentence to the agent. The scaffold's README and AGENTS.md carry that sentence,
+  and both now say plainly which step no agent can do at any price: the embedding
+  API key, which no vendor mints over a protocol. Committed rather than ignored,
+  because both entries authenticate interactively and the file carries no secret —
+  stated, because pasting an API key into it would change that.
+
+- eebd777: OpenAI joins Gemini behind the embedding seam, and the wiring stops naming one
+  vendor (issue #25).
+
+  The seam was already vendor-neutral in shape — `EmbeddingProvider`, the
+  framework's normalization and degeneracy checks, and an embedding space
+  identified by `modelId` + column width and never by the vendor. What was
+  Gemini-bound was the WIRING: `GEMINI_API_KEY` was spelled into three composition
+  roots, so a second provider could not obtain a key even though the registry
+  would happily build it. Each registry row now names its own key variable, and
+  the roots ask, exactly as `instance.md` names the DSN variable rather than
+  hardcoding it.
+
+  `provider: openai` with `model: text-embedding-3-small` and `dim: 1536` reads
+  `OPENAI_API_KEY`. Over `fetch`, no SDK — the same call decision 12's 2026-08-22
+  revision made for Gemini, and for the same reason.
+
+  Two things a live call surfaced that a stub would not. Response items carry
+  their own `index` and the vendor does not promise array order, so they are
+  sorted before the framework pairs them positionally — a shuffled response is the
+  same count, the same width and all finite, so every downstream check passes
+  while every passage carries another's vector. And an exhausted balance arrives
+  as **429**, the same status as a rate limit: it is now read from the vendor's
+  `error.type` and never retried, because five exponential backoffs do not add
+  credit.
+
+  Switching provider is a re-embed of the whole corpus and a re-measured
+  `vector_floor`. A different provider is a different embedding space, and the
+  invariant against copying a calibrated constant applies across vendors with more
+  force, not less.
+
+  Verified live against the real API on a funded key: 1536-dimension vectors, a
+  paraphrase at cosine 0.812 against an unrelated sentence at 0.058, and the two
+  intents agreeing to 0.9997 — which is the symmetry that makes the empty task
+  labels correct. Then through the whole plane: a real record ingested to Postgres
+  under `embedding_model = text-embedding-3-small`, 23 chunks, 0 failed, stored at
+  the declared width of 1536 and L2-normalized as the framework promises.
+
+  One more defect the live call found: `buildShippedProvider` handed EVERY
+  provider Gemini's task labels from global config, so an OpenAI run logged its
+  space as `text-embedding-3-small/d1536/RETRIEVAL_DOCUMENT` — a label that vendor
+  has no concept of and never received. The labels moved onto the registry row,
+  where a vendor's shape belongs.
+
+- eb54871: The npm page shows what the product does, on the first screen.
+
+  It asserted the headline behaviour — a cited answer, an honest refusal — and
+  demonstrated it nowhere. A reader had no way to tell a real mechanism from a
+  prompt instruction, which is exactly the skepticism this product exists to
+  answer. It now shows three things, all of them real output: the admitted count
+  moving when a human approves a draft, the `provenance` and `governance` a search
+  hit carries, and an abstention envelope. It also links the hello world.
+
+  Nothing was added to the tarball; this is the README npm renders.
+
+- 6e5ff3e: Repo documentation and a test only — nothing an adopter installs changes.
+
+  `docs/status.md` named 0.0.42 while the published package was 0.0.53. Authority
+  rule 3 makes that file the only authority on what is built, and it is the first
+  thing an evaluator's coding agent reads. It is current now, and a docs-truth
+  assertion holds it equal to `packages/ksor/package.json` so a Version PR cannot
+  bump one without the other. It also records that the full kernel walk was re-run
+  against 0.0.53 — it had last run against 0.0.18, thirty-five releases earlier.
+
+- ed947c1: The deploy runbook stops ruling out the one step Vercel calls required.
+
+  `docs/deploying.md` said the silent-404 failure "does not depend on the
+  Application Preset". Vercel's own guide says the opposite: a project builds as
+  services only when the preset is `Services` AND `vercel.json` carries a
+  `services` key, and "if either is missing, Vercel falls back to its default
+  framework detection and ignores your services configuration" — which is that
+  failure exactly, and no file in the repository can set a project setting.
+
+  One measurement of ours disagrees with that guide and is recorded rather than
+  reconciled: two projects read back from the API, one `Services` and one `Other`,
+  both built and served. Both facts are real; guessing between them is what
+  produced the sentence that steered adopters away from the fix.
+
+  The scaffold's runbook now sets the preset at step 2, and ends with the three
+  curls that tell a live deployment from a Ready-and-404 one — `/mcp` answering
+  405 is the door refusing a GET, which is how you know it is routed at all.
+
 ## 0.0.53
 
 ### Patch Changes

package/README.md

@@ -16,6 +16,36 @@ pnpm install
 pnpm dev        # the site, live at http://localhost:3000
 ```
 
+Then write a document and publish it:
+
+```console
+$ pnpm exec ksor build
+ksor build: 6 document(s), 5 admitted to a machine surface
+```
+
+**Six documents, five admitted.** The one you just wrote is a `draft`, so it
+reaches nothing an AI agent reads — not `llms.txt`, not the markdown twins —
+until a human approves it. Approve it and the count moves. That is the whole
+product, and it costs nothing: no database, no API key, no account.
+
+Climb one rung and an agent asks the record a question. The answer carries
+where it came from:
+
+```json
+"provenance": { "stable_id": "knowledge/refund-policy", "generation": 1 },
+"governance": { "status": "stable", "approval": { "by": "human:you" } }
+```
+
+…and a question the record does not cover is declined rather than guessed at:
+
+```json
+{ "ok": false, "abstained": true, "gate": { "floor": 0.622 } }
+```
+
+**[Hello world](https://github.com/panaversity/ksor/blob/main/docs/tutorials/00-hello-world.md)**
+walks all of that in about fifteen minutes. Every command and output in it was
+run and pasted as it appeared — including the ones above.
+
 One command emits a complete governed project: the record (`knowledge/`,
 plain CommonMark), a working documentation site with hot reload, offline
 search and `llms.txt`, adopter CI, a dependency-free format checker

package/dist/checker/check-main.mjs

@@ -10892,7 +10892,7 @@ var require_public_api = /* @__PURE__ */ __commonJSMin(((exports) => {
 	exports.stringify = stringify;
 }));
 //#endregion
-//#region ../content/dist/check-DNWlQuBg.mjs
+//#region ../content/dist/check-6fB_kR4G.mjs
 var import_dist = (/* @__PURE__ */ __commonJSMin(((exports) => {
 	var composer = require_composer();
 	var Document = require_Document();
@@ -12150,6 +12150,7 @@ function changedFields(before, after) {
 const CONTROL_FILES = [
 	"instance.md",
 	".ksor/governance.yaml",
+	".ksor/people.yaml",
 	".ksor/takedowns.yaml"
 ];
 /** Files the operating system writes behind the author's back: ignored, never reported. */
@@ -13714,7 +13715,7 @@ function checkAgainstPolicy(concept, policy, refusals) {
 	}
 }
 //#endregion
-//#region ../content/dist/record-DnMnZelb.mjs
+//#region ../content/dist/record-Cxw0SUG3.mjs
 const hex64 = string().regex(/^[0-9a-f]{64}$/, "a sha256 hex digest");
 const viewerList = array(string().min(1));
 const lockSchema = object({
@@ -13732,6 +13733,7 @@ const lockSchema = object({
 	drafts: _enum(["hidden", "shown"]),
 	instance_sha256: hex64,
 	policy_sha256: hex64,
+	people_sha256: hex64,
 	ledger_sha256: hex64,
 	ledger_entries: array(object({
 		id: string().min(1),
@@ -13928,6 +13930,7 @@ const INPUTS = [
 	"knowledge",
 	"instance.md",
 	".ksor/governance.yaml",
+	".ksor/people.yaml",
 	".ksor/takedowns.yaml"
 ];
 function gitFacts(root) {