@cueframe/kernel 0.1.1 → 0.1.2

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

@@ -1,108 +1,14 @@
-/**
- * @cueframe/perception — `activeSpeaker` signal provider (per-angle AV active-
- * speaker FACT).
- *
- * A DECISION-FREE measurement (perception is a leaf — it produces a FACT, never a
- * choice): per-angle audio-visual active-speaker detection (TalkNet-style ASD,
- * arxiv:2107.06592) → a per-window speaking probability for THAT angle's dominant
- * tracked face, calibrated to an ABSOLUTE [0,1] scalar so the Selector core can
- * compare "who is talking" across angles (selector-abstraction spec §1.2, the
- * `activeSpeaker` signal; §9.1 P3, switch on who's-talking).
- *
- * 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 model = a version stamp
- * here; the core is untouched.
- *
- * This module is the PURE FACT CONTRACT (perception is a leaf — NO node I/O here,
- * so it stays importable by every framework leaf):
- *  - `activeSpeakerSignal(series, sourceInSec, sourceOutSec)` — PURE: windows the
- *    per-frame ASD probabilities (over the angle's OWN source timeline) and maps the
- *    windowed speaking probability to the absolute [0,1] value + reasons.
- *
- * The MEASUREMENT (the TalkNet/Light-ASD model that PRODUCES an `ActiveSpeakerSeries`)
- * lives OUTSIDE the leaf — the real perception build is the Modal skill
- * (the backend services_router/skills/detect_active_speaker.py). It is PER-ANGLE:
- * one angle's audio + that angle's tracked dominant face → that angle's speaking
- * probability over time. This REPLACES the within-source Light-ASD (broken on 2+
- * faces) — each angle's track is conditioned on its own audio, never the mixed
- * podcast track (spec §10 — "Cannot be Deepgram-word-gated per-angle"). Both the
- * Modal skill and any local harness feed this one calibration.
- *
- * LANDMINE (spec §scope-1): vocal activity ≠ SPEECH. Laughing, chewing, coughing,
- * a hot reaction mic all raise audio energy and can fool a naive VAD — but a proper
- * AV-ASD model (TalkNet) keys on lip-motion↔audio SYNC, so a chewing/laughing
- * reaction shot (mouth moves, but not in speech-sync, or audio is non-speech)
- * scores LOW. The calibration here trusts the AV model's probability; it does NOT
- * re-derive "is talking" from audio energy alone (that would cut to the chewer).
- * `audioEnergy` (the hot-mic VAD) is a SEPARATE, weaker signal — never conflate the
- * two. The resolver test asserts a high-audio-energy / low-activeSpeaker fixture
- * does NOT trigger a cut.
- *
- * Pure + deterministic.
- */
-/** Bump when the ASD-probability→value calibration changes (the 3-stamp lesson — a
- *  stale cached activeSpeaker is served if a consumer doesn't bump alongside). The
- *  Modal model version is a DISTINCT stamp carried on the series (`modelVersion`). */
 export declare const ACTIVE_SPEAKER_VERSION = "active-speaker-v1-2026.06.21";
-/**
- * The raw per-angle ASD measurement — what the Modal `detect_active_speaker` skill
- * (and any local harness) produces for ONE angle. A per-frame speaking probability
- * over the angle's OWN source timeline for that angle's dominant tracked face.
- *
- * Source-independent absolutes (each value is a probability in [0,1] from the AV
- * model), never normalized across angles (the cross-source comparison is the
- * Selector's job — `switchMargin`/weights, never the signal).
- */
 export interface ActiveSpeakerSeries {
-    /** The Modal ASD model + weights version (e.g. the Light-ASD/TalkNet checkpoint).
-     *  DISTINCT from `ACTIVE_SPEAKER_VERSION` (the calibration stamp). */
     modelVersion: string;
-    /** Frames-per-second of `probs` (the model's visual rate — Light-ASD = 25). */
     fps: number;
-    /** Source-second at which `probs[0]` starts (the angle's window start). */
     windowStartSec: number;
-    /** Per-frame speaking probability ∈ [0,1] for the angle's dominant tracked face.
-     *  A frame where the model had NO face crop (the dominant face left the frame)
-     *  is `null` — NOT 0 (absence ≠ silence; a no-face frame must not dilute the mean
-     *  toward "not speaking"). */
     probs: Array<number | null>;
 }
