@cueframe/kernel 0.0.1

package/dist/_members/core/select/model.d.ts

@@ -0,0 +1,178 @@
+/**
+ * select/model.ts — the candidate-agnostic data model for the Selector core.
+ *
+ * Four nouns (selector-abstraction spec §1): Candidate, Signal, SelectorPolicy,
+ * Advisory. The CORE (`select.ts`) scores over these and reads ONLY `candidateId`,
+ * `Signal.value/confidence`, and `policy` — NEVER `Candidate.kind`,
+ * `Candidate.timebase`, or any geometry (the §8 rot-guard, enforced by a test AND
+ * by `select()` receiving a projected `CoreCandidate`, not the full `Candidate`).
+ *
+ * Plain TS (no zod): the core package has no zod dependency and the vcam math it
+ * generalizes is plain TS. The spec's zod schemas describe the SHAPE; the fail-
+ * loud invariants live in `select.ts` as explicit guards (no silent fallbacks —
+ * `feedback_never_add_fallbacks`).
+ */
+/** The canonical sparse signal keys (selector-abstraction spec §1.2). Adding a
+ *  signal = add a key + a provider + a weight; the CORE never changes. Reframe
+ *  populates the geometric/instantaneous set; switch populates a DISJOINT set
+ *  (L3 — shared container + combinator, not a shared vocabulary). There is NO
+ *  `prominence` key: prominence is the SCORE, not a signal (§2/L5). */
+export type SignalKey = 'size' | 'centrality' | 'persistence' | 'speaking' | 'activeSpeaker' | 'audioEnergy' | 'audioQuality' | 'topicRelevance' | 'scriptCue' | 'reaction' | 'visualQuality' | 'screenActivity' | 'energyBeat';
+/** A per-candidate, per-moment ABSOLUTE calibrated scalar from a pluggable
+ *  provider (spec §1.2). Sparse — an unmeasured signal is ABSENT (the key is
+ *  missing), never zero. `value` is source-INDEPENDENT, NEVER softmax-across-
+ *  candidates (G9). */
+export interface Signal {
+    /** ABSOLUTE, calibrated, source-independent ∈ [0,1]. */
+    value: number;
+    /** Pre-calibration raw, for legibility + recalibration audits. */
+    rawScore?: number;
+    /** ∈ [0,1]; default 1. Scales the weighted contribution. */
+    confidence?: number;
+    /** Reasons-only ("speaking 0.91, 2 faces"); EXCLUDED from every hash. */
+    evidence?: string;
+}
+/** The sparse signal envelope for one candidate at one moment. Only relevant
+ *  providers populate a key; an absent key means NOT MEASURED. */
+export type CandidateSignals = Partial<Record<SignalKey, Signal>>;
+/** A selectable entity over time (spec §1.1). `kind`/`timebase`/`mediaId` are
+ *  read ONLY by adapters (candidate-building, continuity, lowering), NEVER by the
+ *  core. `candidateId` is STABLE + OPAQUE; an unknown id is rejected downstream,
+ *  never remapped. */
+export interface Candidate {
+    candidateId: string;
+    /** Read ONLY by adapters, NEVER by the core (the rot-guard invariant). */
+    kind: 'subject' | 'source' | 'broll';
+    /** Time mapping onto the SHARED grid. The adapter resolves every timebase onto
+     *  the grid BEFORE the core scores, so the core treats time as already-aligned
+     *  and never reads `timebase.mode` (L4). */
+    timebase: CandidateTimebase;
+    /** Agent-declared semantic tag ("wide"/"screen"/"webcam"/"library"). */
+    role?: string;
+    /** source/broll resolve to a MediaClipSource at author time. */
+    mediaId?: string;
+    /** Agent-legible; EXCLUDED from every hash. */
+    label?: string;
+}
+export type CandidateTimebase = {
+    mode: 'aligned';
+} | {
+    mode: 'declared-offset';
+    offsetSec: number;
+} | {
+    mode: 'source-window';
+    sourceInSec: number;
+    sourceOutSec: number;
+};
+/** The projection the CORE actually receives — `select()` is typed against THIS,
+ *  not the full `Candidate`, so it STRUCTURALLY cannot read `kind`/`timebase`/
+ *  geometry (the rot-guard is a type, not a hope; spec §8). The adapter does the
+ *  projection. */
+export interface CoreCandidate {
+    /** OPAQUE stable id — the ONLY candidate field the core may read. */
+    id: string;
+    /** Per-moment sparse signals over the timeline grid. `signals[t]` is the
+     *  envelope at grid tick `t`. */
+    signals: CandidateSignals[];
+}
+/** A declarative clause over a candidate's signals/role at a moment (eligibility
+ *  + rules). An eligibility gate is AND-of-clauses; a candidate failing it is not
+ *  scorable that moment (spec §1.3). */
+export interface WhenClause {
+    signal?: SignalKey;
+    gte?: number;
+    role?: string;
+    topicMatches?: string;
+}
+export type EligibilityClause = WhenClause;
+export interface SelectorRule {
+    when: {
+        all?: WhenClause[];
+        any?: WhenClause[];
+    };
+    then: {
+        preferCandidateId?: string;
+        preferRole?: string;
+        boost?: number;
+        force?: boolean;
+    };
+    /** EXCLUDED from hash. */
+    intent?: string;
+}
+/** A hard span pin (override ladder tier 0). */
+export interface OverrideSpan {
+    startSec: number;
+    endSec: number;
+    candidateId: string;
+}
+/** The director's taste + stabilizer knobs (spec §1.3). `weights` is
+ *  `DOMINANCE_WEIGHTS` made agent-supplied; `topK` selects a membership set
+ *  (>1 = reframe set, 1 = switch pick). */
+export interface SelectorPolicy {
+    /** sparse; THE taste knob. Σ weights·signal. */
+    weights: Partial<Record<SignalKey, number>>;
+    /** absolute per-signal floor → `__hold__` below it. */
+    floor?: Partial<Record<SignalKey, number>>;
+    /** multi-signal AND/OR gate (NOT a per-signal floor — §2 passesGate). */
+    eligibility?: EligibilityClause[];
+    /** declarative "prefer X when Y". */
+    rules?: SelectorRule[];
+    /** 1 = pick one; >1 = membership set (reframe top-K). */
+    topK: number;
+    /** the OVERRIDE LADDER — ONE ordered eval (spec §1.4 step 1). */
+    overrides?: OverrideSpan[];
+    /** HONEST: pin a CAMERA/candidate (NOT a person). */
+    lockSourceId?: string;
+    /** null until cross-source identity ships. */
+    lockPersonId?: string | null;
+    /** free-text; EXCLUDED from hash. */
+    intent?: string;
+}
+/** The held/abstain sentinel — first-class, not a magic empty (spec §1.4 step 3).
+ *  Lowers per kind: sources → stay on incumbent/primary, no cut; subjects →
+ *  center-hold the crop. */
+export declare const HOLD: "__hold__";
+export type Chosen = string | typeof HOLD;
+export interface CandidateScore {
+    candidateId: string;
+    score: number;
+    /** signalKey → weighted contribution (legibility — the agent reweights from
+     *  evidence). */
+    contributions: Partial<Record<SignalKey, number>>;
+}
+/** Which ladder tier / mechanism produced the choice (legibility). */
+export type PacingNote = 'argmax' | 'min-hold' | 'cooldown' | 'hysteresis' | 'gate-snap' | 'rule' | 'override' | 'lock' | 'hold';
+export interface SelectorSegment {
+    startSec: number;
+    endSec: number;
+    /** candidateId | abstain. */
+    chosen: Chosen;
+    /** topK>1 membership set (reframe; the lowering unions it). */
+    alsoChosen: string[];
+    /** sorted desc by score. */
+    perCandidateScores: CandidateScore[];
+    reasons: string[];
+    pacingNote?: PacingNote;
+}
+/** The DERIVED, read-only advisory (spec §1.4). Keyed to envelope+policy, NEVER
+ *  to the authored composition; never auto-applied. */
+export interface Advisory {
+    advisoryVersion: 1;
+    selectorVersion: string;
+    /** non-overlapping, tile the timeline. */
+    segments: SelectorSegment[];
+    /** discrete-instance surfacing only (continuous instances leave empty +
+     *  populate holdSpans). Phase 2 (switch). */
+    suppressedSwitches: Array<{
+        atSec: number;
+        wouldHaveBeenCandidateId: string;
+        byScore: number;
+        blockedBy: string;
+        releaseAtSec: number;
+    }>;
+    /** continuous-instance deadzone holds (reframe). */
+    holdSpans: Array<{
+        startSec: number;
+        endSec: number;
+    }>;
+}

