@onereach/state-machine-contracts 0.0.0-stage → 1.0.0-framework.12
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.
- package/README.md +455 -2
- package/dist/index.d.mts +741 -0
- package/dist/index.d.mts.map +1 -0
- package/dist/index.mjs +14 -0
- package/dist/index.mjs.map +1 -0
- package/dist/json-schemas/CreateStateMachineInstanceRequestSchema.json +64 -0
- package/dist/json-schemas/CreateStateMachineTemplateSchema.json +203 -0
- package/dist/json-schemas/ExecuteStateMachineFunctionRequestSchema.json +38 -0
- package/dist/json-schemas/FunctionImplementationSchema.json +55 -0
- package/dist/json-schemas/FunctionKindSchema.json +8 -0
- package/dist/json-schemas/JsonSchemaSchema.json +7 -0
- package/dist/json-schemas/ObjectJsonSchemaSchema.json +16 -0
- package/dist/json-schemas/StateMachineFunctionDefinitionSchema.json +140 -0
- package/dist/json-schemas/StateMachineInstanceSchema.json +99 -0
- package/dist/json-schemas/StateMachineTemplateBindingSchema.json +26 -0
- package/dist/json-schemas/StateMachineTemplateSchema.json +203 -0
- package/dist/schemas/index.d.mts +732 -0
- package/dist/schemas/index.d.mts.map +1 -0
- package/dist/schemas/index.mjs +2 -0
- package/dist/schemas/index.mjs.map +1 -0
- package/package.json +59 -3
package/dist/index.d.mts
ADDED
|
@@ -0,0 +1,741 @@
|
|
|
1
|
+
import { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
|
|
2
|
+
//#region src/contracts/types.d.ts
|
|
3
|
+
interface ContractIssue {
|
|
4
|
+
/**
|
|
5
|
+
* JSON Pointer to the invalid value; an empty string identifies the root.
|
|
6
|
+
*/
|
|
7
|
+
path: string;
|
|
8
|
+
message: string;
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* Canonical contract diagnostic at the Standard Schema boundary.
|
|
12
|
+
* Paths use decoded string segments.
|
|
13
|
+
*/
|
|
14
|
+
interface StandardContractIssue extends StandardSchemaV1.Issue {
|
|
15
|
+
readonly path: readonly string[];
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Synchronous contract validation result, compatible with Standard Schema v1.
|
|
19
|
+
*/
|
|
20
|
+
type StandardContractResult<T> = StandardSchemaV1.SuccessResult<T> | {
|
|
21
|
+
readonly issues: readonly StandardContractIssue[];
|
|
22
|
+
};
|
|
23
|
+
//#endregion
|
|
24
|
+
//#region src/contracts/contract.d.ts
|
|
25
|
+
declare class ContractValidationError extends Error {
|
|
26
|
+
readonly issues: readonly ContractIssue[];
|
|
27
|
+
constructor(issues: readonly ContractIssue[]);
|
|
28
|
+
}
|
|
29
|
+
type ContractValidationResult<T> = {
|
|
30
|
+
success: true;
|
|
31
|
+
data: T;
|
|
32
|
+
} | {
|
|
33
|
+
success: false;
|
|
34
|
+
error: ContractValidationError;
|
|
35
|
+
};
|
|
36
|
+
interface ContractValidator<Input, Output> extends StandardSchemaV1<Input, Output> {
|
|
37
|
+
readonly '~standard': Omit<StandardSchemaV1.Props<Input, Output>, 'validate'> & {
|
|
38
|
+
readonly validate: (value: unknown) => StandardContractResult<Output>;
|
|
39
|
+
};
|
|
40
|
+
/**
|
|
41
|
+
* Validate and copy declared contract structures, not opaque nested data.
|
|
42
|
+
* Open-record descendants may retain input references; this is not a deep clone.
|
|
43
|
+
*/
|
|
44
|
+
parse(value: unknown): Output;
|
|
45
|
+
/**
|
|
46
|
+
* Return the same data ownership semantics as parse without throwing on invalid input.
|
|
47
|
+
*/
|
|
48
|
+
safeParse(value: unknown): ContractValidationResult<Output>;
|
|
49
|
+
}
|
|
50
|
+
//#endregion
|
|
51
|
+
//#region src/contracts/projection.d.ts
|
|
52
|
+
type Contract<Input, Output = Input> = StandardJSONSchemaV1<Input, Output> & ContractValidator<Input, Output>;
|
|
53
|
+
//#endregion
|
|
54
|
+
//#region generated/CreateStateMachineInstanceRequestSchema.d.mts
|
|
55
|
+
// Generated from authored schemas. Do not edit.
|
|
56
|
+
/**
|
|
57
|
+
* Request to create an instance; the store resolves its template and assigns persisted lifecycle fields.
|
|
58
|
+
*/
|
|
59
|
+
interface CreateStateMachineInstanceRequestSchema {
|
|
60
|
+
/**
|
|
61
|
+
* Unique identifier of the instance.
|
|
62
|
+
*/
|
|
63
|
+
id: string;
|
|
64
|
+
/**
|
|
65
|
+
* Template reference to resolve during creation, not a persisted revision binding.
|
|
66
|
+
*/
|
|
67
|
+
template: {
|
|
68
|
+
/**
|
|
69
|
+
* Unique identifier of the template.
|
|
70
|
+
*/
|
|
71
|
+
id: string;
|
|
72
|
+
/**
|
|
73
|
+
* Logical application version of the template. Optional because the template may have no version.
|
|
74
|
+
*/
|
|
75
|
+
version?: string;
|
|
76
|
+
};
|
|
77
|
+
/**
|
|
78
|
+
* Optional initial state override. The store clones it, or the resolved template initial state when omitted, and validates it against the template state schema.
|
|
79
|
+
*/
|
|
80
|
+
state?: {
|
|
81
|
+
[k: string]: unknown;
|
|
82
|
+
};
|
|
83
|
+
/**
|
|
84
|
+
* Optional application-defined metadata about the instance. Arbitrary keys are preserved.
|
|
85
|
+
*/
|
|
86
|
+
metadata?: {
|
|
87
|
+
[k: string]: unknown;
|
|
88
|
+
};
|
|
89
|
+
/**
|
|
90
|
+
* Instance-owned retention policy, independent of execution callers and application state.
|
|
91
|
+
*/
|
|
92
|
+
retention?: {
|
|
93
|
+
/**
|
|
94
|
+
* Sliding expiration duration in milliseconds, renewed on successful persisted updates. Zero means no expiration.
|
|
95
|
+
*/
|
|
96
|
+
ttlMs: number;
|
|
97
|
+
};
|
|
98
|
+
}
|
|
99
|
+
//#endregion
|
|
100
|
+
//#region generated/CreateStateMachineTemplateSchema.d.mts
|
|
101
|
+
// Generated from authored schemas. Do not edit.
|
|
102
|
+
/**
|
|
103
|
+
* Persisted state-machine template defining shared state, initial state, and available functions.
|
|
104
|
+
*/
|
|
105
|
+
interface CreateStateMachineTemplateSchema {
|
|
106
|
+
/**
|
|
107
|
+
* Version of the persisted template format, not the logical application version.
|
|
108
|
+
*/
|
|
109
|
+
schemaVersion: 1;
|
|
110
|
+
/**
|
|
111
|
+
* Unique identifier of the template.
|
|
112
|
+
*/
|
|
113
|
+
id: string;
|
|
114
|
+
/**
|
|
115
|
+
* Optional logical application version. This is different from a storage-driver revision.
|
|
116
|
+
*/
|
|
117
|
+
version?: string;
|
|
118
|
+
/**
|
|
119
|
+
* Optional human-readable explanation of the state machine.
|
|
120
|
+
*/
|
|
121
|
+
description?: string;
|
|
122
|
+
/**
|
|
123
|
+
* Object-form JSON Schema shared by every function to validate instance state. Core checks its shape only; the injected schema compiler validates and compiles its constraints.
|
|
124
|
+
*/
|
|
125
|
+
stateSchema: {
|
|
126
|
+
/**
|
|
127
|
+
* Explicit root instance type required for state and function-input schemas.
|
|
128
|
+
*/
|
|
129
|
+
type: "object";
|
|
130
|
+
[k: string]: unknown;
|
|
131
|
+
};
|
|
132
|
+
/**
|
|
133
|
+
* Default state used when creating an instance without an explicit state override. Must satisfy stateSchema when the template is prepared.
|
|
134
|
+
*/
|
|
135
|
+
initialState: {
|
|
136
|
+
[k: string]: unknown;
|
|
137
|
+
};
|
|
138
|
+
/**
|
|
139
|
+
* Functions available on instances of this template. Names must be unique; the template parser enforces this semantic rule.
|
|
140
|
+
*
|
|
141
|
+
* Items: Named state-machine function, including its input/output contracts and executable implementation.
|
|
142
|
+
*/
|
|
143
|
+
functions: {
|
|
144
|
+
/**
|
|
145
|
+
* Function name, unique within the template. Must contain 1–64 ASCII letters, digits, underscores, or hyphens.
|
|
146
|
+
*/
|
|
147
|
+
name: string;
|
|
148
|
+
/**
|
|
149
|
+
* Optional human-readable explanation of the function.
|
|
150
|
+
*/
|
|
151
|
+
description?: string;
|
|
152
|
+
/**
|
|
153
|
+
* Function classification: queries read state; mutations may update state.
|
|
154
|
+
*/
|
|
155
|
+
kind: "query" | "mutation";
|
|
156
|
+
/**
|
|
157
|
+
* Object-form JSON Schema for input, the first implementation argument. Core checks its shape only; the injected schema compiler validates and compiles its constraints.
|
|
158
|
+
*/
|
|
159
|
+
inputSchema: {
|
|
160
|
+
/**
|
|
161
|
+
* Explicit root instance type required for state and function-input schemas.
|
|
162
|
+
*/
|
|
163
|
+
type: "object";
|
|
164
|
+
[k: string]: unknown;
|
|
165
|
+
};
|
|
166
|
+
/**
|
|
167
|
+
* Optional object-form JSON Schema for the returned value. If omitted, no output schema validator is prepared. Core checks its shape only; the injected schema compiler validates and compiles its constraints.
|
|
168
|
+
*/
|
|
169
|
+
outputSchema?: {
|
|
170
|
+
[k: string]: unknown;
|
|
171
|
+
};
|
|
172
|
+
/**
|
|
173
|
+
* Executable JavaScript implementation and its execution requirements.
|
|
174
|
+
*/
|
|
175
|
+
implementation: {
|
|
176
|
+
/**
|
|
177
|
+
* Runtime used to execute the implementation.
|
|
178
|
+
*/
|
|
179
|
+
runtime: "javascript";
|
|
180
|
+
/**
|
|
181
|
+
* Calling convention: async function(input, state, ctx). The stored implementation.code runs as its body. The arguments are function input, instance state, and the execution context, in that order.
|
|
182
|
+
*/
|
|
183
|
+
abi: "state-machine-function-v1";
|
|
184
|
+
/**
|
|
185
|
+
* Source format: the body of an async function, not a complete function declaration.
|
|
186
|
+
*/
|
|
187
|
+
format: "async-function-body";
|
|
188
|
+
/**
|
|
189
|
+
* JavaScript async-function body. Do not wrap it in async function(...) { ... }. The body can await context operations, access input and state, and return the function result.
|
|
190
|
+
*/
|
|
191
|
+
code: string;
|
|
192
|
+
/**
|
|
193
|
+
* Capability names requested by the implementation. Creation defaults an omitted list to [].
|
|
194
|
+
*
|
|
195
|
+
* Items: Name of a capability requested by the implementation.
|
|
196
|
+
*/
|
|
197
|
+
capabilities?: string[];
|
|
198
|
+
/**
|
|
199
|
+
* Optional execution timeout in milliseconds, expressed as a positive safe integer.
|
|
200
|
+
*/
|
|
201
|
+
timeoutMs?: number;
|
|
202
|
+
};
|
|
203
|
+
/**
|
|
204
|
+
* Optional descriptive hints about the function, not additional schema validation rules.
|
|
205
|
+
*/
|
|
206
|
+
annotations?: {
|
|
207
|
+
/**
|
|
208
|
+
* Whether tool adapters may advertise this function. Omission means true. Controls discovery only, not execution authorization.
|
|
209
|
+
*/
|
|
210
|
+
exposeAsTool?: boolean;
|
|
211
|
+
/**
|
|
212
|
+
* Author declaration of context-free execution using only input/state and local computation, without external effects. When true, allows an explicitly configured backend to select isolated execution; false or omission retains trusted execution. Not a purity proof, security sandbox, idempotency declaration, or permission to retry.
|
|
213
|
+
*/
|
|
214
|
+
pure?: boolean;
|
|
215
|
+
/**
|
|
216
|
+
* Whether the function is declared to be idempotent.
|
|
217
|
+
*/
|
|
218
|
+
idempotent?: boolean;
|
|
219
|
+
/**
|
|
220
|
+
* Whether the function is declared to perform destructive operations.
|
|
221
|
+
*/
|
|
222
|
+
destructive?: boolean;
|
|
223
|
+
/**
|
|
224
|
+
* Whether use of this function is deprecated.
|
|
225
|
+
*/
|
|
226
|
+
deprecated?: boolean;
|
|
227
|
+
};
|
|
228
|
+
/**
|
|
229
|
+
* Optional application-defined metadata about the function. Arbitrary keys are preserved.
|
|
230
|
+
*/
|
|
231
|
+
metadata?: {
|
|
232
|
+
[k: string]: unknown;
|
|
233
|
+
};
|
|
234
|
+
}[];
|
|
235
|
+
/**
|
|
236
|
+
* Optional application-defined metadata about the template. Arbitrary keys are preserved.
|
|
237
|
+
*/
|
|
238
|
+
metadata?: {
|
|
239
|
+
[k: string]: unknown;
|
|
240
|
+
};
|
|
241
|
+
}
|
|
242
|
+
//#endregion
|
|
243
|
+
//#region generated/ExecuteStateMachineFunctionRequestSchema.d.mts
|
|
244
|
+
// Generated from authored schemas. Do not edit.
|
|
245
|
+
/**
|
|
246
|
+
* Execution request envelope; instance lookup and function-specific input validation occur later.
|
|
247
|
+
*/
|
|
248
|
+
interface ExecuteStateMachineFunctionRequestSchema {
|
|
249
|
+
/**
|
|
250
|
+
* Reference identifying the instance on which to execute the function.
|
|
251
|
+
*/
|
|
252
|
+
instance: {
|
|
253
|
+
/**
|
|
254
|
+
* Unique identifier of the instance.
|
|
255
|
+
*/
|
|
256
|
+
id: string;
|
|
257
|
+
};
|
|
258
|
+
/**
|
|
259
|
+
* Name of the function to invoke on the resolved instance template.
|
|
260
|
+
*/
|
|
261
|
+
functionName: string;
|
|
262
|
+
/**
|
|
263
|
+
* Opaque function input, preserved without transformation. The prepared template validates it against the selected function input schema before implementation execution.
|
|
264
|
+
*/
|
|
265
|
+
input: unknown;
|
|
266
|
+
}
|
|
267
|
+
//#endregion
|
|
268
|
+
//#region generated/FunctionImplementationSchema.d.mts
|
|
269
|
+
// Generated from authored schemas. Do not edit.
|
|
270
|
+
/**
|
|
271
|
+
* Executable JavaScript implementation and its execution requirements.
|
|
272
|
+
*/
|
|
273
|
+
interface FunctionImplementationSchema {
|
|
274
|
+
/**
|
|
275
|
+
* Runtime used to execute the implementation.
|
|
276
|
+
*/
|
|
277
|
+
runtime: "javascript";
|
|
278
|
+
/**
|
|
279
|
+
* Calling convention: async function(input, state, ctx). The stored implementation.code runs as its body. The arguments are function input, instance state, and the execution context, in that order.
|
|
280
|
+
*/
|
|
281
|
+
abi: "state-machine-function-v1";
|
|
282
|
+
/**
|
|
283
|
+
* Source format: the body of an async function, not a complete function declaration.
|
|
284
|
+
*/
|
|
285
|
+
format: "async-function-body";
|
|
286
|
+
/**
|
|
287
|
+
* JavaScript async-function body. Do not wrap it in async function(...) { ... }. The body can await context operations, access input and state, and return the function result.
|
|
288
|
+
*/
|
|
289
|
+
code: string;
|
|
290
|
+
/**
|
|
291
|
+
* Capability names requested by the implementation. Required in canonical definitions.
|
|
292
|
+
*
|
|
293
|
+
* Items: Name of a capability requested by the implementation.
|
|
294
|
+
*/
|
|
295
|
+
capabilities: string[];
|
|
296
|
+
/**
|
|
297
|
+
* Optional execution timeout in milliseconds, expressed as a positive safe integer.
|
|
298
|
+
*/
|
|
299
|
+
timeoutMs?: number;
|
|
300
|
+
}
|
|
301
|
+
//#endregion
|
|
302
|
+
//#region generated/FunctionKindSchema.d.mts
|
|
303
|
+
// Generated from authored schemas. Do not edit.
|
|
304
|
+
/**
|
|
305
|
+
* Function classification: queries read state; mutations may update state.
|
|
306
|
+
*/
|
|
307
|
+
type FunctionKindSchema = "query" | "mutation";
|
|
308
|
+
//#endregion
|
|
309
|
+
//#region generated/JsonSchemaSchema.d.mts
|
|
310
|
+
// Generated from authored schemas. Do not edit.
|
|
311
|
+
/**
|
|
312
|
+
* Opaque object-form JSON Schema. Core preserves all keywords and checks only that the value is an object. The injected schema compiler is responsible for validating the dialect, keywords, and references. Boolean schemas are excluded.
|
|
313
|
+
*/
|
|
314
|
+
interface JsonSchemaSchema {
|
|
315
|
+
[k: string]: unknown;
|
|
316
|
+
}
|
|
317
|
+
//#endregion
|
|
318
|
+
//#region generated/ObjectJsonSchemaSchema.d.mts
|
|
319
|
+
// Generated from authored schemas. Do not edit.
|
|
320
|
+
/**
|
|
321
|
+
* Opaque object-form JSON Schema with an explicit type of object. Other keywords are preserved, not interpreted by core. The injected schema compiler is responsible for validating the dialect, keywords, and references.
|
|
322
|
+
*/
|
|
323
|
+
interface ObjectJsonSchemaSchema {
|
|
324
|
+
/**
|
|
325
|
+
* Explicit root instance type required for state and function-input schemas.
|
|
326
|
+
*/
|
|
327
|
+
type: "object";
|
|
328
|
+
[k: string]: unknown;
|
|
329
|
+
}
|
|
330
|
+
//#endregion
|
|
331
|
+
//#region generated/StateMachineFunctionDefinitionSchema.d.mts
|
|
332
|
+
// Generated from authored schemas. Do not edit.
|
|
333
|
+
/**
|
|
334
|
+
* Named state-machine function, including its input/output contracts and executable implementation.
|
|
335
|
+
*/
|
|
336
|
+
interface StateMachineFunctionDefinitionSchema {
|
|
337
|
+
/**
|
|
338
|
+
* Function name, unique within the template. Must contain 1–64 ASCII letters, digits, underscores, or hyphens.
|
|
339
|
+
*/
|
|
340
|
+
name: string;
|
|
341
|
+
/**
|
|
342
|
+
* Optional human-readable explanation of the function.
|
|
343
|
+
*/
|
|
344
|
+
description?: string;
|
|
345
|
+
/**
|
|
346
|
+
* Function classification: queries read state; mutations may update state.
|
|
347
|
+
*/
|
|
348
|
+
kind: "query" | "mutation";
|
|
349
|
+
/**
|
|
350
|
+
* Object-form JSON Schema for input, the first implementation argument. Core checks its shape only; the injected schema compiler validates and compiles its constraints.
|
|
351
|
+
*/
|
|
352
|
+
inputSchema: {
|
|
353
|
+
/**
|
|
354
|
+
* Explicit root instance type required for state and function-input schemas.
|
|
355
|
+
*/
|
|
356
|
+
type: "object";
|
|
357
|
+
[k: string]: unknown;
|
|
358
|
+
};
|
|
359
|
+
/**
|
|
360
|
+
* Optional object-form JSON Schema for the returned value. If omitted, no output schema validator is prepared. Core checks its shape only; the injected schema compiler validates and compiles its constraints.
|
|
361
|
+
*/
|
|
362
|
+
outputSchema?: {
|
|
363
|
+
[k: string]: unknown;
|
|
364
|
+
};
|
|
365
|
+
/**
|
|
366
|
+
* Executable JavaScript implementation and its execution requirements.
|
|
367
|
+
*/
|
|
368
|
+
implementation: {
|
|
369
|
+
/**
|
|
370
|
+
* Runtime used to execute the implementation.
|
|
371
|
+
*/
|
|
372
|
+
runtime: "javascript";
|
|
373
|
+
/**
|
|
374
|
+
* Calling convention: async function(input, state, ctx). The stored implementation.code runs as its body. The arguments are function input, instance state, and the execution context, in that order.
|
|
375
|
+
*/
|
|
376
|
+
abi: "state-machine-function-v1";
|
|
377
|
+
/**
|
|
378
|
+
* Source format: the body of an async function, not a complete function declaration.
|
|
379
|
+
*/
|
|
380
|
+
format: "async-function-body";
|
|
381
|
+
/**
|
|
382
|
+
* JavaScript async-function body. Do not wrap it in async function(...) { ... }. The body can await context operations, access input and state, and return the function result.
|
|
383
|
+
*/
|
|
384
|
+
code: string;
|
|
385
|
+
/**
|
|
386
|
+
* Capability names requested by the implementation. Required in canonical definitions.
|
|
387
|
+
*
|
|
388
|
+
* Items: Name of a capability requested by the implementation.
|
|
389
|
+
*/
|
|
390
|
+
capabilities: string[];
|
|
391
|
+
/**
|
|
392
|
+
* Optional execution timeout in milliseconds, expressed as a positive safe integer.
|
|
393
|
+
*/
|
|
394
|
+
timeoutMs?: number;
|
|
395
|
+
};
|
|
396
|
+
/**
|
|
397
|
+
* Optional descriptive hints about the function, not additional schema validation rules.
|
|
398
|
+
*/
|
|
399
|
+
annotations?: {
|
|
400
|
+
/**
|
|
401
|
+
* Whether tool adapters may advertise this function. Omission means true. Controls discovery only, not execution authorization.
|
|
402
|
+
*/
|
|
403
|
+
exposeAsTool?: boolean;
|
|
404
|
+
/**
|
|
405
|
+
* Author declaration of context-free execution using only input/state and local computation, without external effects. When true, allows an explicitly configured backend to select isolated execution; false or omission retains trusted execution. Not a purity proof, security sandbox, idempotency declaration, or permission to retry.
|
|
406
|
+
*/
|
|
407
|
+
pure?: boolean;
|
|
408
|
+
/**
|
|
409
|
+
* Whether the function is declared to be idempotent.
|
|
410
|
+
*/
|
|
411
|
+
idempotent?: boolean;
|
|
412
|
+
/**
|
|
413
|
+
* Whether the function is declared to perform destructive operations.
|
|
414
|
+
*/
|
|
415
|
+
destructive?: boolean;
|
|
416
|
+
/**
|
|
417
|
+
* Whether use of this function is deprecated.
|
|
418
|
+
*/
|
|
419
|
+
deprecated?: boolean;
|
|
420
|
+
};
|
|
421
|
+
/**
|
|
422
|
+
* Optional application-defined metadata about the function. Arbitrary keys are preserved.
|
|
423
|
+
*/
|
|
424
|
+
metadata?: {
|
|
425
|
+
[k: string]: unknown;
|
|
426
|
+
};
|
|
427
|
+
}
|
|
428
|
+
//#endregion
|
|
429
|
+
//#region generated/StateMachineInstanceSchema.d.mts
|
|
430
|
+
// Generated from authored schemas. Do not edit.
|
|
431
|
+
/**
|
|
432
|
+
* Persisted state-machine instance, pinned to a template revision and tracking its current state.
|
|
433
|
+
*/
|
|
434
|
+
interface StateMachineInstanceSchema {
|
|
435
|
+
/**
|
|
436
|
+
* Version of the persisted instance format, not the logical instance sequence.
|
|
437
|
+
*/
|
|
438
|
+
schemaVersion: 2;
|
|
439
|
+
/**
|
|
440
|
+
* Unique identifier of the instance.
|
|
441
|
+
*/
|
|
442
|
+
id: string;
|
|
443
|
+
/**
|
|
444
|
+
* Template identity and storage revision bound to a state-machine instance.
|
|
445
|
+
*/
|
|
446
|
+
template: {
|
|
447
|
+
/**
|
|
448
|
+
* Unique identifier of the template.
|
|
449
|
+
*/
|
|
450
|
+
id: string;
|
|
451
|
+
/**
|
|
452
|
+
* Logical application version of the template. Optional because the template may have no version.
|
|
453
|
+
*/
|
|
454
|
+
version?: string;
|
|
455
|
+
/**
|
|
456
|
+
* Storage-driver revision of the template used to create this instance. Pins execution to that revision so changing a stored template cannot silently change instance behavior.
|
|
457
|
+
*/
|
|
458
|
+
revision: string;
|
|
459
|
+
};
|
|
460
|
+
/**
|
|
461
|
+
* Instance-owned retention policy, independent of execution callers and application state.
|
|
462
|
+
*/
|
|
463
|
+
retention: {
|
|
464
|
+
/**
|
|
465
|
+
* Sliding expiration duration in milliseconds, renewed on successful persisted updates. Zero means no expiration.
|
|
466
|
+
*/
|
|
467
|
+
ttlMs: number;
|
|
468
|
+
};
|
|
469
|
+
/**
|
|
470
|
+
* Current instance state, validated against the bound template's stateSchema during execution and storage operations.
|
|
471
|
+
*/
|
|
472
|
+
state: {
|
|
473
|
+
[k: string]: unknown;
|
|
474
|
+
};
|
|
475
|
+
/**
|
|
476
|
+
* Logical instance version. Increased for every successful persisted update; independent of the storage-driver revision.
|
|
477
|
+
*/
|
|
478
|
+
sequence: number;
|
|
479
|
+
/**
|
|
480
|
+
* Date and time the instance was created, as an ISO 8601 UTC datetime ending in Z.
|
|
481
|
+
*/
|
|
482
|
+
createdAt: string;
|
|
483
|
+
/**
|
|
484
|
+
* Date and time the instance was last updated, as an ISO 8601 UTC datetime ending in Z.
|
|
485
|
+
*/
|
|
486
|
+
updatedAt: string;
|
|
487
|
+
/**
|
|
488
|
+
* Optional application-defined metadata about the instance. Arbitrary keys are preserved.
|
|
489
|
+
*/
|
|
490
|
+
metadata?: {
|
|
491
|
+
[k: string]: unknown;
|
|
492
|
+
};
|
|
493
|
+
}
|
|
494
|
+
//#endregion
|
|
495
|
+
//#region generated/StateMachineTemplateBindingSchema.d.mts
|
|
496
|
+
// Generated from authored schemas. Do not edit.
|
|
497
|
+
/**
|
|
498
|
+
* Template identity and storage revision bound to a state-machine instance.
|
|
499
|
+
*/
|
|
500
|
+
interface StateMachineTemplateBindingSchema {
|
|
501
|
+
/**
|
|
502
|
+
* Unique identifier of the template.
|
|
503
|
+
*/
|
|
504
|
+
id: string;
|
|
505
|
+
/**
|
|
506
|
+
* Logical application version of the template. Optional because the template may have no version.
|
|
507
|
+
*/
|
|
508
|
+
version?: string;
|
|
509
|
+
/**
|
|
510
|
+
* Storage-driver revision of the template used to create this instance. Pins execution to that revision so changing a stored template cannot silently change instance behavior.
|
|
511
|
+
*/
|
|
512
|
+
revision: string;
|
|
513
|
+
}
|
|
514
|
+
//#endregion
|
|
515
|
+
//#region generated/StateMachineTemplateSchema.d.mts
|
|
516
|
+
// Generated from authored schemas. Do not edit.
|
|
517
|
+
/**
|
|
518
|
+
* Persisted state-machine template defining shared state, initial state, and available functions.
|
|
519
|
+
*/
|
|
520
|
+
interface StateMachineTemplateSchema {
|
|
521
|
+
/**
|
|
522
|
+
* Version of the persisted template format, not the logical application version.
|
|
523
|
+
*/
|
|
524
|
+
schemaVersion: 1;
|
|
525
|
+
/**
|
|
526
|
+
* Unique identifier of the template.
|
|
527
|
+
*/
|
|
528
|
+
id: string;
|
|
529
|
+
/**
|
|
530
|
+
* Optional logical application version. This is different from a storage-driver revision.
|
|
531
|
+
*/
|
|
532
|
+
version?: string;
|
|
533
|
+
/**
|
|
534
|
+
* Optional human-readable explanation of the state machine.
|
|
535
|
+
*/
|
|
536
|
+
description?: string;
|
|
537
|
+
/**
|
|
538
|
+
* Object-form JSON Schema shared by every function to validate instance state. Core checks its shape only; the injected schema compiler validates and compiles its constraints.
|
|
539
|
+
*/
|
|
540
|
+
stateSchema: {
|
|
541
|
+
/**
|
|
542
|
+
* Explicit root instance type required for state and function-input schemas.
|
|
543
|
+
*/
|
|
544
|
+
type: "object";
|
|
545
|
+
[k: string]: unknown;
|
|
546
|
+
};
|
|
547
|
+
/**
|
|
548
|
+
* Default state used when creating an instance without an explicit state override. Must satisfy stateSchema when the template is prepared.
|
|
549
|
+
*/
|
|
550
|
+
initialState: {
|
|
551
|
+
[k: string]: unknown;
|
|
552
|
+
};
|
|
553
|
+
/**
|
|
554
|
+
* Functions available on instances of this template. Names must be unique; the template parser enforces this semantic rule.
|
|
555
|
+
*
|
|
556
|
+
* Items: Named state-machine function, including its input/output contracts and executable implementation.
|
|
557
|
+
*/
|
|
558
|
+
functions: {
|
|
559
|
+
/**
|
|
560
|
+
* Function name, unique within the template. Must contain 1–64 ASCII letters, digits, underscores, or hyphens.
|
|
561
|
+
*/
|
|
562
|
+
name: string;
|
|
563
|
+
/**
|
|
564
|
+
* Optional human-readable explanation of the function.
|
|
565
|
+
*/
|
|
566
|
+
description?: string;
|
|
567
|
+
/**
|
|
568
|
+
* Function classification: queries read state; mutations may update state.
|
|
569
|
+
*/
|
|
570
|
+
kind: "query" | "mutation";
|
|
571
|
+
/**
|
|
572
|
+
* Object-form JSON Schema for input, the first implementation argument. Core checks its shape only; the injected schema compiler validates and compiles its constraints.
|
|
573
|
+
*/
|
|
574
|
+
inputSchema: {
|
|
575
|
+
/**
|
|
576
|
+
* Explicit root instance type required for state and function-input schemas.
|
|
577
|
+
*/
|
|
578
|
+
type: "object";
|
|
579
|
+
[k: string]: unknown;
|
|
580
|
+
};
|
|
581
|
+
/**
|
|
582
|
+
* Optional object-form JSON Schema for the returned value. If omitted, no output schema validator is prepared. Core checks its shape only; the injected schema compiler validates and compiles its constraints.
|
|
583
|
+
*/
|
|
584
|
+
outputSchema?: {
|
|
585
|
+
[k: string]: unknown;
|
|
586
|
+
};
|
|
587
|
+
/**
|
|
588
|
+
* Executable JavaScript implementation and its execution requirements.
|
|
589
|
+
*/
|
|
590
|
+
implementation: {
|
|
591
|
+
/**
|
|
592
|
+
* Runtime used to execute the implementation.
|
|
593
|
+
*/
|
|
594
|
+
runtime: "javascript";
|
|
595
|
+
/**
|
|
596
|
+
* Calling convention: async function(input, state, ctx). The stored implementation.code runs as its body. The arguments are function input, instance state, and the execution context, in that order.
|
|
597
|
+
*/
|
|
598
|
+
abi: "state-machine-function-v1";
|
|
599
|
+
/**
|
|
600
|
+
* Source format: the body of an async function, not a complete function declaration.
|
|
601
|
+
*/
|
|
602
|
+
format: "async-function-body";
|
|
603
|
+
/**
|
|
604
|
+
* JavaScript async-function body. Do not wrap it in async function(...) { ... }. The body can await context operations, access input and state, and return the function result.
|
|
605
|
+
*/
|
|
606
|
+
code: string;
|
|
607
|
+
/**
|
|
608
|
+
* Capability names requested by the implementation. Required in canonical definitions.
|
|
609
|
+
*
|
|
610
|
+
* Items: Name of a capability requested by the implementation.
|
|
611
|
+
*/
|
|
612
|
+
capabilities: string[];
|
|
613
|
+
/**
|
|
614
|
+
* Optional execution timeout in milliseconds, expressed as a positive safe integer.
|
|
615
|
+
*/
|
|
616
|
+
timeoutMs?: number;
|
|
617
|
+
};
|
|
618
|
+
/**
|
|
619
|
+
* Optional descriptive hints about the function, not additional schema validation rules.
|
|
620
|
+
*/
|
|
621
|
+
annotations?: {
|
|
622
|
+
/**
|
|
623
|
+
* Whether tool adapters may advertise this function. Omission means true. Controls discovery only, not execution authorization.
|
|
624
|
+
*/
|
|
625
|
+
exposeAsTool?: boolean;
|
|
626
|
+
/**
|
|
627
|
+
* Author declaration of context-free execution using only input/state and local computation, without external effects. When true, allows an explicitly configured backend to select isolated execution; false or omission retains trusted execution. Not a purity proof, security sandbox, idempotency declaration, or permission to retry.
|
|
628
|
+
*/
|
|
629
|
+
pure?: boolean;
|
|
630
|
+
/**
|
|
631
|
+
* Whether the function is declared to be idempotent.
|
|
632
|
+
*/
|
|
633
|
+
idempotent?: boolean;
|
|
634
|
+
/**
|
|
635
|
+
* Whether the function is declared to perform destructive operations.
|
|
636
|
+
*/
|
|
637
|
+
destructive?: boolean;
|
|
638
|
+
/**
|
|
639
|
+
* Whether use of this function is deprecated.
|
|
640
|
+
*/
|
|
641
|
+
deprecated?: boolean;
|
|
642
|
+
};
|
|
643
|
+
/**
|
|
644
|
+
* Optional application-defined metadata about the function. Arbitrary keys are preserved.
|
|
645
|
+
*/
|
|
646
|
+
metadata?: {
|
|
647
|
+
[k: string]: unknown;
|
|
648
|
+
};
|
|
649
|
+
}[];
|
|
650
|
+
/**
|
|
651
|
+
* Optional application-defined metadata about the template. Arbitrary keys are preserved.
|
|
652
|
+
*/
|
|
653
|
+
metadata?: {
|
|
654
|
+
[k: string]: unknown;
|
|
655
|
+
};
|
|
656
|
+
}
|
|
657
|
+
//#endregion
|
|
658
|
+
//#region src/types.d.ts
|
|
659
|
+
type FunctionKind = FunctionKindSchema;
|
|
660
|
+
/**
|
|
661
|
+
* Canonical implementation with an explicit capability list.
|
|
662
|
+
*/
|
|
663
|
+
interface FunctionImplementation extends FunctionImplementationSchema {}
|
|
664
|
+
/**
|
|
665
|
+
* Canonical function definition with an explicit implementation capability list.
|
|
666
|
+
*/
|
|
667
|
+
interface StateMachineFunctionDefinition extends StateMachineFunctionDefinitionSchema {}
|
|
668
|
+
interface JsonSchema extends JsonSchemaSchema {}
|
|
669
|
+
interface ObjectJsonSchema extends ObjectJsonSchemaSchema {}
|
|
670
|
+
interface StateMachineTemplateBinding extends StateMachineTemplateBindingSchema {}
|
|
671
|
+
interface StateMachineInstance extends StateMachineInstanceSchema {}
|
|
672
|
+
/**
|
|
673
|
+
* Template draft before creation defaults are applied.
|
|
674
|
+
*/
|
|
675
|
+
interface StateMachineTemplateDraft extends CreateStateMachineTemplateSchema {}
|
|
676
|
+
/**
|
|
677
|
+
* Canonical persisted template; all creation-defaulted fields are required.
|
|
678
|
+
*/
|
|
679
|
+
interface StateMachineTemplate extends StateMachineTemplateSchema {}
|
|
680
|
+
/**
|
|
681
|
+
* Readonly template view for prepared/stored snapshots. This type alone does not
|
|
682
|
+
* establish ownership or freeze data; the template store enforces that boundary.
|
|
683
|
+
*/
|
|
684
|
+
type ReadonlyStateMachineTemplate = DeepReadonly<StateMachineTemplate>;
|
|
685
|
+
/**
|
|
686
|
+
* Function definition view inside a readonly template.
|
|
687
|
+
*/
|
|
688
|
+
type ReadonlyStateMachineFunctionDefinition = DeepReadonly<StateMachineFunctionDefinition>;
|
|
689
|
+
type DeepReadonly<T> = T extends object ? { readonly [Key in keyof T]: DeepReadonly<T[Key]>; } : T;
|
|
690
|
+
/**
|
|
691
|
+
* Validated creation request. Template resolution, initial state selection, timestamps,
|
|
692
|
+
* and sequence assignment remain domain operations rather than schema defaults.
|
|
693
|
+
*/
|
|
694
|
+
interface CreateStateMachineInstanceRequest extends CreateStateMachineInstanceRequestSchema {}
|
|
695
|
+
/**
|
|
696
|
+
* Validated execution envelope. Context is supplied separately; template-specific
|
|
697
|
+
* input validation and execution remain runtime responsibilities.
|
|
698
|
+
*/
|
|
699
|
+
interface ExecuteStateMachineFunctionRequest extends ExecuteStateMachineFunctionRequestSchema {}
|
|
700
|
+
//#endregion
|
|
701
|
+
//#region src/contracts/templates.d.ts
|
|
702
|
+
/**
|
|
703
|
+
* Strict validation: no defaults, coercion, stripping, or implicit migration.
|
|
704
|
+
*/
|
|
705
|
+
declare const StateMachineTemplateContract: Contract<StateMachineTemplate, StateMachineTemplate>;
|
|
706
|
+
/**
|
|
707
|
+
* Creation supplies fresh defaults, then validates the canonical result.
|
|
708
|
+
*/
|
|
709
|
+
declare const CreateStateMachineTemplateContract: Contract<StateMachineTemplateDraft, StateMachineTemplate>;
|
|
710
|
+
//#endregion
|
|
711
|
+
//#region src/contracts/instances.d.ts
|
|
712
|
+
/**
|
|
713
|
+
* Canonical instance validation; creation fields are assigned by domain operations.
|
|
714
|
+
*/
|
|
715
|
+
declare const StateMachineInstanceContract: Contract<StateMachineInstance, StateMachineInstance>;
|
|
716
|
+
declare const StateMachineTemplateBindingContract: Contract<StateMachineTemplateBinding, StateMachineTemplateBinding>;
|
|
717
|
+
//#endregion
|
|
718
|
+
//#region src/contracts/requests.d.ts
|
|
719
|
+
/**
|
|
720
|
+
* Pure request validation; does not create an instance or populate domain-owned fields.
|
|
721
|
+
*/
|
|
722
|
+
declare const CreateStateMachineInstanceRequestContract: Contract<CreateStateMachineInstanceRequest, CreateStateMachineInstanceRequest>;
|
|
723
|
+
/**
|
|
724
|
+
* Validate the envelope only; context and function-specific validation stay separate.
|
|
725
|
+
*/
|
|
726
|
+
declare const ExecuteStateMachineFunctionRequestContract: Contract<ExecuteStateMachineFunctionRequest, ExecuteStateMachineFunctionRequest>;
|
|
727
|
+
//#endregion
|
|
728
|
+
//#region src/contracts/functions.d.ts
|
|
729
|
+
declare const FunctionKindContract: Contract<FunctionKindSchema, FunctionKindSchema>;
|
|
730
|
+
declare const FunctionImplementationContract: Contract<FunctionImplementation, FunctionImplementation>;
|
|
731
|
+
declare const StateMachineFunctionDefinitionContract: Contract<StateMachineFunctionDefinition, StateMachineFunctionDefinition>;
|
|
732
|
+
//#endregion
|
|
733
|
+
//#region src/contracts/json-schema.d.ts
|
|
734
|
+
/**
|
|
735
|
+
* Embedded-schema contracts check object shape only, not dialect or keyword validity.
|
|
736
|
+
*/
|
|
737
|
+
declare const JsonSchemaContract: Contract<JsonSchema, JsonSchema>;
|
|
738
|
+
declare const ObjectJsonSchemaContract: Contract<ObjectJsonSchema, ObjectJsonSchema>;
|
|
739
|
+
//#endregion
|
|
740
|
+
export { type Contract, type ContractIssue, ContractValidationError, type ContractValidationResult, type CreateStateMachineInstanceRequest, CreateStateMachineInstanceRequestContract, CreateStateMachineTemplateContract, type ExecuteStateMachineFunctionRequest, ExecuteStateMachineFunctionRequestContract, type FunctionImplementation, FunctionImplementationContract, type FunctionKind, FunctionKindContract, type JsonSchema, JsonSchemaContract, type ObjectJsonSchema, ObjectJsonSchemaContract, type ReadonlyStateMachineFunctionDefinition, type ReadonlyStateMachineTemplate, type StandardContractIssue, type StandardContractResult, type StateMachineFunctionDefinition, StateMachineFunctionDefinitionContract, type StateMachineInstance, StateMachineInstanceContract, type StateMachineTemplate, type StateMachineTemplateBinding, StateMachineTemplateBindingContract, StateMachineTemplateContract, type StateMachineTemplateDraft };
|
|
741
|
+
//# sourceMappingURL=index.d.mts.map
|