@panaversity/ksor 0.0.28 → 0.0.30

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

@@ -0,0 +1,55 @@
+/**
+ * Identity for authored text: the hash, and what a question hashes.
+ *
+ * FNV-1a, 32-bit, hand-rolled — the site has no crypto import at build time and
+ * this has to produce the same value in the browser, where the saved progress
+ * it keys actually lives. A collision costs one card's or one question's saved
+ * state, never correctness, so 32 bits is the right size of hammer.
+ *
+ * Extracted so the deck and the quiz share ONE implementation. Two hand-rolled
+ * copies of a hash is the kind of duplication that stays identical right up
+ * until someone fixes a separator in one of them.
+ *
+ * A LEAF, and it has to stay one. This repo can only unit-test a scaffold
+ * module with no relative imports: `tsc` under node16 resolution demands a
+ * `.js` specifier, and Next's bundler in the scaffold cannot resolve that back
+ * to a `.ts` file — so a scaffold module that imports a sibling either fails
+ * the typecheck or fails the site build. `questionHash` therefore lives here
+ * beside the hash it calls rather than in a file of its own.
+ */
+
+/**
+ * The separator between parts, written as an escape rather than embedded: a raw
+ * NUL in the source makes git treat the file as binary.
+ *
+ * A separator is load-bearing. Without one, `["ab", "c"]` and `["a", "bc"]`
+ * hash identically, and NUL is the one character authored text cannot contain.
+ */
+const SEPARATOR = "\u0000";
+
+/** Hash these parts as one identity. */
+export function textHash(parts: readonly string[]): string {
+  const text = parts.join(SEPARATOR);
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i += 1) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+
+/**
+ * A question's identity: a hash of the text the reader actually sees.
+ *
+ * The stem AND the options, deliberately including their ORDER — reordering
+ * changes which index is correct, so a saved answer would otherwise be
+ * re-scored against a different question and silently become right or wrong.
+ * `explanation` and `source` are excluded: they teach ABOUT the question
+ * rather than being it, so improving an explanation costs the reader nothing.
+ */
+export function questionHash(question: {
+  readonly question: string;
+  readonly options: readonly string[];
+}): string {
+  return textHash([question.question, ...question.options]);
+}

package/templates/scaffold/system/site/lib/quiz-audit.ts

