@jini-ai/integrations 0.3.2 → 0.3.4

package/dist/media-providers/dispatch/async-operation-store.d.ts

@@ -0,0 +1,166 @@
+/**
+ * `AsyncOperationStore` — the durable operation row behind submit-then-poll media generation.
+ *
+ * Why this exists alongside `task-store.ts`'s `MediaTaskStore`: they model different things and
+ * only one of them survives a restart usefully. `MediaTaskStore` is a *task tracker* — it records
+ * that a generation happened and its `reconcileOnBoot` deliberately marks every still-in-flight
+ * task `'interrupted'`, because a synchronous `fetch` that died with its process genuinely cannot
+ * be resumed. This store is the opposite case: a vendor-side job that is still running *on the
+ * vendor* after our process died, and whose result is still retrievable by polling. It therefore
+ * carries the four columns a poll loop needs and a task tracker does not — `attempts`,
+ * `nextPollAt`, a worker `lease`, and an absolute `deadlineAt` — and its `reconcileOnBoot`
+ * *releases* leases rather than terminating the work.
+ *
+ * Two independent bounds are mandatory, not redundant: `maxAttempts` catches a vendor that answers
+ * "pending" forever, and `deadlineAt` catches a vendor that stops answering at all. Neither one
+ * subsumes the other.
+ *
+ * `state` is the vendor's own resumption handle (a job id, a poll URL). It is deliberately
+ * validated on every write to reject credential material: the row outlives the process and is the
+ * one place a leaked key would become durable. Credentials are re-resolved per poll tick through
+ * the signer seam instead — see `polling-adapter.ts`.
+ */
+/**
+ * `unknown` is a real terminal-ish state, not a failure: it means the operation may or may not
+ * have taken effect at the vendor and cannot be safely retried without an idempotency proof. It is
+ * reachable only from a crash gap or a blown deadline, and exists so those never masquerade as
+ * either success or a retryable failure.
+ */
+export type AsyncOperationStatus = 'submitted' | 'polling' | 'succeeded' | 'failed' | 'unknown';
+/**
+ * The persisted shape's version discriminator. Bumped whenever `AsyncOperationRecord`'s stored
+ * shape changes; `hydrateAsyncOperationRecord` branches on it so an old row is upgraded on read
+ * rather than rescued by a migration script.
+ *
+ * This is deliberately the same mechanism `ffb5ce44` used to close the AAD gap — a version column,
+ * a read path that branches on it, and an idempotent backfill only where one is actually needed —
+ * rather than a second migration playbook.
+ */
+export declare const ASYNC_OPERATION_SCHEMA_VERSION = 1;
+export declare const CREDENTIAL_IN_STATE_MESSAGE = "async operation state must never carry credential material \u2014 credentials are re-resolved per poll tick through the signer seam";
+export interface AsyncOperationError {
+    readonly message: string;
+    readonly status?: number;
+    readonly code?: string;
+}
+/** The generated bytes, held base64-encoded so the row stays JSON-serializable for a durable adapter. */
+export interface AsyncOperationResult {
+    readonly bytesBase64: string;
+    readonly providerNote: string;
+    readonly suggestedExt?: string;
+}
+export interface AsyncOperationRecord {
+    /** Shape discriminator — see `ASYNC_OPERATION_SCHEMA_VERSION`. Stamped once at create and never rewritten. */
+    readonly schemaVersion: number;
+    readonly id: string;
+    readonly providerId: string;
+    readonly routeKey: string;
+    /** Opaque host-supplied scoping key (a run id, a workspace id) — never a domain noun this package knows. */
+    readonly ownerRef: string;
+    readonly status: AsyncOperationStatus;
+    readonly attempts: number;
+    /** Bound 1: caps a vendor that answers "pending" forever. */
+    readonly maxAttempts: number;
+    /** Absolute epoch ms after which this operation may not be polled again. Bound 2: caps a vendor that stops answering. */
+    readonly deadlineAt: number;
+    readonly nextPollAt: number;
+    readonly leaseOwner: string | null;
+    readonly leaseExpiresAt: number | null;
+    /** The vendor's resumption handle. Never credential material — see `CREDENTIAL_IN_STATE_MESSAGE`. */
+    readonly state: Readonly<Record<string, unknown>> | null;
+    readonly result: AsyncOperationResult | null;
+    readonly error: AsyncOperationError | null;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+export interface AsyncOperationCreateInput {
+    readonly id: string;
+    readonly providerId: string;
+    readonly routeKey: string;
+    readonly ownerRef: string;
+    readonly maxAttempts: number;
+    readonly deadlineAt: number;
+    readonly nextPollAt?: number;
+    readonly status?: AsyncOperationStatus;
+    readonly state?: Readonly<Record<string, unknown>> | null;
+}
+export interface AsyncOperationPatch {
+    readonly status?: AsyncOperationStatus;
+    readonly attempts?: number;
+    readonly nextPollAt?: number;
+    readonly state?: Readonly<Record<string, unknown>> | null;
+    readonly result?: AsyncOperationResult | null;
+    readonly error?: AsyncOperationError | null;
+    readonly leaseOwner?: string | null;
+    readonly leaseExpiresAt?: number | null;
+}
+export interface AsyncOperationClaimOptions {
+    readonly now: number;
+    readonly leaseOwner: string;
+    readonly leaseMs: number;
+    readonly limit?: number;
+}
+export interface AsyncOperationReconcileResult {
+    /** Rows whose worker died holding a lease — released for another worker, status untouched. */
+    readonly leasesReleased: number;
+    /** Rows that blew their absolute deadline while unattended — moved to `unknown`, never to `failed`. */
+    readonly deadlineExpired: number;
+}
+export interface AsyncOperationStore {
+    create(input: AsyncOperationCreateInput): Promise<AsyncOperationRecord>;
+    get(id: string): Promise<AsyncOperationRecord | null>;
+    update(id: string, patch: AsyncOperationPatch): Promise<AsyncOperationRecord | null>;
+    listByOwner(ownerRef: string): Promise<AsyncOperationRecord[]>;
+    /** Atomically leases every due, unleased, non-terminal operation and returns the leased rows. */
+    claimDue(options: AsyncOperationClaimOptions): Promise<AsyncOperationRecord[]>;
+    /**
+     * Releases a lease this caller believes it holds. Fenced on `leaseOwner`: a release only takes
+     * effect while the row's current `leaseOwner` still equals the one passed here (the equivalent
+     * SQL is a conditional `UPDATE ... WHERE id = ? AND lease_owner = ?`). Without this fence, a
+     * worker that outlives its own lease (e.g. a slow poll past `leaseMs`) can clear whichever
+     * worker legitimately reclaimed the row after it expired, breaking the single-worker guarantee
+     * `claimDue` exists to provide. A release for a row the caller no longer owns — because it
+     * never claimed it, or another worker has since reclaimed it — is a no-op, not an error: the
+     * caller's intent ("I'm done, let someone else have it") is already satisfied either way.
+     */
+    releaseLease(id: string, leaseOwner: string): Promise<void>;
+    /**
+     * Boot-time recovery. Unlike `MediaTaskStore.reconcileOnBoot`, this does NOT terminate in-flight
+     * work: a vendor-side job outlives our process, so the row stays pollable and only its dead
+     * lease is cleared. Rows already past their absolute deadline go to `unknown` — never `failed`,
+     * because an unattended deadline says nothing about whether the vendor did the work.
+     */
+    reconcileOnBoot(options: {
+        now: number;
+    }): Promise<AsyncOperationReconcileResult>;
+}
+/**
+ * Rejects anything in an operation `state` object outside the resumption-handle allowlist —
+ * which, as a consequence, rejects credential material regardless of what key name it arrives
+ * under (see `ALLOWED_STATE_KEYS`).
+ *
+ * @throws `Error` (message starts with `CREDENTIAL_IN_STATE_MESSAGE`, naming the offending key)
+ *   when any key at any depth is not in `ALLOWED_STATE_KEYS`.
+ * @complexity O(n) in the total number of keys, bounded by `MAX_STATE_DEPTH` against a cyclic or
+ *   pathologically nested object.
+ */
+export declare function assertNoCredentialMaterial(state: Readonly<Record<string, unknown>> | null | undefined): void;
+/**
+ * The branching read path for a persisted operation row.
+ *
+ * A durable adapter calls this on every row it loads. A row with no discriminator predates
+ * versioning (v0) and is upgraded in place on read; a row from a newer build is refused loudly
+ * rather than misread, because silently reinterpreting an unknown shape is how a stored operation
+ * becomes a duplicate vendor charge.
+ *
+ * @throws When `schemaVersion` is newer than this build understands.
+ * @complexity O(1).
+ */
+export declare function hydrateAsyncOperationRecord(raw: Record<string, unknown>): AsyncOperationRecord;
+/**
+ * Creates the in-memory reference `AsyncOperationStore`. No persistence — a durable adapter
+ * implements the same interface; every method here is written so the equivalent SQL is a direct
+ * translation (`claimDue` in particular is a single conditional UPDATE ... RETURNING).
+ */
+export declare function createInMemoryAsyncOperationStore(): AsyncOperationStore;
+//# sourceMappingURL=async-operation-store.d.ts.map

package/dist/media-providers/dispatch/async-operation-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-operation-store.d.ts","sourceRoot":"","sources":["../../../src/media-providers/dispatch/async-operation-store.ts"],"names":[],"mappings":"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"}

package/dist/media-providers/dispatch/async-operation-store.js

@@ -0,0 +1,291 @@
+/**
+ * `AsyncOperationStore` — the durable operation row behind submit-then-poll media generation.
+ *
+ * Why this exists alongside `task-store.ts`'s `MediaTaskStore`: they model different things and
+ * only one of them survives a restart usefully. `MediaTaskStore` is a *task tracker* — it records
+ * that a generation happened and its `reconcileOnBoot` deliberately marks every still-in-flight
+ * task `'interrupted'`, because a synchronous `fetch` that died with its process genuinely cannot
+ * be resumed. This store is the opposite case: a vendor-side job that is still running *on the
+ * vendor* after our process died, and whose result is still retrievable by polling. It therefore
+ * carries the four columns a poll loop needs and a task tracker does not — `attempts`,
+ * `nextPollAt`, a worker `lease`, and an absolute `deadlineAt` — and its `reconcileOnBoot`
+ * *releases* leases rather than terminating the work.
+ *
+ * Two independent bounds are mandatory, not redundant: `maxAttempts` catches a vendor that answers
+ * "pending" forever, and `deadlineAt` catches a vendor that stops answering at all. Neither one
+ * subsumes the other.
+ *
+ * `state` is the vendor's own resumption handle (a job id, a poll URL). It is deliberately
+ * validated on every write to reject credential material: the row outlives the process and is the
+ * one place a leaked key would become durable. Credentials are re-resolved per poll tick through
+ * the signer seam instead — see `polling-adapter.ts`.
+ */
+/**
+ * The persisted shape's version discriminator. Bumped whenever `AsyncOperationRecord`'s stored
+ * shape changes; `hydrateAsyncOperationRecord` branches on it so an old row is upgraded on read
+ * rather than rescued by a migration script.
+ *
+ * This is deliberately the same mechanism `ffb5ce44` used to close the AAD gap — a version column,
+ * a read path that branches on it, and an idempotent backfill only where one is actually needed —
+ * rather than a second migration playbook.
+ */
+export const ASYNC_OPERATION_SCHEMA_VERSION = 1;
+const TERMINAL_STATUSES = new Set(['succeeded', 'failed', 'unknown']);
+const ALLOWED_TRANSITIONS = {
+    submitted: new Set(['submitted', 'polling', 'succeeded', 'failed', 'unknown']),
+    polling: new Set(['polling', 'succeeded', 'failed', 'unknown']),
+    succeeded: new Set(['succeeded']),
+    failed: new Set(['failed']),
+    unknown: new Set(['unknown']),
+};
+/**
+ * The complete set of key names an operation `state` object may carry, at any depth — this
+ * package's own `PollingVendorAdapter`s' resumption handles (currently only `jobId`; see
+ * `providers/imagerouter-video-async.ts`), never anything a `RequestSigner` needs.
+ *
+ * This is deliberately an allowlist, not a denylist. A denylist of "known credential-shaped
+ * names" was tried first (`apiKey`, `authorization`, `secret`, ...) and it missed `clientSecret` /
+ * `client_secret` on the very first adapter shape that could plausibly return one — and it can
+ * never be complete, because the set of names a vendor's response body (and the adapter written
+ * against it) might use for a credential is unbounded and outside this package's control. An
+ * allowlist inverts the failure mode: it fails *closed*. A legitimate new field an adapter starts
+ * returning is a loud registration error here — extend this set, deliberately, one entry at a
+ * time — never a silent path for a secret to become durable under a name this file never
+ * anticipated.
+ */
+const ALLOWED_STATE_KEYS = new Set(['jobId']);
+export const CREDENTIAL_IN_STATE_MESSAGE = 'async operation state must never carry credential material — credentials are re-resolved per poll tick through the signer seam';
+/**
+ * Rejects anything in an operation `state` object outside the resumption-handle allowlist —
+ * which, as a consequence, rejects credential material regardless of what key name it arrives
+ * under (see `ALLOWED_STATE_KEYS`).
+ *
+ * @throws `Error` (message starts with `CREDENTIAL_IN_STATE_MESSAGE`, naming the offending key)
+ *   when any key at any depth is not in `ALLOWED_STATE_KEYS`.
+ * @complexity O(n) in the total number of keys, bounded by `MAX_STATE_DEPTH` against a cyclic or
+ *   pathologically nested object.
+ */
+export function assertNoCredentialMaterial(state) {
+    if (state == null)
+        return;
+    const seen = new Set();
+    const walk = (value, depth) => {
+        if (depth > 12 || value === null || typeof value !== 'object')
+            return;
+        if (seen.has(value))
+            return;
+        seen.add(value);
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                walk(entry, depth + 1);
+            return;
+        }
+        for (const [key, entry] of Object.entries(value)) {
+            if (!ALLOWED_STATE_KEYS.has(key)) {
+                throw new Error(`${CREDENTIAL_IN_STATE_MESSAGE} (key "${key}" is not in the resumption-handle allowlist — add it there if it is genuinely not credential material)`);
+            }
+            walk(entry, depth + 1);
+        }
+    };
+    walk(state, 0);
+}
+/**
+ * The branching read path for a persisted operation row.
+ *
+ * A durable adapter calls this on every row it loads. A row with no discriminator predates
+ * versioning (v0) and is upgraded in place on read; a row from a newer build is refused loudly
+ * rather than misread, because silently reinterpreting an unknown shape is how a stored operation
+ * becomes a duplicate vendor charge.
+ *
+ * @throws When `schemaVersion` is newer than this build understands.
+ * @complexity O(1).
+ */
+export function hydrateAsyncOperationRecord(raw) {
+    const stored = typeof raw.schemaVersion === 'number' ? raw.schemaVersion : 0;
+    if (stored > ASYNC_OPERATION_SCHEMA_VERSION) {
+        throw new Error(`async operation row was written at schema version ${stored}, newer than this build understands (${ASYNC_OPERATION_SCHEMA_VERSION}) — upgrade rather than risk misreading it`);
+    }
+    // v0 -> v1 added only the discriminator itself, so the upgrade is a stamp. A later version adds
+    // its own branch here; the row is never rewritten on disk just to be readable.
+    const now = Date.now();
+    return {
+        schemaVersion: ASYNC_OPERATION_SCHEMA_VERSION,
+        id: String(raw.id),
+        providerId: String(raw.providerId),
+        routeKey: String(raw.routeKey),
+        ownerRef: String(raw.ownerRef),
+        status: raw.status ?? 'submitted',
+        attempts: typeof raw.attempts === 'number' ? raw.attempts : 0,
+        maxAttempts: Number(raw.maxAttempts),
+        deadlineAt: Number(raw.deadlineAt),
+        nextPollAt: typeof raw.nextPollAt === 'number' ? raw.nextPollAt : now,
+        leaseOwner: raw.leaseOwner ?? null,
+        leaseExpiresAt: raw.leaseExpiresAt ?? null,
+        state: raw.state ?? null,
+        result: raw.result ?? null,
+        error: raw.error ?? null,
+        createdAt: typeof raw.createdAt === 'number' ? raw.createdAt : now,
+        updatedAt: typeof raw.updatedAt === 'number' ? raw.updatedAt : now,
+    };
+}
+function cloneRecord(row) {
+    return {
+        ...row,
+        state: row.state === null ? null : structuredClone(row.state),
+        result: row.result === null ? null : { ...row.result },
+        error: row.error === null ? null : { ...row.error },
+    };
+}
+function assertTransition(from, to) {
+    if (!ALLOWED_TRANSITIONS[from]) {
+        throw new RangeError(`Invalid async operation status: "${from}"`);
+    }
+    if (!ALLOWED_TRANSITIONS[from].has(to)) {
+        throw new RangeError(`Invalid async operation transition: "${from}" -> "${to}"`);
+    }
+}
+/**
+ * Creates the in-memory reference `AsyncOperationStore`. No persistence — a durable adapter
+ * implements the same interface; every method here is written so the equivalent SQL is a direct
+ * translation (`claimDue` in particular is a single conditional UPDATE ... RETURNING).
+ */
+export function createInMemoryAsyncOperationStore() {
+    const rows = new Map();
+    const requireRow = (id) => rows.get(id);
+    return {
+        async create(input) {
+            if (rows.has(input.id)) {
+                throw new Error(`async operation "${input.id}" already exists`);
+            }
+            if (!Number.isFinite(input.maxAttempts) || input.maxAttempts < 1) {
+                throw new RangeError(`Invalid maxAttempts: ${input.maxAttempts} must be a finite number >= 1`);
+            }
+            if (!Number.isFinite(input.deadlineAt)) {
+                throw new RangeError(`Invalid deadlineAt: ${input.deadlineAt} must be a finite epoch-ms timestamp`);
+            }
+            assertNoCredentialMaterial(input.state);
+            const now = Date.now();
+            const row = {
+                schemaVersion: ASYNC_OPERATION_SCHEMA_VERSION,
+                id: input.id,
+                providerId: input.providerId,
+                routeKey: input.routeKey,
+                ownerRef: input.ownerRef,
+                status: input.status ?? 'submitted',
+                attempts: 0,
+                maxAttempts: input.maxAttempts,
+                deadlineAt: input.deadlineAt,
+                nextPollAt: input.nextPollAt ?? now,
+                leaseOwner: null,
+                leaseExpiresAt: null,
+                state: input.state === undefined || input.state === null ? null : structuredClone(input.state),
+                result: null,
+                error: null,
+                createdAt: now,
+                updatedAt: now,
+            };
+            rows.set(row.id, row);
+            return cloneRecord(row);
+        },
+        async get(id) {
+            const row = requireRow(id);
+            return row ? cloneRecord(row) : null;
+        },
+        async update(id, patch) {
+            const existing = requireRow(id);
+            if (!existing)
+                return null;
+            if ('state' in patch)
+                assertNoCredentialMaterial(patch.state);
+            const status = patch.status ?? existing.status;
+            assertTransition(existing.status, status);
+            const next = {
+                ...existing,
+                schemaVersion: existing.schemaVersion,
+                status,
+                attempts: patch.attempts ?? existing.attempts,
+                nextPollAt: patch.nextPollAt ?? existing.nextPollAt,
+                state: 'state' in patch ? (patch.state == null ? null : structuredClone(patch.state)) : existing.state,
+                result: 'result' in patch ? (patch.result ?? null) : existing.result,
+                error: 'error' in patch ? (patch.error ?? null) : existing.error,
+                leaseOwner: 'leaseOwner' in patch ? (patch.leaseOwner ?? null) : existing.leaseOwner,
+                leaseExpiresAt: 'leaseExpiresAt' in patch ? (patch.leaseExpiresAt ?? null) : existing.leaseExpiresAt,
+                updatedAt: Date.now(),
+            };
+            rows.set(id, next);
+            return cloneRecord(next);
+        },
+        async listByOwner(ownerRef) {
+            return [...rows.values()]
+                .filter((row) => row.ownerRef === ownerRef)
+                .sort((a, b) => a.createdAt - b.createdAt)
+                .map(cloneRecord);
+        },
+        async claimDue(options) {
+            const { now, leaseOwner, leaseMs } = options;
+            const limit = options.limit ?? 10;
+            const claimed = [];
+            for (const row of [...rows.values()].sort((a, b) => a.nextPollAt - b.nextPollAt)) {
+                if (claimed.length >= limit)
+                    break;
+                if (TERMINAL_STATUSES.has(row.status))
+                    continue;
+                if (row.nextPollAt > now)
+                    continue;
+                // A live lease held by anyone (including this worker's previous tick) blocks the claim;
+                // an expired one does not, which is what makes a dead worker's rows recoverable.
+                if (row.leaseExpiresAt !== null && row.leaseExpiresAt > now)
+                    continue;
+                const leased = {
+                    ...row,
+                    leaseOwner,
+                    leaseExpiresAt: now + leaseMs,
+                    updatedAt: now,
+                };
+                rows.set(row.id, leased);
+                claimed.push(cloneRecord(leased));
+            }
+            return claimed;
+        },
+        async releaseLease(id, leaseOwner) {
+            const row = requireRow(id);
+            if (!row)
+                return;
+            // Fenced: a stale owner's late release must not clear a lease another worker has since
+            // legitimately reclaimed. See the interface doc for why this is not merely defensive.
+            if (row.leaseOwner !== leaseOwner)
+                return;
+            rows.set(id, { ...row, leaseOwner: null, leaseExpiresAt: null, updatedAt: Date.now() });
+        },
+        async reconcileOnBoot(options) {
+            const { now } = options;
+            let leasesReleased = 0;
+            let deadlineExpired = 0;
+            for (const row of [...rows.values()]) {
+                if (TERMINAL_STATUSES.has(row.status))
+                    continue;
+                if (row.deadlineAt <= now) {
+                    rows.set(row.id, {
+                        ...row,
+                        status: 'unknown',
+                        leaseOwner: null,
+                        leaseExpiresAt: null,
+                        error: {
+                            message: 'async operation passed its absolute deadline while unattended — vendor-side effect is undetermined',
+                            code: 'DEADLINE_EXPIRED',
+                        },
+                        updatedAt: now,
+                    });
+                    deadlineExpired += 1;
+                    continue;
+                }
+                if (row.leaseOwner !== null && (row.leaseExpiresAt === null || row.leaseExpiresAt <= now)) {
+                    rows.set(row.id, { ...row, leaseOwner: null, leaseExpiresAt: null, updatedAt: now });
+                    leasesReleased += 1;
+                }
+            }
+            return { leasesReleased, deadlineExpired };
+        },
+    };
+}
+//# sourceMappingURL=async-operation-store.js.map