package/dist/_members/core/select/model.js

@@ -0,0 +1,18 @@
+/**
+ * select/model.ts — the candidate-agnostic data model for the Selector core.
+ *
+ * Four nouns (selector-abstraction spec §1): Candidate, Signal, SelectorPolicy,
+ * Advisory. The CORE (`select.ts`) scores over these and reads ONLY `candidateId`,
+ * `Signal.value/confidence`, and `policy` — NEVER `Candidate.kind`,
+ * `Candidate.timebase`, or any geometry (the §8 rot-guard, enforced by a test AND
+ * by `select()` receiving a projected `CoreCandidate`, not the full `Candidate`).
+ *
+ * Plain TS (no zod): the core package has no zod dependency and the vcam math it
+ * generalizes is plain TS. The spec's zod schemas describe the SHAPE; the fail-
+ * loud invariants live in `select.ts` as explicit guards (no silent fallbacks —
+ * `feedback_never_add_fallbacks`).
+ */
+/** The held/abstain sentinel — first-class, not a magic empty (spec §1.4 step 3).
+ *  Lowers per kind: sources → stay on incumbent/primary, no cut; subjects →
+ *  center-hold the crop. */
+export const HOLD = '__hold__';

package/dist/_members/core/select/select.d.ts

@@ -0,0 +1,63 @@
+/**
+ * select/select.ts — THE durable Selector core (~40 lines of selection logic).
+ *
+ * `select(candidates, policy, opts) → Advisory`: a candidate-agnostic
+ * `score → stabilize-selection → advise` contract (selector-abstraction spec
+ * §1.4). It is the generalization of vcam's `dominance()` ranking (§2): a
+ * weighted-sum combinator + an eligibility-gate predicate + topK membership + a
+ * first-class `__hold__`/abstain + the override ladder + reasons surfacing.
+ *
+ * THE ROT-GUARD (spec §8, the most important invariant): this module reads ONLY
+ * `CoreCandidate.id`, `CandidateSignals[*].value/confidence`, and `policy` — it
+ * NEVER references `Candidate.kind`, `Candidate.timebase`, or any geometry. It is
+ * typed against `CoreCandidate` (id + signals), NOT the full `Candidate`, so the
+ * adapter MUST do the projection and the core STRUCTURALLY cannot branch on kind.
+ * A structural test (`__tests__/rotGuard.test.ts`) asserts this module imports no
+ * geometry/kind types and references none of those fields.
+ *
+ * The selection STABILIZER (continuity over time) is NOT here — it is a per-kind
+ * seam (`stabilize.ts`): `select()` produces the per-moment scored advisory; the
+ * stabilizer (selection-hysteresis | geometric-deadzone | …) is dispatched per
+ * kind by the adapter. This split is L1 of the spec, stated honestly.
+ *
+ * Pure, deterministic. No I/O, no Date.now, no Map-order reads in the math.
+ */
+import type { CoreCandidate, SelectorPolicy, SignalKey, CandidateScore, SelectorSegment } from './model.js';
+export interface SelectOptions {
+    /** Grid tick length in seconds — each tick `t` becomes one [t·dt,(t+1)·dt)
+     *  micro-segment before the stabilizer coalesces. */
+    dtSec: number;
+    /** Number of grid ticks (the timeline length). */
+    ticks: number;
+    selectorVersion: string;
+}
+/**
+ * The core selection over an already-aligned grid. Produces a per-TICK scored
+ * advisory (one `SelectorSegment` per tick, tiling the timeline). The per-kind
+ * stabilizer (`stabilize.ts`) then coalesces ticks under hysteresis/deadzone and
+ * surfaces holds — this function is the SCORE half only.
+ *
+ * Override ladder (spec §1.4 step 1, ONE ordered evaluation):
+ *   tier 0 overrides[] (hard span pin) > tier 1 lock* > tier 2 force rule >
+ *   tier 3 weighted score + eligibility + floor/__hold__.
+ * A SAME-TIER conflict (two overlapping overrides, or two firing force rules at
+ * one tick) FAILS LOUD (`selector_override_conflict` — the Gap.strict() lesson).
+ */
+export declare function select(candidates: CoreCandidate[], policy: SelectorPolicy, opts: SelectOptions): SelectorSegment[];
+/**
+ * The shared scoring COMBINATOR as a pure ONE-SHOT ranking primitive — the
+ * durable `Σ weights·signal` win (spec §2). Both the per-tick `select()` (switch)
+ * and the reframe's segment-wide pool ranking call this, so there is ONE scoring
+ * implementation. `weightKeys` is the CALLER's iteration order: the reframe
+ * subjects adapter passes `{size,centrality,persistence,speaking}` in vcam's
+ * `DOMINANCE_WEIGHTS` order, so the float sum is byte-identical to `dominance()`.
+ *
+ * Reads ONLY `id` + `signals.value/confidence` + `weights` — the rot-guard holds.
+ */
+export declare function scoreAndRank(candidates: Array<{
+    id: string;
+    signals: Partial<Record<SignalKey, {
+        value: number;
+        confidence?: number;
+    }>>;
+}>, weights: Partial<Record<SignalKey, number>>): CandidateScore[];

