@panaversity/ksor 0.0.9 → 0.0.11

package/CHANGELOG.md

@@ -1,5 +1,271 @@
 # @panaversity/ksor
 
+## 0.0.11
+
+### Patch Changes
+
+- 0a0dd27: A record describes itself on the surface agents discover it through
+
+  `/.well-known/mcp/server.json` carried one hard-coded sentence — "The <name>
+  Knowledge System of Record: governed markdown served with citations and honest
+  abstention." — byte-identical in every ksor record ever scaffolded. An agent
+  choosing between records in a registry learned nothing from any of them, which
+  is the opposite of what that document exists for.
+
+  The description now comes from the record's own prose: its display title and the
+  first real sentence of `instance.md`, which is what the intake interview writes.
+  A record whose owner has not described it yet SAYS so rather than borrowing a
+  confident sentence it has not earned — the same answer the MCP door already
+  gives an agent that connects, so the two surfaces do not disagree about whether
+  this record knows what it is.
+
+  The scaffold's opening paragraphs are authoring guidance, not scope, so the
+  template is detected across the whole body rather than paragraph by paragraph:
+  publishing instructions-to-the-author as a description would be worse than
+  admitting there is none.
+
+- 0fe759d: Three defects found by auditing 0.0.10 against a live record
+
+  **A repeated `sslmode` was read the wrong end.** `pinnedTlsDsn` took the FIRST
+  value of a repeated parameter; `pg` takes the LAST. So on
+  `?sslmode=require&sslmode=disable` — whose effective mode is `disable` — the pin
+  saw a weak mode, collapsed the duplicates into one `verify-full`, turned TLS on,
+  and printed "TLS verified" at an operator whose DSN ended in `disable`. The
+  direction was safe; silently overruling an explicit opt-out and then misreporting
+  it was not. All three TLS functions now read the mode the driver will use.
+
+  The same sweep asserted the larger worry the pin creates — that re-serializing a
+  connection string could alter a credential. Seventeen DSNs with the passwords
+  people actually paste (raw `@`, spaces, `%`, `+`, brackets, non-ASCII,
+  percent-encoded separators) are now checked field by field against `pg`'s own
+  resolved view: everything the driver derives is byte-identical, and so is the
+  TLS decision.
+
+  **The outline's `position` disclosed documents an audience may not see.** It was
+  the rank in the whole record, so a public caller received 1, 3, 4 — a gap exactly
+  where an internal sibling sat, telling them something exists and roughly where.
+  The same row's `child_count` was already computed over visible children only, so
+  one response object disagreed with itself. `position` is now the rank among the
+  siblings the caller can see, computed as a window over the filtered set so it
+  stays correct across pages and at every depth, and both it and `depth` say what
+  they are in the tool schema.
+
+  **`ksor serve` now says when the record has no identity yet.** The MCP door
+  already refused to pass an unedited `instance.md` to agents as instructions —
+  it substitutes a plain statement that the scope is unstated — but the operator
+  starting the server was told nothing, so a record serving with no declared
+  identity looked exactly like one that had been described. It is a boot line now,
+  beside the abstention posture: both answer "how much should I trust this".
+
+- f5cd885: The bearer door's key line joins the boot block instead of interrupting it
+
+  In bearer mode the line naming where the signing keys were discovered printed
+  before the aligned posture block and in a different shape, so it read as a stray
+  log line rather than as part of what the server was telling you about itself. It
+  is a `keys` row in the block now, under `auth`, resolved at boot exactly as
+  before.
+
+- 5f30b5f: The site build no longer fails when two evaluations of the record staging overlap
+
+  The scaffold stages a per-audience copy of the record before the site build
+  reads it, removing the previous stage first. `rmSync(..., { force: true })`
+  suppresses ENOENT but retries nothing: Node retries EBUSY / EMFILE / ENFILE /
+  ENOTEMPTY / EPERM only when `maxRetries` is set, and it defaults to zero. The
+  bundler evaluates the source config more than once when it wants it in more than
+  one place, so one run could remove the stage while another was still copying
+  into it — surfacing as `ENOTEMPTY` and failing the entire site build (seen once
+  in CI, 2026-08-21).
+
+  The removal now asks for those retries. Losing that race is safe: the stage is a
+  deterministic function of the record and the denylist, so redoing it produces
+  the same bytes.
+
+  Three claims in the scaffold's `AGENTS.md` that recent releases made false are
+  also corrected: `--actor` no longer "defaults to the operating user" (it is
+  required, and there is no default by design); the signing keys are discovered
+  from the SSO's own metadata rather than fetched from Better Auth's path; and the
+  `order:` key now drives the MCP `outline` tool alongside the sidebar and
+  `llms.txt`, which is what "one order drives every surface" was always supposed
+  to mean.
+
+- 4a1c154: The shrink guard guards `ksor ingest --flip` again — it had stopped
+
+  `.env.example` documents `KSOR_MAX_SHRINK` as "a corpus that shrinks by more
+  than this FRACTION refuses to flip". In 0.0.10 it did not. Deleting eight of ten
+  documents and running `ksor ingest --flip` published the two that were left,
+  silently, exit 0.
+
+  The cause was the fix that stopped a refused ingest from publishing. That moved
+  the flip out of `buildGeneration` and into the command, so the governance gate
+  could run against the new generation BEFORE it became the active one — and the
+  shrink check, which lived inside the build's flip branch, was stepped straight
+  over. The library test that covers the guard stayed green throughout, because it
+  drives `buildGeneration` directly with `flip: true`, which is no longer the path
+  the CLI takes.
+
+  There is now one answer to "may this generation be activated" — `flipRefusal` —
+  and both flip paths ask it, in the same transaction as the flip itself. The new
+  test drives the command rather than the library, so a guard that only one of two
+  paths performs fails the tier that proves it.
+
+  Verified against a live record: a 10 → 2 node build now names all eight removed
+  documents, refuses with exit 1, and leaves the previous generation serving.
+
+## 0.0.10
+
+### Patch Changes
+
+- c07a5db: `ksor calibrate` states what its measurement is worth, not just its result
+
+  The default door synthesizes in-corpus questions by asking a model to write one
+  FROM each sampled passage, then scores those questions against the corpus that
+  contains the passage. They share vocabulary a reader's question will not, so the
+  in-corpus distribution sits higher than real traffic will and the separation the
+  run reports is an UPPER BOUND. The `--queries-file` door carried a caveat about
+  its own distribution; the default door — the biased one — carried none.
+
+  Found live: a real record calibrated this way reported min in-corpus 0.682
+  against max out-of-corpus 0.580 and recommended `vector_floor: 0.631`. Questions
+  the record demonstrably answers then scored 0.530 to 0.606 — every one below the
+  recommended floor. Pasting it would have made the record abstain on questions
+  whose answers it had just cited, which is the failure abstention exists to
+  prevent, arrived at from the other side.
+
+  The block now carries that caveat, and prints the one number it always left the
+  reader to work out: the separation margin, with the probe counts behind it. A
+  margin of 0.054 over six in-corpus and four out-of-corpus probes is a different
+  claim from the same margin over sixty, and both figures were already on the
+  report without ever reaching the page. The mathematics and the recommended value
+  are unchanged.
+
+  It also names the generation it measured. With nothing pinned — the ordinary
+  case, calibrating what is being served — the report carried no generation at
+  all, so the provenance comment beside a pasted floor read `on generation unknown
+(no generation pinned)`. A floor is a threshold inside ONE generation's embedding
+  space, and the query that counts the chunks had already resolved which one.
+
+  `runCalibration` had no test of any kind; it has one now, against real Postgres.
+
+- d00f3a2: The signing keys are discovered, not guessed — any standards-compliant SSO now works.
+
+  `KSOR_SSO_URL` is documented as "the AS base", and the verifier appended one
+  vendor's layout to it (`/api/auth/jwks`, Better Auth's). Auth0, Okta, Entra,
+  Keycloak, Cognito and Google all publish elsewhere, so every one of them failed
+  the key fetch — which is classified transient, so the door booted clean and
+  returned 503 to every request with nothing naming the cause. The only posture an
+  operator could actually reach was `KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1`: the one
+  key we handed people was the one that props the door open.
+
+  `jwks_uri` is now read from the SSO's own metadata document — RFC 8414 first,
+  then OpenID Discovery — with `KSOR_JWKS_URL` kept as an explicit override, and
+  the vendor path kept as a last resort that reports itself as a guess. Where the
+  keys came from is stated on the boot line.
+
+  Verified against three real providers: Google (RFC 8414, cross-origin
+  `jwks_uri`), GitHub Actions OIDC, and Entra — whose issuer carries a path,
+  the case a naive `${sso}/.well-known/…` gets wrong.
+
+  Discovery never refuses to boot: an unreachable AS falls back and says so.
+
+- 9062088: A loopback authorization server's keys are reachable again.
+
+  JWKS discovery refused a cleartext `jwks_uri`, which is right for a network AS
+  and wrong for a local one: a dev authorization server on loopback advertises
+  `http://127.0.0.1:…/jwks`, the resolver refused it, the vendor guess was used
+  instead, and every request returned 503. `assertHttpUrl` already exempts
+  loopback for the SSO base for exactly this reason; the resolver now does too.
+  Cleartext to any non-loopback host is still refused.
+
+  Found by writing the first test that boots the gateway in bearer mode.
+
+- 995ec48: A governance act names its actor; the tool no longer guesses one.
+
+  `ksor takedown --actor` fell back to `$USER` / `$USERNAME` / `"operator"`, so a
+  ledger row read `runner` under CI and `root` in a container — a self-asserted
+  string wearing a schema, indistinguishable from a person who was never there.
+  `retrieval_log.actor` is `NOT NULL` with the comment "NO default: unset errors
+  loudly", and the fallback is precisely what stopped it erroring.
+
+  Denying or revoking now REFUSES without `--actor`, before the DSN is resolved:
+  a missing actor is an argument error (exit 1), not an environment one. The
+  read-only modes — `--list`, `--ledger`, `--export` — write no ledger row and
+  need nothing.
+
+- 41b0c38: Reading order is one rule again: the MCP door now reads `order:`
+
+  `order:` is the only ordering key a record may declare — it is in the governed
+  frontmatter set the format checker closes, and the checker's own remedy for a
+  stray `meta.json` says so. The MCP door never read it. The tree adapter was
+  converted from the predecessor, whose ordering keys were Docusaurus's
+  `position:` / `sidebar_position:`, neither of which a compliant record may
+  declare — so `outline` reported the record's structure in filename order and
+  called it the reading order, while the website honoured `order:`. On a
+  curriculum, where reading order IS the content, an agent asking "what do I read
+  first" got a different answer from the two surfaces.
+
+  Four smaller disagreements went with it, each now a row in a shared decision
+  table: unordered documents sorted at 10 000 rather than after everything;
+  fractional orders were truncated; ties compared `example.md` against
+  `example-two.md`, where `.` sorts after `-`, reversing ordinary pairs; and one
+  side folded case while the other did not.
+
+  The rule now lives in one file, copied into the scaffold and asserted
+  byte-identical, with `ORDER_CASES` run against BOTH surfaces — so a surface that
+  drifts fails on the row it broke.
+
+- 41b0c38: `ksor serve` reports its own posture instead of forwarding other people's warnings
+
+  Booting printed four alarming paragraphs at an operator who had done nothing
+  wrong: the driver's multi-line `SECURITY WARNING` about `sslmode` aliases, ksor's
+  own three-line restatement of the same thing, and the MCP SDK's note about a
+  `responseMode` ksor chose deliberately.
+
+  The driver's warning is correct and its remedy is one word, so ksor now applies
+  it: a remote `sslmode=require|prefer|verify-ca` is rewritten to `verify-full`
+  before the connection is made. The connection is unchanged today — pg 8 was
+  already resolving all three to full verification, which is the entire content of
+  its warning — and it can no longer be silently downgraded by a driver upgrade.
+  The SDK's note describes a recorded decision, not a defect, and is suppressed by
+  exact message so that anything else it says still reaches the operator.
+
+  What is left is the record's posture, aligned and in ksor's own voice, with the
+  two lines that decide whether to trust what happens next saying what they mean:
+  auth `DISABLED` now names the bind it is survivable on, and an absent abstention
+  floor says out-of-corpus questions will be answered rather than refused.
+
+- bea7d80: `read` names every section it will accept, not just the top-level ones
+
+  `read` resolves a `heading` three ways: a full heading path, any prefix of one,
+  and a section's last segment when that segment is unique in the document. The
+  error for a section it could not find listed only the TOP-LEVEL segments — a
+  strict subset of its own vocabulary — so it reported real, reachable sections as
+  absent. Found live: a nested section was refused by name and served on the next
+  call under the same name.
+
+  The error now lists the full heading paths (the form that always resolves and
+  never collides), states the unique-last-segment shorthand rather than doubling
+  the list to enumerate it, and counts the tail past twenty instead of printing an
+  unbounded list. The `heading` input and the `sections` output now describe the
+  same vocabulary in the tool schema, where an agent reads it before making the
+  call rather than after failing one.
+
+- 4631268: Correct every remaining document that said `pnpm serve` publishes.
+
+  `serve` was `pnpm schema && pnpm grant && pnpm ingest && ksor serve` and is now
+  `ksor serve` alone. Three adopter-facing places still described the old chain:
+  the scaffolded `instance.md`'s own comment ("copy .env.example to .env, then run
+  `pnpm serve`"), the scaffold README's file table ("the agent surface: schema →
+  grant → ingest → serve"), and AGENTS.md's runbook ("`pnpm serve` is the only
+  command this rung needs"). Following any of them serves an empty record.
+
+  All three now say the same thing the CLI does: `pnpm provision` once,
+  `pnpm refresh` to publish, `pnpm serve` to serve — and why publishing is
+  separate, since a restart or an autoscaling event must not republish a record.
+
+  A test now asserts the CLAIM rather than the command. The existing guard could
+  not catch this: it checks that a named command exists, and `pnpm serve` does
+  exist — what was wrong was the sentence attached to it.
+
 ## 0.0.9
 
 ### Patch Changes