@cueframe/kernel 0.1.0 → 0.1.2

package/dist/_members/composition/validators/font.js

@@ -1,34 +0,0 @@
-import { z } from "zod";
-// Font lifecycle per data-model.md § FontRef (and the Font entity).
-// Font is immutable after `status: 'ready'` — variants don't get re-subsetted,
-// family doesn't change, files in R2 are content-addressed by subset hash.
-export const FontStatus = z.enum([
-    "pending",
-    "uploading",
-    "analyzing",
-    "subsetting",
-    "ready",
-    "partial", // common-glyphs buffer present, custom glyphs still subsetting
-    "failed",
-]);
-export const FontVariant = z.object({
-    weight: z.number().int().min(100).max(900),
-    style: z.enum(["normal", "italic"]),
-    storageKey: z.string().min(1),
-    byteSize: z.number().int().nonnegative().optional(),
-    subsetComplete: z.boolean().optional(),
-});
-export const Font = z.object({
-    id: z.string().min(1),
-    family: z.string().min(1),
-    status: FontStatus,
-    variants: z.array(FontVariant).nonempty(),
-    source: z.enum(["uploaded", "system", "web"]).optional(),
-    license: z.object({
-        type: z.string().min(1),
-        source: z.string().optional(),
-        notes: z.string().optional(),
-    }).optional(),
-    createdAt: z.number().optional(), // epoch ms
-    ownerOrgId: z.string().optional(),
-});

package/dist/_members/composition/validators/graphicKinds.js

@@ -1,30 +0,0 @@
-export const AUTHORED_GRAPHIC_KINDS = ["overlay", "component", "card", "alpha-layer"];
-/**
- * The canonical authored KIND for each planner graphic ROLE — the clip kind the
- * deterministic graphics compiler (graphics-plan/compile.ts) emits and the LLM
- * designer authors by default. EVERY role currently compiles to an `overlay`
- * clip: title-card/stat/lower-third/pull-quote are overlay primitives, `hero`'s
- * behind-subject look is a zPlane ON an overlay (not a distinct kind), and
- * `logo-tag` is a watermark overlay.
- *
- * The bridge the brief-EXCLUSIONS filter (briefContract.dropExcludedPlanGraphics)
- * needs: plan graphics carry a ROLE, exclusions name a KIND. `Record<GraphicRole,
- * …>` makes a NEW role a COMPILE error here — the same add-or-silently-miss
- * discipline the kinds SSOT above enforces.
- */
-export const GRAPHIC_ROLE_CANONICAL_KIND = {
-    "title-card": "overlay",
-    stat: "overlay",
-    "lower-third": "overlay",
-    "pull-quote": "overlay",
-    hero: "overlay",
-    "logo-tag": "overlay",
-    // The ARGUMENT roles default to `overlay` too: the catalog's argument-carrying components
-    // (reasoning-trace, tool-call-stack, benchmark-bars, metric-gauge, eval-scorecard) are all
-    // overlay primitives placed by `primitiveId`. A designer that ESCALATES to a custom .tsx
-    // authors a `component` clip, and the exclusions check runs against the clip it actually
-    // wrote — this map only supplies the plan-time default.
-    enumeration: "overlay",
-    sequence: "overlay",
-    comparison: "overlay",
-};

package/dist/_members/composition/validators/index.js

@@ -1,9 +0,0 @@
-export * from "./composition";
-export * from "./composePlan";
-export * from "./brandKit";
-export * from "./font";
-export * from "./render";
-export * from "./registry";
-export * from "./project";
-export * from "./session";
-export * from "./webhook";

package/dist/_members/composition/validators/project.js

@@ -1,29 +0,0 @@
-import { z } from "zod";
-import { zid } from "convex-helpers/server/zod3";
-import { Format } from "./composition";
-// Project per data-model.md § Project — top-level container that holds an
-// active editable Composition pointer, default format for new compositions,
-// and references to brand kit + render history. Compositions stay queryable
-// independently; the Project just points at the current "active" version.
-export const Project = z.object({
-    id: zid("projects"),
-    name: z.string().min(1),
-    // Default format applied to new Compositions created under this Project.
-    // Each Composition still carries its own Format — this is just the seed.
-    defaultFormat: Format.optional(),
-    // PAL-region fps conform default. See data-model.md § MediaItem for the table.
-    // 'palConformDefault: 24' makes 25fps PAL footage conform to 24 instead of 30.
-    palConformDefault: z.union([z.literal(24), z.literal(30)]).optional(),
-    // Pointer to the currently-active Composition for this Project. Edits land
-    // on a new CompositionVersion each PUT; this pointer advances to the new
-    // version's id. Nullable when the Project has no active Composition (e.g.,
-    // immediately after creation, or after the active composition was hard-deleted).
-    activeCompositionId: zid("compositions").nullable().optional(),
-    // Stable external `kitId` STRING (the v1 brand-kits API id), not a strict
-    // `zid("brandKits")`. Resolved org-scoped at render by either kitId or the
-    // legacy convex `_id`. Keeps the brand reference consistent end-to-end (#33).
-    brandKitId: z.string().optional(),
-    ownerOrgId: z.string().optional(),
-    createdAt: z.number(),
-    updatedAt: z.number(),
-});

