@cueframe/kernel 0.1.0 → 0.1.2

package/dist/_members/media-model/transcriptSearch.d.ts

@@ -1,54 +1,12 @@
-/**
- * WHAT COUNTS AS A SPOKEN-WORD HIT, AND WHAT IT IS WORTH.
- *
- * This rule is implemented TWICE and has to be — the desktop searches its local
- * `transcript_segments` table in Rust (`src-tauri/src/database/transcripts.rs`),
- * and the web searches the utterances in an R2 blob in TypeScript. Neither can
- * call the other: one is a SQL `LIKE` chain inside a Tauri command, the other
- * runs in a browser against a JSON object it just downloaded.
- *
- * SO THE RULE IS DATA, AND BOTH LANES RUN THE SAME DATA. `cases.json` beside
- * this file is the shared table: each row is a query, some spoken lines, and
- * the hits they must produce, in order. This module is the TypeScript runner;
- * `contract_transcript_search_cases` in `database/mod.rs` is the Rust one,
- * reading the same file. A rule change that lands in one lane and not the other
- * fails the table on the side that was missed.
- *
- * WHY A TABLE AND NOT A PARAMETERISED SUITE: this is a pure, stateless
- * operation — inputs in, ranking out, no store to set up — which is exactly the
- * case CLAUDE.md's decision table assigns to fixtures-as-data. A suite is for
- * stateful CRUD behind one interface.
- *
- * WHY THE SCORES MATTER RATHER THAN JUST THE ORDER: `desktopScope`'s library
- * search puts spoken hits above visual ones and says in its own comment that a
- * transcript score and a CLIP cosine are different units that must not be
- * merged by value. That reasoning only holds if a transcript score means one
- * fixed thing, so two lanes scoring the same line differently would quietly
- * make the ordering arbitrary.
- */
-/** One spoken line, as either lane holds it. */
 export interface SpokenLine {
     text: string;
     start: number;
     end: number;
 }
-/** One line that matched, with what it is worth. */
 export interface TranscriptHit extends SpokenLine {
-    /** Term coverage, 0–1. NOT comparable to a CLIP cosine. */
     score: number;
 }
-/**
- * A line containing the whole query as a PHRASE is a stronger answer than one
- * that happens to contain the same words apart. Both outrank nothing.
- */
 export declare const PHRASE_SCORE = 1;
 export declare const SCATTERED_SCORE = 0.6;
-/** The query, lowercased and split. Empty query = no terms = no hits. */
 export declare function searchTerms(query: string): string[];
-/**
- * Rank the lines that match every term.
- *
- * `limit` is applied LAST, after ranking, so the strongest hits survive a small
- * limit rather than whichever happened to be spoken first.
- */
 export declare function rankTranscriptHits(query: string, lines: readonly SpokenLine[], limit?: number): TranscriptHit[];

package/dist/_members/nle-export/fcpxml.d.ts

@@ -1,15 +1,2 @@
 import type { ClipExportInput } from "./types.js";
-/**
- * Generate FCPXML v1.11. Compatible with Final Cut Pro 11 and DaVinci Resolve 19.
- *
- * Multi-clip, multi-asset composition:
- * - One <format> per unique (w, h, fpsNum, fpsDen) across assets + sequence.
- * - One <asset> per assets[] entry.
- * - One <asset-clip> per spine[] item (offset/duration in sequence rate; start in source rate).
- * - Markers with spineItemId render inside the matching <asset-clip>, start
- *   relativized to the clip's timelineStartFrames.
- * - Markers without spineItemId render at spine root, start in sequence-absolute rate.
- * - Text overlays overlapping a spine item render as markers inside that clip
- *   (value = overlay.text). Overlays outside all clips are dropped.
- */
 export declare function generateFcpxml(input: ClipExportInput): string;

package/dist/_members/nle-export/index.d.ts

@@ -1,9 +1,3 @@
-/**
- * Root subpath — zero-dep, edge-runtime-safe. Types + pure-TS logic only.
- *
- * XML generators (which depend on xmlbuilder2) live at `@cueframe/nle-export/xml`.
- * Node-only packaging (archiver) lives at `@cueframe/nle-export/server`.
- */
 export { generateSrt } from "./srt.js";
 export { compositionToClipExportInput } from "./composition-to-input.js";
 export { compactTimeline } from "./compact-timeline.js";