-/** Matches `@cueframe/core`'s `Signal` shape STRUCTURALLY (perception owns its
- *  fact; the core projects `value`/`confidence`). `null` (not 0) when the angle has
- *  NO measurable face/audio over the window — absence, never "definitely silent". */
 export interface ActiveSpeakerSignal {
-    /** ABSOLUTE, calibrated ∈ [0,1] — "is this angle's subject speaking right now,"
-     *  source-independent. The talking angle scores highest. */
     value: number;
-    /** Pre-calibration raw (the mean windowed ASD probability) for legibility. */
     rawScore: number;
     confidence: number;
-    /** Reasons-only ("speaking 0.91, 18/20 frames faced"); excluded from any hash. */
     evidence: string;
 }
-/**
- * Window the per-frame ASD probabilities over `[sourceInSec, sourceOutSec)` (the
- * angle's OWN source span — the resolver has already mapped the output grid through
- * the angle's declared offset) and map them to the absolute [0,1] activeSpeaker
- * value (PURE).
- *
- * Returns `null` — NOT 0 — when the window has no measurable signal:
- *  - the angle has no ASD series at all (no detected face → no track to score), OR
- *  - every frame in the window is `null` (the dominant face was absent the whole
- *    window).
- * `null` is "not measured" (absence); a weight over an all-null activeSpeaker is
- * fail-loud upstream (`selector_signal_absent`), never silently 0
- * (`feedback_never_add_fallbacks`). A measured-but-quiet angle returns a real low
- * value (e.g. 0.05) — that IS a measurement and DOES suppress a cut.
- *
- * Calibration (absolute, NOT softmax-across-angles): the AV model's per-frame
- * probability is already an absolute speaking likelihood, so the value is the
- * face-present mean over the window. The TalkNet/Light-ASD model keys on lip↔audio
- * SYNC, so a laughing/chewing reaction (mouth moving, non-speech audio) already
- * scores low at the model — this calibration trusts that and does NOT re-inflate
- * from audio energy (the landmine). Confidence scales with face COVERAGE over the
- * window (a face present 2/20 frames is a weak vote).
- */
 export declare function activeSpeakerSignal(series: ActiveSpeakerSeries | undefined, sourceInSec: number, sourceOutSec: number): ActiveSpeakerSignal | null;

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

@@ -1,78 +1,14 @@
-/**
- * @cueframe/perception — `audioQuality` signal provider (per-source audio fact).
- *
- * A DECISION-FREE measurement (perception is a leaf — it produces a FACT, never a
- * choice): per-source loudness + clarity over the source's audio track, calibrated
- * to an ABSOLUTE [0,1] scalar so the Selector core can compare the clearest mic
- * across angles (selector-abstraction spec §1.2, the audioQuality signal; §9.1 P2,
- * the best-audio bed = instance #3).
- *
- * 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.
- *
- * This module is the PURE FACT CONTRACT (perception is a leaf — NO node I/O here,
- * so it stays importable by every framework leaf):
- *  - `audioQualitySignal(metrics)` — PURE: maps the raw per-source acoustic metrics
- *    (integrated loudness LUFS, true-peak, a clarity proxy) to the absolute [0,1]
- *    value + reasons. This is the contract; the production Modal skill and the local
- *    ffmpeg harness BOTH feed it the same `AudioQualityMetrics`.
- *
- * The MEASUREMENT (the ffmpeg/Modal I/O that PRODUCES an `AudioQualityMetrics`)
- * lives OUTSIDE the leaf — the local deploy-free analyzer is in the switch
- * resolver's processing helper (the server-side selector);
- * the Modal per-angle path (Phase 4) produces the SAME `AudioQualityMetrics`. Both
- * feed this one calibration. Keeping the I/O out of perception keeps the leaf pure
- * (no node-only deps) and the rot-guard direction clean.
- *
- * Pure + deterministic.
- */
-/** Bump when the loudness→value calibration changes (the 3-stamp lesson — a stale
- *  cached audioQuality is served if a consumer doesn't bump alongside). */
 export declare const AUDIO_QUALITY_VERSION = "audio-quality-v1-2026.06.21";
