> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Play configuration

New source defaults to authoring contract edition 11. The optional `compatibility: { authoringContract: 'explicit-freshness' }` marker explicitly declares that contract. Existing artifacts retain their pinned edition. Check, publish, and run use the same admitted snapshot.

| Field | Type | Required | Contract |
| - | - | -: | - |
| `displayName` | `string` | No | Optional human-readable Play name. empty uses the derived identifier. |
| `description` | `string` | No | Optional non-empty human-readable summary of the Play. |
| `compatibility.toolErrorSchemaVersion` `compatibility.authoringContract` | `0 \| 1` `'explicit-freshness'` | No No | Artifact-pinned tool error behavior, either 0 or 1. Declares the current explicit-freshness contract. Unmarked new source also uses the current edition. Already-pinned artifacts retain their admitted behavior. |
| `compatibility.toolResponseReceiptRevision` | `string` | No | Explicit durable-receipt revision for a response transformation. bump only when serialized tool output changes. |
| `inline` | `boolean` | No | Compiler hint for an inline named Play handler. |
| `billing.maxCreditsPerRun` | `number` | No | Maximum Deepline credits permitted for one Play Run. |
| `bindings.webhook.hmac.secretEnv` | `string` | Yes | Environment variable containing the webhook HMAC secret. |
| `bindings.webhook.hmac.algorithm` | `'sha256'` | No | Webhook signature hash algorithm. Only sha256 is supported. |
| `bindings.webhook.hmac.header` | `string` | No | HTTP header containing the webhook signature. |
| `bindings.webhook.hmac.signaturePrefix` | `string` | No | Optional literal before the lowercase hexadecimal HMAC. Set to an empty string for providers that send a bare digest. Defaults to sha256= when a signature header is configured. |
| `bindings.webhook.auth.type` | `'standard-webhooks'` | No | Uses the Standard Webhooks v1 symmetric signing scheme. |
| `bindings.webhook.auth.headerFamily` | `'standard' \| 'svix'` | No | Header namespace expected from the webhook provider. |
| `bindings.webhook.auth.signingSecrets[]` | `string` | No | Deepline Secret name used to verify Standard Webhooks. |
| `bindings.webhook.auth.toleranceSeconds` | `number` | No | Accepted delivery timestamp skew in seconds, from 1 through 3600. |
| `bindings.cron.schedule` | `string` | Yes | Five-field cron expression. |
| `bindings.cron.timezone` | `string` | No | IANA timezone. Omitted means UTC. |
| `bindings.cron.input` | `Record<string, unknown>` | No | Static JSON object passed to every run created by this cron binding. |
| `bindings.sqlListeners` | `SqlListener[]` | No | Static provider-monitor listener declarations. |
| `bindings.sqlListeners[].id` | `string` | Yes | Unique static listener identifier within one Play. |
| `bindings.sqlListeners[].tool` | `string` | Yes | Modeled provider monitor tool id in provider.tool form. |
| `bindings.sqlListeners[].stream` | `string` | Yes | Static output stream key exposed by the monitor tool. |
| `bindings.sqlListeners[].operations[]` | `'INSERT' \| 'UPDATE' \| 'DELETE'` | No | Database operation that wakes the listener. |
| `bindings.sqlListeners[].where.before` | `Record<string, SqlListenerFilterOperator>` | No | Column filters evaluated against the row before mutation. |
| `bindings.sqlListeners[].where.after` | `Record<string, SqlListenerFilterOperator>` | No | Column filters evaluated against the row after mutation. |
| `bindings.sqlListeners[].where.*.*.eq` `bindings.sqlListeners[].where.*.*.neq` | `SqlListenerFilterScalar` `SqlListenerFilterScalar` | No No | Scalar equality condition. Scalar inequality condition. |
| `bindings.sqlListeners[].where.*.*.in` `bindings.sqlListeners[].where.*.*.notIn` | `readonly SqlListenerFilterScalar[]` `readonly SqlListenerFilterScalar[]` | No No | Non-empty scalar membership condition. Non-empty scalar exclusion condition. |
| `bindings.sqlListeners[].where.*.*.isNull` `bindings.sqlListeners[].where.*.*.isNotNull` | `true` `true` | No No | Matches null values when set to true. Matches non-null values when set to true. |
| `bindings.sqlListeners[].where.*.*.ilike` | `string` | No | Case-insensitive SQL pattern condition. |
| `bindings.secrets[]` | `string` | No | Environment variable made available to the Play. |
| `staleAfterSeconds` | `number \| null` | No | Edition 11 requires an explicit choice. `0` starts a fresh logical call, though a matching operation receipt may recover that same operation after resume. `null` allows indefinite result reuse. A positive integer is the maximum result age in seconds. Omitted values retain legacy behavior in older editions. |
| `deepline.tools.execute.id` | `string` | Yes | Stable durable receipt identity within one execution scope. |
| `deepline.tools.execute.tool` | `K` | Yes | Integration tool id resolved against the generated ToolMap. |
| `deepline.tools.execute.input` | `K extends keyof ToolMap ? ToolMap[K]['input'] : Record<string, unknown>` | Yes | Tool-specific input object. |
| `deepline.tools.execute.description` | `string` | No | Human-readable purpose of the durable tool call. |
| `deepline.tools.execute.force` | `boolean` | No | Explicitly bypasses a completed durable tool receipt. |
| `deepline.tools.execute.timeoutMs` | `number` | No | Positive whole-number runtime transport timeout in milliseconds. |
| `deepline.tools.execute.receiptWaitMs` | `number` | No | Positive whole-number durable receipt wait budget in milliseconds. |
| `deepline.csv.options.description` | `string` | No | Non-empty description for a staged CSV load. |
| `deepline.csv.options.columns` | `CsvRenameMap` | No | Canonical field-to-header aliases for a staged CSV. |
| `deepline.csv.options.rename` | `CsvRenameMap` | No | Legacy header rename aliases for a staged CSV. |
| `deepline.csv.options.required` | `readonly string[]` | No | Canonical columns required after CSV normalization. |
| `deepline.dataset.key` | `string` | Yes | Stable durable identity for one dataset. |
| `deepline.dataset.run.description` | `string` | No | Non-empty description for one dataset execution. |
| `deepline.dataset.run.key` | `DatasetRowKey<InputRow>` | No | Stable field or fields used for durable row identity. |
| `deepline.dataset.run.rowIdentity` | `'source_row' \| 'key'` | No | Edition 11 requires explicit freshness and semantic identity for supported durable calls. CSV inputs always use source-row occurrence identity, even with rowIdentity: "key". key-based dedup remains available for non-CSV inputs and editions 1–10. |
| `deepline.dataset.run.onRowError` | `'isolate' \| 'fail'` | No | Whether row failures isolate or fail the whole dataset. |
| `deepline.dataset.run.mode` | `'upsert' \| 'net_new'` | No | Whether the dataset returns all rows or only newly admitted rows. |
| `deepline.dataset.run.undrawnColumns` | `readonly string[]` | No | Computed columns deliberately left out of the authored @mermaid diagram. |
| `deepline.step.id` | `string` | Yes | Stable durable identity for one scalar checkpoint. |
| `deepline.step.semanticKey` | `string` | No | Optional semantic receipt identity for a scalar checkpoint. |
| `deepline.step.staleAfterSeconds` | `number \| null` | No | Edition 11 requires an explicit choice. `0` starts a fresh logical call, though a matching operation receipt may recover that same operation after resume. `null` allows indefinite result reuse. A positive integer is the maximum result age in seconds. Omitted values retain legacy behavior in older editions. |
| `deepline.fetch.key` | `string` | Yes | Stable durable identity for one external HTTP request. |
| `deepline.fetch.staleAfterSeconds` | `number \| null` | No | Edition 11 requires an explicit choice. `0` starts a fresh logical call, though a matching operation receipt may recover that same operation after resume. `null` allows indefinite result reuse. A positive integer is the maximum result age in seconds. Omitted values retain legacy behavior in older editions. |
| `deepline.runPlay.key` | `string` | Yes | Stable identity for one inline child Play call. |
| `deepline.runPlay.playRef` | `string \| PlayReferenceLike` | Yes | Child Play name or typed Play definition handle. |
| `deepline.runPlay.input` | `Record<string, unknown>` | Yes | Scalar input object submitted to the child Play. |
| `deepline.runPlay.options.description` | `string` | Yes | Non-empty purpose for one inline child Play call. |
| `deepline.runPlay.options.execution` | `'inline'` | No | Child composition strategy. Only inline is supported. |
| `deepline.runPlay.options.timeoutMs` | `never` | No | Unsupported legacy child-workflow timeout. |
| `deepline.runPlayAsync.key` | `string` | Yes | Stable identity for one independent child Play Run. |
| `deepline.runPlayAsync.playRef` | `string \| PlayReferenceLike` | Yes | Independently published scalar child Play name or strongly typed definition handle. |
| `deepline.runPlayAsync.input` | `Record<string, unknown>` | Yes | Scalar input object submitted to the independent child Run. |
| `deepline.runPlayAsync.options.description` | `string` | Yes | Non-empty purpose for one independent child Play Run. |
| `runtime.timeout` | `string` | No | Play-level sandbox deadline. The default is 30m. Use a static duration such as 90m or 2h, up to 4h. |
| `rateLimit.every` | `string` | No | Start at most one run per window, such as 30s, 5m, or 1h (10s to 24h). |
| `runtime.size` | `'standard' \| 'large' \| 'xlarge' \| '1gb' \| '4gb' \| '8gb'` | No | Deepline-managed sandbox size: standard or 1gb (1 GiB memory, 1 CPU), large or 4gb (4 GiB, 2 CPU), or xlarge or 8gb (8 GiB, 4 CPU). Standard is the default. Each alias selects the same resource profile and compute price as its named size. |
| `deepline.customerDb.query.statement` | `SqlQuery` | Yes | One non-empty Customer DB SQL string. The deprecated SqlQuery object is accepted only without parameter values. |
| `deepline.customerDb.query.options.id` | `string` | Yes | Stable operation identity for Customer DB query recovery. |
| `deepline.customerDb.query.options.staleAfterSeconds` | `number \| null` | No | Customer DB queries always execute with freshness 0. |
| `deepline.customerDb.query.options.maxRows` | `number` | No | Positive whole-number Customer DB response row limit. |
| `deepline.customerDb.query.options.timeoutMs` | `number` | No | Positive whole-number Customer DB timeout in milliseconds. |
| `deepline.tool.key` | `string` | Yes | Stable receipt identity for the tool shorthand. |
| `deepline.tool.tool` | `string` | Yes | Integration tool id for the tool shorthand. |
| `deepline.tool.input` | `Record<string, unknown>` | Yes | Tool-specific input object for the shorthand. |
| `deepline.tool.options.description` | `string` | No | Non-empty purpose for the tool shorthand. |
| `deepline.runSteps.options.description` | `string` | No | Non-empty purpose for a reusable step program. |
| `deepline.runSteps.options.staleAfterSeconds` | `number \| null` | No | Edition 11 requires an explicit choice. `0` starts a fresh logical call, though a matching operation receipt may recover that same operation after resume. `null` allows indefinite result reuse. A positive integer is the maximum result age in seconds. Omitted values retain legacy behavior in older editions. |
| `deepline.sleep.ms` | `number` | Yes | Non-negative whole-number sleep duration in milliseconds. |
| `deepline.fetch.url` | `string` | Yes | HTTP request URL. Secret authentication requires HTTPS. |
| `deepline.fetch.init.method` | `string` | No | HTTP method. Mutating methods require an Idempotency-Key. |
| `deepline.fetch.init.headers.Idempotency-Key` | `string` | No | Required for mutating HTTP methods. The provider must support idempotency, and the same key must be retained across retries and replay. |

