@panaversity/ksor 0.0.39 → 0.0.41

package/templates/scaffold/system/site/lib/index-routes.ts

@@ -0,0 +1,125 @@
+/**
+ * From a directory's regenerated `index.md` (OKF §8 form, parsed by the
+ * record's `parseIndex`) to the routes this site serves — the folder page's
+ * listing and the one reading order every surface shares.
+ *
+ * The index IS the listing: every projection regenerates its indexes from the
+ * tree it was filtered to (record spec §1), so rendering the staged index is
+ * rendering exactly what this viewer may see, in the generator's order — one
+ * bullet list, concepts and folders interleaved by `order:` and ties broken on
+ * the name. The sidebar, `llms.txt` and the folder pages all take their order
+ * from here, which is what makes it ONE reading order rather than three.
+ *
+ * Pure: no framework, no filesystem, so the rule is unit-tested where the
+ * package tests live.
+ */
+
+/**
+ * One bullet of a parsed index: exactly the three fields this module reads.
+ *
+ * Structural rather than the record's own `IndexEntry`, so this rule keeps no
+ * relative import at all — it is unit-tested from the package
+ * (packages/ksor/src/index-routes.test.ts), whose Node-ESM program cannot
+ * typecheck the extensionless specifiers the site's modules must use, and the
+ * record's `parseIndex` output satisfies this by shape. Widening is impossible
+ * in the dangerous direction: a field dropped from the record's type fails at
+ * the call site.
+ */
+export interface IndexBullet {
+  readonly title: string;
+  readonly href: string;
+  readonly description: string | null;
+}
+
+export interface Listing {
+  readonly kind: "concept" | "folder";
+  readonly title: string;
+  /** The route, without any base path: `/docs/policies/x` or `/docs/policies`. */
+  readonly url: string;
+  /** Bundle-relative: `policies/x.md` for a concept, `policies` for a folder. */
+  readonly path: string;
+  readonly description: string | null;
+}
+
+/** The route of a bundle-relative directory: `""` → `/docs`, `a/b` → `/docs/a/b`. */
+export function folderRoute(dir: string): string {
+  return dir === "" ? "/docs" : `/docs/${dir}`;
+}
+
+/** The route of a bundle-relative concept path: `a/b.md` → `/docs/a/b`. */
+export function conceptRoute(conceptPath: string): string {
+  return `/docs/${conceptPath.replace(/\.md$/, "")}`;
+}
+
+/** The bundle-relative directory a route names, or null when it is not under `/docs`. */
+export function dirOfRoute(url: string): string | null {
+  if (url === "/docs") return "";
+  return url.startsWith("/docs/") ? url.slice("/docs/".length).replace(/\/$/, "") : null;
+}
+
+/**
+ * The listing of one directory from its parsed index. `dir` is bundle-relative
+ * (`""` at the root). A bullet's href is either `file.md` (a concept) or
+ * `name/` (a folder) — the two shapes the generator writes.
+ */
+export function listingOf(dir: string, entries: readonly IndexBullet[]): Listing[] {
+  const prefix = dir === "" ? "" : `${dir}/`;
+  return entries.flatMap((entry): Listing[] => {
+    const href = decodeHref(entry.href);
+    if (href.endsWith("/")) {
+      const path = `${prefix}${href.slice(0, -1)}`;
+      return [
+        { kind: "folder", title: entry.title, url: folderRoute(path), path, description: null },
+      ];
+    }
+    if (!href.endsWith(".md")) return [];
+    const path = `${prefix}${href}`;
+    return [
+      {
+        kind: "concept",
+        title: entry.title,
+        url: conceptRoute(path),
+        path,
+        description: entry.description,
+      },
+    ];
+  });
+}
+
+/**
+ * A href is percent-encoded by SOME index writers and not by ours, so it is
+ * decoded before use — and an undecodable one is the href itself, never a
+ * throw. `decodeURIComponent` rejects a bare `%` (`50%-off.md` → URIError),
+ * which took down `next build` with a message naming no file at all (found
+ * live, 2026-08-25); the record now refuses that name outright
+ * (`ksor-name-unportable`), so this is the second half of the same fix rather
+ * than a substitute for it — a bundle from another OKF producer still reaches
+ * here, and it must render the listing it can rather than none.
+ * The record's `resolveLink` guards the identical call for the identical
+ * reason.
+ */
+function decodeHref(href: string): string {
+  try {
+    return decodeURIComponent(href);
+  } catch {
+    return href;
+  }
+}
+
+/**
+ * Every route in reading order, root first, folders entered where their bullet
+ * sits: the depth-first walk of the indexes. `indexes` maps a bundle-relative
+ * directory to its parsed index; a folder bullet whose index is missing is
+ * listed and not entered.
+ */
+export function readingOrder(indexes: ReadonlyMap<string, readonly IndexBullet[]>): string[] {
+  const out: string[] = [];
+  const walk = (dir: string): void => {
+    for (const item of listingOf(dir, indexes.get(dir) ?? [])) {
+      out.push(item.url);
+      if (item.kind === "folder") walk(item.path);
+    }
+  };
+  walk("");
+  return out;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Lifecycle by surface (record spec §2.5) — ONE rule for the page, sidebar
+ * and on-site search (human) and for `llms.txt`, the twins, `server.json`,
+ * bundles and the door (machine). Evaluated at the build's `as_of` for
+ * static output and at request time on the door; the two can disagree on a
+ * concept that crosses a boundary in between, which `LIFECYCLE_CASES` pins
+ * as a row rather than hides. No imports: a leaf, safe to copy.
+ */
+
+export type Surface = "human" | "machine";
+export type LifecycleStatus = "draft" | "stable" | "deprecated";
+
+export interface LifecycleDoc {
+  readonly status: LifecycleStatus;
+  /** Epoch ms, or null when unset. */
+  readonly effectiveFrom: number | null;
+  readonly staleAfter: number | null;
+}
+
+/**
+ * May `surface` publish `doc` at instant `at`? `drafts` is the build's drafts switch,
+ * which admits drafts to HUMAN surfaces only.
+ */
+export function admitsLifecycle(
+  doc: LifecycleDoc,
+  surface: Surface,
+  at: number,
+  drafts: "hidden" | "shown",
+): boolean {
+  if (doc.status === "draft") return surface === "human" && drafts === "shown";
+  if (surface === "human") return true;
+  if (doc.status === "deprecated") return false;
+  if (doc.effectiveFrom !== null && doc.effectiveFrom > at) return false;
+  if (doc.staleAfter !== null && doc.staleAfter <= at) return false;
+  return true;
+}
+
+/** The word a human surface shows for a state the machine surfaces decline. */
+export type LifecycleBadge = "draft" | "effective-from" | "stale" | "deprecated";
+
+/**
+ * Why the machine surfaces decline `doc` at `at`, in one word — or null when
+ * they admit it. Independent of `drafts`: a draft is a draft whether or not a
+ * preview happens to show it.
+ */
+export function lifecycleBadge(doc: LifecycleDoc, at: number): LifecycleBadge | null {
+  if (doc.status === "draft") return "draft";
+  if (doc.status === "deprecated") return "deprecated";
+  if (doc.effectiveFrom !== null && doc.effectiveFrom > at) return "effective-from";
+  if (doc.staleAfter !== null && doc.staleAfter <= at) return "stale";
+  return null;
+}

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

@@ -0,0 +1,282 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+import { z } from "zod";
+
+import { refuse } from "./audience";
+import { RULES_VERSION } from "./rules-version";
+import { parseInstant } from "../record/instant";
+
+/**
+ * `build.lock.json` as the site reads it (build spec §2–§3): the record that
+ * `ksor build` checked this tree, the `as_of` every lifecycle decision in this
+ * build is evaluated at, the registry a viewer is validated against, and the
+ * stamps every machine artefact carries (R14).
+ *
+ * Outside development the site refuses to build without a FRESH lock — one
+ * whose document hashes match the tree — because a projection of a tree
+ * nothing checked is a projection nothing governs. `pnpm dev` is the review
+ * surface and needs none (decision 7); its artefacts say so.
+ *
+ * Freshness is asked in two halves, `readLock` then `assertLockCoversTree`,
+ * with the record's own checker between them: everything answerable about the
+ * lock alone comes first, and the file-by-file comparison comes after the tree
+ * has been shown to be a record at all.
+ */
+
+const hex64 = z.string().regex(/^[0-9a-f]{64}$/, "a sha256 hex digest");
+const hashed = z.object({ path: z.string().min(1), sha256: hex64 });
+
+/**
+ * `as_of` and `ksor_version` are VALIDATED here, not merely required to be
+ * non-empty, because both fail open downstream when they are unreadable: an
+ * `as_of` that does not parse made every lifecycle comparison `NaN`-false, so a
+ * policy not effective until 2030 was published as current and carried no
+ * badge; a `ksor_version` the semver regex misses slipped past the
+ * `ksor-site-outdated` gate and was then stamped verbatim into every machine
+ * artefact. A lock the site cannot read cannot say what was checked.
+ */
+const instant = z
+  .string()
+  .refine((v) => parseInstant(v) !== null, "an ISO 8601 instant with an explicit offset");
+const semver = z.string().regex(/^v?\d+\.\d+\.\d+/, "a version this site can compare");
+
+const lockSchema = z
+  .object({
+    format: z.literal(1),
+    build_id: z.string().min(1),
+    ksor_version: semver,
+    source_commit: z.string().nullable(),
+    dirty: z.boolean(),
+    as_of: instant,
+    drafts: z.enum(["hidden", "shown"]),
+    instance_sha256: hex64,
+    policy_sha256: hex64,
+    ledger_sha256: hex64,
+    ledger_entries: z.array(z.object({ id: z.string().min(1), digest: hex64 }).loose()),
+    audiences: z.object({ registry: z.array(z.string().min(1)) }).loose(),
+    documents: z.array(hashed.loose()),
+    companions: z.array(hashed.loose()),
+    assets: z.array(hashed.loose()),
+    indexes: z.array(hashed.loose()),
+  })
+  .loose();
+
+/**
+ * The three files that hold the record's governance, hashed the way
+ * `composeLock` hashes them: over the TEXT, with the empty string standing for
+ * a ledger that does not exist.
+ */
+export interface ControlTexts {
+  readonly instance: string;
+  readonly policy: string;
+  /** Null when `.ksor/takedowns.yaml` is not there — an empty ledger. */
+  readonly ledger: string | null;
+}
+
+function sha256Text(text: string): string {
+  return createHash("sha256").update(Buffer.from(text, "utf8")).digest("hex");
+}
+
+export type BuildLock = z.infer<typeof lockSchema>;
+
+export const LOCK_FILE = "build.lock.json";
+
+/** sha256 of a file's raw bytes, hex — what `documents[].sha256` holds. */
+export function sha256Of(file: string): string {
+  return createHash("sha256").update(readFileSync(file)).digest("hex");
+}
+
+/**
+ * The lock itself: present, readable, and describing THIS instance's
+ * governance and this build's switches. Refuses `ksor-lock-missing` when
+ * absent, `ksor-lock-stale` when unreadable or when a control file has changed
+ * since it was written, and `ksor-site-outdated` when it was written by a
+ * newer ksor than the rule modules this site carries.
+ *
+ * Everything here is answerable WITHOUT looking at the record's tree, which is
+ * why it is separate from `assertLockCoversTree`: the caller checks the record
+ * in between, so a tree that is not a legal record is refused by the rule it
+ * breaks instead of by a freshness claim it was never eligible for.
+ */
+export function readLock(
+  root: string,
+  control: ControlTexts,
+  options: { readonly draftsRequested: boolean },
+): BuildLock {
+  const file = path.join(root, LOCK_FILE);
+  if (!existsSync(file)) {
+    refuse(
+      "ksor-lock-missing",
+      `${LOCK_FILE} is not there`,
+      "the site projects what `ksor build` checked — without its lock this build cannot tell a checked record from an unchecked one, and a projection of an unchecked record is one nothing governs",
+      "run `ksor build` first (`pnpm build` does), then build the site; `pnpm dev` needs no lock",
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    parsed = undefined;
+  }
+  const lock = lockSchema.safeParse(parsed);
+  if (!lock.success) {
+    refuse(
+      "ksor-lock-stale",
+      `${LOCK_FILE} cannot be read as a build lock (${lock.error.issues[0]?.path.join(".") || "root"}: ${lock.error.issues[0]?.message ?? "unreadable"})`,
+      "a lock this site cannot read cannot say what was checked",
+      "run `ksor build` again; if the lock was written by a newer ksor, upgrade the site with `ksor migrate --write-site`",
+    );
+  }
+  // The control files before anything else about this record, the record's own
+  // rules included: a stale LEDGER or POLICY is a takedown that was lifted or
+  // an authority that was rewritten, and the lock's `ledger_entries` are the
+  // baseline the checker is then handed for `ksor-ledger-amended` — so a ledger
+  // the lock never saw is refused HERE, before anything is judged against it.
+  // The file-by-file comparison is `assertLockCoversTree`, after the checker.
+  for (const [file, want, have] of [
+    ["instance.md", lock.data.instance_sha256, sha256Text(control.instance)],
+    [".ksor/governance.yaml", lock.data.policy_sha256, sha256Text(control.policy)],
+    [".ksor/takedowns.yaml", lock.data.ledger_sha256, sha256Text(control.ledger ?? "")],
+  ] as const) {
+    if (want === have) continue;
+    refuse(
+      "ksor-lock-stale",
+      `${file} changed since ${LOCK_FILE} was written`,
+      "the lock's build_id is a hash over the record AND the three files that govern it, so a projection under a control file the lock never saw publishes what nothing checked — a denial lifted by deleting a line would otherwise leave the lock valid",
+      "run `ksor build` again and commit the lock with the change; lift a denial with `ksor takedown --revoke <id>`, never by editing the ledger",
+    );
+  }
+  // Both directions. The reverse — a `drafts: shown` lock and no KSOR_DRAFTS —
+  // is the dangerous one: one preview build accidentally committed publishes
+  // every draft on every later production deploy, with no environment signal
+  // and nothing red (`noindex` is a crawler hint, not a control).
+  if (options.draftsRequested !== (lock.data.drafts === "shown")) {
+    refuse(
+      "ksor-lock-stale",
+      options.draftsRequested
+        ? `KSOR_DRAFTS=show was requested, but ${LOCK_FILE} was built with drafts hidden`
+        : `${LOCK_FILE} was built with drafts SHOWN, and this build did not ask for them`,
+      "the lock's build_id covers the drafts switch, so a site and a lock that disagree about it would stamp every artefact with an id that does not describe it — and a preview lock is not a publishing lock",
+      options.draftsRequested
+        ? "run `KSOR_DRAFTS=show ksor build` before the site build, or build without KSOR_DRAFTS"
+        : "run `ksor build` (without KSOR_DRAFTS) and commit the lock, or build the preview with `KSOR_DRAFTS=show`",
+    );
+  }
+  if (outdated(lock.data.ksor_version, RULES_VERSION)) {
+    refuse(
+      "ksor-site-outdated",
+      `${LOCK_FILE} was built by ksor ${lock.data.ksor_version}, and this site carries rule modules from ${RULES_VERSION}`,
+      "the site would project the record with rules older than the ones that checked it — a document the newer checker admits under a rule this site does not know is a document this build gets wrong",
+      "upgrade the site's rule modules: `ksor migrate --write-site` offers the byte-copied modules as diffs (decision 4)",
+    );
+  }
+  return lock.data;
+}
+
+/**
+ * Does the lock describe THIS tree, file by file? Refuses `ksor-lock-stale`
+ * naming the first path that disagrees.
+ *
+ * Run AFTER the record's own checker, not before it, because this comparison
+ * cannot tell a document that changed from a file the record may not hold at
+ * all — and it answers both the same way. An `.mdx` dropped into `knowledge/`
+ * is refused by name (`ksor-file-type`: the bundle is CommonMark), so no
+ * `ksor build` can ever have listed it here; reporting it as "asset notes.mdx
+ * is in the tree and not in the lock" told the operator to re-run the build
+ * that refuses the file, and named neither the rule nor the fix (found in
+ * review, 2026-08-25). The record is judged by its own rules first; the lock's
+ * claim about the tree is asked once the tree is a record.
+ *
+ * Nothing is staged in between, so the ordering costs a refused build one
+ * checker pass and can never publish anything.
+ */
+export function assertLockCoversTree(
+  lock: BuildLock,
+  files: {
+    readonly documents: ReadonlyMap<string, string>;
+    readonly companions: ReadonlyMap<string, string>;
+    readonly assets: ReadonlyMap<string, string>;
+    /** The COMMITTED `knowledge/**\/index.md`, not the ones this build will stage. */
+    readonly indexes: ReadonlyMap<string, string>;
+  },
+): void {
+  const stale = firstStale(lock, files);
+  if (stale === null) return;
+  refuse(
+    "ksor-lock-stale",
+    `${LOCK_FILE} does not match the tree: ${stale}`,
+    "the lock records the exact record `ksor build` checked; a document that changed since was never checked, so this build would publish what nothing governs",
+    "run `ksor build` again and commit the lock with the change",
+  );
+}
+
+/** The first path whose presence or hash disagrees between lock and tree, described; null when none. */
+function firstStale(
+  lock: BuildLock,
+  files: {
+    readonly documents: ReadonlyMap<string, string>;
+    readonly companions: ReadonlyMap<string, string>;
+    readonly assets: ReadonlyMap<string, string>;
+    readonly indexes: ReadonlyMap<string, string>;
+  },
+): string | null {
+  for (const [kind, entries, tree] of [
+    ["document", lock.documents, files.documents],
+    ["companion", lock.companions, files.companions],
+    // Assets last and never omitted: the site publishes their bytes, and for a
+    // record whose diagrams carry the substance a lock that stops at the
+    // markdown does not cover what the build actually serves.
+    ["asset", lock.assets, files.assets],
+    // …and the INDEXES, which are the one thing under `knowledge/` the build
+    // WRITES rather than reads. The site never copies them — it regenerates a
+    // per-viewer set — so this comparison is the only thing that can see a
+    // committed index drift away from the bytes `ksor build` wrote (a merge
+    // resolution, and nobody re-ran the build). `ksor ingest` has always
+    // compared them; the site published what the door then refused.
+    //
+    // Against the COMMITTED bytes, never against the staged ones: the lock
+    // records the WHOLE record's indexes, and a per-viewer stage regenerates a
+    // legitimately shorter one, so comparing what the stage is about to write
+    // would refuse every correct build of a record that restricts anything.
+    ["index", lock.indexes, files.indexes],
+  ] as const) {
+    const locked = new Map(entries.map((e) => [e.path, e.sha256] as const));
+    for (const [rel, abs] of tree) {
+      const want = locked.get(rel);
+      if (want === undefined) return `${kind} ${rel} is in the tree and not in the lock`;
+      if (want !== sha256Of(abs)) return `${kind} ${rel} changed since the lock was written`;
+    }
+    for (const rel of locked.keys()) {
+      if (!tree.has(rel)) return `${kind} ${rel} is in the lock and no longer in the tree`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Is a lock written by `lockVersion` newer than the rules this site carries?
+ * Numeric semver, pre-release tags ignored. NEITHER unparsable side is
+ * "current": a SITE stamp that is not a version is the template's literal, so
+ * `ksor init` never finished; a LOCK version that is not a version is a lock
+ * this site cannot compare against at all. Both count as outdated — this used
+ * to return false for the lock half, which let `"999"` past the gate and then
+ * stamped it into every machine artefact. `lockSchema` now refuses that shape
+ * first, so this branch is the second lock on the same door.
+ */
+export function outdated(lockVersion: string, rulesVersion: string): boolean {
+  const a = parts(lockVersion);
+  const b = parts(rulesVersion);
+  if (a === null) return true;
+  if (b === null) return true;
+  for (let i = 0; i < 3; i += 1) {
+    if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0);
+  }
+  return false;
+}
+
+function parts(version: string): number[] | null {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+  return m === null ? null : [Number(m[1]), Number(m[2]), Number(m[3])];
+}

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

@@ -36,6 +36,21 @@
  *   - case. The kernel lowercased the tie key and the site did not, so
  *     `apple.md` and `Banana.md` came out in opposite orders.
  *
+ * Two more, found in the OKF-native review and fixed the same way:
+ *
+ *   - folders. The index generator emitted every concept bullet and THEN every
+ *     folder bullet, so a folder could never sort between two documents, while
+ *     the tree adapter sorted concepts and directories in one list. The site
+ *     takes its whole reading order from the generated indexes, so an agent
+ *     asking `outline` "what do I read first" and a reader on the site were
+ *     told different documents. The ratified row has always said they
+ *     interleave.
+ *   - the folder's own key. The generator folded over every concept BENEATH a
+ *     directory; the adapter folded over the directory's OWN concepts only, so
+ *     a folder whose ordered documents live one level deeper was unordered on
+ *     one surface and first on the other. {@link folderOrder} is now the one
+ *     answer both call.
+ *
  * No imports: a leaf, so it is testable in isolation and safe to copy.
  */
 
@@ -105,3 +120,25 @@ 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);
 }
+
+/**
+ * A directory's sort key: the lowest order among the concepts anywhere BENEATH
+ * it, descendants included — a folder sorts where its first concept does.
+ *
+ * Descendants and not just the directory's own concepts, because a folder whose
+ * documents live one level deeper (`alpha/deep/a.md`) still has a first thing to
+ * read, and calling it unordered files the whole folder behind every ordered
+ * sibling. `ordersByDir` maps a bundle-relative directory to the orders of the
+ * concepts sitting DIRECTLY in it, which is the shape both callers already hold.
+ */
+export function folderOrder(
+  ordersByDir: Iterable<readonly [string, readonly number[]]>,
+  dir: string,
+): number {
+  let min = UNORDERED;
+  for (const [d, orders] of ordersByDir) {
+    if (d !== dir && !d.startsWith(`${dir}/`)) continue;
+    for (const o of orders) if (o < min) min = o;
+  }
+  return min;
+}

package/templates/scaffold/system/site/lib/record-href.ts

@@ -0,0 +1,68 @@
+/**
+ * What a link inside a document names, as a route of THIS build.
+ *
+ * OKF §6.1 allows two forms and the record spec (§2.3) carries both:
+ * bundle-absolute (`/policies/x.md`, resolved against `knowledge/`) and
+ * relative (`x.md`, `./x.md`, `../x.md`, against the document's own
+ * directory), with `.md` optional in each. The shell resolves only the `./`
+ * and `../` forms (fumadocs-core 16.14.5, `resolveHref` returns anything else
+ * untouched), so a bundle-absolute link left the record's frame entirely and a
+ * bare `x.md` was resolved by the browser against the page's ROUTE rather than
+ * its directory: both 404'd from every page, found live 2026-08-25 as prefetch
+ * failures in the console.
+ *
+ * So the record's OWN resolver decides — `resolveLink` is the same function the
+ * checker uses for the widening rule, which is what makes a link the checker
+ * accepted a link this site can serve.
+ *
+ * Pure, and the whole decision, so it is testable without a site install
+ * (packages/ksor/src/record-href.integration.test.ts).
+ */
+import { resolveLink } from "../record/citations";
+
+/**
+ * `href` as this build serves it: a route when the link names a concept of this
+ * build, and the author's own text otherwise.
+ *
+ * Otherwise the href is handed back UNCHANGED, which is what carries assets,
+ * external urls and same-page anchors through untouched.
+ *
+ * Two cases fall through to a link this build cannot serve, and both are
+ * deliberate. A per-viewer build stages a SUBSET, so a link to a concept this
+ * viewer may not see must not be rewritten — inventing a route would publish
+ * the existence of a document the viewer was not given, which is exactly what
+ * the audience rule withholds. And a link to a concept that exists in no build
+ * is an authoring mistake the CHECKER owns: rewriting it here would hide it
+ * from the one thing that can name the file and the line.
+ */
+export function recordHref(
+  href: string | undefined,
+  sourceId: string,
+  routes: ReadonlyMap<string, string>,
+): string | undefined {
+  if (href === undefined) return href;
+  // Classified on the value a BROWSER sees. Parsing a URL strips leading C0
+  // controls and spaces (WHATWG URL §4.4), so `\tjavascript:…` is a scheme to
+  // everything that follows the link and was not one to this test. An href
+  // carrying a scheme was therefore read as a record link — and one whose
+  // mangled path happened to resolve (`\tjavascript:x/../policies/travel`) was
+  // rewritten into a route of this build.
+  //
+  // Defence in depth rather than a live hole: the same regex runs in
+  // `record/citations.ts`, over the raw markdown, so a link written this way is
+  // classified as a record link there too, resolves to nothing, and the build
+  // refuses it `ksor-link-dead` before the page exists. This makes the guard
+  // mean what it says on the value it is guarding.
+  // eslint-disable-next-line no-control-regex -- the control range is the point
+  const probe = href.replace(/^[\u0000-\u0020]+/, "");
+  // A same-page anchor, a protocol-relative url, and anything carrying a
+  // scheme (`https:`, `mailto:`) are not record links and are never touched.
+  if (probe === "" || probe.startsWith("#") || probe.startsWith("//")) return href;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(probe)) return href;
+  const id = resolveLink(sourceId, href);
+  if (id === null) return href;
+  const url = routes.get(id);
+  if (url === undefined) return href;
+  const hash = href.indexOf("#");
+  return hash === -1 ? url : `${url}${href.slice(hash)}`;
+}

package/templates/scaffold/system/site/lib/record-link.tsx

@@ -0,0 +1,26 @@
+import type { ComponentProps, FC } from "react";
+import type { LoaderConfig, LoaderOutput, Page } from "fumadocs-core/source";
+import { createRelativeLink } from "fumadocs-ui/mdx";
+
+import { conceptIdOfPath } from "./governance";
+import { recordHref } from "./record-href";
+
+/**
+ * The MDX anchor for a governed document: the shell's relative link, with the
+ * record's own link rule in front of it (lib/record-href.ts, which carries the
+ * why).
+ *
+ * The routes are the pages of THIS build, so the subset a per-viewer build
+ * staged is exactly the set a link may resolve into.
+ */
+export function recordLink<C extends LoaderConfig>(
+  source: LoaderOutput<C>,
+  page: Page | C["page"],
+): FC<ComponentProps<"a">> {
+  const Relative = createRelativeLink(source, page);
+  const routes = new Map(source.getPages().map((p) => [conceptIdOfPath(p.path), p.url] as const));
+  const sourceId = conceptIdOfPath(page.path);
+  return function RecordLink(props: ComponentProps<"a">) {
+    return <Relative {...props} href={recordHref(props.href, sourceId, routes)} />;
+  };
+}

package/templates/scaffold/system/site/lib/rules-version.ts

@@ -0,0 +1,11 @@
+/**
+ * The ksor version whose rule modules this site carries — stamped by
+ * `ksor init` and offered as a diff by `ksor migrate --write-site` (decision 4:
+ * the site is adopter-owned, so nothing here updates itself).
+ *
+ * `build.lock.json` records the version that built it. When that is NEWER than
+ * this stamp, the site would project a record with rules older than the ones
+ * that checked it — the visibility leak's fifth door — so the build refuses
+ * `ksor-site-outdated` instead (build spec §3).
+ */
+export const RULES_VERSION: string = "KSOR-STAMP-VERSION";