-/** The raw per-source acoustic metrics — what BOTH the local ffmpeg harness and
- *  the future Modal skill measure. Source-independent absolutes (LUFS/dBTP), never
- *  normalized across angles (the cross-source comparison is the Selector's job). */
 export interface AudioQualityMetrics {
-    /** Integrated loudness, LUFS (EBU R128). Typical speech ≈ -23..-16; silence → -70. */
     integratedLufs: number;
-    /** True-peak / sample-peak, dBTP. Clipping (≥ -1 dBTP) is a quality DEFECT. */
     truePeakDbtp: number;
-    /** Loudness RANGE, LU (LRA) — a low LRA on a speech mic ≈ steady level (good);
-     *  a high LRA can mean a distant mic drifting in/out (worse). Optional. */
     loudnessRangeLu?: number;
-    /** A clarity proxy ∈ [0,1] when available (e.g. voiced-frame ratio / SNR proxy).
-     *  Optional — the local harness leaves it undefined and the value leans on
-     *  loudness; the Modal skill (VAD-backed) populates it. */
     clarity?: number;
 }
-/** Matches `@cueframe/core`'s `Signal` shape STRUCTURALLY (perception owns its
- *  fact; the core projects `value`/`confidence`). */
 export interface AudioQualitySignal {
-    /** ABSOLUTE, calibrated ∈ [0,1] — "how good is this mic right now," source-
-     *  independent. The clearest, best-leveled mic scores highest. */
     value: number;
-    /** Pre-calibration raw (the integrated LUFS) for legibility + recalibration. */
     rawScore: number;
     confidence: number;
-    /** Reasons-only ("‑18 LUFS, no clip"); excluded from any hash. */
     evidence: string;
 }
-/**
- * Map raw acoustic metrics → the absolute [0,1] audioQuality value (PURE).
- *
- * Calibration (absolute, NOT softmax-across-angles):
- *  - LOUDNESS: a piecewise-linear preference centered on broadcast speech. -16 LUFS
- *    is ideal (1.0); it falls off toward silence (-50 LUFS → ~0) and toward
- *    too-hot (> -10 LUFS → penalized, an over-driven/distorted mic).
- *  - CLIPPING: a hard penalty as true-peak approaches/exceeds 0 dBTP (a clipped
- *    mic is unusable however loud).
- *  - CLARITY: when provided, multiplies the loudness score (a loud-but-noisy mic
- *    loses to a clean one); absent → loudness alone (the local harness path).
- *
- * The result is the clearest-mic ranking signal: over a span the Selector picks the
- * argmax of this across angles, stabilized (best-audio bed).
- */
 export declare function audioQualitySignal(m: AudioQualityMetrics): AudioQualitySignal;

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

@@ -1,95 +1,14 @@
-/**
- * @cueframe/perception — `energyBeat` signal provider (per-source motion/dynamics
- * energy FACT).
- *
- * A DECISION-FREE measurement (perception is a leaf — it produces a FACT, never a
- * choice): per-source visual MOTION / dynamics energy over a window, calibrated to
- * an ABSOLUTE [0,1] scalar so the Selector core can compare "which angle is the
- * most DYNAMIC right now" across angles (selector-abstraction spec §1.2, the
- * `energyBeat` signal; §9.1 P6, the fancam/CrowdCut switch signal — "cut to the
- * most dynamic angle" on chorus/beat).
- *
- * 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 model = a version stamp
- * here; the core is untouched.
- *
- * LOCALLY COMPUTABLE — NO MODAL (spec §9.1 P6 scope-1, the CRITICAL constraint): the
- * raw measurement is CHEAP frame statistics — the per-frame MEAN-ABS INTER-FRAME
- * LUMA DELTA (a normalized "how much did the picture change frame-to-frame" motion
- * magnitude). That is a single decode + a mean over |luma[t] − luma[t−1]|, with NO
- * GPU model — so the no-deploy CrowdCut validation can derive it host-side (the
- * local node helper `the server-side selector`, exactly like
- * `audioAnalysis.ts` for audioQuality). The pure CALIBRATION here is identical
- * whether the deltas come from the local ffmpeg-frame harness or a future Modal
- * skill — this is the interface, not a fork.
- *
- * This module is the PURE FACT CONTRACT (perception is a leaf — NO node I/O here,
- * so it stays importable by every framework leaf):
- *  - `energyBeatSignal(series, sourceInSec, sourceOutSec)` — PURE: windows the
- *    per-frame inter-frame deltas (over the angle's OWN source timeline) and maps
- *    the windowed mean motion magnitude to the absolute [0,1] value + reasons.
- *
- * Pure + deterministic.
- */
-/** Bump when the motion-delta→value calibration changes (the 3-stamp lesson — a
- *  stale cached energyBeat is served if a consumer doesn't bump alongside). */
 export declare const ENERGY_BEAT_VERSION = "energy-beat-v1-2026.06.21";
