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.toolErrorSchemaVersioncompatibility.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.*.*.eqbindings.sqlListeners[].where.*.*.neq | SqlListenerFilterScalarSqlListenerFilterScalar | No No | Scalar equality condition. Scalar inequality condition. |
bindings.sqlListeners[].where.*.*.inbindings.sqlListeners[].where.*.*.notIn | readonly SqlListenerFilterScalar[]readonly SqlListenerFilterScalar[] | No No | Non-empty scalar membership condition. Non-empty scalar exclusion condition. |
bindings.sqlListeners[].where.*.*.isNullbindings.sqlListeners[].where.*.*.isNotNull | truetrue | 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. |