package/dist/_members/nle-export/types.d.ts

@@ -1,6 +1,5 @@
 export type ExportFormat = "videoClip" | "fcpxml" | "premiere";
 export type MarkerKind = "hook" | "editorial" | "overlay" | "scene" | "custom";
-/** One entry per unique (sourceId, originInFrames, originOutFrames) triple. */
 export type ClipExportAsset = {
     id: string;
     relPath: string;
@@ -58,48 +57,23 @@ export type ClipExportInput = {
     textOverlays: ExportTextOverlay[];
     audioTracks: ExportAudioTrack[];
 };
-/**
- * Trim-activity output. One entry per unique (sourceId, inFrame, outFrame)
- * triple across all clips in a composition.
- */
 export type TrimmedRef = {
     sourceId: string;
-    /**
-     * Integer source-frame count for the clip's requested in-point. Matching
-     * key — compositionToClipExportInput resolves a clip to its ref by exact
-     * (sourceId, inFramesAtSourceRate, outFramesAtSourceRate) equality.
-     */
     inFramesAtSourceRate: number;
     outFramesAtSourceRate: number;
     r2Key: string;
     ptsStartSec: number;
     durationSec: number;
-    /** ffprobe-reported rational rate of the trimmed file. */
     sourceFpsNum: number;
     sourceFpsDen: number;
-    /**
-     * Decimal frame rate used by the trim activity to derive
-     * inFramesAtSourceRate/outFramesAtSourceRate from seconds. Preserved so
-     * the converter's round-trip uses the same formula (avoids NTSC drift
-     * when mediaItem.frameRate is decimal 29.97 but ffprobe reports rational
-     * 30000/1001).
-     */
     mediaItemFps: number;
     handleBeforeSec: number;
     handleAfterSec: number;
-    /** Human-recognizable source name (mediaItem.name). Passed through so
-     * NLE bins show "Interview A.mov" instead of a Convex id. */
     displayName: string;
     cacheHit: boolean;
 };
 export type TimelineClip = {
     id: string;
-    /**
-     * Original clip id before compactTimeline split this segment out of a
-     * bigger clip. Unset on clips that weren't split. Consumers that need
-     * to attach per-original-clip data (e.g. scene labels) should prefer
-     * this over string-parsing `id`.
-     */
     originalClipId?: string;
     poolItemId: string;
     sourceIn: number;

package/dist/_members/nle-export/xml/index.d.ts

@@ -1,10 +1,2 @@
-/**
- * NLE XML generators. Pulls `xmlbuilder2` which uses Node's Buffer, so this
- * subpath only loads cleanly in Node or full browser bundles — NOT in edge
- * runtimes (Convex V8 isolate, Cloudflare Workers without node-compat).
- *
- * Convex + edge-runtime consumers should import types + converter + srt from
- * the package root, which is xmlbuilder2-free.
- */
 export { generateFcpxml } from "../fcpxml.js";
 export { generatePremiereXml } from "../premiere.js";

package/dist/_members/nle-export/xml-utils.d.ts

@@ -1,21 +1,9 @@
 export interface FrameRateInfo {
-    /** Integer display rate (24 for 23.976, 30 for 29.97, 60 for 59.94). */
     displayRate: number;
-    /** True when fps is a classical NTSC rate (N * 1000/1001). */
     isNtsc: boolean;
-    /** FCPXML-style frame duration attribute (e.g. `1/30s` or `1001/30000s`). */
     frameDuration: string;
 }
-/**
- * Classify a frame rate. Handles integer fps and NTSC fractional rates
- * (23.976, 29.97, 59.94) which use rational time values with 1001 numerator.
- */
 export declare function getFrameRateInfo(fps: number): FrameRateInfo;
-/**
- * Convert seconds to an FCPXML rational time string.
- * For NTSC rates, emits `frames*1001 / displayRate*1000 s` so timing stays exact.
- */
 export declare function toRationalTime(seconds: number, fps: number): string;
-/** Convert seconds to an integer frame count (display frames). */
 export declare function toFrames(seconds: number, fps: number): number;
 export declare function slugify(s: string): string;

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: {