@plasius/learning 0.2.20 → 0.2.21

package/dist/index.d.cts

@@ -429,6 +429,109 @@ declare const JUNIOR_CODER_ROBOT_RESCUE_PATH_V1_1: LearningPathVersionV1;
 /** Current pilot catalog for server adapters that intentionally follow releases. */
 declare const JUNIOR_CODER_ROBOT_RESCUE_PATH_CURRENT: LearningPathVersionV1;
 
+/** Additive contract version for touch-first and spoken contextual help. */
+declare const CONTEXTUAL_HELP_CONTRACT_VERSION_V1: "1.0.0";
+declare const CONTEXTUAL_HELP_KINDS_V1: readonly ["command", "visual-block", "generated-code", "assessment-diagnostic"];
+type ContextualHelpKindV1 = (typeof CONTEXTUAL_HELP_KINDS_V1)[number];
+/**
+ * Opaque, manifest-bound identifier. It contains no source, transcript,
+ * learner identity or arbitrary synthesis text.
+ */
+interface ContextualHelpIdentifierV1 {
+    readonly schemaVersion: "1";
+    readonly contractVersion: typeof CONTEXTUAL_HELP_CONTRACT_VERSION_V1;
+    readonly kind: ContextualHelpKindV1;
+    readonly moduleId: string;
+    readonly moduleVersion: string;
+    readonly manifestVersion: string;
+    readonly helpId: string;
+}
+type GuardianVoiceConsentStateV1 = "granted" | "withdrawn";
+type GuardianVoiceProcessingRouteV1 = "private-edge-only";
+/** Voice consent is deliberately separate from general AI consent. */
+interface GuardianVoiceConsentV1 {
+    readonly schemaVersion: "1";
+    readonly actorAccountId: string;
+    readonly subjectAccountId: string;
+    readonly policyVersion: string;
+    readonly state: GuardianVoiceConsentStateV1;
+    readonly permittedProcessingRoute: GuardianVoiceProcessingRouteV1;
+    readonly recordedAt: string;
+}
+type VoiceHelpAvailabilityReasonV1 = "available" | "module-access-required" | "guardian-consent-required" | "guardian-consent-withdrawn" | "age-or-safeguarding-gate" | "capability-disabled" | "rollout-disabled" | "private-edge-unavailable";
+/** Read-aloud and microphone availability are evaluated independently. */
+interface VoiceHelpAvailabilityV1 {
+    readonly schemaVersion: "1";
+    readonly readAloudAvailable: boolean;
+    readonly microphoneAvailable: boolean;
+    readonly microphoneReason: VoiceHelpAvailabilityReasonV1;
+    readonly questionProcessingRoute: GuardianVoiceProcessingRouteV1;
+    readonly guardianVoiceConsentRequired: true;
+    readonly maximumRecordingDurationMs: 10_000;
+    readonly maximumAudioBytes: 2_097_152;
+    readonly rawAudioRetention: "request-memory-only";
+    readonly transcriptRetention: "request-memory-only";
+}
+/** Metadata accepted beside an authenticated multipart audio upload. */
+interface ContextualVoiceQuestionMetadataV1 {
+    readonly schemaVersion: "1";
+    readonly help: ContextualHelpIdentifierV1;
+    readonly locale: string;
+    readonly mediaType: string;
+    readonly durationMs: number;
+    readonly audioBytes: number;
+    readonly assessmentEvidenceId?: string;
+}
+declare const CONTEXTUAL_VOICE_INTENTS_V1: readonly ["describe-command", "describe-inputs", "show-example", "explain-assessment-failure", "suggest-next-experiment", "repeat", "stop", "unresolved"];
+type ContextualVoiceIntentV1 = (typeof CONTEXTUAL_VOICE_INTENTS_V1)[number];
+type ContextualVoiceSuggestedActionV1 = "open-help" | "insert-example" | "show-inputs" | "show-assessment-evidence" | "try-next-experiment" | "repeat" | "stop" | "type-question";
+declare const CONTEXTUAL_VOICE_SUGGESTED_ACTIONS_V1: readonly ["open-help", "insert-example", "show-inputs", "show-assessment-evidence", "try-next-experiment", "repeat", "stop", "type-question"];
+interface ContextualVoiceAnswerV1 {
+    readonly helpId: string;
+    readonly source: "module-documentation" | "assessment-evidence" | "authored-fallback";
+    /** Server-resolved visible answer; never a model-authored open response. */
+    readonly text: string;
+}
+/**
+ * The transcript is returned only so the learner can verify recognition. The
+ * request boundary must use no-store and discard it after the current view.
+ */
+interface ContextualVoiceQuestionResultV1 {
+    readonly schemaVersion: "1";
+    readonly help: ContextualHelpIdentifierV1;
+    readonly intent: ContextualVoiceIntentV1;
+    readonly status: "resolved" | "suggestions" | "stopped";
+    readonly transientTranscript: string;
+    readonly transcriptRetention: "request-memory-only";
+    readonly answer?: ContextualVoiceAnswerV1;
+    readonly suggestedActions: ContextualVoiceSuggestedActionV1[];
+    readonly mayAssignScore: false;
+    readonly mayAwardReward: false;
+    readonly mayPublish: false;
+    readonly mayControlHardware: false;
+}
+/** Canonical audio lookup metadata. Authoritative speech text stays server-side. */
+interface CanonicalSpokenHelpDescriptorV1 {
+    readonly schemaVersion: "1";
+    readonly help: ContextualHelpIdentifierV1;
+    readonly canonicalTextId: string;
+    readonly authoritativeTextDigest: `sha256:${string}`;
+    readonly locale: string;
+    readonly voiceProfile: string;
+    readonly pronunciationVersion: string;
+    readonly utteranceClass: "system-generic";
+    readonly sharingScope: "global";
+    readonly reuse: "exact-only";
+    readonly containsPersonalData: false;
+    readonly containsLearnerContent: false;
+}
+declare function assertValidContextualHelpIdentifier(value: ContextualHelpIdentifierV1): void;
+declare function assertValidGuardianVoiceConsent(value: GuardianVoiceConsentV1): void;
+declare function assertValidContextualVoiceQuestionMetadata(value: ContextualVoiceQuestionMetadataV1): void;
+declare function assertValidVoiceHelpAvailability(value: VoiceHelpAvailabilityV1): void;
+declare function assertValidCanonicalSpokenHelpDescriptor(value: CanonicalSpokenHelpDescriptorV1): void;
+declare function assertValidContextualVoiceQuestionResult(value: ContextualVoiceQuestionResultV1): void;
+
 /** Versioned, infrastructure-neutral contracts for Guardian-approved static projects. */
 declare const STATIC_PROJECT_PUBLISHING_CONTRACT_VERSION_V1: "1.0.0";
 declare const STATIC_PROJECT_SCANNER_VERSION_V1: "junior-coder-static-scan-v1";
