@happyvertical/smrt-education 0.57.43 → 0.57.44

package/dist/question-authoring-service.d.ts

@@ -0,0 +1,125 @@
+import type { DatabaseInterface } from '@happyvertical/sql';
+import { type CourseAuthoringActor, type CourseAuthoringAuthorizer } from './course-authoring-contracts.js';
+import { CourseAuthoringService, type CourseAuthoringServiceOptions } from './course-authoring-service.js';
+import { type LearningObjectiveInput, type LearningObjectiveView, type QuestionContentInput, type QuestionHeadView, type QuestionRevisionView, type ReleasedLessonView, type ResolvedQuestionRevisions, type WorksheetBundle } from './question-contracts.js';
+export interface QuestionAuthoringServiceOptions extends CourseAuthoringServiceOptions {
+    /** Trusted concept ids; when supplied, question and objective concepts must belong. */
+    conceptVocabulary?: ReadonlyArray<{
+        id: string;
+    }>;
+}
+/**
+ * Actor-bound authoring of immutable questions and stable learning objectives.
+ * It shares `CourseAuthoringService`'s authorizer and actions: writes need
+ * `education.course.author` (plus `generate` for generated provenance); reads of
+ * answer keys need `education.course.read-draft`.
+ */
+export declare class QuestionAuthoringService extends CourseAuthoringService {
+    private readonly vocabulary;
+    constructor(db: DatabaseInterface, authorizer: CourseAuthoringAuthorizer, options?: QuestionAuthoringServiceOptions);
+    private normalize;
+    private normalizeObjective;
+    private authorizeWrite;
+    /** Objectives and media named by a revision must exist in the same tenant. */
+    private requireReferences;
+    private lock;
+    private head;
+    /** Creates the stable question identity and its first immutable revision. */
+    createQuestion(request: CourseAuthoringActor & {
+        requestKey: string;
+        courseId?: string;
+        content: QuestionContentInput;
+    }): Promise<QuestionHeadView>;
+    private appendQuestionRevision;
+    /**
+     * Appends an immutable revision when `expectedHeadRevisionId` is still the
+     * head. A retried key replays its original result; the same key with a
+     * different payload is a typed conflict.
+     */
+    saveQuestionRevision(request: CourseAuthoringActor & {
+        questionId: string;
+        expectedHeadRevisionId: string;
+        requestKey: string;
+        content: QuestionContentInput;
+    }): Promise<QuestionHeadView>;
+    /** Replaces a question's objective links by appending a revision. */
+    linkObjectives(request: CourseAuthoringActor & {
+        questionId: string;
+        expectedHeadRevisionId: string;
+        requestKey: string;
+        objectiveIds: string[];
+    }): Promise<QuestionHeadView>;
+    private saveRevision;
+    private questionRow;
+    private contentFromRow;
+    private questionRevisionView;
+    /** Reads a question revision (the head unless `revisionId` is given), key included. */
+    readQuestion(request: CourseAuthoringActor & {
+        questionId: string;
+        revisionId?: string;
+    }): Promise<{
+        head: QuestionHeadView;
+        revision: QuestionRevisionView;
+    }>;
+    /**
+     * Resolves question revision ids to reference labels for a host (e.g. a printed
+     * worksheet's question list). Needs `read-draft` (operation
+     * `resolve-question-revisions`, no course). Tenant-exact: an id that is unknown
+     * or belongs to another tenant is simply reported in `missing`, with no
+     * distinction. The result never carries answer keys, rubrics, choices, media or
+     * provenance. At most 200 ids; duplicates are folded; an empty list, a
+     * non-string or an over-long id is a validation error.
+     */
+    resolveQuestionRevisions(request: CourseAuthoringActor & {
+        revisionIds: string[];
+    }): Promise<ResolvedQuestionRevisions>;
+    /**
+     * Creates a stable objective identity under a tenant-unique `externalKey`. The
+     * same key with the same request replays; any other use of the key conflicts.
+     */
+    createLearningObjective(request: CourseAuthoringActor & {
+        requestKey: string;
+        externalKey: string;
+        objective: LearningObjectiveInput;
+    }): Promise<LearningObjectiveView>;
+    private appendObjective;
+    /** Appends new wording; the objective's id and `externalKey` never change. */
+    saveLearningObjectiveRevision(request: CourseAuthoringActor & {
+        objectiveId: string;
+        expectedHeadRevisionId: string;
+        requestKey: string;
+        objective: LearningObjectiveInput;
+    }): Promise<LearningObjectiveView>;
+    private objectiveRow;
+    private objectiveView;
+    /** Reads an objective by id or by its stable external key. */
+    readLearningObjective(request: CourseAuthoringActor & {
+        objectiveId?: string;
+        externalKey?: string;
+    }): Promise<LearningObjectiveView>;
+    /**
+     * Render input for one lesson of a release, from its pinned question
+     * revisions. `learner` omits keys and rubrics by type. Both audiences need
+     * `read-draft` here; learner delivery is a host path that calls
+     * `buildLearnerWorksheet` over data it already authorized.
+     */
+    getWorksheet(request: CourseAuthoringActor & {
+        releaseId: string;
+        lessonKey: string;
+        audience: 'learner' | 'guardian';
+    }): Promise<WorksheetBundle>;
+    /** The release lesson's immutable revision row and keyed worksheet inputs. */
+    private releasedLessonInput;
+    /**
+     * Authoring/guardian read of one released lesson: the full lesson revision
+     * (materials, provenance, ordered question refs, layout params) and the keyed
+     * worksheet bundle (answer keys and rubrics included). Needs `read-draft`;
+     * learners use `QuestionResponseService.readReleasedLesson`, which is keyless
+     * and limited to their effective lessons.
+     */
+    readReleasedLesson(request: CourseAuthoringActor & {
+        releaseId: string;
+        lessonKey: string;
+    }): Promise<ReleasedLessonView>;
+}
+//# sourceMappingURL=question-authoring-service.d.ts.map