### Durable call keys are static

Durable call keys — the deepline.fetch key, the deepline.dataset key, the deepline.step id — must be static string literals. The key names a durable receipt, so check, publish, and replay have to agree on it before the body runs. A key computed at runtime cannot be resolved at check time and is rejected.

This is an architectural constraint, not a style rule. A play cannot loop over a computed key, so it cannot page a large table with a helper like page(pageNumber). Unrolling one literal key per page is not a design at any real page count.

Push the aggregation server-side and call it once: a SQL function, a view, or a provider endpoint that returns the whole result. Keep unrolled literal keys only for a handful of genuinely distinct calls. To fan out over rows, use deepline.dataset with a static key — the per-row receipt identity comes from the row, not from the key.

### Durable HTTP batches

A static deepline.fetch key inside a loop is a warning because every iteration must still have distinct method, URL, body, or safe headers. One durable receipt must never stand in for every request.

Keep the static fetch label. For a mutating batch, make the body distinct and use a replay-stable external Idempotency-Key such as `${deepline.run.id}:signals:${batchIndex}`.

### `deepline.run.id`

deepline.run.id is stable while Deepline retries or resumes one durable run. A separately submitted run receives a new id.

Use it when deriving an external idempotency key for a sequence of batches.

### Runtime capabilities

