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

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/security/private-hosts.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Hostname classification for a URL a server fetches on someone else's behalf,
+ * such as an SSML `<audio src>` a TTS provider will request or an asset URL an
+ * upstream service returns. Every such check reads this module, so no two
+ * copies of it can drift apart.
+ *
+ * IP literals are classified by `ipaddr.js`, whose ranges follow the IANA IPv4
+ * and IPv6 Special-Purpose Address Registries (RFC 6890). A host is private
+ * unless it is a public unicast address or a name: loopback, private, link-local,
+ * unique-local, carrier-grade NAT, multicast, broadcast, documentation and
+ * reserved ranges, and the IPv6 forms that embed an IPv4 address (NAT64, 6to4,
+ * Teredo), all count. `ipaddr.js` also reads the numeric IPv4 forms (`2130706433`,
+ * `0x7f000001`, `0177.0.0.1`) and unmaps IPv4-mapped IPv6.
+ *
+ * Only the literal is checked. A public name that resolves to a private address
+ * passes; guarding that takes a check of the resolved address at connect time.
+ *
+ * @module
+ */
+/** Whether `hostname` is a cloud instance-metadata endpoint. */
+export declare function isCloudMetadataHostname(hostname: string): boolean;
+/**
+ * Whether `hostname` is anything other than a public unicast address or a
+ * public name: `localhost` and its subdomains (RFC 6761), or an IP literal in
+ * any special-purpose range.
+ */
+export declare function isPrivateHostname(hostname: string): boolean;