@cueframe/kernel 0.0.1

package/dist/_members/composition/invariants/etag.d.ts

@@ -0,0 +1,10 @@
+import type { Composition } from "../validators/composition.js";
+/**
+ * Canonicalize an object for deterministic hashing:
+ * - object keys sorted lexicographically at every depth
+ * - arrays preserve order
+ * - undefined fields dropped (JSON semantics)
+ * - null / number / string / boolean preserved as-is
+ */
+export declare function canonicalJSON(value: unknown): string;
+export declare function etag(composition: Composition): string;

package/dist/_members/composition/invariants/etag.js

@@ -0,0 +1,38 @@
+// Pure-JS SHA-256 (no `node:crypto`) so this module bundles into Convex's V8
+// isolate — importing it transitively (via the invariants barrel) previously
+// broke `npx convex deploy` with "Could not resolve node:crypto". @noble/hashes
+// is sync + dependency-free and its output is byte-identical to node's
+// createHash("sha256").update(utf8).digest("hex"), so every existing etag /
+// If-Match (OCC) value is unchanged. (Pairs with projection.ts's inlined computeEtag.)
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex } from "@noble/hashes/utils";
+/**
+ * Canonicalize an object for deterministic hashing:
+ * - object keys sorted lexicographically at every depth
+ * - arrays preserve order
+ * - undefined fields dropped (JSON semantics)
+ * - null / number / string / boolean preserved as-is
+ */
+export function canonicalJSON(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function canonicalize(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    const out = {};
+    const keys = Object.keys(value).sort();
+    for (const key of keys) {
+        const v = value[key];
+        if (v === undefined)
+            continue;
+        out[key] = canonicalize(v);
+    }
+    return out;
+}
+export function etag(composition) {
+    const canonical = canonicalJSON(composition);
+    const hash = bytesToHex(sha256(new TextEncoder().encode(canonical)));
+    return `"${hash}"`;
+}

package/dist/_members/composition/invariants/ids.d.ts

@@ -0,0 +1,9 @@
+import type { Composition } from "../validators/composition.js";
+import type { InvariantViolation } from "./errors.js";
+/**
+ * Entity ids share a single namespace within the Composition.
+ * TimelineClip.id, Track.id, Gap.id, Marker.id must all be unique.
+ *
+ * composition_id_collision { existingKind, newKind, id }
+ */
+export declare function checkIdCollisions(composition: Composition): InvariantViolation[];

package/dist/_members/composition/invariants/ids.js

@@ -0,0 +1,33 @@
+/**
+ * Entity ids share a single namespace within the Composition.
+ * TimelineClip.id, Track.id, Gap.id, Marker.id must all be unique.
+ *
+ * composition_id_collision { existingKind, newKind, id }
+ */
+export function checkIdCollisions(composition) {
+    const seen = new Map();
+    const out = [];
+    const record = (id, kind) => {
+        const existing = seen.get(id);
+        if (existing) {
+            out.push({
+                code: "composition_id_collision",
+                message: `Id ${id} used by both ${existing} and ${kind}`,
+                details: { id, existingKind: existing, newKind: kind },
+            });
+        }
+        else {
+            seen.set(id, kind);
+        }
+    };
+    for (const track of composition.tracks) {
+        record(track.id, "track");
+        for (const content of track.contents) {
+            record(content.id, "source" in content ? "clip" : "gap");
+        }
+    }
+    for (const marker of composition.markers ?? []) {
+        record(marker.id, "marker");
+    }
+    return out;
+}

package/dist/_members/composition/invariants/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./errors.js";
+export * from "./etag.js";
+export * from "./tracks.js";
+export * from "./markers.js";
+export * from "./ids.js";
+export * from "./keyframes.js";
+export * from "./composition.js";
+export * from "./time.js";
+export * from "./clipPlacement.js";

package/dist/_members/composition/invariants/index.js

@@ -0,0 +1,9 @@
+export * from "./errors";
+export * from "./etag";
+export * from "./tracks";
+export * from "./markers";
+export * from "./ids";
+export * from "./keyframes";
+export * from "./composition";
+export * from "./time";
+export * from "./clipPlacement.js";

package/dist/_members/composition/invariants/keyframes.d.ts

@@ -0,0 +1,23 @@
+/**
+ * KEYFRAME INVARIANTS — the producers for two error codes that had none.
+ *
+ * `varying_keyframe_time_out_of_range` and `varying_keyframe_duplicate_time`
+ * have been in `errors.ts` since before the composition had any keyframe model
+ * at all. A `grep` for either returned exactly one hit each: their own
+ * declaration. Somebody knew what the failures would be before there was
+ * anything that could fail. This file is the other half.
+ *
+ * Both rules exist because of what clip-relative time makes possible:
+ *
+ *   OUT OF RANGE — a keyframe past the clip's duration is unreachable. It is
+ *   not harmless: trim a clip shorter and its tail keyframes silently stop
+ *   mattering, so the motion the author saw is not the motion that ships, with
+ *   nothing in the document looking wrong.
+ *
+ *   DUPLICATE TIME — two values at one instant have no defined result. The
+ *   interpolator would pick by sort order, which is not a decision anyone made.
+ */
+import type { Composition, TimelineClip } from "../validators/composition.js";
+import type { InvariantViolation } from "./errors.js";
+export declare function checkClipKeyframes(clip: TimelineClip): InvariantViolation[];
+export declare function checkKeyframes(composition: Composition): InvariantViolation[];

package/dist/_members/composition/invariants/keyframes.js

@@ -0,0 +1,45 @@
+/** Float slack — two keyframes closer than this are the same instant. */
+const TIME_EPSILON = 1e-6;
+export function checkClipKeyframes(clip) {
+    const animate = clip.animate;
+    if (!animate)
+        return [];
+    const violations = [];
+    for (const [param, channel] of Object.entries(animate)) {
+        if (!channel)
+            continue;
+        const sorted = [...channel].sort((a, b) => a.time - b.time);
+        for (const kf of sorted) {
+            if (kf.time > clip.duration + TIME_EPSILON) {
+                violations.push({
+                    code: "varying_keyframe_time_out_of_range",
+                    message: `clip "${clip.id}" animates "${param}" at ${kf.time}s, past its own ` +
+                        `duration of ${clip.duration}s — that keyframe can never be reached`,
+                    details: { clipId: clip.id, param, time: kf.time, duration: clip.duration },
+                });
+            }
+        }
+        for (let i = 1; i < sorted.length; i++) {
+            if (Math.abs(sorted[i].time - sorted[i - 1].time) < TIME_EPSILON) {
+                violations.push({
+                    code: "varying_keyframe_duplicate_time",
+                    message: `clip "${clip.id}" has two "${param}" keyframes at ${sorted[i].time}s — ` +
+                        `the value at that instant is undefined`,
+                    details: { clipId: clip.id, param, time: sorted[i].time },
+                });
+            }
+        }
+    }
+    return violations;
+}
+export function checkKeyframes(composition) {
+    const violations = [];
+    for (const track of composition.tracks) {
+        for (const item of track.contents) {
+            if (!("source" in item))
+                continue;
+            violations.push(...checkClipKeyframes(item));
+        }
+    }
+    return violations;
+}

package/dist/_members/composition/invariants/markers.d.ts

@@ -0,0 +1,9 @@
+import type { Composition } from "../validators/composition.js";
+import type { InvariantViolation } from "./errors.js";
+/**
+ * Markers with `kind: 'scene'` cannot overlap (single-partition rule).
+ * Other kinds (chapter, note, agent, custom) are free to overlap.
+ *
+ * scene_marker_overlap { markerAId, markerBId, overlapRange }
+ */
+export declare function checkSceneMarkerPartition(composition: Composition): InvariantViolation[];

package/dist/_members/composition/invariants/markers.js

@@ -0,0 +1,29 @@
+const end = (m) => m.endTime ?? m.startTime;
+/**
+ * Markers with `kind: 'scene'` cannot overlap (single-partition rule).
+ * Other kinds (chapter, note, agent, custom) are free to overlap.
+ *
+ * scene_marker_overlap { markerAId, markerBId, overlapRange }
+ */
+export function checkSceneMarkerPartition(composition) {
+    const scenes = (composition.markers ?? [])
+        .filter((m) => m.kind === "scene")
+        .sort((a, b) => a.startTime - b.startTime);
+    const out = [];
+    for (let i = 1; i < scenes.length; i++) {
+        const prev = scenes[i - 1];
+        const cur = scenes[i];
+        if (cur.startTime < end(prev)) {
+            out.push({
+                code: "scene_marker_overlap",
+                message: `Scene markers ${prev.id} and ${cur.id} overlap at [${cur.startTime}, ${Math.min(end(prev), end(cur))})`,
+                details: {
+                    markerAId: prev.id,
+                    markerBId: cur.id,
+                    overlapRange: [cur.startTime, Math.min(end(prev), end(cur))],
+                },
+            });
+        }
+    }
+    return out;
+}

package/dist/_members/composition/invariants/time.d.ts

@@ -0,0 +1,22 @@
+/**
+ * OTIO / native-renderer time quantization rule.
+ * See data-model.md §OTIO time export rule and §Native renderer time quantization.
+ */
+export declare function otioFrames(seconds: number, fps: number): number;
+export interface RationalTime {
+    value: number;
+    rate: number;
+}
+export declare function otioRationalTime(seconds: number, fps: number): RationalTime;
+/**
+ * Per-output-frame source-frame mapping (renderer contract).
+ * Matches the OTIO writer's quantization at the boundary.
+ */
+export declare function sourceFrame(params: {
+    outputFrame: number;
+    formatFps: number;
+    clipStartTime: number;
+    trimStart: number;
+    playbackRate: number;
+    sourceFps: number;
+}): number;

package/dist/_members/composition/invariants/time.js

@@ -0,0 +1,20 @@
+/**
+ * OTIO / native-renderer time quantization rule.
+ * See data-model.md §OTIO time export rule and §Native renderer time quantization.
+ */
+export function otioFrames(seconds, fps) {
+    return Math.round(seconds * fps);
+}
+export function otioRationalTime(seconds, fps) {
+    return { value: Math.round(seconds * fps), rate: fps };
+}
+/**
+ * Per-output-frame source-frame mapping (renderer contract).
+ * Matches the OTIO writer's quantization at the boundary.
+ */
+export function sourceFrame(params) {
+    const { outputFrame, formatFps, clipStartTime, trimStart, playbackRate, sourceFps } = params;
+    const outSeconds = outputFrame / formatFps;
+    const sourceSeconds = trimStart + (outSeconds - clipStartTime) * playbackRate;
+    return Math.round(sourceSeconds * sourceFps);
+}

package/dist/_members/composition/invariants/tracks.d.ts

@@ -0,0 +1,58 @@
+import type { TimelineClip, Track, Composition } from "../validators/composition.js";
+import type { InvariantViolation } from "./errors.js";
+/**
+ * Clips and Gaps on a single Track cannot overlap.
+ * track_clips_overlap { trackId, clipAId, clipBId, overlapRange }
+ */
+export declare function checkTrackContentsNoOverlap(track: Track): InvariantViolation[];
+/**
+ * A TimelineClip.source.kind must match Track.kind per the compatibility table.
+ * clip_source_track_kind_mismatch { trackId, clipId, sourceKind, trackKind }
+ */
+export declare function checkClipSourceTrackKind(track: Track): InvariantViolation[];
+export declare function isSourceKindCompatible(trackKind: Track["kind"], sourceKind: TimelineClip["source"]["kind"]): boolean;
+/**
+ * A TimelineClip with transitionIn must have a contiguous TimelineClip predecessor on the
+ * same Track (no Gap, not first element).
+ *
+ * transition_no_predecessor { trackId, clipId }
+ * transition_too_long       { trackId, clipId, transitionDuration, available }
+ */
+export declare function checkTransitions(track: Track): InvariantViolation[];
+/**
+ * For each TimelineClip with a media source carrying excludedRanges, verify:
+ *   - each range has end > start
+ *   - every range is within the source trim window (or [0, duration] when trim absent)
+ *   - ranges are sorted and non-overlapping
+ *   - clip.duration === (trimEnd - trimStart) - Σ excluded, within float tolerance (1e-3)
+ *
+ * Coordinate space: source coordinates (same as `trim`).
+ *
+ * excluded_range_invalid             { trackId, clipId, index, start, end }
+ * excluded_range_out_of_bounds       { trackId, clipId, index, start, end, trimStart, trimEnd }
+ * excluded_range_overlap             { trackId, clipId, index, start, prevEnd }
+ * excluded_range_duration_mismatch   { trackId, clipId, expected, actual, trimSpan, totalExcluded }
+ */
+export declare function checkExcludedRanges(track: Track): InvariantViolation[];
+/** Combined per-track invariants. */
+/**
+ * A media clip's `duration` must equal its trimmed source span divided by its
+ * playback rate — for clips that have NO excluded ranges.
+ *
+ * `checkExcludedRanges` computes exactly this relationship, but returns early on
+ * `if (!ranges || ranges.length === 0) continue`, so it only ever runs for clips
+ * that HAVE excluded ranges. A plainly-trimmed clip whose duration disagrees
+ * with its trim is therefore unchecked. This closes that gap; the two together
+ * cover every media clip.
+ *
+ * HONEST PROVENANCE: found while chasing a suspected corruption that turned out
+ * not to be one. A project showed `duration 2.4` against `trim {0, 3.4}`, which
+ * looked inconsistent until the clip's `excludedRanges` ([1.9, 2.9]) accounted
+ * for exactly the difference. The composition was fine and the existing check
+ * passed it correctly. No known production case violates THIS rule — it is here
+ * because the coverage hole is real, not because a bug was seen through it.
+ */
+export declare function checkClipDurationMatchesTrim(track: Track): InvariantViolation[];
+export declare function checkTrack(track: Track): InvariantViolation[];
+/** Combined per-composition invariants that live at the Track level. */
+export declare function checkTracks(composition: Composition): InvariantViolation[];

package/dist/_members/composition/invariants/tracks.js

@@ -0,0 +1,304 @@
+function isTimelineClip(c) {
+    return "source" in c;
+}
+function end(c) {
+    return c.startTime + c.duration;
+}
+/**
+ * Clips and Gaps on a single Track cannot overlap.
+ * track_clips_overlap { trackId, clipAId, clipBId, overlapRange }
+ */
+export function checkTrackContentsNoOverlap(track) {
+    const violations = [];
+    const sorted = [...track.contents].sort((a, b) => a.startTime - b.startTime);
+    for (let i = 1; i < sorted.length; i++) {
+        const prev = sorted[i - 1];
+        const cur = sorted[i];
+        if (cur.startTime < end(prev)) {
+            violations.push({
+                code: "track_clips_overlap",
+                message: `Track ${track.id}: items ${prev.id} and ${cur.id} overlap at [${cur.startTime}, ${Math.min(end(prev), end(cur))})`,
+                details: {
+                    trackId: track.id,
+                    clipAId: prev.id,
+                    clipBId: cur.id,
+                    overlapRange: [cur.startTime, Math.min(end(prev), end(cur))],
+                },
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * A TimelineClip.source.kind must match Track.kind per the compatibility table.
+ * clip_source_track_kind_mismatch { trackId, clipId, sourceKind, trackKind }
+ */
+export function checkClipSourceTrackKind(track) {
+    const violations = [];
+    for (const content of track.contents) {
+        if (!isTimelineClip(content))
+            continue;
+        const ok = isSourceKindCompatible(track.kind, content.source.kind);
+        if (!ok) {
+            violations.push({
+                code: "clip_source_track_kind_mismatch",
+                message: `Track ${track.id} (kind=${track.kind}) cannot hold TimelineClip ${content.id} (source.kind=${content.source.kind})`,
+                details: {
+                    trackId: track.id,
+                    clipId: content.id,
+                    sourceKind: content.source.kind,
+                    trackKind: track.kind,
+                },
+            });
+        }
+    }
+    return violations;
+}
+export function isSourceKindCompatible(trackKind, sourceKind) {
+    switch (trackKind) {
+        case "video":
+            // `composition` = a compound clip; its content is video-family by
+            // definition (it flattens to the child's tracks at projection).
+            return sourceKind === "media" || sourceKind === "component" || sourceKind === "composition";
+        case "audio":
+            return sourceKind === "media" || sourceKind === "component";
+        case "image":
+            // Image tracks carry stills via `kind: "media"`. The renderer
+            // resolves them via <StillFrame>, distinct from <Video>. Component
+            // sources are also allowed for parity with video/audio (e.g. a
+            // future "synthetic still" primitive).
+            return sourceKind === "media" || sourceKind === "component";
+        case "overlay":
+            // alpha-layer (a baked-alpha component) and card (authored static graphic)
+            // composite on the overlay track too — keep in lockstep with the server's
+            // clipTrackFamilyIssue (services/convex/composition/projection.ts) and
+            // AUTHORED_GRAPHIC_KINDS (validators/composition.ts).
+            return (sourceKind === "overlay" ||
+                sourceKind === "component" ||
+                sourceKind === "alpha-layer" ||
+                sourceKind === "card");
+        case "effect":
+            return sourceKind === "effect";
+    }
+}
+/**
+ * A TimelineClip with transitionIn must have a contiguous TimelineClip predecessor on the
+ * same Track (no Gap, not first element).
+ *
+ * transition_no_predecessor { trackId, clipId }
+ * transition_too_long       { trackId, clipId, transitionDuration, available }
+ */
+export function checkTransitions(track) {
+    const violations = [];
+    const sorted = [...track.contents].sort((a, b) => a.startTime - b.startTime);
+    for (let i = 0; i < sorted.length; i++) {
+        const cur = sorted[i];
+        if (!isTimelineClip(cur) || !cur.transitionIn)
+            continue;
+        const prev = sorted[i - 1];
+        if (!prev || !isTimelineClip(prev)) {
+            violations.push({
+                code: "transition_no_predecessor",
+                message: `Track ${track.id}: TimelineClip ${cur.id} has transitionIn but no TimelineClip predecessor`,
+                details: { trackId: track.id, clipId: cur.id },
+            });
+            continue;
+        }
+        const d = cur.transitionIn.duration;
+        const headroom = Math.min(prev.duration, cur.duration);
+        if (d > headroom) {
+            violations.push({
+                code: "transition_too_long",
+                message: `Track ${track.id}: TimelineClip ${cur.id} transitionIn.duration (${d}) exceeds available headroom (${headroom})`,
+                details: {
+                    trackId: track.id,
+                    clipId: cur.id,
+                    transitionDuration: d,
+                    available: headroom,
+                },
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * For each TimelineClip with a media source carrying excludedRanges, verify:
+ *   - each range has end > start
+ *   - every range is within the source trim window (or [0, duration] when trim absent)
+ *   - ranges are sorted and non-overlapping
+ *   - clip.duration === (trimEnd - trimStart) - Σ excluded, within float tolerance (1e-3)
+ *
+ * Coordinate space: source coordinates (same as `trim`).
+ *
+ * excluded_range_invalid             { trackId, clipId, index, start, end }
+ * excluded_range_out_of_bounds       { trackId, clipId, index, start, end, trimStart, trimEnd }
+ * excluded_range_overlap             { trackId, clipId, index, start, prevEnd }
+ * excluded_range_duration_mismatch   { trackId, clipId, expected, actual, trimSpan, totalExcluded }
+ */
+export function checkExcludedRanges(track) {
+    const violations = [];
+    for (const content of track.contents) {
+        if (!isTimelineClip(content))
+            continue;
+        if (content.source.kind !== "media")
+            continue;
+        const ranges = content.source.excludedRanges;
+        if (!ranges || ranges.length === 0)
+            continue;
+        const trim = content.source.trim;
+        const trimStart = trim?.start ?? 0;
+        // When trim is absent, source coordinates collapse to [0, duration] (1:1).
+        const trimEnd = trim?.end ?? trimStart + content.duration;
+        let prevEnd = -Infinity;
+        let total = 0;
+        let earlyExit = false;
+        for (let i = 0; i < ranges.length; i++) {
+            const r = ranges[i];
+            if (r.end <= r.start) {
+                violations.push({
+                    code: "excluded_range_invalid",
+                    message: `Track ${track.id}: TimelineClip ${content.id} excludedRanges[${i}] end (${r.end}) must be > start (${r.start})`,
+                    details: {
+                        trackId: track.id,
+                        clipId: content.id,
+                        index: i,
+                        start: r.start,
+                        end: r.end,
+                    },
+                });
+                earlyExit = true;
+                break;
+            }
+            if (r.start < trimStart || r.end > trimEnd) {
+                violations.push({
+                    code: "excluded_range_out_of_bounds",
+                    message: `Track ${track.id}: TimelineClip ${content.id} excludedRanges[${i}] [${r.start}, ${r.end}] outside trim [${trimStart}, ${trimEnd}]`,
+                    details: {
+                        trackId: track.id,
+                        clipId: content.id,
+                        index: i,
+                        start: r.start,
+                        end: r.end,
+                        trimStart,
+                        trimEnd,
+                    },
+                });
+                earlyExit = true;
+                break;
+            }
+            if (r.start < prevEnd) {
+                violations.push({
+                    code: "excluded_range_overlap",
+                    message: `Track ${track.id}: TimelineClip ${content.id} excludedRanges[${i}] overlaps preceding range (start ${r.start} < prevEnd ${prevEnd})`,
+                    details: {
+                        trackId: track.id,
+                        clipId: content.id,
+                        index: i,
+                        start: r.start,
+                        prevEnd,
+                    },
+                });
+                earlyExit = true;
+                break;
+            }
+            prevEnd = r.end;
+            total += r.end - r.start;
+        }
+        if (earlyExit)
+            continue;
+        const trimSpan = trimEnd - trimStart;
+        const expectedDuration = trimSpan - total;
+        // Tolerate float-roundoff at the millisecond level — wire is in seconds and
+        // editor / agent ops compute these with float math.
+        if (Math.abs(expectedDuration - content.duration) > 1e-3) {
+            violations.push({
+                code: "excluded_range_duration_mismatch",
+                message: `Track ${track.id}: TimelineClip ${content.id} duration (${content.duration}) ≠ trimSpan (${trimSpan}) − Σexcluded (${total}) = ${expectedDuration}`,
+                details: {
+                    trackId: track.id,
+                    clipId: content.id,
+                    expected: expectedDuration,
+                    actual: content.duration,
+                    trimSpan,
+                    totalExcluded: total,
+                },
+            });
+        }
+    }
+    return violations;
+}
+/** Combined per-track invariants. */
+/**
+ * A media clip's `duration` must equal its trimmed source span divided by its
+ * playback rate — for clips that have NO excluded ranges.
+ *
+ * `checkExcludedRanges` computes exactly this relationship, but returns early on
+ * `if (!ranges || ranges.length === 0) continue`, so it only ever runs for clips
+ * that HAVE excluded ranges. A plainly-trimmed clip whose duration disagrees
+ * with its trim is therefore unchecked. This closes that gap; the two together
+ * cover every media clip.
+ *
+ * HONEST PROVENANCE: found while chasing a suspected corruption that turned out
+ * not to be one. A project showed `duration 2.4` against `trim {0, 3.4}`, which
+ * looked inconsistent until the clip's `excludedRanges` ([1.9, 2.9]) accounted
+ * for exactly the difference. The composition was fine and the existing check
+ * passed it correctly. No known production case violates THIS rule — it is here
+ * because the coverage hole is real, not because a bug was seen through it.
+ */
+export function checkClipDurationMatchesTrim(track) {
+    const violations = [];
+    for (const content of track.contents) {
+        if (!isTimelineClip(content))
+            continue;
+        if (content.source.kind !== "media")
+            continue;
+        const trim = content.source.trim;
+        // No trim ⇒ source coordinates collapse to [0, duration] and the identity is
+        // vacuous; there is nothing to disagree with.
+        if (!trim)
+            continue;
+        const rate = content.source.playbackRate ?? 1;
+        if (!(rate > 0))
+            continue; // `playbackRate` is validated positive elsewhere
+        // Excluded ranges legitimately shorten the clip below its trim span, and
+        // `checkExcludedRanges` already owns that arithmetic. Do not double-report.
+        const excluded = content.source.excludedRanges;
+        if (excluded && excluded.length > 0)
+            continue;
+        const trimSpan = trim.end - trim.start;
+        const expected = trimSpan / rate;
+        if (Math.abs(expected - content.duration) > 1e-3) {
+            violations.push({
+                code: "clip_duration_trim_mismatch",
+                message: `Track ${track.id}: TimelineClip ${content.id} duration (${content.duration}) ≠ ` +
+                    `trimSpan (${trimSpan}) ÷ playbackRate (${rate}) = ${expected}`,
+                details: {
+                    trackId: track.id,
+                    clipId: content.id,
+                    expected,
+                    actual: content.duration,
+                    trimSpan,
+                    playbackRate: rate,
+                },
+            });
+        }
+    }
+    return violations;
+}
+export function checkTrack(track) {
+    return [
+        ...checkTrackContentsNoOverlap(track),
+        ...checkClipSourceTrackKind(track),
+        ...checkTransitions(track),
+        ...checkExcludedRanges(track),
+        ...checkClipDurationMatchesTrim(track),
+    ];
+}
+/** Combined per-composition invariants that live at the Track level. */
+export function checkTracks(composition) {
+    const out = [];
+    for (const track of composition.tracks) {
+        out.push(...checkTrack(track));
+    }
+    return out;
+}