@happyvertical/smrt-education 0.57.46 → 0.57.48

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

@@ -0,0 +1,231 @@
+/**
+ * Closed contracts for extracting structured questions from scanned worksheets
+ * and imported course files (SMRT #4517). Pure types, limits and typed errors;
+ * no I/O. See `agents/question-extraction.md`.
+ */
+import { CourseAuthoringError } from './course-authoring-contracts.js';
+import type { QuestionChoice, QuestionResponseType, QuestionRubric } from './question-contracts.js';
+export declare const QUESTION_EXTRACTION_VERSION: 1;
+export type QuestionExtractionSourceKind = 'worksheet_scan' | 'course_import';
+export declare const QUESTION_EXTRACTION_SOURCE_KINDS: readonly QuestionExtractionSourceKind[];
+/** What a source page is. Only `exercise`/`mixed` pages yield question records. */
+export type ExtractedPageRole = 'exercise' | 'example' | 'instructions' | 'cover' | 'answer_key' | 'mixed' | 'unknown';
+export declare const EXTRACTED_PAGE_ROLES: readonly ExtractedPageRole[];
+export type ExtractedReadability = 'readable' | 'partial' | 'unreadable' | 'unsupported';
+export declare const EXTRACTED_READABILITY: readonly ExtractedReadability[];
+/** `complete` and `partial` items carry a printed prompt; the others do not. */
+export type ExtractedQuestionStatus = 'complete' | 'partial' | 'unreadable' | 'unsupported';
+export declare const EXTRACTED_QUESTION_STATUSES: readonly ExtractedQuestionStatus[];
+/** Printed in the source, or inferred by the extractor. Never mixed up. */
+export type ExtractedOrigin = 'source' | 'inferred';
+export declare const EXTRACTED_ORIGINS: readonly ExtractedOrigin[];
+export type ExtractedMediaKind = 'diagram' | 'image' | 'table' | 'graph' | 'other';
+export declare const EXTRACTED_MEDIA_KINDS: readonly ExtractedMediaKind[];
+export type ExtractedLegibility = 'legible' | 'partial' | 'illegible';
+export declare const EXTRACTED_LEGIBILITY: readonly ExtractedLegibility[];
+export type ExtractedOmissionReason = 'unreadable' | 'unsupported' | 'out_of_scope'
+/** Ingestion did not extract it (truncated output or a failed page). */
+ | 'not_extracted';
+export declare const EXTRACTED_OMISSION_REASONS: readonly ExtractedOmissionReason[];
+/** Source anchor as cited by the extractor: evidence, physical page, region id. */
+export interface ExtractedAnchorInput {
+    evidenceId: string;
+    /** Physical 1-based source page; null when unknown. Printed page numbers are not pages. */
+    page: number | null;
+    /** Id from the evidence's observedRegions catalog; never a coordinate. */
+    regionId: string | null;
+}
+/** A cited anchor resolved against retained evidence. `rect` only comes from the catalog. */
+export interface ExtractedAnchor extends ExtractedAnchorInput {
+    sha256: string;
+    /** Normalized x, y, width, height from the provider's region catalog, else null. */
+    rect: [number, number, number, number] | null;
+}
+export interface ExtractedPage {
+    evidenceId: string;
+    page: number | null;
+    role: ExtractedPageRole;
+    readability: ExtractedReadability;
+}
+export interface ExtractedSection {
+    id: string;
+    label: string | null;
+    evidenceId: string;
+    page: number | null;
+}
+export interface ExtractedMediaRef<A = ExtractedAnchor> {
+    kind: ExtractedMediaKind;
+    description: string;
+    anchor: A | null;
+}
+export interface ExtractedAnswerKey {
+    acceptedAnswers?: string[];
+    correctChoiceIds?: string[];
+    numeric?: number;
+    origin: ExtractedOrigin;
+}
+export interface ExtractedQuestion<A = ExtractedAnchor> {
+    /** Stable per-source key: printed numbering path, or `u:<slug>:<occurrence>`. */
+    key: string;
+    /** Numbering exactly as printed (`3`, `3b`, `Q4`); null when unnumbered. */
+    numbering: string | null;
+    /** Worked examples are kept as extracted items but never become question records. */
+    role: 'exercise' | 'example';
+    sectionId: string | null;
+    status: ExtractedQuestionStatus;
+    /** Printed task text only; never learner handwriting. Null when unreadable. */
+    prompt: string | null;
+    responseType: QuestionResponseType | null;
+    responseTypeOrigin: ExtractedOrigin;
+    choices: QuestionChoice[];
+    subparts: Array<{
+        partKey: string;
+        prompt: string;
+    }>;
+    media: ExtractedMediaRef<A>[];
+    answerKey: ExtractedAnswerKey | null;
+    rubric: (QuestionRubric & {
+        origin: ExtractedOrigin;
+    }) | null;
+    pointsPossible: number | null;
+    pointsOrigin: ExtractedOrigin | null;
+    anchors: A[];
+}
+/** Observed learner work, kept apart from printed questions. */
+export interface ExtractedStudentWork<A = ExtractedAnchor> {
+    /** The printed question this work answers, when visibly associated. */
+    questionKey: string | null;
+    /** Transcribed response; null when illegible. Never a solved or expected answer. */
+    observed: string | null;
+    legibility: ExtractedLegibility;
+    anchors: A[];
+}
+export interface ExtractedOmission {
+    evidenceId: string;
+    page: number | null;
+    reason: ExtractedOmissionReason;
+    description: string;
+}
+/** The handler arguments a proposal generator fills (closed; see the schema). */
+export interface QuestionExtractionInput {
+    version: 1;
+    sourceKind: QuestionExtractionSourceKind;
+    /** Worksheet version id printed on the page (generated printables print it); else null. */
+    worksheetVersionId: string | null;
+    pages: ExtractedPage[];
+    sections: ExtractedSection[];
+    questions: ExtractedQuestion<ExtractedAnchorInput>[];
+    studentWork: ExtractedStudentWork<ExtractedAnchorInput>[];
+    omissions: ExtractedOmission[];
+}
+/** Validated extraction with anchors resolved against retained evidence. */
+export interface QuestionExtraction extends Omit<QuestionExtractionInput, 'questions' | 'studentWork'> {
+    questions: ExtractedQuestion[];
+    studentWork: ExtractedStudentWork[];
+    /**
+     * Source completeness codes from ingestion (for example `source_incomplete`).
+     * Non-empty means the extraction was made from partial input: review it as such.
+     */
+    sourceWarnings: string[];
+}
+/** Retained evidence an extraction may cite, from one completed ingestion analysis. */
+export interface QuestionExtractionGrounding {
+    version: 1;
+    extractionAttemptId: string;
+    /** Bounded ingestion warning codes (`^[a-z][a-z0-9_.-]{0,47}$`), carried to the review. */
+    warnings?: string[];
+    sources: Array<{
+        evidenceId: string;
+        sha256: string;
+        mediaType: string;
+        /** Known physical pages (extracted and omitted); empty for single images and page-less sources. */
+        pages: number[];
+        /** Pages ingestion reported but did not extract (truncated or failed). */
+        omittedPages?: number[];
+        /** False when ingestion produced no result for this original at all. */
+        extracted?: boolean;
+        /** True when ingestion reported truncation or errors for this original. */
+        incomplete?: boolean;
+        observedRegions?: {
+            version: 1;
+            coordinateSpace: 'display-oriented';
+            regions: Array<{
+                id: string;
+                text: string;
+                rect: [number, number, number, number];
+            }>;
+        };
+    }>;
+}
+/** Extractor identity recorded with the preserved extraction. */
+export interface QuestionExtractorIdentity {
+    provider: string;
+    model: string;
+    version: string;
+    /** Ingestion configuration/prompt versions that produced the proposal, when known. */
+    configurationVersion?: string;
+    promptVersion?: string;
+}
+export type QuestionMatchOutcome = 'matched' | 'ambiguous' | 'unmatched';
+export type QuestionMatchReason = 'worksheet_position' | 'no_worksheet_identifier' | 'unknown_worksheet' | 'worksheet_conflict' | 'no_layout_position' | 'position_not_on_worksheet' | 'layout_conflict' | 'duplicate_position' | 'not_an_exercise';
+export interface QuestionMatch {
+    key: string;
+    outcome: QuestionMatchOutcome;
+    reason: QuestionMatchReason;
+    /** Set only for `matched`; ambiguous matches are never attached. */
+    questionId: string | null;
+    questionRevisionId: string | null;
+    ordinal: number | null;
+}
+export interface QuestionExtractionMatch {
+    worksheetVersionId: string | null;
+    /** Where the worksheet identity came from; observed on the page or supplied by the host. */
+    worksheetSource: 'observed' | 'expected' | null;
+    worksheetKnown: boolean;
+    questions: QuestionMatch[];
+}
+export type ExtractedQuestionOutcome = 'created' | 'replayed' | 'matched' | 'needs_review' | 'source_changed' | 'invalid_content' | 'unreadable' | 'unsupported' | 'not_an_exercise';
+export interface ExtractedQuestionResult {
+    key: string;
+    outcome: ExtractedQuestionOutcome;
+    questionId: string | null;
+    questionRevisionId: string | null;
+}
+export interface StudentWorkView extends ExtractedStudentWork {
+    /** The matched question revision this work belongs to; null unless matched. */
+    questionRevisionId: string | null;
+}
+export interface QuestionExtractionView {
+    extractionId: string;
+    intakeItemId: string;
+    analysisAttemptId: string;
+    /** Digest of source kind and retained evidence hashes: the idempotency identity. */
+    sourceIdentity: string;
+    extractor: QuestionExtractorIdentity;
+    extraction: QuestionExtraction;
+    match: QuestionExtractionMatch;
+    studentWork: StudentWorkView[];
+    /** Set once applied: the per-question outcome. Null while pending review. */
+    applied: ExtractedQuestionResult[] | null;
+}
+export declare const MAX_EXTRACTED_QUESTIONS = 200;
+export declare const MAX_EXTRACTED_SECTIONS = 64;
+export declare const MAX_EXTRACTED_PAGES = 1000;
+export declare const MAX_EXTRACTED_STUDENT_WORK = 400;
+export declare const MAX_EXTRACTED_OMISSIONS = 200;
+export declare const MAX_EXTRACTED_ANCHORS = 8;
+export declare const MAX_EXTRACTED_TEXT = 20000;
+/** The extraction does not fit the closed contract or its retained evidence. */
+export declare class QuestionExtractionValidationError extends CourseAuthoringError {
+    constructor(message: string);
+}
+/** No preserved extraction with this id in the tenant (foreign is alike). */
+export declare class QuestionExtractionNotFoundError extends CourseAuthoringError {
+    constructor();
+}
+/** The ingestion analysis is not a completed question-extraction proposal yet. */
+export declare class QuestionExtractionPendingError extends CourseAuthoringError {
+    readonly reason: 'pending' | 'no_proposal' | 'ambiguous';
+    constructor(reason: 'pending' | 'no_proposal' | 'ambiguous');
+}
+//# sourceMappingURL=question-extraction-contracts.d.ts.map

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

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

