Non-Billable Runway CI Contract Gate

Overview

CI should catch client, request-shape, task-state, and storage regressions without generating media on untrusted code. Provider calls belong in a protected, manually approved canary lane with a hard credit ceiling and no fork secrets.

Prerequisites

• A CI system with protected environments and fork-secret isolation
• Pinned SDK lockfile plus redacted API and task fixtures
• A documented owner for the optional live canary budget

Instructions

Step 1: Inventory trust boundaries

Inspect workflow triggers, permissions, secret inheritance, dependency installation, artifact retention, and fork behavior. Mark every event on which Runway credentials must be unavailable.

Step 2: Build the offline gate

Validate request payloads against reviewed per-model fixtures, exercise all task states, verify retry classifications, and prove output is copied to owned storage. Run with network disabled where practical.

Step 3: Pin the supply chain

Use lockfile-enforced installs, verify the selected SDK package, and fail on unexpected lockfile drift. Do not install an unreviewed latest SDK during CI.

Step 4: Protect test evidence

Use synthetic prompts and media. Redact bearer values, signed output URLs, raw unsafe prompts, and provider responses before uploading artifacts; set a short artifact retention.

Step 5: Isolate the live canary

Place it behind a protected environment, manual approval, trusted default-branch commit, explicit model schema, one-request ceiling, and concurrency lock. Never expose its secret to pull requests from forks.

Step 6: Publish a decision

Report offline contract status separately from live provider status. A skipped canary is not a passing canary, and a created task is not a completed canary.

Authentication

Ordinary CI receives no Runway credential. The protected canary obtains an organization-scoped key only after environment approval and uses server-side bearer authentication plus the reviewed version header.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• Offline CI job covering payload, task, retry, cancellation, and storage contracts
• Protected canary policy with fork isolation, budget, and concurrency lock
• Redacted check summary that distinguishes offline, skipped, and live evidence

Return the environment, organization alias, operation…

Runway HTTP and Task Failure Triage

Overview

Runway has two failure planes: synchronous HTTP responses and asynchronous task terminal states. Triage must preserve the task ID, selected model schema, and redacted evidence before deciding whether a retry is safe.

Prerequisites

• Task ID or redacted HTTP response with request correlation
• Model, endpoint, API version, SDK version, and request fingerprint
• Access to current HTTP-error and task-failure guidance

Instructions

Step 1: Identify the failure plane

If create returned no task ID, classify the HTTP status. If a task exists, retrieve it and classify THROTTLED, FAILED, CANCELLED, or malformed SUCCEEDED output separately.

Step 2: Protect against duplicates

Search durable operation and task records before any retry. A client timeout or lost response is not proof that create failed; reconcile by task ID or operation evidence first.

Step 3: Handle request errors

Treat 400, 401, 404, and 405 as non-retryable until their cause changes. For 400, compare the request against the exact selected model variant instead of editing fields by guesswork.

Step 4: Handle transient HTTP errors

Retry 429, 502, 503, and 504 only with a bound, exponential backoff, and random jitter up to 50 percent. Respect the operation deadline and credit budget.

Step 5: Handle task failures

Inspect failureCode. Never retry safety failures automatically; they still consume credits. Internal or preprocessing-internal failures may permit a delayed, bounded retry according to current documentation.

Step 6: Close the incident

Record the corrected contract or provider recovery, duplicate check, credits at risk, final task state, stored output disposition, and whether a docs or fixture update is required.

Authentication

Triage reads provider tasks using the server-side organization key. Evidence must redact bearer secrets, unsafe prompt bodies, customer media, and signed output URLs while retaining identifiers and hashes needed for correlation.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• HTTP-versus-task failure classification and duplicate-risk decision
• Bounded retry, repair, cancellation, or escalation action
…

Model-Grounded Text-to-Video Workflow

Overview

Treat model choice as an API-schema decision, not a marketing label. Runway request bodies are discriminated by model; valid ratios, durations, prompt limits, optional controls, price, and even required fields can differ between models.

Prerequisites

• A product requirement covering quality, latency, duration, ratio, and budget
• Current Runway models, API reference, and pricing pages
• Durable task tracking and owned output storage

Instructions

Step 1: Define the output contract

