@plasius/learning 0.2.19 → 0.2.21

package/dist/index.js

@@ -571,6 +571,293 @@ 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";
+var STATIC_PROJECT_APPROVAL_STATEMENT_VERSION_V1 = "guardian-static-publication-v1";
+var STATIC_PROJECT_DEFAULT_LIFETIME_DAYS_V1 = 90;
+var STATIC_PROJECT_MAX_SOURCE_CHARACTERS_V1 = 8e3;
+var STATIC_PROJECT_SAFETY_CHECK_IDS_V1 = [
+  "allow-listed-source",
+  "no-personal-details",
+  "no-external-network",
+  "no-executable-markup",
+  "no-transmitting-forms",
+  "no-uploads-or-embeds",
+  "no-trackers-or-advertising",
+  "no-account-identifiers"
+];
+var DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+var IDENTIFIER_PATTERN = /^(?:account|approval|publication|snapshot)_[A-Za-z0-9_-]{20,128}$/u;
+var VERSION_PATTERN = /^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$/u;
+var RANDOM_SLUG_PATTERN = /^[A-Za-z0-9_-]{40,128}$/u;
+function validDate(value) {
+  return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function allSafetyChecksPresent(scan) {
+  if (!Array.isArray(scan.checks) || scan.checks.length !== STATIC_PROJECT_SAFETY_CHECK_IDS_V1.length) {
+    return false;
+  }
+  const supplied = new Set(scan.checks.map((check) => check.id));
+  return STATIC_PROJECT_SAFETY_CHECK_IDS_V1.every((id) => supplied.has(id)) && scan.checks.every((check) => check.passed === true);
+}
+function safeAdventureRender(value) {
+  const headings = ["Moonbase Missions", "Forest Rescue Plans", "Ocean Quest Board"];
+  const titles = ["Find the moon crystal", "Guide the lost firefly", "Map the coral garden"];
+  const days = ["Saturday", "Sunday", "School holiday"];
+  const messages = ["Choose a day", "Add a mission title", "Mission ready!"];
+  return headings.includes(value.heading) && Array.isArray(value.missions) && value.missions.length >= 1 && value.missions.length <= 3 && value.missions.every((mission2) => titles.includes(mission2.title) && days.includes(mission2.day)) && messages.includes(value.validationMessage) && value.savedAcrossRestart === true && value.accessibleSummaryEnabled === true;
+}
+function safeCreatureRender(value) {
+  return ["Moon Moth", "Cloud Cat", "Pebble Dragon"].includes(value.creature) && ["Resting", "Ready to play", "Snack time"].includes(value.status) && [5, 10, 15].includes(value.timerSeconds) && ["single", "cosy-grid", "wide-grid"].includes(value.layout) && value.reducedMotion === true;
+}
+function safeRobotRender(value) {
+  return ["scan", "hold-position", "return-to-base"].includes(value.command) && value.safetyConfirmed === true && [1, 2, 4].includes(value.telemetryRate) && ["line", "bars", "text-only"].includes(value.chartMode) && value.serialSimulation === true && ["SCANNING", "HOLDING", "RETURNING"].includes(value.state);
+}
+function validateStaticProjectSnapshot(value) {
+  const issues = [];
+  if (value.schemaVersion !== "1") issues.push("invalid-schema-version");
+  if (value.contractVersion !== STATIC_PROJECT_PUBLISHING_CONTRACT_VERSION_V1) {
+    issues.push("invalid-contract-version");
+  }
+  if (!IDENTIFIER_PATTERN.test(value.snapshotId) || !IDENTIFIER_PATTERN.test(value.subjectAccountId)) {
+    issues.push("invalid-identifier");
+  }
+  if (!value.moduleId.startsWith("junior-coder.") || value.moduleId !== `junior-coder.${value.moduleSlug}`) {
+    issues.push("invalid-module");
+  }
+  if (!VERSION_PATTERN.test(value.moduleVersion)) issues.push("invalid-version");
+  if (!DIGEST_PATTERN.test(value.sourceDigest)) issues.push("invalid-source-digest");
+  if (!DIGEST_PATTERN.test(value.snapshotDigest)) issues.push("invalid-snapshot-digest");
+  if (!Number.isInteger(value.sourceCharacterCount) || value.sourceCharacterCount < 1 || value.sourceCharacterCount > STATIC_PROJECT_MAX_SOURCE_CHARACTERS_V1) {
+    issues.push("invalid-source-size");
+  }
+  if (!Number.isInteger(value.assessmentScore) || value.assessmentScore < 80 || value.assessmentScore > 100) {
+    issues.push("assessment-score-incomplete");
+  }
+  if (value.mandatorySafetyPassed !== true) issues.push("mandatory-safety-missing");
+  if (value.scan?.passed !== true || value.scan?.scannerVersion !== STATIC_PROJECT_SCANNER_VERSION_V1) {
+    issues.push("scan-not-passed");
+  }
+  if (!value.scan || !allSafetyChecksPresent(value.scan)) issues.push("scan-checks-incomplete");
+  if (value.moduleSlug !== value.renderModel?.kind) issues.push("module-render-model-mismatch");
+  const renderSafe = value.renderModel?.kind === "adventure-mission-planner" ? safeAdventureRender(value.renderModel) : value.renderModel?.kind === "creature-care-dashboard" ? safeCreatureRender(value.renderModel) : value.renderModel?.kind === "robot-mission-control" ? safeRobotRender(value.renderModel) : false;
+  if (!renderSafe) issues.push("unsafe-render-model");
+  if (value.state !== "pending-review" || !validDate(value.createdAt)) issues.push("invalid-created-at");
+  return [...new Set(issues)];
+}
+function assertValidStaticProjectSnapshot(value) {
+  const issues = validateStaticProjectSnapshot(value);
+  if (issues.length > 0) throw new Error(`Invalid static project snapshot: ${issues.join(", ")}`);
+}
+function validateStaticProjectGuardianApproval(value) {
+  const issues = [];
+  if (value.schemaVersion !== "1") issues.push("invalid-schema-version");
+  if (!IDENTIFIER_PATTERN.test(value.approvalId) || !IDENTIFIER_PATTERN.test(value.snapshotId) || !IDENTIFIER_PATTERN.test(value.guardianActorAccountId)) {
+    issues.push("invalid-identifier");
+  }
+  if (!DIGEST_PATTERN.test(value.snapshotDigest)) issues.push("invalid-snapshot-digest");
+  if (value.statementVersion !== STATIC_PROJECT_APPROVAL_STATEMENT_VERSION_V1) {
+    issues.push("invalid-approval-statement");
+  }
+  if (!validDate(value.approvedAt)) issues.push("invalid-approved-at");
+  return [...new Set(issues)];
+}
+function assertValidStaticProjectGuardianApproval(value) {
+  const issues = validateStaticProjectGuardianApproval(value);
+  if (issues.length > 0) throw new Error(`Invalid static project approval: ${issues.join(", ")}`);
+}
+function validateStaticProjectPublication(value) {
+  const issues = [];
+  if (value.schemaVersion !== "1") issues.push("invalid-schema-version");
+  if (!IDENTIFIER_PATTERN.test(value.publicationId) || !IDENTIFIER_PATTERN.test(value.snapshotId) || !IDENTIFIER_PATTERN.test(value.approvalId)) {
+    issues.push("invalid-identifier");
+  }
+  if (!DIGEST_PATTERN.test(value.snapshotDigest)) issues.push("invalid-snapshot-digest");
+  if (!RANDOM_SLUG_PATTERN.test(value.randomSlug)) issues.push("invalid-random-slug");
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(value.publicUrl);
+  } catch {
+    parsedUrl = void 0;
+  }
+  if (!parsedUrl || parsedUrl.protocol !== "https:" || parsedUrl.username || parsedUrl.password) {
+    issues.push("invalid-public-url");
+  }
+  if (!parsedUrl?.pathname.endsWith(`/${value.randomSlug}`)) issues.push("public-url-slug-mismatch");
+  if (value.state !== "published") issues.push("published-state-required");
+  if (!validDate(value.publishedAt)) issues.push("invalid-published-at");
+  if (!validDate(value.expiresAt) || validDate(value.publishedAt) && Date.parse(value.expiresAt) <= Date.parse(value.publishedAt)) {
+    issues.push("invalid-publication-expiry");
+  }
+  if (value.renewedAt !== void 0 && !validDate(value.renewedAt) || value.unpublishedAt !== void 0 && !validDate(value.unpublishedAt)) {
+    issues.push("invalid-lifecycle-timestamp");
+  }
+  return [...new Set(issues)];
+}
+function assertValidStaticProjectPublication(value) {
+  const issues = validateStaticProjectPublication(value);
+  if (issues.length > 0) throw new Error(`Invalid static project publication: ${issues.join(", ")}`);
+}
+
 // src/rubric-validation.ts
 var DIMENSION_TOTALS = {
   structure: 20,
@@ -6630,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,
@@ -6650,14 +6941,32 @@ export {
   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,
   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,
-  validateMissionAuthoringBundle
+  validateMissionAuthoringBundle,
+  validateStaticProjectGuardianApproval,
+  validateStaticProjectPublication,
+  validateStaticProjectSnapshot
 };
 //# sourceMappingURL=index.js.map