@intellectif/lk-core 0.7.1 → 0.8.0

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { ScoredItem } from './scoring.js';
 export { AssessmentScore, AssessmentSectionInput, Band, CompositionPolicy, DEFAULT_PASS_THRESHOLD, PassFailureReason, RoundingMode, RoundingPolicy, SectionScore, classifyBand, composeAssessmentScore, computePassThreshold, evaluate, gte, roundGrade, score } from './scoring.js';
-import { m as ItemOutcome, A as ActivityData, L as LearnerResponse, V as ValidationError, C as CriterionScore, G as GradeRecord, r as ScoringResult, D as DeferredScoringPartial, F as FillInTheBlanksData, f as FillInTheBlanksLearnerResponse, M as MultipleChoiceData, o as MultipleChoiceLearnerResponse, W as WrittenResponseData, u as WrittenResponseLearnerResponse } from './activity-DARHcrz_.js';
-export { a as ActivityDataMap, b as ActivityFeedback, c as ActivityMedia, d as ActivityResult, e as ActivityType, B as BlankConfig, g as Grader, h as GraderKind, i as GraderUsage, j as GradingState, I as InlineCorrection, k as InteractionEvent, l as InteractionKind, n as LearnerResponseMap, p as MultipleChoiceOption, S as ScoringDetail, q as ScoringOutcome, T as TextMatchPolicy, s as TextMatchResult, t as ValidationResult, v as WrittenResponseRubric, w as WrittenResponseRubricCriterion, X as XAPIActor, x as XAPIConfig, y as XAPIContext, z as XAPIContextActivities, E as XAPIError, H as XAPIObject, J as XAPIResult, K as XAPIScore, N as XAPIStatement, O as XAPIVerbObject, P as levenshteinDistance, Q as matchText } from './activity-DARHcrz_.js';
-import { s as SequenceSlot, S as SequenceEntry, I as ItemGroup } from './index-yrUw7NzZ.js';
-export { B as BlankConfigSchema, F as FeedbackSchema, a as FillInTheBlanksDataSchema, b as ItemGroupSchema, M as MediaSchema, c as MediaUrlSchema, d as MultipleChoiceDataSchema, e as MultipleChoiceOptionSchema, R as RedactedActivity, f as RedactedBlankConfig, g as RedactedBlankConfigSchema, h as RedactedFillInTheBlanksData, i as RedactedFillInTheBlanksDataSchema, j as RedactedItemGroupSchema, k as RedactedMultipleChoiceData, l as RedactedMultipleChoiceDataSchema, m as RedactedMultipleChoiceOption, n as RedactedMultipleChoiceOptionSchema, o as RedactedStimulus, p as RedactedStimulusSchema, q as RedactedWrittenResponseData, r as RedactedWrittenResponseDataSchema, t as SequenceSlotGroup, u as Stimulus, v as StimulusKind, w as StimulusSchema, T as TextMatchPolicySchema, W as WrittenResponseDataSchema, x as WrittenResponseRubricCriterionSchema, y as WrittenResponseRubricSchema, z as fillInTheBlanksJsonSchema, A as itemGroupJsonSchema, C as jsonSchemaFor, D as multipleChoiceJsonSchema, E as stimulusJsonSchema, G as validateActivity, H as validateItemGroup, J as writtenResponseJsonSchema } from './index-yrUw7NzZ.js';
+import { m as ItemOutcome, A as ActivityData, L as LearnerResponse, V as ValidationError, C as CriterionScore, G as GradeRecord, N as NativeControlHint, c as ActivityMedia, r as ScoringResult, D as DeferredScoringPartial, F as FillInTheBlanksData, f as FillInTheBlanksLearnerResponse, M as MultipleChoiceData, o as MultipleChoiceLearnerResponse, W as WrittenResponseData, u as WrittenResponseLearnerResponse } from './activity-CPtJUBek.js';
+export { a as ActivityDataMap, b as ActivityFeedback, d as ActivityResult, e as ActivityType, B as BlankConfig, g as Grader, h as GraderKind, i as GraderUsage, j as GradingState, I as InlineCorrection, k as InteractionEvent, l as InteractionKind, n as LearnerResponseMap, p as MultipleChoiceOption, S as ScoringDetail, q as ScoringOutcome, T as TextMatchPolicy, s as TextMatchResult, t as ValidationResult, v as WrittenResponseRubric, w as WrittenResponseRubricCriterion, X as XAPIActor, x as XAPIConfig, y as XAPIContext, z as XAPIContextActivities, E as XAPIError, H as XAPIObject, J as XAPIResult, K as XAPIScore, O as XAPIStatement, P as XAPIVerbObject, Q as levenshteinDistance, R as matchText } from './activity-CPtJUBek.js';
+import { u as SequenceSlot, S as SequenceEntry, I as ItemGroup } from './index-Kc53zVgY.js';
+export { B as BlankConfigSchema, F as FeedbackSchema, a as FillInTheBlanksDataSchema, b as ItemGroupSchema, M as MediaPlaybackSchema, c as MediaSchema, d as MediaUrlSchema, e as MultipleChoiceDataSchema, f as MultipleChoiceOptionSchema, N as NativeControlHintSchema, R as RedactedActivity, g as RedactedBlankConfig, h as RedactedBlankConfigSchema, i as RedactedFillInTheBlanksData, j as RedactedFillInTheBlanksDataSchema, k as RedactedItemGroupSchema, l as RedactedMediaSchema, m as RedactedMultipleChoiceData, n as RedactedMultipleChoiceDataSchema, o as RedactedMultipleChoiceOption, p as RedactedMultipleChoiceOptionSchema, q as RedactedStimulus, r as RedactedStimulusSchema, s as RedactedWrittenResponseData, t as RedactedWrittenResponseDataSchema, v as SequenceSlotGroup, w as Stimulus, x as StimulusKind, y as StimulusSchema, T as TextMatchPolicySchema, W as WrittenResponseDataSchema, z as WrittenResponseRubricCriterionSchema, A as WrittenResponseRubricSchema, C as fillInTheBlanksJsonSchema, D as itemGroupJsonSchema, E as jsonSchemaFor, G as multipleChoiceJsonSchema, H as stimulusJsonSchema, J as validateActivity, K as validateItemGroup, L as writtenResponseJsonSchema } from './index-Kc53zVgY.js';
 import { z } from 'zod/v4';
 export { AnsweredStatementParams, CompletedStatementParams, SubmittedStatementParams, XAPIObjectParams, XAPIStatementParams, XAPIVerb, XAPIVerbKey, XAPI_VERB_DISPLAY, validateXAPIStatement, xAPIBuilder, xapiDefinitionFor } from './xapi.js';
 
