@cueframe/kernel 0.0.1

package/dist/_members/perception/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @cueframe/perception — facts + assets.
+ *
+ * Owns: the subject track (faces, active speaker, dims), the silhouette matte,
+ * the transcript — decision-free measurements derived from the source.
+ * MUST NOT: choose anything (no framing, no "good enough" gate); zero editorial
+ * intent.
+ * Allowed dependencies: NONE (this is a leaf).
+ *
+ * SSOT for the SOURCE-COORDS perception facts — what the detector saw, in the
+ * source video's coordinate space. This is the one home for these shapes; the
+ * director's detect/derive code imports them from here (was re-declared inline).
+ *
+ * DISTINCT from composition's OUTPUT-coords layout shape
+ * (`@cueframe/composition/projection` `Subject` / `FaceBoxOutput` = crop∘face,
+ * a render-layout resolution). Those legitimately differ (different coordinate
+ * space) and the `composition-is-a-leaf` gate forbids composition→perception, so
+ * they must NOT be unified. The Python detector (the backend services_subjects.py,
+ * person_matting.py) is the IMPLEMENTATION of this contract; it emits JSON matching
+ * these shapes, cached on `mediaItems.subjectTracks` (Convex).
+ */
+import type { PersonEmbedding } from './identityMatch.js';
+/** A PIXEL face box `[x1, y1, x2, y2]` in source-pixel coordinates (corner form).
+ *  Consumers normalize by the track's `srcW`/`srcH` (see `subjectSet.ts`,
+ *  `resolver.ts#angleProminenceSignals`). */
+export type FaceBox = [number, number, number, number];
+/** A normalized face detection — `{x,y,width,height}` in [0,1] vs source dims
+ *  (matches the dicts STAGE B builds from the tracker output). */
+export interface Face {
+    faceId?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * One tracked subject's source-level per-frame face boxes + active windows, as
+ * emitted by Modal `detect_subjects` (STAGE A) and cached on
+ * `mediaItems.subjectTracks`. Frame 0 of `perFrameTracked` = `window.startSec`.
+ * This is the contract `detect_subjects` MUST emit.
+ */
+export interface SubjectTrack {
+    detectorVersion: string;
+    srcW: number;
+    srcH: number;
+    srcFps: number;
+    window: {
+        startSec: number;
+        endSec: number;
+    };
+    /** Per-frame `{faceId: [x1,y1,x2,y2]}` pixel bboxes, window-local. */
+    perFrameTracked: Array<Record<string, FaceBox>>;
+    /** `{frameOffset: faceId}` active-speaker picks (sparse), window-local
+     *  offsets as string keys (JSON). */
+    perKeyframeSpeaker: Record<string, string>;
+    /** Window-local frame indices where a NEW shot begins (hard cuts) — the
+     *  detector's HSV-histogram scene-cut boundaries. The first shot starts at
+     *  frame 0 and is excluded, so this lists only interior cuts (each > 0). The
+     *  crop derivation snaps its EMA EXACTLY at these frames instead of inferring
+     *  cuts from face-center jumps. Optional: tracks detected before the
+     *  shots-aware detector version omit it (the derivation degrades to the
+     *  jump-threshold inference). */
+    shotBoundaries?: number[];
+    /** Per-person MEDIAN ArcFace embedding (L2-normalized) for cross-source identity
+     *  (selector-abstraction §4 + §9.1 P6, `lockPersonId`). One entry per consolidated
+     *  person id; the SAME person across angles is matched by cosine over these. The
+     *  detector ALREADY computes per-id ArcFace embeddings for the appearance-merge
+     *  (`scrfd_track.consolidate_tracks`) — they were computed-then-discarded; P6
+     *  persists the median here (`+DETECTOR_VERSION`). Optional: tracks detected before
+     *  the P6 detector bump omit it (a `lockPersonId` switch then fails loud
+     *  `selector_identity_detector_version_mismatch` rather than guessing). */
+    personEmbeddings?: PersonEmbedding[];
+}
+/** One detected face in the roster surfaced to the editor (face-0..N), with an
+ *  optional speaking share. `bbox` is normalized [0,1] vs source dims. */
+export interface SubjectFace {
+    faceId: string;
+    bbox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    speakingShare?: number;
+}
+export { AUDIO_QUALITY_VERSION, audioQualitySignal, type AudioQualityMetrics, type AudioQualitySignal, } from './audioQuality.js';
+export { ACTIVE_SPEAKER_VERSION, activeSpeakerSignal, type ActiveSpeakerSeries, type ActiveSpeakerSignal, } from './activeSpeaker.js';
+export { ENERGY_BEAT_VERSION, energyBeatSignal, type EnergyBeatSeries, type EnergyBeatSignal, } from './energyBeat.js';
+export { VISUAL_QUALITY_VERSION, visualQualitySignal, type VisualQualityMetrics, type VisualQualitySignal, } from './visualQuality.js';
+export { IDENTITY_MATCH_VERSION, IDENTITY_MATCH_COSINE, cosineSimilarity, matchPerson, type PersonEmbedding, type IdentityMatchResult, } from './identityMatch.js';

package/dist/_members/perception/index.js

@@ -0,0 +1,48 @@
+/**
+ * @cueframe/perception — facts + assets.
+ *
+ * Owns: the subject track (faces, active speaker, dims), the silhouette matte,
+ * the transcript — decision-free measurements derived from the source.
+ * MUST NOT: choose anything (no framing, no "good enough" gate); zero editorial
+ * intent.
+ * Allowed dependencies: NONE (this is a leaf).
+ *
+ * SSOT for the SOURCE-COORDS perception facts — what the detector saw, in the
+ * source video's coordinate space. This is the one home for these shapes; the
+ * director's detect/derive code imports them from here (was re-declared inline).
+ *
+ * DISTINCT from composition's OUTPUT-coords layout shape
+ * (`@cueframe/composition/projection` `Subject` / `FaceBoxOutput` = crop∘face,
+ * a render-layout resolution). Those legitimately differ (different coordinate
+ * space) and the `composition-is-a-leaf` gate forbids composition→perception, so
+ * they must NOT be unified. The Python detector (services/modal/.../detect_subjects.py,
+ * person_matting.py) is the IMPLEMENTATION of this contract; it emits JSON matching
+ * these shapes, cached on `mediaItems.subjectTracks` (Convex).
+ */
+// ── audioQuality signal provider (per-source audio fact; spec §1.2 + §9.1 P2) ──
+// The PURE fact calibration only — the ffmpeg/Modal MEASUREMENT that produces an
+// AudioQualityMetrics lives outside this leaf (the switch resolver's processing
+// helper), so perception stays node-free.
+export { AUDIO_QUALITY_VERSION, audioQualitySignal, } from './audioQuality';
+// ── activeSpeaker signal provider (per-angle AV-ASD fact; spec §1.2 + §9.1 P3) ──
+// The PURE fact calibration only — the TalkNet/Light-ASD MEASUREMENT that produces
+// an ActiveSpeakerSeries lives in the Modal skill (detect_active_speaker.py), so
+// perception stays node-free + model-dep-free (the leaf rule).
+export { ACTIVE_SPEAKER_VERSION, activeSpeakerSignal, } from './activeSpeaker';
+// ── energyBeat signal provider (per-source motion/dynamics fact; spec §1.2 + §9.1 P6) ──
+// The PURE fact calibration only — the LOCALLY-COMPUTABLE measurement (cheap inter-
+// frame luma deltas) lives in the resolver's node helper (frameStats.ts), so
+// perception stays node-free. No Modal: a no-deploy CrowdCut validation derives the
+// deltas host-side and feeds this same calibration.
+export { ENERGY_BEAT_VERSION, energyBeatSignal, } from './energyBeat';
+// ── visualQuality signal provider (per-source image-quality fact; spec §1.2 + §9.1 P6) ──
+// The PURE fact calibration only — the LOCALLY-COMPUTABLE measurement (Laplacian-
+// variance sharpness + exposure sanity) lives in the resolver's node helper
+// (frameStats.ts), so perception stays node-free. No Modal: locally computable.
+export { VISUAL_QUALITY_VERSION, visualQualitySignal, } from './visualQuality';
+// ── cross-source identity MATCHING (the lockPersonId fact; spec §4 + §9.1 P6) ──
+// The PURE cosine-match math only — the per-person median ArcFace embedding EXTRACTION
+// is Modal-deploy-deferred (detect_subjects.py persists it into the SubjectTrack);
+// the MATCHING (which candidate is the locked person) runs with no deploy and feeds
+// the resolver's eligibility (the core never learns about embeddings — the rot-guard).
+export { IDENTITY_MATCH_VERSION, IDENTITY_MATCH_COSINE, cosineSimilarity, matchPerson, } from './identityMatch';

package/dist/_members/perception/visualQuality.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @cueframe/perception — `visualQuality` signal provider (per-source image quality
+ * FACT).
+ *
+ * A DECISION-FREE measurement (perception is a leaf — it produces a FACT, never a
+ * choice): per-source image quality — SHARPNESS (focus) + EXPOSURE sanity — over a
+ * window, calibrated to an ABSOLUTE [0,1] scalar so the Selector core can prefer the
+ * cleanest angle (selector-abstraction spec §1.2, the `visualQuality` signal; §9.1
+ * P6, the fancam/CrowdCut signal — don't cut to a blurry/blown-out angle).
+ *
+ * Perception NEVER imports the Selector core (the rot-guard direction): this module
+ * emits a plain `{ value, rawScore, confidence, evidence }` envelope that STRUCTURALLY
+ * matches `@cueframe/core`'s `Signal`, but the type lives here (a leaf owns its own
+ * fact shape; the core projects it). Adding/upgrading the analysis = a version stamp
+ * here; the core is untouched.
+ *
+ * LOCALLY COMPUTABLE — NO MODAL (spec §9.1 P6 scope-2, the CRITICAL constraint): the
+ * raw measurement is CHEAP image statistics — SHARPNESS via the variance of the
+ * Laplacian (a classic blur metric: a focused frame has a high Laplacian variance, a
+ * blurred one a low variance) + EXPOSURE via mean luma / clipped-pixel fraction
+ * (under/over-exposed frames are a quality DEFECT). Both are a single decode + a
+ * convolution/histogram with NO GPU model — so the no-deploy CrowdCut validation can
+ * derive them host-side (the local node helper `frameStats.ts`, like `audioAnalysis.ts`
+ * for audioQuality). The pure CALIBRATION here is identical whether the metrics come
+ * from the local frame harness or a future Modal skill — the interface, not a fork.
+ *
+ * This module is the PURE FACT CONTRACT (perception is a leaf — NO node I/O here):
+ *  - `visualQualitySignal(metrics)` — PURE: maps the raw per-source image metrics
+ *    (Laplacian-variance sharpness, mean luma, clipped fraction) to the absolute
+ *    [0,1] value + reasons.
+ *
+ * `null` on an UNDECODABLE source (no frame to measure) — NEVER 0 (absence ≠ a bad
+ * picture; a weight over an all-null visualQuality fails loud upstream, never reads
+ * as "definitely low quality" — feedback_never_add_fallbacks).
+ *
+ * Pure + deterministic.
+ */
+/** Bump when the metrics→value calibration changes (the 3-stamp lesson — a stale
+ *  cached visualQuality is served if a consumer doesn't bump alongside). */
+export declare const VISUAL_QUALITY_VERSION = "visual-quality-v1-2026.06.21";
+/** The raw per-source image metrics — what BOTH the local frame-stats harness
+ *  (`frameStats.ts`) and the future Modal skill measure (a representative/median
+ *  frame, or a windowed mean). Source-independent absolutes, never normalized
+ *  across angles (the cross-source comparison is the Selector's job). */
+export interface VisualQualityMetrics {
+    /** Variance of the Laplacian of the luma channel (luma normalized to [0,1]).
+     *  HIGH = sharp/in-focus; LOW = blurred/out-of-focus. The classic blur metric. */
+    laplacianVariance: number;
+    /** Mean luma ∈ [0,1] (exposure level). ~0.45 is well-exposed; near 0 (crushed)
+     *  or near 1 (blown out) is under/over-exposed. */
+    meanLuma: number;
+    /** Fraction ∈ [0,1] of pixels at the extremes (pure black or pure white) — a
+     *  clipping proxy. High = blown highlights / crushed blacks (a defect). Optional;
+     *  absent leans on `meanLuma` alone. */
+    clippedFraction?: number;
+}
+/** Matches `@cueframe/core`'s `Signal` shape STRUCTURALLY (perception owns its
+ *  fact; the core projects `value`/`confidence`). */
+export interface VisualQualitySignal {
+    /** ABSOLUTE, calibrated ∈ [0,1] — "how clean is this angle's image" (sharp +
+     *  well-exposed), source-independent. The crispest, best-exposed angle scores
+     *  highest. */
+    value: number;
+    /** Pre-calibration raw (the Laplacian variance) for legibility + recalibration. */
+    rawScore: number;
+    confidence: number;
+    /** Reasons-only ("sharpness 0.81, exposure 0.93"); excluded from any hash. */
+    evidence: string;
+}
+/**
+ * Map raw image metrics → the absolute [0,1] visualQuality value (PURE).
+ *
+ * Returns `null` — NOT 0 — when the source is UNDECODABLE (no frame measured):
+ * pass `undefined` for an angle whose frame the harness could not read. `null` is
+ * "not measured" (absence); a weight over an all-null visualQuality is fail-loud
+ * upstream (`selector_signal_absent`), never silently 0. A real measurement of a
+ * blurry frame returns a genuine LOW value (e.g. 0.05) — that DOES suppress a cut.
+ *
+ * Calibration (absolute, NOT softmax-across-angles):
+ *  - SHARPNESS: a piecewise-linear ramp from BLUR_VAR (→ 0) to SHARP_VAR (→ 1).
+ *  - EXPOSURE: a sanity multiplier — full when `meanLuma` is near IDEAL_LUMA, falling
+ *    off toward crushed/blown, with a hard clip-fraction penalty. A sharp-but-blown
+ *    frame loses to a sharp well-exposed one.
+ *  - value = sharpness · exposure (a blurry OR a blown frame both score low).
+ */
+export declare function visualQualitySignal(m: VisualQualityMetrics | undefined): VisualQualitySignal | null;

package/dist/_members/perception/visualQuality.js

@@ -0,0 +1,95 @@
+/**
+ * @cueframe/perception — `visualQuality` signal provider (per-source image quality
+ * FACT).
+ *
+ * A DECISION-FREE measurement (perception is a leaf — it produces a FACT, never a
+ * choice): per-source image quality — SHARPNESS (focus) + EXPOSURE sanity — over a
+ * window, calibrated to an ABSOLUTE [0,1] scalar so the Selector core can prefer the
+ * cleanest angle (selector-abstraction spec §1.2, the `visualQuality` signal; §9.1
+ * P6, the fancam/CrowdCut signal — don't cut to a blurry/blown-out angle).
+ *
+ * Perception NEVER imports the Selector core (the rot-guard direction): this module
+ * emits a plain `{ value, rawScore, confidence, evidence }` envelope that STRUCTURALLY
+ * matches `@cueframe/core`'s `Signal`, but the type lives here (a leaf owns its own
+ * fact shape; the core projects it). Adding/upgrading the analysis = a version stamp
+ * here; the core is untouched.
+ *
+ * LOCALLY COMPUTABLE — NO MODAL (spec §9.1 P6 scope-2, the CRITICAL constraint): the
+ * raw measurement is CHEAP image statistics — SHARPNESS via the variance of the
+ * Laplacian (a classic blur metric: a focused frame has a high Laplacian variance, a
+ * blurred one a low variance) + EXPOSURE via mean luma / clipped-pixel fraction
+ * (under/over-exposed frames are a quality DEFECT). Both are a single decode + a
+ * convolution/histogram with NO GPU model — so the no-deploy CrowdCut validation can
+ * derive them host-side (the local node helper `frameStats.ts`, like `audioAnalysis.ts`
+ * for audioQuality). The pure CALIBRATION here is identical whether the metrics come
+ * from the local frame harness or a future Modal skill — the interface, not a fork.
+ *
+ * This module is the PURE FACT CONTRACT (perception is a leaf — NO node I/O here):
+ *  - `visualQualitySignal(metrics)` — PURE: maps the raw per-source image metrics
+ *    (Laplacian-variance sharpness, mean luma, clipped fraction) to the absolute
+ *    [0,1] value + reasons.
+ *
+ * `null` on an UNDECODABLE source (no frame to measure) — NEVER 0 (absence ≠ a bad
+ * picture; a weight over an all-null visualQuality fails loud upstream, never reads
+ * as "definitely low quality" — feedback_never_add_fallbacks).
+ *
+ * Pure + deterministic.
+ */
+/** Bump when the metrics→value calibration changes (the 3-stamp lesson — a stale
+ *  cached visualQuality is served if a consumer doesn't bump alongside). */
+export const VISUAL_QUALITY_VERSION = 'visual-quality-v1-2026.06.21';
+// ── Calibration constants (EXPLICIT + versioned — spec §9.1 P6 scope-2) ───────
+// SHARPNESS: the variance of the Laplacian, computed on luma normalized to [0,1].
+// On that scale a sharply-focused frame has a Laplacian variance roughly in the
+// 1e-3..1e-2 range; a soft/blurred frame an order of magnitude lower. We map it
+// through a log-ish piecewise ramp from BLUR_VAR (→ 0, clearly out of focus) to
+// SHARP_VAR (→ 1, crisp). EXPOSURE: a sanity penalty centered on a mid-grey mean
+// luma, plus a hard penalty as the clipped-pixel fraction (pure-black/white) grows
+// (a blown-out or crushed frame is a defect however sharp). These are the
+// visualQuality calibration curve — part of VISUAL_QUALITY_VERSION (bump if retuned).
+const BLUR_VAR = 0.0003; // ≤ this Laplacian variance ⇒ clearly out of focus ⇒ sharpness 0
+const SHARP_VAR = 0.006; // ≥ this Laplacian variance ⇒ crisp ⇒ sharpness 1
+const IDEAL_LUMA = 0.45; // mean luma (normalized) of a well-exposed frame
+const LUMA_TOLERANCE = 0.4; // |meanLuma − IDEAL| beyond this ⇒ exposure penalty maxes out
+const CLIP_PENALTY_AT = 0.25; // clipped fraction at/above this ⇒ exposure score floored
+const clamp01 = (x) => (x < 0 ? 0 : x > 1 ? 1 : x);
+/**
+ * Map raw image metrics → the absolute [0,1] visualQuality value (PURE).
+ *
+ * Returns `null` — NOT 0 — when the source is UNDECODABLE (no frame measured):
+ * pass `undefined` for an angle whose frame the harness could not read. `null` is
+ * "not measured" (absence); a weight over an all-null visualQuality is fail-loud
+ * upstream (`selector_signal_absent`), never silently 0. A real measurement of a
+ * blurry frame returns a genuine LOW value (e.g. 0.05) — that DOES suppress a cut.
+ *
+ * Calibration (absolute, NOT softmax-across-angles):
+ *  - SHARPNESS: a piecewise-linear ramp from BLUR_VAR (→ 0) to SHARP_VAR (→ 1).
+ *  - EXPOSURE: a sanity multiplier — full when `meanLuma` is near IDEAL_LUMA, falling
+ *    off toward crushed/blown, with a hard clip-fraction penalty. A sharp-but-blown
+ *    frame loses to a sharp well-exposed one.
+ *  - value = sharpness · exposure (a blurry OR a blown frame both score low).
+ */
+export function visualQualitySignal(m) {
+    if (m === undefined)
+        return null;
+    if (!Number.isFinite(m.laplacianVariance) || !Number.isFinite(m.meanLuma))
+        return null;
+    // SHARPNESS: BLUR_VAR → 0, SHARP_VAR → 1.
+    const sharpness = clamp01((m.laplacianVariance - BLUR_VAR) / (SHARP_VAR - BLUR_VAR));
+    // EXPOSURE: 1.0 at IDEAL_LUMA, linear falloff to 0 at IDEAL ± LUMA_TOLERANCE.
+    const lumaErr = Math.abs(m.meanLuma - IDEAL_LUMA);
+    let exposure = clamp01(1 - lumaErr / LUMA_TOLERANCE);
+    // Hard clip penalty: linear from 1.0 (no clipping) to 0 (≥ CLIP_PENALTY_AT clipped).
+    if (m.clippedFraction !== undefined) {
+        const clipPenalty = clamp01(1 - clamp01(m.clippedFraction) / CLIP_PENALTY_AT);
+        exposure *= clipPenalty;
+    }
+    const value = clamp01(sharpness * exposure);
+    // Confidence is lower when we lack a clip measurement (exposure leans on luma alone).
+    const confidence = m.clippedFraction === undefined ? 0.75 : 0.95;
+    const evidence = `sharpness ${sharpness.toFixed(2)}, exposure ${exposure.toFixed(2)} ` +
+        `(lapVar ${m.laplacianVariance.toFixed(4)}, luma ${m.meanLuma.toFixed(2)}` +
+        (m.clippedFraction !== undefined ? `, clip ${m.clippedFraction.toFixed(3)}` : '') +
+        ')';
+    return { value, rawScore: m.laplacianVariance, confidence, evidence };
+}

package/dist/_members/plane/conformance.d.ts

@@ -0,0 +1,75 @@
+/**
+ * THE LANE CONFORMANCE TABLE — one set of facts, executed by both lanes.
+ *
+ * WHY THIS FILE EXISTS. `preview_frame` is served twice: by the desktop plane
+ * (`cueframe/src/plane/handlers.ts`, drawing through the webview) and by the
+ * cloud route (`the `/v1/evidence` routes`, rendering through
+ * Modal). Nothing made them agree. The only mechanism was review discipline —
+ * comments like *"ALLOWED_KEYS TRACKS THAT SCHEMA … Add server-side keys here in
+ * the same change"* — and on 2026-08-15 that mechanism was observed failing:
+ *
+ *   asked for a still 6 seconds past the end of a 45s composition,
+ *     cloud → 422 timestamp_out_of_bounds
+ *     local → 200, silently returning the LAST frame
+ *
+ * The founder's agent read those identical-looking 200s as evidence about its
+ * own composition, concluded the renderer was clamping, and abandoned a correct
+ * line of work. A wrong pixel is worse than an error, and this is how they get
+ * shipped: not by writing bad code, but by adding a rule to one lane.
+ *
+ * WHAT THIS IS. Fixtures + expectations as DATA, with no knowledge of either
+ * lane. Each lane owns a thin runner that maps a row onto its own invocation
+ * (`planeConformance.test.ts` in the app, `evidence.conformance.test.ts` in
+ * convex). Deliberately not a shared test *runner*: the two suites live in
+ * different vitest roots with different harnesses, and forcing one process to
+ * host both would couple the desktop's test setup to Convex's.
+ *
+ * That split is the architecture in miniature — shared pure data, per-lane
+ * adapters. See Projects/CueFrame/specs/2026-08-15-plane-lane-parity-design.
+ *
+ * ITS SIBLING, AND WHEN TO USE WHICH. Stateful STORES served by two lanes
+ * (sqlite + Convex behind `DatabaseAdapter`) are held honest by a different
+ * shape: a parameterised suite in
+ * `packages/data-models/<domain>-model/src/testing/*Contract.ts`. A table like
+ * this one cannot express them — a stateful fact reads "save this thrice, then
+ * list, then count", and encoding that as data costs an op-script schema plus
+ * an interpreter per lane. Rows work HERE because `preview_frame` is stateless:
+ * the fixture travels in the request body. Same purpose, two shapes; CLAUDE.md
+ * has the decision table.
+ *
+ * HOW A KNOWN DIVERGENCE IS RECORDED. `knownRed` names the lanes that fail the
+ * row TODAY. A runner turns those into `test.fails()`, which asserts the test
+ * does NOT pass — so the day someone fixes the lane, this row goes green,
+ * `test.fails()` starts failing, and they are forced to delete the marker. A
+ * skip would rot silently; this cannot.
+ */
+import type { Composition } from "../composition/validators/index.js";
+/** Which implementation is answering. */
+export type Lane = "local" | "cloud";
+export interface ConformanceCase {
+    /** Test name. */
+    readonly name: string;
+    /** Why this row is here — surfaced on failure, so a breakage explains itself. */
+    readonly why: string;
+    /** The request body, verbatim. */
+    readonly body: unknown;
+    /** What BOTH lanes must answer. */
+    readonly expect: {
+        readonly status: number;
+        /** For errors, the `error.code` both lanes must use. */
+        readonly code?: string;
+    };
+    /** Lanes known to fail this row today. Empty/absent ⇒ both must pass. */
+    readonly knownRed?: readonly Lane[];
+}
+/**
+ * ONE composition every row is judged against: 16:9 @ 30fps, five seconds of
+ * media with a card over the first four. Duration is therefore 5s / 150 frames,
+ * which is what makes the out-of-bounds row unambiguous.
+ */
+export declare const CONFORMANCE_COMPOSITION: Composition;
+/** The composition's own duration, in seconds — derived once, used by the rows. */
+export declare const CONFORMANCE_DURATION_SEC = 5;
+export declare const PREVIEW_FRAME_CASES: readonly ConformanceCase[];
+/** Does this row currently fail on `lane`? */
+export declare function isKnownRed(c: ConformanceCase, lane: Lane): boolean;

package/dist/_members/plane/conformance.js

@@ -0,0 +1,90 @@
+/**
+ * ONE composition every row is judged against: 16:9 @ 30fps, five seconds of
+ * media with a card over the first four. Duration is therefore 5s / 150 frames,
+ * which is what makes the out-of-bounds row unambiguous.
+ */
+export const CONFORMANCE_COMPOSITION = {
+    v: 1,
+    format: { aspectRatio: "16:9", fps: 30, resolution: "fhd" },
+    tracks: [
+        {
+            id: "t-video",
+            kind: "video",
+            contents: [
+                {
+                    id: "c1",
+                    startTime: 0,
+                    duration: 5,
+                    source: { kind: "media", mediaId: "m1", trim: { start: 0, end: 5 } },
+                },
+            ],
+        },
+        {
+            id: "t-overlay",
+            kind: "overlay",
+            contents: [
+                {
+                    id: "card-1",
+                    startTime: 0,
+                    duration: 4,
+                    source: { kind: "overlay", primitiveId: "lower-third", params: { text: "hi" } },
+                },
+            ],
+        },
+    ],
+};
+/** The composition's own duration, in seconds — derived once, used by the rows. */
+export const CONFORMANCE_DURATION_SEC = 5;
+export const PREVIEW_FRAME_CASES = [
+    {
+        name: "a timestamp inside the composition is answered",
+        why: "The happy path. If this diverges, nothing below means anything.",
+        body: { timestamps: [1] },
+        expect: { status: 200 },
+    },
+    {
+        name: "an empty timestamps array is refused",
+        why: "Both lanes already reject this — local by hand, cloud via zod `.min(1)`. Here as the " +
+            "control that proves agreement is achievable and that the runners are wired correctly.",
+        body: { timestamps: [] },
+        expect: { status: 400, code: "validation_error" },
+    },
+    {
+        name: "a timestamp PAST the composition end is refused, not clamped",
+        why: "THE 2026-08-15 WRONG-PIXELS BUG. Asked 6s past the end of a 5s composition, the local " +
+            "lane answers 200 with the LAST frame (Remotion's Thumbnail pins), and the founder's " +
+            "agent read that as evidence about its own timeline. " +
+            "NEITHER LANE DECIDES THIS AT THE ROUTE. The cloud's 422 comes from its RENDERER — " +
+            "`rethrowCoded` forwarding a downstream 422 (internal/sightedAction.ts:63) — so with the " +
+            "executor stubbed, as it is on both sides here, the cloud answers 200 too. That is the " +
+            "finding, not a gap in the harness: a rule enforced only by one lane's renderer is not a " +
+            "rule the API applies. `timestamp_out_of_bounds` already exists in the shared registry " +
+            "(packages/errors/src/registry.ts:94, httpStatus 422) — the vocabulary is single-sourced; " +
+            "the DECISION has no home. Stage 2 gives it one: a pure precondition both lanes run " +
+            "before reaching for an executor.",
+        body: { timestamps: [CONFORMANCE_DURATION_SEC + 6] },
+        expect: { status: 422, code: "timestamp_out_of_bounds" },
+        knownRed: ["local", "cloud"],
+    },
+    {
+        name: "an unrecognised body key is refused",
+        why: "THREE DEFINITIONS, AND THE PUBLISHED ONE IS THE STRICTEST. The generated " +
+            "`previewFrameBody` ends `.strict()`, and SDK + MCP clients enforce it. But the route's " +
+            "own `PreviewFrameRequest` (evidence.ts:72) — the schema `zodJson` actually runs — ends " +
+            "`});` with NO `.strict()`, and the local handler has no unknown-key check either " +
+            "(ALLOWED_KEYS covers apply only). So a typo like `timestamp` or `dryRun` is accepted and " +
+            "ignored by BOTH servers while the published contract says it is rejected. " +
+            "This row asserts the STRICT reading because that is what is published and what every " +
+            "generated client already enforces; a server looser than its own spec is the divergence. " +
+            "Note this inverts the obvious stage-1 move: adopting the generated schema locally and " +
+            "nowhere else would make the desktop stricter than the cloud — a NEW divergence pointing " +
+            "the other way. Stage 1 has to settle strictness once, for both.",
+        body: { timestamps: [1], nonsenseKey: true },
+        expect: { status: 400, code: "validation_error" },
+        knownRed: ["local", "cloud"],
+    },
+];
+/** Does this row currently fail on `lane`? */
+export function isKnownRed(c, lane) {
+    return c.knownRed?.includes(lane) ?? false;
+}

package/dist/_members/plane/contract.d.ts

@@ -0,0 +1,55 @@
+/**
+ * THE REQUEST CONTRACT — one definition, both servers.
+ *
+ * WHY THIS MOVED HERE. `preview_frame` had THREE definitions of its own body:
+ * the Convex route's zod (what the cloud actually enforced), the orval-generated
+ * `previewFrameBody` (what the SDK and every MCP client enforce), and a
+ * hand-written imperative mirror in the desktop plane. Nothing made them agree,
+ * and the only sync mechanism was review discipline — comments reading
+ * "ALLOWED_KEYS TRACKS THAT SCHEMA … Add server-side keys here in the same
+ * change". On 2026-08-15 that mechanism was observed failing in both directions
+ * at once: the desktop silently ignored `imageFormat`/`jpegQuality` entirely,
+ * while the PUBLISHED contract was `.strict()` and both servers were not — so
+ * generated clients rejected keys that either server would have accepted.
+ *
+ * MOVED VERBATIM. Every `.describe()` string is preserved because the OpenAPI
+ * spec — and therefore the generated SDK, the MCP tool schemas and the docs —
+ * is built from this object (`requestBody: PreviewFrameRequest`). Rewording a
+ * description here republishes the API.
+ *
+ * STRICTNESS IS DELIBERATELY UNCHANGED. This object ends `})`, not `}).strict()`,
+ * exactly as the route defined it, so this extraction is a pure refactor with no
+ * behaviour change on a live API. Whether the servers SHOULD be strict — and
+ * match the contract they publish — is a product decision with outward-facing
+ * consequences for existing callers, tracked as a red row in
+ * `conformance.ts` rather than settled quietly here.
+ *
+ * PURE, because Convex runs this inside a V8 isolate and the desktop bundles it
+ * into a webview. zod only; no I/O, no Node APIs.
+ */
+import { z } from "zod";
+export declare const PreviewFrameRequest: z.ZodObject<{
+    composition: z.ZodOptional<z.ZodUnknown>;
+    compositionId: z.ZodOptional<z.ZodString>;
+    session_id: z.ZodOptional<z.ZodString>;
+    timestamps: z.ZodArray<z.ZodNumber, "many">;
+    imageFormat: z.ZodOptional<z.ZodEnum<["png", "jpeg"]>>;
+    scale: z.ZodOptional<z.ZodNumber>;
+    jpegQuality: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    timestamps: number[];
+    composition?: unknown;
+    compositionId?: string | undefined;
+    session_id?: string | undefined;
+    imageFormat?: "png" | "jpeg" | undefined;
+    scale?: number | undefined;
+    jpegQuality?: number | undefined;
+}, {
+    timestamps: number[];
+    composition?: unknown;
+    compositionId?: string | undefined;
+    session_id?: string | undefined;
+    imageFormat?: "png" | "jpeg" | undefined;
+    scale?: number | undefined;
+    jpegQuality?: number | undefined;
+}>;

package/dist/_members/plane/contract.js

@@ -0,0 +1,49 @@
+/**
+ * THE REQUEST CONTRACT — one definition, both servers.
+ *
+ * WHY THIS MOVED HERE. `preview_frame` had THREE definitions of its own body:
+ * the Convex route's zod (what the cloud actually enforced), the orval-generated
+ * `previewFrameBody` (what the SDK and every MCP client enforce), and a
+ * hand-written imperative mirror in the desktop plane. Nothing made them agree,
+ * and the only sync mechanism was review discipline — comments reading
+ * "ALLOWED_KEYS TRACKS THAT SCHEMA … Add server-side keys here in the same
+ * change". On 2026-08-15 that mechanism was observed failing in both directions
+ * at once: the desktop silently ignored `imageFormat`/`jpegQuality` entirely,
+ * while the PUBLISHED contract was `.strict()` and both servers were not — so
+ * generated clients rejected keys that either server would have accepted.
+ *
+ * MOVED VERBATIM. Every `.describe()` string is preserved because the OpenAPI
+ * spec — and therefore the generated SDK, the MCP tool schemas and the docs —
+ * is built from this object (`requestBody: PreviewFrameRequest`). Rewording a
+ * description here republishes the API.
+ *
+ * STRICTNESS IS DELIBERATELY UNCHANGED. This object ends `})`, not `}).strict()`,
+ * exactly as the route defined it, so this extraction is a pure refactor with no
+ * behaviour change on a live API. Whether the servers SHOULD be strict — and
+ * match the contract they publish — is a product decision with outward-facing
+ * consequences for existing callers, tracked as a red row in
+ * `conformance.ts` rather than settled quietly here.
+ *
+ * PURE, because Convex runs this inside a V8 isolate and the desktop bundles it
+ * into a webview. zod only; no I/O, no Node APIs.
+ */
+import { z } from "zod";
+export const PreviewFrameRequest = z.object({
+    composition: z.unknown().optional().describe("The composition to render. Absent ⇒ the project's ACTIVE composition — what " +
+        "create_render will encode. The response's `previewed.source` names what was rendered."),
+    compositionId: z.string().optional().describe("Preview a SPECIFIC persisted composition of this project (create_render parity). " +
+        "Absent ⇒ the active one. A stale/foreign id is a 404 — never a silent fall-through."),
+    session_id: z.string().optional().describe("Compose-session id: render that session's SCRATCH composition (what the session " +
+        "has been editing) instead of the active row. Ignored when `composition` is passed."),
+    timestamps: z.array(z.number()).min(1),
+    // Vision-bound shrink knobs (additive): an AGENT looking at its own work wants
+    // the judge's cheap stills (jpeg, 0.5, q70 — what the eval panel grades), not
+    // the full-res default a human preview wants. Absent ⇒ unchanged full-res.
+    imageFormat: z.enum(["png", "jpeg"]).optional().describe("Still format. Default jpeg — these pixels go to a vision model, where jpeg " +
+        "is equivalent and png costs multiples in bytes to store and move. Pass " +
+        "png only when you need full fidelity."),
+    scale: z.number().min(0.1).max(1).optional().describe("Render scale 0.1–1. Default 0.5, which is what this schema has always " +
+        "recommended for vision-bound looks. Pass 1 when judging fine detail — " +
+        "it costs ~4x the vision tokens."),
+    jpegQuality: z.number().int().min(1).max(100).optional().describe("JPEG quality (jpeg only). Default 70 — the quality the eval panel grades at."),
+});

package/dist/_members/plane/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@cueframe/plane` — the lane-agnostic core of the verb plane.
+ *
+ * TODAY this package holds only the conformance table (stage 0 of
+ * Projects/CueFrame/specs/2026-08-15-plane-lane-parity-design): the shared facts
+ * both the desktop plane and the Convex routes must agree on.
+ *
+ * IT IS DELIBERATELY PURE. Stage 2 adds the layers that belong here —
+ * `preconditions` (is this request answerable against the composition) and
+ * `describe` (assemble geometry / layers / etag) — both `f(request, state)` with
+ * no I/O. Nothing effectful goes in this package: Convex runs it inside a V8
+ * isolate, and the whole reason the pure layers can be shared while the
+ * orchestration cannot is that pure functions degrade gracefully when the two
+ * independently-deployed artifacts skew.
+ */
+export * from "./conformance.js";

package/dist/_members/plane/index.js

@@ -0,0 +1,16 @@
+/**
+ * `@cueframe/plane` — the lane-agnostic core of the verb plane.
+ *
+ * TODAY this package holds only the conformance table (stage 0 of
+ * Projects/CueFrame/specs/2026-08-15-plane-lane-parity-design): the shared facts
+ * both the desktop plane and the Convex routes must agree on.
+ *
+ * IT IS DELIBERATELY PURE. Stage 2 adds the layers that belong here —
+ * `preconditions` (is this request answerable against the composition) and
+ * `describe` (assemble geometry / layers / etag) — both `f(request, state)` with
+ * no I/O. Nothing effectful goes in this package: Convex runs it inside a V8
+ * isolate, and the whole reason the pure layers can be shared while the
+ * orchestration cannot is that pure functions degrade gracefully when the two
+ * independently-deployed artifacts skew.
+ */
+export * from "./conformance";