@cueframe/kernel 0.0.1 → 0.1.1

package/dist/_members/perception/activeSpeaker.js

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

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

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

@@ -1,91 +0,0 @@
-/**
- * @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 };
-}

package/dist/_members/perception/index.js

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

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

@@ -1,90 +0,0 @@
-/**
- * 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;
-}