@panaversity/ksor 0.0.57 → 0.0.59

package/templates/scaffold/AGENTS.md

@@ -423,7 +423,7 @@ governance block every hit now carries:
 Three edits pay for themselves:
 
 - **Delete a tool nothing calls.** Removing `outline` and `read` gives back
-  ~2,152 tokens for the whole session.
+  ~2,310 tokens for the whole session.
 - **Say what this record covers**, above `FLOOR.search`. It is how an agent with
   several records attached picks yours; name the subject AND the boundary.
 - **Set `k`** in the input schema — it is the lever on reply size.
@@ -497,9 +497,14 @@ runs over every entry in the ledger at `pnpm check`, `ksor build` and ingest, so
 a line appended by hand in a pull request is refused exactly as the verb would
 refuse it. The read-only modes
 (`--list`, `--ledger`) need no actor — nobody is performing an act by looking.
-They do not need a database either: on a record that declares none they read
-the committed `.ksor/takedowns.yaml`, which is the whole record of the act
-anyway.
+They do not need a database either: `--ledger` always reads the committed
+`.ksor/takedowns.yaml`, which is the record of every act, and `--list` reads
+the door's denylist rows when `KSOR_DB_URL` is set and otherwise the ledger's
+denials, each labelled `not applied (no database)` because no row exists for
+a door to refuse on. A denial itself, on this record with `KSOR_DB_URL` unset,
+is refused by name (`ksor-takedown-dsn-missing`) unless `--file-only` records
+the entry alone — `--apply` writes its row later, where the database is
+reachable.
 
 **The MCP door stops serving it immediately. The SITE stops at its next
 build** — the site reads the committed ledger (`.ksor/takedowns.yaml`), not
@@ -516,7 +521,11 @@ ROOT, never `system/site/`), and every other host just serves the folder.
 record checked, `build.lock.json` written (commit it: it is the provenance
 every machine artefact stamps) — and a refusal stops the build before a byte
 is written. `ksor build --strict` additionally refuses an uncommitted input
-(`ksor-build-dirty`), which is the posture for a release.
+(`ksor-build-dirty`), which is the posture for a release. `ksor build
+--bundles` also writes one OKF bundle per viewer under
+`.ksor/out/bundles/<viewer>/` (gitignored) — only what that viewer's machine
+surfaces publish, readable by any OKF consumer with no ksor in the loop — for
+handing the record to another system.
 `KSOR_BASE_PATH=/repo pnpm build` targets sub-path hosting. With audiences
 registered in `.ksor/governance.yaml`, plain `pnpm build` is the `public`
 viewer; `KSOR_AUDIENCE=public,<audience> pnpm build` — a comma list, always
@@ -607,7 +616,14 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   audiences registered in `.ksor/governance.yaml`; never omitted, never
   inferred). A `stable` document carries `generated: { by, at }` and
   `ksor.approval: { by, at }` by an actor the policy authorises, with
