@panaversity/ksor 0.0.9 → 0.0.10

package/package.json

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

package/templates/scaffold/AGENTS.md

@@ -147,19 +147,20 @@ Stand it up in this order (each step's errors explain how to fix themselves):
    `knowledge/`**: an applied schema reports "already applied", an existing
    grant reports "already granted", and ingest builds a fresh generation.
 
-   **`pnpm serve` is the only command this rung needs.** Run it the first
-   time, run it after editing `knowledge/`, run it to bring the server back —
-   it is always the right answer, so there is nothing to decide. Every step it
-   chains reports the state it found rather than failing: an applied schema
-   says "already applied", an existing grant says "already granted", and
-   unchanged chunks carry forward by content hash, so a rerun on an untouched
-   corpus makes **zero provider calls** (`embedded 0, carried N`).
-
-   A rerun on an unchanged record costs **nothing at all**: ingest compares the
-   corpus it just read against the generation already serving and, when they
-   are identical at the same commit, consumes no generation and writes no rows
-   ("unchanged — generation N already serves this corpus"). Edit a document and
-   the next run builds a generation for it, re-embedding only what changed.
+   **`pnpm refresh` after editing `knowledge/`; `pnpm serve` to bring the
+   server up.** Two commands, and the split is the point: serving must not
+   publish, or a restart, a crash-loop or an autoscaling event each republishes
+   your record. Everything is re-runnable and reports the state it found rather
+   than failing — an applied schema says "already applied", an existing grant
+   says "already granted".
+
+   A refresh on an unchanged record costs **nothing at all**: ingest compares
+   the corpus it just read against the generation already serving and, when
+   they are identical at the same commit, consumes no generation and writes no
+   rows ("unchanged — generation N already serves this corpus"). Edit a
+   document and the next refresh builds a generation for it, re-embedding only
+   what changed and carrying the rest forward by content hash — so an ordinary
+   edit makes a handful of provider calls, not a corpus-worth.
 
    Generations do accumulate as you edit. Reap the superseded ones when you
    think of it, or on a schedule:
@@ -169,10 +170,10 @@ Stand it up in this order (each step's errors explain how to fix themselves):
    ```
 
    The individual verbs (`pnpm schema`, `pnpm grant`, `pnpm ingest`,
-   `pnpm serve`) exist for pipelines and split duties — a deploy step that
-   ingests while a different process serves, or a DBA who holds the credentials
-   that authorize ingest. Reach for them when something else runs the steps;
-   not as a daily choice.
+   `pnpm gc`) are what `provision` and `refresh` are made of. Reach for them
+   when duties are split — a deploy step that ingests while a different process
+   serves, or a DBA who holds the credentials that authorize ingest — not as a
+   daily choice.
 
 4. **Turn the abstention gate on — deliberately, once it serves.** This is the
    step that makes "not in this corpus" a real answer, and it is measured, never

package/templates/scaffold/README.md

@@ -97,7 +97,7 @@ different coding agent's way of finding the same working contract.
 | `.gitattributes`                 | markdown is checked out byte-stable on every platform, so the same commit hashes the same everywhere.                                                                                                                            |
 | `.env.example`                   | the variables the served rung needs; copy to `.env` (gitignored) and fill in. |
 | `.gitignore`                     | keeps build output, `node_modules/`, and `.env` out of the record's history.                                                                                                                                                    |
-| `package.json`                   | the two surface commands — `pnpm dev` (the site) and `pnpm serve` (the agent surface: schema → grant → ingest → serve) — plus `pnpm build` / `pnpm check`, the pinned `@panaversity/ksor` tool, and the pnpm version this project pins.                                                |
+| `package.json`                   | the surface commands — `pnpm dev` (the site) and `pnpm provision` / `pnpm refresh` / `pnpm serve` (the agent surface: set up once, publish, then serve) — plus `pnpm build` / `pnpm check`, the pinned `@panaversity/ksor` tool, and the pnpm version this project pins.                                                |
 | `pnpm-workspace.yaml`            | where the workspace looks for code (`system/site`, plus reserved `system/gateways/*` and `system/packages/*`), and the supply-chain policy for installs.                                                                         |
 | `pnpm-lock.yaml`                 | the exact dependency versions — the reason two machines build the same site.                                                                                                                                                     |
 

package/templates/scaffold/env.example

@@ -20,11 +20,12 @@ GEMINI_API_KEY=
 #   KSOR_SSO_URL=https://your-sso.example.com
 #   KSOR_MCP_RESOURCE_URL=https://your-host.example.com/mcp
 #   KSOR_JWT_ALLOWED_AUDIENCES=https://your-host.example.com/mcp
-# The JWKS endpoint defaults to <KSOR_SSO_URL>/api/auth/jwks, which is Better
-# Auth's layout. EVERY other provider — Auth0, Okta, Entra, Keycloak, Cognito —
-# publishes its keys elsewhere, and a wrong JWKS URL fails as a TRANSIENT fetch
-# error, so every request 503s with nothing naming the cause. Say where the keys
-# are:
+# The signing keys are DISCOVERED from your SSO's own metadata document —
+# RFC 8414 (/.well-known/oauth-authorization-server), then OpenID Discovery
+# (/.well-known/openid-configuration) — so Auth0, Okta, Entra, Keycloak,
+# Cognito and Google all work unmodified. The boot line says which document
+# answered and where the keys came from.
+# Set this only to override discovery, or when your SSO publishes no metadata:
 #   KSOR_JWKS_URL=https://your-sso.example.com/.well-known/jwks.json
 # Serving a public bind with auth off additionally requires
 # KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1, which serves your whole record to anyone

package/templates/scaffold/instance.md

@@ -6,7 +6,10 @@ ksor:
   scaffolded: "KSOR-STAMP-VERSION"
 # The served MCP rung needs ONE required block: the NAME of the environment
 # variable holding your Postgres DSN — never the DSN itself. Uncomment it, copy
-# .env.example to .env, then run `pnpm serve`. Nothing else here is required:
+# .env.example to .env, then: `pnpm provision` once (schema + grant), then
+# `pnpm refresh` to PUBLISH the record, then `pnpm serve`. Serving does not
+# publish — that is deliberate, and skipping refresh serves nothing.
+# Nothing else here is required:
 # `embedding:` already defaults to Gemini at 1536 dimensions, and leaving
 # `retrieval:` out starts you with the abstention gate off and honest about it
 # (turn it on afterwards with `ksor calibrate`, once the record is serving).

package/templates/scaffold/system/site/lib/order-rule.ts

@@ -0,0 +1,107 @@
+/**
+ * Reading order — ONE rule, for the website and the MCP door alike.
+ *
+ * `order:` is the only ordering key an author may write: it is in the governed
+ * frontmatter set the format checker closes, and the checker's own remedy for a
+ * stray `meta.json` says so ("sidebar order is the `order` frontmatter key").
+ *
+ * The MCP door did not read it. The kernel's tree adapter was converted from
+ * the predecessor, where the ordering keys were Docusaurus's `position` /
+ * `sidebar_position` — neither of which a compliant record may declare, because
+ * the checker refuses them as unknown keys. So the two surfaces disagreed about
+ * the record's reading order for every corpus that ordered itself at all: the
+ * site honoured `order:` and the door fell back to filename order and called it
+ * the record's structure. On a curriculum, where reading order IS the content,
+ * an agent asking `outline` for "what do I read first" got the wrong answer
+ * (found live 2026-08-21, by an agent probing a real ingested record).
+ *
+ * That is decision 18's shape — one guarantee, two surfaces, two heads — so it
+ * gets decision 18's treatment: this file is the rule, `ORDER_CASES` is the
+ * decision table, and both surfaces are asserted against the same rows. The
+ * site cannot import the kernel, so this file is COPIED into the scaffold and
+ * the copy is asserted byte-identical rather than trusted.
+ *
+ * Four things the two surfaces disagreed about beyond the key name, each of
+ * which is a row in the table:
+ *
+ *   - the unordered sentinel. The kernel used 10_000, a real number, so
+ *     `order: 20000` sorted AFTER an unordered document in the door and BEFORE
+ *     it on the site. Unordered is not a large order; it is the absence of one.
+ *   - truncation. The kernel applied `Math.trunc`, collapsing 3.2 and 3.7 into
+ *     one position and re-sorting them by name; the site kept both.
+ *   - the tie key's extension. The kernel compared `example.md` against
+ *     `example-two.md` — where `-` (45) sorts before `.` (46) — while the site
+ *     compared the extensionless urls, where the shorter is a prefix and wins.
+ *     Two ordinary filenames, two different orders.
+ *   - case. The kernel lowercased the tie key and the site did not, so
+ *     `apple.md` and `Banana.md` came out in opposite orders.
+ *
+ * No imports: a leaf, so it is testable in isolation and safe to copy.
+ */
+
+/**
+ * A document that declares no usable `order:` sorts after every document that
+ * does. Infinity, not a large number — see above.
+ */
+export const UNORDERED: number = Number.POSITIVE_INFINITY;
+
+/**
+ * The `order:` frontmatter value as a sort key.
+ *
+ * A numeric string is accepted because YAML frontmatter is read by scanners
+ * here, not by a YAML library: `order: 3` and `order: "3"` both reach this as
+ * text on one surface and as a number on the other, and an author cannot be
+ * expected to know which. Anything that is not a finite number — a word, a
+ * boolean, an empty value — is NOT an order, and the document sorts unordered.
+ */
+export function orderValue(raw: unknown): number {
+  if (typeof raw === "number") return Number.isFinite(raw) ? raw : UNORDERED;
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (trimmed === "") return UNORDERED;
+    const parsed = Number(trimmed);
+    return Number.isFinite(parsed) ? parsed : UNORDERED;
+  }
+  return UNORDERED;
+}
+
+/**
+ * The tie key for one sibling: its name with a MARKDOWN extension removed,
+ * case PRESERVED. The extension comes off because the site compares routes,
+ * which never carry one, and `.` sorting after `-` silently reversed ordinary
+ * pairs. Only `.md`/`.mdx` come off — a directory named `v1.2` keeps its dot,
+ * because the site's route keeps it too. Case is preserved because the site
+ * compares urls, and the url is what a reader sees.
+ */
+export function tieKey(name: string): string {
+  return name.replace(/\.mdx?$/, "");
+}
+
+/** One sibling's place in its parent: what it declared, and how ties break. */
+export interface Sibling {
+  readonly order: number;
+  readonly tie: string;
+}
+
+/**
+ * Compare by code point, not by locale or UTF-16 unit: reading order must be
+ * one bytewise truth on every machine, and `<` on strings compares UTF-16 units
+ * — which differ from code points on astral names.
+ */
+export function codePointCompare(a: string, b: string): number {
+  const as = [...a];
+  const bs = [...b];
+  const n = Math.min(as.length, bs.length);
+  for (let i = 0; i < n; i += 1) {
+    const x = as[i]?.codePointAt(0) ?? 0;
+    const y = bs[i]?.codePointAt(0) ?? 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return as.length === bs.length ? 0 : as.length < bs.length ? -1 : 1;
+}
+
+/** Declared order first; ties break on the tie key. Total, and stable-safe. */
+export function compareSiblings(a: Sibling, b: Sibling): number {
+  if (a.order !== b.order) return a.order < b.order ? -1 : 1;
+  return codePointCompare(a.tie, b.tie);
+}

package/templates/scaffold/system/site/lib/page-order.ts

@@ -0,0 +1,93 @@
+/**
+ * Turning the reading-order rule into a sorted page tree — the SITE's half of
+ * decision 18, and canonical here so it can be tested.
+ *
+ * It names no framework type — the page-tree node shape is declared
+ * structurally below — for two reasons: the file is byte-copied into the
+ * scaffold's site, where it runs against Fumadocs's `Node`; and a rule that can
+ * only be exercised inside a Next build is a rule nobody exercises. The kernel
+ * has no website — it carries this so the SAME ORDER_CASES rows can be run
+ * against the tree sort a reader actually sees.
+ *
+ * Structural, not nominal: any node shaped like this sorts, which is what makes
+ * one file serve both the real page tree and the table's fixtures.
+ */
+
+import { compareSiblings, UNORDERED } from "./order-rule";
+
+/** The members of a page-tree node that reading order depends on. */
+export interface OrderNode {
+  readonly type: string;
+  /** A page's route. Absent on folders. */
+  readonly url?: string;
+  /** A folder's index document, when it has one. */
+  readonly index?: { readonly url: string } | undefined;
+  readonly children?: readonly OrderNode[] | undefined;
+}
+
+function nodeOrder(node: OrderNode, orders: ReadonlyMap<string, number>): number {
+  if (node.type === "page") return orders.get(node.url ?? "") ?? UNORDERED;
+  if (node.type === "folder" && node.index) return orders.get(node.index.url) ?? UNORDERED;
+  return UNORDERED;
+}
+
+// A url that identifies this node: its own, its index's, or its first
+// descendant's — a folder with no index document has no url of its own.
+function nodeUrl(node: OrderNode): string {
+  if (node.type === "page") return node.url ?? "";
+  if (node.type === "folder") {
+    if (node.index) return node.index.url;
+    for (const child of node.children ?? []) {
+      const url = nodeUrl(child);
+      if (url !== "") return url;
+    }
+  }
+  return "";
+}
+
+// The index of a top-level document's own segment: "/docs/x" splits to
+// ["", "docs", "x"], so its segment is at 2 — the baseUrl's segment count.
+const BASE_SEGMENTS = "/docs".split("/").length;
+
+/**
+ * The tie key: the ONE path segment that distinguishes this node from its
+ * siblings — never the whole url.
+ *
+ * The tree adapter ties on the entry's own name, so a folder with no index
+ * document must tie on its folder name too. Its url comes from a descendant
+ * (`/docs/guides/first`), and comparing that whole url against a sibling
+ * `/docs/guides-x` puts them in the opposite order, because the separator `/`
+ * (47) sorts after `-` (45). Taking the segment at this depth is exactly the
+ * adapter's key.
+ */
+function tieAt(node: OrderNode, depth: number): string {
+  return nodeUrl(node).split("/")[BASE_SEGMENTS + depth] ?? "";
+}
+
+/**
+ * Children of one parent, in reading order, recursively.
+ *
+ * Generic in the node so the caller keeps its own richer type: the site passes
+ * Fumadocs `Node`s and gets `Node`s back. The one cast is the rebuilt folder —
+ * spreading a node and replacing `children` produces a value TypeScript can no
+ * longer prove is the same subtype, though it is: every other member is copied
+ * verbatim. `depth` starts at 0 for the tree's own children.
+ */
+export function sortNodes<T extends OrderNode>(
+  nodes: readonly T[],
+  orders: ReadonlyMap<string, number>,
+  depth: number,
+): T[] {
+  return nodes
+    .map((node) =>
+      node.type === "folder"
+        ? ({ ...node, children: sortNodes(node.children ?? [], orders, depth + 1) } as T)
+        : node,
+    )
+    .sort((a, b) =>
+      compareSiblings(
+        { order: nodeOrder(a, orders), tie: tieAt(a, depth) },
+        { order: nodeOrder(b, orders), tie: tieAt(b, depth) },
+      ),
+    );
+}

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

@@ -3,6 +3,9 @@ import { loader } from "fumadocs-core/source";
 import { lucideIconsPlugin } from "fumadocs-core/source/lucide-icons";
 import type { Node, Root } from "fumadocs-core/page-tree";
 
+import { orderValue } from "./order-rule";
+import { sortNodes } from "./page-order";
+
 // See https://fumadocs.dev/docs/headless/source-api for more info
 export const source = loader({
   baseUrl: "/docs",
@@ -18,54 +21,12 @@ export type KnowledgePage = (typeof source)["$inferPage"];
 // every rendered link.
 export const basePath: string = process.env.KSOR_BASE_PATH ?? "";
 
-// `order:` is a governed frontmatter key; a document without one, or with a
-// value that is not a number, sorts after every document that declares one.
+// Reading order is ONE rule, shared with the MCP door byte-for-byte — see
+// ./order-rule.ts. The site cannot import the kernel, so the rule is copied and
+// the copy is asserted; every case both surfaces must agree on is a row in the
+// kernel's ORDER_CASES table, and this half is asserted against the same rows.
 function orderOf(page: KnowledgePage): number {
-  const raw: unknown = page.data.order;
-  const value = typeof raw === "string" ? Number(raw) : raw;
-  return typeof value === "number" && Number.isFinite(value) ? value : Number.POSITIVE_INFINITY;
-}
-
-function nodeOrder(node: Node, orders: ReadonlyMap<string, number>): number {
-  if (node.type === "page") return orders.get(node.url) ?? Number.POSITIVE_INFINITY;
-  if (node.type === "folder" && node.index) {
-    return orders.get(node.index.url) ?? Number.POSITIVE_INFINITY;
-  }
-  return Number.POSITIVE_INFINITY;
-}
-
-// The tie-break key: a page's url, a folder's index url or first page's url.
-// Ties break on it so unordered documents read in plain name order, folders
-// interleaved — the canonical reading order both shells implement (found
-// live 2026-08-18: the loader's own tie order grouped folders after loose
-// files, silently diverging from the Docusaurus shell on the same record).
-function nodeName(node: Node): string {
-  if (node.type === "page") return node.url;
-  if (node.type === "folder") {
-    if (node.index) return node.index.url;
-    for (const child of node.children) {
-      const name = nodeName(child);
-      if (name !== "") return name;
-    }
-  }
-  return "";
-}
-
-function sortNodes(nodes: readonly Node[], orders: ReadonlyMap<string, number>): Node[] {
-  return nodes
-    .map((node) =>
-      node.type === "folder" ? { ...node, children: sortNodes(node.children, orders) } : node,
-    )
-    .sort((a, b) => {
-      const left = nodeOrder(a, orders);
-      const right = nodeOrder(b, orders);
-      if (left !== right) return left < right ? -1 : 1;
-      const leftName = nodeName(a);
-      const rightName = nodeName(b);
-      // Codepoint comparison, not locale: reading order must be one bytewise
-      // truth on every machine.
-      return leftName < rightName ? -1 : leftName > rightName ? 1 : 0;
-    });
+  return orderValue(page.data.order);
 }
 
 /**
@@ -76,7 +37,7 @@ function sortNodes(nodes: readonly Node[], orders: ReadonlyMap<string, number>):
 export function getSortedPageTree(): Root {
   const orders = new Map(source.getPages().map((page) => [page.url, orderOf(page)] as const));
   const tree = source.getPageTree();
-  return { ...tree, children: sortNodes(tree.children, orders) };
+  return { ...tree, children: sortNodes(tree.children, orders, 0) };
 }
 
 function collectUrls(nodes: readonly Node[], urls: string[]): void {