package/dist/media-providers/dispatch/async-operation-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-operation-store.js","sourceRoot":"","sources":["../../../src/media-providers/dispatch/async-operation-store.ts"],"names":[],"mappings":"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"}

package/dist/media-providers/dispatch/index.d.ts

@@ -21,5 +21,13 @@ export { dispatchVendorRequest, requireApiKey } from './vendor-adapter.js';
 export type { VendorAdapter, VendorCredentialGuard, VendorRequest, VendorRequestBuilder, VendorResponseParser } from './vendor-adapter.js';
 export { createVendorAdapterRegistry, mediaVendorRegistry, VendorAdapterRegistry } from './vendor-registry.js';
 export { createHexEnvelopeAudioParser, createRawBytesParser } from './response-parsers.js';
+export { ASYNC_OPERATION_SCHEMA_VERSION, assertNoCredentialMaterial, createInMemoryAsyncOperationStore, CREDENTIAL_IN_STATE_MESSAGE, hydrateAsyncOperationRecord, } from './async-operation-store.js';
+export type { AsyncOperationClaimOptions, AsyncOperationCreateInput, AsyncOperationError, AsyncOperationPatch, AsyncOperationReconcileResult, AsyncOperationRecord, AsyncOperationResult, AsyncOperationStatus, AsyncOperationStore, } from './async-operation-store.js';
+export { createBearerSigner, withUnsignedRequestInit } from './polling-adapter.js';
+export type { AnyPollingVendorAdapter, ExpectedLatencyClass, PollOutcome, PollingVendorAdapter, RequestSigner, SignedVendorRequest, SubmitOutcome, UnsignedVendorRequest, } from './polling-adapter.js';
+export { DEFAULT_DEADLINE_MS, DEFAULT_GRACE_MS, DEFAULT_MAX_ATTEMPTS, DEFAULT_PERSIST_RETRY_DELAYS_MS, DEFAULT_POLL_INTERVAL_MS, pollDueOperations, recoverAfterRestart, startOperation, } from './operation-runtime.js';
+export type { OperationRuntimeDeps, PollDueParams, PollDueStats, RecoverParams, RecoverResult, StartOperationOutcome, StartOperationParams, } from './operation-runtime.js';
+export { createImageRouterVideoPollingAdapter } from './providers/imagerouter-video-async.js';
+export type { ImageRouterVideoConfig, ImageRouterVideoMeta } from './providers/imagerouter-video-async.js';
 export type { HexEnvelopeAudioMeta, HexEnvelopeAudioParserOptions, RawBytesParserOptions } from './response-parsers.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/media-providers/dispatch/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/media-providers/dispatch/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,iCAAiC,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjF,OAAO,EAAE,uBAAuB,EAAE,+BAA+B,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAC9H,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,4BAA4B,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAChK,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACrE,YAAY,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,sBAAsB,EACtB,0BAA0B,EAC1B,qBAAqB,EACrB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC3E,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,aAAa,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3I,OAAO,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC/G,OAAO,EAAE,4BAA4B,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC3F,YAAY,EAAE,oBAAoB,EAAE,6BAA6B,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/media-providers/dispatch/index.ts"],"names":[],"mappings":"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"}