package/dist/question-authoring-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-authoring-service.d.ts","sourceRoot":"","sources":["../src/question-authoring-service.ts"],"names":[],"mappings":"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"}

package/dist/question-content.d.ts

@@ -0,0 +1,25 @@
+import { type QuestionAnswerKey, type QuestionChoice, type QuestionContentInput, type QuestionField, type QuestionMediaRef, type QuestionProvenance, type QuestionResponseType, type QuestionRubric, type QuestionSubpart } from './question-contracts.js';
+export interface NormalizedQuestionContent {
+    prompt: string;
+    responseType: QuestionResponseType;
+    choices: QuestionChoice[];
+    subparts: QuestionSubpart[];
+    media: Required<QuestionMediaRef>[];
+    objectiveIds: string[];
+    conceptIds: string[];
+    /** Null when no key was supplied; never an empty key. */
+    answerKey: QuestionAnswerKey | null;
+    rubric: QuestionRubric | null;
+    pointsPossible: number | null;
+    provenance: QuestionProvenance;
+    /** Effective provenance of every present field; absent fields have no entry. */
+    fieldProvenance: Partial<Record<QuestionField, QuestionProvenance>>;
+}
+/**
+ * Validates and normalizes authored question content. Pure; ownership checks
+ * (assets, objectives) are the caller's. Throws `CourseAuthoringValidationError`.
+ */
+export declare function normalizeQuestionContent(input: QuestionContentInput, options?: {
+    conceptVocabulary?: ReadonlySet<string>;
+}): NormalizedQuestionContent;
+//# sourceMappingURL=question-content.d.ts.map

package/dist/question-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-content.d.ts","sourceRoot":"","sources":["../src/question-content.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,yBAAyB,CAAC;AAMjC,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,oBAAoB,CAAC;IACnC,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,KAAK,EAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;IACpC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,yDAAyD;IACzD,SAAS,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,kBAAkB,CAAC;IAC/B,gFAAgF;IAChF,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC,CAAC;CACrE;AAyED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,oBAAoB,EAC3B,OAAO,GAAE;IAAE,iBAAiB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAAO,GACxD,yBAAyB,CAuP3B"}

