@tangle-network/agent-app 0.45.54 → 0.45.55

package/dist/sandbox/recovery.d.ts

@@ -0,0 +1,216 @@
+/**
+ * What an app does after the platform hands back a sandbox it cannot use.
+ *
+ * `replaceUnbringableBox` (see `./index`) decides whether to abandon a dead box.
+ * This decides everything around that: which box key the next attempt uses,
+ * whether the old box's snapshot is safe to restore from, whether an owner has
+ * to confirm the loss first, and what the person waiting is told. It is
+ * bookkeeping, not I/O — the app supplies storage through
+ * {@link WorkspaceSandboxRecoveryStore}.
+ *
+ * ── Why the tables ──────────────────────────────────────────────────────────
+ * Every fact about an action or a code lives in ACTIONS/CODES below, and the
+ * types are DERIVED from those tables. That is deliberate, and it is the whole
+ * reliability argument for this module.
+ *
+ * The hand-maintained alternative — a union type plus a separate `x === 'a' ||
+ * x === 'b' || …` list per question — silently drops anything not on the list.
+ * A recovery recorded under an unlisted action is written to storage, read
+ * back, discarded as malformed, and the workspace re-provisions the box it just
+ * abandoned. Nothing throws. The fix looks correct, ships, and does nothing.
+ * That failure was hit twice inside one change before this module existed.
+ *
+ * With the tables, adding an action or code is a compile error until every
+ * question about it is answered. There is no list to forget.
+ */
+/** The box exists and still holds unsnapshotted state, so discarding it is an
+ *  owner's decision, not the runtime's. */
+export declare const EGRESS_PROXY_RECOVERY_REQUIRED = "EGRESS_PROXY_RECOVERY_REQUIRED";
+export declare const EGRESS_PROXY_RECOVERY_PHASE = "egress_proxy_recovery";
+/** The platform no longer has the box. Nothing to confirm, delete, or restore. */
+export declare const WORKSPACE_SANDBOX_MISSING = "WORKSPACE_SANDBOX_MISSING";
+/** The box exists but its host has no free slot, so it can never be resumed
+ *  where it is. A replacement can be placed on a host with room. */
+export declare const WORKSPACE_SANDBOX_HOST_EXHAUSTED = "WORKSPACE_SANDBOX_HOST_EXHAUSTED";
+/** The platform ran its own recovery, failed, and asked for a replacement.
+ *  Covers every way a box ends up unbringable with no more specific cause. */
+export declare const WORKSPACE_SANDBOX_UNRECOVERABLE = "WORKSPACE_SANDBOX_UNRECOVERABLE";
+export declare const WORKSPACE_SANDBOX_SNAPSHOT_MAX_AGE_MS: number;
+/**
+ * Every recovery cause, and the one thing the runtime must know about each:
+ * whether the box it names can still be read from.
+ *
+ * `snapshotUsable: false` is not a preference. A snapshot is addressed by the
+ * sandbox it was taken from, so when that sandbox cannot be started the restore
+ * fails exactly the way the resume did — and an app that tried it would turn a
+ * recoverable workspace into a stuck one.
+ */
+declare const CODES: {
+    readonly EGRESS_PROXY_RECOVERY_REQUIRED: {
+        readonly snapshotUsable: true;
+    };
+    readonly WORKSPACE_SANDBOX_MISSING: {
+        readonly snapshotUsable: false;
+    };
+    readonly WORKSPACE_SANDBOX_HOST_EXHAUSTED: {
+        readonly snapshotUsable: false;
+    };
+    readonly WORKSPACE_SANDBOX_UNRECOVERABLE: {
+        readonly snapshotUsable: false;
+    };
+};
+export type WorkspaceSandboxRecoveryCode = keyof typeof CODES;
+/**
+ * Every recovery action, and whether it means a replacement box has been
+ * CHOSEN — the single question that decides which box key the next provisioning
+ * attempt uses.
+ *
+ * `replacementChosen: false` covers the states where a key may be recorded but
+ * must not be used yet: an owner has been asked and has not answered, or has
+ * answered no. Handing back a key in those states replaces a box the owner
+ * declined to lose.
+ */
+declare const ACTIONS: {
+    readonly confirmation_required: {
+        readonly replacementChosen: false;
+    };
+    readonly deletion_declined: {
+        readonly replacementChosen: false;
+    };
+    readonly replacement_authorized: {
+        readonly replacementChosen: false;
+    };
+    readonly snapshot_replacement_authorized: {
+        readonly replacementChosen: false;
+    };
+    readonly replacement_started: {
+        readonly replacementChosen: true;
+    };
+    readonly replacement_completed: {
+        readonly replacementChosen: true;
+    };
+    readonly snapshot_replacement_started: {
+        readonly replacementChosen: true;
+    };
+    readonly snapshot_restore_failed: {
+        readonly replacementChosen: true;
+    };
+    readonly snapshot_replacement_completed: {
+        readonly replacementChosen: true;
+    };
+    readonly missing_replacement_started: {
+        readonly replacementChosen: true;
+    };
+    readonly missing_replacement_completed: {
+        readonly replacementChosen: true;
+    };
+    readonly unrecoverable_replacement_started: {
+        readonly replacementChosen: true;
+    };
+    readonly unrecoverable_replacement_completed: {
+        readonly replacementChosen: true;
+    };
+};
+export type WorkspaceSandboxRecoveryAction = keyof typeof ACTIONS;
+export type WorkspaceSandboxSnapshotAvailability = 'available' | 'missing' | 'stale';
+export type WorkspaceSandboxSnapshotFreshness = 'fresh' | 'stale' | 'unknown';
+/** A snapshot the app took of a box, addressed by the box it came from. */
+export interface WorkspaceSandboxSnapshot {
+    fromSandboxId: string;
+    createdAt: string;
+    [key: string]: unknown;
+}
+export interface WorkspaceSandboxSnapshotAssessment {
+    availability: WorkspaceSandboxSnapshotAvailability;
+    freshness: WorkspaceSandboxSnapshotFreshness;
+    snapshot?: WorkspaceSandboxSnapshot;
+}
+export interface WorkspaceSandboxRecoveryState {
+    code: WorkspaceSandboxRecoveryCode;
+    sandboxId: string;
+    detectedAt: string;
+    snapshot: WorkspaceSandboxSnapshotAssessment;
+    action: WorkspaceSandboxRecoveryAction;
+    replacementBoxKey?: string;
+    replacementSandboxId?: string;
+    confirmedAt?: string;
+}
+export type WorkspaceSandboxRecoveryDecision = 'replace' | 'decline';
+/** Raised when chat cannot continue until an owner decides about the box. */
+export declare class WorkspaceSandboxRecoveryRequiredError extends Error {
+    readonly code = "EGRESS_PROXY_RECOVERY_REQUIRED";
+    readonly status = 409;
+    readonly phase = "egress_proxy_recovery";
+    readonly recovery: WorkspaceSandboxRecoveryState;
+    constructor(recovery: WorkspaceSandboxRecoveryState, cause: Error);
+}
+export declare function isEgressProxyRecoveryRequiredError(error: unknown): boolean;
+export declare function isWorkspaceSandboxSnapshotRestoreError(error: unknown): boolean;
+/**
+ * Judge a snapshot against the box being replaced.
+ *
+ * Fresh means BOTH that it came from this exact sandbox and that it is inside
+ * the age bound — a snapshot from a different box restores someone else's
+ * filesystem, which is worse than starting empty.
+ */
+export declare function assessWorkspaceSandboxSnapshot(snapshot: WorkspaceSandboxSnapshot | undefined, sandboxId: string, now?: number): WorkspaceSandboxSnapshotAssessment;
+export declare function isWorkspaceSandboxRecoveryAction(value: unknown): value is WorkspaceSandboxRecoveryAction;
+export declare function isWorkspaceSandboxRecoveryCode(value: unknown): value is WorkspaceSandboxRecoveryCode;
+export declare function isWorkspaceSandboxRecoveryState(value: unknown): value is WorkspaceSandboxRecoveryState;
+export declare function workspaceSandboxRecoveryFromError(error: unknown): WorkspaceSandboxRecoveryState | undefined;
+/** What to tell the person waiting. Never names the product, so an app can
+ *  surface it verbatim. */
+export declare function workspaceSandboxRecoveryMessage(recovery: WorkspaceSandboxRecoveryState): string;
+export declare function workspaceSandboxRecoveryRecommendedActions(recovery: WorkspaceSandboxRecoveryState): string[];
+/** Flat key/value shape for a log line — no nesting, no secrets. */
+export declare function workspaceSandboxRecoveryDiagnostic(recovery: WorkspaceSandboxRecoveryState): Record<string, string | undefined>;
+/**
+ * The box key the next provisioning attempt should use, or undefined to keep
+ * using the workspace's own key.
+ *
+ * Reads {@link ACTIONS} rather than a hand-kept list, because the failure mode
+ * of a hand-kept list here is invisible: the key is recorded, silently ignored,
+ * and provisioning goes back to the box the app just decided to abandon.
+ */
+export declare function preferredWorkspaceSandboxRecoveryBoxKey(recovery: WorkspaceSandboxRecoveryState | undefined): string | undefined;
+/** Whether the replacement should be restored from the old box's snapshot. */
+export declare function shouldRestoreWorkspaceSandboxRecovery(recovery: WorkspaceSandboxRecoveryState | undefined): boolean;
+/**
+ * Where an app keeps recovery state. One row per workspace, last write wins —
+ * a recovery is a current situation, not a history.
+ */
+export interface WorkspaceSandboxRecoveryStore {
+    read: (workspaceId: string) => Promise<WorkspaceSandboxRecoveryState | undefined>;
+    write: (workspaceId: string, recovery: WorkspaceSandboxRecoveryState) => Promise<void>;
+}
+export interface WorkspaceSandboxRecoveryManager {
+    read: (workspaceId: string) => Promise<WorkspaceSandboxRecoveryState | undefined>;
+    record: (workspaceId: string, recovery: WorkspaceSandboxRecoveryState) => Promise<void>;
+    /** Record an owner's decision. Returns undefined when the stored recovery does
+     *  not name this sandbox — a decision about a box that has already been
+     *  replaced must not resurrect it. */
+    decide: (args: {
+        workspaceId: string;
+        sandboxId: string;
+        decision: WorkspaceSandboxRecoveryDecision;
+        replacementBoxKey?: string;
+    }) => Promise<WorkspaceSandboxRecoveryState | undefined>;
+    /** Mark a replacement finished and name the box that took over. */
+    complete: (args: {
+        workspaceId: string;
+        replacementSandboxId: string;
+    }) => Promise<WorkspaceSandboxRecoveryState | undefined>;
+}
+/**
+ * Bind the recovery bookkeeping to an app's storage.
+ *
+ * The app owns persistence — a D1 column, a KV key, a Postgres row — and
+ * nothing else. Every rule about which action means what stays here, so it
+ * cannot drift between apps.
+ */
+export declare function createWorkspaceSandboxRecoveryManager(store: WorkspaceSandboxRecoveryStore): WorkspaceSandboxRecoveryManager;
+/** Every declared action, for exhaustiveness tests in apps and here. */
+export declare const WORKSPACE_SANDBOX_RECOVERY_ACTIONS: readonly WorkspaceSandboxRecoveryAction[];
+/** Every declared cause. */
+export declare const WORKSPACE_SANDBOX_RECOVERY_CODES: readonly WorkspaceSandboxRecoveryCode[];
+export {};

