PLAN-MVP — Phase 1 implementation plan (archived)¶

/** 32-bit string hash (xmur3), used to derive one stream per purpose. */
export function hashSeed(...parts: (string | number)[]): number {
  let h = 1779033703 ^ parts.join("\u0001").length;
  const s = parts.join("\u0001");
  for (let i = 0; i < s.length; i++) {
    h = Math.imul(h ^ s.charCodeAt(i), 3432918353);
    h = (h << 13) | (h >>> 19);
  }
  return (h ^= h >>> 16) >>> 0;
}

/** mulberry32 PRNG: returns a [0,1) generator. */
export function rng(seed: number): () => number {
  let a = seed >>> 0;
  return () => {
    a = (a + 0x6d2b79f5) | 0;
    let t = Math.imul(a ^ (a >>> 15), 1 | a);
    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}

/** Fisher-Yates, pure: returns a new array. Same seed ⇒ same permutation, forever. */
export function shuffle<T>(items: readonly T[], seed: number): T[] {
  const out = items.slice();
  const next = rng(seed);
  for (let i = out.length - 1; i > 0; i--) {
    const j = Math.floor(next() * (i + 1));
    [out[i], out[j]] = [out[j]!, out[i]!];
  }
  return out;
}

/** The one and only seed derivation used by the platform. */
export function streamSeed(attemptSeed: number, itemId: string, purpose: string): number {
  return hashSeed(attemptSeed, itemId, purpose);
}

/** Points are on the item scale already (0 … maxPoints), rounded to 2 decimals. */
export interface GradedResult<D = unknown> {
  kind: "graded";
  points: number;
  maxPoints: number;
  /** Type-specific breakdown, stored verbatim in gradings.details. */
  details: D;
  /** Grading born validated (deterministic) or proposed (needs teacher eyes). */
  state?: "validated" | "proposed";
  /** Optional machine comment shown to the teacher, e.g. "runner unavailable". */
  comment?: string;
}

export interface PendingRunnerResult {
  kind: "pending";
  via: "runner";
  /** Fully assembled, server-side. Never contains student-supplied file names. */
  request: RunnerRequest;
  /** Partial details already known (e.g. assembled source hash). */
  details?: unknown;
}

export interface PendingLlmResult {
  kind: "pending";
  via: "llm";
  /** Phase 2. The MVP grading worker rejects this with `llm_unavailable`. */
  request: LlmGradeRequest;
}

export type GradeResult<D = unknown> = GradedResult<D> | PendingRunnerResult | PendingLlmResult;

export const isGraded = <D>(r: GradeResult<D>): r is GradedResult<D> => r.kind === "graded";

export type QuestionTypeId = "mcq" | "short" | "cloze" | "code";

/** What the student is allowed to see right now. */
export interface StudentView {
  /** Attempt seed; 0 for the teacher preview (stable preview). */
  seed: number;
  itemId: string;
  /** Evaluation-level shuffle switch AND question-level shuffleable flag, ANDed by the caller. */
  shuffle: boolean;
}

export interface GradeContext {
  seed: number;
  itemId: string;
  attemptId: string;
  /** evaluation_items.points — the scale the grader must produce points on. */
  itemPoints: number;
  now: Date;
  /** Always present; may be the unavailable stub (throws RunnerUnavailable). */
  runner: RunnerService;
  /** Phase 2; undefined in MVP. */
  llm?: LlmService;
}

export interface QuestionTypeServer<
  TConfig = unknown,
  TAnswer = unknown,
  TStudent = unknown,
  TSolution = unknown,
  TDetails = unknown,
> {
  readonly id: QuestionTypeId;
  /** Bumped when configSchema changes shape; stored in question_versions.config_version. */
  readonly configVersion: number;

  readonly configSchema: z.ZodType<TConfig>;
  readonly answerSchema: z.ZodType<TAnswer>;
  readonly studentSchema: z.ZodType<TStudent>;
  readonly solutionSchema: z.ZodType<TSolution>;
  readonly detailsSchema: z.ZodType<TDetails>;

  /** Config of a freshly created draft, valid against configSchema. */
  emptyDraft(): TConfig;

  /** Raise an old stored config to configVersion. Pure, total, never throws on a config it emitted before. */
  migrate(config: unknown, fromVersion: number): TConfig;

  /** F-EVAL-02 default item points. */
  defaultPoints(config: TConfig): number;

  /** Whether shuffling is meaningful for this config (mcq with shuffleChoices, cloze with selects). */
  shuffleable(config: TConfig): boolean;

  /**
   * THE single content exit toward a student (docs/05 §5.7).
   * Must never return the answer key, explanation, hidden test bodies, matchers,
   * regexes, tolerances, internal name, tags or difficulty. Pure and tested by
   * key-blacklist + key-value search on the serialized output.
   */
  toStudent(config: TConfig, view: StudentView): TStudent;

  /** Key + rationale for review, served ONLY when the feedback policy allows it. */
  toSolution(config: TConfig, view: StudentView): TSolution;

  /** Phase 2 random values; absent in MVP packages. */
  randomize?(config: TConfig, seed: number): TConfig;

  /** `answer === null` means "not answered": graders must return 0 points (F-GRADE-01). */
  grade(config: TConfig, answer: TAnswer | null, ctx: GradeContext): GradeResult<TDetails> | Promise<GradeResult<TDetails>>;

  /** Second half of a `pending: runner` grading. Pure, so it is unit-testable without a runner. */
  finalizeRunner?(
    config: TConfig,
    answer: TAnswer | null,
    ctx: Omit<GradeContext, "runner" | "llm">,
    outcome: RunnerOutcome,
  ): GradedResult<TDetails>;

  /** Text fed to the tsvector of question_versions.search. */
  searchText(config: TConfig): string;

  /** Canonical YAML mapping; identity when omitted. */
  toCanonical?(config: TConfig): unknown;
  fromCanonical?(raw: unknown): TConfig;
}

export interface EditorProps<TConfig> {
  config: TConfig;
  /** Partial patch; the host merges, validates lazily and autosaves the draft. */
  onChange: (next: TConfig) => void;
  /** Uploads an image and returns `asset:<uuid>` for the markdown. */
  uploadAsset: (file: File) => Promise<string>;
  disabled?: boolean;
}

export interface PlayerProps<TStudent, TAnswer> {
  student: TStudent;
  answer: TAnswer | null;
  onChange: (next: TAnswer) => void;
  /** Read-only when the attempt is submitted / paused / expired. */
  readOnly: boolean;
  /** Code type only: interactive run through POST /attempts/:id/run. */
  run?: (payload: unknown) => Promise<unknown>;
}

export interface ReviewProps<TStudent, TAnswer, TSolution, TDetails> {
  student: TStudent;
  answer: TAnswer | null;
  /** null when the feedback policy hides the key. */
  solution: TSolution | null;
  details: TDetails | null;
  points: number | null;
  maxPoints: number;
  /** "teacher" shows everything; "student" respects the already-applied filtering. */
  audience: "teacher" | "student";
}

export interface QuestionTypeClient<TConfig = unknown, TAnswer = unknown, TStudent = unknown, TSolution = unknown, TDetails = unknown> {
  readonly id: QuestionTypeId;
  /** i18n keys, not literals: "qt.mcq.label", "qt.mcq.hint". */
  readonly labelKey: string;
  readonly hintKey: string;
  readonly Icon: ComponentType<{ className?: string }>;

  /** React.lazy, so qt-code (Monaco) never enters the initial bundle (N-PERF-05). */
  readonly Editor: LazyExoticComponent<ComponentType<EditorProps<TConfig>>>;
  readonly Player: LazyExoticComponent<ComponentType<PlayerProps<TStudent, TAnswer>>>;
  readonly Review: LazyExoticComponent<ComponentType<ReviewProps<TStudent, TAnswer, TSolution, TDetails>>>;
  readonly Stats?: LazyExoticComponent<ComponentType<{ student: TStudent; answers: TAnswer[] }>>;

  /** Empty answer for a fresh item (e.g. { selected: [] }). */
  emptyAnswer(student: TStudent): TAnswer;
  /** Drives the "empty / seen / done" progress segments (F-LIVE-09). */
  isAnswered(answer: TAnswer | null): boolean;
  /** One-line rendering for the dashboard inspection panel and the cell tooltip. */
  summarize(answer: TAnswer | null, student: TStudent): string;
}

// packages/core/src/registry.ts
export function defineServerRegistry<T extends Record<string, QuestionTypeServer<any, any, any, any, any>>>(m: T): T { return m; }
export function makeLookup<T extends { id: string }>(m: Record<string, T>) {
  return (id: string): T => {
    const t = m[id];
    if (!t) throw new UnknownQuestionType(id);
    return t;
  };
}

// packages/registry/src/server.ts   (depends on core + qt-*)
import { mcqServer } from "@quiz/qt-mcq/server"; /* … */
export const serverRegistry = defineServerRegistry({ mcq: mcqServer, short: shortServer, cloze: clozeServer, code: codeServer });
export const questionType = makeLookup(serverRegistry);
export const QUESTION_TYPE_IDS = ["mcq", "short", "cloze", "code"] as const;

// packages/registry/src/client.ts
export const clientRegistry = { mcq: mcqClient, short: shortClient, cloze: clozeClient, code: codeClient };
export const questionTypeClient = makeLookup(clientRegistry);

/** Every read of a stored config goes through this. Never parse a raw jsonb elsewhere. */
export function loadConfig(type: string, raw: unknown, storedVersion: number) {
  const t = questionType(type);
  const migrated = storedVersion === t.configVersion ? raw : t.migrate(raw, storedVersion);
  return t.configSchema.parse(migrated);              // throws 422 config_invalid
}
/** Every write. Drafts are always rewritten at the current configVersion (docs/05 §5.2). */
export function saveConfig(type: string, config: unknown) {
  const t = questionType(type);
  return { config: t.configSchema.parse(config), configVersion: t.configVersion };
}

export const RunnerLanguage = z.enum(["c", "cpp", "python", "js", "rust"]);

export const RunnerRequest = z.object({
  language: RunnerLanguage,
  files: z.array(z.object({ name: z.string().max(64), content: z.string().max(200_000) })).min(1).max(8),
  compileArgs: z.string().max(400).default(""),
  action: z.enum(["check", "run"]),
  limits: z.object({ timeMs: z.number().int().min(100).max(20_000), memoryMb: z.number().int().min(16).max(512), outputKb: z.number().int().min(1).max(256) }),
  cases: z.array(z.object({ name: z.string(), stdin: z.string().max(64_000) })).max(50),
  /** "interactive" (student clicked Run) or "grading" (background). Maps to the runner's two queues. */
  priority: z.enum(["interactive", "grading"]).default("grading"),
});

export const RunnerOutcome = z.object({
  compile: z.object({ ok: z.boolean(), stdout: z.string(), stderr: z.string(), ms: z.number() }),
  cases: z.array(z.object({
    exitCode: z.number().int().nullable(), stdout: z.string(), stderr: z.string(),
    ms: z.number(), timedOut: z.boolean(), oom: z.boolean(), truncated: z.boolean(),
  })),
});

export interface RunnerService {
  /** Throws RunnerUnavailable when no engine is configured/healthy; throws RunnerBusy on 429. */
  run(req: RunnerRequest): Promise<RunnerOutcome>;
  health(): Promise<{ ok: boolean; languages: string[]; queued: number; avgMs: number | null; reason?: string }>;
}

// packages/qt-mcq/src/schema.ts
export const McqChoice = z.object({
  text: z.string().min(1).max(2000),
  correct: z.boolean().default(false),
});

export const McqConfig = z.object({
  configVersion: z.literal(1),
  prompt: z.string().min(1).max(20_000),
  choices: z.array(McqChoice).min(2).max(12),
  mode: z.enum(["single", "multiple"]).default("single"),
  maxSelections: z.number().int().min(1).max(12).optional(),
  policy: z.enum(["all_or_nothing", "partial", "penalized"]).default("all_or_nothing"),
  penalty: z.number().min(0).max(1).default(1),
  allowNegative: z.boolean().default(false),
  shuffleChoices: z.boolean().default(true),
})
  .refine((c) => c.choices.some((x) => x.correct), { message: "mcq.no_correct_choice" })
  .refine((c) => c.mode !== "single" || c.choices.filter((x) => x.correct).length === 1, { message: "mcq.single_needs_one" })
  .refine((c) => c.policy !== "all_or_nothing" || true)
  .refine((c) => c.mode !== "single" || c.policy === "all_or_nothing", { message: "mcq.single_policy" });

export const McqAnswer = z.object({
  /** Canonical indices into config.choices, ascending, unique. */
  selected: z.array(z.number().int().min(0).max(11)).max(12),
});

export const McqStudent = z.object({
  prompt: z.string(),
  /** `id` is the canonical index; the ARRAY ORDER is the shuffled display order. */
  choices: z.array(z.object({ id: z.number().int(), text: z.string() })),
  mode: z.enum(["single", "multiple"]),
  maxSelections: z.number().int().optional(),
});

export const McqSolution = z.object({ correct: z.array(z.number().int()) });

export const McqDetails = z.object({
  policy: z.enum(["all_or_nothing", "partial", "penalized"]),
  correct: z.array(z.number().int()),   // C set
  selected: z.array(z.number().int()),
  c: z.number().int(), w: z.number().int(), C: z.number().int(), W: z.number().int(),
  fraction: z.number(),
});

const Base = { points: z.number().min(0).max(1).default(1) };

export const ShortMatcher = z.discriminatedUnion("kind", [
  z.object({ kind: z.literal("exact"), value: z.string().min(1).max(500),
             caseSensitive: z.boolean().default(false), trim: z.boolean().default(true),
             collapseSpaces: z.boolean().default(true), ...Base }),
  z.object({ kind: z.literal("regex"), pattern: z.string().min(1).max(300),
             flags: z.string().regex(/^[imsu]*$/).default("i"), ...Base }),
  z.object({ kind: z.literal("number"), value: z.number(), tolerance: z.number().min(0).default(0),
             toleranceMode: z.enum(["abs", "rel"]).default("abs"),
             unit: z.string().max(16).optional(), unitRequired: z.boolean().default(false), ...Base }),
  z.object({ kind: z.literal("date"), value: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
             toleranceDays: z.number().int().min(0).default(0), ...Base }),
  z.object({ kind: z.literal("time"), value: z.string().regex(/^\d{2}:\d{2}$/),
             toleranceMinutes: z.number().int().min(0).default(0), ...Base }),
  // phase 2, accepted by the schema but rejected at publication in MVP:
  z.object({ kind: z.literal("llm"), rubric: z.string(), reference: z.string().optional(), ...Base }),
]);

export const ShortConfig = z.object({
  configVersion: z.literal(1),
  prompt: z.string().min(1).max(20_000),
  kind: z.enum(["text", "number", "date", "time"]).default("text"),
  placeholder: z.string().max(80).optional(),
  matchers: z.array(ShortMatcher).min(1).max(20),
});

export const ShortAnswer  = z.object({ text: z.string().max(500) });
export const ShortStudent = z.object({ prompt: z.string(), kind: z.enum(["text","number","date","time"]), placeholder: z.string().optional() });
export const ShortSolution = z.object({ /** human rendering, e.g. "0x1004" or "≈ 3.14 ± 1 %" */ expected: z.array(z.string()) });
export const ShortDetails = z.object({
  matchedIndex: z.number().int().nullable(),
  matchedKind: z.string().nullable(),
  normalized: z.string(),
  fraction: z.number(),
});

export const ClozeConfig = z.object({
  configVersion: z.literal(1),
  /** Markdown with {{…}} holes. */
  text: z.string().min(1).max(20_000),
  caseSensitive: z.boolean().default(false),
  shuffleOptions: z.boolean().default(true),
}).superRefine((c, ctx) => { /* parseCloze must succeed and yield ≥ 1 blank */ });

export const ClozeAnswer = z.object({
  /** One entry per blank, in order of appearance. `null` = untouched. */
  blanks: z.array(z.string().max(200).nullable()).max(50),
});

export type ClozeBlank =
  | { index: number; weight: number; kind: "text";   answers: string[] }
  | { index: number; weight: number; kind: "select"; options: string[]; correct: number[] }
  | { index: number; weight: number; kind: "number"; value: number; tolerance: number; mode: "abs" | "rel" }
  | { index: number; weight: number; kind: "regex";  pattern: string; flags: string };

export interface ClozeParse {
  /** Markdown with each blank replaced by the sentinel `⸢{index}⸣`. */
  template: string;
  blanks: ClozeBlank[];
  errors: { at: number; message: string }[];
}
export function parseCloze(text: string): ClozeParse;

export const ClozeStudent = z.object({
  template: z.string(),   // sentinel-bearing markdown, no answers anywhere
  blanks: z.array(z.discriminatedUnion("kind", [
    z.object({ index: z.number().int(), weight: z.number(), kind: z.literal("input"), numeric: z.boolean() }),
    z.object({ index: z.number().int(), weight: z.number(), kind: z.literal("select"),
               options: z.array(z.object({ id: z.number().int(), label: z.string() })) }),
  ])),
});

export const CodeConfig = z.object({
  configVersion: z.literal(1),
  prompt: z.string().min(1).max(20_000),
  language: z.enum(["c", "cpp", "python", "js", "rust"]),
  template: z.string().max(40_000).default(""),
  files: z.array(z.object({ name: z.string().regex(/^[\w.-]{1,40}$/), content: z.string().max(64_000) })).max(4).default([]),
  action: z.enum(["check", "run"]).default("run"),
  compileArgs: z.string().max(400).default(""),
  limits: z.object({
    timeMs: z.number().int().min(100).max(10_000).default(2000),
    memoryMb: z.number().int().min(16).max(512).default(128),
    outputKb: z.number().int().min(1).max(256).default(64),
  }).default({}),
  runsPerMinute: z.number().int().min(1).max(30).default(10),
  allOrNothing: z.boolean().default(false),
  tests: z.object({
    mode: z.literal("io"),            // "tap" is phase 3
    compare: z.object({
      trimTrailing: z.boolean().default(true),
      ignoreCase: z.boolean().default(false),
      numeric: z.object({ epsilon: z.number().min(0), mode: z.enum(["abs", "rel"]) }).nullable().default(null),
    }).default({}),
    cases: z.array(z.object({
      name: z.string().min(1).max(60),
      stdin: z.string().max(16_000).default(""),
      expected: z.string().max(16_000),
      visible: z.boolean().default(false),
      points: z.number().min(0).max(100).default(1),
    })).min(1).max(30),
  }),
});

export const CodeAnswer = z.object({
  /** One entry per EDITABLE region of the template, in order. */
  regions: z.array(z.string().max(20_000)).max(20),
  lastRun: z.object({
    at: z.iso.datetime(), requestId: z.uuid(),
    compileOk: z.boolean(), passed: z.number().int(), total: z.number().int(),
  }).nullable().optional(),
});

export interface TemplateSegment { kind: "locked" | "editable"; index: number | null; text: string }
/** A line is a marker iff, once leading whitespace and the language's line-comment prefix
 *  (`//`, `#`, `--`) are stripped, it equals `@@lock` or `@@endlock`. Markers are part of
 *  the locked text (they are comments and must survive into the compiled source). */
export function splitTemplate(template: string, language: CodeLanguage): TemplateSegment[];
/** Rebuilds the source. Throws if regions.length !== editable count. NEVER accepts client text
 *  for a locked segment (docs/04 §4.7). */
export function assembleSource(template: string, language: CodeLanguage, regions: string[]): string;

export const CodeStudent = z.object({
  prompt: z.string(),
  language: z.enum(["c","cpp","python","js","rust"]),
  segments: z.array(z.object({ kind: z.enum(["locked","editable"]), index: z.number().int().nullable(), text: z.string() })),
  limits: z.object({ timeMs: z.number(), memoryMb: z.number(), outputKb: z.number() }),
  runsPerMinute: z.number().int(),
  /** VISIBLE cases only, with stdin and expected. */
  visibleCases: z.array(z.object({ name: z.string(), stdin: z.string(), expected: z.string(), points: z.number() })),
  /** Hidden cases exist but stay opaque during the attempt (docs/06 Q8). */
  hiddenCount: z.number().int(),
  hiddenPoints: z.number(),
  filesPreview: z.array(z.object({ name: z.string(), bytes: z.number().int() })),
  allOrNothing: z.boolean(),
});

grade(config, answer, ctx): GradeResult {
  if (!answer || answer.regions.every(r => r.trim() === "")) return { kind:"graded", points:0, maxPoints:ctx.itemPoints, details:{ empty:true, … }, state:"validated" };
  const source = assembleSource(config.template, config.language, answer.regions);
  return { kind: "pending", via: "runner", request: {
      language: config.language,
      files: [{ name: mainFileName(config.language), content: source }, ...config.files],
      compileArgs: config.compileArgs, action: "run", limits: config.limits,
      cases: config.tests.cases.map(c => ({ name: c.name, stdin: c.stdin })),
      priority: "grading",
  }};
}

finalizeRunner(config, answer, ctx, outcome): GradedResult {
  if (!outcome.compile.ok) return zero with details.compile;
  const per = config.tests.cases.map((c, i) => ({ …, ok: compareOutput(c.expected, outcome.cases[i].stdout, config.tests.compare) && outcome.cases[i].exitCode === 0 && !timedOut && !oom }));
  const earned = per.filter(p => p.ok).reduce((s,p) => s + p.points, 0);
  const total  = config.tests.cases.reduce((s,c) => s + c.points, 0);
  const fraction = config.allOrNothing ? (earned === total ? 1 : 0) : (total ? earned / total : 0);
  return { kind:"graded", points: round2(fraction * ctx.itemPoints), maxPoints: ctx.itemPoints, details: { compile, cases: per, earned, total }, state:"validated" };
}

export const CodeDetails = z.object({
  runner: z.enum(["ok", "unavailable", "busy", "error"]),
  compile: z.object({ ok: z.boolean(), stderr: z.string().max(4000), ms: z.number() }).nullable(),
  cases: z.array(z.object({
    name: z.string(), visible: z.boolean(), points: z.number(), ok: z.boolean(),
    exitCode: z.number().nullable(), ms: z.number(), timedOut: z.boolean(), oom: z.boolean(),
    /** Present only for visible cases (or for the teacher). */
    expected: z.string().optional(), actual: z.string().optional(), stderr: z.string().optional(),
  })),
  earned: z.number(), total: z.number(), sourceSha256: z.string().length(64),
});

// packages/qt-*/src/toStudent.test.ts
const FORBIDDEN_KEYS = ["correct", "matchers", "answers", "expected", "pattern", "value", "tolerance",
  "policy", "penalty", "compare", "compileArgs", "explanation", "internalName", "tags", "difficulty", "rubric"];
it("leaks no key", () => {
  const out = JSON.stringify(type.toStudent(FULL_FIXTURE, { seed: 7, itemId: "i", shuffle: true }));
  for (const k of FORBIDDEN_KEYS) expect(out).not.toContain(`"${k}"`);
  for (const secret of SECRET_VALUES) expect(out).not.toContain(secret);  // e.g. "0x1004", "Newton", hidden stdin
});