Record modality, intended use, dimensions, duration, audio need, quality threshold, deadline, moderation policy, and maximum credits. Separate hard constraints from preferences.

Step 2: Choose direct model or router

Use a direct model when reproducibility requires a reviewed identifier. Use a saved Model Router when policy should optimize cost, latency, or quality within approved allow and deny lists; use its dry run before billable work.

Step 3: Read the exact variant

Inspect the current text_to_video schema for the chosen model. For example, gen4.5 currently supports text input, but this skill does not transplant its ratio or duration fields to another model.

Step 4: Freeze and submit

Persist the model or router config, normalized request, documentation fingerprint, and approval before create. Store the returned task ID immediately.

Step 5: Observe without duplication

Use the SDK wait helper or bounded polling. Treat THROTTLED as queued and distinguish queue time from execution time. Recover from client interruption by retrieving the saved task.

Step 6: Validate and preserve

On success, download output, verify media type, duration, dimensions, and checksum, then run the product quality review. On failure, apply the HTTP or task-failure policy rather than silently changing models.

Authentication

All model, router, task, and usage calls use the server-side Runway API secret. Direct HTTP also sends the reviewed X-Runway-Version; temporary output URLs remain confidential until copied to controlled storage.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• Reviewed model-or-router decision with current schema and price evidence
• Durable request fingerprint, task timeline, and terminal-state receipt
• Owned output plus…

Runway Input-Media Transformation Workflow

Overview

Input media is part of the generation contract and the security boundary. Choose public HTTPS, data URI, or an ephemeral upload deliberately; verify rights, content, size, format, crop, expiry, and model compatibility before spending credits.

Prerequisites

• An approved source asset with provenance and usage rights
• Current input constraints and exact model variant schema
• Temporary-upload and final-output retention policies

Instructions

Step 1: Classify the transformation

Choose image-to-video, video-to-video, upscale, or another documented endpoint from the desired input and output—not from a copied sample. Record the expected preservation and allowed creative change.

Step 2: Validate the asset

Check MIME type, extension, byte size, dimensions, duration, codec, orientation, and moderation policy. Review auto-crop consequences when the source aspect ratio differs from the requested output.

Step 3: Choose transport

Use a reachable HTTPS URL for already hosted media, a data URI only for small inputs, or an ephemeral upload for local files. Never embed large video as base64 merely because a sample does.

Step 4: Create an ephemeral upload safely

For local media, use the SDK helper or the documented two-step upload. A runway:// URI lasts 24 hours, supports reuse within that period, and must not be treated as permanent storage.

Step 5: Submit and track

Validate the chosen model's input fields, persist the request fingerprint and task ID, then use bounded polling. Do not retry a failed upload URL; start a new upload as documented.

Step 6: Validate transformed output

Copy successful output to owned storage and compare duration, dimensions, codec, visible crop, continuity, brand constraints, and safety. Preserve both source and output checksums in the receipt.

Authentication

The Runway API secret remains server-side for uploads, generation, and task reads. Source URLs and temporary Runway/output URLs may grant access to media and must be redacted and expired according to policy.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• Input provenance, validation, crop, and transport decision
• Upload and generation identifiers with state evidence
• Owned output with media, safety, and transformation review

Return the environment, organiz…

Evidence-Based Runway Credit Optimization

Overview

Runway pricing changes independently of models and code. Cost tuning begins from the current pricing page and authorized usage data, then removes accidental duplicates, rejected work, oversized outputs, unnecessary variants, and poor routing without lowering an approved quality or safety bar.

Prerequisites

• Current first-party pricing and organization usage evidence
• Operation, task, model, duration, output-count, state, and credit records
• A product-owned quality policy and finance-approved budget

Instructions

Step 1: Freeze the authority

Record retrieval time and fingerprint for the current pricing page, billing model, organization tier, and contract exceptions. Do not copy a historical credit table into a long-lived calculator.

Step 2: Reconcile demand to tasks

Join internal operation IDs to provider task IDs and usage. Separate successful, failed, moderated, cancelled, duplicate, abandoned, and stored outputs; account for safety failures that still consume credits.

Step 3: Find duplicate generation

Identify timeouts, client retries, queue resubmission, race conditions, and lost task IDs. Fix persistence and recovery before trading away output quality.

Step 4: Compare eligible policies

