@panaversity/ksor 0.0.39 → 0.0.41

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

@@ -0,0 +1,214 @@
+/**
+ * What makes a blockquote a CALLOUT: GitHub's alert syntax, unchanged.
+ *
+ *     > [!WARNING]
+ *     > A withdrawn document is still cited by answers that were given while
+ *     > it was published.
+ *
+ * The reason this syntax and not `:::warning`: a blockquote is CommonMark. The
+ * record is CommonMark by rule (critical rule 3 keeps `knowledge/` free of any
+ * grammar a plain markdown reader has to learn), and this one is already read
+ * by the two places a record is looked at OUTSIDE this site — GitHub renders it
+ * as a styled alert, and every other viewer renders an ordinary blockquote
+ * carrying a visible `[!WARNING]` label. Nobody is misled and nothing is lost.
+ * A `:::` directive is a grammar: it renders as the literal characters, and it
+ * would reach `/md/`, `llms.txt` and `llms-full.txt`, where an agent would have
+ * to know our dialect to read the record.
+ *
+ * The set is GitHub's five, exactly. Adding a sixth would mean a record that
+ * renders here and not there, which is the whole thing this choice buys.
+ *
+ * A LEAF: no imports, so the remark plugin and the tests share one rule.
+ */
+
+/**
+ * GitHub's marker -> the fumadocs Callout it becomes.
+ *
+ * `type` is one of fumadocs' `CalloutType` (`info` | `warn` | `error` |
+ * `success` | `warning` | `idea`); anything else renders as plain `info` with
+ * nothing going red, so these are checked against the shipped page.
+ *
+ * NOTE and IMPORTANT share `info` because fumadocs has no fifth colour, and
+ * inventing one would drift from GitHub. The `title` is what tells them apart,
+ * which is also how GitHub distinguishes them.
+ */
+export const ALERT_KINDS = [
+  { marker: "NOTE", type: "info", title: "Note" },
+  { marker: "TIP", type: "idea", title: "Tip" },
+  { marker: "IMPORTANT", type: "info", title: "Important" },
+  { marker: "WARNING", type: "warn", title: "Warning" },
+  { marker: "CAUTION", type: "error", title: "Caution" },
+] as const;
+
+export type AlertKind = (typeof ALERT_KINDS)[number];
+
+export interface AlertMatch {
+  readonly kind: AlertKind;
+  /** What is left of the leading text once the marker's own line is removed. */
+  readonly rest: string;
+}
+
+/**
+ * The alert this blockquote opens with, or null when it is an ordinary quote.
+ *
+ * `leadingText` is the value of the first text node of the blockquote's first
+ * paragraph — the marker has to be the very start of the quote, and has to be
+ * the WHOLE of its first line. Both are GitHub's rules, and following them is
+ * the point: a quote that renders as a callout here and as a quote there would
+ * make the site and the record disagree about the same bytes.
+ *
+ * Case-insensitive, because GitHub accepts `[!note]` and rendering it plain
+ * here would be exactly that disagreement.
+ */
+export function matchAlert(leadingText: string): AlertMatch | null {
+  if (!leadingText.startsWith("[!")) return null;
+
+  const close = leadingText.indexOf("]");
+  if (close === -1) return null;
+
+  const marker = leadingText.slice(2, close).toUpperCase();
+  const kind = ALERT_KINDS.find((entry) => entry.marker === marker);
+  if (!kind) return null;
+
+  const after = leadingText.slice(close + 1);
+  const newline = after.indexOf("\n");
+  const restOfLine = newline === -1 ? after : after.slice(0, newline);
+  // Anything else on the marker's line means the author wrote a quote that
+  // happens to start with a bracket, not an alert.
+  if (restOfLine.trim() !== "") return null;
+
+  return { kind, rest: newline === -1 ? "" : after.slice(newline + 1) };
+}
+
+/**
+ * The cases the rule is held to.
+ *
+ * A table rather than prose assertions, because the interesting half is what
+ * this must REFUSE: every refusal here is a blockquote an author wrote meaning
+ * a blockquote, and turning one into a coloured panel is a change to the
+ * record's meaning that nothing else would catch.
+ */
+export const ALERT_CASES = [
+  // The five, as GitHub documents them.
+  { text: "[!NOTE]\nThe record is the source of truth.", type: "info", title: "Note" },
+  { text: "[!TIP]\nStart at level 0.", type: "idea", title: "Tip" },
+  { text: "[!IMPORTANT]\nCitations pin a generation.", type: "info", title: "Important" },
+  { text: "[!WARNING]\nThis document is superseded.", type: "warn", title: "Warning" },
+  { text: "[!CAUTION]\nA takedown does not unsay an answer.", type: "error", title: "Caution" },
+  // Lowercase renders as an alert on GitHub, so it renders as one here.
+  { text: "[!note]\nStill an alert.", type: "info", title: "Note" },
+  { text: "[!Warning]\nStill an alert.", type: "warn", title: "Warning" },
+  // The marker alone, with the body in later nodes or later blocks.
+  { text: "[!NOTE]", type: "info", title: "Note" },
+  { text: "[!NOTE]\n", type: "info", title: "Note" },
+  // Trailing spaces on the marker's line are invisible; they may not decide.
+  { text: "[!NOTE]   \nBody.", type: "info", title: "Note" },
+  // Ordinary blockquotes, which must stay blockquotes.
+  { text: "A quote about something.", type: null, title: null },
+  { text: "[!NOTES]\nNot a marker.", type: null, title: null },
+  { text: "[!]\nEmpty marker.", type: null, title: null },
+  { text: "[NOTE]\nNo bang.", type: null, title: null },
+  { text: " [!NOTE]\nLeading space.", type: null, title: null },
+  { text: "[!NOTE\nUnclosed.", type: null, title: null },
+  // The marker has to own its line. Text beside it means the author quoted it.
+  { text: "[!NOTE] see below", type: null, title: null },
+  { text: "[!NOTE] see below\nBody.", type: null, title: null },
+] as const;
+
+/**
+ * The slice of hast this touches, written structurally rather than imported.
+ *
+ * `@types/hast` would be a dependency for five field names, and this only ever
+ * reads `type`/`tagName`, walks `children`, and edits the `value` of a text
+ * node. Typing what is used keeps this file a leaf.
+ */
+interface AlertNode {
+  type: string;
+  tagName?: string;
+  children?: AlertNode[];
+  value?: string;
+  name?: string;
+  attributes?: { type: "mdxJsxAttribute"; name: string; value: string }[];
+}
+
+/**
+ * The `<Callout>` this blockquote becomes, or null when it stays a blockquote.
+ *
+ * Mutates the quote's own first paragraph to drop the marker line — the marker
+ * is syntax, and leaving it in the rendered panel would show the reader the
+ * plumbing.
+ */
+function calloutFor(node: AlertNode): AlertNode | null {
+  if (node.type !== "element" || node.tagName !== "blockquote") return null;
+
+  // hast keeps the source's whitespace between block children, so the first
+  // paragraph is the first ELEMENT rather than the first child.
+  const paragraph = node.children?.find((child) => child.type === "element");
+  if (!paragraph || paragraph.tagName !== "p") return null;
+
+  const lead = paragraph.children?.[0];
+  if (!lead || lead.type !== "text" || typeof lead.value !== "string") return null;
+
+  const match = matchAlert(lead.value);
+  if (!match) return null;
+
+  if (match.rest === "") {
+    // The marker was the whole text node. Drop it, and drop the paragraph too
+    // when the marker was all it held — `> [!NOTE]` on a line of its own.
+    paragraph.children?.shift();
+    if (paragraph.children?.length === 0) {
+      node.children = node.children?.filter((child) => child !== paragraph);
+    }
+  } else {
+    lead.value = match.rest;
+  }
+
+  return {
+    type: "mdxJsxFlowElement",
+    name: "Callout",
+    attributes: [
+      { type: "mdxJsxAttribute", name: "type", value: match.kind.type },
+      { type: "mdxJsxAttribute", name: "title", value: match.kind.title },
+    ],
+    children: node.children ?? [],
+  };
+}
+
+/** Depth-first, so an alert nested inside a list or another quote converts. */
+function convertAlerts(node: AlertNode): void {
+  const children = node.children;
+  if (!children) return;
+
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i];
+    if (!child) continue;
+    convertAlerts(child);
+    const callout = calloutFor(child);
+    if (callout) children[i] = callout;
+  }
+}
+
+/**
+ * REHYPE, deliberately — and this is the load-bearing half of the design.
+ *
+ * As a remark plugin this works and is wrong: fumadocs serializes the record's
+ * markdown from the mdast (`includeProcessedMarkdown` -> `remarkLLMs`), so a
+ * blockquote rewritten there reaches `/md/` and `llms-full.txt` as
+ * `<Callout type="warn" title="Warning">` — the agent surface served this
+ * site's React component in place of the author's blockquote. Measured, not
+ * assumed: that is exactly what the first build of this emitted.
+ *
+ * By the rehype phase the markdown is already captured, so the page gets the
+ * callout and every agent-facing surface keeps the record's own shape. This is
+ * product principle 2 — one source, two surfaces — and the reason the syntax
+ * is GitHub's rather than a directive in the first place.
+ *
+ * The cost, recorded because it is real: `remarkStructure` also runs in the
+ * remark phase, so the search index contains the literal `[!NOTE]` alongside
+ * the passage. Noise in one index is the cheaper half of this trade.
+ */
+export function rehypeGithubAlerts(): (tree: AlertNode) => void {
+  return (tree: AlertNode): void => {
+    convertAlerts(tree);
+  };
+}

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

