@pie-players/pie-players-shared 1.0.0-beta.8 → 1.0.0-beta.9

package/README.md

@@ -2,7 +2,7 @@
 
 Shared runtime utilities for the `@pie-players/*` player suite: the element
 loader, PIE config and session helpers, markup security, i18n, and the
-formative, timed-media and media contracts. For framework code and host
+item session control, timed-media and media contracts. For framework code and host
 integrations that need the helpers the player packages use.
 
 ## Public Exports
@@ -23,7 +23,7 @@ The subpaths below are the package's `exports`; nothing else is importable.
 | `/security/private-hosts` | `isPrivateHostname` and `isCloudMetadataHostname`, the host classification for a URL a server fetches on someone else's behalf. Node-safe: it loads none of the markup sanitizers |
 | `/object` | `mergeObjectsIgnoringNullUndefined`, `cloneDeep`, `isPlainRecord` |
 | `/types` | The shared types: item, passage, section and session entities, PIE models and controllers, accessibility catalogs, and the [media vocabulary](#media-validation) |
-| `/formative` | [Formative delivery](#formative-delivery) |
+| `/item-session-control` | [Item session control](#item-session-control) |
 | `/timed-media` | [Timed media](#timed-media) |
 | `/media` | [Media validation](#media-validation) |
 | `/pie` | PIE runtime utilities: config helpers, bundle initialization, `ItemController` and the item session contract, session commit and snapshots, authoring helpers, math renderer setup, instrumentation event maps ([PIE utilities](src/pie/README.md)) |
@@ -40,9 +40,9 @@ The subpaths below are the package's `exports`; nothing else is importable.
 | `/ui/fontawesome` | The FontAwesome `<nds-icon-button>` glyphs need: the one FA Free pin, Pro detection, the `<head>` and shadow-root installs, and the glyph weight. The assessment toolkit, the section player and `@pie-players/pie-tool-tts-inline` use it |
 | `/tools/term-lookup` | Term normalization and the lookup session the dictionary tools share; the host supplies the endpoint or a resolver |
 
-## Formative Delivery
+## Item Session Control
 
-`@pie-players/pie-players-shared/formative` holds the policy resolution, outcome
+`@pie-players/pie-players-shared/item-session-control` holds the policy resolution, outcome
 aggregation, Try-state reducer, item view, and mastery rollup that
 `pie-section-player` drives. It is pure (no DOM, no timers, no element
 registry), so it is testable without a browser and importable by an adapter that
@@ -50,18 +50,18 @@ has no player.
 
 ```ts
 import {
-  aggregateFormativeOutcome,
-  resolveFormativePolicy,
-  resolveFormativeItemView,
-  rollupFormativeMastery,
-} from "@pie-players/pie-players-shared/formative";
+  aggregateTryOutcome,
+  resolveItemSessionControl,
+  resolveItemTryView,
+  rollupMastery,
+} from "@pie-players/pie-players-shared/item-session-control";
 ```
 
-The authored half, `FormativeDeliveryPolicy` on `AssessmentSection` and
-`FormativeItemPolicy` on `AssessmentItemRef`, is re-exported from the package
+The authored half, `ItemSessionControlPolicy` on `AssessmentSection` and
+`AssessmentItemRef`, is re-exported from the package
 root and from `/types`, beside the section types it annotates.
 
-The contract is [`docs/prds/formative-delivery-contract.md`](../../docs/prds/formative-delivery-contract.md),
+The contract is [`docs/prds/item-session-control-contract.md`](../../docs/prds/item-session-control-contract.md),
 including the QTI 3 mapping and why PIE says **Try** rather than "attempt".
 
 ## Timed Media
@@ -94,7 +94,7 @@ re-exported from the package root and from `/types`, beside the section types it
 annotates.
 
 The contract is [`docs/prds/timed-media-section-contract.md`](../../docs/prds/timed-media-section-contract.md),
-including why cue gate conditions name the formative vocabulary and why an
+including why cue gate conditions name the Try vocabulary and why an
 unenforceable policy degrades to advisory rather than failing closed.
 
 ## Media Validation

package/dist/i18n/messages/en-US.d.ts

@@ -109,16 +109,16 @@ declare const enUS: {
             loadFailed: string;
             restoreFailed: string;
         };
-        /** Formative delivery: check-answer control and its outcome announcements. */
-        formative: {
-            checkAnswer: string;
+        /** Item session control: check-answer control and its outcome announcements. */
+        check: {
+            answer: string;
             tryAgain: string;
             answerRecorded: string;
             correct: string;
             partlyCorrect: string;
             notCorrect: string;
             notAutoScored: string;
-            checkFailed: string;
+            failed: string;
             /**
              * Appended after the outcome, so the announcement reads
              * "Not correct. 2 tries left." Kept a separate plural group rather than

package/dist/i18n/messages/en-US.js

@@ -109,16 +109,16 @@ const enUS = {
             loadFailed: "The assessment could not be loaded. Try again.",
             restoreFailed: "Your saved answers for this section could not be restored. Try again.",
         },
-        /** Formative delivery: check-answer control and its outcome announcements. */
-        formative: {
-            checkAnswer: "Check answer",
+        /** Item session control: check-answer control and its outcome announcements. */
+        check: {
+            answer: "Check answer",
             tryAgain: "Try again",
             answerRecorded: "Answer recorded.",
             correct: "Correct.",
             partlyCorrect: "Partly correct.",
             notCorrect: "Not correct.",
             notAutoScored: "Answer recorded. This question is not scored automatically.",
-            checkFailed: "This question could not be checked. Try again.",
+            failed: "This question could not be checked. Try again.",
             /**
              * Appended after the outcome, so the announcement reads
              * "Not correct. 2 tries left." Kept a separate plural group rather than

package/dist/i18n/types.d.ts

@@ -57,7 +57,7 @@ type PluralCategoryKey = keyof PluralTranslation;
  * Dot-notation keys of a catalog shape.
  *
  * A plural group terminates the path at the group itself: `plural()` is called
- * with `player.formative.triesLeft`, never with `…triesLeft.other`. A group is
+ * with `player.check.triesLeft`, never with `…triesLeft.other`. A group is
  * recognized by every one of its keys being a CLDR plural category — the
  * containment has to run this way round, because a group carrying only
  * `one`/`other` does not contain the whole category union.

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export * from "./security/index.js";
 export * from "./loaders/index.js";
 export * from "./object/index.js";
 export * from "./pie/index.js";
-export type { AssessmentEntity, AssessmentItemRef, AssessmentSection, AdvancedItemConfig, ConfigEntity, ConfigResource, Env, FormativeDeliveryPolicy, FormativeItemPolicy, TimedMediaSectionData, ItemConfig, ItemEntity, ItemSession, OutcomeResponse, PassageEntity, PieController, PieContent, PieDefaultModel, PieItemElement, PieModel, PieUpdateSession, ReferencedItemEntity, ReferencedPassageEntity, RubricBlock, TestPart, } from "./types/index.js";
+export type { AssessmentEntity, AssessmentItemRef, AssessmentSection, AdvancedItemConfig, ConfigEntity, ConfigResource, Env, ItemSessionControlPolicy, TimedMediaSectionData, ItemConfig, ItemEntity, ItemSession, OutcomeResponse, PassageEntity, PieController, PieContent, PieDefaultModel, PieItemElement, PieModel, PieUpdateSession, ReferencedItemEntity, ReferencedPassageEntity, RubricBlock, TestPart, } from "./types/index.js";
 export { editorPostFix } from "./types/index.js";
 export * from "./ui/attribute-coercion.js";
 export * from "./ui/content-styles.js";

package/dist/item-session-control/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Item session control: Try state, feedback reveal, and section mastery.
+ *
+ * Pure and Node-safe by design — no DOM, no timers, no element registry — so
+ * the contract is testable without a browser and an adapter can import it
+ * without pulling in a player. Everything that touches the DOM stays in
+ * `@pie-players/pie-section-player`.
+ *
+ * Contract: `docs/prds/item-session-control-contract.md`.
+ */
+export type { TryAction, TryCorrectness, ItemSessionControlPolicy, FeedbackEnvOverride, FeedbackReveal, ItemTryState, ItemTryView, MasteryRollup, FeedbackRevealTiming, ScoredElementOutcome, TrySectionProjection, TrySectionSlice, TryLimit, TryOutcome, ResolvedItemSessionControlPolicy, } from "./types.js";
+export { ITEM_SESSION_CONTROL_DEFAULTS, isItemSessionControlEnabledInSection, resolveItemSessionControls, resolveItemSessionControl, } from "./policy.js";
+export { aggregateTryOutcome } from "./outcome.js";
+export { ITEM_TRY_STATE_VERSION, createItemTryState, hideItemFeedback, recordTry, resolveItemTryView, retryItem, revealItemFeedback, } from "./state.js";
+export { MASTERY_ROLLUP_VERSION, rollupMastery } from "./mastery.js";
+export { TRY_SLICE_VERSION, normalizeTrySectionSlice, toTrySectionSlice, } from "./session.js";

package/dist/item-session-control/index.js

@@ -0,0 +1,5 @@
+export { ITEM_SESSION_CONTROL_DEFAULTS, isItemSessionControlEnabledInSection, resolveItemSessionControls, resolveItemSessionControl, } from "./policy.js";
+export { aggregateTryOutcome } from "./outcome.js";
+export { ITEM_TRY_STATE_VERSION, createItemTryState, hideItemFeedback, recordTry, resolveItemTryView, retryItem, revealItemFeedback, } from "./state.js";
+export { MASTERY_ROLLUP_VERSION, rollupMastery } from "./mastery.js";
+export { TRY_SLICE_VERSION, normalizeTrySectionSlice, toTrySectionSlice, } from "./session.js";

package/dist/{formative → item-session-control}/mastery.d.ts

@@ -1,5 +1,5 @@
-import type { FormativeItemState, FormativeMasteryRollup } from "./types.js";
-export declare const FORMATIVE_MASTERY_VERSION: 1;
+import type { ItemTryState, MasteryRollup } from "./types.js";
+export declare const MASTERY_ROLLUP_VERSION: 1;
 /**
  * Roll Try outcomes up to the section.
  *
@@ -10,7 +10,7 @@ export declare const FORMATIVE_MASTERY_VERSION: 1;
  * excluded: nothing yet says it cannot be scored, so it keeps the section from
  * reading as complete after one correct answer.
  */
-export declare function rollupFormativeMastery(args: {
+export declare function rollupMastery(args: {
     itemIdentifiers: readonly string[];
-    states: Record<string, FormativeItemState>;
-}): FormativeMasteryRollup;
+    states: Record<string, ItemTryState>;
+}): MasteryRollup;

package/dist/{formative → item-session-control}/mastery.js

@@ -1,4 +1,4 @@
-export const FORMATIVE_MASTERY_VERSION = 1;
+export const MASTERY_ROLLUP_VERSION = 1;
 /**
  * Roll Try outcomes up to the section.
  *
@@ -9,7 +9,7 @@ export const FORMATIVE_MASTERY_VERSION = 1;
  * excluded: nothing yet says it cannot be scored, so it keeps the section from
  * reading as complete after one correct answer.
  */
-export function rollupFormativeMastery(args) {
+export function rollupMastery(args) {
     const identifiers = args.itemIdentifiers ?? [];
     const totalItems = identifiers.length;
     let notScorableItems = 0;
@@ -31,7 +31,7 @@ export function rollupFormativeMastery(args) {
     }
     const scorableItems = Math.max(0, totalItems - notScorableItems);
     return {
-        version: FORMATIVE_MASTERY_VERSION,
+        version: MASTERY_ROLLUP_VERSION,
         totalItems,
         scorableItems,
         masteredItems,

package/dist/{formative → item-session-control}/outcome.d.ts

@@ -1,10 +1,10 @@
-import type { FormativeScoredOutcome, FormativeTryOutcome } from "./types.js";
+import type { ScoredElementOutcome, TryOutcome } from "./types.js";
 /**
  * Reduce the array `pie-item-player.provideScore()` returns to one Try outcome.
  *
  * The aggregation mirrors the policy the persisted API scoring path already
  * documents (`docs/item-player/scoring-and-rubrics.md`), so a browser-derived
- * formative result and a server-derived score do not disagree about what a
+ * Try result and a server-derived score do not disagree about what a
  * multi-element item is worth:
  *
  * - one scored outcome: `points = score`, `max = max ?? 1`;
@@ -16,4 +16,4 @@ import type { FormativeScoredOutcome, FormativeTryOutcome } from "./types.js";
  * those slots count toward `totalElementCount` and not toward
  * `scoredElementCount`.
  */
-export declare function aggregateFormativeOutcome(outcomes: ReadonlyArray<FormativeScoredOutcome | null | undefined> | null): FormativeTryOutcome;
+export declare function aggregateTryOutcome(outcomes: ReadonlyArray<ScoredElementOutcome | null | undefined> | null): TryOutcome;

package/dist/{formative → item-session-control}/outcome.js

@@ -39,7 +39,7 @@ function classify(points, max) {
  *
  * The aggregation mirrors the policy the persisted API scoring path already
  * documents (`docs/item-player/scoring-and-rubrics.md`), so a browser-derived
- * formative result and a server-derived score do not disagree about what a
+ * Try result and a server-derived score do not disagree about what a
  * multi-element item is worth:
  *
  * - one scored outcome: `points = score`, `max = max ?? 1`;
@@ -51,7 +51,7 @@ function classify(points, max) {
  * those slots count toward `totalElementCount` and not toward
  * `scoredElementCount`.
  */
-export function aggregateFormativeOutcome(outcomes) {
+export function aggregateTryOutcome(outcomes) {
     const all = Array.isArray(outcomes) ? outcomes : [];
     const scored = all.filter(isScored);
     const totalElementCount = all.length;

package/dist/{formative → item-session-control}/policy.d.ts

@@ -1,13 +1,13 @@
-import type { FormativeDeliveryPolicy, FormativeItemPolicy, ResolvedFormativePolicy } from "./types.js";
+import type { ItemSessionControlPolicy, ResolvedItemSessionControlPolicy } from "./types.js";
 /**
  * Built-in defaults. `enabled: false` is what makes this contract invisible to
- * every section authored before it: an absent `formative` field resolves to a
+ * every section authored before it: an absent `itemSessionControl` field resolves to a
  * disabled policy, and a disabled policy produces no state, no projection and
  * no control.
  *
  * `maxTries: 1` matches QTI 3's `qti-item-session-control@max-attempts` default.
  */
-export declare const FORMATIVE_POLICY_DEFAULTS: ResolvedFormativePolicy;
+export declare const ITEM_SESSION_CONTROL_DEFAULTS: ResolvedItemSessionControlPolicy;
 /**
  * Merge built-in defaults, the section policy, and one item ref's override, in
  * that order. Each field overrides independently, which is the order QTI 3 uses
@@ -17,21 +17,21 @@ export declare const FORMATIVE_POLICY_DEFAULTS: ResolvedFormativePolicy;
  * section: authored policy is host-supplied data, and a typo in one field should
  * not cost the learner the whole item.
  */
-export declare function resolveFormativePolicy(sectionPolicy?: FormativeDeliveryPolicy | null, itemPolicy?: FormativeItemPolicy | null): ResolvedFormativePolicy;
+export declare function resolveItemSessionControl(sectionPolicy?: ItemSessionControlPolicy | null, itemPolicy?: ItemSessionControlPolicy | null): ResolvedItemSessionControlPolicy;
 /**
  * Resolve one policy per item in section order.
  *
  * Keyed by the identifier the caller supplies, which in the section runtime is
  * the canonical item id — the same key `itemSessions` and the completion map
- * use, so a formative state and an item session are always addressable by one
+ * use, so Try state and an item session are always addressable by one
  * id.
  */
-export declare function resolveFormativePolicies(args: {
-    sectionPolicy?: FormativeDeliveryPolicy | null;
+export declare function resolveItemSessionControls(args: {
+    sectionPolicy?: ItemSessionControlPolicy | null;
     items: ReadonlyArray<{
         identifier: string;
-        policy?: FormativeItemPolicy | null;
+        policy?: ItemSessionControlPolicy | null;
     }>;
-}): Record<string, ResolvedFormativePolicy>;
-/** True when at least one item in the section delivers formatively. */
-export declare function isFormativeSectionEnabled(policies: Record<string, ResolvedFormativePolicy>): boolean;
+}): Record<string, ResolvedItemSessionControlPolicy>;
+/** True when at least one item in the section enables item session control. */
+export declare function isItemSessionControlEnabledInSection(policies: Record<string, ResolvedItemSessionControlPolicy>): boolean;

package/dist/{formative → item-session-control}/policy.js

@@ -1,12 +1,12 @@
 /**
  * Built-in defaults. `enabled: false` is what makes this contract invisible to
- * every section authored before it: an absent `formative` field resolves to a
+ * every section authored before it: an absent `itemSessionControl` field resolves to a
  * disabled policy, and a disabled policy produces no state, no projection and
  * no control.
  *
  * `maxTries: 1` matches QTI 3's `qti-item-session-control@max-attempts` default.
  */
-export const FORMATIVE_POLICY_DEFAULTS = {
+export const ITEM_SESSION_CONTROL_DEFAULTS = {
     enabled: false,
     maxTries: 1,
     feedback: "correctness",
@@ -40,21 +40,21 @@ function normalizeRevealTiming(value) {
  * section: authored policy is host-supplied data, and a typo in one field should
  * not cost the learner the whole item.
  */
-export function resolveFormativePolicy(sectionPolicy, itemPolicy) {
+export function resolveItemSessionControl(sectionPolicy, itemPolicy) {
     const enabled = typeof itemPolicy?.enabled === "boolean"
         ? itemPolicy.enabled
         : typeof sectionPolicy?.enabled === "boolean"
             ? sectionPolicy.enabled
-            : FORMATIVE_POLICY_DEFAULTS.enabled;
+            : ITEM_SESSION_CONTROL_DEFAULTS.enabled;
     const maxTries = normalizeTryLimit(itemPolicy?.maxTries) ??
         normalizeTryLimit(sectionPolicy?.maxTries) ??
-        FORMATIVE_POLICY_DEFAULTS.maxTries;
+        ITEM_SESSION_CONTROL_DEFAULTS.maxTries;
     const feedback = normalizeFeedback(itemPolicy?.feedback) ??
         normalizeFeedback(sectionPolicy?.feedback) ??
-        FORMATIVE_POLICY_DEFAULTS.feedback;
+        ITEM_SESSION_CONTROL_DEFAULTS.feedback;
     const requestedRevealOn = normalizeRevealTiming(itemPolicy?.revealOn) ??
         normalizeRevealTiming(sectionPolicy?.revealOn) ??
-        FORMATIVE_POLICY_DEFAULTS.revealOn;
+        ITEM_SESSION_CONTROL_DEFAULTS.revealOn;
     // `"on-final-try"` has no referent under unlimited Tries — there is no final
     // Try to reveal on — so it resolves to the only reading that keeps feedback
     // reachable.
@@ -68,19 +68,19 @@ export function resolveFormativePolicy(sectionPolicy, itemPolicy) {
  *
  * Keyed by the identifier the caller supplies, which in the section runtime is
  * the canonical item id — the same key `itemSessions` and the completion map
- * use, so a formative state and an item session are always addressable by one
+ * use, so Try state and an item session are always addressable by one
  * id.
  */
-export function resolveFormativePolicies(args) {
+export function resolveItemSessionControls(args) {
     const resolved = {};
     for (const item of args.items) {
         if (!item?.identifier)
             continue;
-        resolved[item.identifier] = resolveFormativePolicy(args.sectionPolicy, item.policy);
+        resolved[item.identifier] = resolveItemSessionControl(args.sectionPolicy, item.policy);
     }
     return resolved;
 }
-/** True when at least one item in the section delivers formatively. */
-export function isFormativeSectionEnabled(policies) {
+/** True when at least one item in the section enables item session control. */
+export function isItemSessionControlEnabledInSection(policies) {
     return Object.values(policies).some((policy) => policy.enabled);
 }

package/dist/item-session-control/session.d.ts

@@ -0,0 +1,19 @@
+import type { ItemTryState, TrySectionSlice } from "./types.js";
+export declare const TRY_SLICE_VERSION: 1;
+export declare function toTrySectionSlice(states: Record<string, ItemTryState>): TrySectionSlice;
+/**
+ * Validate a persisted slice against the section it is being restored into.
+ *
+ * Returns `null` for a slice this build cannot read, which the caller treats as
+ * "start Try state clean". Rejection is deliberately narrow: it discards
+ * Try progress and nothing else, so a version bump here never costs a
+ * learner their responses — item sessions travel in the same snapshot and are
+ * normalized separately.
+ *
+ * An absent slice is `null` too, and indistinguishable from a save made
+ * without Try state, which is what keeps existing snapshots valid.
+ */
+export declare function normalizeTrySectionSlice(args: {
+    slice: unknown;
+    allowedItemIdentifiers: readonly string[];
+}): Record<string, ItemTryState> | null;

package/dist/{formative → item-session-control}/session.js

@@ -1,5 +1,5 @@
-import { FORMATIVE_ITEM_STATE_VERSION } from "./state.js";
-export const FORMATIVE_SLICE_VERSION = 1;
+import { ITEM_TRY_STATE_VERSION } from "./state.js";
+export const TRY_SLICE_VERSION = 1;
 const CORRECTNESS_VALUES = [
     "correct",
     "partial",
@@ -54,14 +54,14 @@ function normalizeItemState(itemIdentifier, value) {
     if (!value || typeof value !== "object")
         return null;
     const raw = value;
-    if (raw.version !== FORMATIVE_ITEM_STATE_VERSION)
+    if (raw.version !== ITEM_TRY_STATE_VERSION)
         return null;
     const tryCount = readNonNegativeInteger(raw.tryCount);
     if (tryCount === undefined)
         return null;
     const firstCorrectTry = readNonNegativeInteger(raw.firstCorrectTry);
     return {
-        version: FORMATIVE_ITEM_STATE_VERSION,
+        version: ITEM_TRY_STATE_VERSION,
         itemIdentifier,
         tryCount,
         revealed: raw.revealed === true,
@@ -72,9 +72,9 @@ function normalizeItemState(itemIdentifier, value) {
         revealOverride: normalizeRevealOverride(raw.revealOverride),
     };
 }
-export function toFormativeSectionSlice(states) {
+export function toTrySectionSlice(states) {
     return {
-        version: FORMATIVE_SLICE_VERSION,
+        version: TRY_SLICE_VERSION,
         items: { ...states },
     };
 }
@@ -82,20 +82,20 @@ export function toFormativeSectionSlice(states) {
  * Validate a persisted slice against the section it is being restored into.
  *
  * Returns `null` for a slice this build cannot read, which the caller treats as
- * "start formative state clean". Rejection is deliberately narrow: it discards
- * formative progress and nothing else, so a version bump here never costs a
+ * "start Try state clean". Rejection is deliberately narrow: it discards
+ * Try progress and nothing else, so a version bump here never costs a
  * learner their responses — item sessions travel in the same snapshot and are
  * normalized separately.
  *
- * An absent slice is `null` too, and indistinguishable from a pre-formative
- * save, which is what keeps existing snapshots valid.
+ * An absent slice is `null` too, and indistinguishable from a save made
+ * without Try state, which is what keeps existing snapshots valid.
  */
-export function normalizeFormativeSectionSlice(args) {
+export function normalizeTrySectionSlice(args) {
     const { slice } = args;
     if (!slice || typeof slice !== "object")
         return null;
     const raw = slice;
-    if (raw.version !== FORMATIVE_SLICE_VERSION)
+    if (raw.version !== TRY_SLICE_VERSION)
         return null;
     if (!raw.items || typeof raw.items !== "object")
         return null;

package/dist/{formative → item-session-control}/state.d.ts

@@ -1,6 +1,6 @@
-import type { FormativeFeedbackReveal, FormativeItemState, FormativeItemView, FormativeTryOutcome, ResolvedFormativePolicy } from "./types.js";
-export declare const FORMATIVE_ITEM_STATE_VERSION: 1;
-export declare function createFormativeItemState(itemIdentifier: string): FormativeItemState;
+import type { FeedbackReveal, ItemTryState, ItemTryView, TryOutcome, ResolvedItemSessionControlPolicy } from "./types.js";
+export declare const ITEM_TRY_STATE_VERSION: 1;
+export declare function createItemTryState(itemIdentifier: string): ItemTryState;
 /**
  * Record one Try.
  *
@@ -8,24 +8,24 @@ export declare function createFormativeItemState(itemIdentifier: string): Format
  * state can be checked, so a second click landing before the projection
  * round-trips is dropped rather than spending a Try.
  */
-export declare function recordFormativeTry(args: {
-    state?: FormativeItemState;
+export declare function recordTry(args: {
+    state?: ItemTryState;
     itemIdentifier: string;
-    policy: ResolvedFormativePolicy;
-    outcome: FormativeTryOutcome;
-}): FormativeItemState;
+    policy: ResolvedItemSessionControlPolicy;
+    outcome: TryOutcome;
+}): ItemTryState;
 /**
  * Dismiss a reveal and reopen the item for editing. Withdrawing `revealed` is
  * what withdraws the env override, so the item returns to the section's own
  * mode.
  *
  * A learner action, so it respects the Try budget: an item with none left keeps
- * its feedback on screen. `hideFormativeItem` is the host-authority version.
+ * its feedback on screen. `hideItemFeedback` is the host-authority version.
  */
-export declare function retryFormativeItem(args: {
-    state?: FormativeItemState;
-    policy: ResolvedFormativePolicy;
-}): FormativeItemState | undefined;
+export declare function retryItem(args: {
+    state?: ItemTryState;
+    policy: ResolvedItemSessionControlPolicy;
+}): ItemTryState | undefined;
 /**
  * Reveal on host authority — a teacher-driven "show the answer".
  *
@@ -38,23 +38,23 @@ export declare function retryFormativeItem(args: {
  * whatever response is there, including none, which is what "show the answer"
  * means before the learner has answered.
  */
-export declare function revealFormativeItem(args: {
-    state?: FormativeItemState;
+export declare function revealItemFeedback(args: {
+    state?: ItemTryState;
     itemIdentifier: string;
-    policy: ResolvedFormativePolicy;
-    feedback: Exclude<FormativeFeedbackReveal, "none">;
-}): FormativeItemState;
+    policy: ResolvedItemSessionControlPolicy;
+    feedback: Exclude<FeedbackReveal, "none">;
+}): ItemTryState;
 /**
  * Withdraw a reveal on host authority. Unlike a learner retry this ignores the
  * Try budget: a host that revealed an item with no Tries left must be able to
  * put it back.
  */
-export declare function hideFormativeItem(args: {
-    state?: FormativeItemState;
-    policy: ResolvedFormativePolicy;
-}): FormativeItemState | undefined;
+export declare function hideItemFeedback(args: {
+    state?: ItemTryState;
+    policy: ResolvedItemSessionControlPolicy;
+}): ItemTryState | undefined;
 /** Derive everything a rendering component needs from policy plus state. */
-export declare function resolveFormativeItemView(args: {
-    policy: ResolvedFormativePolicy;
-    state?: FormativeItemState;
-}): FormativeItemView;
+export declare function resolveItemTryView(args: {
+    policy: ResolvedItemSessionControlPolicy;
+    state?: ItemTryState;
+}): ItemTryView;

package/dist/{formative → item-session-control}/state.js

@@ -1,7 +1,7 @@
-export const FORMATIVE_ITEM_STATE_VERSION = 1;
-export function createFormativeItemState(itemIdentifier) {
+export const ITEM_TRY_STATE_VERSION = 1;
+export function createItemTryState(itemIdentifier) {
     return {
-        version: FORMATIVE_ITEM_STATE_VERSION,
+        version: ITEM_TRY_STATE_VERSION,
         itemIdentifier,
         tryCount: 0,
         revealed: false,
@@ -20,7 +20,7 @@ function shouldReveal(policy, tryCount) {
         return false;
     if (policy.revealOn === "on-try")
         return true;
-    // Defensive: `resolveFormativePolicy` already coerces `"on-final-try"` to
+    // Defensive: `resolveItemSessionControl` already coerces `"on-final-try"` to
     // `"on-try"` under unlimited Tries, so this branch only guards a
     // hand-constructed policy.
     if (policy.maxTries === "unlimited")
@@ -34,8 +34,8 @@ function shouldReveal(policy, tryCount) {
  * state can be checked, so a second click landing before the projection
  * round-trips is dropped rather than spending a Try.
  */
-export function recordFormativeTry(args) {
-    const current = args.state ?? createFormativeItemState(args.itemIdentifier);
+export function recordTry(args) {
+    const current = args.state ?? createItemTryState(args.itemIdentifier);
     if (!args.policy.enabled)
         return current;
     const remaining = triesRemaining(args.policy, current.tryCount);
@@ -44,7 +44,7 @@ export function recordFormativeTry(args) {
     const tryCount = current.tryCount + 1;
     return {
         ...current,
-        version: FORMATIVE_ITEM_STATE_VERSION,
+        version: ITEM_TRY_STATE_VERSION,
         itemIdentifier: args.itemIdentifier,
         tryCount,
         revealed: shouldReveal(args.policy, tryCount),
@@ -62,9 +62,9 @@ export function recordFormativeTry(args) {
  * mode.
  *
  * A learner action, so it respects the Try budget: an item with none left keeps
- * its feedback on screen. `hideFormativeItem` is the host-authority version.
+ * its feedback on screen. `hideItemFeedback` is the host-authority version.
  */
-export function retryFormativeItem(args) {
+export function retryItem(args) {
     const current = args.state;
     if (!current || !args.policy.enabled)
         return current;
@@ -87,8 +87,8 @@ export function retryFormativeItem(args) {
  * whatever response is there, including none, which is what "show the answer"
  * means before the learner has answered.
  */
-export function revealFormativeItem(args) {
-    const current = args.state ?? createFormativeItemState(args.itemIdentifier);
+export function revealItemFeedback(args) {
+    const current = args.state ?? createItemTryState(args.itemIdentifier);
     if (!args.policy.enabled)
         return current;
     if (current.revealed && current.revealOverride === args.feedback) {
@@ -101,7 +101,7 @@ export function revealFormativeItem(args) {
  * Try budget: a host that revealed an item with no Tries left must be able to
  * put it back.
  */
-export function hideFormativeItem(args) {
+export function hideItemFeedback(args) {
     const current = args.state;
     if (!current || !args.policy.enabled)
         return current;
@@ -119,7 +119,7 @@ function envOverrideFor(policy, revealed, revealOverride) {
     };
 }
 /** Derive everything a rendering component needs from policy plus state. */
-export function resolveFormativeItemView(args) {
+export function resolveItemTryView(args) {
     const { policy } = args;
     const tryCount = args.state?.tryCount ?? 0;
     const revealed = args.state?.revealed === true;

package/dist/{formative → item-session-control}/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * Formative delivery vocabulary.
+ * Item session control vocabulary.
  *
  * A **Try** is one submitted-for-checking pass over a single item. It is not
  * `TestAttemptSession` (the assessment administration) and not
@@ -7,11 +7,11 @@
  * an item). Both of those already own the word "attempt" in this codebase, at
  * two different scopes, which is why this contract does not use it.
  *
- * See `docs/prds/formative-delivery-contract.md` for the ratified contract and
+ * See `docs/prds/item-session-control-contract.md` for the ratified contract and
  * its QTI 3 mapping.
  */
 /** How many Tries a learner gets on one item. */
-export type FormativeTryLimit = number | "unlimited";
+export type TryLimit = number | "unlimited";
 /**
  * What the learner sees after a Try.
  *
@@ -20,54 +20,52 @@ export type FormativeTryLimit = number | "unlimited";
  * `role: "instructor"`, which is the element convention for additionally
  * revealing the authored correct response.
  */
-export type FormativeFeedbackReveal = "none" | "correctness" | "solution";
+export type FeedbackReveal = "none" | "correctness" | "solution";
 /** When a reveal happens: after every Try, or only once Tries are spent. */
-export type FormativeRevealTiming = "on-try" | "on-final-try";
+export type FeedbackRevealTiming = "on-try" | "on-final-try";
 /**
- * Authored policy. Lives on `AssessmentSection.formative` as the section
- * default and on `AssessmentItemRef.formative` as a per-item override.
+ * Authored policy. Lives on `AssessmentSection.itemSessionControl` as the section
+ * default and on `AssessmentItemRef.itemSessionControl` as a per-item override.
  */
-export interface FormativeDeliveryPolicy {
+export interface ItemSessionControlPolicy {
     /**
      * Absent or `false` leaves delivery exactly as it is without this contract:
      * no control, no projection, no state.
      */
     enabled?: boolean;
     /** Default 1. */
-    maxTries?: FormativeTryLimit;
+    maxTries?: TryLimit;
     /** Default `"correctness"`. */
-    feedback?: FormativeFeedbackReveal;
+    feedback?: FeedbackReveal;
     /** Default `"on-try"`. */
-    revealOn?: FormativeRevealTiming;
+    revealOn?: FeedbackRevealTiming;
 }
-/** Same shape as the section policy; every field overrides independently. */
-export type FormativeItemPolicy = FormativeDeliveryPolicy;
 /** The policy after built-in defaults, section, and item ref are merged. */
-export interface ResolvedFormativePolicy {
+export interface ResolvedItemSessionControlPolicy {
     enabled: boolean;
-    maxTries: FormativeTryLimit;
-    feedback: FormativeFeedbackReveal;
-    revealOn: FormativeRevealTiming;
+    maxTries: TryLimit;
+    feedback: FeedbackReveal;
+    revealOn: FeedbackRevealTiming;
 }
 /**
  * `"unknown"` is the honest state for an item no loaded controller can score —
  * one holding a rubric element, or one whose element bundle exposes no
  * `outcome`. It is never collapsed into `"incorrect"`.
  */
-export type FormativeCorrectness = "correct" | "partial" | "incorrect" | "unknown";
+export type TryCorrectness = "correct" | "partial" | "incorrect" | "unknown";
 /**
  * The subset of an element outcome that aggregation reads. `OutcomeResponse` is
  * assignable to this; the structural type keeps this module free of a
  * dependency on the entity types, which import policy types from here.
  */
-export interface FormativeScoredOutcome {
+export interface ScoredElementOutcome {
     score?: number;
     max?: number;
     [key: string]: unknown;
 }
 /** The recorded result of one Try. */
-export interface FormativeTryOutcome {
-    correctness: FormativeCorrectness;
+export interface TryOutcome {
+    correctness: TryCorrectness;
     points?: number;
     max?: number;
     scoredElementCount: number;
@@ -84,10 +82,10 @@ export interface FormativeTryOutcome {
      * A trade: this persists inside the session slice, so a snapshot grows by
      * whatever the elements put in their outcomes — some include a scoring trace.
      */
-    elementOutcomes?: FormativeScoredOutcome[];
+    elementOutcomes?: ScoredElementOutcome[];
 }
-/** Per-item delivery state. Persisted; see `FormativeSectionSlice`. */
-export interface FormativeItemState {
+/** Per-item delivery state. Persisted; see `TrySectionSlice`. */
+export interface ItemTryState {
     version: 1;
     itemIdentifier: string;
     tryCount: number;
@@ -98,7 +96,7 @@ export interface FormativeItemState {
      * reload restores the screen the learner left.
      */
     revealed: boolean;
-    lastOutcome?: FormativeTryOutcome;
+    lastOutcome?: TryOutcome;
     /** 1-based Try on which the item first scored full credit. Never overwritten. */
     firstCorrectTry?: number;
     /**
@@ -106,19 +104,19 @@ export interface FormativeItemState {
      * than the learner earning it. Overrides the policy's `feedback` for the env
      * projection only — the policy still decides Tries.
      *
-     * Set by `revealFormativeItem`, cleared by `hideFormativeItem` and by a
+     * Set by `revealItemFeedback`, cleared by `hideItemFeedback` and by a
      * learner retry, so a teacher-driven "show the answer" does not silently
      * upgrade every later reveal on that item.
      */
-    revealOverride?: FormativeFeedbackReveal;
+    revealOverride?: FeedbackReveal;
 }
-/** The persisted slice, carried on `SectionControllerSessionState.formative`. */
-export interface FormativeSectionSlice {
+/** The persisted slice, carried on `SectionControllerSessionState.tries`. */
+export interface TrySectionSlice {
     version: 1;
-    items: Record<string, FormativeItemState>;
+    items: Record<string, ItemTryState>;
 }
 /** Projected over the section env for one revealed item. */
-export interface FormativeEnvOverride {
+export interface FeedbackEnvOverride {
     mode: "evaluate";
     role: "student" | "instructor";
 }
@@ -126,18 +124,18 @@ export interface FormativeEnvOverride {
  * What a rendering component needs, derived once so no component reimplements
  * the predicate. Carries no copy — wording belongs to the rendering package.
  */
-export interface FormativeItemView {
+export interface ItemTryView {
     enabled: boolean;
     tryCount: number;
     triesRemaining: number | "unlimited";
     canCheck: boolean;
     canRetry: boolean;
     revealed: boolean;
-    envOverride?: FormativeEnvOverride;
-    lastOutcome?: FormativeTryOutcome;
+    envOverride?: FeedbackEnvOverride;
+    lastOutcome?: TryOutcome;
 }
 /** Section rollup over Try outcomes. */
-export interface FormativeMasteryRollup {
+export interface MasteryRollup {
     version: 1;
     totalItems: number;
     /**
@@ -153,12 +151,12 @@ export interface FormativeMasteryRollup {
     complete: boolean;
 }
 /** The composition-model projection layouts read. */
-export interface FormativeSectionProjection {
+export interface TrySectionProjection {
     version: 1;
     enabled: boolean;
-    policies: Record<string, ResolvedFormativePolicy>;
-    states: Record<string, FormativeItemState>;
-    mastery: FormativeMasteryRollup;
+    policies: Record<string, ResolvedItemSessionControlPolicy>;
+    states: Record<string, ItemTryState>;
+    mastery: MasteryRollup;
 }
 /** The two learner actions a rendering component can request. */
-export type FormativeAction = "check" | "retry";
+export type TryAction = "check" | "retry";

package/dist/{formative → item-session-control}/types.js

@@ -1,5 +1,5 @@
 /**
- * Formative delivery vocabulary.
+ * Item session control vocabulary.
  *
  * A **Try** is one submitted-for-checking pass over a single item. It is not
  * `TestAttemptSession` (the assessment administration) and not
@@ -7,7 +7,7 @@
  * an item). Both of those already own the word "attempt" in this codebase, at
  * two different scopes, which is why this contract does not use it.
  *
- * See `docs/prds/formative-delivery-contract.md` for the ratified contract and
+ * See `docs/prds/item-session-control-contract.md` for the ratified contract and
  * its QTI 3 mapping.
  */
 export {};

package/dist/timed-media/index.d.ts

@@ -5,7 +5,7 @@
  * Pure apart from one adapter factory that is inert until called, so the contract
  * is testable without a browser and an adapter can import it without pulling in a
  * player. Live cue state belongs to `SectionController` in
- * `@pie-players/pie-section-player`, which is where the equivalent formative state
+ * `@pie-players/pie-section-player`, which is where the equivalent Try state
  * lives — one rollup over one item set, in one package.
  *
  * Contract: `docs/prds/timed-media-section-contract.md`.

package/dist/timed-media/index.js

@@ -5,7 +5,7 @@
  * Pure apart from one adapter factory that is inert until called, so the contract
  * is testable without a browser and an adapter can import it without pulling in a
  * player. Live cue state belongs to `SectionController` in
- * `@pie-players/pie-section-player`, which is where the equivalent formative state
+ * `@pie-players/pie-section-player`, which is where the equivalent Try state
  * lives — one rollup over one item set, in one package.
  *
  * Contract: `docs/prds/timed-media-section-contract.md`.

package/dist/timed-media/policy.d.ts

@@ -28,9 +28,9 @@ export declare function normalizeTimedMediaSectionData(args: {
     itemIdentifiers: readonly string[];
     resolveStimulusRenderableId: (stimulusRef: string) => string | undefined;
     /**
-     * The Try budget each item's resolved formative policy leaves, so a gate on
+     * The Try budget each item's resolved item session control policy leaves, so a gate on
      * correctness can be refused where it would strand the learner. Supplied by the
-     * caller because formative policy resolution is that contract's, not this one's.
+     * caller because item session control policy resolution is that contract's, not this one's.
      */
     resolveItemTryBudget: (itemIdentifier: string) => TimedMediaItemTryBudget;
 }): TimedMediaValidationResult;

package/dist/timed-media/policy.js

@@ -240,7 +240,7 @@ export function normalizeTimedMediaSectionData(args) {
                 // A correctness gate is only passable while the learner still has a Try
                 // to spend. Over an item with a finite budget the gate becomes
                 // unpassable the moment the budget runs out, and over an item that does
-                // not deliver formatively there is never a Try at all — in both cases
+                // not enable item session control there is never a Try at all — in both cases
                 // nothing the learner can do releases playback, and no host action
                 // releases it either, because a forced reveal is not a correct answer.
                 // Refused here rather than released at runtime: releasing would deliver
@@ -250,7 +250,7 @@ export function normalizeTimedMediaSectionData(args) {
                 if (unpassable.length > 0) {
                     errors.push({
                         code: "gate-requires-unlimited-tries",
-                        message: `Gate cue "${identifier}" releases on correctness, so every item it names needs formative delivery with maxTries: "unlimited" — otherwise a learner who runs out of Tries can never release playback. Offending item refs: ${unpassable.join(", ")}.`,
+                        message: `Gate cue "${identifier}" releases on correctness, so every item it names needs item session control with maxTries: "unlimited" — otherwise a learner who runs out of Tries can never release playback. Offending item refs: ${unpassable.join(", ")}.`,
                         cueIdentifier: identifier,
                     });
                     continue;

package/dist/timed-media/session.d.ts

@@ -1,7 +1,7 @@
 /**
  * Persistence for the timed-media slice.
  *
- * Same posture as the formative slice: an unreadable slice is rejected whole and
+ * Same posture as the Try slice: an unreadable slice is rejected whole and
  * delivery starts from clean cue state, while item sessions in the same snapshot
  * are normalized separately and survive. A version bump here must never cost a
  * learner their responses.

package/dist/timed-media/session.js

@@ -1,7 +1,7 @@
 /**
  * Persistence for the timed-media slice.
  *
- * Same posture as the formative slice: an unreadable slice is rejected whole and
+ * Same posture as the Try slice: an unreadable slice is rejected whole and
  * delivery starts from clean cue state, while item sessions in the same snapshot
  * are normalized separately and survive. A version bump here must never cost a
  * learner their responses.

package/dist/timed-media/types.d.ts

@@ -9,7 +9,7 @@
  * See `docs/prds/timed-media-section-contract.md` for the ratified contract and
  * `docs/architecture/timed-media-section.md` for the layer-ownership record.
  */
-import type { FormativeCorrectness } from "../formative/types.js";
+import type { TryCorrectness } from "../item-session-control/types.js";
 import type { MediaFragmentRange } from "../types/index.js";
 /**
  * What a cue does to the items it names.
@@ -23,15 +23,15 @@ export type TimedMediaCueActivation = "reveal" | "gate" | "metadata";
 /**
  * The condition over delivery state that releases a gate.
  *
- * Named from the shipped formative vocabulary rather than defined here, which is
- * the whole reason formative delivery sequenced first — see
+ * Named from the shipped Try vocabulary rather than defined here, which is
+ * the whole reason item session control sequenced first — see
  * `docs/adr/0001-formative-delivery-before-timed-media.md`. `"responded"` is the
  * response-only case, and it reads item completion rather than Try state so a
- * gate works in a section that does not deliver formatively at all.
+ * gate works in a section that does not enable item session control at all.
  */
 export type TimedMediaGateCondition = "responded" | "correct" | "partial-or-better";
 /**
- * What a gate does when the item cannot be auto-scored — `FormativeCorrectness`
+ * What a gate does when the item cannot be auto-scored — `TryCorrectness`
  * of `"unknown"`, which is the honest state of an item holding a rubric element
  * rather than a defect to design around.
  *
@@ -131,13 +131,13 @@ export interface ResolvedTimedMediaSectionData {
     scoringPolicy?: TimedMediaScoringPolicy;
 }
 /**
- * What a gated item's resolved formative policy leaves the learner.
+ * What a gated item's resolved item session control policy leaves the learner.
  *
  * Read by validation, not by the reduction: a gate on correctness over an item
  * with a finite Try budget is a dead end, and so is one over an item that does not
- * deliver formatively at all — no Try means no correctness, ever.
+ * enable item session control at all — no Try means no correctness, ever.
  */
-export type TimedMediaItemTryBudget = "unlimited" | "finite" | "not-formative";
+export type TimedMediaItemTryBudget = "unlimited" | "finite" | "none";
 export interface TimedMediaValidationError {
     /** Machine-readable, so a host can branch without parsing prose. */
     code: "missing-stimulus-ref" | "unresolved-stimulus-ref"
@@ -219,7 +219,7 @@ export interface MediaTimeSource {
 /**
  * The persisted slice, carried on `SectionControllerSessionState.timedMedia`.
  *
- * One shape live and persisted, unlike formative's split between a per-item
+ * One shape live and persisted, unlike the Try state's split between a per-item
  * reducer state and a slice: timed-media state is section-scoped, so there is
  * nothing to key.
  */
@@ -241,14 +241,14 @@ export interface TimedMediaSectionSessionSlice {
 }
 /**
  * Delivery state a gate condition reads, supplied by the caller so this module
- * stays pure and depends on neither the controller nor the formative module's
+ * stays pure and depends on neither the controller nor the item session control module's
  * live state.
  */
 export interface TimedMediaDeliveryState {
     /** Item completion by canonical id: the `"responded"` condition's signal. */
     respondedByItemId: Record<string, boolean>;
     /** Last Try correctness by canonical id; absent means no Try yet. */
-    correctnessByItemId: Record<string, FormativeCorrectness | undefined>;
+    correctnessByItemId: Record<string, TryCorrectness | undefined>;
     /** Whether every item in the section reports completion. */
     itemsComplete: boolean;
 }

package/dist/types/index.d.ts

@@ -8,10 +8,10 @@
  * them. The module depends on nothing beyond this package's own type modules,
  * so front-end and server code can both import it.
  */
-import type { FormativeDeliveryPolicy, FormativeItemPolicy, FormativeSectionSlice } from "../formative/types.js";
+import type { ItemSessionControlPolicy, TrySectionSlice } from "../item-session-control/types.js";
 import type { TimedMediaSectionData, TimedMediaSectionSessionSlice } from "../timed-media/types.js";
 import type { AdaptationLink, CurriculumStandard, LanguagePolicy, SkillLevel } from "./interchange.js";
-export type { FormativeDeliveryPolicy, FormativeItemPolicy };
+export type { ItemSessionControlPolicy };
 export type { TimedMediaSectionData };
 export type { AdaptationLink, ContentSubstitution, CurriculumStandard, LanguagePolicy, ServedContentIdentity, SkillLevel, } from "./interchange.js";
 export interface BaseEntity {
@@ -175,13 +175,13 @@ export interface AssessmentItemRef extends BaseEntity {
     /** Item-level settings for tool requirements and customization */
     settings?: ItemSettings;
     /**
-     * Formative delivery override for this item. Every field overrides the
-     * section's `formative` policy independently, which is the order QTI 3 uses
+     * Item session control override for this item. Every field overrides the
+     * section's `itemSessionControl` policy independently, which is the order QTI 3 uses
      * for `qti-item-session-control` on an item ref versus its section.
      *
-     * See `docs/prds/formative-delivery-contract.md`.
+     * See `docs/prds/item-session-control-contract.md`.
      */
-    formative?: FormativeItemPolicy;
+    itemSessionControl?: ItemSessionControlPolicy;
 }
 export interface AssessmentSection extends BaseEntity {
     id?: string;
@@ -208,15 +208,15 @@ export interface AssessmentSection extends BaseEntity {
     assessmentItemRefs?: AssessmentItemRef[];
     rubricBlocks?: RubricBlock[];
     /**
-     * Formative delivery policy for this section: how many Tries a learner gets
+     * Item session control policy for this section: how many Tries a learner gets
      * on each item, when feedback is revealed, and whether the behavior is on at
      * all. Absent or `enabled: false` delivers exactly as a section without this
      * field — no control, no state, no env override.
      *
-     * Individual items override it through `AssessmentItemRef.formative`. See
-     * `docs/prds/formative-delivery-contract.md`.
+     * Individual items override it through `AssessmentItemRef.itemSessionControl`. See
+     * `docs/prds/item-session-control-contract.md`.
      */
-    formative?: FormativeDeliveryPolicy;
+    itemSessionControl?: ItemSessionControlPolicy;
     /**
      * The section flavor. Absent for every section authored so far, and the only
      * value is `"timed-media"`, which pairs with `timedMedia` below.
@@ -258,19 +258,19 @@ export interface SectionControllerSessionState {
     visitedItemIdentifiers?: string[];
     itemSessions: Record<string, unknown>;
     /**
-     * Formative delivery state — Try counts and reveal state per item.
+     * Try state — Try counts and reveal state per item.
      *
      * Optional, and its absence is indistinguishable from a snapshot saved
-     * before formative delivery existed, which is what keeps existing persisted
+     * before item session control existed, which is what keeps existing persisted
      * sessions valid. A slice with an unrecognized `version` is rejected whole
-     * and formative state starts clean; `itemSessions` in the same snapshot is
-     * unaffected, so a formative version bump never costs a learner responses.
+     * and Try state starts clean; `itemSessions` in the same snapshot is
+     * unaffected, so a Try slice version bump never costs a learner responses.
      */
-    formative?: FormativeSectionSlice;
+    tries?: TrySectionSlice;
     /**
      * Timed-media delivery state — media progress, cue visits and completions.
      *
-     * Same posture as `formative`: optional, absence indistinguishable from a
+     * Same posture as `tries`: optional, absence indistinguishable from a
      * pre-timed-media snapshot, and an unrecognized `version` rejected whole so
      * cue progress restarts while item sessions in the same snapshot are applied
      * untouched.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "1.0.0-beta.8",
+	"version": "1.0.0-beta.9",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",
@@ -45,9 +45,9 @@
 			"types": "./dist/types/index.d.ts",
 			"import": "./dist/types/index.js"
 		},
-		"./formative": {
-			"types": "./dist/formative/index.d.ts",
-			"import": "./dist/formative/index.js"
+		"./item-session-control": {
+			"types": "./dist/item-session-control/index.d.ts",
+			"import": "./dist/item-session-control/index.js"
 		},
 		"./timed-media": {
 			"types": "./dist/timed-media/index.d.ts",

package/dist/formative/index.d.ts

@@ -1,16 +0,0 @@
-/**
- * Formative delivery: Try state, feedback reveal, and section mastery.
- *
- * Pure and Node-safe by design — no DOM, no timers, no element registry — so
- * the contract is testable without a browser and an adapter can import it
- * without pulling in a player. Everything that touches the DOM stays in
- * `@pie-players/pie-section-player`.
- *
- * Contract: `docs/prds/formative-delivery-contract.md`.
- */
-export type { FormativeAction, FormativeCorrectness, FormativeDeliveryPolicy, FormativeEnvOverride, FormativeFeedbackReveal, FormativeItemPolicy, FormativeItemState, FormativeItemView, FormativeMasteryRollup, FormativeRevealTiming, FormativeScoredOutcome, FormativeSectionProjection, FormativeSectionSlice, FormativeTryLimit, FormativeTryOutcome, ResolvedFormativePolicy, } from "./types.js";
-export { FORMATIVE_POLICY_DEFAULTS, isFormativeSectionEnabled, resolveFormativePolicies, resolveFormativePolicy, } from "./policy.js";
-export { aggregateFormativeOutcome } from "./outcome.js";
-export { FORMATIVE_ITEM_STATE_VERSION, createFormativeItemState, hideFormativeItem, recordFormativeTry, resolveFormativeItemView, retryFormativeItem, revealFormativeItem, } from "./state.js";
-export { FORMATIVE_MASTERY_VERSION, rollupFormativeMastery } from "./mastery.js";
-export { FORMATIVE_SLICE_VERSION, normalizeFormativeSectionSlice, toFormativeSectionSlice, } from "./session.js";

package/dist/formative/index.js

@@ -1,5 +0,0 @@
-export { FORMATIVE_POLICY_DEFAULTS, isFormativeSectionEnabled, resolveFormativePolicies, resolveFormativePolicy, } from "./policy.js";
-export { aggregateFormativeOutcome } from "./outcome.js";
-export { FORMATIVE_ITEM_STATE_VERSION, createFormativeItemState, hideFormativeItem, recordFormativeTry, resolveFormativeItemView, retryFormativeItem, revealFormativeItem, } from "./state.js";
-export { FORMATIVE_MASTERY_VERSION, rollupFormativeMastery } from "./mastery.js";
-export { FORMATIVE_SLICE_VERSION, normalizeFormativeSectionSlice, toFormativeSectionSlice, } from "./session.js";

package/dist/formative/session.d.ts

@@ -1,19 +0,0 @@
-import type { FormativeItemState, FormativeSectionSlice } from "./types.js";
-export declare const FORMATIVE_SLICE_VERSION: 1;
-export declare function toFormativeSectionSlice(states: Record<string, FormativeItemState>): FormativeSectionSlice;
-/**
- * Validate a persisted slice against the section it is being restored into.
- *
- * Returns `null` for a slice this build cannot read, which the caller treats as
- * "start formative state clean". Rejection is deliberately narrow: it discards
- * formative progress and nothing else, so a version bump here never costs a
- * learner their responses — item sessions travel in the same snapshot and are
- * normalized separately.
- *
- * An absent slice is `null` too, and indistinguishable from a pre-formative
- * save, which is what keeps existing snapshots valid.
- */
-export declare function normalizeFormativeSectionSlice(args: {
-    slice: unknown;
-    allowedItemIdentifiers: readonly string[];
-}): Record<string, FormativeItemState> | null;