For each workload, compare approved direct models or Model Router configurations on current estimated credits, latency, and quality. Use router dryRun where supported because it returns selection and estimated cost without generating an asset.

Step 5: Control request shape

Review duration, resolution, output count, reference count, recipe choice, and retries against the product requirement. Reduce only fields that do not violate the approved result.

Step 6: Roll out with guardrails

Set per-operation and rolling budgets, alerts, concurrency locks, and automatic stop conditions. Compare credits per accepted asset and quality escape rate before expanding.

Authentication

Use minimally scoped server-side API and authorized organization usage access. Finance exports should contain aggregate identifiers and credits, not API keys, customer media, prompts, or signed output URLs.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• Pricing and usage authority snapshot
• Measured credit drivers, duplicate waste, and policy scenarios
• Approved change with before/af…

Redacted Runway Generation Debug Bundle

Overview

A useful bundle proves exactly what contract ran and where it failed without redistributing sensitive prompts, customer media, bearer secrets, or temporary output access. Collect metadata and hashes first, then add narrowly approved samples only when support requires them.

Prerequisites

• Internal operation ID or provider task ID
• Access to redacted application traces and current contract sources
• An approved destination and retention period for support evidence

Instructions

Step 1: Freeze identifiers

Record environment, organization alias, internal operation ID, task ID, endpoint, model or router config ID, API version, SDK name/version, and UTC timestamps.

Step 2: Capture the request contract

Store a canonical request hash plus field names, lengths, MIME metadata, dimensions, duration, and source checksums. Omit bearer headers, raw customer media, unsafe prompts, and reachable input URLs.

Step 3: Capture state and timing

Include create response correlation, PENDING, THROTTLED, RUNNING, and terminal transitions as observed; add local queue, upload, poll, download, and storage timings.

Step 4: Capture the failure plane

For HTTP failure, include status, safe headers, request ID, and redacted error. For task failure, include failureCode and sanitized diagnostic. For malformed success, include output count and validation errors, not the signed URLs.

Step 5: Prove local controls

Attach retry attempt bounds, backoff/jitter settings, timeout, cancellation action, duplicate check, selected model schema fingerprint, and relevant fixture result.

Step 6: Minimize and share

Review every field, replace values with hashes where possible, encrypt the bundle, set access and expiry, and record the recipient and deletion owner.

Authentication

Task retrieval uses the server-side Runway secret, but the bundle never contains the secret or an authorization header. Temporary input and output URLs are credentials to media and must be redacted.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• Machine-readable redacted manifest and human timeline
• Contract, state, retry, and media-metadata evidence
• Access-controlled support package with retention and deletion owner

Return the environment, organization alias, oper…

Deploy an Asynchronous Runway Worker

Overview

Runway generation does not fit a synchronous request-response handler. Production deployment should accept intent quickly, persist it, execute through bounded workers, reconcile provider task state after restarts, and move successful assets into owned storage.

Prerequisites

• A deployment environment with queues, durable database, and object storage
• Server-side secrets, egress policy, and reviewed Runway contract
• Capacity, credit, moderation, retention, and rollback owners

Instructions

Step 1: Split API from worker

Make the public endpoint validate intent, assign an operation ID, persist approval and request fingerprint, enqueue work, and return an internal status handle. Do not hold an HTTP request open for generation.

Step 2: Persist provider identity

The worker records the provider task ID immediately after create. Retries and restarts must retrieve that task before any new create decision.

Step 3: Control capacity

Apply per-model concurrency, deadline, priority, and credit guards. Treat provider THROTTLED tasks as already accepted; never resubmit them just because they have not started.

Step 4: Reconcile state

Run a bounded scheduler that retrieves nonterminal tasks, adds jitter/backoff, handles all terminal states, and can resume after deployment. A local shutdown or timeout does not cancel provider work.

Step 5: Own successful assets

Download successful output promptly to controlled object storage, verify it, set access and retention, and discard signed provider URLs from normal application records.

Step 6: Roll out and roll back

Deploy a no-create read probe, one approved canary, then staged traffic. Rollback stops new admission while the old compatible worker drains or cancels existing tasks according to policy.

Authentication

