@cueframe/kernel 0.1.0 → 0.1.2

package/dist/_members/mcp/generated/operations.d.ts

@@ -1,16 +1,3 @@
-/**
- * AUTO-GENERATED — do not edit by hand.
- *
- * Source: docs/api/openapi.json
- * Generator: packages/mcp/scripts/generate-tools.mjs
- * Re-run: `pnpm generate:mcp-tools` from the repo root.
- *
- * Transport-agnostic operation manifest. One entry per OpenAPI operation;
- * consumed by the generic raw-tool registrar and the curated tools (for paths)
- * in src/server.ts, executed through the per-transport Executor. CI fails if
- * this file drifts from the current spec.
- */
-/** MCP tool annotations — client-side hints. See the MCP spec's ToolAnnotations. */
 export interface GeneratedAnnotations {
     readOnlyHint: boolean;
     destructiveHint?: boolean;
@@ -18,24 +5,14 @@ export interface GeneratedAnnotations {
     openWorldHint: boolean;
 }
 export interface GeneratedOperation {
-    /** OpenAPI operationId, e.g. "createCompose". */
     operationId: string;
-    /** Raw MCP tool name, e.g. "cueframe_api_createCompose". */
     toolName: string;
-    /** Human-facing title, e.g. "Create Compose". Required by directory reviews. */
     title: string;
-    /** HTTP method, upper-case. */
     method: string;
-    /** Spec path, /v1-prefixed, e.g. "/v1/projects/{id}/compose". */
     pathTemplate: string;
-    /** Path parameter names in declaration order, e.g. ["id"]. */
     pathParams: string[];
-    /** bodySchemas key for the request body, or null for body-less ops. */
     bodyKey: string | null;
-    /** Human/agent-facing description (raw expert layer). */
     description: string;
-    /** Method-derived client hints. Curated entries may override (curation.ts). */
     annotations: GeneratedAnnotations;
 }
-/** 116 operations derived from docs/api/openapi.json. */
 export declare const GENERATED_OPERATIONS: GeneratedOperation[];

package/dist/_members/mcp/internalLoopTools.d.ts

@@ -1,25 +1,2 @@
-/**
- * INTERNAL in-loop tool registry (A11/A12: the director's in-loop tool names
- * are internal names, exempt from the client-surface rename story).
- *
- * The 2026-07 verb cutover removed the SESSION-SCOPED ops from the public curated
- * surface. But the DIRECTOR's own author/designer loops kept running against a real
- * session — `pathArgs: { projectId, sessionId }` — and THAT is what gave "render this
- * composition at time T" two implementations chosen by caller identity: the agent could
- * not physically address the stateless path, because every sighted tool it had was
- * session-addressed.
- *
- * They are sessionless now, and it needed no new endpoints: these ops already took
- * `body.composition`, so the agent was always sending the very thing it wanted rendered.
- * The `sessionId` in the path never carried composition state — it carried a BOX.
- * Dropping it means the Director's loop and the public API run the ONE seam
- * (bake → stateless capture), and the agent's stills are the SAME content-addressed R2
- * objects the judge grades — so it can no longer be scored on frames it never saw.
- *
- * `commit_session` stays session-addressed: it promotes the run's SCRATCH composition
- * (a real Convex composition row) to active. That scratch is composition versioning, not
- * a box — candidate isolation is a product requirement (only the winner saves), and it
- * survives the box's removal untouched.
- */
 import type { CuratedTool } from './curation.js';
 export declare const INTERNAL_LOOP_TOOLS: CuratedTool[];

package/dist/_members/mcp/prompts.d.ts

@@ -1,22 +1,6 @@
-/**
- * Skills-as-prompts.
- *
- * Each published SKILL.md becomes an MCP *prompt*: metadata registered up front,
- * full markdown fetched on demand. SKILL.md stays the single source of truth.
- * Executed through the transport's `Executor` (stdio: network; hosted: in-process)
- * against the public skills ops from the generated manifest.
- *
- * The skill LIST is memoized at module scope so the hosted per-request server
- * doesn't re-fetch it on every request (a warm isolate populates it once).
- *
- * `failLoud`: stdio sets it (boot once — a missing skills API means a broken
- * server, surface it). Hosted leaves it false — a transient skills hiccup must
- * NOT break an unrelated tool call; prompts are simply skipped that request.
- */
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Executor } from './core.js';
 export declare function registerSkillPrompts(server: McpServer, ex: Executor, opts?: {
     failLoud?: boolean;
 }): Promise<void>;
