@cueframe/kernel 0.0.1

package/dist/_members/perception/activeSpeaker.js

@@ -0,0 +1,103 @@
+/**
+ * @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
+ * (services/modal/video_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 const ACTIVE_SPEAKER_VERSION = 'active-speaker-v1-2026.06.21';
+const clamp01 = (x) => (x < 0 ? 0 : x > 1 ? 1 : x);
+/**
+ * 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 function activeSpeakerSignal(series, sourceInSec, sourceOutSec) {
+    if (!series || series.probs.length === 0 || series.fps <= 0)
+        return null;
+    const f0 = Math.max(0, Math.floor((sourceInSec - series.windowStartSec) * series.fps));
+    const f1 = Math.min(series.probs.length, Math.ceil((sourceOutSec - series.windowStartSec) * series.fps));
+    if (f1 <= f0)
+        return null;
+    let sum = 0;
+    let present = 0;
+    for (let f = f0; f < f1; f++) {
+        const p = series.probs[f];
+        if (p === null || p === undefined)
+            continue; // face absent this frame — NOT 0
+        sum += clamp01(p);
+        present++;
+    }
+    const totalFrames = f1 - f0;
+    // No face in the window at all → absence, not silence. `null` so a weight over an
+    // all-absent angle fails loud rather than reading as "definitely not speaking".
+    if (present === 0)
+        return null;
+    const rawScore = sum / present; // face-present mean (absence does NOT dilute it)
+    const value = clamp01(rawScore);
+    // Confidence = face coverage over the window. A face present every frame is a
+    // strong vote; a face present a handful of frames is a weak one (the model saw
+    // little of it). Floor at 0.3 so a sparse-but-real measurement still counts.
+    const coverage = present / totalFrames;
+    const confidence = clamp01(0.3 + 0.7 * coverage);
+    const evidence = `speaking ${rawScore.toFixed(2)}, ${present}/${totalFrames} frames faced`;
+    return { value, rawScore, confidence, evidence };
+}

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

@@ -0,0 +1,78 @@
+/**
+ * @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/audioQuality.js

@@ -0,0 +1,76 @@
+/**
+ * @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 (services/convex/api/selector/audioAnalysis.ts);
+ * 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 const AUDIO_QUALITY_VERSION = 'audio-quality-v1-2026.06.21';
+const clamp01 = (x) => (x < 0 ? 0 : x > 1 ? 1 : x);
+/**
+ * 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 function audioQualitySignal(m) {
+    // Loudness preference: peak at -16 LUFS, linear ramps on both sides.
+    const IDEAL = -16;
+    const FLOOR = -50; // ≤ this → effectively silent
+    const HOT = -6; //    ≥ this → over-driven
+    let loud;
+    if (m.integratedLufs <= FLOOR)
+        loud = 0;
+    else if (m.integratedLufs <= IDEAL)
+        loud = (m.integratedLufs - FLOOR) / (IDEAL - FLOOR);
+    else if (m.integratedLufs >= HOT)
+        loud = 0.35; // hot but present — usable, penalized
+    else
+        loud = 1 - (0.65 * (m.integratedLufs - IDEAL)) / (HOT - IDEAL); // 1.0 → 0.35
+    loud = clamp01(loud);
+    // Clipping penalty: linear from 1.0 (≤ -3 dBTP) to 0.2 (≥ 0 dBTP).
+    const clipPenalty = m.truePeakDbtp <= -3 ? 1 : m.truePeakDbtp >= 0 ? 0.2 : 1 - (0.8 * (m.truePeakDbtp + 3)) / 3;
+    const clarityMul = m.clarity === undefined ? 1 : 0.4 + 0.6 * clamp01(m.clarity);
+    const value = clamp01(loud * clipPenalty * clarityMul);
+    // Confidence is lower when we lack a clarity measurement (loudness alone).
+    const confidence = m.clarity === undefined ? 0.75 : 0.95;
+    const evidence = `${m.integratedLufs.toFixed(1)} LUFS, ${m.truePeakDbtp.toFixed(1)} dBTP` +
+        (m.loudnessRangeLu !== undefined ? `, LRA ${m.loudnessRangeLu.toFixed(1)}` : '') +
+        (m.clarity !== undefined ? `, clarity ${m.clarity.toFixed(2)}` : '');
+    return { value, rawScore: m.integratedLufs, confidence, evidence };
+}

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

@@ -0,0 +1,95 @@
+/**
+ * @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/energyBeat.js

@@ -0,0 +1,99 @@
+/**
+ * @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 `services/convex/api/selector/frameStats.ts`, 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 const ENERGY_BEAT_VERSION = 'energy-beat-v1-2026.06.21';
+// ── Calibration constants (EXPLICIT + versioned — spec §9.1 P6 scope-1) ───────
+// Inter-frame luma delta is in [0,1] units (luma normalized to [0,1], delta is an
+// absolute difference, so a full black↔white flip is 1.0). Real footage motion sits
+// well below that: a static talking head ≈ 0.005–0.02, lively hand/body motion ≈
+// 0.03–0.08, a fast pan / dance move / strobe ≈ 0.10+. We map this onto [0,1] with a
+// floor (below which the picture is effectively still) and a saturation point
+// (above which it is "maximally dynamic"). These are the energyBeat calibration
+// curve — they are part of ENERGY_BEAT_VERSION (bump it if you retune them).
+const STILL_DELTA = 0.004; // ≤ this normalized delta ⇒ effectively static ⇒ 0.0
+const DYNAMIC_DELTA = 0.09; // ≥ this normalized delta ⇒ maximally dynamic ⇒ 1.0
+const clamp01 = (x) => (x < 0 ? 0 : x > 1 ? 1 : x);
+/**
+ * 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 function energyBeatSignal(series, sourceInSec, sourceOutSec) {
+    if (!series || series.deltas.length === 0 || series.fps <= 0)
+        return null;
+    const f0 = Math.max(0, Math.floor((sourceInSec - series.windowStartSec) * series.fps));
+    const f1 = Math.min(series.deltas.length, Math.ceil((sourceOutSec - series.windowStartSec) * series.fps));
+    if (f1 <= f0)
+        return null;
+    let sum = 0;
+    let present = 0;
+    for (let f = f0; f < f1; f++) {
+        const d = series.deltas[f];
+        if (d === null || d === undefined)
+            continue; // frame undecodable — NOT 0
+        sum += clamp01(d);
+        present++;
+    }
+    const totalFrames = f1 - f0;
+    // No decodable frame in the window at all → absence, not stillness. `null` so a
+    // weight over an all-undecodable angle fails loud rather than reading as "static".
+    if (present === 0)
+        return null;
+    const rawScore = sum / present; // mean over DECODED frames (absence does NOT dilute it)
+    // Piecewise-linear ramp: STILL_DELTA → 0, DYNAMIC_DELTA → 1.
+    const value = clamp01((rawScore - STILL_DELTA) / (DYNAMIC_DELTA - STILL_DELTA));
+    // Confidence = decoded-frame coverage over the window. Floor at 0.3 so a sparse-
+    // but-real measurement still counts.
+    const coverage = present / totalFrames;
+    const confidence = clamp01(0.3 + 0.7 * coverage);
+    const evidence = `motion ${rawScore.toFixed(4)}, ${present}/${totalFrames} frames decoded`;
+    return { value, rawScore, confidence, evidence };
+}

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

@@ -0,0 +1,80 @@
+/**
+ * @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/identityMatch.js

@@ -0,0 +1,91 @@
+/**
+ * @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 (services/convex/api/selector/resolver.ts), 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 const IDENTITY_MATCH_VERSION = 'identity-match-v1-2026.06.21';
+// ── Calibration: the cosine threshold above which two ArcFace embeddings are the
+//    SAME person. ArcFace embeddings are L2-NORMALIZED, so cosine == dot product and
+//    sits in [-1,1]; the SAME identity across angles/poses typically scores ≳ 0.4,
+//    different people ≲ 0.2. We use the SAME default as the detector's intra-source
+//    appearance-merge (scrfd_track.py APPEARANCE_MERGE_THRESHOLD) so cross-angle
+//    matching is consistent with within-source re-linking. Part of
+//    IDENTITY_MATCH_VERSION (bump if retuned).
+export const IDENTITY_MATCH_COSINE = 0.4;
+/** 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 function cosineSimilarity(a, b) {
+    if (a.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    const denom = Math.sqrt(na) * Math.sqrt(nb);
+    if (denom <= 0)
+        return 0;
+    return dot / denom;
+}
+/**
+ * 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 function matchPerson(reference, anglePeople, cosineThreshold = IDENTITY_MATCH_COSINE) {
+    if (anglePeople.length === 0)
+        return { present: false, bestCosine: -1, matchedFaceId: null };
+    let bestCosine = -1;
+    let matchedFaceId = null;
+    for (const p of anglePeople) {
+        const c = cosineSimilarity(reference, p.embedding);
+        if (c > bestCosine) {
+            bestCosine = c;
+            matchedFaceId = p.faceId;
+        }
+    }
+    return { present: bestCosine >= cosineThreshold, bestCosine, matchedFaceId };
+}