Workers receive RUNWAYML_API_SECRET from the deployment secret manager and use the reviewed API version. Public handlers and browser bundles never receive the provider key or signed asset URLs.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• API, queue, worker, state-store, and output-store deployment map
• Capacity, retry, timeout, cancellation, drain, and rollback controls
• Canary and staged-rollout receipt with terminal-state and storage evidence

Return the environment, organization…

One Controlled Runway Generation

Overview

Prove the minimum asynchronous generation path without pretending that task creation is completion. A Runway generation consumes credits and may be moderated, so the smoke test requires an explicit cost ceiling, safe prompt, terminal-state evidence, and owned output storage.

Prerequisites

• Server-side Runway authentication and available organization credits
• An operator-approved model, prompt, duration, ratio, and maximum credit budget
• Durable task storage and an output bucket with retention controls

Instructions

Step 1: Read the current model schema

Open the current models guide and the exact text_to_video model variant in the API reference. Confirm model identifier, required fields, prompt limit, ratio set, duration range, and price immediately before the test.

Step 2: Freeze the billable intent

Record a unique operation ID, normalized request fingerprint, model, duration, ratio, estimated ceiling, and approval. Use gen4.5 only when its current schema still matches the request; never revive retired gen3a_turbo.

Step 3: Create one task

Submit one server-side request. Persist the returned task ID before waiting. Treat the create response as acceptance into the task system, not a generated asset.

Step 4: Wait with a bound

Use the SDK wait helper or poll GET /v1/tasks/<task-id> no more frequently than every five seconds with jitter and backoff. Set a deadline. Remember that a client timeout does not cancel the provider task.

Step 5: Classify the terminal state

Accept output only from SUCCEEDED. For FAILED, retain redacted failureCode and diagnostic text; for CANCELLED, record who cancelled. Treat THROTTLED as queued, not failed.

Step 6: Own the output

Download successful output promptly, validate type and size, store it under the operation ID, and retain the source URL only as sensitive temporary evidence because Runway output URLs expire.

Authentication

Create and task-read requests use the server-side bearer secret and reviewed Runway API version. Never expose the key or temporary signed output URL to an untrusted browser, log stream, or ticket.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• Task ID, request fingerprint, approval, and observed st…

Secure Runway SDK and REST Bootstrap

Overview

Establish a reproducible client, explicit API-version contract, and non-billable authentication probe. Runway API keys are organization-scoped credentials, so a working client is not evidence that a user should retain access or that a billable generation is approved.

Prerequisites

• Runway Dev organization and an operator authorized to manage API keys
• Node.js 18+ or Python 3.8+, or an HTTP client for the REST path
• A secret manager and a reviewed X-Runway-Version value

Instructions

Step 1: Discover the integration boundary

Use Read and Grep to locate runtime manifests, lockfiles, existing Runway clients, environment-variable names, and browser/server boundaries. Separate Runway Dev API access from the consumer Runway web application and from the OAuth-based Runway Dev MCP.

Step 2: Resolve and pin the client

Choose @runwayml/sdk, runwayml, or direct REST. Query the package registry and official SDK page at implementation time, review the changelog, and pin the selected compatible version in the project lockfile instead of copying a stale version from this skill.

Step 3: Provision the key safely

Create or rotate a key in the Developer Portal under the intended organization. Store it as RUNWAYML_API_SECRET in the deployment secret manager. Never place it in source, logs, screenshots, browser bundles, MCP configuration, or client-visible environment variables.

Step 4: Configure the protocol

The official SDKs read RUNWAYML_API_SECRET and supply the version header. For direct HTTP, send Authorization: Bearer <secret> and X-Runway-Version: 2024-11-06 to https://api.dev.runwayml.com; centralize both headers in one server-side client.

Step 5: Run a read-only probe

Use a documented organization or task read endpoint that the key is authorized to access. Record status, request ID, API version, and organization identity in redacted form. Do not create a generation merely to prove authentication.

Step 6: Exercise rotation and revocation

Install the replacement key, prove the read path, switch consumers, disable the old key explicitly, and prove the old key receives 401. Removing an organization member alone does not revoke an organization-scoped key.

Authentication

Runway REST authentication is a bearer API secret plus the required X-Runway-Version header. The SDKs obtain the secret from RUNWAYML_API_SECRET; browser code must call a protected server endpoint rather than receive the secret.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before prop…

Runway Offline-First Development Loop

Overview