-/** Test seam — reset the memoized skill list. */
 export declare function __resetSkillCache(): void;

package/dist/_members/mcp/resources.d.ts

@@ -1,16 +1,3 @@
-/**
- * CueFrame MCP resources — the read side of the surface (no side effects).
- *
- * Every read endpoint is a URI-addressed MCP *resource*, executed through the
- * transport's `Executor` (stdio: network; hosted: in-process) against the GET
- * op's path from the generated manifest — the SAME single source of truth the
- * tools use, so paths are never hand-maintained. Four templates (media,
- * component, project, brand-kit) also carry a `list` callback so resources/list
- * enumerates concrete instances via the matching list op.
- *
- * Fail-loud: a non-2xx read throws, which the MCP server surfaces as a JSON-RPC
- * error (no try/catch swallow).
- */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Executor } from './core.js';
 export declare function registerResources(server: McpServer, ex: Executor): void;

package/dist/_members/mcp/server.d.ts

@@ -1,69 +1,19 @@
-/**
- * CueFrame MCP — transport-agnostic core. NO transport import lives here, so
- * both the stdio entry (index.ts) and the hosted Hono route
- * (the hosted MCP route) build their server from this one module.
- *
- * Layers (all execute through the injected `Executor`, paths from the generated
- * manifest — single source of truth, drift-gated):
- *   - curated front-door  → registerCuratedTools  (hand-picked names + guidance)
- *   - raw expert layer    → registerRawTools      (generic, one tool per op)
- *   - read resources      → registerResources     (resources.ts)
- *   - skills-as-prompts   → registerSkillPrompts   (prompts.ts; async, by caller)
- */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Executor } from './core.js';
 export { registerSkillPrompts, __resetSkillCache } from './prompts.js';
 export { SERVER_INSTRUCTIONS } from './generated/harness.js';
 export type { Executor } from './core.js';
-/**
- * Transport-agnostic telemetry contract. The core emits; the TRANSPORT decides
- * where it lands (the hosted Convex route ships these to PostHog; stdio passes
- * no sink and pays nothing). Keeping this a plain callback is what lets the
- * package stay free of any analytics dependency.
- */
-/**
- * A completed tool call. No `errorKind`: every handler here already converts a
- * throw into an `isError` result before the wrapper sees it, so a thrown-error
- * class could never be populated — it would be a permanently-null column.
- */
 export type McpTelemetryEvent = {
     tool: string;
     isError: boolean;
-    /**
-     * Preview-attachment outcome, when the tool carries media. `urls` is what the
-     * extractor found in the response; `fetched` is how many actually encoded.
-     *
-     * This rides the SINK, not console.log: the core stays transport-agnostic (it
-     * also ships as a stdio npm package with no Convex in scope), and the hosted
-     * route decides where it lands. urls>0 with fetched===0 is the signature of a
-     * runtime-level failure — it is how the Buffer-in-Convex crash was finally
-     * found, after being invisible behind a silent catch.
-     */
     preview?: {
         urls: number;
         fetched: number;
     };
 };
 export type McpTelemetrySink = (event: McpTelemetryEvent) => void;
-/**
- * Operations the RAW expert layer must not register, even though they are in the
- * manifest. This is a raw-layer property, not a manifest one: the manifest is the
- * transport-agnostic op SSOT the CURATED layer resolves paths through (`opById`),
- * so an op dropped from it becomes uncuratable.
- *
- * `searchLibrary` — the raw registrar builds its inputSchema from path params +
- * the request body only, and every argument of GET /v1/media/search is a QUERY
- * param. `q` is REQUIRED, so the raw tool could not send it and would 400 on
- * every call — worse than absent, because an agent reads that 400 as "the
- * feature is broken". The working surface is the curated `search_library`
- * (internalLoopTools.ts) whose `queryArgs` the adapter threads onto the URL.
- * DELETE this entry once the generator + this registrar thread query params
- * (internal issue 2026-08-07 — the Executor
- * already carries `query`).
- */
 export declare const RAW_EXCLUDED_OPERATION_IDS: ReadonlySet<string>;
 export declare function registerRawTools(server: McpServer, ex: Executor, onEvent?: McpTelemetrySink): void;