package/dist/question-contracts.d.ts

@@ -0,0 +1,240 @@
+import { type CourseAuthoringActor, CourseAuthoringError, type CourseLessonCompletion, type CourseLessonRevisionView, type CourseLessonType } from './course-authoring-contracts.js';
+import type { QuestionRubric } from './question-rubric.js';
+export type { QuestionRubric, QuestionRubricCriterion, } from './question-rubric.js';
+/** Supplied by the author, or inferred/generated/extracted by a tool. */
+export type QuestionProvenance = 'supplied' | 'inferred' | 'generated' | 'edited' | 'extracted';
+export declare const QUESTION_PROVENANCES: readonly QuestionProvenance[];
+export type QuestionResponseType = 'short-answer' | 'numeric' | 'multiple-choice' | 'multi-select' | 'true-false' | 'extended' | 'multi-part';
+export declare const QUESTION_RESPONSE_TYPES: readonly QuestionResponseType[];
+/** Where a learner completed the question; same completion vocabulary as workbooks. */
+export type QuestionCompletionMode = 'printable' | 'online' | 'interactive';
+export declare const QUESTION_COMPLETION_MODES: readonly QuestionCompletionMode[];
+export type QuestionAssistance = 'independent' | 'assisted' | 'unknown';
+/** Fields that carry their own provenance. A field that is absent has no entry. */
+export type QuestionField = 'prompt' | 'responseType' | 'choices' | 'subparts' | 'media' | 'objectives' | 'concepts' | 'answerKey' | 'rubric' | 'pointsPossible';
+export declare const QUESTION_FIELDS: readonly QuestionField[];
+export interface QuestionChoice {
+    id: string;
+    label: string;
+}
+export interface QuestionSubpart {
+    partKey: string;
+    prompt: string;
+    responseType?: Exclude<QuestionResponseType, 'multi-part'>;
+    pointsPossible?: number;
+}
+export interface QuestionMediaRef {
+    assetId: string;
+    role?: 'figure' | 'passage' | 'audio' | 'other';
+    alt?: string;
+}
+/** Atomic accepted answer(s). At least one member is required; never `{}`. */
+export interface QuestionAnswerAtom {
+    correctChoiceIds?: string[];
+    acceptedAnswers?: string[];
+    numeric?: {
+        value: number;
+        tolerance?: number;
+    };
+}
+export interface QuestionAnswerKey extends QuestionAnswerAtom {
+    /** Per-subpart keys by `partKey`. */
+    parts?: Record<string, QuestionAnswerAtom>;
+    explanation?: string;
+}
+/** Everything an author states about one question revision. */
+export interface QuestionContentInput {
+    prompt: string;
+    responseType: QuestionResponseType;
+    choices?: QuestionChoice[];
+    subparts?: QuestionSubpart[];
+    media?: QuestionMediaRef[];
+    /** Stable `LearningObjective` identity ids. */
+    objectiveIds?: string[];
+    conceptIds?: string[];
+    /** Omit (or null) when no key exists: a missing key stays missing. */
+    answerKey?: QuestionAnswerKey | null;
+    rubric?: QuestionRubric | null;
+    pointsPossible?: number | null;
+    /** Default for every present field without its own entry. */
+    provenance: QuestionProvenance;
+    fieldProvenance?: Partial<Record<QuestionField, QuestionProvenance>>;
+}
+export interface QuestionRevisionView {
+    id: string;
+    questionId: string;
+    parentRevisionId: string | null;
+    sequence: number;
+    prompt: string;
+    responseType: QuestionResponseType;
+    choices: QuestionChoice[];
+    subparts: QuestionSubpart[];
+    media: QuestionMediaRef[];
+    objectives: Array<{
+        objectiveId: string;
+        externalKey: string;
+        revisionId: string;
+        statement: string;
+    }>;
+    conceptIds: string[];
+    /** Null means no key was ever supplied; it is never an empty/zero key. */
+    answerKey: QuestionAnswerKey | null;
+    rubric: QuestionRubric | null;
+    pointsPossible: number | null;
+    provenance: QuestionProvenance;
+    fieldProvenance: Partial<Record<QuestionField, QuestionProvenance>>;
+    authorUserId: string;
+    delegatingGuardianUserId: string | null;
+    delegationId: string | null;
+    recordedAt: string;
+}
+/** Most question revision ids one `resolveQuestionRevisions` call accepts. */
+export declare const MAX_RESOLVE_QUESTION_REVISIONS = 200;
+/** Longest `promptSummary`, in characters. */
+export declare const QUESTION_PROMPT_SUMMARY_LENGTH = 200;
+/**
+ * A question revision as a host reference label. Never carries an answer key,
+ * rubric, choices, media or provenance.
+ */
+export interface QuestionRevisionSummary {
+    revisionId: string;
+    questionId: string;
+    sequence: number;
+    responseType: QuestionResponseType;
+    /** Plain-text excerpt of the prompt: whitespace collapsed, at most 200 characters. */
+    promptSummary: string;
+    /** Stable objective external keys; present only when the revision links objectives. */
+    learningObjectiveKeys?: string[];
+}
+export interface ResolvedQuestionRevisions {
+    /** Found revisions, in the order of the first occurrence of each requested id. */
+    items: QuestionRevisionSummary[];
+    /** Requested ids with no revision in this tenant (foreign and unknown are alike). */
+    missing: string[];
+}
+export interface QuestionHeadView {
+    questionId: string;
+    /** The expected-head token for the next save. */
+    headRevisionId: string;
+    sequence: number;
+}
+export interface LearningObjectiveInput {
+    statement: string;
+    conceptIds?: string[];
+    subject?: string;
+    levelMin?: number;
+    levelMax?: number;
+    provenance?: QuestionProvenance;
+}
+export interface LearningObjectiveView {
+    id: string;
+    /** Stable key shared with consumers (for example hearthed.org#35). */
+    externalKey: string;
+    headRevisionId: string;
+    sequence: number;
+    statement: string;
+    conceptIds: string[];
+    subject: string;
+    levelMin: number;
+    levelMax: number;
+    provenance: QuestionProvenance;
+}
+/** One ordered question in a lesson revision. Order is array order. */
+export interface LessonQuestionRefInput {
+    questionRevisionId: string;
+    section?: string;
+    column?: number;
+    /** Source page/region where known; normalized `rect` is x, y, width, height. */
+    anchor?: {
+        assetId?: string;
+        page?: number;
+        rect?: [number, number, number, number];
+    };
+}
+export type LessonLayoutParams = Record<string, string | number | boolean>;
+/** Learner-facing item. Built from an allowlist, so keys and rubrics cannot leak. */
+export interface LearnerQuestionItem {
+    ordinal: number;
+    questionId: string;
+    questionRevisionId: string;
+    section: string;
+    column: number;
+    anchor: LessonQuestionRefInput['anchor'] | null;
+    prompt: string;
+    responseType: QuestionResponseType;
+    choices: QuestionChoice[];
+    subparts: QuestionSubpart[];
+    media: QuestionMediaRef[];
+    pointsPossible: number | null;
+}
+export interface GuardianQuestionItem extends LearnerQuestionItem {
+    answerKey: QuestionAnswerKey | null;
+    rubric: QuestionRubric | null;
+    fieldProvenance: Partial<Record<QuestionField, QuestionProvenance>>;
+}
+interface WorksheetBundleBase {
+    /** Digest of ordered question revision ids and layout params. */
+    worksheetVersionId: string;
+    lessonRevisionId: string;
+    layoutParams: LessonLayoutParams;
+}
+export interface LearnerWorksheetBundle extends WorksheetBundleBase {
+    audience: 'learner';
+    items: LearnerQuestionItem[];
+}
+export interface GuardianWorksheetBundle extends WorksheetBundleBase {
+    audience: 'guardian';
+    items: GuardianQuestionItem[];
+}
+export type WorksheetBundle = LearnerWorksheetBundle | GuardianWorksheetBundle;
+export type QuestionActor = CourseAuthoringActor;
+/**
+ * Authoring/guardian read of one released lesson (`read-draft`): the full lesson
+ * revision (materials and provenance included) and the keyed worksheet bundle.
+ */
+export type ReleasedLessonView = Readonly<{
+    releaseId: string;
+    courseId: string;
+    lessonKey: string;
+    lessonId: string;
+    sectionId: string;
+    lessonRevisionId: string;
+    revision: CourseLessonRevisionView;
+    worksheet: GuardianWorksheetBundle;
+}>;
+/**
+ * Learner-safe read of one effective lesson. Built from an allowlist: no key,
+ * rubric, provenance, material, source locator or licence detail. The body of a
+ * personal-use-copy lesson is withheld (empty, `bodyWithheld`).
+ */
+export type LearnerLessonView = Readonly<{
+    enrollmentId: string;
+    releaseId: string;
+    lessonKey: string;
+    lessonId: string;
+    lessonRevisionId: string;
+    title: string;
+    body: string;
+    bodyWithheld: boolean;
+    lessonType: CourseLessonType;
+    completionRule: CourseLessonCompletion;
+    estimatedMinutes: number;
+    /** True when a started lesson stays on an older release than the current pin. */
+    pinnedToOlderRelease: boolean;
+    worksheet: LearnerWorksheetBundle;
+}>;
+export declare class QuestionNotFoundError extends CourseAuthoringError {
+    constructor();
+}
+export declare class LearningObjectiveNotFoundError extends CourseAuthoringError {
+    constructor();
+}
+export declare class LearningObjectiveKeyConflictError extends CourseAuthoringError {
+    constructor();
+}
+/** A lesson revision named a question revision that is missing or foreign. */
+export declare class QuestionReferenceError extends CourseAuthoringError {
+    readonly references: readonly string[];
+    constructor(references: readonly string[]);
+}
+//# sourceMappingURL=question-contracts.d.ts.map

