@cueframe/kernel 0.1.1 → 0.1.2

package/dist/_members/core/render/vcam/requiredRegion.d.ts

@@ -1,85 +1,14 @@
-/**
- * vcam/requiredRegion.ts — every focus mode's per-frame target, lowered into a
- * `RequiredRegion`: the SOURCE-NORMALIZED box the crop window MUST contain.
- *
- * Phase 3 of the virtual-camera redesign (brain spec
- * 2026-06-21-virtual-camera-reframe-design.md, "Every focus mode lowers to a
- * RequiredRegion" + "Virtual-camera stability"). A RequiredRegion is the padded
- * subject/group extent (subject box + headroom pad). `cameraPath` then enforces
- * the INCLUSION INVARIANT: the crop always contains the RequiredRegion ⇒ the
- * subject can never walk out of frame.
- *
- * This is a REPRESENTATION, not a behavior change for the modes that already
- * work: `face` lowers its single per-frame subject box; `point` a zero-size rect
- * at the authored location; `frame-center` the center rect. Only `all-faces`
- * gains tracking — its region is the per-frame framed-group union box from
- * `subjectSet` (hysteresis-filtered), so the camera follows a moving group.
- *
- * Pure, deterministic, no I/O. All boxes are source-normalized `[x1,y1,x2,y2]`
- * ∈ [0,1]; `REGION_PAD` is a fraction of the source dimension (the geometry is
- * source-normalized — the deadzone in `cameraPath` is the output-crop-normalized
- * hold band, a separate stage).
- */
 import type { Center, NormBox } from './subjectSet.js';
-/** The padded box the crop must contain, as a center+size — the unit the
- *  camera-path solver consumes. Source-normalized: `cx,cy` ∈ [0,1], `w,h` the
- *  fraction of the source the region spans (already padded). */
 export interface RequiredRegion {
     cx: number;
     cy: number;
-    /** Padded region width as a fraction of source width. */
     w: number;
-    /** Padded region height as a fraction of source height. */
     h: number;
 }
-/** Pad a source-normalized box on every side by `pad` (clamped to [0,1]) and
- *  express it as a `RequiredRegion` (center + padded size). A zero-area box (a
- *  `point` target) yields a zero-size padded region at the point. */
 export declare function padBox(box: NormBox, pad?: number): RequiredRegion;
-/** A zero-size RequiredRegion at a single point (the `point` mode target, or any
- *  centroid-only target with no extent). Padded so a point still carries a small
- *  margin the crop must contain. */
 export declare function pointRegion(c: Center, pad?: number): RequiredRegion;
-/** The frame-center RequiredRegion — a zero-size region at source center. The
- *  crop centering on it is a no-op (the window is already centerable), so this
- *  preserves `frame-center`'s `[0.5,0.5]` behavior exactly. */
 export declare function centerRegion(): RequiredRegion;
-/**
- * Lower a per-frame series of source-normalized union boxes (e.g. `all-faces`'s
- * per-frame framed-group box from `subjectSet.perFrameBoxes`) into per-frame
- * RequiredRegions. A null box (no framed member present — occlusion / gap) →
- * null region; `cameraPath` forward-fills the last in-shot region across the
- * gap (so the camera holds, not snaps to center, during a brief occlusion).
- */
 export declare function regionsFromBoxes(boxes: Array<NormBox | null>, pad?: number): Array<RequiredRegion | null>;
-/**
- * Lower a per-frame series of centroid-only targets (the `face` /
- * `active-speaker` per-frame center) into zero-size RequiredRegions. These modes
- * carry a single subject point, not a measured box, in the crop-center path —
- * lowering to a padded point keeps their framing (the camera points at the
- * subject) while giving `cameraPath` a region to include. A null center (subject
- * absent this frame) → null region (forward-filled by `cameraPath`).
- */
 export declare function regionsFromCenters(centers: Array<Center | null>, pad?: number): Array<RequiredRegion | null>;