-/** `create_render` → "Create Render". Default title for a curated tool. */
 export declare function titleCase(name: string): string;
 export declare function registerCuratedTools(server: McpServer, ex: Executor, opts?: {
     waitCapMs?: number;
@@ -72,21 +22,10 @@ export declare function registerCuratedTools(server: McpServer, ex: Executor, op
 }): void;
 export interface BuildServerOpts {
     executor: Executor;
-    /** Expose the raw `cueframe_api_*` expert layer (one tool per operation). */
     expert?: boolean;
-    /** SERVER_INSTRUCTIONS harness, if any. */
     instructions?: string;
-    /** Cap wait_job blocking (ms). Hosted transports set this under the Convex
-     * httpAction limit; stdio leaves it unset (30-min default applies). */
     waitCapMs?: number;
-    /** Optional telemetry sink. Omitted on stdio; the hosted route supplies one
-     * so agent discovery (initialize) and tool usage are measurable. */
     onEvent?: McpTelemetrySink;
 }
 export declare function buildServer(opts: BuildServerOpts): McpServer;
-/**
- * A12 burned names: each dead verb registers as a TOMBSTONE — calling it
- * hard-errors with the replacement instead of a bare method-not-found, so an
- * agent with a stale memory of the surface gets re-taught in one round-trip.
- */
 export declare function registerBurnedTombstones(server: McpServer, onEvent?: McpTelemetrySink): void;

package/dist/_members/mcp/wait.d.ts

@@ -1,37 +1,15 @@
-/**
- * `wait_job` — block until a long-running job reaches a terminal state, by
- * POLLING its status endpoint through the Executor. Unified across transports:
- * the same poll loop works for stdio (network) and hosted (in-process), so the
- * blocking-SSE path is gone (the agent only ever sees the terminal result, so
- * polling is functionally equivalent; `create_webhook` is the event-driven path
- * for fan-out). Pure + side-effect-free (clock/sleep injectable) so it unit-tests
- * without a server.
- */
 import { type Executor } from './core.js';
 export type WaitResult = {
     ok: boolean;
     text: string;
-    /** True when the wait window expired with the job still running — a
-     *  CONTINUATION, not an error: the caller re-invokes wait_job to keep
-     *  waiting (bounded long-poll; plan 2026-07-06-bounded-api-jobs). */
     stillRunning?: boolean;
-    /** Image urls to attach as MCP image blocks. An async tool's pixels arrive at
-     *  wait_job, not at the enqueue call, so this is where they must surface —
-     *  preview_component's own 202 carries only a jobId. Same treatment
-     *  adapter.ts:578 already gives this url on the ai-SDK path. */
     mediaUrls?: string[];
 };
 export type WaitKind = 'render' | 'compose' | 'suggestions' | 'verify' | 'preview' | 'brand_kit_extract' | 'consult';
 export interface WaitDeps {
     sleep?: (ms: number) => Promise<void>;
     now?: () => number;
-    /** Poll interval; overridable for fast tests. */
     pollMs?: number;
-    /** Reserved headroom for one status invoke (overshoot guard); test override. */
     invokeBudgetMs?: number;
 }
-/**
- * Poll a job's status op until terminal or the deadline. 4xx → fail loud
- * immediately; 5xx/transient → keep polling; 2xx non-terminal → sleep + retry.
- */
 export declare function waitForJob(ex: Executor, kind: WaitKind, id: string, projectId: string | undefined, deadline: number, deps?: WaitDeps): Promise<WaitResult>;

package/dist/_members/mcp/x402Meta.d.ts

@@ -1,50 +1,6 @@
-/**
- * x402-over-MCP wire constants + helpers, VENDORED from the first-party
- * `@x402/mcp` package and pinned to it by `x402Meta.conformance.test.ts`.
- *
- * Why vendored instead of `import … from "@x402/mcp"`: the published `@x402/mcp`
- * dist is a single bundle that imports `@x402/core/client` + `/server`
- * (viem/Buffer) at MODULE scope, so importing even a constant drags Buffer into
- * the Convex V8 isolate — the exact failure `x402Facilitator.ts` is `"use node"`
- * to avoid. This module is plain-JSON + `btoa` only, so it is V8-safe and runs in
- * both the hosted (V8 isolate) and stdio (Node) transports. Same generator/runtime
- * split as `x402Discovery` (a Node test tracks the spec; the runtime reads plain
- * data). The conformance test fails if these drift from `@x402/mcp`.
- *
- * The convention (Cloudflare/Coinbase/Vercel + `@x402/mcp`): over MCP, payment
- * rides in the JSON-RPC `_meta` field, NOT an HTTP header — MCP is transport-
- * agnostic (stdio has no HTTP layer). The `PaymentPayload` / `PaymentRequired`
- * objects are byte-identical to CueFrame's REST v2 envelope; only the carrier
- * differs (`_meta` key vs `PAYMENT-SIGNATURE`/`Payment-Required` header).
- */
-/** Client → server: the signed EIP-3009 `PaymentPayload`, on the tools/call `_meta`. */
 export declare const MCP_PAYMENT_META_KEY = "x402/payment";
-/** JSON-RPC error code a paid tool returns when called unpaid. */
 export declare const MCP_PAYMENT_REQUIRED_CODE = 402;
-/** Loose `_meta` bag as seen on a tools/call request (SDK `extra._meta`). */
 export type RequestMeta = Record<string, unknown> | undefined;
-/**
- * True iff a parsed body is a canonical x402 `PaymentRequired` challenge (has a
- * numeric `x402Version` and an `accepts` array) — matching the @x402/mcp client's
- * `isPaymentRequiredStructure`. Used to tell the REAL 402 payment challenge apart
- * from the OTHER errors that share HTTP 402 (billing_required,
- * generation_budget_exceeded, payment_invalid, …), which must surface as typed
- * errors, not an x402 "sign a payment" prompt.
- */
 export declare function isX402PaymentRequired(body: unknown): body is Record<string, unknown>;
-/**
- * Read the client's signed payment (a `PaymentPayload` object) off a tools/call
- * `_meta`. Returns the raw object or null; the STRUCTURE is validated downstream
- * by the facilitator's EIP-3009 decode (single source of truth), so this is a
- * presence/shape gate only — never trust it as verified payment.
- */
 export declare function extractPaymentFromMeta(meta: RequestMeta): Record<string, unknown> | null;
-/**
- * Encode a `PaymentPayload` object into the base64 `PAYMENT-SIGNATURE` header
- * value the REST x402 middleware decodes (`@x402/core` `encodePaymentSignatureHeader`
- * = `safeBase64Encode(JSON.stringify(payload))`). `btoa`-based → V8-safe; mirrors
- * `@x402/core`'s own `safeBase64Encode` (which is also btoa-first). This lets an
- * MCP tool call forward its `_meta` payment INTO the unchanged REST verify/settle
- * path via the inner `app.fetch`, reusing all money-safety.
- */
 export declare function encodePaymentSignature(payload: unknown): string;

package/dist/_members/media-model/generation.d.ts

@@ -0,0 +1,314 @@
+import { z } from "zod";
+export declare const MediaId: z.ZodBranded<z.ZodString, "Id<media>">;
+export type MediaId = z.infer<typeof MediaId>;
+export declare const GenerationId: z.ZodBranded<z.ZodString, "Id<generation>">;
+export type GenerationId = z.infer<typeof GenerationId>;
+export declare const GenerationGroupId: z.ZodBranded<z.ZodString, "Id<generationGroup>">;
+export type GenerationGroupId = z.infer<typeof GenerationGroupId>;
+export declare const ClientRequestId: z.ZodBranded<z.ZodString, "Id<generationRequest>">;
+export type ClientRequestId = z.infer<typeof ClientRequestId>;
+export declare const ProjectHome: z.ZodEnum<["local", "cloud"]>;
+export type ProjectHome = z.infer<typeof ProjectHome>;
+export declare const MediaKind: z.ZodEnum<["image", "video", "audio"]>;
+export type MediaKind = z.infer<typeof MediaKind>;
+export declare const MediaGenerator: z.ZodEnum<["text-to-video", "text-to-image", "image-to-video", "text-to-music", "text-to-speech", "text-to-sfx", "auto"]>;
+export type MediaGenerator = z.infer<typeof MediaGenerator>;
+export declare const GenerationReference: z.ZodObject<{
+    role: z.ZodEnum<["first-frame", "last-frame", "image", "source"]>;
+    mediaId: z.ZodBranded<z.ZodString, "Id<media>">;
+}, "strip", z.ZodTypeAny, {
+    mediaId: string & z.BRAND<"Id<media>">;
+    role: "image" | "source" | "first-frame" | "last-frame";
+}, {
+    mediaId: string;
+    role: "image" | "source" | "first-frame" | "last-frame";
+}>;
+export type GenerationReference = z.infer<typeof GenerationReference>;
+export declare const GenerateMediaCommand: z.ZodObject<{
+    clientRequestId: z.ZodBranded<z.ZodString, "Id<generationRequest>">;
+    generator: z.ZodEnum<["text-to-video", "text-to-image", "image-to-video", "text-to-music", "text-to-speech", "text-to-sfx", "auto"]>;
+    prompt: z.ZodString;
+    style: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    references: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<["first-frame", "last-frame", "image", "source"]>;
+        mediaId: z.ZodBranded<z.ZodString, "Id<media>">;
+    }, "strip", z.ZodTypeAny, {
+        mediaId: string & z.BRAND<"Id<media>">;
+        role: "image" | "source" | "first-frame" | "last-frame";
+    }, {
+        mediaId: string;
+        role: "image" | "source" | "first-frame" | "last-frame";
+    }>, "many">>;
+    generationGroupId: z.ZodOptional<z.ZodBranded<z.ZodString, "Id<generationGroup>">>;
+    parentMediaId: z.ZodOptional<z.ZodBranded<z.ZodString, "Id<media>">>;
+    variationNonce: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+    clientRequestId: string & z.BRAND<"Id<generationRequest>">;
+    generator: "text-to-speech" | "text-to-image" | "image-to-video" | "text-to-video" | "text-to-music" | "text-to-sfx" | "auto";
+    references: {
+        mediaId: string & z.BRAND<"Id<media>">;
+        role: "image" | "source" | "first-frame" | "last-frame";
+    }[];
+    style?: Record<string, unknown> | undefined;
+    generationGroupId?: (string & z.BRAND<"Id<generationGroup>">) | undefined;
+    parentMediaId?: (string & z.BRAND<"Id<media>">) | undefined;
+    variationNonce?: string | undefined;
+}, {
+    prompt: string;
+    clientRequestId: string;
+    generator: "text-to-speech" | "text-to-image" | "image-to-video" | "text-to-video" | "text-to-music" | "text-to-sfx" | "auto";
+    style?: Record<string, unknown> | undefined;
+    references?: {
+        mediaId: string;
+        role: "image" | "source" | "first-frame" | "last-frame";
+    }[] | undefined;
+    generationGroupId?: string | undefined;
+    parentMediaId?: string | undefined;
+    variationNonce?: string | undefined;
+}>;
+export type GenerateMediaCommand = z.infer<typeof GenerateMediaCommand>;
+export declare const GenerationReceipt: z.ZodObject<{
+    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;
+    providerJobId: z.ZodOptional<z.ZodString>;
+    estimateUsd: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    mediaId: string & z.BRAND<"Id<media>">;
+    clientRequestId: string & z.BRAND<"Id<generationRequest>">;
+    generationGroupId: string & z.BRAND<"Id<generationGroup>">;
+    generationId: string & z.BRAND<"Id<generation>">;
+    version: number;
+    providerJobId?: string | undefined;
+    estimateUsd?: number | undefined;
+}, {
+    mediaId: string;
+    clientRequestId: string;
+    generationGroupId: string;
+    generationId: string;
+    version: number;
+    providerJobId?: string | undefined;
+    estimateUsd?: number | undefined;
+}>;
+export type GenerationReceipt = z.infer<typeof GenerationReceipt>;
+export declare const GenerationStatus: z.ZodEnum<["draft", "submitting", "queued", "generating", "provider_complete", "materialising", "processing", "ready", "cancelling", "cancelled", "failed"]>;
+export type GenerationStatus = z.infer<typeof GenerationStatus>;
+export declare const GenerationFailure: 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;
+}>;
+export type GenerationFailure = z.infer<typeof GenerationFailure>;
+export declare const GenerationArtifact: 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;
+}>;
+export type GenerationArtifact = z.infer<typeof GenerationArtifact>;
+export declare const GenerationCapability: z.ZodObject<{
+    generator: z.ZodEnum<["text-to-video", "text-to-image", "image-to-video", "text-to-music", "text-to-speech", "text-to-sfx", "auto"]>;
+    outputKind: z.ZodEnum<["image", "video", "audio"]>;
+    referenceRoles: z.ZodArray<z.ZodEnum<["first-frame", "last-frame", "image", "source"]>, "many">;
+    durationSec: z.ZodOptional<z.ZodObject<{
+        min: z.ZodNumber;
+        max: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        min: number;
+        max: number;
+    }, {
+        min: number;
+        max: number;
+    }>>;
+    aspectRatios: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    supportsCancellation: z.ZodBoolean;
+    supportsParallelAttempts: z.ZodBoolean;
+    supportsQuote: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    generator: "text-to-speech" | "text-to-image" | "image-to-video" | "text-to-video" | "text-to-music" | "text-to-sfx" | "auto";
+    outputKind: "video" | "audio" | "image";
+    referenceRoles: ("image" | "source" | "first-frame" | "last-frame")[];
+    supportsCancellation: boolean;
+    supportsParallelAttempts: boolean;
+    supportsQuote: boolean;
+    durationSec?: {
+        min: number;
+        max: number;
+    } | undefined;
+    aspectRatios?: string[] | undefined;
+}, {
+    generator: "text-to-speech" | "text-to-image" | "image-to-video" | "text-to-video" | "text-to-music" | "text-to-sfx" | "auto";
+    outputKind: "video" | "audio" | "image";
+    referenceRoles: ("image" | "source" | "first-frame" | "last-frame")[];
+    supportsCancellation: boolean;
+    supportsParallelAttempts: boolean;
+    supportsQuote: boolean;
+    durationSec?: {
+        min: number;
+        max: number;
+    } | undefined;
+    aspectRatios?: string[] | undefined;
+}>;
+export type GenerationCapability = z.infer<typeof GenerationCapability>;
+export declare const GenerationCapabilities: z.ZodArray<z.ZodObject<{
+    generator: z.ZodEnum<["text-to-video", "text-to-image", "image-to-video", "text-to-music", "text-to-speech", "text-to-sfx", "auto"]>;
+    outputKind: z.ZodEnum<["image", "video", "audio"]>;
+    referenceRoles: z.ZodArray<z.ZodEnum<["first-frame", "last-frame", "image", "source"]>, "many">;
+    durationSec: z.ZodOptional<z.ZodObject<{
+        min: z.ZodNumber;
+        max: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        min: number;
+        max: number;
+    }, {
+        min: number;
+        max: number;
+    }>>;
+    aspectRatios: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    supportsCancellation: z.ZodBoolean;
+    supportsParallelAttempts: z.ZodBoolean;
+    supportsQuote: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    generator: "text-to-speech" | "text-to-image" | "image-to-video" | "text-to-video" | "text-to-music" | "text-to-sfx" | "auto";
+    outputKind: "video" | "audio" | "image";
+    referenceRoles: ("image" | "source" | "first-frame" | "last-frame")[];
+    supportsCancellation: boolean;
+    supportsParallelAttempts: boolean;
+    supportsQuote: boolean;
+    durationSec?: {
+        min: number;
+        max: number;
+    } | undefined;
+    aspectRatios?: string[] | undefined;
+}, {
+    generator: "text-to-speech" | "text-to-image" | "image-to-video" | "text-to-video" | "text-to-music" | "text-to-sfx" | "auto";
+    outputKind: "video" | "audio" | "image";
+    referenceRoles: ("image" | "source" | "first-frame" | "last-frame")[];
+    supportsCancellation: boolean;
+    supportsParallelAttempts: boolean;
+    supportsQuote: boolean;
+    durationSec?: {
+        min: number;
+        max: number;
+    } | undefined;
+    aspectRatios?: string[] | undefined;
+}>, "many">;
+export type GenerationCapabilities = z.infer<typeof GenerationCapabilities>;
+export interface GenerationStateSources {
+    attempt: {
+        status: Exclude<GenerationStatus, "materialising" | "processing" | "ready">;
+        progress?: number;
+        failure?: GenerationFailure;
+    };
+    resource: {
+        kind: MediaKind;
+        durable: boolean;
+        decodable: boolean;
+        metadataReady: boolean;
+        placementReady: boolean;
+    };
+    materialisation: {
+        required: boolean;
+        status: "not_started" | "pending_source" | "downloading" | "complete" | "failed";
+        verifiedBytes: boolean;
+        failure?: GenerationFailure;
+    };
+}
+export declare function deriveGenerationStatus(sources: GenerationStateSources): {
+    status: GenerationStatus;
+    placementReady: boolean;
+    failure?: GenerationFailure;
+};