Make routine development deterministic and non-billable. The local loop should model Runway's asynchronous protocol accurately, while a separately authorized canary detects provider drift without turning every test run into paid generation.

Prerequisites

• A local service boundary that can replace the Runway client
• Redacted fixtures for create, task states, HTTP errors, and task failures
• A disabled-by-default credential path for an approved canary

Instructions

Step 1: Map the seam

Use Read and Grep to locate direct SDK calls, task persistence, output download code, retries, and cancellation. Introduce one provider interface if application code currently imports the SDK everywhere.

Step 2: Model the state machine

Create fixtures for PENDING, THROTTLED, RUNNING, SUCCEEDED, FAILED, and CANCELLED. Make only SUCCEEDED include output; make failed fixtures include a machine-readable failure code.

Step 3: Separate clocks and network

Inject polling time, jitter, timeout, and HTTP transport. Tests should advance a fake clock and never wait five real seconds or contact Runway.

Step 4: Protect against duplicate work

Persist an internal operation ID and provider task ID. Simulate a lost response after task creation and prove recovery reads the saved task rather than issuing another paid request.

Step 5: Test media boundaries

Use tiny synthetic files and fixtures for public URL, data URI, and runway:// input. Model auto-crop review, upload expiry, output expiry, and owned-storage copy without retaining real signed URLs.

Step 6: Run an opt-in canary

Require an explicit environment switch, safe prompt, model schema check, credit ceiling, and named approver. Keep CI and ordinary local commands on the fake provider.

Authentication

Fixtures contain no usable secrets. The optional canary reads RUNWAYML_API_SECRET only in the server process, uses the reviewed version header, and refuses to run when the opt-in approval variables are incomplete.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• Replaceable Runway client interface and deterministic fixture set
• Fast state-machine, retry, timeout, cancellation, and duplicate-recovery tests
• Redacted optio…

Runway Queue-to-Asset Performance Tuning

Overview

End-to-end latency is a sequence of distinct phases: local admission, upload, provider queue, generation, output download, and owned storage. Optimize the measured bottleneck while preserving model quality, moderation, quota, and cost constraints.

Prerequisites

• An SLO with percentile, modality, model, duration, and quality dimensions
• Traceable operation and task state timestamps
• Current model, input, tier, and pricing evidence

Instructions

Step 1: Instrument the phases

Capture operation accepted, local queue start/end, upload start/end, provider create, each state transition, terminal state, download, validation, and storage completion. Use redacted IDs to join traces.

Step 2: Separate queue from generation

Report THROTTLED and PENDING residence independently from RUNNING. A concurrency bottleneck should not be misdiagnosed as model execution slowness.

Step 3: Reduce input overhead

Prefer already hosted HTTPS media or reusable ephemeral uploads when appropriate. Avoid large data URIs, validate formats before submission, and review silent auto-crop work.

Step 4: Tune observation

Use SDK wait helpers or polling at five seconds or more with jitter and backoff. Replace per-request busy loops with a bounded worker scheduler; more polls do not make generation finish sooner.

Step 5: Evaluate routing and models

Compare only eligible models or approved router policies on latency, quality, and credits. Use router dry runs for selection evidence and controlled canaries for realized performance.

Step 6: Protect tail latency

Apply deadlines, queue priorities, cancellation policy, circuit breaking for transient outages, and owned-output download retries. Never create duplicate generations as a latency hedge without explicit cost approval.

Authentication

Performance traces use server-side Runway access and must redact keys, prompt/media content, and signed URLs. Organization usage access should be restricted to operators who need capacity and cost evidence.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• Phase-by-phase latency profile with percentiles and task states
• Ranked bottleneck hypotheses and controlled changes
• Before/after SLO, quality, failure, and credit-impact receipt

Return the environment, organi…

Runway Production Readiness Gate

Overview

Go-live is an evidence gate, not a list of intentions. The release must prove model-aware validation, durable asynchronous state, credit and concurrency controls, moderation handling, owned output storage, secret rotation, observability, and a rollback that does not orphan provider tasks.

Prerequisites

• Release SHA, environment, owner, SLO, budget, and rollback candidate
• Current first-party API, models, limits, pricing, and go-live guidance
• Passing contract, security, load, failure, and canary evidence

Instructions