-/**
- * Outlier-robust median filter on a region series within a SHOT (radius `r`
- * frames). Single-frame detector/ReID spikes — a crowd ReID flicker that
- * teleports the box across the frame for one frame, then snaps back — would
- * otherwise yank the camera (the chase, re-skinned). A short median on
- * cx/cy/w/h rejects them while tracking a clean multi-frame walk (an order
- * statistic, lag-free on a monotone pan). The window is clamped to the shot
- * (never reads past a cut). Null entries are skipped in the window (a present
- * spike isn't outvoted by absent frames). Identity for r < 1.
- */
 export declare function medianFilterRegions(regions: Array<RequiredRegion | null>, r: number, shotStart: number, shotEnd: number): Array<RequiredRegion | null>;
-/**
- * Build the canonical per-frame RequiredRegions for an `all-faces` segment from
- * the per-frame framed-group union boxes (`subjectSet.perFrameBoxes`): pad each
- * box, then outlier-reject single-frame spikes per shot. This is THE region the
- * camera is obliged to contain AND the region the eval measures inclusion
- * against — one source of truth, so the gate is honest (the camera is judged on
- * the same temporally-coherent region it frames). `interiorCuts` are the segment-
- * local shot boundaries (median windows never cross a cut). `fps` sizes the
- * median radius. Null boxes (occlusion) stay null (forward-filled by cameraPath).
- */
 export declare function buildRequiredRegions(boxes: Array<NormBox | null>, fps: number, interiorCuts: Iterable<number>, pad?: number): Array<RequiredRegion | null>;

package/dist/_members/core/render/vcam/shots.d.ts

@@ -1,45 +1,5 @@
-/**
- * vcam/shots.ts — shot segmentation, the SOLE cut source.
- *
- * Phase 1 of the virtual-camera redesign (brain spec
- * 2026-06-21-virtual-camera-reframe-design.md, "Shot/segment handling"):
- * cuts come ONLY from the detector's `track.shotBoundaries` (HSV hard cuts),
- * NEVER inferred from a face-center jump. The deleted `isJump`-as-cut inference
- * is the false-cut snap (the 1.6-frame-widths/sec teleport) — structurally
- * impossible once the only reset is a real detector boundary.
- *
- * Two scopes the selection math must NOT conflate:
- *   - **Identity scope = the authored segment** (cross-shot). A tracker id is
- *     stable within a shot; the same person is followed across cuts. The
- *     `MIN_SUBJECT_RESOLUTION` resolution gate lives at segment granularity.
- *   - **Camera re-lock scope = the shot.** The per-shot LOCKED subject set
- *     (quality gate) is computed per shot; deadzone / window / zoom-fit reset
- *     at a shot boundary (the latter two land in Phase 3/5).
- *
- * Pure, deterministic, no I/O. Inputs are already segment-local frame indices
- * (the caller rebased the window-local `shotBoundaries` into segment offsets).
- */
-/** A half-open shot range `[start, end)` in segment-local frame indices. */
 export interface ShotRange {
-    /** First frame of the shot (segment-local, inclusive). */
     start: number;
-    /** One past the last frame of the shot (segment-local, exclusive). */
     end: number;
 }
-/**
- * Split `[0, segLen)` into shot ranges at the interior cut frames.
- *
- * `interiorCuts` are segment-local frame indices where a NEW shot begins — the
- * SAME set `deriveTrajectory` already derives (`segCuts`: window-local
- * `shotBoundaries` strictly inside the segment, rebased to segment offsets). A
- * cut at frame `c` ends the prior shot at `c` and starts the next at `c`.
- *
- * Legacy tracks with no `shotBoundaries` → no interior cuts → ONE shot covering
- * the whole segment (the safe hold). `shot_boundaries_missing` is NOT thrown —
- * a one-shot segment is a legal, documented outcome, never a degrade.
- *
- * Out-of-range / duplicate / unsorted cuts are tolerated: cuts are sorted,
- * deduped, and clamped to `(0, segLen)`; zero-length spans are dropped. A
- * segment of length 0 yields no shots.
- */
 export declare function segmentShots(interiorCuts: Iterable<number>, segLen: number): ShotRange[];