package/dist/_members/composition/validators/registry.js

@@ -1,41 +0,0 @@
-import { z } from "zod";
-export const PrimitiveOriginClass = z.enum([
-    "first-party",
-    "community-verified",
-    "community-unverified",
-    "user-private",
-    "sandbox",
-    "deprecated",
-]);
-export const PrimitiveMode = z.enum(["2d", "immersive", "interactive"]);
-export const PrimitiveToken = z.object({
-    path: z.string().min(1),
-    fallback: z.unknown(),
-});
-export const PrimitiveOtioMapping = z.object({
-    effectName: z.string().min(1),
-    metadata: z.record(z.string(), z.unknown()).optional(),
-});
-export const PrimitiveMeta = z.object({
-    description: z.string().optional(),
-    use_when: z.array(z.string()).optional(),
-    avoid_when: z.array(z.string()).optional(),
-    vibe: z.array(z.string()).optional(),
-    formats: z.array(z.string()).optional(),
-    pairs_well_with: z.array(z.string()).optional(),
-    exemplars: z.array(z.string()).optional(),
-});
-export const PrimitiveRegistryEntry = z.object({
-    name: z.string().min(1),
-    package: z.string().min(1),
-    category: z.enum(["overlay", "text", "effect", "transition", "layout"]),
-    version: z.string().min(1),
-    origin: PrimitiveOriginClass,
-    modes: z.array(PrimitiveMode).optional(),
-    paramsSchema: z.unknown(),
-    varyingParams: z.array(z.string()).optional(),
-    extends: z.string().optional(),
-    tokens: z.array(PrimitiveToken).optional(),
-    otio: PrimitiveOtioMapping.optional(),
-    meta: PrimitiveMeta.optional(),
-});

package/dist/_members/composition/validators/render.js