-/**
- * The raw per-source motion measurement — what BOTH the local frame-stats harness
- * (`frameStats.ts`) and a future Modal skill produce for ONE source. A per-frame
- * normalized inter-frame luma delta over the source's OWN timeline.
- *
- * Source-independent absolutes (each delta is a normalized [0,1] motion magnitude),
- * never normalized across angles (the cross-source comparison is the Selector's
- * job — `switchMargin`/weights, never the signal).
- */
 export interface EnergyBeatSeries {
-    /** The measurement version (e.g. the frame-stats harness / Modal skill version).
-     *  DISTINCT from `ENERGY_BEAT_VERSION` (the calibration stamp). */
     measurementVersion: string;
-    /** Frames-per-second of `deltas` (the sampling rate the deltas were computed at). */
     fps: number;
-    /** Source-second at which `deltas[0]` starts (the angle's window start). */
     windowStartSec: number;
-    /** Per-frame normalized inter-frame luma delta ∈ [0,1] (mean over the frame of
-     *  |luma[t] − luma[t−1]|, luma in [0,1]). `deltas[0]` is the delta between the
-     *  window's first two frames. A frame the harness could NOT decode is `null` —
-     *  NOT 0 (an undecodable frame is absence, never "no motion"; it must not dilute
-     *  the mean toward "still"). */
     deltas: Array<number | null>;
 }
-/** Matches `@cueframe/core`'s `Signal` shape STRUCTURALLY (perception owns its
- *  fact; the core projects `value`/`confidence`). `null` (not 0) when the source
- *  has NO decodable frames over the window — absence, never "definitely still". */
 export interface EnergyBeatSignal {
-    /** ABSOLUTE, calibrated ∈ [0,1] — "how dynamic is this angle right now,"
-     *  source-independent. The most dynamic angle scores highest. */
     value: number;
-    /** Pre-calibration raw (the mean windowed inter-frame delta) for legibility. */
     rawScore: number;
     confidence: number;
-    /** Reasons-only ("motion 0.06, 38/40 frames decoded"); excluded from any hash. */
     evidence: string;
 }
-/**
- * Window the per-frame inter-frame deltas over `[sourceInSec, sourceOutSec)` (the
- * angle's OWN source span — the resolver has already mapped the output grid through
- * the angle's declared offset) and map the windowed mean motion magnitude to the
- * absolute [0,1] energyBeat value (PURE).
- *
- * Returns `null` — NOT 0 — when the window has no measurable signal:
- *  - the angle has no series at all (no frames decoded), OR
- *  - every frame in the window is `null` (undecodable the whole window).
- * `null` is "not measured" (absence); a weight over an all-null energyBeat is
- * fail-loud upstream (`selector_signal_absent`), never silently 0
- * (`feedback_never_add_fallbacks`). A measured-but-static angle returns a real low
- * value (e.g. 0.02) — that IS a measurement and DOES suppress a cut to it.
- *
- * Calibration (absolute, NOT softmax-across-angles): the windowed mean delta is
- * mapped through a piecewise-linear ramp from STILL_DELTA (→ 0) to DYNAMIC_DELTA
- * (→ 1). Confidence scales with the fraction of decodable frames over the window (a
- * window where most frames failed to decode is a weak vote).
- */
 export declare function energyBeatSignal(series: EnergyBeatSeries | undefined, sourceInSec: number, sourceOutSec: number): EnergyBeatSignal | null;

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