package/dist/question-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-contracts.d.ts","sourceRoot":"","sources":["../src/question-contracts.ts"],"names":[],"mappings":"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"}

package/dist/question-models.d.ts

@@ -0,0 +1,124 @@
+import { SmrtCollection, SmrtObject, type SmrtSaveOptions } from '@happyvertical/smrt-core';
+/** Stable learning-objective identity: survives wording changes, variants and themes. */
+export declare class LearningObjective extends SmrtObject {
+    tenantId: string;
+    /** Stable coordination key (for example with hearthed.org#35); unique per tenant. */
+    externalKey: string;
+    createdByUserId: string;
+    requestKey: string;
+    recordedAt: Date;
+    constructor(options?: Record<string, unknown>);
+    delete(): Promise<void>;
+    save(options?: SmrtSaveOptions): Promise<this>;
+}
+export declare class LearningObjectiveCollection extends SmrtCollection<LearningObjective> {
+    static readonly _itemClass: typeof LearningObjective;
+}
+/** Append-only objective wording; the highest sequence is the head. */
+export declare class LearningObjectiveRevision extends SmrtObject {
+    tenantId: string;
+    objectiveId: string;
+    parentRevisionId: string | null;
+    sequence: number;
+    statement: string;
+    conceptIdsJson: string;
+    subject: string;
+    levelMin: number;
+    levelMax: number;
+    provenance: string;
+    authorUserId: string;
+    delegatingGuardianUserId: string;
+    delegationId: string;
+    requestKey: string;
+    payloadDigest: string;
+    recordedAt: Date;
+    constructor(options?: Record<string, unknown>);
+    delete(): Promise<void>;
+    save(options?: SmrtSaveOptions): Promise<this>;
+}
+export declare class LearningObjectiveRevisionCollection extends SmrtCollection<LearningObjectiveRevision> {
+    static readonly _itemClass: typeof LearningObjectiveRevision;
+}
+/** Stable question identity. Content lives only in immutable revisions. */
+export declare class Question extends SmrtObject {
+    tenantId: string;
+    /** Authored course this question was written for; reuse across courses is allowed. */
+    courseId: string | null;
+    createdByUserId: string;
+    requestKey: string;
+    recordedAt: Date;
+    constructor(options?: Record<string, unknown>);
+    delete(): Promise<void>;
+    save(options?: SmrtSaveOptions): Promise<this>;
+}
+export declare class QuestionCollection extends SmrtCollection<Question> {
+    static readonly _itemClass: typeof Question;
+}
+/**
+ * Immutable question snapshot. A missing answer key or rubric is stored as NULL
+ * and never as an empty object, zero or an inferred value.
+ */
+export declare class QuestionRevision extends SmrtObject {
+    tenantId: string;
+    questionId: string;
+    parentRevisionId: string | null;
+    sequence: number;
+    prompt: string;
+    responseType: string;
+    choicesJson: string;
+    subpartsJson: string;
+    mediaJson: string;
+    objectiveIdsJson: string;
+    conceptIdsJson: string;
+    answerKeyJson: string | null;
+    rubricJson: string | null;
+    pointsPossible: number | null;
+    provenance: string;
+    fieldProvenanceJson: string;
+    authorUserId: string;
+    delegatingGuardianUserId: string;
+    delegationId: string;
+    requestKey: string;
+    payloadDigest: string;
+    recordedAt: Date;
+    constructor(options?: Record<string, unknown>);
+    delete(): Promise<void>;
+    save(options?: SmrtSaveOptions): Promise<this>;
+}
+export declare class QuestionRevisionCollection extends SmrtCollection<QuestionRevision> {
+    static readonly _itemClass: typeof QuestionRevision;
+}
+/**
+ * Append-only learner response to one exact question revision. A correction is a
+ * new row naming its predecessor; a response never rewrites question content.
+ */
+export declare class QuestionResponse extends SmrtObject {
+    tenantId: string;
+    learnerId: string;
+    enrollmentId: string;
+    questionRevisionId: string;
+    lessonRevisionId: string | null;
+    /** The worksheet render the learner saw, for scan matching. */
+    worksheetVersionId: string;
+    submissionId: string | null;
+    previousResponseId: string | null;
+    /** Groups an attempt and its corrections. */
+    episodeId: string;
+    completionMode: string;
+    assistance: string;
+    responseJson: string;
+    /** 1-based attempt (episode) number per learner and question revision. */
+    attemptNumber: number;
+    actorUserId: string;
+    requestKey: string;
+    /** Digest of the request that wrote this row; empty for rows written directly. */
+    payloadDigest: string;
+    recordedAt: Date;
+    constructor(options?: Record<string, unknown>);
+    delete(): Promise<void>;
+    save(options?: SmrtSaveOptions): Promise<this>;
+}
+export declare class QuestionResponseCollection extends SmrtCollection<QuestionResponse> {
+    static readonly _itemClass: typeof QuestionResponse;
+}
+//# sourceMappingURL=question-models.d.ts.map