package/dist/question-extraction-ingestion.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Server-only ingestion bridge for question extraction (SMRT #4517): the
+ * `extract-questions` catalog handler and the preserve step that validates a
+ * completed proposal against retained evidence. Never import from browser code.
+ */
+import type { OperationHandler } from '@happyvertical/smrt-ingestion/execution';
+import { type IngestionService } from '@happyvertical/smrt-ingestion/server';
+import type { CourseAuthoringActor } from './course-authoring-contracts.js';
+import type { WorksheetBundle } from './question-contracts.js';
+import { type QuestionExtractionGrounding, type QuestionExtractionView } from './question-extraction-contracts.js';
+import { type QuestionExtractionService } from './question-extraction-service.js';
+export declare const QUESTION_EXTRACTION_HANDLER_ID = "@happyvertical/smrt-education:extract-questions";
+/**
+ * The `extract-questions` handler for ONE authenticated actor (guardian or a
+ * delegated agent). The application resolves `request` from its session. Keep
+ * every ingestion policy layer `requireReview: true`; there is no automation.
+ * Apply requires `preserveQuestionExtractionAnalysis` to have kept the exact
+ * proposal first.
+ */
+export declare function educationQuestionExtractionHandler(input: {
+    extractions: QuestionExtractionService;
+    request: CourseAuthoringActor;
+}): OperationHandler;
+type Snapshot = Awaited<ReturnType<IngestionService['getCompletedAnalysis']>>;
+/** Retained original evidence of one completed analysis, as extraction grounding. */
+export declare function questionExtractionGrounding(snapshot: Snapshot, warnings?: readonly string[]): QuestionExtractionGrounding;
+/**
+ * Preserve the current completed `extract-questions` proposal of one intake
+ * item for extraction review: validates it against retained evidence, matches
+ * it to known worksheets and records it (idempotent per analysis attempt).
+ * Not ready, no proposal or competing proposals throw
+ * `QuestionExtractionPendingError`; invalid output throws
+ * `QuestionExtractionValidationError`. Writes no question records.
+ */
+export declare function preserveQuestionExtractionAnalysis(input: {
+    ingestion: IngestionService;
+    extractions: QuestionExtractionService;
+    request: CourseAuthoringActor;
+    itemId: string;
+    expectedWorksheetVersionId?: string;
+    worksheets?: readonly WorksheetBundle[];
+}): Promise<QuestionExtractionView>;
+export {};
+//# sourceMappingURL=question-extraction-ingestion.d.ts.map

package/dist/question-extraction-ingestion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"question-extraction-ingestion.d.ts","sourceRoot":"","sources":["../src/question-extraction-ingestion.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAEV,gBAAgB,EACjB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,sCAAsC,CAAC;AAG9C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAE5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,EAEL,KAAK,2BAA2B,EAGhC,KAAK,sBAAsB,EAC5B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,KAAK,yBAAyB,EAE/B,MAAM,kCAAkC,CAAC;AAE1C,eAAO,MAAM,8BAA8B,oDACQ,CAAC;AAuFpD;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAAC,KAAK,EAAE;IACxD,WAAW,EAAE,yBAAyB,CAAC;IACvC,OAAO,EAAE,oBAAoB,CAAC;CAC/B,GAAG,gBAAgB,CA4DnB;AAED,KAAK,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;AAE9E,qFAAqF;AACrF,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,QAAQ,EAClB,QAAQ,GAAE,SAAS,MAAM,EAAO,GAC/B,2BAA2B,CAyG7B;AAED;;;;;;;GAOG;AACH,wBAAsB,kCAAkC,CAAC,KAAK,EAAE;IAC9D,SAAS,EAAE,gBAAgB,CAAC;IAC5B,WAAW,EAAE,yBAAyB,CAAC;IACvC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;CACzC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAwDlC"}

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

@@ -0,0 +1,56 @@
+import { SmrtCollection, SmrtObject, type SmrtSaveOptions } from '@happyvertical/smrt-core';
+import { type ExtractedQuestionOutcome, type QuestionExtractionSourceKind } from './question-extraction-contracts.js';
+/**
+ * Append-only preserved question extraction: one row per tenant, intake item
+ * and ingestion analysis attempt. Holds the validated extraction (anchors
+ * resolved against retained evidence), the evidence-only match and the
+ * extractor identity. The originals stay in ingestion; this never copies bytes.
+ */
+export declare class QuestionExtractionRecord extends SmrtObject {
+    tenantId: string;
+    /** Ingestion intake item id (an ingestion-owned identity, not a local FK). */
+    intakeItemId: string;
+    analysisAttemptId: string;
+    sourceIdentity: string;
+    sourceKind: QuestionExtractionSourceKind;
+    /** Digest of the reviewed proposal arguments; binds the later human decision. */
+    proposalDigest: string;
+    /** Digest of every preserve input (grounding, extractor, worksheets): same-key replays must match. */
+    inputDigest: string;
+    extractorJson: string;
+    extractionJson: string;
+    matchJson: string;
+    recordedByUserId: string;
+    recordedAt: Date;
+    constructor(options?: Record<string, unknown>);
+    delete(): Promise<void>;
+    save(options?: SmrtSaveOptions): Promise<this>;
+}
+export declare class QuestionExtractionRecordCollection extends SmrtCollection<QuestionExtractionRecord> {
+    static readonly _itemClass: typeof QuestionExtractionRecord;
+}
+/**
+ * Append-only applied outcome of one extracted question: which question record
+ * it created or matched (or why none), with its source anchors and media refs.
+ * This is the provenance link from a question record back to page and region.
+ */
+export declare class ExtractedQuestionLink extends SmrtObject {
+    tenantId: string;
+    extractionId: string;
+    questionKey: string;
+    sourceIdentity: string;
+    outcome: ExtractedQuestionOutcome;
+    questionId: string | null;
+    questionRevisionId: string | null;
+    anchorsJson: string;
+    mediaJson: string;
+    appliedByUserId: string;
+    recordedAt: Date;
+    constructor(options?: Record<string, unknown>);
+    delete(): Promise<void>;
+    save(options?: SmrtSaveOptions): Promise<this>;
+}
+export declare class ExtractedQuestionLinkCollection extends SmrtCollection<ExtractedQuestionLink> {
+    static readonly _itemClass: typeof ExtractedQuestionLink;
+}
+//# sourceMappingURL=question-extraction-models.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"question-extraction-models.d.ts","sourceRoot":"","sources":["../src/question-extraction-models.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,cAAc,EACd,UAAU,EACV,KAAK,eAAe,EAErB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,KAAK,wBAAwB,EAE7B,KAAK,4BAA4B,EAClC,MAAM,oCAAoC,CAAC;AAuD5C;;;;;GAKG;AACH,qBAiBa,wBAAyB,SAAQ,UAAU;IAC1C,QAAQ,SAAM;IAC1B,8EAA8E;IAC9E,YAAY,SAAM;IAClB,iBAAiB,SAAM;IACvB,cAAc,SAAM;IACpB,UAAU,EAAE,4BAA4B,CAAoB;IAC5D,iFAAiF;IACjF,cAAc,SAAM;IACpB,sGAAsG;IACtG,WAAW,SAAM;IACQ,aAAa,SAAQ;IACrB,cAAc,SAAQ;IACtB,SAAS,SAAQ;IAC1C,gBAAgB,SAAM;IACtB,UAAU,OAAc;gBACZ,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAIlC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAGvB,IAAI,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAiB9D;AACD,qBAAa,kCAAmC,SAAQ,cAAc,CAAC,wBAAwB,CAAC;IAC9F,MAAM,CAAC,QAAQ,CAAC,UAAU,kCAA4B;CACvD;AAED;;;;GAIG;AACH,qBAqBa,qBAAsB,SAAQ,UAAU;IACvC,QAAQ,SAAM;IACkC,YAAY,SAAM;IAC9E,WAAW,SAAM;IACjB,cAAc,SAAM;IACpB,OAAO,EAAE,wBAAwB,CAAkB;IACP,UAAU,EAAE,MAAM,GAAG,IAAI,CAAQ;IACzB,kBAAkB,EAClE,MAAM,GACN,IAAI,CAAQ;IACS,WAAW,SAAQ;IACnB,SAAS,SAAQ;IAC1C,eAAe,SAAM;IACrB,UAAU,OAAc;gBACZ,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAIlC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAGvB,IAAI,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAsB9D;AACD,qBAAa,+BAAgC,SAAQ,cAAc,CAAC,qBAAqB,CAAC;IACxF,MAAM,CAAC,QAAQ,CAAC,UAAU,+BAAyB;CACpD"}

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

@@ -0,0 +1,71 @@
+import type { DatabaseInterface } from '@happyvertical/sql';
+import { type CourseAuthoringActor, type CourseAuthoringAuthorizer } from './course-authoring-contracts.js';
+import { QuestionAuthoringService, type QuestionAuthoringServiceOptions } from './question-authoring-service.js';
+import type { GuardianWorksheetBundle, WorksheetBundle } from './question-contracts.js';
+import { type ExtractedQuestionResult, type QuestionExtractionGrounding, type QuestionExtractionView, type QuestionExtractorIdentity } from './question-extraction-contracts.js';
+/** Digest of reviewed proposal arguments; binds a preserved extraction to its decision. */
+export declare function questionExtractionProposalDigest(args: unknown): string;
+export interface PreserveQuestionExtractionRequest extends CourseAuthoringActor {
+    intakeItemId: string;
+    /** The ingestion analysis attempt that produced the proposal (one record per attempt). */
+    analysisAttemptId: string;
+    grounding: QuestionExtractionGrounding;
+    extractor: QuestionExtractorIdentity;
+    /** The proposal arguments (closed `QUESTION_EXTRACTION_ARGS_SCHEMA`). */
+    extraction: unknown;
+    /** Host-known worksheet (for example from the assignment); never overrides a printed id. */
+    expectedWorksheetVersionId?: string;
+    /** Extra candidate worksheets the host already holds; generated printables are found automatically. */
+    worksheets?: readonly WorksheetBundle[];
+}
+/**
+ * Preserve, match, review and apply structured questions extracted from scans
+ * and imported course files (SMRT #4517). Reuses the course authorizer:
+ * preserve/apply need `education.course.author`; reads need `read-draft`.
+ * Question records are written only through `createQuestion`, keyed by source
+ * identity, so retries and re-ingestion of the same bytes never multiply them.
+ */
+export declare class QuestionExtractionService extends QuestionAuthoringService {
+    private readonly courseAuthorizer;
+    private readonly serviceOptions;
+    constructor(db: DatabaseInterface, authorizer: CourseAuthoringAuthorizer, options?: QuestionAuthoringServiceOptions);
+    /** The same service bound to a host-owned transaction executor (ingestion apply). */
+    withExecutor(executor: DatabaseInterface): QuestionExtractionService;
+    /**
+     * Known worksheets carrying this version id: released lessons whose generated
+     * printable was attached with it. Keyed bundles; needs `read-draft`.
+     */
+    resolveWorksheet(request: CourseAuthoringActor & {
+        worksheetVersionId: string;
+    }): Promise<GuardianWorksheetBundle | null>;
+    /**
+     * Validate extractor output against retained evidence, match it to known
+     * worksheet revisions and keep it for extraction review. Idempotent per
+     * (tenant, intake item, analysis attempt); a different payload for the same
+     * attempt is `CourseRequestKeyConflictError`. Writes no question records.
+     */
+    preserveExtraction(request: PreserveQuestionExtractionRequest): Promise<QuestionExtractionView>;
+    /** The preserved extraction with its match and, once applied, its outcomes. */
+    readExtraction(request: CourseAuthoringActor & {
+        extractionId: string;
+    }): Promise<QuestionExtractionView>;
+    /** The preserved extraction for one intake item and reviewed proposal, if any. */
+    findExtraction(request: CourseAuthoringActor & {
+        intakeItemId: string;
+        proposalDigest: string;
+    }): Promise<QuestionExtractionView | null>;
+    /**
+     * Apply a reviewed extraction in one transaction. Matched questions link to
+     * their existing revision; readable unmatched exercises become question
+     * records (`extracted`/`inferred` provenance) keyed by source identity and
+     * question key; ambiguous, unreadable, unsupported and example items are
+     * recorded without a question. A repeated apply replays the stored outcomes.
+     */
+    applyExtraction(request: CourseAuthoringActor & {
+        extractionId: string;
+    }): Promise<ExtractedQuestionResult[]>;
+    private record;
+    private links;
+    private view;
+}
+//# sourceMappingURL=question-extraction-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"question-extraction-service.d.ts","sourceRoot":"","sources":["../src/question-extraction-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAE/B,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,wBAAwB,EACxB,KAAK,+BAA+B,EACrC,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,uBAAuB,EACvB,eAAe,EAChB,MAAM,yBAAyB,CAAC;AAOjC,OAAO,EAEL,KAAK,uBAAuB,EAE5B,KAAK,2BAA2B,EAIhC,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC/B,MAAM,oCAAoC,CAAC;AAW5C,2FAA2F;AAC3F,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAEtE;AAqCD,MAAM,WAAW,iCACf,SAAQ,oBAAoB;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,0FAA0F;IAC1F,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,2BAA2B,CAAC;IACvC,SAAS,EAAE,yBAAyB,CAAC;IACrC,yEAAyE;IACzE,UAAU,EAAE,OAAO,CAAC;IACpB,4FAA4F;IAC5F,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,uGAAuG;IACvG,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;CACzC;AAED;;;;;;GAMG;AACH,qBAAa,yBAA0B,SAAQ,wBAAwB;IACrE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA4B;IAC7D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAkC;gBAG/D,EAAE,EAAE,iBAAiB,EACrB,UAAU,EAAE,yBAAyB,EACrC,OAAO,GAAE,+BAAoC;IAO/C,qFAAqF;IACrF,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG,yBAAyB;IAQpE;;;OAGG;IACG,gBAAgB,CACpB,OAAO,EAAE,oBAAoB,GAAG;QAAE,kBAAkB,EAAE,MAAM,CAAA;KAAE,GAC7D,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC;IAuC1C;;;;;OAKG;IACG,kBAAkB,CACtB,OAAO,EAAE,iCAAiC,GACzC,OAAO,CAAC,sBAAsB,CAAC;IA6GlC,+EAA+E;IACzE,cAAc,CAClB,OAAO,EAAE,oBAAoB,GAAG;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,GACvD,OAAO,CAAC,sBAAsB,CAAC;IAYlC,kFAAkF;IAC5E,cAAc,CAClB,OAAO,EAAE,oBAAoB,GAAG;QAC9B,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,MAAM,CAAC;KACxB,GACA,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAoBzC;;;;;;OAMG;IACG,eAAe,CACnB,OAAO,EAAE,oBAAoB,GAAG;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,GACvD,OAAO,CAAC,uBAAuB,EAAE,CAAC;YA8GvB,MAAM;YAeN,KAAK;YAmCL,IAAI;CA2BnB"}