package/dist/_members/media-model/index.d.ts

@@ -1 +1,2 @@
 export * from "./api.js";
+export * from "./generation.js";

package/dist/_members/media-model/media-kind.d.ts

@@ -1,36 +1,9 @@
-/** `opaque` is `asset` renamed (spec §5): "asset" was the word that made two
- *  different concepts — storage furniture and a media classification — look
- *  like one. `opaque` states the contract: no pipeline, not placeable. */
 export type MediaKind = "video" | "audio" | "image" | "opaque";
 export declare const IMAGE_CONTENT_TYPES: readonly ["image/png", "image/jpeg", "image/webp"];
-/** Closed allowlist — the complete set of accepted content-types (the acceptance
- *  gate). mediaKind() routes each: video/audio/still-image do real work;
- *  fonts/json/svg/gif route to the opaque path. Unknown bytes (not here)
- *  are rejected at the edge. */
 export declare const ALLOWED_CONTENT_TYPES: readonly ["video/mp4", "video/quicktime", "video/x-matroska", "video/webm", "audio/mpeg", "audio/wav", "audio/x-wav", "audio/mp4", "audio/aac", "image/png", "image/jpeg", "image/webp", "image/gif", "image/svg+xml", "application/json", "font/ttf", "font/otf", "font/woff", "font/woff2"];
 export type AllowedContentType = (typeof ALLOWED_CONTENT_TYPES)[number];
 export declare function mediaKind(contentType: string): MediaKind;
 export declare function extensionForContentType(contentType: string): string;
