@cueframe/kernel 0.1.1 → 0.1.2

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";

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

@@ -0,0 +1,292 @@
+import { z } from "zod";
+import type { UIMessage } from "ai";
+import { ChatErrorView } from "../domain/chat.js";
+import { GenerationArtifact } from "../domain/generation.js";
+export declare const CueFrameMessageMetadata: z.ZodOptional<z.ZodObject<{
+    createdAt: z.ZodNumber;
+    runId: z.ZodOptional<z.ZodString>;
+    backend: z.ZodOptional<z.ZodEnum<["cli", "ts-agent", "convex-agent", "direct"]>>;
+    context: z.ZodOptional<z.ZodObject<{
+        location: z.ZodString;
+        project: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            home: z.ZodEnum<["local", "cloud"]>;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            home: "local" | "cloud";
+        }, {
+            id: string;
+            home: "local" | "cloud";
+        }>>>;
+        selectedMediaIds: z.ZodDefault<z.ZodArray<z.ZodBranded<z.ZodString, "Id<media>">, "many">>;
+        fastMode: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        location: string;
+        project: {
+            id: string;
+            home: "local" | "cloud";
+        } | null;
+        selectedMediaIds: (string & z.BRAND<"Id<media>">)[];
+        fastMode: boolean;
+    }, {
+        location: string;
+        project?: {
+            id: string;
+            home: "local" | "cloud";
+        } | null | undefined;
+        selectedMediaIds?: string[] | undefined;
+        fastMode?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    createdAt: number;
+    context?: {
+        location: string;
+        project: {
+            id: string;
+            home: "local" | "cloud";
+        } | null;
+        selectedMediaIds: (string & z.BRAND<"Id<media>">)[];
+        fastMode: boolean;
+    } | undefined;
+    runId?: string | undefined;
+    backend?: "cli" | "ts-agent" | "convex-agent" | "direct" | undefined;
+}, {
+    createdAt: number;
+    context?: {
+        location: string;
+        project?: {
+            id: string;
+            home: "local" | "cloud";
+        } | null | undefined;
+        selectedMediaIds?: string[] | undefined;
+        fastMode?: boolean | undefined;
+    } | undefined;
+    runId?: string | undefined;
+    backend?: "cli" | "ts-agent" | "convex-agent" | "direct" | undefined;
+}>>;
+export type CueFrameMessageMetadata = z.infer<typeof CueFrameMessageMetadata>;
+export declare const CueFramePhase: z.ZodObject<{
+    phase: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    phase: string;
+    detail?: string | undefined;
+}, {
+    phase: string;
+    detail?: string | undefined;
+}>;
+export declare const CueFrameIteration: z.ZodObject<{
+    iteration: z.ZodNumber;
+    maxIterations: z.ZodNumber;
+    agent: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    agent: string;
+    iteration: number;
+    maxIterations: number;
+}, {
+    agent: string;
+    iteration: number;
+    maxIterations: number;
+}>;
+export declare const CueFrameSuggestions: z.ZodObject<{
+    items: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    items: string[];
+}, {
+    items: string[];
+}>;
+export declare const CueFramePlan: z.ZodObject<{
+    plan: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    plan: string;
+}, {
+    plan: string;
+}>;
+export declare const CueFrameRunOutcome: z.ZodObject<{
+    outcome: z.ZodEnum<["aborted", "error"]>;
+    reason: z.ZodOptional<z.ZodString>;
+    wrote: z.ZodBoolean;
+    phase: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    outcome: "aborted" | "error";
+    wrote: boolean;
+    phase?: string | undefined;
+    reason?: string | undefined;
+}, {
+    outcome: "aborted" | "error";
+    wrote: boolean;
+    phase?: string | undefined;
+    reason?: string | undefined;
+}>;
+export type CueFrameUIData = {
+    phase: z.infer<typeof CueFramePhase>;
+    iteration: z.infer<typeof CueFrameIteration>;
+    suggestions: z.infer<typeof CueFrameSuggestions>;
+    plan: z.infer<typeof CueFramePlan>;
+    run: z.infer<typeof CueFrameRunOutcome>;
+    generation: z.infer<typeof GenerationArtifact>;
+    error: z.infer<typeof ChatErrorView>;
+};
+export type CueFrameUIMessage = UIMessage<CueFrameMessageMetadata, CueFrameUIData>;
+export declare const cueFrameDataPartSchemas: {
+    phase: z.ZodObject<{
+        phase: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        phase: string;
+        detail?: string | undefined;
+    }, {
+        phase: string;
+        detail?: string | undefined;
+    }>;
+    iteration: z.ZodObject<{
+        iteration: z.ZodNumber;
+        maxIterations: z.ZodNumber;
+        agent: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        agent: string;
+        iteration: number;
+        maxIterations: number;
+    }, {
+        agent: string;
+        iteration: number;
+        maxIterations: number;
+    }>;
+    suggestions: z.ZodObject<{
+        items: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        items: string[];
+    }, {
+        items: string[];
+    }>;
+    plan: z.ZodObject<{
+        plan: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        plan: string;
+    }, {
+        plan: string;
+    }>;
+    run: z.ZodObject<{
+        outcome: z.ZodEnum<["aborted", "error"]>;
+        reason: z.ZodOptional<z.ZodString>;
+        wrote: z.ZodBoolean;
+        phase: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        outcome: "aborted" | "error";
+        wrote: boolean;
+        phase?: string | undefined;
+        reason?: string | undefined;
+    }, {
+        outcome: "aborted" | "error";
+        wrote: boolean;
+        phase?: string | undefined;
+        reason?: string | undefined;
+    }>;
+    generation: z.ZodObject<{
+        artifactVersion: z.ZodLiteral<1>;
+        clientRequestId: z.ZodBranded<z.ZodString, "Id<generationRequest>">;
+        generationId: z.ZodBranded<z.ZodString, "Id<generation>">;
+        mediaId: z.ZodBranded<z.ZodString, "Id<media>">;
+        generationGroupId: z.ZodBranded<z.ZodString, "Id<generationGroup>">;
+        version: z.ZodNumber;
+        kind: z.ZodEnum<["image", "video", "audio"]>;
+        requestSummary: z.ZodString;
+        status: z.ZodEnum<["draft", "submitting", "queued", "generating", "provider_complete", "materialising", "processing", "ready", "cancelling", "cancelled", "failed"]>;
+        progress: z.ZodOptional<z.ZodNumber>;
+        placementReady: z.ZodDefault<z.ZodBoolean>;
+        parentMediaId: z.ZodOptional<z.ZodBranded<z.ZodString, "Id<media>">>;
+        estimateUsd: z.ZodOptional<z.ZodNumber>;
+        failure: z.ZodOptional<z.ZodObject<{
+            code: z.ZodString;
+            title: z.ZodString;
+            recovery: z.ZodOptional<z.ZodString>;
+            retryable: z.ZodBoolean;
+            correlationId: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            code: string;
+            title: string;
+            retryable: boolean;
+            recovery?: string | undefined;
+            correlationId?: string | undefined;
+        }, {
+            code: string;
+            title: string;
+            retryable: boolean;
+            recovery?: string | undefined;
+            correlationId?: string | undefined;
+        }>>;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        kind: "video" | "audio" | "image";
+        status: "generating" | "processing" | "cancelled" | "ready" | "failed" | "draft" | "submitting" | "queued" | "provider_complete" | "materialising" | "cancelling";
+        mediaId: string & z.BRAND<"Id<media>">;
+        createdAt: number;
+        updatedAt: number;
+        clientRequestId: string & z.BRAND<"Id<generationRequest>">;
+        generationGroupId: string & z.BRAND<"Id<generationGroup>">;
+        generationId: string & z.BRAND<"Id<generation>">;
+        version: number;
+        artifactVersion: 1;
+        requestSummary: string;
+        placementReady: boolean;
+        parentMediaId?: (string & z.BRAND<"Id<media>">) | undefined;
+        estimateUsd?: number | undefined;
+        progress?: number | undefined;
+        failure?: {
+            code: string;
+            title: string;
+            retryable: boolean;
+            recovery?: string | undefined;
+            correlationId?: string | undefined;
+        } | undefined;
+    }, {
+        kind: "video" | "audio" | "image";
+        status: "generating" | "processing" | "cancelled" | "ready" | "failed" | "draft" | "submitting" | "queued" | "provider_complete" | "materialising" | "cancelling";
+        mediaId: string;
+        createdAt: number;
+        updatedAt: number;
+        clientRequestId: string;
+        generationGroupId: string;
+        generationId: string;
+        version: number;
+        artifactVersion: 1;
+        requestSummary: string;
+        parentMediaId?: string | undefined;
+        estimateUsd?: number | undefined;
+        progress?: number | undefined;
+        placementReady?: boolean | undefined;
+        failure?: {
+            code: string;
+            title: string;
+            retryable: boolean;
+            recovery?: string | undefined;
+            correlationId?: string | undefined;
+        } | undefined;
+    }>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        title: z.ZodString;
+        recovery: z.ZodOptional<z.ZodString>;
+        retryable: z.ZodBoolean;
+        source: z.ZodOptional<z.ZodEnum<["provider", "generation", "materialisation", "agent", "transport"]>>;
+        correlationId: z.ZodOptional<z.ZodString>;
+        details: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        title: string;
+        retryable: boolean;
+        recovery?: string | undefined;
+        source?: "provider" | "generation" | "materialisation" | "agent" | "transport" | undefined;
+        correlationId?: string | undefined;
+        details?: string | undefined;
+    }, {
+        code: string;
+        title: string;
+        retryable: boolean;
+        recovery?: string | undefined;
+        source?: "provider" | "generation" | "materialisation" | "agent" | "transport" | undefined;
+        correlationId?: string | undefined;
+        details?: string | undefined;
+    }>;
+};