package/dist/_members/core/select/select.js

@@ -0,0 +1,244 @@
+/**
+ * select/select.ts — THE durable Selector core (~40 lines of selection logic).
+ *
+ * `select(candidates, policy, opts) → Advisory`: a candidate-agnostic
+ * `score → stabilize-selection → advise` contract (selector-abstraction spec
+ * §1.4). It is the generalization of vcam's `dominance()` ranking (§2): a
+ * weighted-sum combinator + an eligibility-gate predicate + topK membership + a
+ * first-class `__hold__`/abstain + the override ladder + reasons surfacing.
+ *
+ * THE ROT-GUARD (spec §8, the most important invariant): this module reads ONLY
+ * `CoreCandidate.id`, `CandidateSignals[*].value/confidence`, and `policy` — it
+ * NEVER references `Candidate.kind`, `Candidate.timebase`, or any geometry. It is
+ * typed against `CoreCandidate` (id + signals), NOT the full `Candidate`, so the
+ * adapter MUST do the projection and the core STRUCTURALLY cannot branch on kind.
+ * A structural test (`__tests__/rotGuard.test.ts`) asserts this module imports no
+ * geometry/kind types and references none of those fields.
+ *
+ * The selection STABILIZER (continuity over time) is NOT here — it is a per-kind
+ * seam (`stabilize.ts`): `select()` produces the per-moment scored advisory; the
+ * stabilizer (selection-hysteresis | geometric-deadzone | …) is dispatched per
+ * kind by the adapter. This split is L1 of the spec, stated honestly.
+ *
+ * Pure, deterministic. No I/O, no Date.now, no Map-order reads in the math.
+ */
+import { CueframeError, encodeError } from '@cueframe/errors';
+import { HOLD } from './model';
+/** Throw a registered fail-loud error (no silent fallback —
+ *  `feedback_never_add_fallbacks`). */
+function fail(code, message, fix) {
+    throw new Error(encodeError(new CueframeError(code, message, fix)));
+}
+/** Does a candidate's signal envelope satisfy a single clause at this moment?
+ *  Geometry-free: reads `signal value ≥ gte` and (adapter-projected) role match.
+ *  `role`/`topicMatches` are matched against a projected `roleTag` the adapter
+ *  folds into a synthetic signal — the core itself never reads `Candidate.role`. */
+function clauseHolds(sig, clause) {
+    if (clause.signal !== undefined) {
+        const s = sig[clause.signal];
+        if (s === undefined)
+            return false;
+        if (clause.gte !== undefined && s.value < clause.gte)
+            return false;
+    }
+    return true;
+}
+/** AND-of-clauses (eligibility) / a rule's `when` (all = AND, any = OR). */
+function whenHolds(sig, when) {
+    const all = when.all ?? [];
+    const any = when.any ?? [];
+    if (all.length > 0 && !all.every((c) => clauseHolds(sig, c)))
+        return false;
+    if (any.length > 0 && !any.some((c) => clauseHolds(sig, c)))
+        return false;
+    return true;
+}
+/** The per-moment weighted score `Σ_k weights[k]·signal[k].value·confidence`,
+ *  with each weighted term recorded for legibility. The weight-key iteration
+ *  order is the CALLER'S (adapter-supplied) order — for the reframe instance the
+ *  subjects adapter supplies `{size,centrality,persistence,speaking}` in exactly
+ *  vcam's `dominance()` order, so the float sum is byte-identical (the byte-
+ *  equivalence acceptance bar). */
+function scoreCandidate(id, sig, weightKeys, weights, ruleBoost) {
+    const contributions = {};
+    let score = 0;
+    for (const k of weightKeys) {
+        const w = weights[k];
+        const s = sig[k];
+        // A weight over an ALL-ABSENT signal is fail-loud upstream (preflight); here
+        // an absent signal at a single moment contributes 0 (the candidate simply
+        // isn't measured on that axis this tick), NOT a silent default for the whole
+        // run.
+        const v = s ? s.value * (s.confidence ?? 1) : 0;
+        const term = w * v;
+        contributions[k] = term;
+        score += term;
+    }
+    score += ruleBoost;
+    return { candidateId: id, score, contributions };
+}
+/**
+ * The core selection over an already-aligned grid. Produces a per-TICK scored
+ * advisory (one `SelectorSegment` per tick, tiling the timeline). The per-kind
+ * stabilizer (`stabilize.ts`) then coalesces ticks under hysteresis/deadzone and
+ * surfaces holds — this function is the SCORE half only.
+ *
+ * Override ladder (spec §1.4 step 1, ONE ordered evaluation):
+ *   tier 0 overrides[] (hard span pin) > tier 1 lock* > tier 2 force rule >
+ *   tier 3 weighted score + eligibility + floor/__hold__.
+ * A SAME-TIER conflict (two overlapping overrides, or two firing force rules at
+ * one tick) FAILS LOUD (`selector_override_conflict` — the Gap.strict() lesson).
+ */
+export function select(candidates, policy, opts) {
+    const { dtSec, ticks } = opts;
+    const ids = candidates.map((c) => c.id);
+    const idSet = new Set(ids);
+    // Preflight: a weighted signal that is ABSENT for EVERY candidate at EVERY tick
+    // is fail-loud (a weight that can never contribute — the agent mis-wired the
+    // policy). This is the spec's `selector_signal_absent` (§1.2/§8).
+    const weightKeys = Object.keys(policy.weights).filter((k) => (policy.weights[k] ?? 0) > 0);
+    for (const k of weightKeys) {
+        let measured = false;
+        for (const c of candidates) {
+            for (const env of c.signals)
+                if (env[k] !== undefined) {
+                    measured = true;
+                    break;
+                }
+            if (measured)
+                break;
+        }
+        if (!measured) {
+            fail('selector_signal_absent', `weight on signal '${k}' but no candidate measures it at any moment`, { signal: k });
+        }
+    }
+    // Validate override/lock ids exist (unknown id REJECTED, never remapped).
+    for (const o of policy.overrides ?? []) {
+        if (!idSet.has(o.candidateId))
+            fail('selector_override_conflict', `override candidateId '${o.candidateId}' not in roster`, { candidateId: o.candidateId });
+    }
+    const rules = policy.rules ?? [];
+    const eligibility = policy.eligibility ?? [];
+    const floor = policy.floor ?? {};
+    const segments = new Array(ticks);
+    for (let t = 0; t < ticks; t++) {
+        const startSec = t * dtSec;
+        const endSec = (t + 1) * dtSec;
+        const tSec = startSec; // a span is "covered" by an override iff its start is inside
+        // ── Tier 0: hard span overrides (fail loud on same-tier overlap). ──────────
+        const hits = (policy.overrides ?? []).filter((o) => tSec >= o.startSec && tSec < o.endSec);
+        if (hits.length > 1) {
+            fail('selector_override_conflict', `two overlapping overrides at ${tSec}s: ${hits.map((h) => h.candidateId).join(', ')}`, { atSec: tSec });
+        }
+        if (hits.length === 1) {
+            segments[t] = pinned(startSec, endSec, hits[0].candidateId, 'override', 'override span');
+            continue;
+        }
+        // ── Tier 1: lock (camera/candidate pin). ───────────────────────────────────
+        if (policy.lockSourceId && idSet.has(policy.lockSourceId)) {
+            segments[t] = pinned(startSec, endSec, policy.lockSourceId, 'lock', `locked to '${policy.lockSourceId}'`);
+            continue;
+        }
+        // ── Tier 3 prep: eligibility filter + rule boosts (geometry-free). ─────────
+        const sigAt = (c) => c.signals[t] ?? {};
+        const eligible = candidates.filter((c) => eligibility.length === 0 || eligibility.every((cl) => clauseHolds(sigAt(c), cl)));
+        const ruleBoostFor = (c) => {
+            let boost = 0;
+            const forces = [];
+            for (const r of rules) {
+                const fires = whenHolds(sigAt(c), r.when) && rulePrefers(r, c.id);
+                if (!fires)
+                    continue;
+                if (r.then.force)
+                    forces.push(r);
+                boost += r.then.boost ?? 0.3;
+            }
+            return { boost, forces };
+        };
+        // ── Tier 2: force rules (fail loud on two distinct forced candidates). ─────
+        const forcedIds = new Set();
+        for (const c of eligible) {
+            const { forces } = ruleBoostFor(c);
+            if (forces.length > 0)
+                forcedIds.add(c.id);
+        }
+        if (forcedIds.size > 1) {
+            fail('selector_override_conflict', `two force rules elect different candidates at ${tSec}s: ${[...forcedIds].join(', ')}`, { atSec: tSec });
+        }
+        if (forcedIds.size === 1) {
+            const fid = [...forcedIds][0];
+            const scored = scoreAll(eligible, sigAt, weightKeys, policy.weights, ruleBoostFor);
+            segments[t] = { startSec, endSec, chosen: fid, alsoChosen: [], perCandidateScores: scored, reasons: [`force rule → '${fid}'`], pacingNote: 'rule' };
+            continue;
+        }
+        // ── Tier 3: weighted score + floor/__hold__ + topK membership. ─────────────
+        const scored = scoreAll(eligible, sigAt, weightKeys, policy.weights, ruleBoostFor);
+        // Floor: if no eligible candidate has ANY contributing signal at/above its
+        // floor, elect __hold__ (abstain — forcing a pick on nothing is autopilot
+        // bias, G8). A candidate clears the floor iff every floored signal it has is
+        // ≥ its floor AND at least one floored signal is present (an empty floor →
+        // never holds, the reframe default).
+        const floorKeys = Object.keys(floor);
+        const anyAboveFloor = floorKeys.length === 0 ||
+            eligible.some((c) => {
+                const sig = sigAt(c);
+                return floorKeys.some((k) => sig[k] !== undefined && sig[k].value >= (floor[k] ?? 0));
+            });
+        if (eligible.length === 0 || !anyAboveFloor) {
+            segments[t] = { startSec, endSec, chosen: HOLD, alsoChosen: [], perCandidateScores: scored, reasons: floorKeys.length && eligible.length ? ['no candidate above floor'] : ['no eligible candidate'], pacingNote: 'hold' };
+            continue;
+        }
+        // topK membership: the top-K by score (stable id tiebreak — deterministic).
+        const k = Math.max(1, policy.topK);
+        const top = scored.slice(0, k);
+        segments[t] = {
+            startSec,
+            endSec,
+            chosen: top[0].candidateId,
+            alsoChosen: top.slice(1).map((s) => s.candidateId),
+            perCandidateScores: scored,
+            reasons: [`argmax score ${top[0].score.toFixed(4)}`],
+            pacingNote: 'argmax',
+        };
+    }
+    return segments;
+}
+function pinned(startSec, endSec, id, note, reason) {
+    return { startSec, endSec, chosen: id, alsoChosen: [], perCandidateScores: [], reasons: [reason], pacingNote: note };
+}
+function rulePrefers(r, id) {
+    // A rule with no preference target applies to all candidates; a targeted rule
+    // applies only to its candidate (role-targeting is folded by the adapter).
+    if (r.then.preferCandidateId !== undefined)
+        return r.then.preferCandidateId === id;
+    return true;
+}
+function scoreAll(cands, sigAt, weightKeys, weights, ruleBoostFor) {
+    const scored = cands.map((c) => scoreCandidate(c.id, sigAt(c), weightKeys, weights, ruleBoostFor(c).boost));
+    return sortScores(scored);
+}
+/** Sort desc by score, then stable id tiebreak — the EXACT vcam `dominance`
+ *  ranking tiebreak (byte-equivalence-preserving for the reframe pool ranking). */
+function sortScores(scored) {
+    scored.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.candidateId < b.candidateId ? -1 : a.candidateId > b.candidateId ? 1 : 0;
+    });
+    return scored;
+}
+/**
+ * The shared scoring COMBINATOR as a pure ONE-SHOT ranking primitive — the
+ * durable `Σ weights·signal` win (spec §2). Both the per-tick `select()` (switch)
+ * and the reframe's segment-wide pool ranking call this, so there is ONE scoring
+ * implementation. `weightKeys` is the CALLER's iteration order: the reframe
+ * subjects adapter passes `{size,centrality,persistence,speaking}` in vcam's
+ * `DOMINANCE_WEIGHTS` order, so the float sum is byte-identical to `dominance()`.
+ *
+ * Reads ONLY `id` + `signals.value/confidence` + `weights` — the rot-guard holds.
+ */
+export function scoreAndRank(candidates, weights) {
+    const weightKeys = Object.keys(weights);
+    const scored = candidates.map((c) => scoreCandidate(c.id, c.signals, weightKeys, weights, 0));
+    return sortScores(scored);
+}