-/** What a file IS, from nothing but its name — the ONE derivation the import
- *  door, the project-file parse gate, and migration 020's SQL all mirror. */
 export declare function mediaKindForFilename(filename: string): MediaKind;
-/** Every extension whose derived kind can occupy time. The import door's
- *  accept-list IS this list — derived, so the door and the authority cannot
- *  disagree (the disagreement was a thrown import for `.jpeg`/`.m4a`). */
 export declare const POOL_EXTENSIONS: readonly string[];
-/**
- * The content-type to UPLOAD a file as, given what the platform claimed and
- * what the file is called.
- *
- * WHY THIS EXISTS. The upload client used to send `file.type || "video/mp4"`.
- * Both halves are wrong: the alias case rejects real MP3s (see above), and the
- * fallback silently relabels ANY untyped file as video — so an MP3 dragged in
- * without a MIME is accepted and then routed down the VIDEO transcode path by
- * `mediaKind()`, which is a wrong pipeline rather than an honest refusal.
- *
- * Order: an already-allowed type wins, then a known alias, then the extension.
- * If none of those resolve, the ORIGINAL string is returned unchanged — never a
- * guess. The closed gate then refuses it and names the type the user actually
- * has, which is the error message they need.
- */
 export declare function contentTypeForUpload(filename: string, claimed?: string | null): string;