@hypit/hypit 0.0.1 → 0.1.0

package/packages/temporal/src/index.ts

@@ -0,0 +1,110 @@
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
+import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
+import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";
+import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
+
+const string = { kind: "string", minLength: 1 } as const;
+const unsignedInteger = { kind: "number", integer: true, minimum: 0 } as const;
+const integer = { kind: "number", integer: true } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+const duration: ValueSchema = { kind: "oneOf", variants: [
+  object({ unit: { schema: { kind: "literal", value: "frames" } }, value: { schema: integer } }),
+  object({ unit: { schema: { kind: "literal", value: "milliseconds" } }, value: { schema: integer } }),
+  object({ unit: { schema: { kind: "literal", value: "seconds" } }, numerator: { schema: integer }, denominator: { schema: { kind: "number", integer: true, minimum: 1 } } }),
+] };
+const instant: ValueSchema = { kind: "oneOf", variants: [
+  ...["program.start", "program.end", "selection.start", "selection.end", "segment.start", "segment.end", "moment.cue"].map((ref) => object({
+    ref: { schema: { kind: "literal", value: ref } }, offset: { schema: duration, optional: true },
+  })),
+  object({ ref: { schema: { kind: "literal", value: "absolute" } }, at: { schema: duration }, offset: { schema: duration, optional: true } }),
+] };
+const sourceSchema: ValueSchema = { kind: "oneOf", variants: [
+  ...["program", "selection", "segment", "moment"].map((kind) => object({
+    spaceId: { schema: string }, narrativeId: { schema: string, optional: true },
+    kind: { schema: { kind: "literal", value: kind } }, id: { schema: string },
+  })),
+] };
+const authoritySchema: ValueSchema = { kind: "oneOf", variants: [
+  object({
+    kind: { schema: { kind: "literal", value: "semantic" } },
+    boundary: { schema: { kind: "string", enum: ["start", "end", "cue"] } },
+  }),
+  object({
+    kind: { schema: { kind: "literal", value: "parameter" } },
+    binding: { schema: string },
+    relation: { schema: { kind: "string", enum: ["direct", "after-start", "before-end"] } },
+  }),
+  object({ kind: { schema: { kind: "literal", value: "fixed" } } }),
+] };
+const frameSpanSchema: ValueSchema = object({
+  startFrame: { schema: unsignedInteger },
+  endFrameExclusive: { schema: { kind: "number", integer: true, minimum: 1 } },
+});
+
+export * from "./location.js";
+export * from "./projection.js";
+export * from "./schedule.js";
+export * from "./sample.js";
+export type * from "./types.js";
+
+export const temporalModuleRef = { name: "@hypit/temporal", version: "1" } as const;
+export const temporalTypes = {
+  instantSpec: { module: temporalModuleRef, name: "TemporalInstantSpec" },
+  instant: { module: temporalModuleRef, name: "TemporalInstant" },
+  windowSpec: { module: temporalModuleRef, name: "TemporalWindowSpec" },
+  window: { module: temporalModuleRef, name: "TemporalWindow" },
+} satisfies Record<string, TypeRef>;
+export const temporalProducers = {
+  projectProgramInstant: { module: temporalModuleRef, name: "project-program-instant" },
+  projectSelectionInstant: { module: temporalModuleRef, name: "project-selection-instant" },
+  projectSegmentInstant: { module: temporalModuleRef, name: "project-segment-instant" },
+  projectMomentInstant: { module: temporalModuleRef, name: "project-moment-instant" },
+  composeWindow: { module: temporalModuleRef, name: "compose-window" },
+} satisfies Record<string, ProducerRef>;
+export const temporalManifest: ModuleManifest = {
+  format: "hypit.module@1",
+  name: temporalModuleRef.name,
+  version: temporalModuleRef.version,
+  dependencies: [narrativeDependency, programSpaceDependency, semanticTrackDependency],
+  types: [
+    { name: temporalTypes.instantSpec.name },
+    { name: temporalTypes.instant.name },
+    { name: temporalTypes.windowSpec.name },
+    { name: temporalTypes.window.name },
+  ],
+  capabilities: [],
+  producers: [
+    { name: temporalProducers.projectProgramInstant.name,
+      inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "spec", type: temporalTypes.instantSpec }],
+      outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },
+    { name: temporalProducers.projectSelectionInstant.name,
+      inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "selection", type: narrativeTypes.selection }, { name: "spec", type: temporalTypes.instantSpec }],
+      outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },
+    { name: temporalProducers.projectSegmentInstant.name,
+      inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "segment", type: narrativeTypes.excerpt }, { name: "spec", type: temporalTypes.instantSpec }],
+      outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },
+    { name: temporalProducers.projectMomentInstant.name,
+      inputs: [{ name: "semantic", type: semanticTrackTypes.track }, { name: "moment", type: narrativeTypes.moment }, { name: "spec", type: temporalTypes.instantSpec }],
+      outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },
+    { name: temporalProducers.composeWindow.name,
+      inputs: [{ name: "spec", type: temporalTypes.windowSpec }, { name: "start", type: temporalTypes.instant }, { name: "end", type: temporalTypes.instant }],
+      outputs: [{ name: "window", type: temporalTypes.window }], needs: [] },
+  ],
+};
+export const temporalDependency = { module: temporalModuleRef } as const;
+
+export const temporalInstantSpecSchema: ValueSchema = object({
+  id: { schema: string }, subjectId: { schema: string }, projection: { schema: instant }, authority: { schema: authoritySchema },
+});
+export const temporalInstantSchema: ValueSchema = object({
+  id: { schema: string }, subjectId: { schema: string }, source: { schema: sourceSchema }, projection: { schema: instant },
+  authority: { schema: authoritySchema }, frame: { schema: unsignedInteger },
+});
+export const temporalWindowSpecSchema: ValueSchema = object({ id: { schema: string }, subjectId: { schema: string } });
+export const temporalWindowSchema: ValueSchema = object({
+  id: { schema: string },
+  subjectId: { schema: string },
+  start: { schema: temporalInstantSchema },
+  end: { schema: temporalInstantSchema },
+  span: { schema: frameSpanSchema },
+});