Step 1: Verify contract and supply chain

Pin the reviewed SDK, API version, model or router schemas, and lockfile. Reject retired identifiers such as gen3a_turbo and any request shape copied across model variants.

Step 2: Verify identity and secrets

Confirm organization, roles, key consumers, secret-manager delivery, redaction, rotation owner, and explicit old-key disable procedure. Prove the browser has no provider credential.

Step 3: Verify task reliability

Prove operation and task ID persistence, restart recovery, all six states, bounded polling, transient retry classes, explicit cancellation, and no duplicate create after ambiguity.

Step 4: Verify capacity and billing

Record tier, per-model concurrency, rolling daily quota, spend cap, credit balance, autobilling alerts, canary ceiling, and stop conditions. Treat THROTTLED as queued work.

Step 5: Verify content and storage

Confirm rights, moderation policy, supported input, crop review, failed-safety handling, output validation, owned private storage, URL expiry, retention, and deletion.

Step 6: Run and decide

Execute one approved canary, trace it through terminal state and storage, test alerts, then rehearse rollback: stop admission, drain or cancel compatible tasks, and preserve reconciliation.

Authentication

Production keys live only in the secret manager and are scoped operationally through server access controls. The readiness evidence contains aliases and hashes, never usable bearer values or signed media URLs.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• Pass/fail matrix with owner and evidence link per control
• Canary task and owned-output receipt under an explicit ceiling
• Launch or rejection decision with drain, cancellation, and rollback state

Runway Concurrency and Quota Control

Overview

Runway generation capacity is governed by usage-tier limits, not a universal requests-per-minute number. The application must distinguish accepted-but-queued THROTTLED tasks from create requests rejected with 429, then apply local admission control to protect deadlines and budget.

Prerequisites

• Current organization tier and per-model limit evidence
• Task creation, state, latency, daily-generation, and credit metrics
• A durable queue with priority, deadline, and cancellation policy

Instructions

Step 1: Read live authority

Review the organization Usage page and current tiers documentation. Record per-model concurrency, rolling 24-hour generation cap, 30-day spend cap, and any approved enterprise exception.

Step 2: Measure by model

Count create attempts, accepted task IDs, THROTTLED depth and age, running tasks, terminal states, queue wait, execution time, and rolling daily use per model and organization.

Step 3: Set local admission control

Use per-model semaphores below the provider concurrency boundary, a global budget guard, priority queues, and customer deadlines. Do not add arbitrary RPM sleeps that hide the actual capacity model.

Step 4: Treat THROTTLED correctly

Keep the existing task ID and continue bounded observation. Do not create a replacement task; Runway has already stored and queued it.

Step 5: Handle 429 correctly

Determine whether the rolling daily generation quota or another documented limit was exceeded. Stop new admission, calculate when capacity returns, and retry only within the documented transient policy and operation deadline.

Step 6: Tune with evidence

Adjust worker concurrency from queue age, terminal throughput, failure rate, and spend—not request count alone. Request an official exception when the documented tiers cannot meet the service objective.

Authentication

Usage and task reads use the same server-side organization credential as generation. Limit telemetry should identify organization and model without exporting the API secret, prompt contents, or temporary media URLs.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• Authoritative tier and per-model capacity snapshot
• Admission-control, queue, deadline, and cancellation policy
• Before/after queue, throug…

Runway Production Control-Plane Architecture

Overview

The stable architecture centers on an internal operation record rather than a provider request. It isolates credentials, models asynchronous task state, applies cost and concurrency admission, preserves media in owned storage, and makes provider/API drift reviewable.

Prerequisites

• Workload, SLO, data-classification, and budget requirements
• Current Runway API, model, limits, pricing, and output contracts
• Owners for security, media rights, moderation, operations, and finance

Instructions

Step 1: Define trust zones

Place clients outside the provider credential boundary. Put the admission API, task worker, reconciler, secret access, and provider egress in a server zone; isolate raw media and final assets by classification.

Step 2: Make operation state authoritative

Persist operation ID, actor, approval, request fingerprint, model or router policy, provider task ID, state timeline, budget, and output object. Enforce legal state transitions and unique provider IDs.

Step 3: Separate control and data planes

The control plane validates, queues, retrieves, cancels, and emits internal events. The data plane stages input, performs ephemeral upload when needed, validates output, and copies assets to owned storage.