package/dist/_members/core/render/vcam/subjectSet.d.ts

@@ -1,106 +1,21 @@
-/**
- * vcam/subjectSet.ts — the CHASE KILLER (Phase 2).
- *
- * The `all-faces` failure is the per-frame area-weighted centroid of EVERY
- * detected face: any transient face (a crowd extra, a ByteTrack fragment, a
- * background head) yanks the centroid, so the camera ping-pongs (the "chase").
- * This module selects a STABLE subject set and frames the GROUP smoothly,
- * beating a static center crop on jitter — the headline behavioral fix.
- *
- * Mode-isolated: this is consulted ONLY for the `all-faces` path in
- * `deriveSegment`. `face` / `point` / `frame-center` / `active-speaker` keep
- * their existing selection verbatim.
- *
- * Pipeline (brain spec 2026-06-21-virtual-camera-reframe-design.md, "Subject-of
- * -interest selection"):
- *   1. Per-shot LOCKED subject set (quality gate) — size-aware drop, NOT a flat
- *      persistence gate, so a dominant late entrant is kept and a transient
- *      small face is dropped.
- *   2. Identity scope = the authored SEGMENT: union the per-shot locked sets →
- *      the segment candidate pool; rank by segment-wide dominance; take top-K.
- *   3. Per-frame set-MEMBERSHIP hysteresis over the pool (add/drop debounce) so
- *      a member flickering at the gate boundary doesn't toggle the framing.
- *   4. Emit, PER FRAME, the area-weighted centroid + union bbox over the framed
- *      members PRESENT this frame. The centroid is the raw crop target; the box
- *      is the RequiredRegion source. Transient entries/exits can't yank the
- *      camera (they're gated out of the framed set), but the framed group's own
- *      motion IS followed — Phase 3's deadzone + Hamming window in `cameraPath`
- *      turn this per-frame target into a held-then-glide path, so a walking
- *      subject stays in frame (the camera tracks) without chasing micro-jitter.
- *      (Phase 2 held this target static, which kept a moving subject framed only
- *      while it stayed near the centroid; Phase 3 lets the hold glide to re-
- *      contain the subject when it walks.)
- *
- * The per-subject `face_box_series` the floor reads is produced UNCHANGED by
- * `perSubjectSeries` — this module only chooses WHERE the camera points.
- */
 import type { FaceBox } from '../../../perception/index.js';
-/** A normalized crop center `[cx, cy]` in [0,1] vs source dims. */
 export type Center = [number, number];
-/** A source-normalized axis-aligned box `[x1, y1, x2, y2]` ∈ [0,1]. */
 export type NormBox = [number, number, number, number];
-/** The selection result for one segment's `all-faces` path. */
 export interface SubjectSetResult {
-    /** Per-frame crop target (the basis for `centers`). For `all-faces` this is
-     *  the per-frame framed-group centroid — the basis Phase 3's cameraPath
-     *  smooths into a tracking glide. (Phase 2 held it static; Phase 3 lets the
-     *  camera follow a walking subject because this now varies per frame.) */
     centers: Center[];
-    /** Per-frame UNION bbox of the framed members PRESENT this frame (after the
-     *  membership hysteresis), source-normalized `[x1,y1,x2,y2]`, or null when no
-     *  framed member is present (occlusion / between-shot gap). This is the
-     *  RequiredRegion source: Phase 3 lowers it to the padded box the crop must
-     *  contain so the subject can never walk out of frame. */
     perFrameBoxes: Array<NormBox | null>;
-    /** The tracker ids chosen as the framed set (top-K by dominance). For
-     *  diagnostics / the per-subject floor series (which is produced separately
-     *  but lists the SAME framed ids). Empty when no face survives the gate. */
     framedIds: string[];
-    /** How many frames the framed set was present in (≥1 member) — feeds the
-     *  segment-level resolution accounting (so `all-faces` on a faceless clip
-     *  center-holds, the documented outcome, rather than throwing). */
     resolvedFrames: number;
 }