package/dist/question-models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-models.d.ts","sourceRoot":"","sources":["../src/question-models.ts"],"names":[],"mappings":"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"}

package/dist/question-render.d.ts

@@ -0,0 +1,20 @@
+import type { GuardianWorksheetBundle, LearnerWorksheetBundle, LessonLayoutParams, LessonQuestionRefInput, QuestionRevisionView } from './question-contracts.js';
+export declare const canonical: (value: unknown) => string;
+/**
+ * Deterministic id of one worksheet layout: the ordered question revisions with
+ * their placement plus the layout params. Printable and online renders of the
+ * same inputs share it, so a later scan can be matched to the exact revisions.
+ */
+export declare function worksheetVersionId(refs: readonly LessonQuestionRefInput[], layoutParams?: LessonLayoutParams): string;
+export interface WorksheetRenderInput {
+    lessonRevisionId: string;
+    refs: readonly LessonQuestionRefInput[];
+    layoutParams?: LessonLayoutParams;
+    /** The pinned revisions, by id. Every ref must resolve. */
+    revisions: ReadonlyMap<string, QuestionRevisionView>;
+}
+/** Render input for learners (printable or online); answer keys are excluded by type. */
+export declare function buildLearnerWorksheet(input: WorksheetRenderInput): LearnerWorksheetBundle;
+/** Guardian/author bundle: the same items plus keys, rubrics and provenance. */
+export declare function buildGuardianWorksheet(input: WorksheetRenderInput): GuardianWorksheetBundle;
+//# sourceMappingURL=question-render.d.ts.map

