deepline 0.3.45 → 0.3.47

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/dist/bundling-sources/sdk/src/client.ts +2 -3
  2. package/dist/bundling-sources/sdk/src/errors.ts +2 -2
  3. package/dist/bundling-sources/sdk/src/http.ts +1 -1
  4. package/dist/bundling-sources/sdk/src/play.ts +7 -10
  5. package/dist/bundling-sources/sdk/src/plays/bundle-play-file.ts +3 -3
  6. package/dist/bundling-sources/sdk/src/release.ts +3 -3
  7. package/dist/bundling-sources/sdk/src/version.ts +2 -2
  8. package/dist/bundling-sources/shared_libs/play-data-plane/contracts.ts +25 -0
  9. package/dist/bundling-sources/shared_libs/play-data-plane/index.ts +1 -0
  10. package/dist/bundling-sources/shared_libs/play-data-plane/sheet-contract.ts +1 -1
  11. package/dist/bundling-sources/shared_libs/play-runtime/app-runtime-api.ts +19 -19
  12. package/dist/bundling-sources/shared_libs/play-runtime/backend.ts +5 -6
  13. package/dist/bundling-sources/shared_libs/play-runtime/cell-staleness.ts +1 -66
  14. package/dist/bundling-sources/shared_libs/play-runtime/context.ts +11 -11
  15. package/dist/bundling-sources/shared_libs/play-runtime/ctx-types.ts +3 -3
  16. package/dist/bundling-sources/shared_libs/play-runtime/dataset-id.ts +4 -3
  17. package/dist/bundling-sources/shared_libs/play-runtime/durable-call-cache.ts +3 -4
  18. package/dist/bundling-sources/shared_libs/play-runtime/durable-receipt-execution.ts +2 -2
  19. package/dist/bundling-sources/shared_libs/play-runtime/email-status.ts +1 -275
  20. package/dist/bundling-sources/shared_libs/play-runtime/execution-ledger-store.ts +1 -1
  21. package/dist/bundling-sources/shared_libs/play-runtime/extractor-targets.ts +1 -106
  22. package/dist/bundling-sources/shared_libs/play-runtime/gateway-postgres-admission.ts +1 -2
  23. package/dist/bundling-sources/shared_libs/play-runtime/governor/in-memory-rate-state-backend.ts +13 -4
  24. package/dist/bundling-sources/shared_libs/play-runtime/live-events.ts +1 -5
  25. package/dist/bundling-sources/shared_libs/play-runtime/map-row-identity.ts +2 -3
  26. package/dist/bundling-sources/shared_libs/play-runtime/map-row-outcome.ts +2 -1
  27. package/dist/bundling-sources/shared_libs/play-runtime/modal-runtime-config.ts +1 -1
  28. package/dist/bundling-sources/shared_libs/play-runtime/output-size-limits.ts +1 -1
  29. package/dist/bundling-sources/shared_libs/play-runtime/projection.ts +5 -5
  30. package/dist/bundling-sources/shared_libs/play-runtime/protocol.ts +3 -3
  31. package/dist/bundling-sources/shared_libs/play-runtime/run-failure.ts +1 -1
  32. package/dist/bundling-sources/shared_libs/play-runtime/run-snapshot-stream.ts +1 -1
  33. package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona-lifecycle.ts +4 -4
  34. package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona-modal-fallback.ts +3 -3
  35. package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona-payload-transport.ts +8 -8
  36. package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona-session-execution.ts +1 -1
  37. package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/daytona.ts +4 -4
  38. package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/local-process.ts +7 -7
  39. package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/backends/modal.ts +7 -7
  40. package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/bundle.ts +13 -2
  41. package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/index.ts +2 -2
  42. package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/runner-events.ts +1 -1
  43. package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/runtime-sandbox-reconciliation.ts +1 -1
  44. package/dist/bundling-sources/shared_libs/play-runtime/runner-backends/types.ts +2 -2
  45. package/dist/bundling-sources/shared_libs/play-runtime/runtime-actions.ts +1 -1
  46. package/dist/bundling-sources/shared_libs/play-runtime/runtime-api.ts +6 -3
  47. package/dist/bundling-sources/shared_libs/play-runtime/runtime-constants.ts +1 -1
  48. package/dist/bundling-sources/shared_libs/play-runtime/runtime-constraints.ts +1 -2
  49. package/dist/bundling-sources/shared_libs/play-runtime/runtime-env.ts +55 -0
  50. package/dist/bundling-sources/shared_libs/play-runtime/sandbox-runtime-limits.ts +1 -109
  51. package/dist/bundling-sources/shared_libs/play-runtime/step-program-dataset-builder.ts +1 -1
  52. package/dist/bundling-sources/shared_libs/play-runtime/test-runtime-seams.ts +1 -1
  53. package/dist/bundling-sources/shared_libs/play-runtime/tool-execute-retry-policy.ts +1 -1
  54. package/dist/bundling-sources/shared_libs/play-runtime/tool-execution-outcome.ts +6 -5
  55. package/dist/bundling-sources/shared_libs/play-runtime/tool-http-errors.ts +1 -1
  56. package/dist/bundling-sources/shared_libs/play-runtime/tool-result-types.ts +1 -206
  57. package/dist/bundling-sources/shared_libs/play-runtime/tool-result.ts +10 -7
  58. package/dist/bundling-sources/shared_libs/play-runtime/work-receipts.ts +1 -1
  59. package/dist/bundling-sources/shared_libs/plays/artifact-types.ts +8 -3
  60. package/dist/bundling-sources/shared_libs/plays/authoring-contract.ts +4 -4
  61. package/dist/bundling-sources/shared_libs/plays/bundling/index.ts +3 -6
  62. package/dist/bundling-sources/shared_libs/plays/cell-staleness.ts +66 -0
  63. package/dist/bundling-sources/shared_libs/plays/compiler-manifest.ts +1 -1
  64. package/dist/bundling-sources/shared_libs/plays/contracts.ts +2 -2
  65. package/dist/bundling-sources/shared_libs/plays/core.ts +466 -0
  66. package/dist/bundling-sources/shared_libs/plays/email-status.ts +287 -0
  67. package/dist/bundling-sources/shared_libs/plays/extractor-targets.ts +106 -0
  68. package/dist/bundling-sources/shared_libs/plays/row-identity.ts +1 -3
  69. package/dist/bundling-sources/shared_libs/plays/runtime-constraints.ts +2 -0
  70. package/dist/bundling-sources/shared_libs/plays/runtime-validation.ts +4 -2
  71. package/dist/bundling-sources/shared_libs/plays/sandbox-runtime-limits.ts +109 -0
  72. package/dist/bundling-sources/shared_libs/plays/tool-execution-error.ts +624 -0
  73. package/dist/bundling-sources/shared_libs/plays/tool-result-types.ts +206 -0
  74. package/dist/bundling-sources/shared_libs/security/safe-outbound-fetch.ts +1 -1
  75. package/dist/cli/index.js +181 -169
  76. package/dist/cli/index.mjs +189 -170
  77. package/dist/{compiler-manifest-DwYe2C2S.d.mts → compiler-manifest-BuoqasqI.d.mts} +585 -540
  78. package/dist/{compiler-manifest-DwYe2C2S.d.ts → compiler-manifest-BuoqasqI.d.ts} +585 -540
  79. package/dist/index.d.mts +9 -2
  80. package/dist/index.d.ts +9 -2
  81. package/dist/index.js +47 -40
  82. package/dist/index.mjs +47 -40
  83. package/dist/install-integrity.json +13 -3
  84. package/dist/plays/bundle-play-file.d.mts +4 -61
  85. package/dist/plays/bundle-play-file.d.ts +4 -61
  86. package/dist/plays/bundle-play-file.mjs +157 -155
  87. package/package.json +9 -6
  88. /package/dist/bundling-sources/shared_libs/{play-runtime → plays}/tool-response-contract.ts +0 -0
@@ -2,336 +2,250 @@
2
2
  import * as _sinclair_typebox from '@sinclair/typebox';
3
3
  import { Static } from '@sinclair/typebox';
4
4
 