| Capability | Surface | Contract |
| - | - | - |
| Hosted pages | `deepline.pages.write` | A write replaces the whole page and must set `public`. The first write sets who can see the page. A later write can make a public page private but never a private page public. that takes `deepline pages set-public <name>`, and `deepline plays check` warns when code asks for it. A completed write is safe to repeat. |
| Durable external I/O | `deepline.fetch`, `deepline.tools.execute`, `deepline.step`, `deepline.runPlay` | Use a `deepline.*` primitive for external work. Each primitive owns durable receipt identity and replay. raw I/O in play code does not. |
| Web Crypto | `crypto.subtle` | WebCrypto is available for standards-based signing, verification, encryption, and key import. Keep private material in `deepline.secrets`. `docs-examples/sdk-v2/github-app-jwt.play.ts` is an edition-10 compatibility example. edition 11 allows transient fetches only for read-only methods, so do not copy its credential-returning POST into new source. |
| Workspace secrets | `deepline.secrets.get`, `.bearer`, `.header` | Declare the secret at the Play boundary, read it only at runtime, and never return or log it. Secret-bearing HTTP requests require HTTPS. |
| Freshness | `staleAfterSeconds` on durable calls | New source in edition 11 must choose freshness explicitly. Zero executes a new logical call, a positive integer is a maximum result age in seconds, and null allows indefinite reuse. A completed operation receipt separately recovers the same intended operation after resume. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.