@@ -630,4 +733,4 @@ declare function validateLearningPath(path: LearningPathVersionV1): LearningVali
 /** Fail fast when a path is not safe to publish or consume. */
 declare function assertValidLearningPath(path: LearningPathVersionV1): void;
 
-export { ADVENTURE_MISSION_PLANNER_MISSION_ONE_AUTHORING_V1, type AdventureMissionPlannerSafeRenderV1, type AssessmentCheckResultV1, type AssessmentCriterionV1, type AssessmentDimensionV1, type AssessmentResultV1, type AssessmentRubricV1, type AttemptEvidenceV1, BEACON_BOT_MISSION_ONE_AUTHORING_V1, type BadgeDefinitionV1, CREATURE_CARE_DASHBOARD_MISSION_ONE_AUTHORING_V1, type CommercialStateV1, type CourseMaterialAudienceV1, type CourseMaterialKindV1, type CourseMaterialV1, type CourseMaterialsManifestV1, type CreatureCareDashboardSafeRenderV1, DANCE_ROVER_MISSION_ONE_AUTHORING_V1, type FacilitatorMissionAuthoringV1, type GuardianAiConsentV1, type HardwareItemV1, type HardwareModeV1, type HardwareRequirementManifestV1, type HardwareVerificationStatusV1, JUNIOR_CODER_MISSION_STAGE_ORDER_V1, JUNIOR_CODER_MODULE_PRICE_V1_1, JUNIOR_CODER_ROBOT_RESCUE_PATH_CURRENT, JUNIOR_CODER_ROBOT_RESCUE_PATH_V1, JUNIOR_CODER_ROBOT_RESCUE_PATH_V1_1, type LearnerMissionAuthoringV1, type LearningGoalV1, type LearningModuleVersionV1, type LearningPathVersionV1, type LearningValidationIssueV1, METEOR_SHIELD_MISSION_ONE_AUTHORING_V1, MISSION_AUTHORING_CONTRACT_VERSION_V1, type MissionAccessibilityAlternativeV1, type MissionArtifactKindV1, type MissionArtifactReferenceV1, type MissionAuthoringBundleV1, type MissionAuthoringGoalV1, type MissionAuthoringValidationIssueV1, type MissionBoundedSuggestionV1, type MissionEvidenceKindV1, type MissionEvidenceRequirementV1, type MissionEvidenceRetentionV1, type MissionFunctionParameterV1, type MissionFunctionReferenceV1, type MissionHardwareAcquisitionScopeV1, type MissionHardwareComponentDisclosureV1, type MissionHardwareDisclosureV1, type MissionInteractionModeV1, type MissionInteractionRequirementV1, type MissionPhysicalSafeguardsV1, type MissionReadinessCheckV1, type MissionRewardBindingV1, type MissionSideAdventureV1, type MissionStageCardV1, type MissionStageKindV1, type MissionV1, type ModuleAgentDefinitionV1, type ModuleAgentFeedbackV1, type ModuleAgentRoleV1, type ModuleCategoryV1, type ModuleEntitlementV1, type ModulePricingV1, type ModuleReferencePriceV1, OBSTACLE_EXPLORER_MISSION_ONE_AUTHORING_V1, PADDLE_PULSE_MISSION_ONE_AUTHORING_V1, PIXEL_TRAIL_CHALLENGE_MISSION_ONE_AUTHORING_V1, type PublishedStaticProjectSnapshotV1, RAINBOW_RESCUE_ROVER_MISSION_ONE_AUTHORING_V1, RESCUE_CREW_COMMANDER_MISSION_ONE_AUTHORING_V1, ROAD_HOPPER_RALLY_MISSION_ONE_AUTHORING_V1, ROBOT_MAZE_DASH_MISSION_ONE_AUTHORING_V1, ROBOT_MISSION_CONTROL_MISSION_ONE_AUTHORING_V1, type RobotMissionControlSafeRenderV1, SERVO_CREATURE_MISSION_ONE_AUTHORING_V1, SKYWING_SPRINT_MISSION_ONE_AUTHORING_V1, STAR_DEFENDER_SQUADRON_MISSION_ONE_AUTHORING_V1, STATIC_PROJECT_APPROVAL_STATEMENT_VERSION_V1, STATIC_PROJECT_DEFAULT_LIFETIME_DAYS_V1, STATIC_PROJECT_MAX_SOURCE_CHARACTERS_V1, STATIC_PROJECT_PUBLISHING_CONTRACT_VERSION_V1, STATIC_PROJECT_SAFETY_CHECK_IDS_V1, STATIC_PROJECT_SCANNER_VERSION_V1, type ScoreBandV1, type StaticProjectContractIssueV1, type StaticProjectGuardianApprovalV1, type StaticProjectModuleSlugV1, type StaticProjectPublicationV1, type StaticProjectSafeRenderV1, type StaticProjectSafetyCheckIdV1, type StaticProjectSafetyCheckV1, type StaticProjectSafetyScanV1, type StaticProjectSnapshotV1, VIBE_BUG_DETECTIVE_MISSION_ONE_AUTHORING_V1, VIBE_GAME_REMIX_LAB_MISSION_ONE_AUTHORING_V1, VIBE_IDEA_STUDIO_MISSION_ONE_AUTHORING_V1, assertValidLearningPath, assertValidMissionAuthoringBundle, assertValidStaticProjectGuardianApproval, assertValidStaticProjectPublication, assertValidStaticProjectSnapshot, calculateAssessment, validateAssessmentRubric, validateLearningPath, validateMissionAuthoringBundle, validateStaticProjectGuardianApproval, validateStaticProjectPublication, validateStaticProjectSnapshot };
+export { ADVENTURE_MISSION_PLANNER_MISSION_ONE_AUTHORING_V1, type AdventureMissionPlannerSafeRenderV1, type AssessmentCheckResultV1, type AssessmentCriterionV1, type AssessmentDimensionV1, type AssessmentResultV1, type AssessmentRubricV1, type AttemptEvidenceV1, BEACON_BOT_MISSION_ONE_AUTHORING_V1, type BadgeDefinitionV1, CONTEXTUAL_HELP_CONTRACT_VERSION_V1, CONTEXTUAL_HELP_KINDS_V1, CONTEXTUAL_VOICE_INTENTS_V1, CONTEXTUAL_VOICE_SUGGESTED_ACTIONS_V1, CREATURE_CARE_DASHBOARD_MISSION_ONE_AUTHORING_V1, type CanonicalSpokenHelpDescriptorV1, type CommercialStateV1, type ContextualHelpIdentifierV1, type ContextualHelpKindV1, type ContextualVoiceAnswerV1, type ContextualVoiceIntentV1, type ContextualVoiceQuestionMetadataV1, type ContextualVoiceQuestionResultV1, type ContextualVoiceSuggestedActionV1, type CourseMaterialAudienceV1, type CourseMaterialKindV1, type CourseMaterialV1, type CourseMaterialsManifestV1, type CreatureCareDashboardSafeRenderV1, DANCE_ROVER_MISSION_ONE_AUTHORING_V1, type FacilitatorMissionAuthoringV1, type GuardianAiConsentV1, type GuardianVoiceConsentStateV1, type GuardianVoiceConsentV1, type GuardianVoiceProcessingRouteV1, type HardwareItemV1, type HardwareModeV1, type HardwareRequirementManifestV1, type HardwareVerificationStatusV1, JUNIOR_CODER_MISSION_STAGE_ORDER_V1, JUNIOR_CODER_MODULE_PRICE_V1_1, JUNIOR_CODER_ROBOT_RESCUE_PATH_CURRENT, JUNIOR_CODER_ROBOT_RESCUE_PATH_V1, JUNIOR_CODER_ROBOT_RESCUE_PATH_V1_1, type LearnerMissionAuthoringV1, type LearningGoalV1, type LearningModuleVersionV1, type LearningPathVersionV1, type LearningValidationIssueV1, METEOR_SHIELD_MISSION_ONE_AUTHORING_V1, MISSION_AUTHORING_CONTRACT_VERSION_V1, type MissionAccessibilityAlternativeV1, type MissionArtifactKindV1, type MissionArtifactReferenceV1, type MissionAuthoringBundleV1, type MissionAuthoringGoalV1, type MissionAuthoringValidationIssueV1, type MissionBoundedSuggestionV1, type MissionEvidenceKindV1, type MissionEvidenceRequirementV1, type MissionEvidenceRetentionV1, type MissionFunctionParameterV1, type MissionFunctionReferenceV1, type MissionHardwareAcquisitionScopeV1, type MissionHardwareComponentDisclosureV1, type MissionHardwareDisclosureV1, type MissionInteractionModeV1, type MissionInteractionRequirementV1, type MissionPhysicalSafeguardsV1, type MissionReadinessCheckV1, type MissionRewardBindingV1, type MissionSideAdventureV1, type MissionStageCardV1, type MissionStageKindV1, type MissionV1, type ModuleAgentDefinitionV1, type ModuleAgentFeedbackV1, type ModuleAgentRoleV1, type ModuleCategoryV1, type ModuleEntitlementV1, type ModulePricingV1, type ModuleReferencePriceV1, OBSTACLE_EXPLORER_MISSION_ONE_AUTHORING_V1, PADDLE_PULSE_MISSION_ONE_AUTHORING_V1, PIXEL_TRAIL_CHALLENGE_MISSION_ONE_AUTHORING_V1, type PublishedStaticProjectSnapshotV1, RAINBOW_RESCUE_ROVER_MISSION_ONE_AUTHORING_V1, RESCUE_CREW_COMMANDER_MISSION_ONE_AUTHORING_V1, ROAD_HOPPER_RALLY_MISSION_ONE_AUTHORING_V1, ROBOT_MAZE_DASH_MISSION_ONE_AUTHORING_V1, ROBOT_MISSION_CONTROL_MISSION_ONE_AUTHORING_V1, type RobotMissionControlSafeRenderV1, SERVO_CREATURE_MISSION_ONE_AUTHORING_V1, SKYWING_SPRINT_MISSION_ONE_AUTHORING_V1, STAR_DEFENDER_SQUADRON_MISSION_ONE_AUTHORING_V1, STATIC_PROJECT_APPROVAL_STATEMENT_VERSION_V1, STATIC_PROJECT_DEFAULT_LIFETIME_DAYS_V1, STATIC_PROJECT_MAX_SOURCE_CHARACTERS_V1, STATIC_PROJECT_PUBLISHING_CONTRACT_VERSION_V1, STATIC_PROJECT_SAFETY_CHECK_IDS_V1, STATIC_PROJECT_SCANNER_VERSION_V1, type ScoreBandV1, type StaticProjectContractIssueV1, type StaticProjectGuardianApprovalV1, type StaticProjectModuleSlugV1, type StaticProjectPublicationV1, type StaticProjectSafeRenderV1, type StaticProjectSafetyCheckIdV1, type StaticProjectSafetyCheckV1, type StaticProjectSafetyScanV1, type StaticProjectSnapshotV1, VIBE_BUG_DETECTIVE_MISSION_ONE_AUTHORING_V1, VIBE_GAME_REMIX_LAB_MISSION_ONE_AUTHORING_V1, VIBE_IDEA_STUDIO_MISSION_ONE_AUTHORING_V1, type VoiceHelpAvailabilityReasonV1, type VoiceHelpAvailabilityV1, assertValidCanonicalSpokenHelpDescriptor, assertValidContextualHelpIdentifier, assertValidContextualVoiceQuestionMetadata, assertValidContextualVoiceQuestionResult, assertValidGuardianVoiceConsent, assertValidLearningPath, assertValidMissionAuthoringBundle, assertValidStaticProjectGuardianApproval, assertValidStaticProjectPublication, assertValidStaticProjectSnapshot, assertValidVoiceHelpAvailability, calculateAssessment, validateAssessmentRubric, validateLearningPath, validateMissionAuthoringBundle, validateStaticProjectGuardianApproval, validateStaticProjectPublication, validateStaticProjectSnapshot };