@@ -0,0 +1,306 @@
+/**
+ * Mechanical hygiene checks for a quiz, run before it can be published.
+ *
+ * Carried from the predecessor's `scripts/quiz-audit/` under decision 6, and
+ * carried because of what its own README records: these bugs SHIPPED and were
+ * found by students rather than by the project — every correct answer at
+ * position A across 9 quizzes and 451 questions, explanations dismissing their
+ * own marked answer, and the correct option systematically the longest. Its
+ * `findings-2026-04-14.txt` still reports 88% pick-longest in one file, which
+ * is the argument for running this in the build instead of on request: the
+ * script existed, and the findings sat.
+ *
+ * What is NOT carried is its thresholds. It targets a 15-35% distribution,
+ * which a five-question bank cannot satisfy without the checker dictating the
+ * answers. These are floors against the shipped bug, not a distribution target
+ * — see MIN_BANK_FOR_RATIOS.
+ *
+ * Verified against the predecessor's real data before shipping (2026-08-23):
+ * run over the 18 parsed questions of its `11-chapter-quiz.md`, this reports
+ * 67% of answers at option C and 78% pick-longest — both real, both shipped,
+ * and both the exact class its README says students found rather than the
+ * project. A rule that fires only on fixtures would not have earned this.
+ *
+ * A LEAF: no imports, so the site's build and the record's checker can both
+ * hold this rule without either taking the other's dependencies.
+ */
+
+/** One question, in the shape the audit needs — a structural subset of the schema. */
+export interface AuditQuestion {
+  readonly question: string;
+  readonly options: readonly string[];
+  readonly answer: number;
+  readonly explanation?: string | undefined;
+}
+
+export interface AuditQuiz {
+  readonly quiz: { readonly title: string };
+  readonly questions: readonly AuditQuestion[];
+}
+
+export interface QuizFinding {
+  readonly slug: string;
+  /** 1-based question numbers, so a human can find them in the file. */
+  readonly questions: readonly number[];
+  /** What was measured, with the number that failed. */
+  readonly detail: string;
+}
+
+export const QUIZ_AUDIT_SLUGS = [
+  "ksor-quiz-answer-bias",
+  "ksor-quiz-length-bias",
+  "ksor-quiz-answer-run",
+  "ksor-quiz-contradiction",
+  "ksor-quiz-duplicate-stem",
+] as const;
+
+/**
+ * Below this many questions the ratio checks do not run.
+ *
+ * A four-question bank cannot spread answers across four indices without the
+ * checker deciding which option is correct, and a record's answers are the
+ * record's business. The run and contradiction checks have no such floor —
+ * they are wrong at any size.
+ */
+export const MIN_BANK_FOR_RATIOS = 5;
+/** Above this share of answers on one index, the reader can guess. */
+export const MAX_INDEX_SHARE = 0.6;
+/** Above this share, "always pick the longest" is a winning strategy. */
+export const MAX_STRATEGY_WIN = 0.6;
+/** A run this long reads as a pattern rather than as chance. */
+export const MAX_SAME_ANSWER_RUN = 3;
+/** Two stems sharing this much of their opening are the same question twice. */
+export const STEM_PREFIX = 60;
+
+/** Letters for the dismissal check: `answer: 0` is spoken about as "A". */
+const LETTERS = "ABCDEFGH";
+
+/**
+ * Phrases that dismiss an option, paired with how an author names it.
+ *
+ * Deliberately narrow. A broad reading of explanation prose refuses honest
+ * text — "option B is wrong" is exactly what a good explanation SAYS about the
+ * distractors, so only a phrase naming the MARKED answer is a contradiction.
+ */
+function dismissalsOf(letter: string, index: number): readonly RegExp[] {
+  const names = [`option ${letter}`, `\\(${letter}\\)`, `answer ${letter}`, `option ${index + 1}`];
+  const verdicts = ["is wrong", "is incorrect", "is not correct", "is false"];
+  return names.flatMap((name) =>
+    verdicts.map((verdict) => new RegExp(`${name}\\b[^.]{0,40}?${verdict}`, "i")),
+  );
+}
+
+/**
+ * The option a length strategy would pick, or null when nothing is picked.
+ *
+ * A TIE is not a win. If two options are the longest, "always pick the longest"
+ * does not name an answer, so counting it as a win would report 100% on a quiz
+ * whose options are all deliberately the same length — which is the shape the
+ * check exists to encourage. Found by the conformance table: options of equal
+ * length scored as pick-longest wins on every question.
+ */
+function uniqueExtreme(options: readonly string[], want: "long" | "short"): number | null {
+  const lengths = options.map((o) => o.length);
+  const target = want === "long" ? Math.max(...lengths) : Math.min(...lengths);
+  const hits = lengths.flatMap((len, i) => (len === target ? [i] : []));
+  return hits.length === 1 ? (hits[0] ?? null) : null;
+}
+
+/**
+ * Every hygiene problem in this quiz, or an empty array.
+ *
+ * Pure and total: it never throws on a malformed quiz, because the schema is
+ * what refuses that and an audit that threw would replace a precise schema
+ * error with a vague one.
+ */
+export function auditQuiz(quiz: AuditQuiz): readonly QuizFinding[] {
+  const findings: QuizFinding[] = [];
+  const questions = quiz.questions;
+  const total = questions.length;
+  if (total === 0) return findings;
+
+  if (total >= MIN_BANK_FOR_RATIOS) {
+    // Answer-position bias — the predecessor's 451-question bug.
+    const byIndex = new Map<number, number[]>();
+    questions.forEach((q, i) => {
+      byIndex.set(q.answer, [...(byIndex.get(q.answer) ?? []), i + 1]);
+    });
+    for (const [index, numbers] of [...byIndex].sort((a, b) => b[1].length - a[1].length)) {
+      const share = numbers.length / total;
+      if (share > MAX_INDEX_SHARE) {
+        findings.push({
+          slug: "ksor-quiz-answer-bias",
+          questions: numbers,
+          detail: `${numbers.length} of ${total} answers (${Math.round(share * 100)}%) are option ${LETTERS[index] ?? index}, above ${Math.round(MAX_INDEX_SHARE * 100)}% — a reader can pass by guessing it`,
+        });
+        break;
+      }
+    }
+
+    // Length bias, both directions: if either "always pick the longest" or
+    // "always pick the shortest" wins, the reader never has to read.
+    for (const want of ["long", "short"] as const) {
+      const label = want === "long" ? "longest" : "shortest";
+      const wins = questions.flatMap((q, i) =>
+        uniqueExtreme(q.options, want) === q.answer ? [i + 1] : [],
+      );
+      const share = wins.length / total;
+      if (share > MAX_STRATEGY_WIN) {
+        findings.push({
+          slug: "ksor-quiz-length-bias",
+          questions: wins,
+          detail: `picking the ${label} option answers ${wins.length} of ${total} (${Math.round(share * 100)}%), above ${Math.round(MAX_STRATEGY_WIN * 100)}% — the answer is visible without reading`,
+        });
+        break;
+      }
+    }
+  }
+
+  // A run of identical answers. No size floor: it is a pattern at any length.
+  let runStart = 0;
+  for (let i = 1; i <= total; i++) {
+    const same = i < total && questions[i]?.answer === questions[runStart]?.answer;
+    if (same) continue;
+    const length = i - runStart;
+    if (length > MAX_SAME_ANSWER_RUN) {
+      const numbers = Array.from({ length }, (_, k) => runStart + k + 1);
+      findings.push({
+        slug: "ksor-quiz-answer-run",
+        questions: numbers,
+        detail: `questions ${numbers[0]}-${numbers[numbers.length - 1]} all answer option ${LETTERS[questions[runStart]?.answer ?? 0] ?? "?"} — ${length} in a row, above ${MAX_SAME_ANSWER_RUN}`,
+      });
+    }
+    runStart = i;
+  }
+
+  // An explanation that dismisses the answer the quiz marks correct. One of
+  // the two is wrong and neither the reader nor the author can tell which.
+  const contradicting = questions.flatMap((q, i) => {
+    const text = q.explanation ?? "";
+    if (text === "") return [];
+    const letter = LETTERS[q.answer] ?? String(q.answer);
+    return dismissalsOf(letter, q.answer).some((re) => re.test(text)) ? [i + 1] : [];
+  });
+  if (contradicting.length > 0) {
+    findings.push({
+      slug: "ksor-quiz-contradiction",
+      questions: contradicting,
+      detail: `the explanation calls the marked answer wrong — either the answer index or the explanation is incorrect`,
+    });
+  }
+
+  // Two questions opening identically are the same question twice.
+  const seen = new Map<string, number>();
+  const duplicates: number[] = [];
+  questions.forEach((q, i) => {
+    const key = q.question.trim().slice(0, STEM_PREFIX).toLowerCase();
+    const first = seen.get(key);
+    if (first === undefined) seen.set(key, i + 1);
+    else duplicates.push(first, i + 1);
+  });
+  if (duplicates.length > 0) {
+    findings.push({
+      slug: "ksor-quiz-duplicate-stem",
+      questions: [...new Set(duplicates)].sort((a, b) => a - b),
+      detail: `two questions share their first ${STEM_PREFIX} characters`,
+    });
+  }
+
+  return findings;
+}
+
+/** A bank whose answers cycle, so no ratio, run or duplicate rule fires. */
+function clean(count: number): readonly AuditQuestion[] {
+  return Array.from({ length: count }, (_, i) => ({
+    question: `Question ${i} about a distinct matter entirely, worded at length`,
+    // All the same length on purpose: the clean bank must be clean on the
+    // length rule too, and equal-length options are what an author should aim
+    // for anyway.
+    options: ["option alpha", "option gamma", "option delta", "option omega"],
+    answer: i % 4,
+    explanation: "The marked option follows from the document.",
+  }));
+}
+
+/**
+ * The rule, as a decision table.
+ *
+ * The checker implements these same rules in plain JS because it cannot import
+ * TypeScript, so this table is what both halves are asserted against rather
+ * than each being internally consistent with itself — the shape decision 18
+ * exists to enforce.
+ */
+/** One row of the decision table: a quiz, and every slug it must produce. */
+export interface QuizAuditCase {
+  readonly name: string;
+  readonly quiz: AuditQuiz;
+  readonly expect: readonly string[];
+}
+
+export const QUIZ_AUDIT_CASES: readonly QuizAuditCase[] = [
+  {
+    name: "a balanced bank is clean",
+    quiz: { quiz: { title: "Clean" }, questions: clean(8) },
+    expect: [],
+  },
+  {
+    name: "every answer at A",
+    quiz: {
+      quiz: { title: "Bias" },
+      questions: clean(8).map((q) => ({ ...q, answer: 0 })),
+    },
+    expect: ["ksor-quiz-answer-bias", "ksor-quiz-answer-run"],
+  },
+  {
+    name: "the correct option is always the longest",
+    quiz: {
+      quiz: { title: "Length" },
+      questions: clean(8).map((q, i) => ({
+        ...q,
+        options: q.options.map((o, k) => (k === i % 4 ? `${o} with considerably more words` : o)),
+      })),
+    },
+    expect: ["ksor-quiz-length-bias"],
+  },
+  {
+    name: "four consecutive questions share an answer",
+    quiz: {
+      quiz: { title: "Run" },
+      // 12 questions so the four-long run cannot also trip the ratio rule.
+      questions: clean(12).map((q, i) => (i < 4 ? { ...q, answer: 1 } : q)),
+    },
+    expect: ["ksor-quiz-answer-run"],
+  },
+  {
+    name: "an explanation dismisses its own marked answer",
+    quiz: {
+      quiz: { title: "Contradiction" },
+      questions: clean(8).map((q, i) =>
+        i === 2
+          ? { ...q, answer: 1, explanation: "Option B is wrong because it inverts the rule." }
+          : q,
+      ),
+    },
+    expect: ["ksor-quiz-contradiction"],
+  },
+  {
+    name: "an explanation dismissing a DISTRACTOR is honest text, not a finding",
+    quiz: {
+      quiz: { title: "Honest" },
+      questions: clean(8).map((q, i) =>
+        i === 2
+          ? { ...q, answer: 2, explanation: "Option B is wrong because it inverts the rule." }
+          : q,
+      ),
+    },
+    expect: [],
+  },
+  {
+    name: "two questions open identically",
+    quiz: {
+      quiz: { title: "Duplicate" },
+      questions: clean(8).map((q, i) => (i === 5 ? { ...q, question: clean(8)[1]!.question } : q)),
+    },
+    expect: ["ksor-quiz-duplicate-stem"],
+  },
+];