@@ -53,6 +53,25 @@ interface AttemptPlanSlot {
         /** Fingerprint of the stimulus as served — a corrected passage changes the question. */
         stimulusHash: string;
     };
+    /**
+     * Play budgets in force for this slot when the attempt was planned.
+     *
+     * Frozen for the same reason `points` is: a budget decides the grade, so an
+     * author who edits `maxPlays: 2 → 4` mid-window must not be able to change
+     * what a past learner was held to. A group's stimulus budget repeats on every
+     * slot of the group, exactly as `group.stimulusHash` already does.
+     *
+     * Absent when the slot budgets nothing, which keeps the plan — and therefore
+     * `planHash` — byte-identical for every paper written before 0.8.0.
+     */
+    mediaBudgets?: MediaBudgetRef[];
+}
+/** A budgeted recording a slot presents, frozen as served. */
+interface MediaBudgetRef {
+    /** `slot:<slotId>` or `stimulus:<entryKey>`. */
+    key: string;
+    /** The `maxPlays` in force when the attempt was planned. */
+    maxPlays: number;
 }
 /** Everything needed to reproduce and re-grade one attempt. */
 interface AttemptPlan {
@@ -490,6 +509,155 @@ declare function flattenSequence<TItem extends {
     type: string;
 }>(entries: readonly SequenceEntry<TItem>[], options?: FlattenSequenceOptions): SequenceSlot<TItem>[];
 
+/**
+ * What one budgeted recording has cost the learner so far.
+ */
+interface MediaPlayLedgerEntry {
+    /**
+     * Plays consumed. A non-negative integer. It MAY exceed the budget: an
+     * invigilator override and a race the server resolved both legitimately
+     * produce that, and clamping here would hide it.
+     */
+    plays: number;
+    /**
+     * Where playback stood at the last report, in seconds.
+     *
+     * Restored on mount so a refresh RESUMES the play the learner already paid
+     * for instead of charging them again for it. It can only ever let them
+     * continue from where they were, never restart, because `seek` resolves to
+     * `'none'` under a budget.
+     */
+    at?: number;
+}
+/**
+ * The spent-play ledger for one attempt.
+ *
+ * Deliberately **not** part of `AttemptState`, for two reasons that both bite
+ * in production:
+ *
+ * 1. It is written on a different cadence. A play is charged *immediately*,
+ *    before audio is audible; answers are autosaved on a debounce. Batching a
+ *    payment with a debounced write is how a learner starts a third play and
+ *    hard-reloads inside the debounce window.
+ * 2. `restoreAttemptState` rebuilds its output field by field. A build that
+ *    predates this release would not merely fail to read a `mediaPlays` field —
+ *    it would write the snapshot back **without** it, erasing spent plays
+ *    across a staged rollout, at exactly the moment they matter.
+ *
+ * Bound to its paper by `planHash` for the same reason `AttemptState` is.
+ */
+interface MediaPlayLedger {
+    ledgerVersion: '1.0';
+    /** The `planHash` of the paper these counts were spent on. */
+    planHash: string;
+    /** Keyed by `slotMediaKey()` / `stimulusMediaKey()`. An absent key means nothing spent. */
+    entries: Record<string, MediaPlayLedgerEntry>;
+    /** ISO 8601, when the caller supplies one. The SDK reads no clock. */
+    savedAt?: string;
+}
+/**
+ * What the SDK asks the consumer to record, before a sample of audio is
+ * audible.
+ *
+ * `previousPlaysUsed` is what makes a compare-and-set possible: two tabs both
+ * seeded at 0 both claim 1, and only an atomic write can tell them apart.
+ */
+interface MediaPlayClaim {
+    /** `slot:…` / `stimulus:…`. */
+    key: string;
+    /** The count the client believes was already spent — the value to compare against. */
+    previousPlaysUsed: number;
+    /** The count the client is claiming: `previousPlaysUsed + 1`. */
+    playsUsed: number;
+    maxPlays: number;
+    playsRemaining: number;
+    /** Where the learner stood when the claim was made. Forensics; never identity. */
+    slotId: string;
+    index: number;
+    activityId?: string;
+}
+/** The consumer's authoritative answer to a {@link MediaPlayClaim}. */
+interface MediaPlayGrant {
+    /**
+     * The count AFTER the server's atomic write. A value greater than
+     * `maxPlays` refuses the play — which is how a second tab is caught.
+     */
+    playsUsed: number;
+}
+
+/**
+ * The authored-entry prefix of a slot id: `"3"` for both `"3"` and `"3.1"`.
+ *
+ * Safe because every slot id in a plan is produced by `flattenSequence`, and
+ * `keyOf` rejects a `.` in both an entry key and an item key — so the first
+ * `.` is always the group/item separator.
+ */
+declare function entryKeyOf(slotId: string): string;
+/** Budget key for an activity's OWN `data.media`. One budget per slot. */
+declare function slotMediaKey(slotId: string): string;
+/**
+ * Budget key for an item group's `stimulus.media`.
+ *
+ * Keyed by the ENTRY, not the slot: one recording serves every question in the
+ * group, so `"3.0"`…`"3.5"` share one budget. Keying by `slotId` would hand a
+ * six-question `maxPlays: 2` listening group twelve plays; keying by
+ * `stimulus.id` would collide across papers, which is the thing slot keys and
+ * `planHash` exist to prevent.
+ */
+declare function stimulusMediaKey(slotId: string): string;
+/** A playback policy with every default resolved. One derivation, used everywhere. */
+interface ResolvedPlaybackPolicy {
+    controls: 'native' | 'minimal';
+    /** `null` when the recording is unbudgeted. */
+    maxPlays: number | null;
+    seek: 'allow' | 'none';
+    rate: 'allow' | 'fixed';
+    nativeControlHints: readonly NativeControlHint[];
+}
+/**
+ * Resolves the defaults once, so the schema refinements, the plan and the
+ * renderer cannot drift apart about what a policy means.
+ *
+ * Absent `playback` resolves to exactly the SDK's pre-0.8.0 behaviour:
+ * `controls: 'native'`, no budget, free seeking, free speed, no hints.
+ */
+declare function resolvePlaybackPolicy(media: ActivityMedia): ResolvedPlaybackPolicy;
+/**
+ * Every budgeted recording a plan contains: budget key → the `maxPlays` that
+ * was frozen when the attempt was planned.
+ *
+ * Use it to build the storage rows an attempt needs, and to check a stored
+ * ledger against the paper it claims to belong to.
+ */
+declare function planMediaBudgets(plan: AttemptPlan): Record<string, number>;
+/**
+ * Validates a set of spent-play counts against the plan that budgeted them,
+ * and stamps the envelope.
+ *
+ * Validates on the way **in**: a play recorded against a recording the paper
+ * does not budget is a bug at the moment it is written, and discovering it
+ * when a learner tries to resume is discovering it far too late.
+ *
+ * @throws Error when a key is not budgeted by the plan, or a count is not a
+ *         non-negative integer, or a position is not a finite number.
+ */
+declare function serializeMediaPlayLedger(plan: AttemptPlan, entries: Readonly<Record<string, MediaPlayLedgerEntry>>, options?: {
+    savedAt?: string;
+}): MediaPlayLedger;
+/**
+ * Reopens a stored ledger against the paper it was spent on.
+ *
+ * Refuses a ledger from a different paper for the same reason
+ * `restoreAttemptState` does: budget keys are short and repeat across papers
+ * (`slot:0`, `stimulus:1`), so a ledger from last term's midterm would hold a
+ * learner to a budget from an exam they never sat, and look entirely plausible
+ * doing it.
+ *
+ * @throws Error on an unrecognised `ledgerVersion`, a `planHash` mismatch, or
+ *         anything `serializeMediaPlayLedger` refuses.
+ */
+declare function restoreMediaPlayLedger(plan: AttemptPlan, stored: MediaPlayLedger): MediaPlayLedger;
+
 /** ScoringResult without `passed` — the public `score()` / `evaluate()` fill that in. */
 type PartialScoringResult = Omit<ScoringResult, 'passed'>;
 /**
@@ -829,4 +997,4 @@ interface ThemeTokens {
     '--lk-transition-base': string;
 }
 
-export { ActivityData, ActivitySchemaError, type ActivityTypeDescriptor, type ActivityTypeInterop, type ActivityTypeScoring, type AttemptPlan, type AttemptPlanDrift, type AttemptPlanSlot, type AttemptProgress, type AttemptState, CriterionScore, DeferredScoringError, DeferredScoringPartial, type FieldPolicy, FillInTheBlanksData, FillInTheBlanksLearnerResponse, type FlattenSequenceOptions, type GradeFromRubricOptions, GradeRecord, ItemGroup, ItemOutcome, LearnerResponse, type MissingOutcomePolicy, MultipleChoiceData, MultipleChoiceLearnerResponse, type PartialScoringResult, type PlanAttemptOptions, type PlannableEntry, type RedactOptions, type RedactedActivityData, type RedactedItemGroup, RedactedScoringError, type RegisteredActivityTypeDescriptor, type ResponseDiffEntry, ScoredItem, ScoringResult, type SeededShuffleOptions, type Sensitivity, SequenceEntry, SequenceSlot, type ShuffleVersion, type ThemeTokens, UnknownActivityTypeError, ValidationError, WrittenResponseData, WrittenResponseLearnerResponse, type XAPIInteractionType, assertRedacted, assertRedactedItemGroup, canonicalJson, contentHash, countWords, defineActivityType, diffResponses, fillInTheBlanksType, fingerprint, flattenSequence, getActivityTypeDescriptor, gradeFromRubric, hasGrade, hashSeed, isItemGroup, multipleChoiceType, outcomeFromGrade, planAttempt, redact, redactItemGroup, registerActivityType, registeredActivityTypes, restoreAttemptState, scoredItemsFromPlan, seededShuffle, serializeAttemptState, verifyAttemptPlan, writtenResponseType };
+export { ActivityData, ActivityMedia, ActivitySchemaError, type ActivityTypeDescriptor, type ActivityTypeInterop, type ActivityTypeScoring, type AttemptPlan, type AttemptPlanDrift, type AttemptPlanSlot, type AttemptProgress, type AttemptState, CriterionScore, DeferredScoringError, DeferredScoringPartial, type FieldPolicy, FillInTheBlanksData, FillInTheBlanksLearnerResponse, type FlattenSequenceOptions, type GradeFromRubricOptions, GradeRecord, ItemGroup, ItemOutcome, LearnerResponse, type MediaBudgetRef, type MediaPlayClaim, type MediaPlayGrant, type MediaPlayLedger, type MediaPlayLedgerEntry, type MissingOutcomePolicy, MultipleChoiceData, MultipleChoiceLearnerResponse, type PartialScoringResult, type PlanAttemptOptions, type PlannableEntry, type RedactOptions, type RedactedActivityData, type RedactedItemGroup, RedactedScoringError, type RegisteredActivityTypeDescriptor, type ResolvedPlaybackPolicy, type ResponseDiffEntry, ScoredItem, ScoringResult, type SeededShuffleOptions, type Sensitivity, SequenceEntry, SequenceSlot, type ShuffleVersion, type ThemeTokens, UnknownActivityTypeError, ValidationError, WrittenResponseData, WrittenResponseLearnerResponse, type XAPIInteractionType, assertRedacted, assertRedactedItemGroup, canonicalJson, contentHash, countWords, defineActivityType, diffResponses, entryKeyOf, fillInTheBlanksType, fingerprint, flattenSequence, getActivityTypeDescriptor, gradeFromRubric, hasGrade, hashSeed, isItemGroup, multipleChoiceType, outcomeFromGrade, planAttempt, planMediaBudgets, redact, redactItemGroup, registerActivityType, registeredActivityTypes, resolvePlaybackPolicy, restoreAttemptState, restoreMediaPlayLedger, scoredItemsFromPlan, seededShuffle, serializeAttemptState, serializeMediaPlayLedger, slotMediaKey, stimulusMediaKey, verifyAttemptPlan, writtenResponseType };

package/dist/index.js

@@ -10,14 +10,14 @@ import {
   outcomeFromGrade,
   roundGrade,
   score
-} from "./chunk-NOBJYDOB.js";
+} from "./chunk-HTMRJ2SS.js";
 import {
   XAPIVerb,
   XAPI_VERB_DISPLAY,
   validateXAPIStatement,
   xAPIBuilder,
   xapiDefinitionFor
-} from "./chunk-2SQ75JTE.js";
+} from "./chunk-ZBCKQBAB.js";
 import {
   ItemGroupSchema,
   RedactedItemGroupSchema,
@@ -31,19 +31,23 @@ import {
   validateActivity,
   validateItemGroup,
   writtenResponseJsonSchema
-} from "./chunk-XL75ZZVM.js";
+} from "./chunk-H7L57ITR.js";
 import {
   ActivitySchemaError,
   BlankConfigSchema,
   DeferredScoringError,
   FeedbackSchema,
   FillInTheBlanksDataSchema,
+  MEDIA_FIELD_POLICY,
+  MediaPlaybackSchema,
   MediaSchema,
   MediaUrlSchema,
   MultipleChoiceDataSchema,
   MultipleChoiceOptionSchema,
+  NativeControlHintSchema,
   RedactedBlankConfigSchema,
   RedactedFillInTheBlanksDataSchema,
+  RedactedMediaSchema,
   RedactedMultipleChoiceDataSchema,
   RedactedMultipleChoiceOptionSchema,
   RedactedScoringError,
@@ -63,7 +67,7 @@ import {
   registerActivityType,
   registeredActivityTypes,
   writtenResponseType
-} from "./chunk-YCXIHFLG.js";
+} from "./chunk-OJXTXOUA.js";
 
 // src/content-hash.ts
 function canonicalJson(value, seen = /* @__PURE__ */ new Set()) {
@@ -228,6 +232,99 @@ function flattenSequence(entries, options = {}) {
   return slots;
 }
 
+// src/media-budget.ts
+function entryKeyOf(slotId) {
+  const dot = slotId.indexOf(".");
+  return dot === -1 ? slotId : slotId.slice(0, dot);
+}
+function slotMediaKey(slotId) {
+  return `slot:${slotId}`;
+}
+function stimulusMediaKey(slotId) {
+  return `stimulus:${entryKeyOf(slotId)}`;
+}
+function resolvePlaybackPolicy(media) {
+  const p = media.playback;
+  const budgeted = typeof p?.maxPlays === "number";
+  const seek = p?.seek ?? (budgeted ? "none" : "allow");
+  const rate = p?.rate ?? "allow";
+  const controls = p?.controls ?? (budgeted || seek === "none" || rate === "fixed" ? "minimal" : "native");
+  return {
+    controls,
+    maxPlays: budgeted ? p?.maxPlays : null,
+    seek,
+    rate,
+    nativeControlHints: p?.nativeControlHints ?? []
+  };
+}
+function planMediaBudgets(plan) {
+  const out = {};
+  for (const slot of plan.slots) {
+    for (const budget of slot.mediaBudgets ?? []) {
+      out[budget.key] = budget.maxPlays;
+    }
+  }
+  return out;
+}
+function assertEntry(key, entry) {
+  if (entry === null || typeof entry !== "object" || !Number.isInteger(entry.plays) || entry.plays < 0) {
+    throw new Error(
+      `serializeMediaPlayLedger: play count for ${JSON.stringify(key)} is ${JSON.stringify(entry?.plays)}. A count must be a non-negative integer; Number(a NULL column) is the usual cause.`
+    );
+  }
+  if (entry.at !== void 0 && (!Number.isFinite(entry.at) || entry.at < 0)) {
+    throw new Error(
+      `serializeMediaPlayLedger: position for ${JSON.stringify(key)} is ${JSON.stringify(entry.at)}. A position must be a finite number of seconds >= 0.`
+    );
+  }
+}
+function serializeMediaPlayLedger(plan, entries, options = {}) {
+  if (entries === null || typeof entries !== "object") {
+    throw new Error("serializeMediaPlayLedger: entries must be an object keyed by media key.");
+  }
+  const budgets = planMediaBudgets(plan);
+  const out = {};
+  for (const key of Object.keys(entries)) {
+    if (!Object.hasOwn(budgets, key)) {
+      throw new Error(
+        `serializeMediaPlayLedger: media play recorded against a recording the plan does not budget: ${JSON.stringify(key)}. Keys come from slotMediaKey() / stimulusMediaKey(); a key that belongs to no budgeted media means the client and the plan disagree about which paper this is.`
+      );
+    }
+    const entry = entries[key];
+    assertEntry(key, entry);
+    out[key] = { plays: entry.plays, ...entry.at !== void 0 ? { at: entry.at } : {} };
+  }
+  return {
+    ledgerVersion: "1.0",
+    planHash: plan.planHash,
+    entries: out,
+    ...options.savedAt !== void 0 ? { savedAt: options.savedAt } : {}
+  };
+}
+function restoreMediaPlayLedger(plan, stored) {
+  if (stored === null || typeof stored !== "object") {
+    throw new Error("restoreMediaPlayLedger: the stored ledger is not an object.");
+  }
+  if (stored.ledgerVersion !== "1.0") {
+    throw new Error(
+      `restoreMediaPlayLedger: unsupported ledgerVersion ${JSON.stringify(stored.ledgerVersion)}. This build understands "1.0"; a newer ledger must be migrated before it is restored.`
+    );
+  }
+  if (stored.entries === null || typeof stored.entries !== "object") {
+    throw new Error(
+      "restoreMediaPlayLedger: the ledger carries no entries object (a NULL column, or a partially written row)."
+    );
+  }
+  if (stored.planHash !== plan.planHash) {
+    throw new Error(
+      `restoreMediaPlayLedger: this ledger belongs to a different paper (ledger ${stored.planHash}, plan ${plan.planHash}). Restoring it would hold the learner to a play budget from an exam they never sat.`
+    );
+  }
+  return serializeMediaPlayLedger(plan, stored.entries, {
+    ...stored.savedAt !== void 0 ? { savedAt: stored.savedAt } : {}
+  });
+}
+
 // src/attempt-plan.ts
 function contentOf(activity) {
   if (!Object.hasOwn(activity, "slotKey")) {
@@ -236,12 +333,50 @@ function contentOf(activity) {
   const { slotKey: _slotKey, ...content } = activity;
   return content;
 }
+function mediaBudgetsOf(slot) {
+  const budgets = [];
+  const own = slot.activity.media;
+  if (own !== void 0) {
+    const maxPlays = resolvePlaybackPolicy(own).maxPlays;
+    if (maxPlays !== null) {
+      budgets.push({ key: slotMediaKey(slot.slotId), maxPlays });
+    }
+  }
+  const stimulusMedia = slot.group?.stimulus.media;
+  if (stimulusMedia !== void 0) {
+    const maxPlays = resolvePlaybackPolicy(stimulusMedia).maxPlays;
+    if (maxPlays !== null) {
+      budgets.push({ key: stimulusMediaKey(slot.slotId), maxPlays });
+    }
+  }
+  return budgets.length > 0 ? budgets : void 0;
+}
+function assertNoSplitBudgets(slots) {
+  const keysByUrl = /* @__PURE__ */ new Map();
+  for (const slot of slots) {
+    const own = slot.activity.media;
+    if (own === void 0 || resolvePlaybackPolicy(own).maxPlays === null) {
+      continue;
+    }
+    const keys = keysByUrl.get(own.url) ?? [];
+    keys.push(slotMediaKey(slot.slotId));
+    keysByUrl.set(own.url, keys);
+  }
+  for (const [url, keys] of keysByUrl) {
+    if (keys.length > 1) {
+      throw new Error(
+        `planAttempt: media ${JSON.stringify(url)} is budgeted under ${keys.length} separate keys (${keys.join(", ")}), so one recording grants ${keys.length} \xD7 maxPlays. Put the questions that share a recording in an item group \u2014 a group's stimulus is one recording with one budget.`
+      );
+    }
+  }
+}
 function planSlot(slot, points) {
   if (!Number.isFinite(points) || points < 0) {
     throw new Error(
       `planAttempt: slot "${slot.slotId}" resolved to ${String(points)} points. Points must be a finite, non-negative number, or the paper has no defensible total.`
     );
   }
+  const mediaBudgets = mediaBudgetsOf(slot);
   return {
     slotId: slot.slotId,
     index: slot.index,
@@ -255,7 +390,8 @@ function planSlot(slot, points) {
         ...slot.group.title !== void 0 ? { title: slot.group.title } : {},
         stimulusHash: contentHash(slot.group.stimulus)
       }
-    } : {}
+    } : {},
+    ...mediaBudgets !== void 0 ? { mediaBudgets } : {}
   };
 }
 function planAttempt(entries, options = {}) {
@@ -264,6 +400,7 @@ function planAttempt(entries, options = {}) {
     ...shuffleEntries !== void 0 ? { shuffleEntries } : {},
     ...seed !== void 0 ? { seed } : {}
   });
+  assertNoSplitBudgets(slots);
   const planned = slots.map((slot) => planSlot(slot, points?.(slot) ?? 1));
   const totalPoints = planned.reduce((sum, slot) => sum + slot.points, 0);
   return {
@@ -562,7 +699,7 @@ var STIMULUS_FIELD_POLICY = {
   title: "public",
   body: "public",
   bodyHtml: "public",
-  media: "public",
+  media: MEDIA_FIELD_POLICY,
   locale: "public",
   attribution: "public",
   transcript: "author-only"
@@ -654,13 +791,16 @@ export {
   FeedbackSchema,
   FillInTheBlanksDataSchema,
   ItemGroupSchema,
+  MediaPlaybackSchema,
   MediaSchema,
   MediaUrlSchema,
   MultipleChoiceDataSchema,
   MultipleChoiceOptionSchema,
+  NativeControlHintSchema,
   RedactedBlankConfigSchema,
   RedactedFillInTheBlanksDataSchema,
   RedactedItemGroupSchema,
+  RedactedMediaSchema,
   RedactedMultipleChoiceDataSchema,
   RedactedMultipleChoiceOptionSchema,
   RedactedScoringError,
@@ -684,6 +824,7 @@ export {
   countWords,
   defineActivityType,
   diffResponses,
+  entryKeyOf,
   evaluate,
   fillInTheBlanksJsonSchema,
   fillInTheBlanksType,
@@ -703,17 +844,23 @@ export {
   multipleChoiceType,
   outcomeFromGrade,
   planAttempt,
+  planMediaBudgets,
   redact,
   redactItemGroup,
   registerActivityType,
   registeredActivityTypes,
+  resolvePlaybackPolicy,
   restoreAttemptState,
+  restoreMediaPlayLedger,
   roundGrade,
   score,
   scoredItemsFromPlan,
   seededShuffle,
   serializeAttemptState,
+  serializeMediaPlayLedger,
+  slotMediaKey,
   stimulusJsonSchema,
+  stimulusMediaKey,
   validateActivity,
   validateItemGroup,
   validateXAPIStatement,