package/dist/media-providers/dispatch/index.js

@@ -21,4 +21,11 @@ export { assertAndFetchExternalAsset, assertExternalAssetUrl, isBlockedExternalA
 export { dispatchVendorRequest, requireApiKey } from './vendor-adapter.js';
 export { createVendorAdapterRegistry, mediaVendorRegistry, VendorAdapterRegistry } from './vendor-registry.js';
 export { createHexEnvelopeAudioParser, createRawBytesParser } from './response-parsers.js';
+// The submit-then-poll tier (added 2026-09-02) — purely additive alongside `VendorAdapter`, for
+// vendors that hand back a job handle instead of finishing inside one request/response. See
+// `operation-runtime.ts`'s module doc for the persist-before-fetch design.
+export { ASYNC_OPERATION_SCHEMA_VERSION, assertNoCredentialMaterial, createInMemoryAsyncOperationStore, CREDENTIAL_IN_STATE_MESSAGE, hydrateAsyncOperationRecord, } from './async-operation-store.js';
+export { createBearerSigner, withUnsignedRequestInit } from './polling-adapter.js';
+export { DEFAULT_DEADLINE_MS, DEFAULT_GRACE_MS, DEFAULT_MAX_ATTEMPTS, DEFAULT_PERSIST_RETRY_DELAYS_MS, DEFAULT_POLL_INTERVAL_MS, pollDueOperations, recoverAfterRestart, startOperation, } from './operation-runtime.js';
+export { createImageRouterVideoPollingAdapter } from './providers/imagerouter-video-async.js';
 //# sourceMappingURL=index.js.map

package/dist/media-providers/dispatch/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/media-providers/dispatch/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,iCAAiC,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjF,OAAO,EAAE,uBAAuB,EAAE,+BAA+B,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAC9H,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,4BAA4B,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAYhK,sEAAsE;AACtE,0EAA0E;AAC1E,wCAAwC;AACxC,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC/G,OAAO,EAAE,4BAA4B,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/media-providers/dispatch/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,iCAAiC,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjF,OAAO,EAAE,uBAAuB,EAAE,+BAA+B,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAC9H,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,4BAA4B,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAYhK,sEAAsE;AACtE,0EAA0E;AAC1E,wCAAwC;AACxC,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC/G,OAAO,EAAE,4BAA4B,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC3F,gGAAgG;AAChG,4FAA4F;AAC5F,2EAA2E;AAC3E,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,iCAAiC,EACjC,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,4BAA4B,CAAC;AAYpC,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAWnF,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,+BAA+B,EAC/B,wBAAwB,EACxB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,GACf,MAAM,wBAAwB,CAAC;AAUhC,OAAO,EAAE,oCAAoC,EAAE,MAAM,wCAAwC,CAAC"}

package/dist/media-providers/dispatch/operation-runtime.d.ts

@@ -0,0 +1,101 @@
+import type { AsyncOperationRecord, AsyncOperationStore } from './async-operation-store.js';
+import type { AnyPollingVendorAdapter, PollingVendorAdapter, RequestSigner } from './polling-adapter.js';
+import type { RenderContext, RenderResult } from './types.js';
+/** Interactive budget for the inline attempt. Deliberately NOT `FETCH_TIMEOUT_MS.GENERATE` (10min) — that is the backstop for the *request*, this is the ceiling on making a human wait. */
+export declare const DEFAULT_GRACE_MS = 4000;
+export declare const DEFAULT_MAX_ATTEMPTS = 60;
+export declare const DEFAULT_DEADLINE_MS: number;
+export declare const DEFAULT_POLL_INTERVAL_MS = 5000;
+/**
+ * Backoff between retries of the write that records a vendor job handle after a successful
+ * submit. A handle that made it past the vendor round trip must not be dropped just because the
+ * very next write is transiently unlucky — see `startOperation`'s post-submit persistence.
+ */
+export declare const DEFAULT_PERSIST_RETRY_DELAYS_MS: readonly number[];
+export interface OperationRuntimeDeps {
+    readonly store: AsyncOperationStore;
+    readonly signer: RequestSigner;
+    readonly fetchImpl?: typeof fetch;
+    readonly now?: () => number;
+    readonly newId?: () => string;
+    /** Overrides `DEFAULT_PERSIST_RETRY_DELAYS_MS`. Tests pass a short/empty array to avoid real delays. */
+    readonly persistRetryDelaysMs?: readonly number[];
+}
+export interface StartOperationParams<Meta> {
+    readonly adapter: PollingVendorAdapter<Meta>;
+    readonly ctx: RenderContext;
+    readonly providerId: string;
+    readonly routeKey: string;
+    readonly ownerRef: string;
+    readonly maxAttempts?: number;
+    readonly deadlineMs?: number;
+    readonly graceMs?: number;
+}
+export type StartOperationOutcome = {
+    readonly done: true;
+    readonly operationId: string;
+    readonly result: RenderResult;
+} | {
+    readonly done: false;
+    readonly operationId: string;
+};
+/**
+ * Persists the operation row, issues the submit, and races it against the grace window.
+ *
+ * @returns `{done: true, result}` when the vendor finished inside the grace window, else
+ *   `{done: false, operationId}` — the row is already durable in both cases.
+ * @complexity O(1) plus one vendor round trip.
+ */
+export declare function startOperation<Meta>(deps: OperationRuntimeDeps, params: StartOperationParams<Meta>): Promise<StartOperationOutcome>;
+export interface PollDueParams {
+    /** Resolves the adapter registered for a row's `(providerId, routeKey)`. */
+    readonly adapters: (providerId: string, routeKey: string) => AnyPollingVendorAdapter | undefined;
+    /** Rehydrates the render context for a row. The row deliberately does not persist the context — it can hold reference-image data URLs, and none of it is needed to identify the vendor-side job. */
+    readonly resolveContext: (row: AsyncOperationRecord) => RenderContext;
+    readonly leaseOwner: string;
+    readonly leaseMs: number;
+    readonly limit?: number;
+}
+export interface PollDueStats {
+    readonly claimed: number;
+    readonly completed: number;
+    readonly failed: number;
+    readonly pending: number;
+    readonly unknown: number;
+}
+/**
+ * One leased worker tick: claims every due operation, advances each by exactly one vendor poll,
+ * and releases the lease. Safe to run concurrently on several workers — `claimDue` is the
+ * exclusion mechanism.
+ *
+ * Both bounds are enforced here, and in this order: the absolute deadline is checked *before* any
+ * vendor call (a blown deadline must not cost another request), the attempt cap after it.
+ *
+ * @complexity O(k) vendor round trips for k claimed operations.
+ */
+export declare function pollDueOperations(deps: OperationRuntimeDeps, params: PollDueParams): Promise<PollDueStats>;
+export interface RecoverParams {
+    readonly adapters: (providerId: string, routeKey: string) => AnyPollingVendorAdapter | undefined;
+    readonly now?: number;
+}
+export interface RecoverResult {
+    readonly leasesReleased: number;
+    readonly deadlineExpired: number;
+    /** Rows whose submit may or may not have reached the vendor and cannot be safely re-issued. */
+    readonly unknownCrashGap: number;
+    /** Rows whose adapter declares its submit idempotent — left `submitted` for the host to re-issue. */
+    readonly resubmittable: readonly string[];
+}
+/**
+ * Boot-time recovery. Releases dead leases and expires blown deadlines via the store, then handles
+ * the one case the store cannot decide alone: a row still at `submitted`, meaning the process died
+ * between persisting the row and learning whether the vendor accepted the submit.
+ *
+ * Retry safety is gated on idempotency, not assumed. An adapter that has not declared
+ * `submitIsIdempotent` sends that row to `unknown` for reconciliation — media generation is billed
+ * per call, so a silent re-issue can double a real charge.
+ *
+ * @complexity O(n) in stored operations.
+ */
+export declare function recoverAfterRestart(deps: OperationRuntimeDeps, params: RecoverParams): Promise<RecoverResult>;
+//# sourceMappingURL=operation-runtime.d.ts.map

package/dist/media-providers/dispatch/operation-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-runtime.d.ts","sourceRoot":"","sources":["../../../src/media-providers/dispatch/operation-runtime.ts"],"names":[],"mappings":"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"}