@happyvertical/smrt-education 0.57.43 → 0.57.45

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

@@ -0,0 +1,154 @@
+import { type AssetRuntimeOptions } from '@happyvertical/smrt-assets';
+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 AttachGeneratedPrintableRequest, type GeneratedPrintableResult, 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;
+    }>;
+    /**
+     * Private asset storage for `attachGeneratedPrintable`, the same shape
+     * `SubmissionService` takes. Server configuration only. Without it the call
+     * fails closed with `PrintableStorageNotConfiguredError`.
+     */
+    printableAssets?: {
+        storage: AssetRuntimeOptions['storage'];
+        storeOptions?: AssetRuntimeOptions['storeOptions'];
+    };
+}
+/**
+ * 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;
+    /** The non-transactional database: compensation must read committed state. */
+    private readonly rootDatabase;
+    private readonly printableAssets;
+    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;
+    /**
+     * Renders the released lesson's worksheet as a PDF and attaches it to the
+     * lesson as a private education-owned asset, so the durable print queue can
+     * serve it. `worksheetVersionId` must be the digest of the lesson revision's
+     * pinned questions and layout. The learner copy is built from the keyless
+     * bundle and linked as `printable`; the guardian copy carries keys and is
+     * linked as `answer-key`, which `SubmissionService.signLessonPrintable` never
+     * signs. Idempotent per (tenant, lesson, worksheet version, audience).
+     * Needs `education.course.author`, plus `read-draft` for the guardian audience.
+     * A learner of the tenant, or a delegation naming one, is refused before the
+     * host is asked.
+     */
+    attachGeneratedPrintable(request: AttachGeneratedPrintableRequest): Promise<GeneratedPrintableResult>;
+    /** Removes files planned by a rolled-back attach, unless their asset committed. */
+    private compensatePrintables;
+    private attachOnce;
+    /**
+     * 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,292 @@
+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[]);
+}
+/** Audience of a generated printable: which artefact is produced, never authority. */
+export type GeneratedPrintableAudience = 'learner' | 'guardian';
+export declare const GENERATED_PRINTABLE_AUDIENCES: readonly GeneratedPrintableAudience[];
+/** `LessonAsset` relationship per audience: the learner copy is the only signable one. */
+export type GeneratedPrintableRelationship = 'printable' | 'answer-key';
+export declare const GENERATED_PRINTABLE_RELATIONSHIPS: Readonly<Record<GeneratedPrintableAudience, GeneratedPrintableRelationship>>;
+/** Most question items one generated printable may carry. */
+export declare const MAX_PRINTABLE_ITEMS = 200;
+/** Longest single text value (prompt, choice, key, ...) rendered, in characters. */
+export declare const MAX_PRINTABLE_TEXT_LENGTH = 10000;
+/** Most characters of all rendered text in one generated printable. */
+export declare const MAX_PRINTABLE_TOTAL_TEXT = 400000;
+/** Most pages one generated printable may span. */
+export declare const MAX_PRINTABLE_PAGES = 150;
+/** Attach the rendered worksheet of a released lesson to the durable print queue. */
+export type AttachGeneratedPrintableRequest = CourseAuthoringActor & {
+    /** The materialised `lessons` row id of a released lesson. */
+    lessonId: string;
+    /** Must equal the worksheet version id of the lesson revision's questions and layout. */
+    worksheetVersionId: string;
+    audience: GeneratedPrintableAudience;
+};
+/** Closed result: never carries keys, answers or storage locators. */
+export interface GeneratedPrintableResult {
+    lessonId: string;
+    worksheetVersionId: string;
+    audience: GeneratedPrintableAudience;
+    assetId: string;
+    relationship: GeneratedPrintableRelationship;
+    /** False when an earlier call already attached this printable. */
+    created: boolean;
+}
+/** The request's worksheet version is unknown or no longer the lesson's own. */
+export declare class WorksheetVersionMismatchError extends CourseAuthoringError {
+    constructor();
+}
+/** No asset runtime/storage was configured for generated printables. */
+export declare class PrintableStorageNotConfiguredError extends CourseAuthoringError {
+    constructor();
+}
+/** The acting guardian (or delegating guardian) has no profile to own the asset. */
+export declare class PrintableOwnerError extends CourseAuthoringError {
+    constructor();
+}
+/**
+ * A rolled-back attach could not remove its fresh private PDF(s). Carries the
+ * fresh asset ids only, for operator reconciliation; the original cause is kept.
+ */
+export declare class PrintableStorageCleanupError extends CourseAuthoringError {
+    readonly assetIds: readonly string[];
+    constructor(assetIds: readonly string[], cause: unknown);
+}
+//# 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,151 @@
+import { SmrtCollection, SmrtObject, type SmrtSaveOptions } from '@happyvertical/smrt-core';
+import { type GeneratedPrintableAudience } from './question-contracts.js';
+/** 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;
+}
+/**
+ * Append-only record that a released lesson's worksheet render was attached to
+ * the print queue: one row per tenant, lesson, worksheet version and audience.
+ * The unique index is what makes concurrent first attaches converge. It holds
+ * ids only (never keys or locators); the PDF is a private education-owned asset.
+ */
+export declare class GeneratedPrintable extends SmrtObject {
+    tenantId: string;
+    lessonId: string;
+    worksheetVersionId: string;
+    /** `learner` (relationship `printable`) or `guardian` (relationship `answer-key`). */
+    audience: GeneratedPrintableAudience;
+    assetId: string;
+    /** Provenance only: checked in `save()`, not a database constraint, so the table depends on lessons and assets alone. */
+    lessonRevisionId: string;
+    generatedByUserId: string;
+    delegatingGuardianUserId: string;
+    delegationId: string;
+    recordedAt: Date;
+    constructor(options?: Record<string, unknown>);
+    delete(): Promise<void>;
+    save(options?: SmrtSaveOptions): Promise<this>;
+}
+export declare class GeneratedPrintableCollection extends SmrtCollection<GeneratedPrintable> {
+    static readonly _itemClass: typeof GeneratedPrintable;
+}
+//# 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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"}