package/dist/index.d.ts

@@ -429,6 +429,109 @@ declare const JUNIOR_CODER_ROBOT_RESCUE_PATH_V1_1: LearningPathVersionV1;
 /** Current pilot catalog for server adapters that intentionally follow releases. */
 declare const JUNIOR_CODER_ROBOT_RESCUE_PATH_CURRENT: LearningPathVersionV1;
 
+/** Additive contract version for touch-first and spoken contextual help. */
+declare const CONTEXTUAL_HELP_CONTRACT_VERSION_V1: "1.0.0";
+declare const CONTEXTUAL_HELP_KINDS_V1: readonly ["command", "visual-block", "generated-code", "assessment-diagnostic"];
+type ContextualHelpKindV1 = (typeof CONTEXTUAL_HELP_KINDS_V1)[number];
+/**
+ * Opaque, manifest-bound identifier. It contains no source, transcript,
+ * learner identity or arbitrary synthesis text.
+ */
+interface ContextualHelpIdentifierV1 {
+    readonly schemaVersion: "1";
+    readonly contractVersion: typeof CONTEXTUAL_HELP_CONTRACT_VERSION_V1;
+    readonly kind: ContextualHelpKindV1;
+    readonly moduleId: string;
+    readonly moduleVersion: string;
+    readonly manifestVersion: string;
+    readonly helpId: string;
+}
+type GuardianVoiceConsentStateV1 = "granted" | "withdrawn";
+type GuardianVoiceProcessingRouteV1 = "private-edge-only";
+/** Voice consent is deliberately separate from general AI consent. */
+interface GuardianVoiceConsentV1 {
+    readonly schemaVersion: "1";
+    readonly actorAccountId: string;
+    readonly subjectAccountId: string;
+    readonly policyVersion: string;
+    readonly state: GuardianVoiceConsentStateV1;
+    readonly permittedProcessingRoute: GuardianVoiceProcessingRouteV1;
+    readonly recordedAt: string;
+}
+type VoiceHelpAvailabilityReasonV1 = "available" | "module-access-required" | "guardian-consent-required" | "guardian-consent-withdrawn" | "age-or-safeguarding-gate" | "capability-disabled" | "rollout-disabled" | "private-edge-unavailable";
+/** Read-aloud and microphone availability are evaluated independently. */
+interface VoiceHelpAvailabilityV1 {
+    readonly schemaVersion: "1";
+    readonly readAloudAvailable: boolean;
+    readonly microphoneAvailable: boolean;
+    readonly microphoneReason: VoiceHelpAvailabilityReasonV1;
+    readonly questionProcessingRoute: GuardianVoiceProcessingRouteV1;
+    readonly guardianVoiceConsentRequired: true;
+    readonly maximumRecordingDurationMs: 10_000;
+    readonly maximumAudioBytes: 2_097_152;
+    readonly rawAudioRetention: "request-memory-only";
+    readonly transcriptRetention: "request-memory-only";
+}
+/** Metadata accepted beside an authenticated multipart audio upload. */
+interface ContextualVoiceQuestionMetadataV1 {
+    readonly schemaVersion: "1";
+    readonly help: ContextualHelpIdentifierV1;
+    readonly locale: string;
+    readonly mediaType: string;
+    readonly durationMs: number;
+    readonly audioBytes: number;
+    readonly assessmentEvidenceId?: string;
+}
+declare const CONTEXTUAL_VOICE_INTENTS_V1: readonly ["describe-command", "describe-inputs", "show-example", "explain-assessment-failure", "suggest-next-experiment", "repeat", "stop", "unresolved"];
+type ContextualVoiceIntentV1 = (typeof CONTEXTUAL_VOICE_INTENTS_V1)[number];
+type ContextualVoiceSuggestedActionV1 = "open-help" | "insert-example" | "show-inputs" | "show-assessment-evidence" | "try-next-experiment" | "repeat" | "stop" | "type-question";
+declare const CONTEXTUAL_VOICE_SUGGESTED_ACTIONS_V1: readonly ["open-help", "insert-example", "show-inputs", "show-assessment-evidence", "try-next-experiment", "repeat", "stop", "type-question"];
+interface ContextualVoiceAnswerV1 {
+    readonly helpId: string;
+    readonly source: "module-documentation" | "assessment-evidence" | "authored-fallback";
+    /** Server-resolved visible answer; never a model-authored open response. */
+    readonly text: string;
+}
+/**
+ * The transcript is returned only so the learner can verify recognition. The
+ * request boundary must use no-store and discard it after the current view.
+ */
+interface ContextualVoiceQuestionResultV1 {
+    readonly schemaVersion: "1";
+    readonly help: ContextualHelpIdentifierV1;
+    readonly intent: ContextualVoiceIntentV1;
+    readonly status: "resolved" | "suggestions" | "stopped";
+    readonly transientTranscript: string;
+    readonly transcriptRetention: "request-memory-only";
+    readonly answer?: ContextualVoiceAnswerV1;
+    readonly suggestedActions: ContextualVoiceSuggestedActionV1[];
+    readonly mayAssignScore: false;
+    readonly mayAwardReward: false;
+    readonly mayPublish: false;
+    readonly mayControlHardware: false;
+}
+/** Canonical audio lookup metadata. Authoritative speech text stays server-side. */
+interface CanonicalSpokenHelpDescriptorV1 {
+    readonly schemaVersion: "1";
+    readonly help: ContextualHelpIdentifierV1;
+    readonly canonicalTextId: string;
+    readonly authoritativeTextDigest: `sha256:${string}`;
+    readonly locale: string;
+    readonly voiceProfile: string;
+    readonly pronunciationVersion: string;
+    readonly utteranceClass: "system-generic";
+    readonly sharingScope: "global";
+    readonly reuse: "exact-only";
+    readonly containsPersonalData: false;
+    readonly containsLearnerContent: false;
+}
+declare function assertValidContextualHelpIdentifier(value: ContextualHelpIdentifierV1): void;
+declare function assertValidGuardianVoiceConsent(value: GuardianVoiceConsentV1): void;
+declare function assertValidContextualVoiceQuestionMetadata(value: ContextualVoiceQuestionMetadataV1): void;
+declare function assertValidVoiceHelpAvailability(value: VoiceHelpAvailabilityV1): void;
+declare function assertValidCanonicalSpokenHelpDescriptor(value: CanonicalSpokenHelpDescriptorV1): void;
+declare function assertValidContextualVoiceQuestionResult(value: ContextualVoiceQuestionResultV1): void;
+
 /** Versioned, infrastructure-neutral contracts for Guardian-approved static projects. */
 declare const STATIC_PROJECT_PUBLISHING_CONTRACT_VERSION_V1: "1.0.0";
 declare const STATIC_PROJECT_SCANNER_VERSION_V1: "junior-coder-static-scan-v1";