5
- declare const PLAY_RUNTIME_BACKENDS: {
6
- readonly localProcess: "local_process";
7
- readonly daytona: "daytona";
8
- readonly modal: "modal";
9
- };
10
- type PlayRuntimeBackendId = (typeof PLAY_RUNTIME_BACKENDS)[keyof typeof PLAY_RUNTIME_BACKENDS];
5
+ declare const TOOL_EXECUTION_ERROR_SCHEMA_VERSION: 1;
6
+ declare const SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS: readonly [0, 1];
7
+ type ToolExecutionErrorSchemaVersion = (typeof SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS)[number];
11
8
  /**
12
- * The one executable Play artifact contract. Daytona and local-process both
13
- * load CommonJS under Node 20.
9
+ * The boundary responsible for a failed tool call.
10
+ *
11
+ * Use `provider` to distinguish a provider answer from caller input and
12
+ * Deepline infrastructure. `unknown` fails closed and must not trigger a
13
+ * waterfall fallback.
14
+ *
15
+ * @sdkReference errors 020
14
16
  */
15
- declare const PLAY_ARTIFACT_KINDS: {
16
- readonly cjsNode20: "cjs_node20";
17
+ type ToolExecutionErrorOrigin = 'caller' | 'provider' | 'deepline' | 'unknown';
18
+ /**
19
+ * The stable reason family for a failed tool call.
20
+ *
21
+ * Branch on this field only after narrowing to `ToolExecutionError`. Catch
22
+ * `ProviderTransientError` when the policy is simply “try the next read
23
+ * provider”; it is the safer and shorter waterfall contract.
24
+ *
25
+ * @sdkReference errors 030
26
+ */
27
+ type ToolExecutionErrorCategory = 'validation' | 'authentication' | 'authorization' | 'rate_limit' | 'network' | 'upstream' | 'billing' | 'conflict' | 'internal' | 'unknown';
28
+ /**
29
+ * The transport failure observed when `category` is `network`.
30
+ *
31
+ * This is `null` for failures that are not network failures.
32
+ *
33
+ * @sdkReference errors 040
34
+ */
35
+ type ToolExecutionNetworkKind = 'timeout' | 'dns' | 'connect' | 'reset' | 'unavailable' | 'unknown';
36
+ /**
37
+ * The request boundary on which a network failure occurred.
38
+ *
39
+ * `deepline_to_provider` is provider-side. Client and runtime scopes are
40
+ * Deepline transport failures and never qualify as provider fallthrough.
41
+ *
42
+ * @sdkReference errors 050
43
+ */
44
+ type ToolExecutionNetworkScope = 'client_to_deepline' | 'runtime_to_deepline' | 'deepline_to_provider';
45
+ /**
46
+ * Portable version-1 `tool_error` payload.
47
+ *
48
+ * This allowlisted shape crosses the API, runtime, and SDK boundaries.
49
+ * `message` remains on the Error object and is deliberately not a policy
50
+ * field.
51
+ *
52
+ * @sdkReference errors 064
53
+ */
54
+ type ToolExecutionFailureV1 = {
55
+ /** Payload version. */
56
+ schemaVersion: typeof TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
57
+ /** Public tool id passed to `tools.execute`. */
58
+ toolId: string;
59
+ /** Provider responsible for the operation, or `null`. */
60
+ provider: string | null;
61
+ /** Provider operation name, or `null`. */
62
+ operation: string | null;
63
+ /** Stable machine-readable failure code, or `null`. */
64
+ code: string | null;
65
+ /** Boundary responsible for the failure. */
66
+ origin: ToolExecutionErrorOrigin;
67
+ /** Stable reason family. */
68
+ category: ToolExecutionErrorCategory;
69
+ /** Whether repeating the same semantic call is delivery-safe. */
70
+ retryable: boolean;
71
+ /** HTTP status when one exists, or `null`. */
72
+ statusCode: number | null;
73
+ /** Provider or Deepline request id, or `null`. */
74
+ requestId: string | null;
75
+ /** Suggested same-call retry delay in milliseconds, or `null`. */
76
+ retryAfterMs: number | null;
77
+ /** Network failure kind, or `null`. */
78
+ networkKind: ToolExecutionNetworkKind | null;
79
+ /** Network boundary that failed, or `null`. */
80
+ networkScope: ToolExecutionNetworkScope | null;
17
81
  };
18
- type PlayArtifactKind = (typeof PLAY_ARTIFACT_KINDS)[keyof typeof PLAY_ARTIFACT_KINDS];
19
-
20
- type PlayDocflowNodeKind = 'action' | 'decision' | 'dataset' | 'play' | 'conceptual';
21
- type PlayDocflowNode = {
22
- id: string;
23
- label: string;
24
- kind: PlayDocflowNodeKind;
82
+ /**
83
+ * Constructor input for a structured tool failure.
84
+ *
85
+ * Deepline creates these values while decoding the versioned wire payload.
86
+ * Customer code normally reads `ToolExecutionError` fields instead of
87
+ * constructing an error.
88
+ *
89
+ * @sdkReference errors 065
90
+ */
91
+ type ToolExecutionErrorOptions = Omit<ToolExecutionFailureV1, 'schemaVersion'> & {
25
92
  /**
26
- * No statement in this play runs this box the author said so with
27
- * `class <id> sketch`. See {@link SKETCH_CLASS}.
28
- *
29
- * Deliberately NOT a `kind`. What a box IS (an action, a decision, a dataset)
30
- * and whether code binds it are two different questions, and folding the
31
- * second into the first was wrong in a way the tests caught immediately: a
32
- * sketched diamond stopped being a decision, so it lost its shape on the
33
- * canvas and the branch-label lint stopped checking its arms. Absent rather
34
- * than `false` when bound, so the JSON a bound diagram hashes to is byte for
35
- * byte what it was before sketches existed.
93
+ * Local diagnostic context inherited from DeeplineError. This is not part of
94
+ * the portable failure payload and is intentionally omitted by serialization.
36
95
  */
37
- sketch?: true;
96
+ details?: Record<string, unknown>;
38
97
  };
39
98
  /**
40
- * Which arm of a conditional a drawn decision edge IS.
99
+ * Provider-owned failure categories that may fall through to another read
100
+ * provider.
41
101
  *
42
- * The runtime's own two-valued vocabulary for a `runIf` (ADR 0019): the cell
43
- * record says `branch: 'run' | 'else'`, and this is the same token on the
44
- * diagram's side of the join. Deliberately NOT the arm's label — a label is the
45
- * author's prose ("fit 65 or better", "nicht gefunden") and says nothing about
46
- * polarity in any language.
102
+ * @sdkReference errors 060
47
103
  */
48
- type PlayDocflowArm = 'run' | 'else';
49
- type PlayDocflowEdge = {
50
- from: string;
51
- to: string;
52
- label?: string;
104
+ type ProviderTransientErrorCategory = 'rate_limit' | 'network' | 'upstream';
105
+ /**
106
+ * Base error class shared by the SDK and play runtime.
107
+ *
108
+ * The global brand preserves `instanceof DeeplineError` when a bundled play
109
+ * and the runtime load separate physical copies of this module.
110
+ *
111
+ * @sdkReference errors 010
112
+ */
113
+ declare class DeeplineError extends Error {
114
+ /** HTTP status when the failure crossed an HTTP boundary. */
115
+ statusCode?: number;
116
+ /** Stable machine-readable error code when one exists. */
117
+ code?: string;
118
+ /** Local diagnostic context; not a portable error contract. */
119
+ details?: Record<string, unknown>;
53
120
  /**
54
- * The conditional arm this edge is, when the author recorded it.
121
+ * Construct a Deepline error.
55
122
  *
56
- * ABSENT never `null` when unrecorded, and that is load-bearing rather
57
- * than stylistic. `docflow` is whole-object serialized into
58
- * `playStaticPipelineContractHash` (`src/lib/plays/artifact-storage.ts`),
59
- * which is part of the immutable artifact storage key, and the canonicalizer
60
- * there drops `undefined` but HASHES `null`. Emitting `arm: null` on an
61
- * unannotated edge would change the contract hash of every diagrammed play
62
- * ever published and force a republish. Omission is what keeps this additive.
123
+ * SDK and runtime code construct these errors. Application and Play code
124
+ * normally catches the public subclasses instead.
125
+ *
126
+ * @param message Human-readable failure summary.
127
+ * @param statusCode HTTP status when one exists.
128
+ * @param code Stable machine-readable code when one exists.
129
+ * @param details Local diagnostic context; never a portable error contract.
63
130
  */
64
- arm?: PlayDocflowArm;
65
- };
131
+ constructor(message: string, statusCode?: number, code?: string, details?: Record<string, unknown>);
132
+ static [Symbol.hasInstance](value: unknown): boolean;
133
+ }
66
134
  /**
67
- * A Mermaid `subgraph … end` region. When an edge connects it to a dataset
68
- * node, it models that dataset's per-row loop; its members represent the
69
- * per-row column work. See `docs/play-syntax-spec.md`. `memberIds` records the
70
- * innermost subgraph for nested regions.
135
+ * A failed `tools.execute` call with stable, allowlisted provenance.
136
+ *
137
+ * `retryable` means Deepline's delivery/idempotency contract says it is safe
138
+ * to repeat the same semantic call. It does not describe durable receipt
139
+ * repairability and does not make arbitrary side-effecting fallbacks safe.
140
+ *
141
+ * In a Play, catch `ProviderTransientError` to continue a read waterfall and
142
+ * let every other `ToolExecutionError` remain loud. In an SDK client, catch
143
+ * this base class when you need structured diagnostics for every tool failure.
144
+ *
145
+ * @sdkReference errors 070
71
146
  */
72
- type PlayDocflowSubgraph = {
73
- id: string;
74
- label: string;
75
- memberIds: string[];
76
- };
77
- type PlayDocflowBinding = {
78
- nodeId: string;
79
- line: number;
80
- label?: string;
81
- kind?: PlayDocflowNodeKind;
82
- /** Symbolic values read by this business node. Never an arbitrary JS expression. */
83
- inputs?: string[];
84
- /** Symbolic values produced or changed by this business node. */
85
- outputs?: string[];
86
- /** Whether the contract was authored, safely inferred, or still needs help. */
87
- ioConfidence?: 'explicit' | 'inferred' | 'ambiguous';
147
+ declare class ToolExecutionError extends DeeplineError {
148
+ /** Public tool id passed to `tools.execute`. */
149
+ readonly toolId: string;
150
+ /** Provider responsible for the operation, or `null` when unattributed. */
151
+ readonly provider: string | null;
152
+ /** Provider operation name, or `null` when unavailable. */
153
+ readonly operation: string | null;
154
+ /** Boundary responsible for the failure. */
155
+ readonly origin: ToolExecutionErrorOrigin;
156
+ /** Stable reason family for policy and diagnostics. */
157
+ readonly category: ToolExecutionErrorCategory;
88
158
  /**
89
- * `arm:"run"` / `arm:"else"` this node is that arm of the decision above it.
159
+ * Whether repeating the same semantic call is delivery-safe.
90
160
  *
91
- * Recorded on the annotation because the annotation is the only place the two
92
- * halves of the join meet: a `@mermaid-node` binds a DIAGRAM id to the SOURCE
93
- * statement directly beneath it, so the author writing it is the one person
94
- * who knows both which drawn arm this is and which side of the `runIf` the
95
- * code under it implements. Projected onto the incoming decision edge by
96
- * {@link attachBindingsToBlocks}; the edge is what readers resolve against.
161
+ * This does not mean the error may be ignored. Waterfall fallthrough is
162
+ * represented by `ProviderTransientError`.
97
163
  */
98
- arm?: PlayDocflowArm;
99
- };
100
- type PlayDocflow = {
101
- direction: 'LR' | 'RL' | 'TB' | 'TD' | 'BT';
102
- nodes: PlayDocflowNode[];
103
- edges: PlayDocflowEdge[];
104
- bindings: PlayDocflowBinding[];
105
- /** Authoring syntax used by the source file. */
106
- syntax?: 'mermaid';
107
- /** Normalized Mermaid text, ready to pass directly to a Mermaid renderer. */
108
- mermaidSource?: string;
164
+ readonly retryable: boolean;
165
+ /** Provider or Deepline request id, or `null` when unavailable. */
166
+ readonly requestId: string | null;
167
+ /** Suggested same-call retry delay in milliseconds, or `null`. */
168
+ readonly retryAfterMs: number | null;
169
+ /** Network failure kind, or `null` for non-network failures. */
170
+ readonly networkKind: ToolExecutionNetworkKind | null;
171
+ /** Network boundary that failed, or `null` for non-network failures. */
172
+ readonly networkScope: ToolExecutionNetworkScope | null;
109
173
  /**
110
- * Mermaid `subgraph` loop regions. Optional for persisted graphs that have
111
- * no authored regions.
174
+ * Construct a structured tool error.
175
+ *
176
+ * Deepline constructs this from the versioned `tool_error` payload.
177
+ * Application and Play code should catch it rather than create it.
112
178
  */
113
- subgraphs?: PlayDocflowSubgraph[];
114
- /** Mermaid directives accepted by the parser but not applied by React Flow. */
115
- ignoredDirectives?: string[];
116
- };
117
-
179
+ constructor(message: string, options: ToolExecutionErrorOptions);
180
+ static [Symbol.hasInstance](value: unknown): boolean;
181
+ }
118
182
  /**
119
- * A top-level key the play's function literally `return`s. Derived from the
120
- * `return { ... }` object literal NOT from dataset `.withColumn(...)` names —
121
- * so the "Returns" graph node mirrors the function's real output shape.
122
- * `isDataset` is true when the key's value is a `PlayDataset` handle (a table).
123
- */
124
- interface PlayStaticReturnField {
125
- name: string;
126
- isDataset: boolean;
127
- /**
128
- * For a dataset-valued field, the `ctx.dataset(KEY, ...)` key backing it
129
- * (e.g. `job_change_checks`) so the UI can label the return by the dataset
130
- * it actually produces instead of the bland object key (`rows`). Undefined
131
- * for non-dataset fields, `ctx.csv(...)` (no durable name), or when the key
132
- * isn't a static string literal.
133
- */
134
- datasetName?: string;
135
- }
136
- interface PlayStaticPipeline {
137
- /** Authored business flow. Static analysis is used only when this is absent. */
138
- docflow?: PlayDocflow;
139
- tableNamespace?: string;
140
- inputFields?: string[];
141
- rowKeyFields?: string[];
142
- csvArg?: string;
143
- hasInlineData?: boolean;
144
- csvDescription?: string;
145
- datasetDescription?: string;
146
- fields: string[];
147
- /**
148
- * Top-level keys of the play's `return { ... }` object literal, in source
149
- * order. Undefined when the terminal return isn't a statically-known object
150
- * literal (bare value, dataset handle, conditional returns, etc.).
151
- */
152
- returnFields?: PlayStaticReturnField[];
153
- stages?: PlayStaticSubstep[];
154
- substeps: PlayStaticSubstep[];
155
- sheetContract?: PlaySheetContract | null;
156
- sheetContractErrors?: string[];
157
- }
158
- type PlaySheetColumnSource = 'input' | 'datasetColumn' | 'waterfallStep' | 'childPlayColumn';
159
- interface PlaySheetColumnContract {
160
- id: string;
161
- sqlName: string;
162
- source: PlaySheetColumnSource;
163
- field?: string;
164
- parentField?: string;
165
- playId?: string;
166
- waterfallId?: string;
167
- outputField?: string;
168
- outputSqlName?: string;
169
- stepId?: string;
170
- toolId?: string;
171
- isRowKey?: boolean;
172
- }
173
- interface PlaySheetContract {
174
- tableNamespace: string;
175
- columns: PlaySheetColumnContract[];
176
- }
177
- type PlayStaticColumnProducerKind = 'tool' | 'waterfall' | 'stepProgram' | 'playCall' | 'controlFlow' | 'transform';
178
- interface PlayStaticColumnProducer {
179
- id: string;
180
- kind: PlayStaticColumnProducerKind;
181
- field: string;
182
- toolId?: string;
183
- playId?: string;
184
- conditional?: boolean;
185
- sourceRange?: PlayStaticSourceRange;
186
- steps?: PlayStaticColumnProducer[];
187
- substep: PlayStaticSubstep;
188
- }
189
- interface PlayStaticDatasetColumn {
190
- id: string;
191
- source: PlaySheetColumnSource;
192
- sqlName?: string;
193
- producers: PlayStaticColumnProducer[];
194
- }
195
- interface PlayStaticSourceRange {
196
- sourcePath?: string;
197
- startLine: number;
198
- endLine: number;
199
- startColumn: number;
200
- endColumn: number;
183
+ * A provider-owned transient failure that is safe to handle as an empty
184
+ * waterfall leg. Validation, auth, billing, Deepline, and unknown failures
185
+ * never satisfy this type.
186
+ *
187
+ * `retryable` remains independent: it says whether the same semantic call may
188
+ * be repeated safely. Falling through to a different read provider depends on
189
+ * this class, not on `retryable`.
190
+ *
191
+ * @sdkReference errors 080
192
+ */
193
+ declare class ProviderTransientError extends ToolExecutionError {
194
+ /** Provider attribution is guaranteed for this subtype. */
195
+ readonly origin: "provider";
196
+ /** Provider failure category that made this error eligible for fallthrough. */
197
+ readonly category: ProviderTransientErrorCategory;
198
+ /** Constructed by Deepline when a provider-owned transient failure arrives. */
199
+ constructor(message: string, options: Omit<ToolExecutionErrorOptions, 'origin' | 'category'> & {
200
+ category: ProviderTransientErrorCategory;
201
+ });
202
+ static [Symbol.hasInstance](value: unknown): boolean;
201
203
  }
202
- type PlayStaticSubstepMetadata = {
203
- conditional?: boolean;
204
- disabled?: boolean;
205
- };
204
+ /** Why a provider cannot serve the current read request. */
205
+ type ProviderUnavailableReason = ProviderTransientErrorCategory | 'account_capacity' | 'credentials_missing';
206
206
  /**
207
- * One arm of a conditional `control_flow` substep an `if`/`else if`/`else`
208
- * leg, a `switch` case, or a ternary branch. Carries its own steps so the graph
209
- * can render the conditional as a real fork instead of a flat strip.
207
+ * A provider failure that permits a read waterfall to try its next provider.
208
+ * A missing provider connection is included because another provider may still
209
+ * serve the read. Invalid credentials, caller input, and Deepline billing
210
+ * failures remain loud.
210
211
  */
211
- type PlayStaticControlFlowBranch = {
212
- /** Short arm label, e.g. `if`, `else if`, `else`, `case 'x'`, `default`. */
213
- label: string;
214
- /** The arm's condition source text, when it has one (omitted for `else`). */
215
- condition?: string;
216
- /** Static work in this arm. Empty for log/throw/return-only arms. */
217
- steps: PlayStaticSubstep[];
218
- };
219
- type PlayStaticSubstep = PlayStaticSubstepMetadata & ({
220
- type: 'csv';
221
- field: string;
222
- path?: string;
223
- description?: string;
224
- sourceRange?: PlayStaticSourceRange;
225
- callDepth?: number;
226
- callPath?: string[];
227
- } | {
228
- type: 'dataset';
229
- field: string;
230
- name?: string;
231
- tableNamespace?: string;
232
- inputFields?: string[];
233
- rowKeyFields?: string[];
234
- outputFields?: string[];
235
- columns?: PlayStaticDatasetColumn[];
236
- waterfallIds?: string[];
237
- steps?: PlayStaticSubstep[];
238
- sheetContract?: PlaySheetContract | null;
239
- /**
240
- * Columns the author declared as deliberately absent from the `@mermaid`
241
- * diagram via `.run({ undrawnColumns: [...] })`. The docflow column
242
- * coverage gate reads this; nothing about execution does.
243
- */
244
- undrawnColumns?: string[];
245
- description?: string;
246
- sourceRange?: PlayStaticSourceRange;
247
- callDepth?: number;
248
- callPath?: string[];
249
- } | {
250
- type: 'tool';
251
- toolId: string;
252
- field: string;
253
- paramsSource?: string;
254
- sourceText?: string;
255
- description?: string;
256
- inLoop?: boolean;
257
- isEventWait?: boolean;
258
- sourceRange?: PlayStaticSourceRange;
259
- callDepth?: number;
260
- callPath?: string[];
261
- } | {
262
- type: 'waterfall';
263
- tool?: string;
264
- field: string;
265
- inLoop?: boolean;
266
- id?: string;
267
- output?: string;
268
- minResults?: number;
269
- sourceText?: string;
270
- steps?: Array<{
271
- id: string;
272
- kind?: 'tool' | 'code';
273
- toolId?: string;
274
- paramsSource?: string;
275
- }>;
276
- description?: string;
277
- sourceRange?: PlayStaticSourceRange;
278
- callDepth?: number;
279
- callPath?: string[];
280
- } | {
281
- type: 'step_suite';
282
- field: string;
283
- steps: PlayStaticSubstep[];
284
- returnSource?: string;
285
- description?: string;
286
- sourceRange?: PlayStaticSourceRange;
287
- callDepth?: number;
288
- callPath?: string[];
289
- } | {
290
- type: 'play_call';
291
- playId: string;
292
- execution?: 'inline' | 'child-workflow';
293
- timeoutMs?: number;
294
- hasExplicitTimeout?: boolean;
295
- field: string;
296
- inLoop?: boolean;
297
- pipeline?: PlayStaticPipeline | null;
298
- cycleDetected?: boolean;
299
- resolutionError?: string;
300
- description?: string;
301
- sourceRange?: PlayStaticSourceRange;
302
- callDepth?: number;
303
- callPath?: string[];
304
- } | {
305
- type: 'control_flow';
306
- kind: 'conditional' | 'loop';
307
- field: string;
308
- /** Flattened steps across every arm, in source order (back-compat). */
309
- steps: PlayStaticSubstep[];
310
- /** Discriminant source text (the `if`/ternary test, `switch` subject). */
311
- condition?: string;
312
- /** Per-arm breakdown for conditionals; omitted for loops. */
313
- branches?: PlayStaticControlFlowBranch[];
314
- description?: string;
315
- sourceRange?: PlayStaticSourceRange;
316
- callDepth?: number;
317
- callPath?: string[];
318
- } | {
319
- type: 'run_javascript';
320
- alias: string;
321
- sourceText?: string;
322
- description?: string;
323
- sourceRange?: PlayStaticSourceRange;
324
- callDepth?: number;
325
- callPath?: string[];
326
- } | {
327
- type: 'code';
328
- field: string;
329
- sourceText?: string;
330
- description?: string;
331
- sourceRange?: PlayStaticSourceRange;
332
- callDepth?: number;
333
- callPath?: string[];
212
+ type ProviderUnavailableError = ProviderTransientError | (ToolExecutionError & {
213
+ readonly origin: 'provider';
214
+ readonly code: 'PROVIDER_ACCOUNT_CAPACITY';
215
+ }) | (ToolExecutionError & {
216
+ readonly origin: 'caller';
217
+ readonly code: 'INTEGRATION_CREDENTIALS_MISSING';
334
218
  });
219
+ /**
220
+ * Return the provider-specific reason a read cannot run right now.
221
+ *
222
+ * `null` means this error must stay loud: it is caller input, an invalid
223
+ * customer credential, Deepline billing, or an internal failure. A missing
224
+ * provider connection is different: an explicit read waterfall may continue
225
+ * to a configured fallback and record the unavailable leg.
226
+ */
227
+ declare function getProviderUnavailableReason(error: unknown): ProviderUnavailableReason | null;
228
+ /**
229
+ * Whether a provider cannot serve this read right now.
230
+ *
231
+ * Use this in an explicit `catch` to advance a read-only waterfall. For
232
+ * diagnostics, use `getProviderUnavailableReason(error)`.
233
+ */
234
+ declare function isProviderUnavailable(error: unknown): error is ProviderUnavailableError;
235
+ /** @deprecated Use isProviderUnavailable. */
236
+ declare const isProviderWaterfallUnavailableError: typeof isProviderUnavailable;
237
+
238
+ /**
239
+ * Public tool-response contracts shared by the API, SDK, Play bundler, and
240
+ * runtime. This is a versioned response transformation contract: a change to
241
+ * the persisted public tool-result shape must introduce a new value here and
242
+ * have newly built Play artifacts select it. Receipt-cache revisions are
243
+ * intentionally separate: ordinary response-contract changes do not refresh
244
+ * durable receipts unless the response transformation changed as well.
245
+ */
246
+ declare const V2_TOOL_RESPONSE_CONTRACT: "v2-tool-response";
247
+ declare const RAW_V2_TOOL_RESPONSE_CONTRACT: "raw-v2";
248
+ type ToolResponseContract = typeof V2_TOOL_RESPONSE_CONTRACT | typeof RAW_V2_TOOL_RESPONSE_CONTRACT;
335
249
 
336
250
  /**
337
251
  * Previous durable cell value passed to object-column resolvers.
@@ -785,239 +699,6 @@ type ToolExecuteResultAccessors<TExtracted extends Record<string, unknown> = Par
785
699
  */
786
700
  type ToolExecuteResult<TResult = unknown, TMeta = Record<string, unknown>, TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>, TLists extends Record<string, Record<string, unknown>> = Record<string, Record<string, unknown>>> = ToolExecuteResultBase<TResult, TMeta> & ToolExecuteResultAccessors<TExtracted, TLists>;
787
701
 
788
- declare const TOOL_EXECUTION_ERROR_SCHEMA_VERSION: 1;
789
- declare const SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS: readonly [0, 1];
790
- type ToolExecutionErrorSchemaVersion = (typeof SUPPORTED_TOOL_EXECUTION_ERROR_SCHEMA_VERSIONS)[number];
791
- /**
792
- * The boundary responsible for a failed tool call.
793
- *
794
- * Use `provider` to distinguish a provider answer from caller input and
795
- * Deepline infrastructure. `unknown` fails closed and must not trigger a
796
- * waterfall fallback.
797
- *
798
- * @sdkReference errors 020
799
- */
800
- type ToolExecutionErrorOrigin = 'caller' | 'provider' | 'deepline' | 'unknown';
801
- /**
802
- * The stable reason family for a failed tool call.
803
- *
804
- * Branch on this field only after narrowing to `ToolExecutionError`. Catch
805
- * `ProviderTransientError` when the policy is simply “try the next read
806
- * provider”; it is the safer and shorter waterfall contract.
807
- *
808
- * @sdkReference errors 030
809
- */
810
- type ToolExecutionErrorCategory = 'validation' | 'authentication' | 'authorization' | 'rate_limit' | 'network' | 'upstream' | 'billing' | 'conflict' | 'internal' | 'unknown';
811
- /**
812
- * The transport failure observed when `category` is `network`.
813
- *
814
- * This is `null` for failures that are not network failures.
815
- *
816
- * @sdkReference errors 040
817
- */
818
- type ToolExecutionNetworkKind = 'timeout' | 'dns' | 'connect' | 'reset' | 'unavailable' | 'unknown';
819
- /**
820
- * The request boundary on which a network failure occurred.
821
- *
822
- * `deepline_to_provider` is provider-side. Client and runtime scopes are
823
- * Deepline transport failures and never qualify as provider fallthrough.
824
- *
825
- * @sdkReference errors 050
826
- */
827
- type ToolExecutionNetworkScope = 'client_to_deepline' | 'runtime_to_deepline' | 'deepline_to_provider';
828
- /**
829
- * Portable version-1 `tool_error` payload.
830
- *
831
- * This allowlisted shape crosses the API, runtime, and SDK boundaries.
832
- * `message` remains on the Error object and is deliberately not a policy
833
- * field.
834
- *
835
- * @sdkReference errors 064
836
- */
837
- type ToolExecutionFailureV1 = {
838
- /** Payload version. */
839
- schemaVersion: typeof TOOL_EXECUTION_ERROR_SCHEMA_VERSION;
840
- /** Public tool id passed to `tools.execute`. */
841
- toolId: string;
842
- /** Provider responsible for the operation, or `null`. */
843
- provider: string | null;
844
- /** Provider operation name, or `null`. */
845
- operation: string | null;
846
- /** Stable machine-readable failure code, or `null`. */
847
- code: string | null;
848
- /** Boundary responsible for the failure. */
849
- origin: ToolExecutionErrorOrigin;
850
- /** Stable reason family. */
851
- category: ToolExecutionErrorCategory;
852
- /** Whether repeating the same semantic call is delivery-safe. */
853
- retryable: boolean;
854
- /** HTTP status when one exists, or `null`. */
855
- statusCode: number | null;
856
- /** Provider or Deepline request id, or `null`. */
857
- requestId: string | null;
858
- /** Suggested same-call retry delay in milliseconds, or `null`. */
859
- retryAfterMs: number | null;
860
- /** Network failure kind, or `null`. */
861
- networkKind: ToolExecutionNetworkKind | null;
862
- /** Network boundary that failed, or `null`. */
863
- networkScope: ToolExecutionNetworkScope | null;
864
- };
865
- /**
866
- * Constructor input for a structured tool failure.
867
- *
868
- * Deepline creates these values while decoding the versioned wire payload.
869
- * Customer code normally reads `ToolExecutionError` fields instead of
870
- * constructing an error.
871
- *
872
- * @sdkReference errors 065
873
- */
874
- type ToolExecutionErrorOptions = Omit<ToolExecutionFailureV1, 'schemaVersion'> & {
875
- /**
876
- * Local diagnostic context inherited from DeeplineError. This is not part of
877
- * the portable failure payload and is intentionally omitted by serialization.
878
- */
879
- details?: Record<string, unknown>;
880
- };
881
- /**
882
- * Provider-owned failure categories that may fall through to another read
883
- * provider.
884
- *
885
- * @sdkReference errors 060
886
- */
887
- type ProviderTransientErrorCategory = 'rate_limit' | 'network' | 'upstream';
888
- /**
889
- * Base error class shared by the SDK and play runtime.
890
- *
891
- * The global brand preserves `instanceof DeeplineError` when a bundled play
892
- * and the runtime load separate physical copies of this module.
893
- *
894
- * @sdkReference errors 010
895
- */
896
- declare class DeeplineError extends Error {
897
- /** HTTP status when the failure crossed an HTTP boundary. */
898
- statusCode?: number;
899
- /** Stable machine-readable error code when one exists. */
900
- code?: string;
901
- /** Local diagnostic context; not a portable error contract. */
902
- details?: Record<string, unknown>;
903
- /**
904
- * Construct a Deepline error.
905
- *
906
- * SDK and runtime code construct these errors. Application and Play code
907
- * normally catches the public subclasses instead.
908
- *
909
- * @param message Human-readable failure summary.
910
- * @param statusCode HTTP status when one exists.
911
- * @param code Stable machine-readable code when one exists.
912
- * @param details Local diagnostic context; never a portable error contract.
913
- */
914
- constructor(message: string, statusCode?: number, code?: string, details?: Record<string, unknown>);
915
- static [Symbol.hasInstance](value: unknown): boolean;
916
- }
917
- /**
918
- * A failed `tools.execute` call with stable, allowlisted provenance.
919
- *
920
- * `retryable` means Deepline's delivery/idempotency contract says it is safe
921
- * to repeat the same semantic call. It does not describe durable receipt
922
- * repairability and does not make arbitrary side-effecting fallbacks safe.
923
- *
924
- * In a Play, catch `ProviderTransientError` to continue a read waterfall and
925
- * let every other `ToolExecutionError` remain loud. In an SDK client, catch
926
- * this base class when you need structured diagnostics for every tool failure.
927
- *
928
- * @sdkReference errors 070
929
- */
930
- declare class ToolExecutionError extends DeeplineError {
931
- /** Public tool id passed to `tools.execute`. */
932
- readonly toolId: string;
933
- /** Provider responsible for the operation, or `null` when unattributed. */
934
- readonly provider: string | null;
935
- /** Provider operation name, or `null` when unavailable. */
936
- readonly operation: string | null;
937
- /** Boundary responsible for the failure. */
938
- readonly origin: ToolExecutionErrorOrigin;
939
- /** Stable reason family for policy and diagnostics. */
940
- readonly category: ToolExecutionErrorCategory;
941
- /**
942
- * Whether repeating the same semantic call is delivery-safe.
943
- *
944
- * This does not mean the error may be ignored. Waterfall fallthrough is
945
- * represented by `ProviderTransientError`.
946
- */
947
- readonly retryable: boolean;
948
- /** Provider or Deepline request id, or `null` when unavailable. */
949
- readonly requestId: string | null;
950
- /** Suggested same-call retry delay in milliseconds, or `null`. */
951
- readonly retryAfterMs: number | null;
952
- /** Network failure kind, or `null` for non-network failures. */
953
- readonly networkKind: ToolExecutionNetworkKind | null;
954
- /** Network boundary that failed, or `null` for non-network failures. */
955
- readonly networkScope: ToolExecutionNetworkScope | null;
956
- /**
957
- * Construct a structured tool error.
958
- *
959
- * Deepline constructs this from the versioned `tool_error` payload.
960
- * Application and Play code should catch it rather than create it.
961
- */
962
- constructor(message: string, options: ToolExecutionErrorOptions);
963
- static [Symbol.hasInstance](value: unknown): boolean;
964
- }
965
- /**
966
- * A provider-owned transient failure that is safe to handle as an empty
967
- * waterfall leg. Validation, auth, billing, Deepline, and unknown failures
968
- * never satisfy this type.
969
- *
970
- * `retryable` remains independent: it says whether the same semantic call may
971
- * be repeated safely. Falling through to a different read provider depends on
972
- * this class, not on `retryable`.
973
- *
974
- * @sdkReference errors 080
975
- */
976
- declare class ProviderTransientError extends ToolExecutionError {
977
- /** Provider attribution is guaranteed for this subtype. */
978
- readonly origin: "provider";
979
- /** Provider failure category that made this error eligible for fallthrough. */
980
- readonly category: ProviderTransientErrorCategory;
981
- /** Constructed by Deepline when a provider-owned transient failure arrives. */
982
- constructor(message: string, options: Omit<ToolExecutionErrorOptions, 'origin' | 'category'> & {
983
- category: ProviderTransientErrorCategory;
984
- });
985
- static [Symbol.hasInstance](value: unknown): boolean;
986
- }
987
- /** Why a provider cannot serve the current read request. */
988
- type ProviderUnavailableReason = ProviderTransientErrorCategory | 'account_capacity' | 'credentials_missing';
989
- /**
990
- * A provider failure that permits a read waterfall to try its next provider.
991
- * A missing provider connection is included because another provider may still
992
- * serve the read. Invalid credentials, caller input, and Deepline billing
993
- * failures remain loud.
994
- */
995
- type ProviderUnavailableError = ProviderTransientError | (ToolExecutionError & {
996
- readonly origin: 'provider';
997
- readonly code: 'PROVIDER_ACCOUNT_CAPACITY';
998
- }) | (ToolExecutionError & {
999
- readonly origin: 'caller';
1000
- readonly code: 'INTEGRATION_CREDENTIALS_MISSING';
1001
- });
1002
- /**
1003
- * Return the provider-specific reason a read cannot run right now.
1004
- *
1005
- * `null` means this error must stay loud: it is caller input, an invalid
1006
- * customer credential, Deepline billing, or an internal failure. A missing
1007
- * provider connection is different: an explicit read waterfall may continue
1008
- * to a configured fallback and record the unavailable leg.
1009
- */
1010
- declare function getProviderUnavailableReason(error: unknown): ProviderUnavailableReason | null;
1011
- /**
1012
- * Whether a provider cannot serve this read right now.
1013
- *
1014
- * Use this in an explicit `catch` to advance a read-only waterfall. For
1015
- * diagnostics, use `getProviderUnavailableReason(error)`.
1016
- */
1017
- declare function isProviderUnavailable(error: unknown): error is ProviderUnavailableError;
1018
- /** @deprecated Use isProviderUnavailable. */
1019
- declare const isProviderWaterfallUnavailableError: typeof isProviderUnavailable;
1020
-
1021
702
  declare const SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS: readonly [1, 2, 3, 4];
1022
703
  type PlayAuthoringContractEdition = (typeof SUPPORTED_PLAY_AUTHORING_CONTRACT_EDITIONS)[number];
1023
704
  type PlaySqlListenerOperation = 'INSERT' | 'UPDATE' | 'DELETE';
@@ -2863,6 +2544,370 @@ type DurableCallStaleAfterSeconds = Static<(typeof PLAY_AUTHORING_FIELD_REGISTRY
2863
2544
  type PlayRuntimeTimeoutMs = number;
2864
2545
  type PlayReceiptWaitMs = number;
2865
2546
 
2547
+ type PlayPackageImport = {
2548
+ name: string;
2549
+ version: string | null;
2550
+ };
2551
+ type PlayImportPolicy = {
2552
+ localFiles: string[];
2553
+ nodeBuiltins: string[];
2554
+ packages: PlayPackageImport[];
2555
+ };
2556
+ type PlayRuntimeFeature = 'artifact_storage' | 'checkpoint_resume' | 'durable_sleep' | 'packaged_files';
2557
+ type PlayArtifactCompatibility = {
2558
+ apiVersion: number;
2559
+ artifactVersion: number;
2560
+ minRunnerVersion: number;
2561
+ runtimeFeatures: PlayRuntimeFeature[];
2562
+ runtimeBackend?: string | null;
2563
+ /** Missing preserves the legacy schema used before this field existed. */
2564
+ toolErrorSchemaVersion?: ToolExecutionErrorSchemaVersion;
2565
+ /** Missing preserves edition 1 for artifacts created before authoring contracts were pinned. */
2566
+ authoringContractEdition?: PlayAuthoringContractEdition;
2567
+ /** Missing preserves the raw-only V2 execute response contract. */
2568
+ toolResponseContract?: ToolResponseContract;
2569
+ /** Missing preserves the receipt namespace of artifacts created before this revision existed. */
2570
+ toolResponseReceiptRevision?: string;
2571
+ };
2572
+ /** The only executable Play artifact contract. */
2573
+ declare const PLAY_ARTIFACT_KINDS: {
2574
+ readonly cjsNode20: "cjs_node20";
2575
+ };
2576
+ type PlayArtifactKind = (typeof PLAY_ARTIFACT_KINDS)[keyof typeof PLAY_ARTIFACT_KINDS];
2577
+ type PlayBundleArtifact = {
2578
+ codeFormat: 'cjs_module';
2579
+ /** Defaults to cjs_node20 when not present on legacy Node artifacts. */
2580
+ artifactKind?: PlayArtifactKind;
2581
+ entryFile: string;
2582
+ virtualFilename: string;
2583
+ sourceHash: string;
2584
+ graphHash: string;
2585
+ artifactHash: string;
2586
+ sourceMapHash: string;
2587
+ bundledCode: string;
2588
+ sourceMap: string;
2589
+ importPolicy: PlayImportPolicy;
2590
+ compatibility: PlayArtifactCompatibility;
2591
+ generatedAt: number;
2592
+ cacheHit: boolean;
2593
+ };
2594
+
2595
+ type PlayDocflowNodeKind = 'action' | 'decision' | 'dataset' | 'play' | 'conceptual';
2596
+ type PlayDocflowNode = {
2597
+ id: string;
2598
+ label: string;
2599
+ kind: PlayDocflowNodeKind;
2600
+ /**
2601
+ * No statement in this play runs this box — the author said so with
2602
+ * `class <id> sketch`. See {@link SKETCH_CLASS}.
2603
+ *
2604
+ * Deliberately NOT a `kind`. What a box IS (an action, a decision, a dataset)
2605
+ * and whether code binds it are two different questions, and folding the
2606
+ * second into the first was wrong in a way the tests caught immediately: a
2607
+ * sketched diamond stopped being a decision, so it lost its shape on the
2608
+ * canvas and the branch-label lint stopped checking its arms. Absent rather
2609
+ * than `false` when bound, so the JSON a bound diagram hashes to is byte for
2610
+ * byte what it was before sketches existed.
2611
+ */
2612
+ sketch?: true;
2613
+ };
2614
+ /**
2615
+ * Which arm of a conditional a drawn decision edge IS.
2616
+ *
2617
+ * The runtime's own two-valued vocabulary for a `runIf` (ADR 0019): the cell
2618
+ * record says `branch: 'run' | 'else'`, and this is the same token on the
2619
+ * diagram's side of the join. Deliberately NOT the arm's label — a label is the
2620
+ * author's prose ("fit 65 or better", "nicht gefunden") and says nothing about
2621
+ * polarity in any language.
2622
+ */
2623
+ type PlayDocflowArm = 'run' | 'else';
2624
+ type PlayDocflowEdge = {
2625
+ from: string;
2626
+ to: string;
2627
+ label?: string;
2628
+ /**
2629
+ * The conditional arm this edge is, when the author recorded it.
2630
+ *
2631
+ * ABSENT — never `null` — when unrecorded, and that is load-bearing rather
2632
+ * than stylistic. `docflow` is whole-object serialized into
2633
+ * `playStaticPipelineContractHash` (`src/lib/plays/artifact-storage.ts`),
2634
+ * which is part of the immutable artifact storage key, and the canonicalizer
2635
+ * there drops `undefined` but HASHES `null`. Emitting `arm: null` on an
2636
+ * unannotated edge would change the contract hash of every diagrammed play
2637
+ * ever published and force a republish. Omission is what keeps this additive.
2638
+ */
2639
+ arm?: PlayDocflowArm;
2640
+ };
2641
+ /**
2642
+ * A Mermaid `subgraph … end` region. When an edge connects it to a dataset
2643
+ * node, it models that dataset's per-row loop; its members represent the
2644
+ * per-row column work. See `docs/play-syntax-spec.md`. `memberIds` records the
2645
+ * innermost subgraph for nested regions.
2646
+ */
2647
+ type PlayDocflowSubgraph = {
2648
+ id: string;
2649
+ label: string;
2650
+ memberIds: string[];
2651
+ };
2652
+ type PlayDocflowBinding = {
2653
+ nodeId: string;
2654
+ line: number;
2655
+ label?: string;
2656
+ kind?: PlayDocflowNodeKind;
2657
+ /** Symbolic values read by this business node. Never an arbitrary JS expression. */
2658
+ inputs?: string[];
2659
+ /** Symbolic values produced or changed by this business node. */
2660
+ outputs?: string[];
2661
+ /** Whether the contract was authored, safely inferred, or still needs help. */
2662
+ ioConfidence?: 'explicit' | 'inferred' | 'ambiguous';
2663
+ /**
2664
+ * `arm:"run"` / `arm:"else"` — this node is that arm of the decision above it.
2665
+ *
2666
+ * Recorded on the annotation because the annotation is the only place the two
2667
+ * halves of the join meet: a `@mermaid-node` binds a DIAGRAM id to the SOURCE
2668
+ * statement directly beneath it, so the author writing it is the one person
2669
+ * who knows both which drawn arm this is and which side of the `runIf` the
2670
+ * code under it implements. Projected onto the incoming decision edge by
2671
+ * {@link attachBindingsToBlocks}; the edge is what readers resolve against.
2672
+ */
2673
+ arm?: PlayDocflowArm;
2674
+ };
2675
+ type PlayDocflow = {
2676
+ direction: 'LR' | 'RL' | 'TB' | 'TD' | 'BT';
2677
+ nodes: PlayDocflowNode[];
2678
+ edges: PlayDocflowEdge[];
2679
+ bindings: PlayDocflowBinding[];
2680
+ /** Authoring syntax used by the source file. */
2681
+ syntax?: 'mermaid';
2682
+ /** Normalized Mermaid text, ready to pass directly to a Mermaid renderer. */
2683
+ mermaidSource?: string;
2684
+ /**
2685
+ * Mermaid `subgraph` loop regions. Optional for persisted graphs that have
2686
+ * no authored regions.
2687
+ */
2688
+ subgraphs?: PlayDocflowSubgraph[];
2689
+ /** Mermaid directives accepted by the parser but not applied by React Flow. */
2690
+ ignoredDirectives?: string[];
2691
+ };
2692
+
2693
+ /**
2694
+ * A top-level key the play's function literally `return`s. Derived from the
2695
+ * `return { ... }` object literal — NOT from dataset `.withColumn(...)` names —
2696
+ * so the "Returns" graph node mirrors the function's real output shape.
2697
+ * `isDataset` is true when the key's value is a `PlayDataset` handle (a table).
2698
+ */
2699
+ interface PlayStaticReturnField {
2700
+ name: string;
2701
+ isDataset: boolean;
2702
+ /**
2703
+ * For a dataset-valued field, the `ctx.dataset(KEY, ...)` key backing it
2704
+ * (e.g. `job_change_checks`) — so the UI can label the return by the dataset
2705
+ * it actually produces instead of the bland object key (`rows`). Undefined
2706
+ * for non-dataset fields, `ctx.csv(...)` (no durable name), or when the key
2707
+ * isn't a static string literal.
2708
+ */
2709
+ datasetName?: string;
2710
+ }
2711
+ interface PlayStaticPipeline {
2712
+ /** Authored business flow. Static analysis is used only when this is absent. */
2713
+ docflow?: PlayDocflow;
2714
+ tableNamespace?: string;
2715
+ inputFields?: string[];
2716
+ rowKeyFields?: string[];
2717
+ csvArg?: string;
2718
+ hasInlineData?: boolean;
2719
+ csvDescription?: string;
2720
+ datasetDescription?: string;
2721
+ fields: string[];
2722
+ /**
2723
+ * Top-level keys of the play's `return { ... }` object literal, in source
2724
+ * order. Undefined when the terminal return isn't a statically-known object
2725
+ * literal (bare value, dataset handle, conditional returns, etc.).
2726
+ */
2727
+ returnFields?: PlayStaticReturnField[];
2728
+ stages?: PlayStaticSubstep[];
2729
+ substeps: PlayStaticSubstep[];
2730
+ sheetContract?: PlaySheetContract | null;
2731
+ sheetContractErrors?: string[];
2732
+ }
2733
+ type PlaySheetColumnSource = 'input' | 'datasetColumn' | 'waterfallStep' | 'childPlayColumn';
2734
+ interface PlaySheetColumnContract {
2735
+ id: string;
2736
+ sqlName: string;
2737
+ source: PlaySheetColumnSource;
2738
+ field?: string;
2739
+ parentField?: string;
2740
+ playId?: string;
2741
+ waterfallId?: string;
2742
+ outputField?: string;
2743
+ outputSqlName?: string;
2744
+ stepId?: string;
2745
+ toolId?: string;
2746
+ isRowKey?: boolean;
2747
+ }
2748
+ interface PlaySheetContract {
2749
+ tableNamespace: string;
2750
+ columns: PlaySheetColumnContract[];
2751
+ }
2752
+ type PlayStaticColumnProducerKind = 'tool' | 'waterfall' | 'stepProgram' | 'playCall' | 'controlFlow' | 'transform';
2753
+ interface PlayStaticColumnProducer {
2754
+ id: string;
2755
+ kind: PlayStaticColumnProducerKind;
2756
+ field: string;
2757
+ toolId?: string;
2758
+ playId?: string;
2759
+ conditional?: boolean;
2760
+ sourceRange?: PlayStaticSourceRange;
2761
+ steps?: PlayStaticColumnProducer[];
2762
+ substep: PlayStaticSubstep;
2763
+ }
2764
+ interface PlayStaticDatasetColumn {
2765
+ id: string;
2766
+ source: PlaySheetColumnSource;
2767
+ sqlName?: string;
2768
+ producers: PlayStaticColumnProducer[];
2769
+ }
2770
+ interface PlayStaticSourceRange {
2771
+ sourcePath?: string;
2772
+ startLine: number;
2773
+ endLine: number;
2774
+ startColumn: number;
2775
+ endColumn: number;
2776
+ }
2777
+ type PlayStaticSubstepMetadata = {
2778
+ conditional?: boolean;
2779
+ disabled?: boolean;
2780
+ };
2781
+ /**
2782
+ * One arm of a conditional `control_flow` substep — an `if`/`else if`/`else`
2783
+ * leg, a `switch` case, or a ternary branch. Carries its own steps so the graph
2784
+ * can render the conditional as a real fork instead of a flat strip.
2785
+ */
2786
+ type PlayStaticControlFlowBranch = {
2787
+ /** Short arm label, e.g. `if`, `else if`, `else`, `case 'x'`, `default`. */
2788
+ label: string;
2789
+ /** The arm's condition source text, when it has one (omitted for `else`). */
2790
+ condition?: string;
2791
+ /** Static work in this arm. Empty for log/throw/return-only arms. */
2792
+ steps: PlayStaticSubstep[];
2793
+ };
2794
+ type PlayStaticSubstep = PlayStaticSubstepMetadata & ({
2795
+ type: 'csv';
2796
+ field: string;
2797
+ path?: string;
2798
+ description?: string;
2799
+ sourceRange?: PlayStaticSourceRange;
2800
+ callDepth?: number;
2801
+ callPath?: string[];
2802
+ } | {
2803
+ type: 'dataset';
2804
+ field: string;
2805
+ name?: string;
2806
+ tableNamespace?: string;
2807
+ inputFields?: string[];
2808
+ rowKeyFields?: string[];
2809
+ outputFields?: string[];
2810
+ columns?: PlayStaticDatasetColumn[];
2811
+ waterfallIds?: string[];
2812
+ steps?: PlayStaticSubstep[];
2813
+ sheetContract?: PlaySheetContract | null;
2814
+ /**
2815
+ * Columns the author declared as deliberately absent from the `@mermaid`
2816
+ * diagram via `.run({ undrawnColumns: [...] })`. The docflow column
2817
+ * coverage gate reads this; nothing about execution does.
2818
+ */
2819
+ undrawnColumns?: string[];
2820
+ description?: string;
2821
+ sourceRange?: PlayStaticSourceRange;
2822
+ callDepth?: number;
2823
+ callPath?: string[];
2824
+ } | {
2825
+ type: 'tool';
2826
+ toolId: string;
2827
+ field: string;
2828
+ paramsSource?: string;
2829
+ sourceText?: string;
2830
+ description?: string;
2831
+ inLoop?: boolean;
2832
+ isEventWait?: boolean;
2833
+ sourceRange?: PlayStaticSourceRange;
2834
+ callDepth?: number;
2835
+ callPath?: string[];
2836
+ } | {
2837
+ type: 'waterfall';
2838
+ tool?: string;
2839
+ field: string;
2840
+ inLoop?: boolean;
2841
+ id?: string;
2842
+ output?: string;
2843
+ minResults?: number;
2844
+ sourceText?: string;
2845
+ steps?: Array<{
2846
+ id: string;
2847
+ kind?: 'tool' | 'code';
2848
+ toolId?: string;
2849
+ paramsSource?: string;
2850
+ }>;
2851
+ description?: string;
2852
+ sourceRange?: PlayStaticSourceRange;
2853
+ callDepth?: number;
2854
+ callPath?: string[];
2855
+ } | {
2856
+ type: 'step_suite';
2857
+ field: string;
2858
+ steps: PlayStaticSubstep[];
2859
+ returnSource?: string;
2860
+ description?: string;
2861
+ sourceRange?: PlayStaticSourceRange;
2862
+ callDepth?: number;
2863
+ callPath?: string[];
2864
+ } | {
2865
+ type: 'play_call';
2866
+ playId: string;
2867
+ execution?: 'inline' | 'child-workflow';
2868
+ timeoutMs?: number;
2869
+ hasExplicitTimeout?: boolean;
2870
+ field: string;
2871
+ inLoop?: boolean;
2872
+ pipeline?: PlayStaticPipeline | null;
2873
+ cycleDetected?: boolean;
2874
+ resolutionError?: string;
2875
+ description?: string;
2876
+ sourceRange?: PlayStaticSourceRange;
2877
+ callDepth?: number;
2878
+ callPath?: string[];
2879
+ } | {
2880
+ type: 'control_flow';
2881
+ kind: 'conditional' | 'loop';
2882
+ field: string;
2883
+ /** Flattened steps across every arm, in source order (back-compat). */
2884
+ steps: PlayStaticSubstep[];
2885
+ /** Discriminant source text (the `if`/ternary test, `switch` subject). */
2886
+ condition?: string;
2887
+ /** Per-arm breakdown for conditionals; omitted for loops. */
2888
+ branches?: PlayStaticControlFlowBranch[];
2889
+ description?: string;
2890
+ sourceRange?: PlayStaticSourceRange;
2891
+ callDepth?: number;
2892
+ callPath?: string[];
2893
+ } | {
2894
+ type: 'run_javascript';
2895
+ alias: string;
2896
+ sourceText?: string;
2897
+ description?: string;
2898
+ sourceRange?: PlayStaticSourceRange;
2899
+ callDepth?: number;
2900
+ callPath?: string[];
2901
+ } | {
2902
+ type: 'code';
2903
+ field: string;
2904
+ sourceText?: string;
2905
+ description?: string;
2906
+ sourceRange?: PlayStaticSourceRange;
2907
+ callDepth?: number;
2908
+ callPath?: string[];
2909
+ });
2910
+
2866
2911
  type PlayCompilerDependencyManifest = {
2867
2912
  playName: string;
2868
2913
  /** Original source path for direct imported definePlay dependencies. */
@@ -2896,4 +2941,4 @@ type PlayCompilerManifest = {
2896
2941
  authoringContract?: AdmittedPlayAuthoringContract;
2897
2942
  };
2898
2943
 
2899
- export { type PlayDataset as $, type PlayAuthoringFetchResponse as A, type PlayAuthoringInputContract as B, type PlayAuthoringStepProgramStep as C, DeeplineError as D, type PlayAuthoringRuntimeStepOptions as E, type PlaySqlListenerDeclaration as F, type PlaySqlListenerEvent as G, type PlaySqlListenerOperation as H, type PlaySqlQuery as I, type PlayAuthoringStepOptions as J, type PlayAuthoringStepProgram as K, type PlayAuthoringStepProgramResolver as L, type PlayAuthoringStepResolver as M, type PlayToolExecutionRequest as N, type PlayAuthoringStepProgramOptions as O, type PlayAuthoringContractEdition as P, DEEPLINE_EXTRACTOR_TARGETS as Q, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS as R, type DeeplineEmailStatusGetterValue as S, type ToolExecutionErrorSchemaVersion as T, type DeeplineExtractorTarget as U, type DeeplineGetterValue as V, type DeeplineGetterValueMap as W, JOB_CHANGE_STATUS_VALUES as X, type JobChangeStatus as Y, PHONE_STATUS_VALUES as Z, type PhoneStatus as _, type PlayArtifactKind as a, type PlayDatasetInput as a0, type PreviousCell as a1, ProviderTransientError as a2, type ProviderTransientErrorCategory as a3, type ProviderUnavailableError as a4, type ProviderUnavailableReason as a5, type ToolExecutionErrorCategory as a6, type ToolExecutionErrorOrigin as a7, type ToolExecutionFailureV1 as a8, type ToolExecutionNetworkKind as a9, type ToolExecutionNetworkScope as aa, getProviderUnavailableReason as ab, isDeeplineExtractorTarget as ac, isProviderUnavailable as ad, isProviderWaterfallUnavailableError as ae, type PlaySandboxRuntimeDeclaration as b, type PlayCompilerManifest as c, PLAY_ARTIFACT_KINDS as d, type PlayRuntimeBackendId as e, ToolExecutionError as f, type ToolExecutionErrorOptions as g, type PlayAuthoringColumnMap as h, type PlayAuthoringColumnResolver as i, type PlayAuthoringRuntimeContext as j, type PlayAuthoringConditionalStepResolver as k, type PlayAuthoringCsvInput as l, type PlayAuthoringCsvOptions as m, type PlayAuthoringDatasetBuilder as n, type PlayAuthoringDatasetColumnDefinition as o, type PlayAuthoringDatasetColumnRunInput as p, type ToolExecuteResult as q, type PlayAuthoringReferenceLike as r, type PlayReturnObject as s, type PlayAuthoringDefineConfig as t, type PlayAuthoringDefinedPlay as u, type PlayAuthoringFetchOptions as v, type PlayAuthoringFileInput as w, type PlayAuthoringBindings as x, type PlayAuthoringCallExecution as y, type PlayAuthoringCallOptions as z };
2944
+ export { PHONE_STATUS_VALUES as $, type PlayAuthoringCallExecution as A, type PlayAuthoringCallOptions as B, type PlayAuthoringFetchResponse as C, DeeplineError as D, type PlayAuthoringInputContract as E, type PlayAuthoringStepProgramStep as F, type PlayAuthoringRuntimeStepOptions as G, type PlaySqlListenerDeclaration as H, type PlaySqlListenerEvent as I, type PlaySqlListenerOperation as J, type PlaySqlQuery as K, type PlayAuthoringStepOptions as L, type PlayAuthoringStepProgram as M, type PlayAuthoringStepProgramResolver as N, type PlayAuthoringStepResolver as O, type PlayArtifactKind as P, type PlayToolExecutionRequest as Q, type PlayAuthoringStepProgramOptions as R, DEEPLINE_EXTRACTOR_TARGETS as S, ToolExecutionError as T, DEEPLINE_EXTRACTOR_TARGET_DEFINITIONS as U, type DeeplineEmailStatusGetterValue as V, type DeeplineExtractorTarget as W, type DeeplineGetterValue as X, type DeeplineGetterValueMap as Y, JOB_CHANGE_STATUS_VALUES as Z, type JobChangeStatus as _, type PlayBundleArtifact as a, type PhoneStatus as a0, type PlayDataset as a1, type PlayDatasetInput as a2, type PreviousCell as a3, ProviderTransientError as a4, type ProviderTransientErrorCategory as a5, type ProviderUnavailableError as a6, type ProviderUnavailableReason as a7, type ToolExecutionErrorCategory as a8, type ToolExecutionErrorOrigin as a9, type ToolExecutionFailureV1 as aa, type ToolExecutionNetworkKind as ab, type ToolExecutionNetworkScope as ac, getProviderUnavailableReason as ad, isDeeplineExtractorTarget as ae, isProviderUnavailable as af, isProviderWaterfallUnavailableError as ag, type PlaySandboxRuntimeDeclaration as b, type PlayCompilerManifest as c, PLAY_ARTIFACT_KINDS as d, type PlayArtifactCompatibility as e, type PlayImportPolicy as f, type PlayPackageImport as g, type PlayRuntimeFeature as h, type ToolExecutionErrorOptions as i, type PlayAuthoringColumnMap as j, type PlayAuthoringColumnResolver as k, type PlayAuthoringRuntimeContext as l, type PlayAuthoringConditionalStepResolver as m, type PlayAuthoringCsvInput as n, type PlayAuthoringCsvOptions as o, type PlayAuthoringDatasetBuilder as p, type PlayAuthoringDatasetColumnDefinition as q, type PlayAuthoringDatasetColumnRunInput as r, type ToolExecuteResult as s, type PlayAuthoringReferenceLike as t, type PlayReturnObject as u, type PlayAuthoringDefineConfig as v, type PlayAuthoringDefinedPlay as w, type PlayAuthoringFetchOptions as x, type PlayAuthoringFileInput as y, type PlayAuthoringBindings as z };