@@ -1,139 +0,0 @@
-import { z } from "zod";
-import { zid } from "convex-helpers/server/zod3";
-import { Composition } from "./composition";
-import { BrandKit } from "./brandKit";
-export const RenderPriority = z.enum(["interactive", "standard", "background"]);
-export const RenderIntent = z.enum(["preview", "final"]);
-export const RenderMode = z.enum(["offline", "live"]);
-// Cancel reasons — union of doc spec and operational realities.
-// `user`, `agent`, `cost_limit` are the doc-required triad; the rest are
-// operational reasons the worker pool needs to surface (idempotently retryable).
-export const RenderCancelReason = z.enum([
-    "user",
-    "agent",
-    "cost_limit",
-    "superseded",
-    "source_removed",
-    "timeout",
-    "error",
-]);
-// Lifecycle per data-model.md § Render (RenderJob).
-// pending → rendering → complete | error | cancelled.
-export const RenderStatus = z.enum([
-    "pending",
-    "rendering",
-    "complete",
-    "error",
-    "cancelled",
-]);
-export const RenderProgressPhase = z.object({
-    phase: z.string().min(1),
-    percent: z.number().min(0).max(100),
-    scenesTotal: z.number().int().positive().optional(),
-});
-export const RegistryPin = z.object({
-    package: z.string().min(1),
-    name: z.string().min(1),
-    version: z.string().min(1),
-});
-export const MediaSourceSnapshot = z.object({
-    mediaId: zid("mediaItems"),
-    presignedUrl: z.string().url(),
-    expiresAt: z.number().optional(),
-});
-export const RenderSnapshot = z.object({
-    composition: Composition,
-    brandKit: BrandKit.optional(),
-    mediaSources: z.array(MediaSourceSnapshot),
-    registryPins: z.array(RegistryPin),
-    capturedAt: z.number(),
-});
-// Destinations — delivery intents post-encode. R2 is always the canonical origin;
-// additional destinations are delivered in parallel after the R2 write succeeds.
-// Credentials are referenced by `credentialId` and never inlined on the request.
-export const R2Destination = z.object({
-    kind: z.literal("r2"),
-    path: z.string().optional(),
-});
-export const S3Destination = z.object({
-    kind: z.literal("s3"),
-    credentialId: z.string().min(1),
-    bucket: z.string().min(1),
-    key: z.string().min(1),
-    region: z.string().optional(),
-    acl: z.string().optional(),
-});
-export const YoutubeDestination = z.object({
-    kind: z.literal("youtube"),
-    credentialId: z.string().min(1),
-    title: z.string().min(1),
-    description: z.string().optional(),
-    privacy: z.enum(["public", "unlisted", "private"]),
-    tags: z.array(z.string()).optional(),
-});
-export const MuxDestination = z.object({
-    kind: z.literal("mux"),
-    credentialId: z.string().min(1),
-    passthrough: z.string().optional(),
-});
-export const WebhookDestination = z.object({
-    kind: z.literal("webhook"),
-    url: z.string().url(),
-    signingKeyId: z.string().optional(),
-    headers: z.record(z.string(), z.string()).optional(),
-});
-export const Destination = z.discriminatedUnion("kind", [
-    R2Destination,
-    S3Destination,
-    YoutubeDestination,
-    MuxDestination,
-    WebhookDestination,
-]);
-export const DestinationDeliveryStatus = z.enum([
-    "pending",
-    "uploading",
-    "delivered",
-    "failed",
-]);
-export const DestinationResult = z.object({
-    destinationIndex: z.number().int().nonnegative(),
-    status: DestinationDeliveryStatus,
-    url: z.string().url().optional(),
-    deliveredAt: z.number().optional(),
-    error: z.string().optional(),
-});
-export const RenderJob = z.object({
-    id: zid("renderJobs"),
-    projectId: zid("projects").optional(),
-    compositionId: zid("compositions"),
-    compositionVersionId: z.string().min(1),
-    status: RenderStatus,
-    progress: RenderProgressPhase.optional(),
-    mode: RenderMode.optional(),
-    priority: RenderPriority, // required per data-model.md § Render priority
-    intent: RenderIntent.optional(),
-    snapshot: RenderSnapshot.optional(),
-    snapshotRef: z.string().optional(),
-    outputUrl: z.string().url().optional(),
-    outputExpiresAt: z.number().optional(), // epoch ms
-    destinations: z.array(Destination).optional(),
-    destinationResults: z.array(DestinationResult).optional(),
-    cancelReason: RenderCancelReason.optional(),
-    // `error` is structured (richer than the doc's plain-string spec) so the worker
-    // can surface a stable code, a human message, and operator-visible details.
-    // See CONVEX_ADAPTATIONS.md for the rationale on richer-than-doc shapes.
-    error: z.object({
-        code: z.string(),
-        message: z.string(),
-        details: z.record(z.string(), z.unknown()).optional(),
-    }).optional(),
-    createdAt: z.number(),
-    updatedAt: z.number(),
-});
-export const RenderProgress = z.object({
-    jobId: zid("renderJobs"),
-    status: RenderStatus,
-    percent: z.number().min(0).max(100).optional(),
-    framesRendered: z.number().int().nonnegative().optional(),
-    framesTotal: z.number().int().positive().optional(),
-});

package/dist/_members/composition/validators/session.js

@@ -1,37 +0,0 @@
-import { z } from "zod";
-import { zid } from "convex-helpers/server/zod3";
-// Session per data-model.md § Session — a group of MediaItem items captured
-// together (multi-cam podcast, screen + facecam recording, two-person
-// interview on separate cameras). Each MediaItem in the session has a typed
-// `role`. Sessions can be muxed (audio role merged onto a video role).
-//
-// In a Composition, a scene references a session and specifies which angle
-// is active by role; the session resolves to a concrete `mediaId` at write
-// time and the TimelineClip stores the resolved id, not the session reference.
-export const SessionMediaRole = z.enum([
-    "main",
-    "wide",
-    "facecam",
-    "screen",
-    "audio",
-]);
-export const SessionMember = z.object({
-    mediaId: zid("mediaItems"),
-    role: SessionMediaRole,
-    label: z.string().optional(), // human-readable annotation, e.g., "host's camera"
-});
-// Mux pairing — audio role merged onto a video role at session-resolution time.
-// The renderer treats the muxed pair as a single source for sync and trim.
-export const SessionMux = z.object({
-    videoRole: z.enum(["main", "wide", "facecam", "screen"]),
-    audioRole: z.literal("audio"),
-});
-export const Session = z.object({
-    id: zid("sessions"),
-    name: z.string().min(1),
-    members: z.array(SessionMember).nonempty(),
-    mux: z.array(SessionMux).optional(),
-    ownerOrgId: z.string().optional(),
-    createdAt: z.number(),
-    updatedAt: z.number(),
-});