@@ -630,4 +733,4 @@ declare function validateLearningPath(path: LearningPathVersionV1): LearningVali
 /** Fail fast when a path is not safe to publish or consume. */
 declare function assertValidLearningPath(path: LearningPathVersionV1): void;
 
-export { ADVENTURE_MISSION_PLANNER_MISSION_ONE_AUTHORING_V1, type AdventureMissionPlannerSafeRenderV1, type AssessmentCheckResultV1, type AssessmentCriterionV1, type AssessmentDimensionV1, type AssessmentResultV1, type AssessmentRubricV1, type AttemptEvidenceV1, BEACON_BOT_MISSION_ONE_AUTHORING_V1, type BadgeDefinitionV1, CREATURE_CARE_DASHBOARD_MISSION_ONE_AUTHORING_V1, type CommercialStateV1, type CourseMaterialAudienceV1, type CourseMaterialKindV1, type CourseMaterialV1, type CourseMaterialsManifestV1, type CreatureCareDashboardSafeRenderV1, DANCE_ROVER_MISSION_ONE_AUTHORING_V1, type FacilitatorMissionAuthoringV1, type GuardianAiConsentV1, type HardwareItemV1, type HardwareModeV1, type HardwareRequirementManifestV1, type HardwareVerificationStatusV1, JUNIOR_CODER_MISSION_STAGE_ORDER_V1, JUNIOR_CODER_MODULE_PRICE_V1_1, JUNIOR_CODER_ROBOT_RESCUE_PATH_CURRENT, JUNIOR_CODER_ROBOT_RESCUE_PATH_V1, JUNIOR_CODER_ROBOT_RESCUE_PATH_V1_1, type LearnerMissionAuthoringV1, type LearningGoalV1, type LearningModuleVersionV1, type LearningPathVersionV1, type LearningValidationIssueV1, METEOR_SHIELD_MISSION_ONE_AUTHORING_V1, MISSION_AUTHORING_CONTRACT_VERSION_V1, type MissionAccessibilityAlternativeV1, type MissionArtifactKindV1, type MissionArtifactReferenceV1, type MissionAuthoringBundleV1, type MissionAuthoringGoalV1, type MissionAuthoringValidationIssueV1, type MissionBoundedSuggestionV1, type MissionEvidenceKindV1, type MissionEvidenceRequirementV1, type MissionEvidenceRetentionV1, type MissionFunctionParameterV1, type MissionFunctionReferenceV1, type MissionHardwareAcquisitionScopeV1, type MissionHardwareComponentDisclosureV1, type MissionHardwareDisclosureV1, type MissionInteractionModeV1, type MissionInteractionRequirementV1, type MissionPhysicalSafeguardsV1, type MissionReadinessCheckV1, type MissionRewardBindingV1, type MissionSideAdventureV1, type MissionStageCardV1, type MissionStageKindV1, type MissionV1, type ModuleAgentDefinitionV1, type ModuleAgentFeedbackV1, type ModuleAgentRoleV1, type ModuleCategoryV1, type ModuleEntitlementV1, type ModulePricingV1, type ModuleReferencePriceV1, OBSTACLE_EXPLORER_MISSION_ONE_AUTHORING_V1, PADDLE_PULSE_MISSION_ONE_AUTHORING_V1, PIXEL_TRAIL_CHALLENGE_MISSION_ONE_AUTHORING_V1, type PublishedStaticProjectSnapshotV1, RAINBOW_RESCUE_ROVER_MISSION_ONE_AUTHORING_V1, RESCUE_CREW_COMMANDER_MISSION_ONE_AUTHORING_V1, ROAD_HOPPER_RALLY_MISSION_ONE_AUTHORING_V1, ROBOT_MAZE_DASH_MISSION_ONE_AUTHORING_V1, ROBOT_MISSION_CONTROL_MISSION_ONE_AUTHORING_V1, type RobotMissionControlSafeRenderV1, SERVO_CREATURE_MISSION_ONE_AUTHORING_V1, SKYWING_SPRINT_MISSION_ONE_AUTHORING_V1, STAR_DEFENDER_SQUADRON_MISSION_ONE_AUTHORING_V1, STATIC_PROJECT_APPROVAL_STATEMENT_VERSION_V1, STATIC_PROJECT_DEFAULT_LIFETIME_DAYS_V1, STATIC_PROJECT_MAX_SOURCE_CHARACTERS_V1, STATIC_PROJECT_PUBLISHING_CONTRACT_VERSION_V1, STATIC_PROJECT_SAFETY_CHECK_IDS_V1, STATIC_PROJECT_SCANNER_VERSION_V1, type ScoreBandV1, type StaticProjectContractIssueV1, type StaticProjectGuardianApprovalV1, type StaticProjectModuleSlugV1, type StaticProjectPublicationV1, type StaticProjectSafeRenderV1, type StaticProjectSafetyCheckIdV1, type StaticProjectSafetyCheckV1, type StaticProjectSafetyScanV1, type StaticProjectSnapshotV1, VIBE_BUG_DETECTIVE_MISSION_ONE_AUTHORING_V1, VIBE_GAME_REMIX_LAB_MISSION_ONE_AUTHORING_V1, VIBE_IDEA_STUDIO_MISSION_ONE_AUTHORING_V1, assertValidLearningPath, assertValidMissionAuthoringBundle, assertValidStaticProjectGuardianApproval, assertValidStaticProjectPublication, assertValidStaticProjectSnapshot, calculateAssessment, validateAssessmentRubric, validateLearningPath, validateMissionAuthoringBundle, validateStaticProjectGuardianApproval, validateStaticProjectPublication, validateStaticProjectSnapshot };
+export { ADVENTURE_MISSION_PLANNER_MISSION_ONE_AUTHORING_V1, type AdventureMissionPlannerSafeRenderV1, type AssessmentCheckResultV1, type AssessmentCriterionV1, type AssessmentDimensionV1, type AssessmentResultV1, type AssessmentRubricV1, type AttemptEvidenceV1, BEACON_BOT_MISSION_ONE_AUTHORING_V1, type BadgeDefinitionV1, CONTEXTUAL_HELP_CONTRACT_VERSION_V1, CONTEXTUAL_HELP_KINDS_V1, CONTEXTUAL_VOICE_INTENTS_V1, CONTEXTUAL_VOICE_SUGGESTED_ACTIONS_V1, CREATURE_CARE_DASHBOARD_MISSION_ONE_AUTHORING_V1, type CanonicalSpokenHelpDescriptorV1, type CommercialStateV1, type ContextualHelpIdentifierV1, type ContextualHelpKindV1, type ContextualVoiceAnswerV1, type ContextualVoiceIntentV1, type ContextualVoiceQuestionMetadataV1, type ContextualVoiceQuestionResultV1, type ContextualVoiceSuggestedActionV1, type CourseMaterialAudienceV1, type CourseMaterialKindV1, type CourseMaterialV1, type CourseMaterialsManifestV1, type CreatureCareDashboardSafeRenderV1, DANCE_ROVER_MISSION_ONE_AUTHORING_V1, type FacilitatorMissionAuthoringV1, type GuardianAiConsentV1, type GuardianVoiceConsentStateV1, type GuardianVoiceConsentV1, type GuardianVoiceProcessingRouteV1, type HardwareItemV1, type HardwareModeV1, type HardwareRequirementManifestV1, type HardwareVerificationStatusV1, JUNIOR_CODER_MISSION_STAGE_ORDER_V1, JUNIOR_CODER_MODULE_PRICE_V1_1, JUNIOR_CODER_ROBOT_RESCUE_PATH_CURRENT, JUNIOR_CODER_ROBOT_RESCUE_PATH_V1, JUNIOR_CODER_ROBOT_RESCUE_PATH_V1_1, type LearnerMissionAuthoringV1, type LearningGoalV1, type LearningModuleVersionV1, type LearningPathVersionV1, type LearningValidationIssueV1, METEOR_SHIELD_MISSION_ONE_AUTHORING_V1, MISSION_AUTHORING_CONTRACT_VERSION_V1, type MissionAccessibilityAlternativeV1, type MissionArtifactKindV1, type MissionArtifactReferenceV1, type MissionAuthoringBundleV1, type MissionAuthoringGoalV1, type MissionAuthoringValidationIssueV1, type MissionBoundedSuggestionV1, type MissionEvidenceKindV1, type MissionEvidenceRequirementV1, type MissionEvidenceRetentionV1, type MissionFunctionParameterV1, type MissionFunctionReferenceV1, type MissionHardwareAcquisitionScopeV1, type MissionHardwareComponentDisclosureV1, type MissionHardwareDisclosureV1, type MissionInteractionModeV1, type MissionInteractionRequirementV1, type MissionPhysicalSafeguardsV1, type MissionReadinessCheckV1, type MissionRewardBindingV1, type MissionSideAdventureV1, type MissionStageCardV1, type MissionStageKindV1, type MissionV1, type ModuleAgentDefinitionV1, type ModuleAgentFeedbackV1, type ModuleAgentRoleV1, type ModuleCategoryV1, type ModuleEntitlementV1, type ModulePricingV1, type ModuleReferencePriceV1, OBSTACLE_EXPLORER_MISSION_ONE_AUTHORING_V1, PADDLE_PULSE_MISSION_ONE_AUTHORING_V1, PIXEL_TRAIL_CHALLENGE_MISSION_ONE_AUTHORING_V1, type PublishedStaticProjectSnapshotV1, RAINBOW_RESCUE_ROVER_MISSION_ONE_AUTHORING_V1, RESCUE_CREW_COMMANDER_MISSION_ONE_AUTHORING_V1, ROAD_HOPPER_RALLY_MISSION_ONE_AUTHORING_V1, ROBOT_MAZE_DASH_MISSION_ONE_AUTHORING_V1, ROBOT_MISSION_CONTROL_MISSION_ONE_AUTHORING_V1, type RobotMissionControlSafeRenderV1, SERVO_CREATURE_MISSION_ONE_AUTHORING_V1, SKYWING_SPRINT_MISSION_ONE_AUTHORING_V1, STAR_DEFENDER_SQUADRON_MISSION_ONE_AUTHORING_V1, STATIC_PROJECT_APPROVAL_STATEMENT_VERSION_V1, STATIC_PROJECT_DEFAULT_LIFETIME_DAYS_V1, STATIC_PROJECT_MAX_SOURCE_CHARACTERS_V1, STATIC_PROJECT_PUBLISHING_CONTRACT_VERSION_V1, STATIC_PROJECT_SAFETY_CHECK_IDS_V1, STATIC_PROJECT_SCANNER_VERSION_V1, type ScoreBandV1, type StaticProjectContractIssueV1, type StaticProjectGuardianApprovalV1, type StaticProjectModuleSlugV1, type StaticProjectPublicationV1, type StaticProjectSafeRenderV1, type StaticProjectSafetyCheckIdV1, type StaticProjectSafetyCheckV1, type StaticProjectSafetyScanV1, type StaticProjectSnapshotV1, VIBE_BUG_DETECTIVE_MISSION_ONE_AUTHORING_V1, VIBE_GAME_REMIX_LAB_MISSION_ONE_AUTHORING_V1, VIBE_IDEA_STUDIO_MISSION_ONE_AUTHORING_V1, type VoiceHelpAvailabilityReasonV1, type VoiceHelpAvailabilityV1, assertValidCanonicalSpokenHelpDescriptor, assertValidContextualHelpIdentifier, assertValidContextualVoiceQuestionMetadata, assertValidContextualVoiceQuestionResult, assertValidGuardianVoiceConsent, assertValidLearningPath, assertValidMissionAuthoringBundle, assertValidStaticProjectGuardianApproval, assertValidStaticProjectPublication, assertValidStaticProjectSnapshot, assertValidVoiceHelpAvailability, calculateAssessment, validateAssessmentRubric, validateLearningPath, validateMissionAuthoringBundle, validateStaticProjectGuardianApproval, validateStaticProjectPublication, validateStaticProjectSnapshot };

