@danypops/papyrus 0.59.1 → 0.59.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.59.1",
+  "version": "0.59.3",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "main": "./src/index.ts",
@@ -57,9 +57,9 @@
   },
   "files": ["src", "README.md"],
   "dependencies": {
-    "@danypops/vehicle-client": "^0.10.1",
+    "@danypops/vehicle-client": "^0.10.3",
     "@danypops/vehicle-core": "^0.17.1",
-    "@danypops/vehicle-server": "^0.24.5",
+    "@danypops/vehicle-server": "^0.25.2",
     "@stricli/core": "^1.3.0"
   }
 }

package/src/cli/discuss-command.ts

@@ -38,6 +38,8 @@ const openCommand = buildCommand({
 			optionsJson?: string[];
 			optionsMode?: string;
 			optionDescriptionsJson?: string[];
+			correctOptionsJson?: string[];
+			explanation?: string;
 		},
 	) {
 		await call.call(this, "discuss.open", {
@@ -50,6 +52,8 @@ const openCommand = buildCommand({
 			options: flags.optionsJson,
 			options_mode: flags.optionsMode,
 			option_descriptions: flags.optionDescriptionsJson,
+			correct_options: flags.correctOptionsJson,
+			explanation: flags.explanation,
 		});
 	},
 	parameters: {
@@ -81,6 +85,20 @@ const openCommand = buildCommand({
 				placeholder: "json",
 				optional: true,
 			},
+			correctOptionsJson: {
+				brief: "JSON string array of correct options (one or more, verbatim from options) -- makes this a graded quiz",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+				optional: true,
+			},
+			explanation: {
+				brief: "Quiz explanation, required alongside correctOptionsJson, always shown after grading",
+				kind: "parsed",
+				parse: String,
+				placeholder: "text",
+				optional: true,
+			},
 		},
 	},
 	docs: { brief: "Open a new discussion" },
@@ -96,6 +114,8 @@ const replyCommand = buildCommand({
 			optionsJson?: string[];
 			optionsMode?: string;
 			optionDescriptionsJson?: string[];
+			correctOptionsJson?: string[];
+			explanation?: string;
 		},
 		id: string,
 	) {
@@ -107,6 +127,8 @@ const replyCommand = buildCommand({
 			options: flags.optionsJson,
 			options_mode: flags.optionsMode,
 			option_descriptions: flags.optionDescriptionsJson,
+			correct_options: flags.correctOptionsJson,
+			explanation: flags.explanation,
 		});
 	},
 	parameters: {
@@ -135,6 +157,20 @@ const replyCommand = buildCommand({
 				placeholder: "json",
 				optional: true,
 			},
+			correctOptionsJson: {
+				brief: "JSON string array of correct options (one or more, verbatim from options) -- makes this a graded quiz",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+				optional: true,
+			},
+			explanation: {
+				brief: "Quiz explanation, required alongside correctOptionsJson, always shown after grading",
+				kind: "parsed",
+				parse: String,
+				placeholder: "text",
+				optional: true,
+			},
 		},
 		positional: { kind: "tuple", parameters: [{ brief: "Discussion id", parse: String, placeholder: "id" }] },
 	},

package/src/constants.ts

@@ -17,7 +17,7 @@ export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";
 export const DAEMON_DIR_ENV = "PAPYRUS_DAEMON_DIR";
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
-export const SQLITE_SCHEMA_VERSION = 29;
+export const SQLITE_SCHEMA_VERSION = 30;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -243,6 +243,25 @@ export const DISCUSSION_OPTION_MAX_LENGTH = 200;
 export const DISCUSSION_OPTION_DESCRIPTION_MAX_LENGTH = 240;
 // Below this, a binary yes/no choice is often self-evident and a description would just pad it.
 export const DISCUSSION_OPTION_DESCRIPTION_REQUIRED_FROM_COUNT = 3;
+/**
+ * A posed choice becomes a graded quiz/assessment once correct_options + explanation are given
+ * alongside options/optionsMode. correct_options is one or more entries drawn verbatim from
+ * options (exact text match, the same identity scheme `selected` already uses -- never an index
+ * or the display-only A/B/C/... label). A "single" quiz must have exactly one correct option
+ * (the participant can only pick one); a "multi" quiz allows several, graded correct iff the
+ * selected set exactly equals the correct set (no partial credit). explanation is mandatory --
+ * always shown after grading, especially when wrong, so a wrong answer still teaches something.
+ */
+export const DISCUSSION_QUIZ_EXPLANATION_MAX_CHARACTERS = 2_000;
+/**
+ * Display-only labels (A, B, C, ...) assigned to a quiz's options by position, computed on the
+ * fly wherever a quiz is rendered -- never persisted, never part of a quiz's addressing scheme.
+ * Single-letter labels only support up to 26 options; DISCUSSION_OPTIONS_MAX_COUNT (10) already
+ * sits comfortably under that ceiling, so there is deliberately no AA/AB double-letter overflow
+ * scheme -- raising DISCUSSION_OPTIONS_MAX_COUNT past 26 would need one added at the same time.
+ */
+export const DISCUSSION_QUIZ_OPTION_LABEL_MAX_COUNT = 26;
+
 /** Bounds for the generic graph projection protocol (external bounded contexts). */
 export const GRAPH_PROJECTION_MAX_ARTIFACTS_PER_BATCH = 500;
 export const GRAPH_PROJECTION_MAX_EDGES_PER_BATCH = 1_000;
@@ -344,6 +363,12 @@ export function dbPath(): string {
 	return `${xdg}/papyrus/papyrus.db`;
 }
 
+/** $XDG_DATA_HOME/papyrus/metrics.sqlite -- vehicle-server's own tool/operation usage metrics store, sibling of dbPath() above. */
+export function metricsPath(): string {
+	const xdg = process.env.XDG_DATA_HOME || `${process.env.HOME}/.local/share`;
+	return `${xdg}/papyrus/metrics.sqlite`;
+}
+
 /**
  * The initial status a newly created artifact of a kind gets when no caller-supplied
  * status is given. This must be an explicit, named mapping — never derived from row order

package/src/daemon/daemon.ts

@@ -3,9 +3,12 @@ import { join } from "node:path";
 import { createNodeAtomicJsonFsAdapter } from "@danypops/vehicle-server/atomic-json";
 import { readLaunchProvenance } from "@danypops/vehicle-server/daemon";
 import { diagnoseDaemon, openDaemonLifecycleLog } from "@danypops/vehicle-server/daemon-lifecycle";
+import { openVehicleMetricsStore } from "@danypops/vehicle-server/metrics";
+import { createVehicleMetricsMiddleware } from "@danypops/vehicle-server/metrics-middleware";
+import { registerVehicleMetricsOperations } from "@danypops/vehicle-server/metrics-operations";
 import { acquireDaemonLock, releaseDaemonLock } from "@danypops/vehicle-server/paths";
 import { PushChannel } from "@danypops/vehicle-server/push-channel";
-import { DAEMON_HOST, DB_OPTIMIZE_INTERVAL_MS, dbPath, WAL_CHECKPOINT_INTERVAL_MS } from "../constants.ts";
+import { DAEMON_HOST, DB_OPTIMIZE_INTERVAL_MS, dbPath, metricsPath, WAL_CHECKPOINT_INTERVAL_MS } from "../constants.ts";
 import { logEvent, logger } from "../log/log.ts";
 import { createApp, createPapyrusService } from "../service.ts";
 import {
@@ -69,6 +72,14 @@ export async function serveMain(): Promise<void> {
 	const startedAt = new Date().toISOString();
 	const token = loadOrCreateToken(stateDir);
 	const service = createPapyrusService(dbPath());
+	// Records how often each real operation is invoked (server-side, every caller) plus, via
+	// metrics.recordClientEvent, client-observed Vehicle Shell meta-tool calls -- see
+	// @danypops/vehicle-server's own metrics README section. Wired directly onto the same registry
+	// every real papyrus operation is already registered on, so it's discoverable through the exact
+	// same tools_list/tools_man path as any other operation.
+	const vehicleMetrics = openVehicleMetricsStore(metricsPath());
+	service.vehicle.useExecutionMiddleware(createVehicleMetricsMiddleware(vehicleMetrics, "papyrus"));
+	registerVehicleMetricsOperations(service.vehicle, vehicleMetrics, "papyrus");
 	const pushChannel = new PushChannel({ token });
 	const app = createApp({
 		service,
@@ -106,6 +117,7 @@ export async function serveMain(): Promise<void> {
 	});
 	if (!server.port) {
 		service.close();
+		vehicleMetrics.close();
 		releaseDaemonLock(lockPath);
 		throw new Error("Papyrus daemon failed to bind a listener");
 	}
@@ -168,6 +180,7 @@ export async function serveMain(): Promise<void> {
 		}
 		releaseDaemonLock(lockPath);
 		service.close();
+		vehicleMetrics.close();
 		// .finally() re-throws rather than handling a rejection -- catching it first turns a bare
 		// unhandled-rejection warning into a real, queryable shutdown-failure log line.
 		void recordLifecycle("stopped", signal)

package/src/db.ts

@@ -307,6 +307,16 @@ CREATE TABLE IF NOT EXISTS discussion_rounds (
 	options_mode  TEXT,
 	selected      TEXT,
 	option_descriptions TEXT,
+	-- Quiz: quiz marks a posing round (safe, public); quiz_correct_options/quiz_explanation are the
+	-- hidden answer (never selected by any general-purpose query, only resolvePendingQuizAnswer's
+	-- own dedicated one); quiz_result_* is the graded outcome on the answering round (public, safe
+	-- once submission has already happened). See domain/discussion.ts.
+	quiz          INTEGER,
+	quiz_correct_options TEXT,
+	quiz_explanation TEXT,
+	quiz_result_correct INTEGER,
+	quiz_result_correct_options TEXT,
+	quiz_result_explanation TEXT,
 	UNIQUE (discussion_id, round_number)
 );
 CREATE INDEX IF NOT EXISTS discussion_rounds_discussion_idx ON discussion_rounds(discussion_id, round_number, id);
@@ -1008,6 +1018,35 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 			`);
 		},
 	},
+	{
+		version: 30,
+		name: "discuss-quiz",
+		// See domain/discussion.ts. Nullable, purely additive columns, same pattern as version 16/19's
+		// own discuss-options/discuss-option-descriptions migrations -- a round with no quiz (the
+		// overwhelming majority) simply stores NULL in all six. quiz_correct_options/quiz_explanation
+		// are the hidden answer (a posing round) -- deliberately never selected by discussion_rounds'
+		// general-purpose read queries, only by SQLiteDiscussionRoundStore's own dedicated
+		// resolvePendingQuizAnswer. quiz_result_* is the graded outcome (an answering round, safe to
+		// read generally since it only exists after submission). Guarded per-column (SQLite has no
+		// `ADD COLUMN IF NOT EXISTS`), the same already-bootstrapped-fixture concern version 9's comment
+		// covers.
+		up: (db) => {
+			const existing = new Set(
+				(db.prepare("PRAGMA table_info(discussion_rounds)").all() as Array<{ name: string }>).map((row) => row.name),
+			);
+			const columns = [
+				["quiz", "INTEGER"],
+				["quiz_correct_options", "TEXT"],
+				["quiz_explanation", "TEXT"],
+				["quiz_result_correct", "INTEGER"],
+				["quiz_result_correct_options", "TEXT"],
+				["quiz_result_explanation", "TEXT"],
+			] as const;
+			for (const [column, type] of columns) {
+				if (!existing.has(column)) db.exec(`ALTER TABLE discussion_rounds ADD COLUMN ${column} ${type}`);
+			}
+		},
+	},
 ];
 
 /**

package/src/discussion/discussion-round-store.ts

@@ -5,4 +5,11 @@ export interface DiscussionRoundStore {
 	append(round: AppendDiscussionRound, occurredAt: string): DiscussionRound;
 	list(query: DiscussionRoundQuery): DiscussionRound[];
 	count(discussionId: string): number;
+	/**
+	 * Reads back a quiz's hidden correct-answer + explanation, for grading only -- the one deliberate
+	 * hole in "never expose the answer", scoped to discussion-service.ts's reply() alone. Returns
+	 * undefined when that round never posed a quiz (defensive; discussion-service.ts only calls this
+	 * when extra.discussion.pendingIsQuiz is already true, so this should always resolve in practice).
+	 */
+	resolvePendingQuizAnswer(discussionId: string, roundNumber: number): { correctOptions: string[]; explanation: string } | undefined;
 }

package/src/discussion/discussion-service.ts

@@ -12,13 +12,16 @@ import {
 	DISCUSSION_SUBTYPE,
 	type DiscussionExtra,
 	type DiscussionOptionsMode,
+	type DiscussionQuizResult,
 	type DiscussionRound,
+	gradeQuizAnswer,
 	isDiscussionArtifact,
 	readDiscussionExtra,
 	validateDeferReason,
 	validateDiscussionActor,
 	validateDiscussionContent,
 	validateDiscussionOptions,
+	validateDiscussionQuiz,
 	validateSelectedOptions,
 	validateSettlement,
 } from "./discussion.ts";
@@ -38,17 +41,25 @@ export interface OpenDiscussionInput {
 	optionsMode?: DiscussionOptionsMode;
 	/** Index-aligned with options -- see domain/discussion.ts's pendingOptionDescriptions. */
 	optionDescriptions?: string[];
+	/** Turns the posed choice into a graded quiz -- both required together, alongside options/optionsMode.
+	 * See domain/discussion.ts's validateDiscussionQuiz. */
+	quizCorrectOptions?: string[];
+	quizExplanation?: string;
 }
 
 export interface ReplyInput {
 	actor: string;
 	content: string;
-	/** Answers the Discussion's currently pending posed choice, if any; validated against it. */
+	/** Answers the Discussion's currently pending posed choice, if any; validated against it. If the
+	 * pending choice was a quiz, this is also graded automatically -- see the round's own quizResult. */
 	selected?: string[];
 	/** Poses a new choice on this same round, replacing whatever was previously pending. */
 	options?: string[];
 	optionsMode?: DiscussionOptionsMode;
 	optionDescriptions?: string[];
+	/** Turns the newly-posed choice into a graded quiz -- both required together. */
+	quizCorrectOptions?: string[];
+	quizExplanation?: string;
 }
 
 export interface DiscussionAndRounds {
@@ -72,20 +83,50 @@ export class Discussions {
 		return readDiscussionExtra(discussion.extra);
 	}
 
-	/** Validates a freshly-posed choice; undefined when neither field is given (nothing posed), since both/neither is the only valid shape. */
+	/**
+	 * Validates a freshly-posed choice; undefined when nothing is posed at all (neither options nor
+	 * quiz fields given), since both/neither is the only valid shape. correct_options/explanation
+	 * turn the choice into a graded quiz -- both required together, and only once options/optionsMode
+	 * are also given.
+	 */
 	private validatePosedOptions(
 		options: string[] | undefined,
 		optionsMode: DiscussionOptionsMode | undefined,
 		optionDescriptions: string[] | undefined,
-	): { options: string[]; mode: DiscussionOptionsMode; optionDescriptions?: string[] } | undefined {
-		if (options === undefined && optionsMode === undefined) return undefined;
-		return validateDiscussionOptions(options ?? [], optionsMode ?? "", optionDescriptions);
+		quizCorrectOptions: string[] | undefined,
+		quizExplanation: string | undefined,
+	):
+		| {
+				options: string[];
+				mode: DiscussionOptionsMode;
+				optionDescriptions?: string[];
+				quiz?: { correctOptions: string[]; explanation: string };
+		  }
+		| undefined {
+		if (options === undefined && optionsMode === undefined) {
+			if (quizCorrectOptions !== undefined || quizExplanation !== undefined) {
+				throw new Error("correct_options/explanation require options and options_mode to also be posed");
+			}
+			return undefined;
+		}
+		const posed = validateDiscussionOptions(options ?? [], optionsMode ?? "", optionDescriptions);
+		if (quizCorrectOptions === undefined && quizExplanation === undefined) return posed;
+		if (quizCorrectOptions === undefined || quizExplanation === undefined) {
+			throw new Error("correct_options and explanation must both be given to pose a quiz, or neither");
+		}
+		return { ...posed, quiz: validateDiscussionQuiz(posed.options, posed.mode, quizCorrectOptions, quizExplanation) };
 	}
 
 	open(input: OpenDiscussionInput, context?: ArtifactEventContext): DiscussionAndRounds {
 		const actor = validateDiscussionActor(input.actor);
 		const content = validateDiscussionContent(input.content);
-		const posed = this.validatePosedOptions(input.options, input.optionsMode, input.optionDescriptions);
+		const posed = this.validatePosedOptions(
+			input.options,
+			input.optionsMode,
+			input.optionDescriptions,
+			input.quizCorrectOptions,
+			input.quizExplanation,
+		);
 		return this.artifacts.atomic(() => {
 			const discussion = this.artifacts.create(
 				{
@@ -104,6 +145,7 @@ export class Discussions {
 										pendingOptions: posed.options,
 										pendingOptionsMode: posed.mode,
 										...(posed.optionDescriptions ? { pendingOptionDescriptions: posed.optionDescriptions } : {}),
+										...(posed.quiz ? { pendingIsQuiz: true, pendingQuizRoundNumber: 1 } : {}),
 									}
 								: {}),
 						},
@@ -122,6 +164,9 @@ export class Discussions {
 								options: posed.options,
 								optionsMode: posed.mode,
 								...(posed.optionDescriptions ? { optionDescriptions: posed.optionDescriptions } : {}),
+								...(posed.quiz
+									? { quiz: true, quizCorrectOptions: posed.quiz.correctOptions, quizExplanation: posed.quiz.explanation }
+									: {}),
 							}
 						: {}),
 				},
@@ -135,7 +180,13 @@ export class Discussions {
 	reply(discussionId: string, input: ReplyInput, context?: ArtifactEventContext): DiscussionAndRounds {
 		const validActor = validateDiscussionActor(input.actor);
 		const validContent = validateDiscussionContent(input.content);
-		const posed = this.validatePosedOptions(input.options, input.optionsMode, input.optionDescriptions);
+		const posed = this.validatePosedOptions(
+			input.options,
+			input.optionsMode,
+			input.optionDescriptions,
+			input.quizCorrectOptions,
+			input.quizExplanation,
+		);
 		return this.artifacts.atomic(() => {
 			const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
 			const state = this.extra(discussion);
@@ -144,6 +195,24 @@ export class Discussions {
 				throw new DiscussionError(`discussion "${discussionId}" has reached its ${DISCUSSION_MAX_ROUNDS}-round limit; settle or defer it`);
 			const selected =
 				input.selected !== undefined ? validateSelectedOptions(input.selected, state.pendingOptions, state.pendingOptionsMode) : undefined;
+			// Grading happens right here, inside this same transaction: the hidden answer is read via
+			// resolvePendingQuizAnswer (the one deliberate hole in "never expose the quiz's answer",
+			// scoped to exactly this call) and immediately folded into a safe, already-graded quizResult --
+			// nothing upstream of this method ever sees the raw correct-options set for an unanswered quiz.
+			const quizResult: DiscussionQuizResult | undefined =
+				selected && state.pendingIsQuiz && state.pendingQuizRoundNumber !== undefined
+					? (() => {
+							const hidden = this.rounds.resolvePendingQuizAnswer(discussionId, state.pendingQuizRoundNumber as number);
+							if (!hidden) {
+								throw new DiscussionError(`discussion "${discussionId}" has no recorded quiz answer for its pending round`);
+							}
+							return {
+								correct: gradeQuizAnswer(selected, hidden.correctOptions),
+								correctOptions: hidden.correctOptions,
+								explanation: hidden.explanation,
+							};
+						})()
+					: undefined;
 			const nextRound = state.roundCount + 1;
 			const round = this.rounds.append(
 				{
@@ -156,21 +225,28 @@ export class Discussions {
 								options: posed.options,
 								optionsMode: posed.mode,
 								...(posed.optionDescriptions ? { optionDescriptions: posed.optionDescriptions } : {}),
+								...(posed.quiz
+									? { quiz: true, quizCorrectOptions: posed.quiz.correctOptions, quizExplanation: posed.quiz.explanation }
+									: {}),
 							}
 						: {}),
 					...(selected ? { selected } : {}),
+					...(quizResult ? { quizResult } : {}),
 				},
 				new Date().toISOString(),
 			);
 			// Whenever this round answers the pending choice OR poses a new one, the base must drop ALL
-			// three pending* fields first -- otherwise a re-pose that omits descriptions this time would
+			// pending* fields first -- otherwise a re-pose that omits descriptions this time would
 			// leave a stale pendingOptionDescriptions array (sized for the OLD options) spread through
-			// unchanged, no longer aligned 1:1 with the new pendingOptions. Only a plain reply that
-			// neither answers nor re-poses leaves the existing pending state untouched.
+			// unchanged, no longer aligned 1:1 with the new pendingOptions (and likewise for a stale
+			// pendingIsQuiz/pendingQuizRoundNumber pointing at a round that's no longer pending). Only a
+			// plain reply that neither answers nor re-poses leaves the existing pending state untouched.
 			const {
 				pendingOptions: _clearedOptions,
 				pendingOptionsMode: _clearedMode,
 				pendingOptionDescriptions: _clearedDescriptions,
+				pendingIsQuiz: _clearedIsQuiz,
+				pendingQuizRoundNumber: _clearedQuizRoundNumber,
 				...withoutPending
 			} = state;
 			const nextState = {
@@ -181,6 +257,7 @@ export class Discussions {
 							pendingOptions: posed.options,
 							pendingOptionsMode: posed.mode,
 							...(posed.optionDescriptions ? { pendingOptionDescriptions: posed.optionDescriptions } : {}),
+							...(posed.quiz ? { pendingIsQuiz: true, pendingQuizRoundNumber: nextRound } : {}),
 						}
 					: {}),
 			};

package/src/discussion/discussion.ts

@@ -25,6 +25,8 @@ import {
 	DISCUSSION_OPTION_MAX_LENGTH,
 	DISCUSSION_OPTIONS_MAX_COUNT,
 	DISCUSSION_OPTIONS_MIN_COUNT,
+	DISCUSSION_QUIZ_EXPLANATION_MAX_CHARACTERS,
+	DISCUSSION_QUIZ_OPTION_LABEL_MAX_COUNT,
 	DISCUSSION_ROUND_CONTENT_MAX_CHARACTERS,
 	DISCUSSION_SETTLEMENT_MAX_CHARACTERS,
 } from "../constants.ts";
@@ -55,9 +57,25 @@ export interface DiscussionExtra {
 	 * "no description for this one". Purely descriptive metadata: selection/validation only ever
 	 * matches against pendingOptions itself, never against this array. */
 	pendingOptionDescriptions?: string[];
+	/** True when the currently pending posed choice is a graded quiz -- safe to expose (announces
+	 * "this will be graded", never the answer itself, which never lives in extra.discussion at all;
+	 * see AppendDiscussionRound's own comment for where the real answer is kept instead). */
+	pendingIsQuiz?: boolean;
+	/** The round number that posed the currently pending quiz -- lets reply() look up its hidden
+	 * answer in O(1) via DiscussionRoundStore.resolvePendingQuizAnswer, without scanning history. */
+	pendingQuizRoundNumber?: number;
 }
 
-/** One append-only round of a Discussion -- opening statement is round 1. options/optionsMode/selected are the historical record of what was posed/picked in this specific round (extra.discussion.pendingOptions is the separate, mutable "what's unanswered right now" cache). */
+/**
+ * One append-only round of a Discussion -- opening statement is round 1. options/optionsMode/selected
+ * are the historical record of what was posed/picked in this specific round (extra.discussion.pendingOptions
+ * is the separate, mutable "what's unanswered right now" cache).
+ *
+ * quiz/quizResult are the two quiz-safe fields: `quiz: true` marks a posing round as graded (never
+ * the correct answer itself -- that never appears on this type, by construction, see
+ * AppendDiscussionRound); `quizResult` appears only on the round that actually answered a pending
+ * quiz, once grading has already happened -- safe to reveal at that point since submission is done.
+ */
 export interface DiscussionRound {
 	id: number;
 	discussionId: string;
@@ -70,6 +88,19 @@ export interface DiscussionRound {
 	/** Index-aligned with options -- see DiscussionExtra.pendingOptionDescriptions. */
 	optionDescriptions?: string[];
 	selected?: string[];
+	/** True when this round posed a graded quiz alongside options/optionsMode. */
+	quiz?: boolean;
+	/** Present only on the round that answered a pending quiz -- the graded outcome, safe to show
+	 * because the participant has already submitted by the time this exists. */
+	quizResult?: DiscussionQuizResult;
+}
+
+/** The graded outcome of one quiz submission, attached to the answering round. */
+export interface DiscussionQuizResult {
+	correct: boolean;
+	/** The full correct set, drawn verbatim from the options that were offered. */
+	correctOptions: string[];
+	explanation: string;
 }
 
 export interface AppendDiscussionRound {
@@ -81,6 +112,20 @@ export interface AppendDiscussionRound {
 	optionsMode?: DiscussionOptionsMode;
 	optionDescriptions?: string[];
 	selected?: string[];
+	/** Marks this round as posing a graded quiz -- paired with quizCorrectOptions/quizExplanation below. */
+	quiz?: boolean;
+	/**
+	 * Write-only: the quiz's actual answer, persisted for grading but deliberately absent from
+	 * DiscussionRound (the read-side type) -- a store implementation must never select these columns
+	 * into anything it returns from list()/append()'s own return value. Only
+	 * DiscussionRoundStore.resolvePendingQuizAnswer may ever read them back, from within the same
+	 * reply() transaction that performs grading.
+	 */
+	quizCorrectOptions?: string[];
+	quizExplanation?: string;
+	/** The already-graded outcome to persist on an answering round -- computed by discussion-service.ts
+	 * before this reaches the store, never derived by the store itself. */
+	quizResult?: DiscussionQuizResult;
 }
 
 export interface DiscussionRoundQuery {
@@ -150,7 +195,48 @@ export function validateDiscussionOptions(
 	};
 }
 
-/** Validates an answer against the Discussion's currently pending posed choice, if any. */
+/**
+ * Validates a quiz's correct-answer + explanation against the options it's layered onto (already
+ * validated by validateDiscussionOptions). correctOptions is one or more entries drawn verbatim
+ * from options -- exact text match, the same identity scheme `selected` uses. A "single" quiz
+ * (the participant can only pick one) must have exactly one correct option; a "multi" quiz may
+ * have several. explanation is mandatory -- always shown after grading, never optional.
+ */
+export function validateDiscussionQuiz(
+	options: string[],
+	mode: DiscussionOptionsMode,
+	correctOptions: string[],
+	explanation: string,
+): { correctOptions: string[]; explanation: string } {
+	if (correctOptions.length === 0) throw new Error("quiz correct_options must not be empty");
+	if (new Set(correctOptions).size !== correctOptions.length) throw new Error("quiz correct_options must not repeat an entry");
+	const unknown = correctOptions.filter((entry) => !options.includes(entry));
+	if (unknown.length > 0) throw new Error(`quiz correct_options must be among the offered options: ${unknown.join(", ")}`);
+	if (mode === "single" && correctOptions.length !== 1) {
+		throw new Error('a "single" quiz must have exactly one correct_option');
+	}
+	const validExplanation = boundedString(explanation, "explanation", DISCUSSION_QUIZ_EXPLANATION_MAX_CHARACTERS);
+	return { correctOptions: [...correctOptions], explanation: validExplanation };
+}
+
+/** Correct iff the participant's selection exactly matches the quiz's correct set -- no partial credit. */
+export function gradeQuizAnswer(selected: string[], correctOptions: string[]): boolean {
+	return selected.length === correctOptions.length && selected.every((entry) => correctOptions.includes(entry));
+}
+
+/**
+ * Display-only label for a quiz option by its position (A, B, C, ...) -- never persisted, never
+ * part of a quiz's addressing scheme (options/correct_options/selected all match by exact text).
+ * Single letters only: see DISCUSSION_QUIZ_OPTION_LABEL_MAX_COUNT's own comment for why that's
+ * always enough given the enforced DISCUSSION_OPTIONS_MAX_COUNT.
+ */
+export function quizOptionLabel(index: number): string {
+	if (index < 0 || index >= DISCUSSION_QUIZ_OPTION_LABEL_MAX_COUNT) {
+		throw new Error(`quiz option index ${index} has no single-letter label (max ${DISCUSSION_QUIZ_OPTION_LABEL_MAX_COUNT} options)`);
+	}
+	return String.fromCharCode(65 + index);
+}
+
 export function validateSelectedOptions(
 	selected: string[],
 	pendingOptions: string[] | undefined,
@@ -202,6 +288,15 @@ export function readDiscussionExtra(extra: Record<string, unknown>): DiscussionE
 			throw new Error("invalid Discussion pendingOptionDescriptions: must align 1:1 with pendingOptions");
 		}
 	}
+	const pendingIsQuiz = record.pendingIsQuiz;
+	if (pendingIsQuiz !== undefined && typeof pendingIsQuiz !== "boolean") throw new Error("invalid Discussion pendingIsQuiz");
+	const pendingQuizRoundNumber = record.pendingQuizRoundNumber;
+	if (
+		pendingQuizRoundNumber !== undefined &&
+		(typeof pendingQuizRoundNumber !== "number" || !Number.isInteger(pendingQuizRoundNumber) || pendingQuizRoundNumber < 1)
+	) {
+		throw new Error("invalid Discussion pendingQuizRoundNumber");
+	}
 	return {
 		state: state as DiscussionState,
 		roundCount,
@@ -211,5 +306,7 @@ export function readDiscussionExtra(extra: Record<string, unknown>): DiscussionE
 		...(pendingOptions !== undefined ? { pendingOptions: pendingOptions as string[] } : {}),
 		...(pendingOptionsMode !== undefined ? { pendingOptionsMode: pendingOptionsMode as DiscussionOptionsMode } : {}),
 		...(pendingOptionDescriptions !== undefined ? { pendingOptionDescriptions: pendingOptionDescriptions as string[] } : {}),
+		...(pendingIsQuiz !== undefined ? { pendingIsQuiz } : {}),
+		...(pendingQuizRoundNumber !== undefined ? { pendingQuizRoundNumber } : {}),
 	};
 }

package/src/discussion/sqlite-discussion-round-store.ts

@@ -3,6 +3,7 @@ import type { Db } from "../db.ts";
 import {
 	type AppendDiscussionRound,
 	type DiscussionOptionsMode,
+	type DiscussionQuizResult,
 	type DiscussionRound,
 	type DiscussionRoundQuery,
 	validateDiscussionActor,
@@ -11,6 +12,10 @@ import {
 } from "../discussion/discussion.ts";
 import type { DiscussionRoundStore } from "../discussion/discussion-round-store.ts";
 
+// Deliberately excludes quiz_correct_options/quiz_explanation: those are the hidden columns only
+// resolvePendingQuizAnswer's own dedicated, narrower query ever selects. This row type -- and the
+// general-purpose SELECT below that populates it -- structurally cannot leak a quiz's answer,
+// because the shape flowing through mapRow() never carries it in the first place.
 interface DiscussionRoundRow {
 	id: number;
 	discussion_id: string;
@@ -22,9 +27,21 @@ interface DiscussionRoundRow {
 	options_mode: string | null;
 	selected: string | null;
 	option_descriptions: string | null;
+	quiz: number | null;
+	quiz_result_correct: number | null;
+	quiz_result_correct_options: string | null;
+	quiz_result_explanation: string | null;
 }
 
 function mapRow(row: DiscussionRoundRow): DiscussionRound {
+	const quizResult: DiscussionQuizResult | undefined =
+		row.quiz_result_correct !== null
+			? {
+					correct: row.quiz_result_correct === 1,
+					correctOptions: JSON.parse(row.quiz_result_correct_options ?? "[]") as string[],
+					explanation: row.quiz_result_explanation ?? "",
+				}
+			: undefined;
 	return {
 		id: row.id,
 		discussionId: row.discussion_id,
@@ -36,6 +53,8 @@ function mapRow(row: DiscussionRoundRow): DiscussionRound {
 		...(row.options_mode !== null ? { optionsMode: row.options_mode as DiscussionOptionsMode } : {}),
 		...(row.selected !== null ? { selected: JSON.parse(row.selected) as string[] } : {}),
 		...(row.option_descriptions !== null ? { optionDescriptions: JSON.parse(row.option_descriptions) as string[] } : {}),
+		...(row.quiz === 1 ? { quiz: true } : {}),
+		...(quizResult ? { quizResult } : {}),
 	};
 }
 
@@ -52,10 +71,18 @@ export class SQLiteDiscussionRoundStore implements DiscussionRoundStore {
 			round.options !== undefined || round.optionsMode !== undefined
 				? validateDiscussionOptions(round.options ?? [], round.optionsMode ?? "", round.optionDescriptions)
 				: undefined;
+		// quizCorrectOptions/quizExplanation are NOT re-validated here -- discussion-service.ts already
+		// ran validateDiscussionQuiz before this reaches the store, same trust boundary as `selected`
+		// above. quizResult (the already-graded outcome) is likewise computed upstream, never here.
 		const result = this.db
 			.prepare(`
-			INSERT INTO discussion_rounds (discussion_id, round_number, actor, content, occurred_at, event_schema_version, options, options_mode, selected, option_descriptions)
-			VALUES (?, ?, ?, ?, ?, 1, ?, ?, ?, ?)
+			INSERT INTO discussion_rounds (
+				discussion_id, round_number, actor, content, occurred_at, event_schema_version,
+				options, options_mode, selected, option_descriptions,
+				quiz, quiz_correct_options, quiz_explanation,
+				quiz_result_correct, quiz_result_correct_options, quiz_result_explanation
+			)
+			VALUES (?, ?, ?, ?, ?, 1, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 		`)
 			.run(
 				round.discussionId,
@@ -67,6 +94,12 @@ export class SQLiteDiscussionRoundStore implements DiscussionRoundStore {
 				posed ? posed.mode : null,
 				round.selected !== undefined ? JSON.stringify(round.selected) : null,
 				posed?.optionDescriptions ? JSON.stringify(posed.optionDescriptions) : null,
+				round.quiz ? 1 : null,
+				round.quizCorrectOptions !== undefined ? JSON.stringify(round.quizCorrectOptions) : null,
+				round.quizExplanation ?? null,
+				round.quizResult !== undefined ? (round.quizResult.correct ? 1 : 0) : null,
+				round.quizResult !== undefined ? JSON.stringify(round.quizResult.correctOptions) : null,
+				round.quizResult?.explanation ?? null,
 			);
 		return {
 			id: Number(result.lastInsertRowid),
@@ -78,6 +111,10 @@ export class SQLiteDiscussionRoundStore implements DiscussionRoundStore {
 			...(posed ? { options: posed.options, optionsMode: posed.mode } : {}),
 			...(posed?.optionDescriptions ? { optionDescriptions: posed.optionDescriptions } : {}),
 			...(round.selected !== undefined ? { selected: [...round.selected] } : {}),
+			...(round.quiz ? { quiz: true as const } : {}),
+			...(round.quizResult !== undefined
+				? { quizResult: { ...round.quizResult, correctOptions: [...round.quizResult.correctOptions] } }
+				: {}),
 		};
 	}
 
@@ -85,7 +122,8 @@ export class SQLiteDiscussionRoundStore implements DiscussionRoundStore {
 		const limit = Math.min(DISCUSSION_ROUNDS_MAX_LIMIT, Math.max(1, Math.floor(query.limit ?? DISCUSSION_ROUNDS_DEFAULT_LIMIT)));
 		const rows = this.db
 			.prepare(`
-			SELECT id, discussion_id, round_number, actor, content, occurred_at, options, options_mode, selected, option_descriptions
+			SELECT id, discussion_id, round_number, actor, content, occurred_at, options, options_mode, selected, option_descriptions,
+			       quiz, quiz_result_correct, quiz_result_correct_options, quiz_result_explanation
 			FROM discussion_rounds
 			WHERE discussion_id = ? AND round_number > ?
 			ORDER BY round_number ASC
@@ -98,4 +136,14 @@ export class SQLiteDiscussionRoundStore implements DiscussionRoundStore {
 	count(discussionId: string): number {
 		return (this.db.prepare("SELECT COUNT(*) AS c FROM discussion_rounds WHERE discussion_id = ?").get(discussionId) as { c: number }).c;
 	}
+
+	// The one place quiz_correct_options/quiz_explanation are ever read back -- a narrow, dedicated
+	// query naming exactly those two hidden columns, deliberately separate from list()'s own SELECT.
+	resolvePendingQuizAnswer(discussionId: string, roundNumber: number): { correctOptions: string[]; explanation: string } | undefined {
+		const row = this.db
+			.prepare("SELECT quiz_correct_options, quiz_explanation FROM discussion_rounds WHERE discussion_id = ? AND round_number = ?")
+			.get(discussionId, roundNumber) as { quiz_correct_options: string | null; quiz_explanation: string | null } | undefined;
+		if (!row || row.quiz_correct_options === null || row.quiz_explanation === null) return undefined;
+		return { correctOptions: JSON.parse(row.quiz_correct_options) as string[], explanation: row.quiz_explanation };
+	}
 }

package/src/handlers/discuss.ts

@@ -17,8 +17,13 @@ import type { VehicleContentBlock } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
 import type { Artifact } from "../artifact/artifact.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
-import { DISCUSSION_OPTION_DESCRIPTION_MAX_LENGTH, DISCUSSION_OPTION_MAX_LENGTH, DISCUSSION_OPTIONS_MAX_COUNT } from "../constants.ts";
-import { DISCUSSION_SUBTYPE, type DiscussionRound } from "../discussion/discussion.ts";
+import {
+	DISCUSSION_OPTION_DESCRIPTION_MAX_LENGTH,
+	DISCUSSION_OPTION_MAX_LENGTH,
+	DISCUSSION_OPTIONS_MAX_COUNT,
+	DISCUSSION_QUIZ_EXPLANATION_MAX_CHARACTERS,
+} from "../constants.ts";
+import { DISCUSSION_SUBTYPE, type DiscussionRound, quizOptionLabel } from "../discussion/discussion.ts";
 import type { DiscussionAndRounds, Discussions } from "../discussion/discussion-service.ts";
 import { discussOperations } from "../modules/discuss.ts";
 import {
@@ -43,6 +48,19 @@ function roundsTranscript(rounds: readonly DiscussionRound[]): string {
 	return rounds.map((round) => `  [round ${round.roundNumber}] ${round.actor}: ${round.content}`).join("\n") || "  (no rounds)";
 }
 
+/** Lettered rendering of a quiz round's options (A, B, C, ...) -- never shown for a plain, non-quiz
+ * posed choice, which keeps its existing comma-joined presentation unchanged (backward compatible). */
+function formatQuizOptions(options: readonly string[]): string {
+	return options.map((option, index) => `${quizOptionLabel(index)}. ${option}`).join("  ");
+}
+
+/** Appended to reply's own content block once a submission answered a pending quiz -- always states
+ * correct/incorrect and always includes the explanation (never optional, especially when wrong). */
+function formatQuizVerdict(result: { correct: boolean; correctOptions: string[]; explanation: string }): string {
+	const verdict = result.correct ? "✅ Correct!" : `❌ Incorrect -- correct answer(s): ${result.correctOptions.join(", ")}.`;
+	return `${verdict} ${result.explanation}`;
+}
+
 /**
  * Resolves a discussion's id from either an explicit id or its exact title.
  * Discussions.list() has no project-scoping concept at all (unlike Tasks),
@@ -129,6 +147,12 @@ const optionsUnionSchema = { type: "array" } as const;
  */
 const OPTION_BOUNDS_TEXT = `Each option is at most ${DISCUSSION_OPTION_MAX_LENGTH} characters (up to ${DISCUSSION_OPTIONS_MAX_COUNT} total); each description is at most ${DISCUSSION_OPTION_DESCRIPTION_MAX_LENGTH} characters.`;
 
+/**
+ * Quiz support layered onto the same options/options_mode a plain posed choice already uses.
+ * Interpolates the real, enforced explanation bound the same way OPTION_BOUNDS_TEXT does for options.
+ */
+const QUIZ_BOUNDS_TEXT = `To make it a graded quiz/knowledge assessment instead of a plain posed choice, also pass correct_options (one or more entries drawn verbatim from options -- exact text, not an index or display letter) + explanation (REQUIRED, at most ${DISCUSSION_QUIZ_EXPLANATION_MAX_CHARACTERS} characters, always shown after grading -- especially when wrong). A "single" quiz needs exactly one correct option; "multi" allows several, graded correct iff the reply's selected set exactly matches (no partial credit). Options display as lettered choices (A, B, C, ...) once a quiz is posed.`;
+
 export function registerDiscussVehicleOperations(registry: VehicleRegistry, discussions: Discussions, artifacts: ArtifactStore): void {
 	const moduleOperations = new Map(discussOperations(discussions).map((op) => [op.name, op]));
 	const call = <Output>(name: string, input: Record<string, unknown>): Output => moduleOperations.get(name)!.execute(input) as Output;
@@ -163,7 +187,7 @@ export function registerDiscussVehicleOperations(registry: VehicleRegistry, disc
 
 	define(
 		"open",
-		`Opens a new Discussion and starts round 1. Optionally poses a structured choice via options (2-10 entries) + options_mode ('single' mutually exclusive, 'multi' allows several) -- each option a bare string (self-evident) or {title, description} (a real tradeoff worth spelling out; description REQUIRED once there are 3+ options). ${OPTION_BOUNDS_TEXT} Optionally blocks one or more Tasks immediately via blocks_task_ids/blocks_task_names. Pass live:true to get a human's answer synchronously in this same call, via an interactive prompt -- only takes effect with an interactive UI available, otherwise degrades silently to the normal durably-recorded round.`,
+		`Opens a new Discussion and starts round 1. Optionally poses a structured choice via options (2-10 entries) + options_mode ('single' mutually exclusive, 'multi' allows several) -- each option a bare string (self-evident) or {title, description} (a real tradeoff worth spelling out; description REQUIRED once there are 3+ options). ${OPTION_BOUNDS_TEXT} ${QUIZ_BOUNDS_TEXT} Optionally blocks one or more Tasks immediately via blocks_task_ids/blocks_task_names. Pass live:true to get a human's answer synchronously in this same call, via an interactive prompt -- only takes effect with an interactive UI available, otherwise degrades silently to the normal durably-recorded round.`,
 		"local-write",
 		{
 			title: stringProp,
@@ -176,6 +200,8 @@ export function registerDiscussVehicleOperations(registry: VehicleRegistry, disc
 			options: optionsUnionSchema,
 			options_mode: { type: "string", enum: ["single", "multi"] },
 			option_descriptions: arrayProp,
+			correct_options: arrayProp,
+			explanation: stringProp,
 			live: boolProp,
 			source: stringProp,
 			session_id: stringProp,
@@ -189,13 +215,15 @@ export function registerDiscussVehicleOperations(registry: VehicleRegistry, disc
 		},
 		(raw) => {
 			const result = raw as DiscussionAndRounds;
-			return { ...result, content: [contentBlock(`Opened discussion ${artifactLine(result.discussion)}`)] };
+			const posed = result.rounds[0];
+			const quizNote = posed?.quiz && posed.options ? `\n${formatQuizOptions(posed.options)}` : "";
+			return { ...result, content: [contentBlock(`Opened discussion ${artifactLine(result.discussion)}${quizNote}`)] };
 		},
 	);
 
 	define(
 		"reply",
-		`Adds a round to an existing Discussion. Refused once deferred or settled -- resume first. Answers a currently pending posed choice via \`selected\` (validated against it), or poses a new choice via options/options_mode. ${OPTION_BOUNDS_TEXT} Prefer \`name\` over \`id\`. Pass live:true to get a human's answer synchronously in this same call, via the pending choice's picker if one was posed, otherwise a freeform question -- only takes effect with an interactive UI available, otherwise degrades silently to the normal durably-recorded round.`,
+		`Adds a round to an existing Discussion. Refused once deferred or settled -- resume first. Answers a currently pending posed choice via \`selected\` (validated against it) -- if that choice was a quiz, the answer is graded automatically and the verdict + explanation come back in this same call. Or poses a new choice via options/options_mode. ${OPTION_BOUNDS_TEXT} ${QUIZ_BOUNDS_TEXT} Prefer \`name\` over \`id\`. Pass live:true to get a human's answer synchronously in this same call, via the pending choice's picker if one was posed, otherwise a freeform question -- only takes effect with an interactive UI available, otherwise degrades silently to the normal durably-recorded round.`,
 		"local-write",
 		{
 			id: stringProp,
@@ -206,6 +234,8 @@ export function registerDiscussVehicleOperations(registry: VehicleRegistry, disc
 			options: optionsUnionSchema,
 			options_mode: { type: "string", enum: ["single", "multi"] },
 			option_descriptions: arrayProp,
+			correct_options: arrayProp,
+			explanation: stringProp,
 			live: boolProp,
 			source: stringProp,
 			session_id: stringProp,
@@ -218,9 +248,12 @@ export function registerDiscussVehicleOperations(registry: VehicleRegistry, disc
 		},
 		(raw) => {
 			const result = raw as DiscussionAndRounds;
+			const answered = result.rounds[0];
+			const posed = answered?.quiz && answered.options ? `\n${formatQuizOptions(answered.options)}` : "";
+			const verdict = answered?.quizResult ? `\n${formatQuizVerdict(answered.quizResult)}` : "";
 			return {
 				...result,
-				content: [contentBlock(`Round ${result.rounds[0]?.roundNumber} added to "${result.discussion.title}"`)],
+				content: [contentBlock(`Round ${answered?.roundNumber} added to "${result.discussion.title}"${posed}${verdict}`)],
 			};
 		},
 	);

package/src/index.ts

@@ -17,7 +17,13 @@ export {
 	type VehicleClientTarget,
 } from "./client.ts";
 export * from "./constants.ts";
-export { DISCUSSION_SUBTYPE, type DiscussionRound, readDiscussionExtra } from "./discussion/discussion.ts";
+export {
+	DISCUSSION_SUBTYPE,
+	type DiscussionQuizResult,
+	type DiscussionRound,
+	quizOptionLabel,
+	readDiscussionExtra,
+} from "./discussion/discussion.ts";
 export type { DiscussionAndRounds } from "./discussion/discussion-service.ts";
 export type { DisplayGraph, DisplayGraphEdge, DisplayGraphNode, RenderedGraph } from "./display-graph/display-graph.ts";
 export type { GraphRenderer } from "./display-graph/graph-renderer.ts";

package/src/modules/discuss.ts

@@ -76,6 +76,8 @@ export function discussOperations(discussions: Discussions): OperationDefinition
 					options: optionalStringArray(input, "options"),
 					optionsMode: optionsMode(input),
 					optionDescriptions: optionalStringArray(input, "option_descriptions") ?? optionalStringArray(input, "optionDescriptions"),
+					quizCorrectOptions: optionalStringArray(input, "correct_options") ?? optionalStringArray(input, "correctOptions"),
+					quizExplanation: optionalString(input, "explanation"),
 				},
 				eventContext(input),
 			),
@@ -90,6 +92,8 @@ export function discussOperations(discussions: Discussions): OperationDefinition
 					options: optionalStringArray(input, "options"),
 					optionsMode: optionsMode(input),
 					optionDescriptions: optionalStringArray(input, "option_descriptions") ?? optionalStringArray(input, "optionDescriptions"),
+					quizCorrectOptions: optionalStringArray(input, "correct_options") ?? optionalStringArray(input, "correctOptions"),
+					quizExplanation: optionalString(input, "explanation"),
 				},
 				eventContext(input),
 			),