package/dist/_members/composition/validators/webhook.js

@@ -1,72 +0,0 @@
-import { z } from "zod";
-import { zid } from "convex-helpers/server/zod3";
-// Webhook per data-model.md — subscriber URLs that receive events for
-// substrate state transitions (renders, media, font, composition).
-// Delivery is at-least-once, with Standard Webhooks signing.
-//
-// Domain-extensible event names: `Webhook.events` is `string[]` so domain
-// packages (e.g. @cueframe/clip-model) can contribute their own event
-// vocabulary without forcing substrate to know about them. Each domain exports
-// its own typed enum (e.g. ClipsWebhookEvent) that consumers compose into the
-// `events` array; the substrate's SubstrateWebhookEvent enum below is the
-// canonical list of substrate-emitted events. The webhook delivery
-// infrastructure routes any event name.
-//
-// EMITTED-ONLY SSOT (#16 webhook-vocab honesty). This enum lists ONLY the
-// render/media/composition lifecycle events the substrate ACTUALLY fires (an
-// `event:` literal routed to webhooksFire.fireEvent). The previously-advertised
-// `render.queued/started/delivered/delivery_failed`, `media.uploaded`,
-// `media.spatial_ready`, `media.transcript_ready`, and the `font.*` family were
-// REMOVED: nothing emits them. Honesty over aspiration — advertising a webhook
-// the agent can never receive silently breaks its progress tracking. The convex
-// parity gate (api.webhookVocabParity.test.ts) asserts every value here has a
-// real emit site.
-export const SubstrateWebhookEvent = z.enum([
-    // Render lifecycle — A3 terminal family (plan 2026-07-10-flow-checkpoint):
-    // ONE terminal event per kind, `status` INSIDE the payload.
-    "render.completed",
-    // MediaItem lifecycle
-    "media.transcribed",
-    "media.completed",
-    // Composition lifecycle
-    "composition.updated",
-]);
-export const WebhookDeliveryStatus = z.enum([
-    "pending",
-    "delivering",
-    "delivered",
-    "failed",
-    "exhausted", // retry budget burned through
-]);
-export const Webhook = z.object({
-    id: zid("webhooks"),
-    url: z.string().url(),
-    // Open string array — substrate event names live in SubstrateWebhookEvent;
-    // domain packages export their own event enums and consumers compose them.
-    events: z.array(z.string().min(1)).nonempty(),
-    // Standard Webhooks signing key reference; the signing secret itself is
-    // stored server-side and never round-tripped through the API surface.
-    signingKeyId: z.string().optional(),
-    // Optional headers the subscriber wants on every delivery.
-    headers: z.record(z.string(), z.string()).optional(),
-    enabled: z.boolean().optional(),
-    ownerOrgId: z.string().optional(),
-    createdAt: z.number(),
-    updatedAt: z.number(),
-});
-// Per-attempt delivery record. Useful for the operator dashboard and for
-// the subscriber's "what did you receive" replay surface.
-export const WebhookDelivery = z.object({
-    id: z.string().min(1),
-    webhookId: zid("webhooks"),
-    // Open string — could be any substrate or domain event name.
-    event: z.string().min(1),
-    payload: z.record(z.string(), z.unknown()),
-    status: WebhookDeliveryStatus,
-    attemptCount: z.number().int().nonnegative(),
-    responseStatus: z.number().int().optional(),
-    responseBody: z.string().optional(),
-    error: z.string().optional(),
-    createdAt: z.number(),
-    deliveredAt: z.number().optional(),
-});

package/dist/_members/composition-ops/alphaLayers.js