-/**
- * Select the stable subject set for an `all-faces` segment and emit the per-
- * frame crop target. Pure over the segment-local slice.
- *
- * Empty locked set (no face survives the gate — a faceless / crowd-only clip) →
- * center-hold (`[0.5,0.5]` every frame), a DEFINED outcome, never a throw
- * (per spec fail-loud invariants).
- */
 export declare function selectSubjectSet(perFrameTracked: Array<Record<string, FaceBox>>, srcW: number, srcH: number, fps: number, perKeyframeSpeaker: Map<number, string>, interiorCuts: Iterable<number>): SubjectSetResult;
-/** How the single chosen subject is resolved per frame. `authoredFaceId` is the
- *  agent's `face` pick (a `face-N` id); `null` means active-speaker (resolve via
- *  the per-keyframe speaker, then degrade to the largest face). */
 export type SingleSubjectPick = {
     kind: 'face';
     authoredFaceId: string;
 } | {
     kind: 'active-speaker';
 };
-/** The per-frame chosen-subject box series for a `topK=1` segment (face /
- *  active-speaker). The box is the chosen subject's source-normalized extent
- *  `[x1,y1,x2,y2]`, or null when the chosen subject is absent this frame
- *  (occlusion / between-shot gap) — `cameraPath` forward-fills the last in-shot
- *  region across a brief gap and center-holds a shot with no subject at all. */
 export interface SingleSubjectResult {
-    /** Per-frame chosen-subject box (source-normalized) or null when absent. */
     perFrameBoxes: Array<NormBox | null>;
-    /** How many frames the chosen subject was actually resolved (a non-null box) —
-     *  feeds the `MIN_SUBJECT_RESOLUTION` fail-loud gate for an authored `face`. */
     resolvedFrames: number;
 }
-/**
- * The `topK=1` subjects adapter for `face` / `active-speaker`. Per frame, resolve
- * the single chosen subject and emit its source-normalized box. Pure over the
- * segment-local slice.
- *
- *  - `face` (authored id): the box of that STABLE tracker id this frame; absent →
- *    null (no silent snap to a different person — the roster rule). The empty /
- *    non-`face-` sentinel id resolves to the largest face (legacy callers).
- *  - `active-speaker`: the box of the per-keyframe speaker pick when tracked this
- *    frame; otherwise the largest face this frame (the ASD degrade, mirror of
- *    `deriveSegment`'s active-speaker path).
- */
 export declare function selectSingleSubjectBoxes(perFrameTracked: Array<Record<string, FaceBox>>, srcW: number, srcH: number, perKeyframeSpeaker: Map<number, string>, pick: SingleSubjectPick, nearestSpeaker: (frame: number) => string | null): SingleSubjectResult;

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

@@ -1,27 +1,2 @@
-/**
- * select/errorCodes.ts — the Selector error vocabulary, as VALUES.
- *
- * Every code the Selector core / adapters / lowerings can throw (now or in a
- * later phase) is listed here as a literal value, and the registry-membership CI
- * test (`__tests__/selectorErrorRegistry.test.ts`) imports THIS list and asserts
- * each exists in `@cueframe/errors`'s `ERROR_CODES`. Importing the codes as VALUES
- * (not grepping literals) means a template/variable code can't slip past — an
- * unregistered code would make the CFERR decode fall back to `internal_error` and
- * 500 (the `clip_source_track_mismatch` landmine).
- *
- * Phase 1 (this phase) registers all of these even though only the CORE codes
- * (`selector_signal_absent`, `selector_override_conflict`) are thrown today; the
- * adapter/lowering codes (`selector_timebase_undefined`, `selector_group_unsynced`,
- * `selector_segment_out_of_media`) are thrown by the Phase-2 switch adapters and
- * are registered now so they can never 500 when that phase lands. Phase 3
- * (active-speaker) adds `selector_speaking_double_count` — the structural double-
- * count guard (§11-L5): weighting both `activeSpeaker` and `speaking` fails loud.
- * Phase 6 (cross-source identity) adds `selector_identity_detector_version_mismatch`
- * — a `lockPersonId` match over a STALE-detector-version embedding fails loud (the
- * 3-stamp lesson: a person-lock cosine over embeddings from a different
- * `DETECTOR_VERSION` than the reference is meaningless; refuse rather than guess).
- */
-/** The error codes the Selector layer is allowed to throw. Each MUST be a row in
- *  `@cueframe/errors` `ERROR_CODES` (asserted in CI). */
 export declare const SELECTOR_ERROR_CODES: readonly ["selector_signal_absent", "selector_override_conflict", "selector_timebase_undefined", "selector_group_unsynced", "selector_segment_out_of_media", "selector_speaking_double_count", "selector_identity_detector_version_mismatch"];
 export type SelectorErrorCode = (typeof SELECTOR_ERROR_CODES)[number];

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