@@ -1,80 +1,14 @@
-/**
- * @cueframe/perception — cross-source identity MATCHING (the `lockPersonId` fact).
- *
- * A DECISION-FREE measurement (perception is a leaf — it produces a FACT, never a
- * choice): given a LOCKED person's reference ArcFace embedding and a candidate
- * angle's per-person median ArcFace embeddings, answer "is the locked person present
- * in this angle, and how confidently" — a cosine match over the stored vectors
- * (selector-abstraction spec §4 cross-source identity; §9.1 P6, `lockPersonId` =
- * lock-to-member across angles).
- *
- * Perception NEVER imports the Selector core (the rot-guard direction): this module
- * is the pure embedding→similarity MATH. The ROUTING decision it feeds — "restrict
- * the candidate set to angles where the locked person is present" — is the
- * RESOLVER's job (the server-side selector), which turns this
- * presence fact into a per-candidate eligibility the candidate-agnostic core reads
- * as an opaque scalar. The core never learns about embeddings (the §9.1 P6
- * ROT-GUARD: cross-source identity is a resolver concern; the core reads only id /
- * Signal.value / policy).
- *
- * THE EXTRACTION IS DEPLOY-DEFERRED, THE MATCHING IS LOCAL: the per-person median
- * ArcFace embedding is PRODUCED by the Modal `detect_subjects` skill (it already
- * computes per-id ArcFace embeddings for the appearance-merge — they were
- * computed-then-discarded; P6 persists the per-person MEDIAN into the SubjectTrack,
- * `+DETECTOR_VERSION`). That extraction needs a `modal deploy` (deploy-deferred,
- * never from a worktree — feedback_never_deploy_from_worktree). This MATCHING (the
- * cosine over the stored vectors) is PURE TS and runs with no deploy — the resolver
- * consumes the persisted embeddings and matches here.
- *
- * Pure + deterministic.
- */
-/** Bump when the matching math / threshold semantics change. The embeddings
- *  themselves carry the Modal `DETECTOR_VERSION` (a DISTINCT stamp) — a stale
- *  detector version on an embedding is fail-loud in the resolver
- *  (`selector_identity_detector_version_mismatch`). */
 export declare const IDENTITY_MATCH_VERSION = "identity-match-v1-2026.06.21";
 export declare const IDENTITY_MATCH_COSINE = 0.4;
-/** A per-person median ArcFace embedding persisted on a SubjectTrack — produced by
- *  Modal `detect_subjects` (P6). L2-NORMALIZED (so cosine == dot product). Carries
- *  the `detectorVersion` so a stale-version embedding is fail-loud in the resolver. */
 export interface PersonEmbedding {
-    /** The track-local consolidated person id (`face-0`..`face-N`). */
     faceId: string;
-    /** The per-person MEDIAN ArcFace embedding, L2-normalized. */
     embedding: number[];
-    /** The Modal `DETECTOR_VERSION` that produced this embedding (cache-freshness +
-     *  the fail-loud version guard). */
     detectorVersion: string;
 }
-/** The result of matching a locked reference embedding against ONE angle's people:
- *  is the locked person present in this angle, with what cosine confidence + which
- *  of the angle's faces it matched. */
 export interface IdentityMatchResult {
-    /** True iff some person in this angle matches the reference at/above the cosine
-     *  threshold (the BEST match wins). */
     present: boolean;
-    /** The best cosine similarity over the angle's people ∈ [-1,1]. */
     bestCosine: number;
-    /** The angle-local faceId of the best match (or null if the angle has no people). */
     matchedFaceId: string | null;
 }
-/** Cosine similarity of two embeddings. ArcFace vectors are L2-normalized, so this
- *  is the dot product, but we normalize defensively (a non-normalized input — e.g. a
- *  hand-built test vector — still yields a true cosine). Returns 0 for a zero vector
- *  or a length mismatch (degenerate — never a false high match). */
 export declare function cosineSimilarity(a: number[], b: number[]): number;
-/**
- * Match a LOCKED person's reference embedding against ONE angle's per-person median
- * embeddings (PURE). The locked person is "present" in this angle iff the BEST cosine
- * over the angle's people is at/above `cosineThreshold`.
- *
- * Returns `{ present: false, bestCosine: -1, matchedFaceId: null }` when the angle
- * has NO people (a faceless wide) — absence of the locked person, NOT an error. The
- * resolver turns this into "this angle is not eligible while locked" (it has no
- * decodable identity to lock to). A version mismatch between the reference and a
- * candidate embedding is NOT silently tolerated — the resolver checks
- * `detectorVersion` BEFORE calling this and fails loud
- * (`selector_identity_detector_version_mismatch`); this pure math assumes the
- * versions already agree.
- */
 export declare function matchPerson(reference: number[], anglePeople: PersonEmbedding[], cosineThreshold?: number): IdentityMatchResult;

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

@@ -1,31 +1,5 @@
-/**
- * @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;
@@ -33,12 +7,6 @@ export interface Face {
     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;
@@ -48,31 +16,11 @@ export interface SubjectTrack {
         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: {

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

@@ -1,86 +1,13 @@
-/**
- * @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/plane/conformance.d.ts

@@ -1,75 +1,16 @@
-/**
- * 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
- * (`apps/studio/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/contract.d.ts

@@ -1,32 +1,3 @@
-/**
- * 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>;

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

@@ -1,16 +1 @@
-/**
- * `@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";