package/templates/scaffold/system/site/lib/quiz-round.ts

@@ -0,0 +1,57 @@
+/**
+ * How many questions one round of a quiz asks, and which ones.
+ *
+ * Split from `quiz.ts` because that file carries zod, and a zod-carrying module
+ * cannot be pulled into this repo's unit tier — `isolatedDeclarations` cannot
+ * infer a schema's type and the annotations it would need are unwritable by
+ * hand. The same split already happened once, when `progressPercent` moved out
+ * of `deck.ts` into `srs.ts`. Rounds are pure arithmetic and belong on this
+ * side of that line anyway.
+ *
+ * A LEAF: no imports.
+ */
+
+/**
+ * Default round size.
+ *
+ * The predecessor shows 15-20 from a bank of 50 — about a third, so three
+ * retakes are mostly new questions. Ten keeps that ratio at a size a record's
+ * document can actually reach without inventing questions to pad it.
+ */
+export const DEFAULT_QUESTIONS_PER_ROUND = 10;
+
+/**
+ * The questions one round asks.
+ *
+ * A bank at or below the round size is returned WHOLE and in authored order:
+ * there is no second round to make different, so shuffling would only cost the
+ * author their deliberate ordering. A larger bank is sampled, which is what
+ * makes another round worth taking.
+ *
+ * `pick` is a parameter rather than a call to `Math.random()` inside, so the
+ * sampling is assertable and the module stays pure — the same reason `schedule`
+ * takes `now`.
+ */
+export function roundOf<T>(
+  bank: readonly T[],
+  size: number,
+  pick: () => number = Math.random,
+): readonly T[] {
+  if (bank.length <= size) return bank;
+  const pool = [...bank];
+  for (let i = pool.length - 1; i > 0; i--) {
+    const j = Math.floor(pick() * (i + 1));
+    const a = pool[i];
+    const b = pool[j];
+    if (a !== undefined && b !== undefined) {
+      pool[i] = b;
+      pool[j] = a;
+    }
+  }
+  return pool.slice(0, size);
+}
+
+/** True when the bank is bigger than one round, so another round differs. */
+export function hasMoreRounds(bankSize: number, roundSize: number): boolean {
+  return bankSize > roundSize;
+}

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