Step 4: Apply governance at admission

Check rights, moderation policy, tenant quotas, credit ceiling, model allowlist, duration and ratio schema, and retention before creating billable work.

Step 5: Reconcile asynchronously

Workers honor per-model concurrency; reconcilers observe THROTTLED and terminal states with bounded polling. Internal consumers receive idempotent events derived from persisted transitions.

Step 6: Design for change

Pin SDK and API contracts, fingerprint official docs, use model-aware fixtures, canary upgrades, and support both direct model and approved router policies without scattering identifiers.

Authentication

Only server-side workers and restricted operational readers access the organization-scoped key. Signed media URLs are short-lived capabilities; application clients receive controlled internal asset URLs instead.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• Component, trust-zone, data-flow, and state-transition design
• Capacity, budget, security, retention, and failure policies
• Migration, canary…

Recoverable Runway SDK Client Pattern

Overview

A production client must separate request acceptance, provider task execution, and output persistence. The SDK removes protocol boilerplate, but the application still owns operation identity, deadlines, cancellation, state recovery, observability, and business decisions.

Prerequisites

• Pinned official Node or Python SDK and reviewed API contract
• Durable operation and provider-task persistence
• Injected timeout, retry, logging, and output-storage adapters

Instructions

Step 1: Create one client factory

Construct the SDK once per process from server-side configuration. Expose reviewed timeouts, retry policy, and user agent; do not scatter raw client creation across handlers.

Step 2: Define typed commands and results

Represent create intent, accepted task ID, provider state, terminal result, and stored asset separately. Prevent callers from treating an accepted create response as output.

Step 3: Persist before waiting

Write operation ID, normalized request hash, and provider task ID transactionally before calling a wait helper. On restart, retrieve the task and resume rather than creating again.

Step 4: Bound waiting

Use waitForTaskOutput or wait_for_task_output with a deadline and cancellation signal. A local abort or timeout stops waiting only; call the task cancellation endpoint when policy requires provider cancellation.

Step 5: Classify failures

Map HTTP responses, TaskFailedError, timeout, cancellation, and malformed output into distinct application errors. Retry only documented transient HTTP classes; never retry safety failures automatically.

Step 6: Store and observe

Copy output to owned storage, emit queue, run, and download timings, and record SDK version, API version, model, task ID, and redacted request fingerprint.

Authentication

The factory reads RUNWAYML_API_SECRET from a server secret provider. Direct protocol concerns such as bearer and version headers stay inside the SDK boundary; application logs must redact credentials and signed URLs.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• Single typed client boundary with injected dependencies
• Restart-safe create, retrieve, wait, cancel, and output-copy behavior
• Structured error taxonomy and redacted telemetry contract

Return…

Runway Credential, Media, and Moderation Controls

Overview

Runway integrations handle organization-scoped credentials and potentially sensitive media. Security must cover key lifecycle, server-only egress, input rights, temporary URL capabilities, moderation outcomes, output access, evidence minimization, and incident response.

Prerequisites

• Data classification and media-rights policy
• Runway organization role and key inventory
• Secret manager, private object storage, audit logging, and incident owners

Instructions

Step 1: Inventory identities and keys

List organization members, roles, keys, consumers, environments, creation dates, and rotation owners. Removing a member does not disable their organization-scoped keys, so revocation is a separate control.

Step 2: Enforce server-only access

Keep RUNWAYML_API_SECRET in a secret manager and restrict egress to Runway hosts. Prevent browser exposure, repository commits, shell history, build arguments, logs, traces, and support archives.

Step 3: Govern input content

Verify rights, tenant authorization, data minimization, acceptable-use policy, file type and size, and public-URL exposure. Treat prompts and source media as sensitive application data.

Step 4: Handle moderation honestly

Expect moderation as a failed task and inspect failureCode. Do not automatically retry safety failures or expose unsafe diagnostics; repeated moderated requests can threaten account availability.

Step 5: Control media capabilities

Treat public input URLs, runway:// URIs, and signed output URLs as temporary access capabilities. Copy approved output to owned private storage, scan and validate it, and issue internal authorized links.

Step 6: Prove rotation and response