@@ -1,141 +0,0 @@
-/**
- * Alpha-layer clip walk — the SINGLE shared, V8-safe home for finding a wire
- * composition's alpha-layer clips (overlay-track clips whose
- * `source.kind === 'alpha-layer'`).
- *
- * This is PURE and crypto-free on purpose: both the director (Node worker, which
- * bakes the alpha) and Convex (V8 isolate, which materializes the authored
- * tsxSource into the stage body) walk the SAME composition for the SAME clips —
- * so the walk is the SSOT and lives here, importable from both. The director's
- * content-hash (`alphaLayerHash`, uses `node:crypto`) stays director-side; it is
- * NOT shareable with the V8 isolate and is orthogonal to the walk.
- */
-/**
- * Walk a wire composition for alpha-layer clips (overlay-track clips whose
- * `source.kind === 'alpha-layer'`). Pure + tolerant of unknown shape (skips
- * malformed entries rather than throwing — the validator already gated saves).
- */
-export function collectAlphaLayerClips(composition) {
-    const tracks = composition?.tracks;
-    if (!Array.isArray(tracks))
-        return [];
-    const out = [];
-    for (const track of tracks) {
-        const contents = track?.contents;
-        if (!Array.isArray(contents))
-            continue;
-        for (const c of contents) {
-            const src = c?.source;
-            if (!src || typeof src !== "object")
-                continue;
-            if (src.kind !== "alpha-layer")
-                continue;
-            const componentId = src.componentId;
-            const clipId = c.id;
-            const startTime = c.startTime;
-            const duration = c.duration;
-            if (typeof componentId !== "string" || componentId.length === 0)
-                continue;
-            if (typeof clipId !== "string" || clipId.length === 0)
-                continue;
-            if (typeof startTime !== "number" || typeof duration !== "number" || duration <= 0)
-                continue;
-            const rawProps = src.props;
-            const props = rawProps && typeof rawProps === "object" && !Array.isArray(rawProps)
-                ? rawProps
-                : {};
-            out.push({ clipId, componentId, props, startTime, duration });
-        }
-    }
-    return out;
-}
-/**
- * Walk a wire composition for RAW `component` clip sources — sources that have
- * NOT been desugared and therefore cannot be projected by the renderer.
- *
- * `component` is a first-class `ClipSource` in the validator, but it is an
- * AUTHORING shape, never a render one: the cloud's save/writer chokepoint
- * (`services/convex/composition/projection.ts`) lowers every one of them to an
- * `alpha-layer` or a `custom` overlay before it is persisted, reading the
- * component's `executionMode` from the `installedComponents` table. Anything
- * that reaches `projectOverlayTrack` still wearing `kind:'component'` throws
- * `kind=component is invalid on an overlay track`.
- *
- * That throw is why this exists. On the desktop lane there is no such
- * chokepoint (and no registry to lower against), so an agent-authored component
- * clip committed straight to the store, the preview projected it during render,
- * and the throw escaped a `useMemo` into the app-root ErrorBoundary — the entire
- * editor replaced by "Something went wrong", with the broken composition saved,
- * so every subsequent open died the same way. Observed 2026-08-18.
- *
- * Two callers, which is the point of putting it here rather than in either of
- * them: the desktop plane REFUSES an apply that would create one, and the
- * preview GATE holds the player with a readable reason if a project already
- * contains one. The first stops the state being reachable; the second is how
- * anyone who already reached it gets their project open again.
- *
- * Pure + tolerant of unknown shape, like its siblings above.
- */
-export function collectRawComponentClips(composition) {
-    const tracks = composition?.tracks;
-    if (!Array.isArray(tracks))
-        return [];
-    const out = [];
-    for (const track of tracks) {
-        const contents = track?.contents;
-        if (!Array.isArray(contents))
-            continue;
-        for (const c of contents) {
-            const src = c?.source;
-            if (!src || typeof src !== "object")
-                continue;
-            if (src.kind !== "component")
-                continue;
-            const id = c.id;
-            out.push(typeof id === "string" && id.length > 0 ? id : "(unnamed clip)");
-        }
-    }
-    return out;
-}
-/**
- * Walk a wire composition for LIVE component-backed `custom` overlays — the
- * bakeless-lane peer of `collectAlphaLayerClips`. A live component desugars (at
- * the save writer) to `{ kind:'overlay', primitiveId:'custom', params:{
- * componentId, ...props } }` — a componentId REFERENCE with no frozen source.
- * The renderJob-create path (renders.ts) walks these to materialize each
- * component's FRESH transpiled jsSource per render (keyed by clipId). Pure +
- * tolerant of unknown shape. Desktop-INLINE customs (which carry their own
- * `params.sourceCode` and no `componentId`) are NOT returned — they need no
- * materialization.
- */
-export function collectLiveComponentClips(composition) {
-    const tracks = composition?.tracks;
-    if (!Array.isArray(tracks))
-        return [];
-    const out = [];
-    for (const track of tracks) {
-        const contents = track?.contents;
-        if (!Array.isArray(contents))
-            continue;
-        for (const c of contents) {
-            const src = c?.source;
-            if (!src || typeof src !== "object")
-                continue;
-            if (src.kind !== "overlay")
-                continue;
-            if (src.primitiveId !== "custom")
-                continue;
-            const params = src.params;
-            const componentId = params && typeof params === "object"
-                ? params.componentId
-                : undefined;
-            const clipId = c.id;
-            if (typeof componentId !== "string" || componentId.length === 0)
-                continue;
-            if (typeof clipId !== "string" || clipId.length === 0)
-                continue;
-            out.push({ clipId, componentId });
-        }
-    }
-    return out;
-}