package/dist/index.js

@@ -571,6 +571,164 @@ var JUNIOR_CODER_ROBOT_RESCUE_PATH_CURRENT = JUNIOR_CODER_ROBOT_RESCUE_PATH_V1_1
 // src/contracts.ts
 var MISSION_AUTHORING_CONTRACT_VERSION_V1 = "1.0.0";
 
+// src/contextual-help.ts
+var CONTEXTUAL_HELP_CONTRACT_VERSION_V1 = "1.0.0";
+var CONTEXTUAL_HELP_KINDS_V1 = Object.freeze([
+  "command",
+  "visual-block",
+  "generated-code",
+  "assessment-diagnostic"
+]);
+var CONTEXTUAL_VOICE_INTENTS_V1 = Object.freeze([
+  "describe-command",
+  "describe-inputs",
+  "show-example",
+  "explain-assessment-failure",
+  "suggest-next-experiment",
+  "repeat",
+  "stop",
+  "unresolved"
+]);
+var CONTEXTUAL_VOICE_SUGGESTED_ACTIONS_V1 = Object.freeze([
+  "open-help",
+  "insert-example",
+  "show-inputs",
+  "show-assessment-evidence",
+  "try-next-experiment",
+  "repeat",
+  "stop",
+  "type-question"
+]);
+var OPAQUE_ID = /^[a-z0-9]+(?:[._:-][a-z0-9]+)*$/u;
+var SEMVER = /^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$/u;
+var SHA_256 = /^sha256:[a-f0-9]{64}$/u;
+var LOCALE = /^[a-z]{2,3}(?:-[A-Z]{2})?$/u;
+var MEDIA_TYPE = /^audio\/[a-z0-9.+-]+$/u;
+function containsDisallowedControlCharacter(value) {
+  return [...value].some((character) => {
+    const code = character.codePointAt(0) ?? 0;
+    return code <= 8 || code === 11 || code === 12 || code >= 14 && code <= 31 || code === 127;
+  });
+}
+function requireOpaqueId(value, label, maximum = 160) {
+  if (value.length === 0 || value.length > maximum || !OPAQUE_ID.test(value)) {
+    throw new Error(`${label} must be a bounded opaque identifier.`);
+  }
+}
+function requireSemver(value, label) {
+  if (!SEMVER.test(value)) {
+    throw new Error(`${label} must be an immutable semantic version.`);
+  }
+}
+function requireIsoTimestamp(value, label) {
+  if (!/^\d{4}-\d{2}-\d{2}T/u.test(value) || !Number.isFinite(Date.parse(value))) {
+    throw new Error(`${label} must be an ISO-8601 timestamp.`);
+  }
+}
+function assertValidContextualHelpIdentifier(value) {
+  if (value.schemaVersion !== "1") {
+    throw new Error("schemaVersion must be 1.");
+  }
+  if (value.contractVersion !== CONTEXTUAL_HELP_CONTRACT_VERSION_V1) {
+    throw new Error("contractVersion is unsupported.");
+  }
+  if (!CONTEXTUAL_HELP_KINDS_V1.includes(value.kind)) {
+    throw new Error("kind is unsupported.");
+  }
+  requireOpaqueId(value.moduleId, "moduleId");
+  requireSemver(value.moduleVersion, "moduleVersion");
+  requireSemver(value.manifestVersion, "manifestVersion");
+  requireOpaqueId(value.helpId, "helpId");
+}
+function assertValidGuardianVoiceConsent(value) {
+  if (value.schemaVersion !== "1") {
+    throw new Error("schemaVersion must be 1.");
+  }
+  requireOpaqueId(value.actorAccountId, "actorAccountId");
+  requireOpaqueId(value.subjectAccountId, "subjectAccountId");
+  requireSemver(value.policyVersion, "policyVersion");
+  if (value.state !== "granted" && value.state !== "withdrawn") {
+    throw new Error("state must be granted or withdrawn.");
+  }
+  if (value.permittedProcessingRoute !== "private-edge-only") {
+    throw new Error("permittedProcessingRoute must be private-edge-only.");
+  }
+  requireIsoTimestamp(value.recordedAt, "recordedAt");
+}
+function assertValidContextualVoiceQuestionMetadata(value) {
+  assertValidContextualHelpIdentifier(value.help);
+  if (!LOCALE.test(value.locale)) throw new Error("locale is invalid.");
+  if (!MEDIA_TYPE.test(value.mediaType)) throw new Error("mediaType is invalid.");
+  if (!Number.isInteger(value.durationMs) || value.durationMs < 1 || value.durationMs > 1e4) {
+    throw new Error("durationMs must be between 1 and 10000.");
+  }
+  if (!Number.isInteger(value.audioBytes) || value.audioBytes < 1 || value.audioBytes > 2097152) {
+    throw new Error("audioBytes must be between 1 and 2097152.");
+  }
+  if (value.assessmentEvidenceId !== void 0) {
+    requireOpaqueId(value.assessmentEvidenceId, "assessmentEvidenceId");
+  }
+}
+function assertValidVoiceHelpAvailability(value) {
+  if (value.schemaVersion !== "1") throw new Error("schemaVersion must be 1.");
+  if (value.questionProcessingRoute !== "private-edge-only") {
+    throw new Error("questionProcessingRoute must be private-edge-only.");
+  }
+  if (value.guardianVoiceConsentRequired !== true) {
+    throw new Error("guardianVoiceConsentRequired must remain true.");
+  }
+  if (value.maximumRecordingDurationMs !== 1e4 || value.maximumAudioBytes !== 2097152 || value.rawAudioRetention !== "request-memory-only" || value.transcriptRetention !== "request-memory-only") {
+    throw new Error("Voice limits and transient retention are immutable in version one.");
+  }
+  if (value.microphoneAvailable !== (value.microphoneReason === "available")) {
+    throw new Error("microphoneReason must match microphone availability.");
+  }
+}
+function assertValidCanonicalSpokenHelpDescriptor(value) {
+  if (value.schemaVersion !== "1") throw new Error("schemaVersion must be 1.");
+  assertValidContextualHelpIdentifier(value.help);
+  requireOpaqueId(value.canonicalTextId, "canonicalTextId");
+  if (!SHA_256.test(value.authoritativeTextDigest)) {
+    throw new Error("authoritativeTextDigest must be a SHA-256 digest.");
+  }
+  if (!LOCALE.test(value.locale)) throw new Error("locale is invalid.");
+  requireOpaqueId(value.voiceProfile, "voiceProfile");
+  requireSemver(value.pronunciationVersion, "pronunciationVersion");
+  if (value.utteranceClass !== "system-generic" || value.sharingScope !== "global" || value.reuse !== "exact-only" || value.containsPersonalData !== false || value.containsLearnerContent !== false) {
+    throw new Error("Canonical spoken help must use global system-generic exact-only reuse.");
+  }
+}
+function assertValidContextualVoiceQuestionResult(value) {
+  if (value.schemaVersion !== "1") throw new Error("schemaVersion must be 1.");
+  assertValidContextualHelpIdentifier(value.help);
+  if (!CONTEXTUAL_VOICE_INTENTS_V1.includes(value.intent)) {
+    throw new Error("intent is unsupported.");
+  }
+  if (value.transcriptRetention !== "request-memory-only") {
+    throw new Error("transcriptRetention must be request-memory-only.");
+  }
+  if (value.status !== "resolved" && value.status !== "suggestions" && value.status !== "stopped") {
+    throw new Error("status is unsupported.");
+  }
+  if (value.transientTranscript.length > 500 || containsDisallowedControlCharacter(value.transientTranscript)) {
+    throw new Error("transientTranscript is invalid.");
+  }
+  if (value.answer) {
+    requireOpaqueId(value.answer.helpId, "answer.helpId");
+    if (value.answer.source !== "module-documentation" && value.answer.source !== "assessment-evidence" && value.answer.source !== "authored-fallback" || value.answer.text.length === 0 || value.answer.text.length > 800 || containsDisallowedControlCharacter(value.answer.text)) {
+      throw new Error("answer.text is invalid.");
+    }
+  }
+  if (value.suggestedActions.some(
+    (action) => !CONTEXTUAL_VOICE_SUGGESTED_ACTIONS_V1.includes(action)
+  )) {
+    throw new Error("suggestedActions contains an unsupported action.");
+  }
+  if (value.mayAssignScore !== false || value.mayAwardReward !== false || value.mayPublish !== false || value.mayControlHardware !== false) {
+    throw new Error("mayAssignScore, reward, publish and hardware authority must remain false.");
+  }
+}
+
 // src/publishing.ts
 var STATIC_PROJECT_PUBLISHING_CONTRACT_VERSION_V1 = "1.0.0";
 var STATIC_PROJECT_SCANNER_VERSION_V1 = "junior-coder-static-scan-v1";
