@plasius/learning 0.2.25 → 0.4.0

package/dist/course-authoring-DImvrK5r.d.ts

@@ -0,0 +1,514 @@
+/** Version-one module categories supported by the learning catalog. */
+type ModuleCategoryV1 = "game" | "robot" | "vibe" | "web-app";
+/** Commercial states deliberately separate pilot grants from public checkout. */
+type CommercialStateV1 = "pilot-grant-only" | "fixed-price" | "retired";
+/** The four deterministic assessment dimensions and their product meanings. */
+type AssessmentDimensionV1 = "structure" | "behaviour" | "resilience" | "safety";
+type ScoreBandV1 = "keep-exploring" | "nearly-there" | "mission-complete" | "mastered";
+type CourseMaterialAudienceV1 = "learner" | "facilitator";
+type CourseMaterialKindV1 = "child-guide" | "mission-cards" | "starter-project" | "asset-pack" | "printable" | "facilitator-guide" | "answer-key" | "protected-tests" | "hardware-guide";
+type ModuleAgentRoleV1 = "assessor" | "debugger" | "fix-guide" | "concept-explainer";
+type HardwareModeV1 = "none" | "optional" | "physical-first";
+type HardwareVerificationStatusV1 = "not-applicable" | "pending-bench-test" | "verified";
+/** A material record contains metadata only; storage and signed URLs are adapter concerns. */
+interface CourseMaterialV1 {
+    id: string;
+    kind: CourseMaterialKindV1;
+    audience: CourseMaterialAudienceV1;
+    title?: string;
+}
+/** Learner and facilitator materials are deliberately separated. */
+interface CourseMaterialsManifestV1 {
+    version: string;
+    learner: CourseMaterialV1[];
+    facilitator: CourseMaterialV1[];
+}
+/** A physical item disclosed before a Guardian creates a purchase quote. */
+interface HardwareItemV1 {
+    id: string;
+    label: string;
+    quantity: number;
+    requirement: "required" | "optional";
+    exactSpecification: string;
+    adultOnly: boolean;
+    stage: "core" | "servo" | "rover" | "sensor" | "camera";
+}
+/** Immutable hardware and preparation disclosure for a module version. */
+interface HardwareRequirementManifestV1 {
+    requirementsVersion: string;
+    mode: HardwareModeV1;
+    hardwareIncluded: false;
+    simulatorAvailable: boolean;
+    verificationStatus: HardwareVerificationStatusV1;
+    publicSaleBlocked: boolean;
+    preparationMinutes: number;
+    items: HardwareItemV1[];
+    warnings: string[];
+    supportedPlatforms: string[];
+}
+/** One short, observable learning goal inside a mission. */
+interface LearningGoalV1 {
+    id: string;
+    statement: string;
+    evidence: "assessment" | "explanation" | "adult-signoff";
+}
+/** A 15–25 minute unit following learn, predict, build, assess and explain. */
+interface MissionV1 {
+    id: string;
+    title: string;
+    estimatedMinutes: number;
+    concepts: string[];
+    goals: LearningGoalV1[];
+    sideAdventure: string;
+}
+/** One objective source of points in an assessment rubric. */
+interface AssessmentCriterionV1 {
+    id: string;
+    label: string;
+    dimension: AssessmentDimensionV1;
+    points: number;
+    mandatory: boolean;
+    visibility: "visible" | "protected";
+}
+/** The immutable assessment authority for a module challenge. */
+interface AssessmentRubricV1 {
+    version: string;
+    completionScore: 80;
+    criteria: AssessmentCriterionV1[];
+}
+interface AssessmentCheckResultV1 {
+    criterionId: string;
+    passed: boolean;
+    sourceLocation?: {
+        fileId?: string;
+        blockId?: string;
+        startLine?: number;
+        endLine?: number;
+    };
+}
+interface AssessmentResultV1 {
+    score: number;
+    band: ScoreBandV1;
+    completed: boolean;
+    passedCriterionIds: string[];
+    failedCriterionIds: string[];
+    failedMandatoryCriterionIds: string[];
+}
+/** A constrained module-agent role; score and reward authority are always false. */
+interface ModuleAgentDefinitionV1 {
+    id: string;
+    role: ModuleAgentRoleV1;
+    evidenceBound: true;
+    maySuggestSingleFix: boolean;
+    mayAssignScore: false;
+    mayAwardReward: false;
+    mayPublish: false;
+    mayControlHardware: false;
+}
+/** Structured feedback that a deterministic or AI-backed adapter may return. */
+interface ModuleAgentFeedbackV1 {
+    role: ModuleAgentRoleV1;
+    assessmentScore: number;
+    passedGoalIds: string[];
+    failedGoalIds: string[];
+    explanation: string;
+    expectedBehaviour: string;
+    suggestedExperiment?: string;
+    sourceLocation?: AssessmentCheckResultV1["sourceLocation"];
+    scoreAuthority: "deterministic-assessment";
+}
+/** Ordinary Token subunits used as a pilot shadow or fixed price. */
+interface ModuleReferencePriceV1 {
+    /** Reference copy only; this is never a cash balance or redemption promise. */
+    currency: "GBP";
+    /** Canonical GBP minor units. */
+    minorUnits: string;
+    basis: "nominal-reference";
+    cashRedemptionAllowed: false;
+}
+interface ModulePricingV1 {
+    state: CommercialStateV1;
+    tokenSubunits: string;
+    referencePrice?: ModuleReferencePriceV1;
+    includesMaterials: true;
+    includesAssessmentRetries: true;
+    includesAgents: true;
+    includesHostingAllowance: boolean;
+}
+interface BadgeDefinitionV1 {
+    id: string;
+    title: string;
+    evidence: "mission-score" | "module-score" | "adult-physical-signoff";
+    tradeable: false;
+    tokenConvertible: false;
+}
+/** Immutable package export selected by the catalog without importing it. */
+declare const EXTERNAL_LEARNING_CONTENT_REFERENCE_VERSION_V1: "1";
+interface ExternalLearningContentReferenceV1 {
+    /** Exact public package name; ranges and aliases are not permitted. */
+    packageName: string;
+    /** Exact semantic version without a range operator. */
+    packageVersion: string;
+    /** Named ESM/CJS export containing the immutable content manifest. */
+    exportName: string;
+    /** Exact schema version declared by the referenced exported manifest. */
+    schemaVersion: string;
+    /** Lower-case SHA-256 of the canonical exported manifest JSON. */
+    sha256: string;
+}
+/** One immutable, independently sellable module version. */
+interface LearningModuleVersionV1 {
+    id: string;
+    slug: string;
+    version: string;
+    contentRevision: string;
+    title: string;
+    category: ModuleCategoryV1;
+    summary: string;
+    estimatedMinutes: number;
+    tools: string[];
+    concepts: string[];
+    selfContained: true;
+    prerequisiteModuleIds: string[];
+    pricing: ModulePricingV1;
+    materials: CourseMaterialsManifestV1;
+    hardware: HardwareRequirementManifestV1;
+    missions: MissionV1[];
+    assessment: AssessmentRubricV1;
+    agents: ModuleAgentDefinitionV1[];
+    badges: BadgeDefinitionV1[];
+    /** Optional separately released content implementation pinned by digest. */
+    externalContent?: ExternalLearningContentReferenceV1;
+}
+/** A versioned path is a recommendation and never a paid prerequisite chain. */
+interface LearningPathVersionV1 {
+    id: string;
+    slug: string;
+    version: string;
+    title: string;
+    description: string;
+    catalogState: "pilot" | "public" | "retired";
+    publicLaunchAtomic: true;
+    featureFlag: string;
+    modules: LearningModuleVersionV1[];
+}
+/** Entitlement records bind a subject to an immutable module version. */
+interface ModuleEntitlementV1 {
+    entitlementId: string;
+    subjectAccountId: string;
+    moduleId: string;
+    moduleVersion: string;
+    source: "pilot-grant" | "module-allowance-purchase" | "support-grant" | "admin-test-grant";
+    state: "pending" | "active" | "revoked";
+    economyTransactionId?: string;
+    grantedAt: string;
+}
+interface AttemptEvidenceV1 {
+    attemptId: string;
+    moduleId: string;
+    moduleVersion: string;
+    assessment: AssessmentResultV1;
+    sourceDigest: string;
+    recordedAt: string;
+    adultPhysicalSignoff?: {
+        signedByActorAccountId: string;
+        checklistVersion: string;
+        signedAt: string;
+    };
+}
+interface GuardianAiConsentV1 {
+    actorAccountId: string;
+    subjectAccountId: string;
+    policyVersion: string;
+    state: "granted" | "withdrawn";
+    recordedAt: string;
+}
+/** A static project snapshot is immutable and separately approved for publishing. */
+interface PublishedStaticProjectSnapshotV1 {
+    snapshotId: string;
+    subjectAccountId: string;
+    moduleId: string;
+    sourceDigest: string;
+    randomSlug: string;
+    guardianApprovalId: string;
+    state: "pending-review" | "published" | "expired" | "unpublished";
+    expiresAt: string;
+}
+/** Canonical learner journey shared by interactive and printable adapters. */
+declare const MISSION_AUTHORING_CONTRACT_VERSION_V1: "1.0.0";
+type MissionStageKindV1 = "learn" | "predict" | "build" | "run" | "assess" | "inspect" | "fix" | "explain" | "reward";
+type MissionArtifactKindV1 = "starter-code" | "starter-assets" | "sample-data" | "printable" | "facilitator-note" | "answer-key" | "protected-test";
+/** Metadata only: storage and authorized delivery remain adapter concerns. */
+interface MissionArtifactReferenceV1 {
+    id: string;
+    kind: MissionArtifactKindV1;
+    audience: CourseMaterialAudienceV1;
+    solutionBearing: boolean;
+}
+interface MissionReadinessCheckV1 {
+    id: string;
+    prompt: string;
+    scored: false;
+}
+interface MissionStageCardV1 {
+    kind: MissionStageKindV1;
+    instruction: string;
+    artifactIds: string[];
+}
+interface MissionAuthoringGoalV1 {
+    id: string;
+    statement: string;
+    visibility: "visible" | "protected";
+    criterionIds: string[];
+    completionRequired: boolean;
+    aiRequired: boolean;
+}
+type MissionInteractionModeV1 = "keyboard" | "pointer" | "drag" | "audio" | "colour" | "motion" | "text" | "shape" | "symbol" | "reduced-motion";
+interface MissionInteractionRequirementV1 {
+    id: string;
+    description: string;
+    primaryMode: MissionInteractionModeV1;
+    alternativeIds: string[];
+}
+interface MissionAccessibilityAlternativeV1 {
+    id: string;
+    modes: MissionInteractionModeV1[];
+    equivalentOutcome: true;
+    description: string;
+}
+type MissionEvidenceKindV1 = "assessment-result" | "learner-explanation" | "project-snapshot" | "adult-signoff";
+type MissionEvidenceRetentionV1 = "attempt" | "entitlement" | "adult-signoff";
+interface MissionEvidenceRequirementV1 {
+    id: string;
+    goalIds: string[];
+    kind: MissionEvidenceKindV1;
+    retention: MissionEvidenceRetentionV1;
+    containsPersonalData: false;
+}
+interface MissionSideAdventureV1 {
+    id: string;
+    prompt: string;
+    completionRequired: false;
+}
+interface MissionRewardBindingV1 {
+    id: string;
+    badgeId: string;
+    goalIds: string[];
+    deterministic: true;
+    random: false;
+    tokenConvertible: false;
+}
+interface MissionFunctionParameterV1 {
+    name: string;
+    type: string;
+    description: string;
+}
+/** Learner-safe documentation for one bounded host or simulator function. */
+interface MissionFunctionReferenceV1 {
+    id: string;
+    signature: string;
+    summary: string;
+    parameters: MissionFunctionParameterV1[];
+    effect: string;
+    example: string;
+}
+/**
+ * One learner-safe change proposal. A mission may expose a diff for a single
+ * authored artifact and always leaves the final accept/reject decision to the
+ * learner. Live AI is an optional adapter concern, never a completion input.
+ */
+interface MissionBoundedSuggestionV1 {
+    id: string;
+    source: "authored-fallback";
+    intent: string;
+    constraints: string[];
+    permittedArtifactId: string;
+    originalSnippet: string;
+    replacementSnippet: string;
+    explanationPrompt: string;
+    aiOptional: false;
+    learnerApprovalRequired: true;
+    alternatives: ["accept", "reject"];
+}
+/** The only mission projection safe to return to a learner. */
+interface LearnerMissionAuthoringV1 {
+    estimatedMinutes: number;
+    stages: MissionStageCardV1[];
+    readinessChecks: MissionReadinessCheckV1[];
+    artifacts: MissionArtifactReferenceV1[];
+    goals: MissionAuthoringGoalV1[];
+    interactions: MissionInteractionRequirementV1[];
+    accessibilityAlternatives: MissionAccessibilityAlternativeV1[];
+    evidenceRequirements: MissionEvidenceRequirementV1[];
+    sideAdventures: MissionSideAdventureV1[];
+    rewardBindings: MissionRewardBindingV1[];
+    functionReference?: MissionFunctionReferenceV1[];
+    boundedSuggestion?: MissionBoundedSuggestionV1;
+}
+/** Protected authoring data must never be projected through learner APIs. */
+interface FacilitatorMissionAuthoringV1 {
+    artifacts: MissionArtifactReferenceV1[];
+    protectedGoals: MissionAuthoringGoalV1[];
+    prompts: string[];
+}
+type MissionHardwareAcquisitionScopeV1 = "complete-path" | "incremental";
+/** Per-item verification authority for a physical mission disclosure. */
+interface MissionHardwareComponentDisclosureV1 {
+    itemId: string;
+    quantity: number;
+    acquisitionScope: MissionHardwareAcquisitionScopeV1;
+    verificationStatus: HardwareVerificationStatusV1;
+    compatibilityClaimed: boolean;
+    physicalCompletionEligible: boolean;
+}
+/** Adult and simulator boundaries that consuming workspaces must preserve. */
+interface MissionPhysicalSafeguardsV1 {
+    adultAssemblyRequired: true;
+    adultAcknowledgementRequiredForExport: true;
+    websiteMayControlHardware: false;
+    simulatorCompletionAvailable: true;
+    simulatedBadgeId: string;
+    physicalBadgeId: string;
+    physicalBadgeRequiresAdultSignoff: true;
+    adultAssemblySteps: string[];
+    powerRequirements: string[];
+    cableRequirements: string[];
+    softwarePrerequisites: string[];
+    warnings: string[];
+    unrelatedHardwareNotRequired: string[];
+}
+/**
+ * Additive mission-level projection of one immutable catalog hardware manifest.
+ * It distinguishes the complete reusable path kit from this module's additions.
+ */
+interface MissionHardwareDisclosureV1 {
+    requirementsVersion: string;
+    hardwareIncluded: false;
+    completePathItemIds: string[];
+    incrementalItemIds: string[];
+    components: MissionHardwareComponentDisclosureV1[];
+    safeguards: MissionPhysicalSafeguardsV1;
+}
+/** Additive authoring detail keyed to one immutable catalog mission. */
+interface MissionAuthoringBundleV1 {
+    version: string;
+    moduleId: string;
+    moduleVersion: string;
+    missionId: string;
+    learner: LearnerMissionAuthoringV1;
+    facilitator: FacilitatorMissionAuthoringV1;
+    hardware?: MissionHardwareDisclosureV1;
+}
+interface MissionAuthoringValidationIssueV1 {
+    code: "bundle-version-mismatch" | "module-reference-mismatch" | "mission-reference-mismatch" | "invalid-duration" | "missing-stage" | "duplicate-stage" | "stage-order" | "missing-readiness-check" | "scored-readiness-check" | "missing-starter-artifact" | "learner-artifact-leak" | "facilitator-artifact-leak" | "unknown-artifact" | "duplicate-id" | "missing-visible-goal" | "missing-protected-goal" | "invalid-goal-projection" | "duplicate-goal-id" | "unknown-criterion" | "criterion-visibility-mismatch" | "rubric-total" | "rubric-dimension-total" | "duplicate-criterion-id" | "missing-mandatory-safety" | "missing-safety-evidence" | "ai-dependent-completion" | "inaccessible-interaction" | "unknown-accessibility-alternative" | "non-equivalent-accessibility-alternative" | "missing-evidence" | "unknown-evidence-goal" | "personal-data-evidence" | "missing-side-adventure" | "mandatory-side-adventure" | "invalid-reward" | "hardware-module-mismatch" | "hardware-requirements-version-mismatch" | "hardware-item-mismatch" | "hardware-verification-claim" | "unsafe-physical-export" | "invalid-hardware-reward" | "invalid-function-reference" | "invalid-bounded-suggestion";
+    message: string;
+    path: string;
+}
+interface LearningValidationIssueV1 {
+    code: "duplicate-module-id" | "duplicate-module-slug" | "module-not-self-contained" | "paid-prerequisite" | "missing-materials" | "facilitator-material-leak" | "learner-material-leak" | "invalid-token-subunits" | "invalid-reference-price" | "rubric-total" | "rubric-dimension-total" | "duplicate-criterion-id" | "missing-mandatory-safety" | "missing-hardware-items" | "invalid-agent-authority" | "missing-missions" | "invalid-external-content-reference";
+    message: string;
+    moduleId?: string;
+    path: string;
+}
+
+/** Stable activity order for complete courses; legacy authoring remains immutable. */
+declare const LEARNING_COURSE_STAGE_ORDER: readonly ["learn", "predict", "build", "run", "assess", "inspect", "fix", "explain", "reward"];
+declare const LEARNING_COURSE_LIMITS: Readonly<{
+    missions: 6;
+    stagesPerMission: 9;
+    projectFiles: 8;
+    sourceCharactersPerFile: 64000;
+    sourceCharactersPerProject: 96000;
+}>;
+type LearningProjectLanguageV1 = "javascript" | "python" | "cpp" | "html" | "css" | "blocks" | "json";
+interface LearningProjectFileV1 {
+    path: string;
+    source: string;
+}
+interface LearningProjectV1 {
+    files: LearningProjectFileV1[];
+}
+interface LearningCourseStageV1 {
+    id: string;
+    kind: MissionStageKindV1;
+    title: string;
+    instruction: string;
+    help: string;
+}
+interface LearningCourseMissionV1 {
+    id: string;
+    title: string;
+    concepts: string[];
+    estimatedMinutes: number;
+    goals: string[];
+    assessmentId: string;
+    stages: LearningCourseStageV1[];
+    extension: string;
+}
+/** Learner-safe content only. Protected scenarios and solutions are host-owned. */
+interface LearningCourseV1 {
+    schemaVersion: "1";
+    moduleId: string;
+    moduleVersion: string;
+    slug: string;
+    title: string;
+    summary: string;
+    runtimeId: string;
+    category: ModuleCategoryV1;
+    estimatedMinutes: number;
+    completionAssessmentId: string;
+    projectFiles: {
+        path: string;
+        language: LearningProjectLanguageV1;
+        maximumCharacters: number;
+    }[];
+    starterProject: LearningProjectV1;
+    reference: {
+        name: string;
+        signature: string;
+        description: string;
+        example: string;
+    }[];
+    missions: LearningCourseMissionV1[];
+    completionBadge: {
+        id: string;
+        title: string;
+    };
+}
+/** The only learner-owned save inputs. Progress/evidence are never draft authority. */
+interface LearningCourseDraftV1 {
+    schemaVersion: "1";
+    moduleVersion: string;
+    activeStageId: string;
+    project: LearningProjectV1;
+}
+type LearningSaveSlotIdV1 = "auto" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+interface LearningCourseValidationIssueV1 {
+    code: "invalid-manifest" | "mission-count" | "stage-order" | "duplicate-id" | "incomplete-content" | "invalid-project";
+    path: string;
+}
+/** Errors contain no source, learner text or caller-supplied identifiers. */
+declare class LearningCourseInputError extends Error {
+    constructor();
+}
+/** Validate every file against the declared editable set; never preserve extra fields. */
+declare function parseLearningProject(course: Pick<LearningCourseV1, "projectFiles">, value: unknown): LearningProjectV1;
+/** Parse untrusted saves without accepting identity, scores, completion or evidence. */
+declare function parseLearningCourseDraft(course: LearningCourseV1, value: unknown): LearningCourseDraftV1;
+/** An account owns one autosave and nine explicitly managed slots per course version. */
+declare function parseLearningSaveSlotId(value: unknown): LearningSaveSlotIdV1;
+/** Structural publication gate. Working runtime/curriculum acceptance is additional. */
+declare function validateLearningCourse(value: unknown): LearningCourseValidationIssueV1[];
+/** Validate an external learner manifest and detach it from the supplied object. */
+declare function parseLearningCourse(value: unknown): LearningCourseV1;
+
+/** Formative checks are learner-visible teaching material, not protected assessments. */
+interface CoursePracticeQuestion {
+    stageId: string;
+    question: string;
+    choices: [string, string, string];
+    correctChoice: 0 | 1 | 2;
+    feedback: string;
+}
+
+export { type MissionHardwareDisclosureV1 as $, type AssessmentRubricV1 as A, type BadgeDefinitionV1 as B, type CoursePracticeQuestion as C, type LearningGoalV1 as D, type ExternalLearningContentReferenceV1 as E, type FacilitatorMissionAuthoringV1 as F, type GuardianAiConsentV1 as G, type HardwareItemV1 as H, type LearningProjectFileV1 as I, type LearningProjectLanguageV1 as J, type LearningProjectV1 as K, type LearningCourseV1 as L, type MissionAuthoringBundleV1 as M, type LearningSaveSlotIdV1 as N, MISSION_AUTHORING_CONTRACT_VERSION_V1 as O, type MissionAccessibilityAlternativeV1 as P, type MissionArtifactKindV1 as Q, type MissionArtifactReferenceV1 as R, type MissionAuthoringGoalV1 as S, type MissionBoundedSuggestionV1 as T, type MissionEvidenceKindV1 as U, type MissionEvidenceRequirementV1 as V, type MissionEvidenceRetentionV1 as W, type MissionFunctionParameterV1 as X, type MissionFunctionReferenceV1 as Y, type MissionHardwareAcquisitionScopeV1 as Z, type MissionHardwareComponentDisclosureV1 as _, type AssessmentCheckResultV1 as a, type MissionInteractionModeV1 as a0, type MissionInteractionRequirementV1 as a1, type MissionPhysicalSafeguardsV1 as a2, type MissionReadinessCheckV1 as a3, type MissionRewardBindingV1 as a4, type MissionSideAdventureV1 as a5, type MissionStageCardV1 as a6, type MissionStageKindV1 as a7, type MissionV1 as a8, type ModuleAgentDefinitionV1 as a9, type ModuleAgentFeedbackV1 as aa, type ModuleAgentRoleV1 as ab, type ModuleCategoryV1 as ac, type ModuleEntitlementV1 as ad, type ModulePricingV1 as ae, type ModuleReferencePriceV1 as af, type PublishedStaticProjectSnapshotV1 as ag, type ScoreBandV1 as ah, parseLearningCourse as ai, parseLearningCourseDraft as aj, parseLearningProject as ak, parseLearningSaveSlotId as al, validateLearningCourse as am, type AssessmentResultV1 as b, type LearningModuleVersionV1 as c, type LearningPathVersionV1 as d, type LearningValidationIssueV1 as e, type MissionAuthoringValidationIssueV1 as f, type AssessmentCriterionV1 as g, type AssessmentDimensionV1 as h, type AttemptEvidenceV1 as i, type CommercialStateV1 as j, type CourseMaterialAudienceV1 as k, type CourseMaterialKindV1 as l, type CourseMaterialV1 as m, type CourseMaterialsManifestV1 as n, EXTERNAL_LEARNING_CONTENT_REFERENCE_VERSION_V1 as o, type HardwareModeV1 as p, type HardwareRequirementManifestV1 as q, type HardwareVerificationStatusV1 as r, LEARNING_COURSE_LIMITS as s, LEARNING_COURSE_STAGE_ORDER as t, type LearnerMissionAuthoringV1 as u, type LearningCourseDraftV1 as v, LearningCourseInputError as w, type LearningCourseMissionV1 as x, type LearningCourseStageV1 as y, type LearningCourseValidationIssueV1 as z };