package/dist/sandbox/terminal-connection.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Browser-direct scoped-token terminal connection route (#341/#349).
+ *
+ * Epic #343 / decision #341: the fleet's terminal transport is browser-direct
+ * — the product's server authenticates the request and provisions/resolves
+ * the sandbox exactly once, mints a short-lived SDK scoped token
+ * (`box.mintScopedToken`), and hands the browser just enough to connect
+ * `TerminalView` straight to the sidecar. No worker relays terminal bytes.
+ * The deprecated same-origin relay was removed in #350 after the fleet
+ * migrated, leaving this as the package's only terminal transport.
+ *
+ * VERIFIED PLATFORM CONTRACT (`@tangle-network/sandbox` 0.15.2 + the
+ * orchestrator/sidecar enforcement source, verified 2026-07-30):
+ *
+ * 1. Only a `scope: 'session-runtime'` token carries the `terminal`
+ *    capability (`cap: ["read", "workspace", "terminal"]`). `'project'` and
+ *    `'session'` mint SessionGateway READ tokens (HS256, `typ: "read"`, no
+ *    `cap` claim at all — a different token family the sidecar rejects
+ *    outright); `'read-only'` carries `cap: ["read"]` only. **No scope other
+ *    than `'session-runtime'` can ever open a terminal**, which is why this
+ *    route no longer takes `scope` as a parameter — it is pinned.
+ * 2. The orchestrator's terminal WS gate fails closed unless the token's
+ *    `sid` claim EQUALS the `<connectionId>` path segment of
+ *    `/terminals/<connectionId>/ws`
+ *    (`verifyScopedSidecarCapability(sidecar, token, "terminal", connectionId)`).
+ *    So `mintScopedToken({ scope: 'session-runtime', sessionId })` MUST be
+ *    called with `sessionId === connectionId` — the exact id `TerminalView`
+ *    will dial. That is why this route threads a `connectionId` end to end
+ *    instead of deriving its own session id.
+ * 3. The browser-safe terminal base is the mint result's `sidecarProxyUrl`
+ *    (`/v1/sidecar-proxy/{id}` on the Sandbox API) — **not**
+ *    `box.connection.runtimeUrl`. The SDK's own `_attachTerminal` is the
+ *    reference implementation:
+ *    `mintScopedToken({ scope: 'session-runtime', sessionId: connectionId })`
+ *    then dial `${scoped.sidecarProxyUrl}/terminals/${connectionId}/ws`.
+ *    Pointing `TerminalView` at `runtimeUrl` fails auth regardless of scope —
+ *    only the sidecar-proxy hop decodes the browser's
+ *    `bearer.<base64url>` WS subprotocol.
+ *
+ * HISTORICAL NOTE: an earlier shape of this route (and legal-agent's
+ * production route it was modeled on, `scope: 'project'` +
+ * `connection.runtimeUrl`) predates the platform's terminal-auth hardening —
+ * the terminal capability gate (2026-06-19), the scoped-token terminal WS
+ * path (2026-07-15), and the `sid`-binding fail-closed check
+ * (2026-07-17/18). That shape does not authenticate on the current platform
+ * and is not a valid spec for the token path anymore.
+ *
+ * SECURITY POSTURE: unlike the read-only session-gateway streaming token
+ * (`box.mintScopedToken({scope:'session'})` paired with
+ * `SessionGatewayClient`), the token this route mints grants **command
+ * execution** in the sandbox once handed to `TerminalView`. Its safety rests
+ * on a **short TTL** (default 15 minutes, the SDK's own max — still a caller
+ * parameter) and, structurally, the narrowest scope the platform offers: one
+ * box (`ensureSandbox` resolved it for THIS user), one terminal connection
+ * (`session-runtime` bound to a single `sid`). Widening the TTL default
+ * without an explicit reason is a security regression, not a convenience.
+ *
+ * Wire contract: the browser passes the response's `sidecarUrl` as
+ * `TerminalView`'s `apiUrl` prop, `token` as its token prop, and the
+ * response's echoed `connectionId` as `TerminalView`'s `connectionId` prop —
+ * the token's `sid` is bound to exactly that id, so any other value fails the
+ * WS upgrade. sandbox-ui sends the token as a `bearer.<base64url>` WebSocket
+ * subprotocol (browsers cannot set `Authorization` on a WS handshake).
+ * `useSandboxTerminalConnection` (`../web-react/sandbox-terminal`) carries
+ * `connectionId` through automatically.
+ */
+/** The structural surface this route needs from an SDK sandbox box — no `@tangle-network/sandbox` class import (invariant 3). */
+export interface TerminalConnectionBoxLike {
+    id: string;
+    status?: string;
+    connection?: {
+        runtimeUrl?: string;
+    };
+    mintScopedToken(opts: {
+        scope: string;
+        sessionId?: string;
+        ttlMinutes?: number;
+    }): Promise<{
+        token: string;
+        expiresAt: Date;
+        sidecarProxyUrl: string;
+    }>;
+}
+/** Configuration for {@link createSandboxTerminalConnectionRoute}. */
+export interface SandboxTerminalConnectionRouteOptions<TBox extends TerminalConnectionBoxLike, TUser> {
+    /**
+     * Authenticate the incoming request. Return the authenticated user, or a
+     * `Response` to short-circuit the route (e.g. a 401) — that Response is
+     * returned to the caller verbatim.
+     */
+    requireUser(request: Request): Promise<TUser | Response>;
+    /**
+     * Resolve (provisioning if needed) the sandbox this user's terminal should
+     * connect to. Domain-specific provisioning (workspace- vs user-scoped,
+     * naming, reuse) stays entirely in the product's implementation of this
+     * seam — the route only reacts to success/failure.
+     */
+    ensureSandbox(user: TUser, request: Request): Promise<TBox>;
+    /** `box.mintScopedToken` TTL in minutes. Default `15` (the SDK's own max). */
+    ttlMinutes?: number;
+    /**
+     * Resolve the terminal connection id the minted token's `sid` is bound to
+     * — this MUST be the same id `TerminalView` dials
+     * (`tabTerminalConnectionId()`), because the orchestrator's terminal WS
+     * gate fails closed unless `sid === <connectionId>` in
+     * `/terminals/<connectionId>/ws`.
+     *
+     * `requested` is `new URL(request.url).searchParams.get('connectionId')`.
+     * The default resolver returns `requested` unchanged. A product may
+     * validate/namespace the id here (e.g. a per-user prefix in a shared box)
+     * — if it rewrites the id, the client MUST use the response's echoed
+     * `connectionId`, since the sid binding makes any other id fail the WS
+     * upgrade.
+     *
+     * A resolved falsy/empty value fails the request with a 400 before any
+     * sandbox work happens.
+     */
+    resolveConnectionId?: (ctx: {
+        request: Request;
+        user: TUser;
+        box: TBox;
+        requested: string | null;
+    }) => string | null | undefined | Promise<string | null | undefined>;
+}
+/**
+ * Build the browser-direct terminal connection route: `GET` handler that
+ * authenticates, resolves the sandbox, mints a scoped token pinned to
+ * `scope: 'session-runtime'` (the ONLY scope the platform grants the
+ * `terminal` capability to), and returns exactly what the browser needs to
+ * connect `TerminalView` directly to the sidecar — no worker in the data
+ * path once the terminal is open.
+ *
+ * Response shapes:
+ * - `requireUser` returns a `Response` → that `Response`, verbatim.
+ * - `ensureSandbox` throws → `500 {error}` (the thrown message surfaced).
+ * - `box.connection?.runtimeUrl` missing → `503 {error, status: box.status}`
+ *   — this is a READINESS gate only; the URL returned to the client on
+ *   success is always the mint's `sidecarProxyUrl`, never `runtimeUrl`.
+ * - resolved connection id is falsy/empty → `400 {error}`.
+ * - `box.mintScopedToken` rejects → `503 {error}`.
+ * - success → `200 {sidecarUrl, token, expiresAt, status, sandboxId, connectionId}`.
+ *   `connectionId` is the id the token's `sid` is bound to — the client MUST
+ *   hand this (not its own) to `TerminalView`.
+ */
+export declare function createSandboxTerminalConnectionRoute<TBox extends TerminalConnectionBoxLike, TUser>(opts: SandboxTerminalConnectionRouteOptions<TBox, TUser>): (request: Request) => Promise<Response>;

package/dist/sandbox/workspace-sandbox-manager.d.ts

@@ -0,0 +1,44 @@
+/** Define the shape of a workspace sandbox instance including its connection details and status. */
+export interface WorkspaceSandboxInstanceLike {
+    id: string;
+    name?: string;
+    status?: string;
+    connection?: {
+        runtimeUrl?: string;
+        sidecarUrl?: string;
+        authToken?: string;
+        sidecarToken?: string;
+        authTokenExpiresAt?: string;
+    } | null;
+}
+/** Define the context containing workspace and user identifiers for sandbox environment operations. */
+export interface WorkspaceSandboxEnsureContext {
+    workspaceId: string;
+    userId: string;
+}
+/** Define configuration options for managing workspace sandboxes. */
+export interface WorkspaceSandboxManagerOptions<TClient, TBox extends WorkspaceSandboxInstanceLike, TEnsureOptions = void> {
+    getClient: (ctx: WorkspaceSandboxEnsureContext) => Promise<TClient> | TClient;
+    nameForWorkspace: (workspaceId: string, ctx: WorkspaceSandboxEnsureContext) => string;
+    listSandboxes: (client: TClient, ctx: WorkspaceSandboxEnsureContext) => Promise<TBox[]>;
+    createSandbox: (args: {
+        client: TClient;
+        ctx: WorkspaceSandboxEnsureContext;
+        name: string;
+        options: TEnsureOptions;
+        listError?: unknown;
+    }) => Promise<TBox>;
+    waitForRunning?: (box: TBox, ctx: WorkspaceSandboxEnsureContext) => Promise<void>;
+    prepareExisting?: (box: TBox, ctx: WorkspaceSandboxEnsureContext, options: TEnsureOptions) => Promise<TBox | void>;
+    prepareCreated?: (box: TBox, ctx: WorkspaceSandboxEnsureContext, options: TEnsureOptions) => Promise<TBox | void>;
+    onListError?: (error: unknown, ctx: WorkspaceSandboxEnsureContext) => void;
+}
+/** Manage workspace sandboxes by ensuring their creation and retrieval for specified users. */
+export interface WorkspaceSandboxManager<TBox extends WorkspaceSandboxInstanceLike, TEnsureOptions = void> {
+    ensureWorkspaceSandbox: (workspaceId: string, userId: string, options?: TEnsureOptions) => Promise<TBox>;
+}
+/**
+ * Create a generic name-keyed sandbox lifecycle manager for products that
+ * drive their own SDK or box types.
+ */
+export declare function createWorkspaceSandboxManager<TClient, TBox extends WorkspaceSandboxInstanceLike, TEnsureOptions = void>(opts: WorkspaceSandboxManagerOptions<TClient, TBox, TEnsureOptions>): WorkspaceSandboxManager<TBox, TEnsureOptions>;

package/dist/sequences/apply.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Maps one validated `SequenceOperation` to `SequenceStore` calls and reports
+ * what changed. Each call re-validates its single operation against the
+ * provided timeline — a dispatcher that skips batch validation still cannot
+ * reach the store with an invalid write. The timeline must be the CURRENT
+ * state: dispatchers applying a batch refresh it between operations so later
+ * operations can reference entities earlier ones created.
+ *
+ * Split assumes source frames advance 1:1 with sequence frames (the model
+ * addresses source in/out points at sequence fps); time-remapped clips are
+ * outside this operation vocabulary.
+ */
+import type { SequenceClip, SequenceExportRecord, SequenceMeta, SequenceTimeline, SequenceTrack } from './model';
+import type { SequenceOperation } from './operations';
+import type { SequenceStore } from './store';
+import type { SequenceOperationContext } from './validate';
+/**
+ * The entity an operation changed, for the MCP layer to serialize back to the
+ * agent. Conventions for multi-entity operations:
+ * - `split_clip` returns the newly created second half (the first half is the
+ *   original clip id with a shortened duration).
+ * - `delete_clip` returns the pre-delete clip snapshot.
+ */
+export type SequenceApplyResult = {
+    kind: 'clip';
+    clip: SequenceClip;
+} | {
+    kind: 'track';
+    track: SequenceTrack;
+} | {
+    kind: 'export';
+    record: SequenceExportRecord;
+} | {
+    kind: 'sequence';
+    sequence: SequenceMeta;
+};
+/**
+ * The batch path every dispatcher (the MCP tools, a product's editor
+ * persistence route) funnels through: fetch the timeline, validate the WHOLE
+ * batch against pre-state, then apply in order with a timeline refresh between
+ * operations — later operations must see earlier writes (the static-validation
+ * boundary in ./validate).
+ *
+ * Atomicity contract: validation throws (before the first store write) leave
+ * the sequence untouched. Store-layer throws after at least one successful
+ * write leave a prefix-committed state — operations 1..N-1 are persisted,
+ * operations N..end are not. The store is non-transactional (SQLite D1);
+ * callers that receive a partial-commit throw must treat the result as partial
+ * success, not a full rollback. Decision-log rows are the caller's job: the
+ * MCP layer records `agent_edit`, an editor route records `human_edit`.
+ */
+export declare function applySequenceOperations(store: SequenceStore, operations: SequenceOperation[], ctx: SequenceOperationContext): Promise<SequenceApplyResult[]>;
+/** Apply a sequence operation to update the store and timeline asynchronously */
+export declare function applySequenceOperation(store: SequenceStore, timeline: SequenceTimeline, op: SequenceOperation, ctx: SequenceOperationContext): Promise<SequenceApplyResult>;

package/dist/sequences/captions.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Caption planning — pure, server-safe helpers that turn transcripts into
+ * frame-typed caption chunks and answer "are captions complete?" per language.
+ * No store access, no React, no provider coupling: products feed transcript
+ * segments in (from any transcription provider) and get chunk bounds out,
+ * ready to become `add_caption` operations.
+ *
+ * All outputs are integer frames at the sequence fps. Seconds appear only on
+ * the transcript-segment inputs, because that is what transcription providers
+ * emit; the conversion happens exactly once, here.
+ */
+import { type SequenceTimeline, type TimelineInterval } from './model';
+/** Server twin of `TranscriptionSegment` (../sequences-react/contracts) —
+ *  structurally identical so react-side transcription output feeds
+ *  `buildCaptionChunks` without mapping. Keep the shapes in lockstep. */
+export interface TranscriptSegment {
+    text: string;
+    startSeconds: number;
+    endSeconds: number;
+}
+/** One caption clip's worth of text with its timeline bounds. */
+export interface CaptionChunk {
+    text: string;
+    startFrame: number;
+    durationFrames: number;
+}
+/** Define options to configure caption chunk size, duration, and frame rate constraints */
+export interface BuildCaptionChunksOptions {
+    /** Upper bound on words per caption; segments split on word boundaries. */
+    maxWordsPerChunk?: number;
+    /** Readability floor — chunks shorter than this are extended, never
+     *  overlapped: the following chunk's start is pushed forward instead. */
+    minDurationSeconds?: number;
+    fps: number;
+}
+/**
+ * Split transcript segments into caption chunks. Within each segment, time is
+ * apportioned to chunks by word count (a constant words-per-second estimate).
+ * Guarantees, across the WHOLE output regardless of segment boundaries:
+ *
+ * - starts are strictly increasing and chunks never overlap
+ * - every chunk lasts at least the min-duration clamp (and at least
+ *   `MIN_SEQUENCE_CLIP_FRAMES`)
+ * - a chunk may extend past its segment's end by at most the clamp — the cost
+ *   of the readability floor on short tails
+ *
+ * Whitespace-only segments produce no chunks. Segments may arrive unsorted
+ * (providers emit per-channel batches); they are ordered by start before
+ * chunking so the no-overlap guarantee holds.
+ */
+export declare function buildCaptionChunks(segments: TranscriptSegment[], opts: BuildCaptionChunksOptions): CaptionChunk[];
+/**
+ * Normalize a BCP-47 tag to conventional casing: primary subtag lowercase,
+ * 4-letter script subtags Title Case, 2-letter region subtags UPPER, all other
+ * subtags lowercase. Throws on empty or structurally invalid tags.
+ */
+export declare function normalizeLanguageTag(tag: string): string;
+/** Define options to specify target languages and an optional source language for fan-out operations */
+export interface LanguageFanoutOptions {
+    languages: string[];
+    /** Excluded from the plan (exact normalized match only — 'en' does not
+     *  exclude 'en-US'; a regional variant of the source is still a valid
+     *  fan-out target). */
+    sourceLanguage?: string;
+}
+/**
+ * Plan which caption languages to generate: normalized, deduped (first
+ * occurrence wins), source excluded. Throws on an empty request or any
+ * invalid tag — a malformed fan-out request must fail before any generation
+ * is queued. Returns [] when every requested language IS the source; the
+ * caller reports "nothing to fan out" rather than erroring.
+ */
+export declare function planLanguageFanout(opts: LanguageFanoutOptions): string[];
+/** Coverage for one caption language across the sequence. `language` is the
+ *  clip's stored tag verbatim (no normalization — coverage reports what is
+ *  actually on the timeline); null groups caption clips with no tag. */
+export interface CaptionCoverageEntry {
+    language: string | null;
+    coveredFrames: number;
+    totalFrames: number;
+    /** Uncovered intervals, ascending; endFrame exclusive. */
+    gaps: TimelineInterval[];
+}
+/**
+ * Per-language caption coverage over [0, durationFrames). A frame counts as
+ * covered when an enabled, non-empty-text clip on a caption-kind track spans
+ * it. Overlapping clips merge (no double counting). Returns one entry per
+ * distinct language, null first then lexicographic; [] when the timeline has
+ * no caption clips at all.
+ */
+export declare function captionCoverage(timeline: SequenceTimeline): CaptionCoverageEntry[];

package/dist/sequences/drizzle-store.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Drizzle-backed `SequenceStore` over the tables from `createSequenceTables`.
+ * Works against any SQLite drizzle driver (better-sqlite3, D1, libsql) — the
+ * builders are awaited, never `.run()`/`.all()`, so sync and async drivers
+ * behave identically.
+ *
+ * Defense in depth: RBAC runs before the store is constructed, but every
+ * query still pins `workspaceId` AND `sequenceId` from the scope in its WHERE
+ * clause, so a leaked or attacker-supplied row id from another workspace can
+ * never read or write across the boundary — it surfaces as "not found".
+ *
+ * Store-level invariants (everything richer lives in the operation
+ * validator): frame fields must be non-negative integers, clip durations at
+ * least `MIN_SEQUENCE_CLIP_FRAMES`, and the sequence duration can never
+ * shrink below the last clip end. Every mutation bumps `sequence.updatedAt`
+ * so workspace recency sorts stay truthful.
+ */
+import type { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core';
+import { type SequenceClipMedia } from './model';
+import type { SequenceStore, SequenceStoreScope } from './store';
+import type { SequenceClipRow, SequenceTables } from './schema';
+/** Any SQLite drizzle database — `any` erases the driver-specific run-result
+ *  and schema generics so better-sqlite3, D1, and libsql handles all fit. */
+export type SequenceDatabase = BaseSQLiteDatabase<'sync' | 'async', any, any>;
+/** Resolves product-specific media (generation rows, asset rows) for a batch
+ *  of clip rows. Keyed by clip id; clips absent from the map carry no media. */
+export type SequenceMediaResolver = (clipRows: SequenceClipRow[]) => Promise<Map<string, SequenceClipMedia>>;
+/** Define options for creating a Drizzle sequence store including database, tables, scope, and media resolver */
+export interface CreateDrizzleSequenceStoreOptions {
+    db: SequenceDatabase;
+    tables: SequenceTables;
+    scope: SequenceStoreScope;
+    resolveMedia?: SequenceMediaResolver;
+}
+/** Create a sequence store scoped to a specific sequence and workspace with database access and media resolution */
+export declare function createDrizzleSequenceStore(options: CreateDrizzleSequenceStoreOptions): SequenceStore;