@@ -6759,6 +6917,10 @@ ${summary}`);
 export {
   ADVENTURE_MISSION_PLANNER_MISSION_ONE_AUTHORING_V1,
   BEACON_BOT_MISSION_ONE_AUTHORING_V1,
+  CONTEXTUAL_HELP_CONTRACT_VERSION_V1,
+  CONTEXTUAL_HELP_KINDS_V1,
+  CONTEXTUAL_VOICE_INTENTS_V1,
+  CONTEXTUAL_VOICE_SUGGESTED_ACTIONS_V1,
   CREATURE_CARE_DASHBOARD_MISSION_ONE_AUTHORING_V1,
   DANCE_ROVER_MISSION_ONE_AUTHORING_V1,
   JUNIOR_CODER_MISSION_STAGE_ORDER_V1,
@@ -6788,11 +6950,17 @@ export {
   VIBE_BUG_DETECTIVE_MISSION_ONE_AUTHORING_V1,
   VIBE_GAME_REMIX_LAB_MISSION_ONE_AUTHORING_V1,
   VIBE_IDEA_STUDIO_MISSION_ONE_AUTHORING_V1,
+  assertValidCanonicalSpokenHelpDescriptor,
+  assertValidContextualHelpIdentifier,
+  assertValidContextualVoiceQuestionMetadata,
+  assertValidContextualVoiceQuestionResult,
+  assertValidGuardianVoiceConsent,
   assertValidLearningPath,
   assertValidMissionAuthoringBundle,
   assertValidStaticProjectGuardianApproval,
   assertValidStaticProjectPublication,
   assertValidStaticProjectSnapshot,
+  assertValidVoiceHelpAvailability,
   calculateAssessment,
   validateAssessmentRubric,
   validateLearningPath,