package/dist/question-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-render.d.ts","sourceRoot":"","sources":["../src/question-render.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,uBAAuB,EAEvB,sBAAsB,EACtB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,yBAAyB,CAAC;AAEjC,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,MAOxC,CAAC;AAEJ;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,sBAAsB,EAAE,EACvC,YAAY,GAAE,kBAAuB,GACpC,MAAM,CAWR;AAwBD,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACxC,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,2DAA2D;IAC3D,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;CACtD;AAUD,yFAAyF;AACzF,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,oBAAoB,GAC1B,sBAAsB,CASxB;AAED,gFAAgF;AAChF,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,GAC1B,uBAAuB,CAgBzB"}

package/dist/question-response-contracts.d.ts

@@ -0,0 +1,54 @@
+import { CourseAuthoringError } from './course-authoring-contracts.js';
+import type { GuardianWorksheetBundle, LearnerWorksheetBundle, QuestionAssistance, QuestionCompletionMode } from './question-contracts.js';
+/**
+ * The learner's answer to one question. Only these members are accepted so a
+ * response can never smuggle other data; `choiceIds` must name the revision's
+ * choices and `parts` keys its subparts.
+ */
+export interface QuestionResponseContent {
+    text?: string;
+    numeric?: number;
+    choiceIds?: string[];
+    parts?: Record<string, {
+        text?: string;
+        numeric?: number;
+        choiceIds?: string[];
+    }>;
+}
+/** Data-only view of one append-only response row. It carries no key or rubric. */
+export interface QuestionResponseView {
+    id: string;
+    learnerId: string;
+    enrollmentId: string;
+    lessonRevisionId: string | null;
+    questionRevisionId: string;
+    worksheetVersionId: string;
+    /** Groups one attempt and its corrections. */
+    episodeId: string;
+    attemptNumber: number;
+    /** The response this row corrects, or null for a new attempt. */
+    previousResponseId: string | null;
+    completionMode: QuestionCompletionMode;
+    assistance: QuestionAssistance;
+    response: QuestionResponseContent;
+    actorUserId: string;
+    /** True when the author is not the learner (a guardian correction). */
+    byGuardian: boolean;
+    recordedAt: string;
+}
+/** Learner reads get the keyless bundle; guardians get the keyed one. */
+export interface LessonQuestionResponses {
+    worksheet: LearnerWorksheetBundle | GuardianWorksheetBundle;
+    responses: QuestionResponseView[];
+}
+export declare class QuestionResponseValidationError extends CourseAuthoringError {
+    constructor(message: string);
+}
+/** The question revision is not in the enrollment's effective lesson set. */
+export declare class QuestionResponseScopeError extends CourseAuthoringError {
+    constructor();
+}
+export declare class QuestionResponseNotFoundError extends CourseAuthoringError {
+    constructor();
+}
+//# sourceMappingURL=question-response-contracts.d.ts.map

package/dist/question-response-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-response-contracts.d.ts","sourceRoot":"","sources":["../src/question-response-contracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,KAAK,EACV,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AAEjC;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CACZ,MAAM,EACN;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAC1D,CAAC;CACH;AAED,mFAAmF;AACnF,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,cAAc,EAAE,sBAAsB,CAAC;IACvC,UAAU,EAAE,kBAAkB,CAAC;IAC/B,QAAQ,EAAE,uBAAuB,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,yEAAyE;AACzE,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,sBAAsB,GAAG,uBAAuB,CAAC;IAC5D,SAAS,EAAE,oBAAoB,EAAE,CAAC;CACnC;AAED,qBAAa,+BAAgC,SAAQ,oBAAoB;gBAC3D,OAAO,EAAE,MAAM;CAG5B;AACD,6EAA6E;AAC7E,qBAAa,0BAA2B,SAAQ,oBAAoB;;CAOnE;AACD,qBAAa,6BAA8B,SAAQ,oBAAoB;;CAItE"}