package/packages/temporal/src/location.ts

@@ -0,0 +1,67 @@
+import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
+import { programSpaceFrameCount } from "@hypit/program-space";
+import {
+  momentFrame,
+  projectSemanticProgramSpace,
+  segmentFrameSpan,
+  selectionFrameSpan,
+} from "@hypit/semantic-track";
+import type { SemanticTrack } from "@hypit/semantic-track";
+
+import type {
+  LocatedMoment,
+  LocatedProgram,
+  LocatedSegment,
+  LocatedSelection,
+} from "./types.js";
+
+function assertLocatedFrame(frame: number, totalFrames: number, label: string): void {
+  if (!Number.isSafeInteger(frame) || frame < 0 || frame > totalFrames) {
+    throw new Error(`${label} is outside ProgramSpace.`);
+  }
+}
+
+export function locateSelection(
+  semantic: SemanticTrack,
+  selection: NarrativeSelectionRef,
+): LocatedSelection {
+  const space = projectSemanticProgramSpace(semantic);
+  const totalFrames = programSpaceFrameCount(space);
+  const span = selectionFrameSpan(semantic, selection);
+  assertLocatedFrame(span.startFrame, totalFrames, `NarrativeSelection ${selection.id} start`);
+  assertLocatedFrame(span.endFrameExclusive, totalFrames, `NarrativeSelection ${selection.id} end`);
+  return { id: selection.id, start: { frame: span.startFrame }, end: { frame: span.endFrameExclusive } };
+}
+
+export function locateMoment(
+  semantic: SemanticTrack,
+  moment: NarrativeMomentRef,
+): LocatedMoment {
+  const space = projectSemanticProgramSpace(semantic);
+  const totalFrames = programSpaceFrameCount(space);
+  const frame = momentFrame(semantic, moment);
+  assertLocatedFrame(frame, totalFrames, `NarrativeMoment ${moment.id} cue`);
+  return { id: moment.id, cue: { frame } };
+}
+
+export function locateProgram(semantic: SemanticTrack): LocatedProgram {
+  const space = projectSemanticProgramSpace(semantic);
+  return { id: "program", start: { frame: 0 }, end: { frame: programSpaceFrameCount(space) } };
+}
+
+export function locateSegment(
+  semantic: SemanticTrack,
+  segment: NarrativeExcerpt,
+): LocatedSegment {
+  const space = projectSemanticProgramSpace(semantic);
+  const totalFrames = programSpaceFrameCount(space);
+  const span = segmentFrameSpan(semantic, segment);
+  assertLocatedFrame(span.startFrame, totalFrames, `Narrative Segment ${segment.id} start`);
+  assertLocatedFrame(span.endFrameExclusive, totalFrames, `Narrative Segment ${segment.id} end`);
+  if (span.endFrameExclusive <= span.startFrame) throw new Error(`Narrative Segment ${segment.id} has no positive frame span.`);
+  return {
+    id: segment.id,
+    start: { frame: span.startFrame },
+    end: { frame: span.endFrameExclusive },
+  };
+}