package/dist/_members/core/select/stabilize.d.ts

@@ -0,0 +1,145 @@
+/**
+ * select/stabilize.ts — the continuity/selection STABILIZER seam (spec §1.4 step
+ * 4 + L1). The scoring (`select.ts`) generalizes cleanly; the stabilizer does
+ * NOT — it is THREE kinds behind ONE `stabilize(kind, …)` seam, dispatched per
+ * kind by the adapter. This is the honest "build a small fixed set of per-kind
+ * stabilizers," not "one function" (L1; the prior draft's "selection-hysteresis
+ * generalizes verbatim" claim is retracted).
+ *
+ * Phase 1 implements the two kinds reframe needs:
+ *   - `selection-hysteresis` — the per-id set-MEMBERSHIP state machine (the
+ *     `topK>1` reframe stabilizer), lifted VERBATIM from `vcam/subjectSet.ts`
+ *     (`inset`/`presRun`/`absRun` + the short-clip `usedFallback` bypass). Pure;
+ *     byte-equivalence-preserving.
+ *   - `geometric-deadzone` — `vcam/cameraPath.ts`, lifted VERBATIM and SEALED
+ *     (deadzone inclusion invariant + Hamming + glide cap). Re-exported, NEVER
+ *     altered — perturbing its math risks the shipped `inclusionRate ≈ 1.0` (L1).
+ *
+ * Phase 2 (switch) adds `incumbent-challenger` (topK=1 + switchMargin — NEW code,
+ * vcam has no incumbent concept) and `presence-gate` (overlay binary show/hide).
+ * Their seams are declared here so the dispatch shape is fixed; they fail loud
+ * until built (no silent stub — `feedback_never_add_fallbacks`).
+ */
+/** The continuity-stabilizer kinds (spec L1). */
+export type StabilizerKind = 'selection-hysteresis' | 'geometric-deadzone' | 'incumbent-challenger' | 'presence-gate';
+/** Per-frame presence of a candidate over the grid (the input to the membership
+ *  state machine — `true` iff the candidate is tracked/present this frame). */
+export type PresenceSeries = boolean[];
+export interface SelectionHysteresisParams {
+    /** Frames a member must be present to ENTER the set (= round(ENTER_SEC·fps)). */
+    enterFrames: number;
+    /** Frames a member must be absent to LEAVE the set (= round(LEAVE_SEC·fps)). */
+    leaveFrames: number;
+}
+export interface SelectionHysteresisResult {
+    /** Per-frame: which member ids are IN the framed set this frame (after the
+     *  enter/leave debounce AND present this frame). */
+    inThisFrame: string[][];
+    /** The union of ids that were ever in the set (the framed group). */
+    everIn: Set<string>;
+    /** True iff NO member ever cleared the ENTER debounce (a short clip) → the
+     *  caller falls back to the static set (the vcam `usedFallback` bypass). */
+    usedFallback: boolean;
+}
+/**
+ * The per-id set-MEMBERSHIP hysteresis state machine — the `topK>1` selection
+ * stabilizer (spec §1.4 step 4; §2 maps it as CORE for reframe's membership).
+ * Lifted VERBATIM from `vcam/subjectSet.ts:306-343`: each member enters after
+ * `enterFrames` consecutive present frames and leaves after `leaveFrames` absent
+ * frames — independent per-id booleans. A member is FRAMED this frame iff it is
+ * IN the set AND present this frame.
+ *
+ * `usedFallback` is the short-segment bypass: a segment that ends before any
+ * member clears the ENTER debounce uses the static framed set (so a brief clip
+ * with a clear dominant subject is still framed, never center-held — the spec's
+ * `minSegmentForHysteresis` bypass).
+ *
+ * Pure. Byte-identical to the inline vcam logic — `framedIds` order drives the
+ * per-frame `here` order, so the adapter must pass ids in dominance order.
+ */
+export declare function stabilizeSelectionHysteresis(framedIds: string[], presence: (id: string, frame: number) => boolean, n: number, params: SelectionHysteresisParams): SelectionHysteresisResult;
+export { cameraPath } from '../render/vcam/cameraPath.js';
+export type { CropWindow } from '../render/vcam/cameraPath.js';
+/** A surfaced switch the stabilizer SUPPRESSED (the discrete-instance boundary
+ *  surfacing, spec §1.4 step 5 + Advisory.suppressedSwitches). */
+export interface SuppressedSwitch {
+    /** Grid tick at which the challenger out-scored the incumbent but was held. */
+    atTick: number;
+    wouldHaveBeenId: string;
+    byScore: number;
+    /** Why the switch was blocked: 'min-hold' | 'enter-debounce' | 'switch-margin'
+     *  | 'cooldown'. */
+    blockedBy: string;
+    /** Grid tick at which the block releases (when the incumbent's min-hold ends or
+     *  the cooldown lapses) — null if it releases the moment the condition clears. */
+    releaseAtTick: number | null;
+}
+export interface IncumbentChallengerParams {
+    /** Frames the incumbent must hold before ANY switch is allowed (= round(minHoldSec·fps)). */
+    minHoldFrames: number;
+    /** Frames a challenger must continuously lead by `switchMargin` to take over
+     *  (= round(enterSec·fps)). */
+    enterFrames: number;
+    /** Score margin a challenger must exceed the incumbent by to count as leading. */
+    switchMargin: number;
+    /** Frames after the incumbent is dethroned during which it cannot be re-entered
+     *  (= round(cooldownSec·fps); default resolves to minHoldFrames upstream). */
+    cooldownFrames: number;
+    /** OPTIONAL forced variety: after this many held frames the incumbent must yield
+     *  to the next-best challenger even without a margin lead (= round(maxHoldSec·fps)). */
+    maxHoldFrames?: number;
+}
+export interface IncumbentChallengerResult {
+    /** Per-tick STABILIZED winner id (the incumbent that survives hysteresis). The
+     *  caller coalesces equal runs into cut segments. */
+    chosenPerTick: string[];
+    /** The switches the stabilizer suppressed (anti-ping-pong audit trail). */
+    suppressed: SuppressedSwitch[];
+}
+/**
+ * The incumbent/challenger selection stabilizer — the `topK=1` (switch cut)
+ * anti-ping-pong machine (spec §1.4 step 4, NEW code; L1). Inputs are the per-tick
+ * RAW winner id (the score argmax for that tick) and the per-tick scores by id, so
+ * the stabilizer is candidate-AGNOSTIC (it reads ids + scalars + policy knobs).
+ *
+ * Rule (spec §3.2 + §1.3 knobs):
+ *   - A challenger replaces the incumbent ONLY IF it leads the incumbent by
+ *     `switchMargin` for `enterFrames` CONTINUOUS ticks AND the incumbent has held
+ *     ≥ `minHoldFrames`.
+ *   - `cooldownFrames` forbids re-entering the just-left incumbent for that long.
+ *   - `maxHoldFrames` (optional) forces the incumbent to yield to the best
+ *     challenger after that many held ticks even without a margin lead.
+ *   - A `__hold__` raw winner (no candidate above floor) holds the incumbent (the
+ *     source lowering: "stay on the incumbent, emit no cut").
+ *
+ * `scoreById(id, t)` returns the candidate's score at tick t (0 if not scored).
+ * Pure. Deterministic — no Date, no Map-order math.
+ */
+export declare function stabilizeIncumbentChallenger(rawWinnerPerTick: string[], scoreById: (id: string, tick: number) => number, n: number, params: IncumbentChallengerParams): IncumbentChallengerResult;
+export interface PresenceGateParams {
+    /** Minimum frames an overlay must stay ON once shown (= round(minOnSec·fps)). */
+    minOnFrames: number;
+    /** Minimum frames between two ON windows of the SAME candidate
+     *  (= round(minGapSec·fps)) — prevents flicker on/off. */
+    minGapFrames: number;
+}
+export interface PresenceWindow {
+    candidateId: string;
+    /** Inclusive start tick, exclusive end tick. */
+    startTick: number;
+    endTick: number;
+}
+/**
+ * The presence-gate stabilizer — overlay binary show/hide (spec §6.2 + L1, NEW
+ * code). Overlay is ADDITIVE (the primary is always underneath; there is no
+ * incumbent to dethrone), so this is NOT incumbent/challenger: it is a per-
+ * candidate binary "is this overlay on?" with min-on (no blink-out) and min-gap
+ * (no re-trigger flicker) hysteresis.
+ *
+ * `wantOnPerTick[t]` is the candidate id the adapter wants overlaid at tick t (the
+ * floor-cleared winner), or `__hold__` for "no overlay this tick" (primary alone).
+ * Output: coalesced ON windows per candidate, after the min-on / min-gap debounce.
+ *
+ * Reads ONLY ids + policy knobs (the rot-guard holds). Pure + deterministic.
+ */
+export declare function stabilizePresenceGate(wantOnPerTick: string[], n: number, params: PresenceGateParams): PresenceWindow[];