@plasius/learning 0.2.20 → 0.2.21

package/README.md

@@ -54,6 +54,37 @@ const result = calculateAssessment(rubric, [
 console.log(result.score, result.completed);
 ```
 
+## Bind contextual and spoken help
+
+Contextual-help identifiers are immutable module/manifest references rather
+than free-form learner text. Voice consent is separate from general AI consent,
+and version one permits private-edge transcription only.
+
+```ts
+import {
+  CONTEXTUAL_HELP_CONTRACT_VERSION_V1,
+  assertValidContextualHelpIdentifier,
+  type ContextualHelpIdentifierV1,
+} from "@plasius/learning";
+
+const help: ContextualHelpIdentifierV1 = {
+  schemaVersion: "1",
+  contractVersion: CONTEXTUAL_HELP_CONTRACT_VERSION_V1,
+  kind: "command",
+  moduleId: "junior-coder.road-hopper-rally",
+  moduleVersion: "1.1.0",
+  manifestVersion: "1.0.0",
+  helpId: "command.draw-lane",
+};
+
+assertValidContextualHelpIdentifier(help);
+```
+
+The package also exports `GuardianVoiceConsentV1`,
+`VoiceHelpAvailabilityV1`, bounded voice question metadata/results and
+`CanonicalSpokenHelpDescriptorV1`. It does not record audio, persist consent,
+call a transcription or synthesis provider, or evaluate runtime rollout flags.
+
 ## Validate a Guardian-approved static project
 
 The publishing contracts cover only immutable evidence and safe render models.

package/dist/index.cjs

@@ -22,6 +22,10 @@ var index_exports = {};
 __export(index_exports, {
   ADVENTURE_MISSION_PLANNER_MISSION_ONE_AUTHORING_V1: () => ADVENTURE_MISSION_PLANNER_MISSION_ONE_AUTHORING_V1,
   BEACON_BOT_MISSION_ONE_AUTHORING_V1: () => BEACON_BOT_MISSION_ONE_AUTHORING_V1,
+  CONTEXTUAL_HELP_CONTRACT_VERSION_V1: () => CONTEXTUAL_HELP_CONTRACT_VERSION_V1,
+  CONTEXTUAL_HELP_KINDS_V1: () => CONTEXTUAL_HELP_KINDS_V1,
+  CONTEXTUAL_VOICE_INTENTS_V1: () => CONTEXTUAL_VOICE_INTENTS_V1,
+  CONTEXTUAL_VOICE_SUGGESTED_ACTIONS_V1: () => CONTEXTUAL_VOICE_SUGGESTED_ACTIONS_V1,
   CREATURE_CARE_DASHBOARD_MISSION_ONE_AUTHORING_V1: () => CREATURE_CARE_DASHBOARD_MISSION_ONE_AUTHORING_V1,
   DANCE_ROVER_MISSION_ONE_AUTHORING_V1: () => DANCE_ROVER_MISSION_ONE_AUTHORING_V1,
   JUNIOR_CODER_MISSION_STAGE_ORDER_V1: () => JUNIOR_CODER_MISSION_STAGE_ORDER_V1,
@@ -51,11 +55,17 @@ __export(index_exports, {
   VIBE_BUG_DETECTIVE_MISSION_ONE_AUTHORING_V1: () => VIBE_BUG_DETECTIVE_MISSION_ONE_AUTHORING_V1,
   VIBE_GAME_REMIX_LAB_MISSION_ONE_AUTHORING_V1: () => VIBE_GAME_REMIX_LAB_MISSION_ONE_AUTHORING_V1,
   VIBE_IDEA_STUDIO_MISSION_ONE_AUTHORING_V1: () => VIBE_IDEA_STUDIO_MISSION_ONE_AUTHORING_V1,
+  assertValidCanonicalSpokenHelpDescriptor: () => assertValidCanonicalSpokenHelpDescriptor,
+  assertValidContextualHelpIdentifier: () => assertValidContextualHelpIdentifier,
+  assertValidContextualVoiceQuestionMetadata: () => assertValidContextualVoiceQuestionMetadata,
+  assertValidContextualVoiceQuestionResult: () => assertValidContextualVoiceQuestionResult,
+  assertValidGuardianVoiceConsent: () => assertValidGuardianVoiceConsent,
   assertValidLearningPath: () => assertValidLearningPath,
   assertValidMissionAuthoringBundle: () => assertValidMissionAuthoringBundle,
   assertValidStaticProjectGuardianApproval: () => assertValidStaticProjectGuardianApproval,
   assertValidStaticProjectPublication: () => assertValidStaticProjectPublication,
   assertValidStaticProjectSnapshot: () => assertValidStaticProjectSnapshot,
+  assertValidVoiceHelpAvailability: () => assertValidVoiceHelpAvailability,
   calculateAssessment: () => calculateAssessment,
   validateAssessmentRubric: () => validateAssessmentRubric,
   validateLearningPath: () => validateLearningPath,
@@ -639,6 +649,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";
@@ -6828,6 +6996,10 @@ ${summary}`);
 0 && (module.exports = {
   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,
@@ -6857,11 +7029,17 @@ ${summary}`);
   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,