@@ -110,7 +110,12 @@ export const ATTACHMENT_CASES = [
   { name: "returns.flashcards.yaml", kind: "deck", parent: "returns.md" },
   { name: "returns.quiz.yaml", kind: "quiz", parent: "returns.md" },
   { name: "returns.slides.yaml", kind: "slides", parent: "returns.md" },
-  { name: "index.summary.md", kind: "summary", parent: "index.md" },
+  // No `index.summary.md` row: `index.md` is GENERATED (record spec §1) — no
+  // route, no node, no governance of its own — so nothing attaches to it, and
+  // decision 27 retires this row with the authored index. The NAME is still an
+  // attachment by this rule (it has a stem and a known suffix); what refuses it
+  // is `ksor-attachment-of-index` in the checker, which is where "who may be a
+  // parent" belongs — this file only answers "is this name an attachment".
   // A stem containing dots keeps every one of them: the parent is the same
   // name with the attachment suffix removed, never "up to the first dot".
   { name: "v1.2.policy.summary.md", kind: "summary", parent: "v1.2.policy.md" },

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

@@ -1,8 +1,6 @@
 import { decks, quizzes, slides, summaries } from "collections/server";
 
-import { ATTACHMENT_SUFFIXES } from "./attachment-rule";
 import { cardHash, type Card, type Deck } from "./deck";
-import { newCard, type CardSchedule } from "./srs";
 import { type Question, type Quiz } from "./quiz";
 import { type Slide, type Slides } from "./slides";
 import { embedUrlFor, providerOf } from "./slides-embed";
@@ -162,29 +160,3 @@ export function slidesFor(documentPath: string): SlidesEntry | null {
     path: parsed.info.path,
   };
 }
