@cueframe/kernel 0.1.1 → 0.1.3

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

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

@@ -1,145 +1,43 @@
-/**
- * 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[];

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

@@ -9,7 +9,6 @@ export interface MediaMetadata {
     codec: string;
     frameRate: number;
     fileSize: number;
-    /** Offset between audio and video start times (seconds). Applied to transcription timestamps. */
     audioOffset: number;
 }
 export type ProxyStatus = 'none' | 'generating' | 'ready' | 'failed';

package/dist/_members/director/ai-sdk/chunks.d.ts

@@ -0,0 +1,14 @@
+import type { UIMessageChunk } from "ai";
+import type { CueFrameUIMessage } from "./messages.js";
+import type { DirectorEvent } from "../domain/chat.js";
+type CueFrameChunk = UIMessageChunk<CueFrameUIMessage>;
+export declare function dataChunk<K extends "phase" | "generation" | "error">(name: K, data: K extends "generation" ? Extract<DirectorEvent, {
+    type: "generation";
+}>["artifact"] : K extends "error" ? Extract<DirectorEvent, {
+    type: "error";
+}>["error"] : {
+    phase: string;
+    detail?: string;
+}, id?: string): CueFrameChunk;
+export declare function chunksForDirectorEvent(event: DirectorEvent): CueFrameChunk[];
+export {};

package/dist/_members/director/ai-sdk/context.d.ts

@@ -0,0 +1,6 @@
+import type { CueFrameUIMessage } from "./messages.js";
+export interface DirectorHistoryMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+export declare function projectDirectorHistory(messages: CueFrameUIMessage[], maxChars?: number): DirectorHistoryMessage[];

package/dist/_members/director/ai-sdk/generationTool.d.ts

@@ -0,0 +1,8 @@
+import { GenerationArtifact } from "../domain/generation.js";
+export declare function generationArtifactFromToolResult(args: {
+    toolCallId: string;
+    toolName: string;
+    input?: unknown;
+    output: unknown;
+    now?: number;
+}): GenerationArtifact | null;

package/dist/_members/director/ai-sdk/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./messages.js";
+export * from "./chunks.js";
+export * from "./context.js";
+export * from "./generationTool.js";