-  `generated.at` no later than the approval; a `deprecated` one carries
+  `generated.at` no later than the approval — and `generated.at` dates the
+  TEXT: edit a stable document's body and `ksor build` and `ksor ingest`
+  compare it against every committed version that was stable, and refuse
+  `ksor-generated-stale` until you move the stamp PAST the edit and re-approve
+  — leaving the stamp alone and backdating it are refused alike, because
+  neither advances it (a frontmatter-only edit, such as adding a `verified`
+  entry, is not a body change; `pnpm check` reads no document history, so it passes an
+  edit the build will refuse); a `deprecated` one carries
   `ksor.deprecated: { by, at }` and usually `ksor.superseded_by: <id>`
   (a stable document every reader of this one may read). Optional: `order`
   (reading position), `sources` (`{ id, resource, title }`, cited in the body
@@ -899,8 +915,7 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   click is informed.
 
   **You do not state a height.** A page carried in the record is measured, so
-  the frame is exactly as tall as what it holds — on this record's own seven,
-  to the pixel. A number written into a document would be a number some other
+  the frame is exactly as tall as what it holds, to the pixel. A number written into a document would be a number some other
   measure makes wrong.
 
   **Carry the page in where you can.** A file named `<name>.sim.html`, sitting

package/templates/scaffold/README.md

@@ -259,7 +259,9 @@ Never copy a floor from another corpus.
 It also prints its own caveat, and it is worth reading: the probes it writes are
 derived from your passages, so they share vocabulary a real question will not.
 The floor it reports is an upper bound on separation until you check it against
-questions the corpus did not write (`--queries-file`).
+questions a person wrote: in-corpus ones with `--queries-file`, and — because
+the built-in out-of-corpus probes are all far-domain — questions just outside
+your scope with `--ooc-file`.
 
 A rerun on an unchanged record costs nothing: no new generation, no embedding,
 no rows. Edit a document and the next run picks up exactly that change.
@@ -698,7 +700,7 @@ different coding agent's way of finding the same working contract.
 | `.gemini/settings.json`          | points Gemini CLI at `AGENTS.md`; Gemini does not read that filename on its own.                                                                                                                        |
 | `.github/workflows/validate.yml` | your CI: runs the same checker on every pull request and push to main.                                                                                                                                  |
 | `.gitattributes`                 | markdown is checked out byte-stable on every platform, so the same commit hashes the same everywhere.                                                                                                   |
-| `.gitignore`                     | keeps build output, `node_modules/`, and `.env` out of the record's history — and negates two paths inside `.ksor/`, because the policy and the ledger ARE the record.                                   |
+| `.gitignore`                     | keeps build output, `node_modules/`, and `.env` out of the record's history — and negates three paths inside `.ksor/`, because the policy, the ledger and the phone book ARE the record.                  |
 
 `format-checker` deliberately contains a program, `check.mjs`, and not only
 prose: rules that are only written down cannot refuse anything.
@@ -724,6 +726,7 @@ map rather than a substitute.
 | the home page and `/llms.txt` are empty                              | every document is still a draft — correct, not broken                                                      | approve one and rebuild                                                                |
 | `ksor-record-empty`                                                  | every document was deleted — a record is never empty, so nothing was written                               | add one document of your own (or restore one from git) before deleting the last starter |
 | `ksor-approver-unauthorised`                                         | a document is approved by an actor `.ksor/governance.yaml` no longer names — usually `human:you` after the interview | re-attribute the approval to your handle, or restore the actor to `approval_authorities` |
+| `ksor-generated-stale` at `pnpm build` or `pnpm refresh`             | a `stable` document's body changed since a commit where it was stable, and `generated.at` was not advanced past that commit's (left alone, or moved backward) — the stamp dates the text, and `pnpm check` reads no document history, so it passed | set `generated.at` to an instant after the edit and re-approve (`ksor.approval.at` may not precede it) |
 | a new document never appears on the built site                       | drafts reach no built surface at all                                                                       | publish it — `status: stable` plus both governance keys                                |
 | an expired document still shows on the site but not through the door | the static build evaluated `stale_after` at build time                                                     | rebuild and redeploy; schedule a rebuild if you use it                                 |
 | Vercel: `no services are declared`                                   | Root Directory was auto-filled with `system/site`                                                          | set it to `./`                                                                         |

package/templates/scaffold/env.example

@@ -66,6 +66,9 @@ KSOR_AUTH=disabled-local
 # NEXT_PUBLIC_KSOR_SSO_URL=https://your-sso.example.com
 # NEXT_PUBLIC_KSOR_OAUTH_CLIENT_ID=
 # NEXT_PUBLIC_KSOR_OAUTH_REDIRECT_URI=https://your-site.example.com/auth/callback
+#
+# Next.js telemetry is already off: the site's build and dev scripts run next
+# through system/site/next-no-telemetry.mjs, which sets NEXT_TELEMETRY_DISABLED=1.
 
 # ── Production knobs ────────────────────────────────────────────────────────
 # Unset is fine for a local run; each one matters once this serves for real.

package/templates/scaffold/instance.md

@@ -41,9 +41,8 @@ record wins.
 
 Everything above describes KSoR itself. It ships filled in so that a fresh
 project has a real governed corpus on the first `pnpm dev` — five approved
-documents, three of them inside a folder, and one carrying all four study
-attachments (a summary, slides, flashcards and a quiz) — instead of an empty
-shelf and a placeholder.
+documents, three of them inside a folder, and one carrying a summary
+companion — instead of an empty shelf and a placeholder.
 The documents live in `knowledge/`; delete them as your own knowledge arrives.
 
 Be deliberate about replacing it, because a starter that describes the wrong

package/templates/scaffold/system/site/next-no-telemetry.mjs

@@ -0,0 +1,27 @@
+/**
+ * Run Next.js with its telemetry OFF, so nothing phones home.
+ *
+ * Next.js ships with anonymous usage telemetry switched on: `next build` and
+ * `next dev` each post to telemetry.nextjs.org unless NEXT_TELEMETRY_DISABLED
+ * is set in the process environment. This project promises that nothing
+ * phones home, so `build` and `dev` run next through here instead of directly.
+ *
+ * Why the environment and not next.config.mjs: the `next dev` parent process
+ * never loads the config, and still records a session event on exit. Why a
+ * file and not a `NEXT_TELEMETRY_DISABLED=1 next …` prefix in package.json:
+ * that prefix is POSIX shell syntax, which cmd.exe refuses on Windows. This
+ * is node:child_process and nothing else — no dependency, works everywhere
+ * node does — and every argument passes through to next unchanged.
+ */
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const next = fileURLToPath(new URL("dist/bin/next", import.meta.resolve("next/package.json")));
+
+const child = spawnSync(process.execPath, [next, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: { ...process.env, NEXT_TELEMETRY_DISABLED: "1" },
+});
+
+if (child.error) throw child.error;
+process.exit(child.status ?? 1);

package/templates/scaffold/system/site/package.json

@@ -4,8 +4,8 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "build": "next build --webpack",
-    "dev": "next dev"
+    "build": "node next-no-telemetry.mjs build --webpack",
+    "dev": "node next-no-telemetry.mjs dev"
   },
   "dependencies": {
     "class-variance-authority": "0.7.1",

package/templates/scaffold/system/site/record/change-control.ts

@@ -0,0 +1,319 @@
+/**
+ * KSP R23 — the first verification tooth in approval.
+ *
+ * A `stable` concept's `generated.at` dates its TEXT, and `ksor.approval.at`
+ * ratifies the text of that date. Until now the checker compared the two
+ * authored instants and nothing else (`ksor-generated-after-approval`), so
+ * whether an edit actually moved `generated.at` was the author's obligation:
+ * change a sentence, leave the stamp, and the approval that ratified the old
+ * sentence reads as ratifying the new one, with nothing red. This module
+ * compares the body in the working tree against every committed version of
+ * the same path that was `stable`, and refuses `ksor-generated-stale` when a
+ * body differs under a `generated.at` the tree has not ADVANCED past — equal,
+ * or moved backward, which changes the stamp without advancing it. Only the
+ * body: a frontmatter-only
+ * edit — a `verified` entry, a re-approval — is not a change to the text the
+ * stamp dates.
+ *
+ * What it does NOT verify, and says so: who reviewed anything. R22 and R25
+ * need an identity the platform can vouch for, and `approval.checked` stays
+ * `"policy"` (decision 21). This is the one rule in the record module that
+ * reads git, so it sits beside `git-ledger.ts` and is run by the two
+ * publishing verbs — `ksor build` and `ksor ingest` — each of which SAYS when
+ * history could not be read rather than passing a check that did not run. The
+ * emitted `check.mjs` does not run it: that is the format gate an agent runs
+ * after every edit, and a stamp is verified where the record is published.
+ */
+import { spawnSync } from "node:child_process";
+
+import { normalizeText, splitFrontmatter } from "./frontmatter";
+import { git } from "./git-ledger";
+import { parseInstant } from "./instant";
+import type { Concept } from "./profile";
+import type { Refusal } from "./refusal";
+
+export interface CommittedVersion {
+  readonly sha: string;
+  /** The committer instant, ISO 8601 with an offset (`%cI`). */
+  readonly committedAt: string;
+  readonly text: string;
+}
+
+export interface CommittedHistory {
+  /** False outside any repository, and false without a git binary. */
+  readonly repository: boolean;
+  /** Whether HEAD exists: a fresh `ksor init` is a repository with no commit. */
+  readonly born: boolean;
+  readonly shallow: boolean;
+  /** Record-relative path → its committed versions, newest first; null when history could not be read. */
+  readonly versions: ReadonlyMap<string, readonly CommittedVersion[]> | null;
+}
+
+/** The record's bundle, and the only pathspec the walk needs (relative to the cwd, which is the record root). */
+const BUNDLE = "knowledge/";
+
+/**
+ * Objects per `git cat-file --batch` call. One process per object was measured
+ * at ~53 ms a call on the machine this was built on against ~0.6 ms an object
+ * batched (2026-09-02), so a record with a few hundred committed versions is
+ * the difference between a build that finishes and one that does not. Chunked
+ * so the reply stays under the buffer ceiling `git-ledger.ts` explains.
+ */
+const BATCH = 256;
+const MAX_BUFFER = 64 * 1024 * 1024;
+
+/**
+ * Every committed version of each path, read in three git calls plus one
+ * `cat-file --batch` per chunk. `--full-history`, for the reason the ledger
+ * walk gives: default simplification follows a merge through the parent it is
+ * TREESAME to, so a version that lived only on a branch never enters the set.
+ * `-m`, because without a diff-merges option a merge commit lists NO paths at
+ * all — verified against git 2.50 — and a conflict resolved by hand is a body
+ * that is in neither parent; the same commit then prints once per parent, so
+ * versions are keyed by (commit, path). That flag is held by the merge case in
+ * `build.integration.test.ts`'s KSP R23 describe: drop `-m` here and the build
+ * it expects to refuse exits 0 instead.
+ */
+export function committedVersions(root: string, paths: readonly string[]): CommittedHistory {
+  const inside = git(root, ["rev-parse", "--is-inside-work-tree"]);
+  if (inside === null || inside.trim() !== "true") {
+    return { repository: false, born: false, shallow: false, versions: null };
+  }
+  const shallow = (git(root, ["rev-parse", "--is-shallow-repository"]) ?? "").trim() === "true";
+  const born = git(root, ["rev-parse", "--verify", "--quiet", "HEAD"]) !== null;
+  const versions = new Map<string, CommittedVersion[]>();
+  if (!born || paths.length === 0) return { repository: true, born, shallow, versions };
+
+  // `--name-only` prints paths from the REPOSITORY root, and the record may
+  // sit below it (`docs-sor/knowledge/x.md`) — the same two meanings of "path"
+  // `git-ledger.ts` records. The pathspec is cwd-relative; the names are not.
+  const prefix = (git(root, ["rev-parse", "--show-prefix"]) ?? "").trim();
+  const log = git(root, [
+    "log",
+    "--full-history",
+    "-m",
+    "--format=%x1e%H %cI",
+    "--name-only",
+    "--",
+    BUNDLE,
+  ]);
+  if (log === null) return { repository: true, born, shallow, versions: null };
+
+  const wanted = new Set(paths);
+  const refs: { readonly sha: string; readonly committedAt: string; readonly path: string }[] = [];
+  const seen = new Set<string>();
+  for (const block of log.split("\x1e")) {
+    const [header = "", ...names] = block.split("\n");
+    const [sha = "", committedAt = ""] = header.trim().split(" ");
+    if (sha === "") continue;
+    for (const name of names) {
+      // Names the profile admits are plain ASCII (`ksor-name-unportable`), so
+      // git never C-quotes one here; a quoted stray matches no wanted path.
+      const trimmed = name.trim();
+      if (trimmed === "" || !trimmed.startsWith(prefix)) continue;
+      const rel = trimmed.slice(prefix.length);
+      if (!wanted.has(rel) || seen.has(`${sha} ${rel}`)) continue;
+      seen.add(`${sha} ${rel}`);
+      refs.push({ sha, committedAt, path: rel });
+    }
+  }
+  const blobs = readBlobs(
+    root,
+    refs.map((r) => `${r.sha}:${prefix}${r.path}`),
+  );
+  if (blobs === null) return { repository: true, born, shallow, versions: null };
+  refs.forEach((ref, i) => {
+    const text = blobs[i];
+    // Absent in that commit: the commit DELETED the path (a rename's old name).
+    if (text === null || text === undefined) return;
+    const list = versions.get(ref.path) ?? [];
+    list.push({ sha: ref.sha, committedAt: ref.committedAt, text });
+    versions.set(ref.path, list);
+  });
+  return { repository: true, born, shallow, versions };
+}
+
+/**
+ * `<rev>:<path>` specs → text, in order; null for a spec that names nothing,
+ * and null for the WHOLE read when git failed — a version dropped in silence
+ * would read as verified.
+ */
+function readBlobs(root: string, specs: readonly string[]): readonly (string | null)[] | null {
+  const out: (string | null)[] = [];
+  for (let i = 0; i < specs.length; i += BATCH) {
+    const chunk = specs.slice(i, i + BATCH);
+    const r = spawnSync("git", ["cat-file", "--batch"], {
+      cwd: root,
+      input: `${chunk.join("\n")}\n`,
+      maxBuffer: MAX_BUFFER,
+    });
+    if (r.status !== 0) return null;
+    const buf: Buffer = r.stdout;
+    let at = 0;
+    for (let k = 0; k < chunk.length; k += 1) {
+      const nl = buf.indexOf(0x0a, at);
+      if (nl === -1) return null;
+      const header = buf.subarray(at, nl).toString("utf8");
+      at = nl + 1;
+      if (header.endsWith(" missing")) {
+        out.push(null);
+        continue;
+      }
+      const [, type, sizeText] = header.split(" ");
+      const size = Number(sizeText);
+      if (type !== "blob" || !Number.isInteger(size) || at + size > buf.length) return null;
+      out.push(buf.subarray(at, at + size).toString("utf8"));
+      at += size + 1;
+    }
+  }
+  return out;
+}
+
+interface StableVersion {
+  readonly sha: string;
+  readonly committedAt: string;
+  readonly generatedAt: number;
+  /** The stamp as that version spelled it, so the refusal quotes the file rather than a re-rendering. */
+  readonly stamp: string;
+  readonly body: string;
+}
+
+/** Line endings are the checkout's and a trailing blank line is nobody's edit; everything else is the text. */
+function comparable(body: string): string {
+  return normalizeText(body).trimEnd();
+}
+
+/**
+ * A committed version as a stable, stamped text — or null: a draft's body is
+ * free, and a version the profile cannot read (no fence, broken YAML, no
+ * `generated.at`) was never a stable version under the profile.
+ */
+function stableVersionOf(version: CommittedVersion, path: string): StableVersion | null {
+  const split = splitFrontmatter(version.text, path);
+  if (!split.ok || split.frontmatter === null || split.frontmatter["status"] !== "stable") {
+    return null;
+  }
+  const generated = split.frontmatter["generated"];
+  if (typeof generated !== "object" || generated === null) return null;
+  const at = (generated as Readonly<Record<string, unknown>>)["at"];
+  if (typeof at !== "string") return null;
+  const generatedAt = parseInstant(at);
+  if (generatedAt === null) return null;
+  return {
+    sha: version.sha,
+    committedAt: version.committedAt,
+    generatedAt,
+    stamp: at,
+    body: comparable(split.body),
+  };
+}
+
+/**
+ * The rule, pure: for every `stable` concept whose body differs from a
+ * committed version that was `stable`, the tree's `generated.at` must be
+ * strictly LATER than that version's. Equal is the defect this rule exists to
+ * catch — edit the sentence, leave the stamp — and EARLIER is the same defect
+ * with one more keystroke: backdating the stamp changes it without advancing
+ * it, so the approval that ratified the old text still post-dates the new one.
+ * Only strictly-later clears a version, which is exactly what the refusal's
+ * own `fix` prints. All of history, not only HEAD's version — an edit
+ * committed without a bump matches HEAD exactly, and it is the version BEHIND
+ * it that tells (the shape CI sees). A path with no committed stable version
+ * passes: stable for the first time, or renamed, since path is identity.
+ * Instants are compared as instants, so two spellings of one moment are one
+ * stamp.
+ */
+export function checkGeneratedStale(
+  concepts: readonly Concept[],
+  files: ReadonlyMap<string, string>,
+  versions: ReadonlyMap<string, readonly CommittedVersion[]>,
+): Refusal[] {
+  const refusals: Refusal[] = [];
+  for (const concept of concepts) {
+    if (concept.status !== "stable" || concept.generatedAt === null) continue;
+    const text = files.get(concept.path);
+    if (text === undefined) continue;
+    const split = splitFrontmatter(text, concept.path);
+    if (!split.ok) continue;
+    const body = comparable(split.body);
+    for (const version of versions.get(concept.path) ?? []) {
+      const stable = stableVersionOf(version, concept.path);
+      if (stable === null || stable.generatedAt < concept.generatedAt || stable.body === body) {
+        continue;
+      }
+      const authored = (concept.frontmatter["generated"] as { readonly at?: unknown } | undefined)
+        ?.at;
+      const stamp =
+        typeof authored === "string" ? authored : new Date(concept.generatedAt).toISOString();
+      const under =
+        stable.generatedAt === concept.generatedAt
+          ? `under the same \`generated.at\` (${stamp})`
+          : `under \`generated.at\` ${stable.stamp}, LATER than the ${stamp} this file now carries ` +
+            "(the stamp was moved backward, which changes it without advancing it)";
+      refusals.push({
+        slug: "ksor-generated-stale",
+        path: concept.path,
+        why:
+          `the body differs from the one committed at ${stable.sha.slice(0, 7)} (${stable.committedAt}), ` +
+          `where this concept was \`stable\` ${under} — that instant dates ` +
+          "the text, so an edit to a stable concept must advance it, or the approval that ratified the old " +
+          "text reads as ratifying the new one (KSP R23)",
+        fix:
+          "set `generated.at` to an instant after this edit, then re-approve: `ksor.approval.at` must not " +
+          "precede the new `generated.at` (`ksor-generated-after-approval`)",
+      });
+      break;
+    }
+  }
+  return refusals;
+}
+
+export interface ChangeControl {
+  readonly refusals: readonly Refusal[];
+  /**
+   * Why the check could not run, or ran short — printed beside the verdict,
+   * never swallowed. Null when every committed version was read.
+   */
+  readonly notice: string | null;
+}
+
+/** The two callers' one entry: read history for the stable concepts, judge, and say what could not be read. */
+export function checkChangeControl(
+  root: string,
+  concepts: readonly Concept[],
+  files: ReadonlyMap<string, string>,
+): ChangeControl {
+  const paths = concepts.filter((c) => c.status === "stable").map((c) => c.path);
+  const history = committedVersions(root, paths);
+  const refusals =
+    history.versions === null ? [] : checkGeneratedStale(concepts, files, history.versions);
+  return { refusals, notice: changeControlNotice(history) };
+}
+
+/**
+ * Honest absence in the build's own idiom — the `source: unspecified` line
+ * already says the commit is unknown; this says the same of the check that
+ * needs one. A check that could not run is never a check that passed.
+ */
+function changeControlNotice(history: CommittedHistory): string | null {
+  const what =
+    "so whether a stable concept's body changed under its `generated.at` (KSP R23) was not checked";
+  if (!history.repository) {
+    return `change-control: not checked — knowledge/ is not in a git repository (or git is not installed), ${what}`;
+  }
+  if (!history.born) {
+    return `change-control: not checked — the repository has no commits yet, ${what}`;
+  }
+  if (history.versions === null) {
+    return `change-control: not checked — git could not read the history of knowledge/ (\`git log -- knowledge/\` or \`git cat-file --batch\` failed), ${what}`;
+  }
+  if (history.shallow) {
+    const read = [...history.versions.values()].reduce((n, list) => n + list.length, 0);
+    return (
+      `change-control: checked against the ${read} committed version(s) this shallow clone holds — a stable ` +
+      "version beyond the shallow boundary was not read; fetch full history (`git fetch --unshallow`; in CI, " +
+      "`fetch-depth: 0`) to check all of it"
+    );
+  }
+  return null;
+}

package/templates/scaffold/system/site/record/index.ts

@@ -72,6 +72,14 @@ export {
   type Drafts,
 } from "./lock";
 export { git, historicLedger, type HistoricLedger } from "./git-ledger";
+export {
+  checkChangeControl,
+  checkGeneratedStale,
+  committedVersions,
+  type ChangeControl,
+  type CommittedHistory,
+  type CommittedVersion,
+} from "./change-control";
 export { generateIndexes, parseIndex, humanise, type IndexInput } from "./index-file";
 export { actorKind, isIndividualActor } from "./actor";
 export { checkFootnotes, linkTargets, resolveLink } from "./citations";

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

@@ -33,6 +33,9 @@ export type Drafts = "hidden" | "shown";
 
 const hex64 = z.string().regex(/^[0-9a-f]{64}$/, "a sha256 hex digest");
 const viewerList = z.array(z.string().min(1));
+const bundleEntry = z
+  .object({ viewer: z.string().min(1), sha256: hex64, files: z.number().int().nonnegative() })
+  .strict();
 
 const lockSchema = z
   .object({
@@ -66,9 +69,22 @@ const lockSchema = z
     companions: z.array(z.object({ path: z.string().min(1), sha256: hex64 }).strict()),
     assets: z.array(z.object({ path: z.string().min(1), sha256: hex64 }).strict()),
     indexes: z.array(z.object({ path: z.string().min(1), sha256: hex64 }).strict()),
+    bundles: z.array(bundleEntry),
   })
   .strict();
 
+/**
+ * One OKF bundle, as `ksor build --bundles` writes it for a canonical viewer
+ * (build spec §1 step 4): the digest is sha256 over the JSON of the bundle's
+ * sorted `[path, sha256]` pairs, so a recipient holding only the directory can
+ * recompute it and find the publication it came from.
+ */
+export interface LockBundle {
+  readonly viewer: string;
+  readonly sha256: string;
+  readonly files: number;
+}
+
 export interface LockDocument {
   /** Bundle-relative, with `.md`. */
   readonly path: string;
@@ -116,6 +132,24 @@ export interface Lock {
    * stopped short of the file that lists what was published.
    */
   readonly indexes: readonly { readonly path: string; readonly sha256: string }[];
+  /**
+   * One digest per canonical viewer, recorded on EVERY build and not only when
+   * `--bundles` wrote the directories: the bundle set is a function of what
+   * `build_id` already hashes, so the lock is the same lock either way, and a
+   * `pnpm build` on a host that never passes the flag records the same digests
+   * the owner's `--bundles` run did. Outside `build_id` for the same reason —
+   * the documents, their admitted sets, the companions, the assets and the
+   * instance title are already in it, so hashing the bundles again could not
+   * move it (build spec §2). Listed so a directory can be MATCHED to a
+   * publication, not to widen what the id covers. Required on read like every
+   * other field, and NOT read around: a lock an older ksor wrote lacks the key,
+   * so `ksor build` refuses it as `ksor-lock-invalid` and says to delete it —
+   * it does not regenerate one it cannot read, because the lock is also a
+   * takedown baseline and a lock nothing can read is a baseline that quietly
+   * holds nothing. `ksor migrate` offers that deletion, which is the migration
+   * decision 28 pairs the removal with.
+   */
+  readonly bundles: readonly LockBundle[];
 }
 
 export type LockResult =
@@ -254,6 +288,8 @@ export interface LockInput {
   /** Bundle-relative path → the §8 index text this build generated (`index.md`, `policies/index.md`). */
   readonly indexes: readonly { readonly path: string; readonly text: string }[];
   readonly denials: readonly Denial[];
+  /** The digest of each canonical viewer's bundle, in the order `canonicalViewers` lists them. */
+  readonly bundles: readonly LockBundle[];
 }
 
 export function composeLock(input: LockInput): Lock {
@@ -310,6 +346,7 @@ export function composeLock(input: LockInput): Lock {
     companions,
     assets,
     indexes,
+    bundles: input.bundles.map((b) => ({ viewer: b.viewer, sha256: b.sha256, files: b.files })),
   };
 }
 

package/templates/scaffold/system/site/record/refusal.ts

@@ -16,6 +16,7 @@ export const REFUSAL_SLUGS = [
   "ksor-stable-unapproved",
   "ksor-approver-unauthorised",
   "ksor-generated-after-approval",
+  "ksor-generated-stale",
   "ksor-deprecated-unattributed",
   "ksor-deprecator-unauthorised",
   "ksor-reserved-type-unsourced",