package/packages/temporal/src/projection.ts

@@ -0,0 +1,280 @@
+import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
+import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
+import type { ProgramSpace } from "@hypit/program-space";
+import { projectSemanticProgramSpace } from "@hypit/semantic-track";
+import type { SemanticTrack } from "@hypit/semantic-track";
+
+import { locateMoment, locateProgram, locateSegment, locateSelection } from "./location.js";
+import { add, compare, durationInFrames, quantizeBoundary, rational } from "./rational.js";
+import type { Rational } from "./rational.js";
+import type {
+  LocatedMoment,
+  LocatedProgram,
+  LocatedSegment,
+  LocatedSelection,
+  ProjectedInstant,
+  ProjectedWindow,
+  TemporalInstantExpression,
+  TemporalInstant,
+  TemporalInstantSpec,
+  TemporalSource,
+  TemporalWindow,
+  TemporalWindowSpec,
+  WindowRelation,
+} from "./types.js";
+
+export type TemporalConsumption = {
+  readonly subjectId: string;
+  readonly space?: ProgramSpace;
+};
+
+/** Verify the public identity carried across a Temporal consumer boundary. */
+export function assertTemporalInstantFor(
+  instant: TemporalInstant,
+  expected: TemporalConsumption,
+): void {
+  if (!expected.subjectId || instant.subjectId !== expected.subjectId) {
+    throw new Error(`Temporal Instant subject ${instant.subjectId} does not match ${expected.subjectId}.`);
+  }
+  if (!instant.source.spaceId) {
+    throw new Error("Temporal Instant has no ProgramSpace identity.");
+  }
+  if (!Number.isSafeInteger(instant.frame) || instant.frame < 0) {
+    throw new Error("Temporal Instant frame is invalid.");
+  }
+  if (expected.space !== undefined) {
+    assertProgramSpaceIdentity(expected.space);
+    if (instant.source.spaceId !== expected.space.id) {
+      throw new Error("Temporal Instant belongs to a different ProgramSpace.");
+    }
+    if (instant.frame > programSpaceFrameCount(expected.space)) {
+      throw new Error("Temporal Instant falls outside its ProgramSpace.");
+    }
+  }
+}
+
+/** Verify both endpoint provenance and the materialized span consumed by a domain program. */
+export function assertTemporalWindowFor(
+  window: TemporalWindow,
+  expected: TemporalConsumption,
+): void {
+  if (window.subjectId !== expected.subjectId
+    || window.start.subjectId !== expected.subjectId
+    || window.end.subjectId !== expected.subjectId) {
+    throw new Error(`Temporal Window subject ${window.subjectId} does not match ${expected.subjectId}.`);
+  }
+  assertTemporalInstantFor(window.start, expected);
+  assertTemporalInstantFor(window.end, expected);
+  if (window.start.source.spaceId !== window.end.source.spaceId) {
+    throw new Error("Temporal Window endpoints belong to different ProgramSpaces.");
+  }
+  if (window.span.startFrame !== window.start.frame
+    || window.span.endFrameExclusive !== window.end.frame
+    || window.span.endFrameExclusive <= window.span.startFrame) {
+    throw new Error("Temporal Window span disagrees with its endpoints.");
+  }
+}
+
+type InstantEnvironment = {
+  readonly program: LocatedProgram;
+  readonly selection?: LocatedSelection;
+  readonly moment?: LocatedMoment;
+  readonly segment?: LocatedSegment;
+};
+
+function evaluateInstant(
+  expression: TemporalInstantExpression,
+  environment: InstantEnvironment,
+  space: ProgramSpace,
+): Rational {
+  if (expression.ref === "absolute") {
+    const at = durationInFrames(expression.at, space);
+    return expression.offset === undefined ? at : add(at, durationInFrames(expression.offset, space));
+  }
+  let base: number;
+  switch (expression.ref) {
+    case "program.start": base = environment.program.start.frame; break;
+    case "program.end": base = environment.program.end.frame; break;
+    case "selection.start": {
+      if (environment.selection === undefined) throw new Error("selection.start requires a Selection.");
+      base = environment.selection.start.frame;
+      break;
+    }
+    case "selection.end": {
+      if (environment.selection === undefined) throw new Error("selection.end requires a Selection.");
+      base = environment.selection.end.frame;
+      break;
+    }
+    case "segment.start": {
+      if (environment.segment === undefined) throw new Error("segment.start requires a Segment.");
+      base = environment.segment.start.frame;
+      break;
+    }
+    case "segment.end": {
+      if (environment.segment === undefined) throw new Error("segment.end requires a Segment.");
+      base = environment.segment.end.frame;
+      break;
+    }
+    case "moment.cue": {
+      if (environment.moment === undefined) throw new Error("moment.cue requires a Moment.");
+      base = environment.moment.cue.frame;
+      break;
+    }
+  }
+  return expression.offset === undefined
+    ? rational(BigInt(base))
+    : add(rational(BigInt(base)), durationInFrames(expression.offset, space));
+}
+
+export function projectTemporalInstant(
+  projection: TemporalInstantExpression,
+  environment: InstantEnvironment,
+  space: ProgramSpace,
+): number {
+  assertProgramSpaceIdentity(space);
+  const totalFrames = programSpaceFrameCount(space);
+  const raw = evaluateInstant(projection, environment, space);
+  const lower = rational(0n);
+  const upper = rational(BigInt(totalFrames));
+  if (compare(raw, lower) < 0 || compare(raw, upper) > 0) {
+    throw new Error("Temporal Instant projection falls outside ProgramSpace.");
+  }
+  const frame = quantizeBoundary(raw);
+  if (frame < 0 || frame > totalFrames) {
+    throw new Error("Temporal Instant projection quantizes outside ProgramSpace.");
+  }
+  return frame;
+}
+
+function projectedId(itemId: string, sourceId: string): string {
+  if (itemId.length === 0) throw new Error("Projected item id must not be empty.");
+  return `${itemId}::${sourceId}`;
+}
+
+function projectedInstant(
+  spec: TemporalInstantSpec,
+  source: TemporalSource,
+  frame: number,
+): ProjectedInstant {
+  return {
+    id: projectedId(spec.id, source.id),
+    subjectId: spec.subjectId,
+    source: { ...source },
+    projection: structuredClone(spec.projection),
+    authority: structuredClone(spec.authority),
+    frame,
+  };
+}
+
+export function projectSelectionInstant(input: {
+  readonly itemId: string;
+  readonly subjectId: string;
+  readonly semantic: SemanticTrack;
+  readonly selection: NarrativeSelectionRef;
+  readonly projection: TemporalInstantExpression;
+  readonly authority: TemporalInstantSpec["authority"];
+}): ProjectedInstant {
+  const space = projectSemanticProgramSpace(input.semantic);
+  const program = locateProgram(input.semantic);
+  const selection = locateSelection(input.semantic, input.selection);
+  return projectedInstant(
+    { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
+    { spaceId: space.id, narrativeId: input.semantic.narrativeId, kind: "selection", id: selection.id },
+    projectTemporalInstant(input.projection, { program, selection }, space),
+  );
+}
+
+export function projectMomentInstant(input: {
+  readonly itemId: string;
+  readonly subjectId: string;
+  readonly semantic: SemanticTrack;
+  readonly moment: NarrativeMomentRef;
+  readonly projection: TemporalInstantExpression;
+  readonly authority: TemporalInstantSpec["authority"];
+}): ProjectedInstant {
+  const space = projectSemanticProgramSpace(input.semantic);
+  const program = locateProgram(input.semantic);
+  const moment = locateMoment(input.semantic, input.moment);
+  return projectedInstant(
+    { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
+    { spaceId: space.id, narrativeId: input.semantic.narrativeId, kind: "moment", id: moment.id },
+    projectTemporalInstant(input.projection, { program, moment }, space),
+  );
+}
+
+export function projectProgramInstant(input: {
+  readonly itemId: string;
+  readonly subjectId: string;
+  readonly space: ProgramSpace;
+  readonly projection: TemporalInstantExpression;
+  readonly authority: TemporalInstantSpec["authority"];
+}): ProjectedInstant {
+  const space = input.space;
+  const program = { id: "program" as const, start: { frame: 0 }, end: { frame: programSpaceFrameCount(space) } };
+  return projectedInstant(
+    { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
+    { spaceId: space.id, kind: "program", id: program.id },
+    projectTemporalInstant(input.projection, { program }, space),
+  );
+}
+
+export function projectSegmentInstant(input: {
+  readonly itemId: string;
+  readonly subjectId: string;
+  readonly semantic: SemanticTrack;
+  readonly segment: NarrativeExcerpt;
+  readonly projection: TemporalInstantExpression;
+  readonly authority: TemporalInstantSpec["authority"];
+}): ProjectedInstant {
+  const space = projectSemanticProgramSpace(input.semantic);
+  const program = locateProgram(input.semantic);
+  const segment = locateSegment(input.semantic, input.segment);
+  return projectedInstant(
+    { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
+    { spaceId: space.id, narrativeId: input.semantic.narrativeId, kind: "segment", id: segment.id },
+    projectTemporalInstant(input.projection, { program, segment }, space),
+  );
+}
+
+export function composeTemporalWindow(
+  spec: TemporalWindowSpec,
+  start: ProjectedInstant,
+  end: ProjectedInstant,
+): ProjectedWindow {
+  if (spec.id.length === 0) throw new Error("Temporal Window id must not be empty.");
+  if (!spec.subjectId || start.subjectId !== spec.subjectId || end.subjectId !== spec.subjectId) {
+    throw new Error("Temporal Window endpoints must explicitly name the Window subject.");
+  }
+  if (start.source.spaceId !== end.source.spaceId) {
+    throw new Error("Temporal Window endpoints must belong to one ProgramSpace.");
+  }
+  if (end.frame < start.frame) throw new Error("Temporal Window endpoints are reversed.");
+  if (end.frame === start.frame) throw new Error("Temporal Window endpoints produce a zero window.");
+  return {
+    id: spec.id,
+    subjectId: spec.subjectId,
+    start: structuredClone(start),
+    end: structuredClone(end),
+    span: { startFrame: start.frame, endFrameExclusive: end.frame },
+  };
+}
+
+export function assertWindowRelation(
+  windows: readonly ProjectedWindow[],
+  relation: WindowRelation,
+): readonly ProjectedWindow[] {
+  if (relation === "independent") return windows;
+  const ordered = [...windows].sort((left, right) =>
+    left.span.startFrame - right.span.startFrame
+    || left.span.endFrameExclusive - right.span.endFrameExclusive
+    || left.id.localeCompare(right.id));
+  for (let index = 1; index < ordered.length; index += 1) {
+    const previous = ordered[index - 1];
+    const current = ordered[index];
+    if (previous !== undefined && current !== undefined
+      && current.span.startFrame < previous.span.endFrameExclusive) {
+      throw new Error(`Temporal windows ${previous.id} and ${current.id} overlap under disjoint policy.`);
+    }
+  }
+  return windows;
+}

package/packages/temporal/src/rational.ts

@@ -0,0 +1,80 @@
+import type { ProgramSpace } from "@hypit/program-space";
+
+import type { TemporalDuration } from "./types.js";
+
+export type Rational = {
+  readonly numerator: bigint;
+  readonly denominator: bigint;
+};
+
+function divisor(left: bigint, right: bigint): bigint {
+  let a = left < 0n ? -left : left;
+  let b = right < 0n ? -right : right;
+  while (b !== 0n) [a, b] = [b, a % b];
+  return a;
+}
+
+export function rational(numerator: bigint, denominator = 1n): Rational {
+  if (denominator === 0n) throw new Error("Temporal rational denominator must not be zero.");
+  const sign = denominator < 0n ? -1n : 1n;
+  const normalizedNumerator = numerator * sign;
+  const normalizedDenominator = denominator * sign;
+  const gcd = divisor(normalizedNumerator, normalizedDenominator);
+  return {
+    numerator: normalizedNumerator / gcd,
+    denominator: normalizedDenominator / gcd,
+  };
+}
+
+export function add(left: Rational, right: Rational): Rational {
+  return rational(
+    left.numerator * right.denominator + right.numerator * left.denominator,
+    left.denominator * right.denominator,
+  );
+}
+
+export function compare(left: Rational, right: Rational): number {
+  const difference = left.numerator * right.denominator - right.numerator * left.denominator;
+  return difference < 0n ? -1 : difference > 0n ? 1 : 0;
+}
+
+export function maximum(left: Rational, right: Rational): Rational {
+  return compare(left, right) >= 0 ? left : right;
+}
+
+export function minimum(left: Rational, right: Rational): Rational {
+  return compare(left, right) <= 0 ? left : right;
+}
+
+function safeInteger(value: number, label: string): bigint {
+  if (!Number.isSafeInteger(value)) throw new Error(`${label} must be a safe integer.`);
+  return BigInt(value);
+}
+
+export function durationInFrames(duration: TemporalDuration, space: ProgramSpace): Rational {
+  const frameNumerator = safeInteger(space.frameRate.numerator, "ProgramSpace frame-rate numerator");
+  const frameDenominator = safeInteger(space.frameRate.denominator, "ProgramSpace frame-rate denominator");
+  switch (duration.unit) {
+    case "frames":
+      return rational(safeInteger(duration.value, "Frame duration"));
+    case "milliseconds":
+      return rational(
+        safeInteger(duration.value, "Millisecond duration") * frameNumerator,
+        1000n * frameDenominator,
+      );
+    case "seconds": {
+      const numerator = safeInteger(duration.numerator, "Second duration numerator");
+      const denominator = safeInteger(duration.denominator, "Second duration denominator");
+      if (denominator <= 0n) throw new Error("Second duration denominator must be positive.");
+      return rational(numerator * frameNumerator, denominator * frameDenominator);
+    }
+  }
+}
+
+/** Nearest frame boundary; an exact half lands on the later boundary. Input must be non-negative. */
+export function quantizeBoundary(value: Rational): number {
+  if (value.numerator < 0n) throw new Error("Cannot quantize a negative clipped frame boundary.");
+  const rounded = (value.numerator * 2n + value.denominator) / (value.denominator * 2n);
+  if (rounded > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("Temporal boundary exceeds safe frame arithmetic.");
+  return Number(rounded);
+}

package/packages/temporal/src/sample.ts

@@ -0,0 +1,43 @@
+import type { ProgramSpace } from "@hypit/program-space";
+
+import type { TemporalDuration } from "./types.js";
+
+function integer(value: number, label: string): bigint {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${label} must be a non-negative safe integer.`);
+  return BigInt(value);
+}
+
+function roundedRatio(numerator: bigint, denominator: bigint, label: string): number {
+  if (denominator <= 0n) throw new Error(`${label} denominator must be positive.`);
+  const value = (numerator * 2n + denominator) / (denominator * 2n);
+  if (value < 0n || value > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error(`${label} exceeds safe sample arithmetic.`);
+  }
+  return Number(value);
+}
+
+/** Quantize one non-negative authored duration into the canonical sample domain exactly once. */
+export function temporalDurationInSamples(
+  duration: TemporalDuration,
+  space: ProgramSpace,
+  sampleRate = 48_000,
+): number {
+  const rate = integer(sampleRate, "Sample rate");
+  if (rate === 0n) throw new Error("Sample rate must be positive.");
+  switch (duration.unit) {
+    case "frames":
+      return roundedRatio(
+        integer(duration.value, "Frame duration") * rate * integer(space.frameRate.denominator, "Frame-rate denominator"),
+        integer(space.frameRate.numerator, "Frame-rate numerator"),
+        "Frame duration",
+      );
+    case "milliseconds":
+      return roundedRatio(integer(duration.value, "Millisecond duration") * rate, 1_000n, "Millisecond duration");
+    case "seconds":
+      return roundedRatio(
+        integer(duration.numerator, "Second duration numerator") * rate,
+        integer(duration.denominator, "Second duration denominator"),
+        "Second duration",
+      );
+  }
+}

package/packages/temporal/src/schedule.ts

@@ -0,0 +1,52 @@
+import type { FrameSpan, TriggerPoint, TriggeredSchedule } from "./types.js";
+
+function assertFrame(frame: number, label: string): void {
+  if (!Number.isSafeInteger(frame) || frame < 0) throw new Error(`${label} must be a non-negative frame.`);
+}
+
+function assertSpan(span: FrameSpan): void {
+  assertFrame(span.startFrame, "Triggered schedule outer start");
+  assertFrame(span.endFrameExclusive, "Triggered schedule outer end");
+  if (span.endFrameExclusive <= span.startFrame) throw new Error("Triggered schedule outer window is empty.");
+}
+
+export function resolveTriggeredSchedule(input: {
+  readonly outer: FrameSpan;
+  readonly terminalFrame: number;
+  readonly triggers: readonly TriggerPoint[];
+}): TriggeredSchedule {
+  assertSpan(input.outer);
+  assertFrame(input.terminalFrame, "Triggered schedule terminal");
+  if (input.triggers.length === 0) throw new Error("Triggered schedule requires at least one trigger.");
+  if (input.terminalFrame > input.outer.endFrameExclusive) {
+    throw new Error("Triggered schedule terminal is after the outer window.");
+  }
+  const ids = new Set<string>();
+  let previousFrame: number | undefined;
+  for (const trigger of input.triggers) {
+    if (trigger.id.length === 0 || ids.has(trigger.id)) throw new Error("Triggered schedule ids must be non-empty and unique.");
+    ids.add(trigger.id);
+    assertFrame(trigger.frame, `Triggered schedule ${trigger.id}`);
+    if (trigger.frame < input.outer.startFrame || trigger.frame >= input.terminalFrame) {
+      throw new Error(`Triggered schedule ${trigger.id} is outside [outer.start, terminal).`);
+    }
+    if (previousFrame !== undefined && trigger.frame <= previousFrame) {
+      throw new Error("Triggered schedule points must be strictly increasing in authored order.");
+    }
+    previousFrame = trigger.frame;
+  }
+  const cumulative = input.triggers.map((trigger) => ({
+    startFrame: trigger.frame,
+    endFrameExclusive: input.outer.endFrameExclusive,
+  }));
+  const exclusive = input.triggers.map((trigger, index) => ({
+    startFrame: trigger.frame,
+    endFrameExclusive: input.triggers[index + 1]?.frame ?? input.terminalFrame,
+  }));
+  return {
+    outer: { ...input.outer },
+    terminalFrame: input.terminalFrame,
+    cumulative,
+    exclusive,
+  };
+}