-
-/** True when a document has ANY attachment — the presence gate for the UI. */
-export function hasAttachments(documentPath: string): boolean {
-  return (
-    summaryFor(documentPath) !== null ||
-    deckFor(documentPath) !== null ||
-    quizFor(documentPath) !== null ||
-    slidesFor(documentPath) !== null
-  );
-}
-
-/**
- * A fresh schedule for every card in a deck, all due now.
- *
- * Exported so the deck's first render and its reset path agree by construction
- * rather than by two similar-looking object literals.
- */
-export function freshSchedules(
-  cards: readonly DeckCard[],
-  now: number,
-): Record<string, CardSchedule> {
-  return Object.fromEntries(cards.map((card) => [card.hash, newCard(card.hash, now)]));
-}
-
-/** Every attachment suffix, for the surfaces that need the list rather than the rule. */
-export const ATTACHMENT_SUFFIX_LIST: readonly string[] = ATTACHMENT_SUFFIXES.map((e) => e.suffix);

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

@@ -16,29 +16,23 @@
  * this file is the shared implementation of the TypeScript half.
  */
 
-export interface AudienceModel {
-  /** Least- to most-restricted, `public` first. */
-  readonly audiences: readonly string[];
-  /** The tier of a document that declares no `visibility:`. */
-  readonly defaultVisibility: string;
+/**
+ * The overlap rule (record spec §2.4): a concept holds a LIST of audience
+ * identifiers, a viewer holds a list that always includes `public`, and the
+ * concept is visible when the two overlap. Rank moves to the viewer,
+ * membership stays on the document. Omission is a refusal upstream, never a
+ * default here — an empty list on either side is visible to nobody.
+ */
+export function overlaps(viewer: readonly string[], audience: readonly string[]): boolean {
+  return audience.some((a) => viewer.includes(a));
 }
 
 /**
- * May a build FOR `audience` publish a document of this `visibility`?
- *
- * `model === null` is a record that declares no audience model: nothing to
- * filter, everything publishes — the level-0 shape.
+ * The widening rule: a link, a `ksor.superseded_by` pointer or a companion
+ * body may reach a target whose audience contains `public` or contains every
+ * identifier in the source's — then every reader of the source can read the
+ * target. `[internal]` → `[public]` passes; `[public]` → `[internal]` refuses.
  */
-export function decideVisible(
-  model: AudienceModel | null,
-  audience: string,
-  visibility: string | null,
-): boolean {
-  if (model === null) return true;
-  const value = visibility === null || visibility === "" ? model.defaultVisibility : visibility;
-  const rank = model.audiences.indexOf(value);
-  // An undeclared visibility is refused, never published: a value no build
-  // understands is a typo, and a typo reads as a restriction.
-  if (rank === -1) return false;
-  return rank <= model.audiences.indexOf(audience);
+export function mayReach(source: readonly string[], target: readonly string[]): boolean {
+  return target.includes("public") || source.every((a) => target.includes(a));
 }

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

@@ -1,168 +1,64 @@
-import { decideVisible, type AudienceModel } from "./audience-rule";
-import { instanceFrontmatter } from "./shared";
-
 /**
- * The audience model, declared in instance.md — the record says who its
- * readers are, and the build enforces it:
+ * The viewer this build publishes for (record spec §2.4, build spec §3).
+ *
+ * A concept holds a LIST of audience identifiers; a viewer holds a list that
+ * always includes `public`; the concept is visible when the two overlap. The
+ * rule itself is `overlaps` in `./audience-rule` — the kernel's copy, asserted
+ * byte-identical — and this module only reads the viewer from the environment:
  *
- *     audiences:
- *       - public
- *       - internal
- *       - restricted
- *     default_visibility: public
+ *     KSOR_AUDIENCE=public,internal pnpm build
  *
- * Ordered least- to most-restricted, so "build the internal site" means
- * "public and internal included" with no further configuration. A record
- * that declares no audiences has no model and publishes every document —
- * the behaviour of every instance written before this key existed.
+ * Unset means `[public]`, the only default that cannot leak. Whether each
+ * identifier is REGISTERED is the staging's question, because the registry
+ * lives in the policy (or the lock) and this module reads neither.
  */
-export type { AudienceModel };
-export { decideVisible };
-
-function unquote(raw: string): string {
-  const trimmed = raw.trim();
-  return /^(['"])(.*)\1$/.exec(trimmed)?.[2] ?? trimmed;
-}
 
-/** Every refusal this feature makes: a slug a pipeline can match, then the remedy. */
+/** Every refusal the site makes: a slug a pipeline can match, then the remedy. */
 export function refuse(slug: string, what: string, why: string, fix: string): never {
   // The slug leads, so a pipeline can match on it, and the three lines below
   // it are the whole remedy — an operator never has to read this file.
   throw new Error(`${slug}: ${what}\n  why: ${why}\n  fix: ${fix}`);
 }
 
-function readAudienceModel(): AudienceModel | null {
-  const block = instanceFrontmatter();
-  // Top-level key only: `^` under /m cannot match an indented child.
-  if (!/^audiences:/m.test(block)) return null;
-
-  // The grammar mirrors the checker's exactly — CRLF-tolerant, list items at
-  // ANY indent (YAML allows unindented block sequences), and a ` #` comment
-  // ends an unquoted entry (all three found live 2026-08-18: records the
-  // checker blessed either failed this build or silently lost a tier).
-  const stripComment = (value: string): string =>
-    /^["']/.test(value.trim()) ? value : value.replace(/\s+#.*$/, "");
-  // A line scanner, not a block regex: a blank line among the items or a
-  // comment on the key line broke the block capture and refused every build
-  // of a checker-green record (review finding, 2026-08-19).
-  const flow = /^audiences:[ \t]*\[(.*)\][ \t]*(?:#.*)?$/m.exec(block)?.[1];
-  let items: string[] = [];
-  if (flow !== undefined) {
-    items = flow.split(",");
-  } else {
-    const lines = block.split("\n");
-    const start = lines.findIndex((line) => /^audiences:[ \t]*(?:#.*)?$/.test(line));
-    if (start !== -1) {
-      for (const line of lines.slice(start + 1)) {
-        if (line.trim() === "") continue;
-        const item = /^[ \t]*-[ \t]+(.*)$/.exec(line);
-        if (item === null) break;
-        items.push(item[1] ?? "");
-      }
-    }
-  }
-  const audiences = items
-    .map(stripComment)
-    .map(unquote)
-    .filter((value) => value !== "");
-
-  // A declared-but-unreadable model must never read as "no model": that is
-  // the one parse failure that publishes the whole record.
-  if (audiences.length === 0) {
-    refuse(
-      "ksor-audiences-unreadable",
-      "instance.md declares `audiences:` but no audience could be read from it",
-      "an unreadable model reads as no model, and no model publishes every document — the one parse failure that leaks",
-      "write the audiences as a list, least-restricted first:\n    audiences:\n      - public\n      - internal",
-    );
-  }
+let resolved: readonly string[] | null = null;
 
-  // The staging never depends on the checker having run: a
-  // most-restrictive-first model would make plain `pnpm build` publish
-  // every restricted document with no label (review finding, 2026-08-18).
-  if (audiences[0] !== "public") {
-    refuse(
-      "ksor-audiences-misordered",
-      `audiences: must start with public (it starts with "${audiences[0]}")`,
-      "the list is ordered least- to most-restricted, and an unset KSOR_AUDIENCE builds the FIRST entry — any other first entry makes the default build the leak",
-      "reorder audiences: with public first",
-    );
-  }
-  if (new Set(audiences).size !== audiences.length) {
-    refuse(
-      "ksor-audiences-duplicate",
-      `audiences: declares a tier twice (${audiences.join(", ")})`,
-      "a duplicated tier has two positions in the ordering, and which one a build honours is undefined",
-      "remove the duplicate entry",
-    );
-  }
-  const defaultVisibility = unquote(
-    stripComment(/^default_visibility:[ \t]*(.*)$/m.exec(block)?.[1] ?? ""),
-  );
-  if (defaultVisibility === "") {
-    refuse(
-      "ksor-default-visibility-missing",
-      "instance.md declares `audiences:` without `default_visibility:`",
-      "there is no safe guess: assuming the widest tier leaks on the first document that forgets the key, assuming the narrowest hides the record",
-      `add the tier a document without a visibility: key belongs to, e.g. default_visibility: ${audiences[0]}`,
-    );
-  }
-  if (!audiences.includes(defaultVisibility)) {
-    refuse(
-      "ksor-default-visibility-undeclared",
-      `default_visibility: ${defaultVisibility} is not one of the declared audiences (${audiences.join(", ")})`,
-      "every document without a visibility: key belongs to this tier — a tier no build understands is a record no build can publish honestly",
-      `set default_visibility: to one of ${audiences.join(", ")}, or declare ${defaultVisibility} in audiences:`,
-    );
-  }
-
-  return { audiences, defaultVisibility };
+/**
+ * The viewer list, `public` always among it. A function rather than a
+ * module constant so the refusal is raised where staging can clean up after
+ * it: thrown at import time it escaped the stage lock and left the previous,
+ * wider stage on disk (found by the staging suite, 2026-08-25).
+ */
+export function viewer(): readonly string[] {
+  if (resolved === null) resolved = readViewer();
+  return resolved;
 }
 
-/** The declared model, or null when this record declares none. */
-export const audienceModel: AudienceModel | null = readAudienceModel();
-
-function resolveBuildAudience(model: AudienceModel | null): string {
-  const requested = process.env.KSOR_AUDIENCE?.trim() ?? "";
-  if (model === null) {
-    if (requested !== "") {
-      refuse(
-        "ksor-audiences-not-declared",
-        `KSOR_AUDIENCE="${requested}" was requested, but instance.md declares no audiences`,
-        "this build would publish every document — a build that cannot filter must never look like one that did",
-        "declare the model in instance.md (audiences: + default_visibility:), or build without KSOR_AUDIENCE",
-      );
-    }
-    return "";
-  }
-  // Unset means the least-restricted tier: the only default that cannot leak,
-  // so `pnpm build` keeps publishing the public site out of the box.
-  if (requested === "") return model.audiences[0] as string;
-  if (!model.audiences.includes(requested)) {
+function readViewer(): readonly string[] {
+  const raw = process.env.KSOR_AUDIENCE?.trim() ?? "";
+  if (raw === "") return ["public"];
+  const list = raw
+    .split(",")
+    .map((item) => item.trim())
+    .filter((item) => item !== "");
+  if (!list.includes("public")) {
     refuse(
-      "ksor-audience-undeclared",
-      `KSOR_AUDIENCE="${requested}" is not an audience this record declares (${model.audiences.join(", ")})`,
-      "an unrecognized audience could only be honoured by publishing more than the record names — so it refuses instead of widening",
-      `build with one of ${model.audiences.join(", ")}, or add "${requested}" to instance.md's audiences: list`,
+      "ksor-viewer-omits-public",
+      `KSOR_AUDIENCE="${raw}" does not include public`,
+      "a viewer list always includes public — every reader of a restricted build is also a reader of the open one, and a build for a restricted audience alone would silently drop every public concept",
+      `build with KSOR_AUDIENCE=public,${list.join(",")}`,
     );
   }
-  return requested;
-}
-
-/** The audience this build publishes for; "" when the record has no model. */
-export const buildAudience: string = resolveBuildAudience(audienceModel);
-
-/** Whether a document of this visibility belongs in THIS build. */
-export function visibleInBuild(visibility: string | null): boolean {
-  return decideVisible(audienceModel, buildAudience, visibility);
+  return [...new Set(list)];
 }
 
 /**
- * What a non-public build calls itself, in the site chrome — so a leaked
- * screenshot of an internal site says which audience it was built for. The
- * public build (the least-restricted tier) says nothing new.
+ * What a restricted build calls itself, in the site chrome — so a leaked
+ * screenshot of an internal site says which audiences it was built for. The
+ * public build says nothing new.
  */
-export const audienceNotice: string | null =
-  audienceModel === null || buildAudience === audienceModel.audiences[0]
+export function audienceNotice(): string | null {
+  const list = viewer();
+  return list.length === 1
     ? null
-    : `${buildAudience} build — not for publication`;
+    : `${list.filter((a) => a !== "public").join(", ")} build — not for publication`;
+}