Rotate keys through a canary, explicitly disable old credentials, scan for leaks, and maintain a playbook for revocation, artifact restriction, customer notification, and evidence deletion.

Authentication

Bearer secrets authenticate the organization, not an end user. Authorization in the product must therefore occur before the server uses Runway; API authentication does not replace tenant, actor, media-rights, or budget checks.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• Key, role, consumer, and data-flow inventory
• Threat model and prioritized credential/media/moderation con…

Runway SDK and Model Contract Migration

Overview

A Runway upgrade can change client types, model availability, allowed fields, output behavior, cost, latency, and quality at once. Preserve operation and task compatibility while migrating from retired identifiers through explicit per-model contracts and controlled comparisons.

Prerequisites

• Current dependency lock, model/request inventory, and task-state schema
• Target SDK changelog, API reference, models, and pricing evidence
• Representative fixtures, canary budget, and rollback owner

Instructions

Step 1: Inventory the current surface

Use Read and Grep to find SDK imports, raw endpoints, version headers, model identifiers, ratio and duration literals, wait helpers, error classes, task persistence, output handling, and docs.

Step 2: Define the target contract

Resolve the target SDK and review its changelog. For model changes, inspect exact input/output variants; gen3a_turbo is retired, while gen4.5 and gen4_turbo have different input capabilities and cannot be substituted mechanically.

Step 3: Build compatibility fixtures

Capture accepted request shapes, every task state, HTTP and task failures, cancellation, timeout, and output-copy behavior. Add explicit rejection tests for retired identifiers and cross-model fields.

Step 4: Separate code and policy rollout

Introduce a client adapter that can read existing task IDs, then deploy target support disabled. Change model or router policy separately so dependency regressions and output-quality changes remain distinguishable.

Step 5: Canary both paths

Use safe representative prompts/media and fixed ceilings. Compare schema acceptance, queue/run latency, terminal rate, credits, dimensions, duration, moderation, and blinded product quality.

Step 6: Migrate and retire

Ramp by tenant or workload, keep retrieval compatibility for old tasks, stop new old-contract admission, then remove deprecated code only after the reconciliation horizon. Retain a rollback that does not recreate tasks.

Authentication

Migration tests use protected server-side credentials and redacted fixtures. Package registry lookup and documentation are public; live generations require explicit approval and a bounded credit budget.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• Current-to-target dependency, model,…

Runway Polling-to-Event Relay

Overview

The documented Runway generation surface exposes task retrieval and cancellation, not a native generation-completion webhook endpoint. Build notifications by reconciling provider task state into an internal outbox, then deliver idempotent internal events or your own signed customer webhook.

Prerequisites

• Durable operations, provider task IDs, and legal state transitions
• A bounded polling scheduler and transactional outbox
• Consumer authentication, signing, retry, and replay policies

Instructions

Step 1: State the authority boundary

Document that Runway is polled via GET /v1/tasks/<task-id>. Do not configure a fictional provider webhook secret or tell consumers that a callback originated from Runway.

Step 2: Reconcile provider state

Retrieve due nonterminal tasks at five-second-or-longer jittered intervals with backoff. Treat THROTTLED as queued and accept only legal forward transitions to SUCCEEDED, FAILED, or CANCELLED.

Step 3: Write state and outbox atomically

Persist the newly observed state, provider evidence hash, and one outbox record in the same transaction. Use a uniqueness key such as operation ID plus state version so restarts cannot duplicate logical events.

Step 4: Shape the internal event

Emit internal operation ID, provider task ID, terminal state, timestamps, model or router metadata, stored-asset ID, and redacted failure class. Never emit bearer keys, prompt/media bodies, or signed provider URLs.

Step 5: Deliver your callback

For customer webhooks, sign exact raw bytes with your service's secret, include timestamp and event ID, retry with a bound, and expose replay and verification guidance. This is your protocol, not Runway's.

Step 6: Reconcile delivery

Track attempts, acknowledgements, dead letters, consumer idempotency, and asset authorization. A callback failure must not trigger a new Runway generation.

Authentication

Provider polling uses the server-side Runway bearer secret and version header. Internal buses use workload identity; customer callbacks use a separate service-owned signing secret and never reuse the Runway key.

Tool Discipline

Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.

Output

• Explicit provider-polling and internal-event architecture
• Transactional state/outbox and ide…