@@ -1,27 +1,7 @@
-/**
- * @cueframe/core/select — the durable Selector core (selector-abstraction spec).
- *
- * The candidate-agnostic data model + the ~40-line `select()` scoring contract +
- * the per-kind `stabilize` seam. Reframe is its first instance (the subjects
- * adapter lives in `render/vcam/subjectSet.ts`, which calls `scoreAndRank` +
- * `stabilizeSelectionHysteresis` and lowers via the sealed `cameraPath`).
- *
- * Switch (Phase 2) is the second instance — same core, new candidate adapter +
- * the incumbent-challenger/presence-gate stabilizers + the cut/overlay lowering.
- */
 export type { SignalKey, Signal, CandidateSignals, Candidate, CandidateTimebase, CoreCandidate, WhenClause, EligibilityClause, SelectorRule, OverrideSpan, SelectorPolicy, Chosen, CandidateScore, PacingNote, SelectorSegment, Advisory, } from './model.js';
 export { HOLD } from './model.js';
 export { select, scoreAndRank, type SelectOptions } from './select.js';
 export { stabilizeSelectionHysteresis, stabilizeIncumbentChallenger, stabilizePresenceGate, cameraPath, type StabilizerKind, type SelectionHysteresisParams, type SelectionHysteresisResult, type IncumbentChallengerParams, type IncumbentChallengerResult, type SuppressedSwitch, type PresenceGateParams, type PresenceWindow, type CropWindow, } from './stabilize.js';
 export { SELECTOR_ERROR_CODES, type SelectorErrorCode } from './errorCodes.js';
-/** The default prominence weights — vcam's `DOMINANCE_WEIGHTS`, re-exported as the
- *  canonical "dominant-subject" `policy.weights` for the SCORE combinator. The
- *  switch instance's video-on-prominence path uses these directly (spec §9.1 P2 —
- *  "video-switch on prominence = vcam dominance, exists"); reframe uses the same
- *  constant. Re-exporting it here keeps the scoring default in the select surface.
- *  (This import is in index.ts, NOT select.ts — the rot-guard scans select.ts.) */
 export { DOMINANCE_WEIGHTS } from '../render/vcam/constants.js';
-/** The Selector engine version (spec §8). DISTINCT from BAKE_VERSION (the crop
- *  lowering stamp) and the per-signal stamps. Bump when the scoring/stabilizer
- *  math changes in a way that changes the Advisory for fixed inputs. */
 export declare const SELECTOR_VERSION = "selector-core-v1-2026.06.21";

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

@@ -1,57 +1,17 @@
-/**
- * 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 = {
@@ -64,20 +24,10 @@ export type CandidateTimebase = {
     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;
@@ -96,73 +46,45 @@ export interface SelectorRule {
         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;
@@ -170,7 +92,6 @@ export interface Advisory {
         blockedBy: string;
         releaseAtSec: number;
     }>;
-    /** continuous-instance deadzone holds (reframe). */
     holdSpans: Array<{
         startSec: number;
         endSec: number;

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

@@ -1,59 +1,10 @@
-/**
- * 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, {