@@ -0,0 +1,84 @@
+import { z } from "zod";
+
+import { QUIZ_AUDIT_SLUGS, auditQuiz, type QuizFinding } from "./quiz-audit";
+
+/**
+ * The shape of a `<doc>.quiz.yaml`.
+ *
+ * NO AUTHORED IDS, as with the deck: the quiz's identity is its path and a
+ * question's identity is its own text. See `lib/deck.ts` for the full argument.
+ *
+ * Two of the predecessor's hard requirements are deliberately not here, and the
+ * spec (`specs/ksor/quiz/spec.md` §6) records why: exactly four options, and a
+ * bank of exactly fifty. Both are conventions from timed multiple-choice exams,
+ * and a governed record's document may honestly warrant five questions with
+ * three options each. Quality is protected by the audit instead of by a count.
+ */
+export const QuestionSchema = z.object({
+  question: z.string().min(1).max(400),
+  /**
+   * Two to six. Two is a true/false question, which is a legitimate check on a
+   * policy statement; past six the reader is scanning a list rather than
+   * choosing.
+   */
+  options: z.array(z.string().min(1).max(300)).min(2).max(6),
+  /** Zero-based index into `options`. Range is checked below, against THIS question. */
+  answer: z.number().int().min(0),
+  /**
+   * Required. The predecessor's immediate-feedback model teaches through the
+   * mistake, and a wrong answer with no explanation teaches nothing at all —
+   * which is the whole reason to put a quiz in a record rather than a course.
+   */
+  explanation: z.string().min(1).max(1200),
+  /**
+   * Where in the document the answer lives — prose, not a citation.
+   *
+   * Deliberately NOT called a source in the UI. A citation in this product
+   * carries a generation (product invariant 1) and an attachment has no id to
+   * pin, so presenting this as one would be selling provenance we do not have.
+   */
+  source: z.string().max(200).optional(),
+});
+
+export const QuizSchema = z
+  .object({
+    quiz: z.object({
+      title: z.string().min(1).max(120),
+      description: z.string().max(300).optional(),
+      /** How many questions one round shows. See `roundOf`. */
+      questionsPerRound: z.number().int().min(1).max(50).optional(),
+    }),
+    questions: z.array(QuestionSchema).min(1).max(200),
+  })
+  .superRefine((value, ctx) => {
+    // The answer index must point at an option THIS question has. A schema-wide
+    // max would admit `answer: 3` on a two-option question, which renders as a
+    // quiz nobody can pass and no error anybody can see.
+    value.questions.forEach((q, i) => {
+      if (q.answer >= q.options.length) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["questions", i, "answer"],
+          message: `answer ${q.answer} is out of range: question ${i + 1} has ${q.options.length} options, so the last valid index is ${q.options.length - 1}`,
+        });
+      }
+    });
+
+    // The audit runs as part of parsing, so a quiz that would let a reader
+    // guess cannot be loaded at all — not by a separate pass somebody has to
+    // remember to run. This is the predecessor's mistake corrected: it had
+    // these checks and they lived in a script (spec §5).
+    for (const finding of auditQuiz(value)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["questions"],
+        message: `${finding.slug}: ${finding.detail} (questions ${finding.questions.join(", ")})`,
+      });
+    }
+  });
+
+export type Quiz = z.infer<typeof QuizSchema>;
+export type Question = z.infer<typeof QuestionSchema>;
+
+/** Re-exported so a caller needs one import to name what refused it. */
+export { QUIZ_AUDIT_SLUGS, type QuizFinding };

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

@@ -2,6 +2,7 @@ import { defineCollections, defineConfig, defineDocs } from "fumadocs-mdx/config
 import { metaSchema, pageSchema } from "fumadocs-core/source/schema";
 import { z } from "zod";
 import { DeckSchema } from "./lib/deck";
+import { QuizSchema } from "./lib/quiz";
 import { knowledgeSourceDir } from "./lib/stage-knowledge";
 
 // The record lives at <repo>/knowledge — two levels up from this site.
@@ -87,6 +88,21 @@ export const decks = defineCollections({
   schema: DeckSchema,
 });
 
+/**
+ * Quizzes, on the deck's terms exactly — same loader, same reason for `.yaml`.
+ *
+ * `QuizSchema` runs the hygiene audit as part of parsing, so a quiz whose
+ * answers are guessable fails HERE, during the build, naming the questions.
+ * That is the point of putting it in the schema rather than in a script: the
+ * predecessor had these checks and shipped the bugs anyway.
+ */
+export const quizzes = defineCollections({
+  type: "meta",
+  dir: knowledgeSourceDir(),
+  files: ["**/*.quiz.yaml"],
+  schema: QuizSchema,
+});
+
 export default defineConfig({
   mdxOptions: {
     // MDX options