@astrale-os/sdk 0.6.0-beta.53 → 0.6.0-beta.55

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 (32) hide show
  1. package/dist/application/action/authoring.d.ts +2 -0
  2. package/dist/application/action/authoring.js +1 -0
  3. package/dist/application/action/context.d.ts +6 -1
  4. package/dist/application/action/index.d.ts +2 -0
  5. package/dist/application/action/index.js +1 -0
  6. package/dist/application/file/binary.d.ts +11 -0
  7. package/dist/application/file/binary.js +45 -0
  8. package/dist/application/file/file.d.ts +72 -0
  9. package/dist/application/file/file.js +111 -0
  10. package/dist/application/file/index.d.ts +4 -0
  11. package/dist/application/file/index.js +2 -0
  12. package/dist/application/file/input.d.ts +13 -0
  13. package/dist/application/file/input.js +57 -0
  14. package/dist/application/mutation/authoring/properties.d.ts +12 -1
  15. package/dist/application/mutation/authoring/properties.js +6 -3
  16. package/dist/application/runtime/runtime.js +12 -0
  17. package/dist/execution/identity/exchange.js +11 -1
  18. package/dist/execution/invocation/dispatch/context.d.ts +2 -2
  19. package/dist/execution/invocation/dispatch/context.js +22 -2
  20. package/dist/execution/invocation/invocation.js +1 -1
  21. package/dist/execution/invocation/result/errors.js +8 -0
  22. package/dist/index.d.ts +1 -1
  23. package/dist/platform/schema/kernel-compiled.d.ts +1 -1
  24. package/dist/platform/schema/kernel-compiled.js +2 -2
  25. package/dist/testing/file.d.ts +20 -0
  26. package/dist/testing/file.js +49 -0
  27. package/dist/testing/index.d.ts +4 -2
  28. package/dist/testing/index.js +3 -2
  29. package/docs/auth-api-migration.md +3 -1
  30. package/docs/durable-workflows.md +55 -0
  31. package/docs/handler-dependencies.md +160 -68
  32. package/package.json +6 -6
@@ -0,0 +1,20 @@
1
+ import type { ReceivedFile } from '../application/file/index.js';
2
+ /** What a test file declares besides its bytes. */
3
+ export interface TestFileOptions {
4
+ /** The file's media type. Default: `text/plain` for a string, else the Blob's type, else `application/octet-stream`. */
5
+ readonly type?: string;
6
+ /** The receipt the file object carries. Default: a new `test-receipt-<n>`. */
7
+ readonly receipt?: string;
8
+ }
9
+ /**
10
+ * A file object as a handler receives it at a `file()` field, over bytes held in memory: a handler
11
+ * unit test passes it in its input without a Kernel. Each read yields the same bytes, under the same
12
+ * limits as a received file; a Mutation attaches it as its `receipt`.
13
+ *
14
+ * ```ts
15
+ * import * as testing from '@astrale-os/sdk/testing'
16
+ *
17
+ * const balance = testing.file('account,amount\n512,10', { type: 'text/csv' })
18
+ * ```
19
+ */
20
+ export declare function file(content: string | Uint8Array | Blob, options?: TestFileOptions): ReceivedFile;
@@ -0,0 +1,49 @@
1
+ import { receivedFile } from '../application/file/index.js';
2
+ let receipts = 0;
3
+ /**
4
+ * A file object as a handler receives it at a `file()` field, over bytes held in memory: a handler
5
+ * unit test passes it in its input without a Kernel. Each read yields the same bytes, under the same
6
+ * limits as a received file; a Mutation attaches it as its `receipt`.
7
+ *
8
+ * ```ts
9
+ * import * as testing from '@astrale-os/sdk/testing'
10
+ *
11
+ * const balance = testing.file('account,amount\n512,10', { type: 'text/csv' })
12
+ * ```
13
+ */
14
+ export function file(content, options = {}) {
15
+ if (options === null || typeof options !== 'object') {
16
+ throw new TypeError('Test file options must be an object.');
17
+ }
18
+ const mediaType = options.type ??
19
+ (typeof content === 'string'
20
+ ? 'text/plain'
21
+ : content instanceof Blob && content.type !== ''
22
+ ? content.type
23
+ : 'application/octet-stream');
24
+ // The bytes as they are now: a later change to `content` never reaches the file.
25
+ const held = typeof content === 'string'
26
+ ? new TextEncoder().encode(content)
27
+ : content instanceof Uint8Array
28
+ ? content.slice()
29
+ : content instanceof Blob
30
+ ? content
31
+ : invalidContent();
32
+ const read = async () => held instanceof Blob ? new Uint8Array(await held.arrayBuffer()) : held.slice();
33
+ receipts += 1;
34
+ const receipt = (options.receipt ?? `test-receipt-${receipts}`);
35
+ return receivedFile(receipt, async () => {
36
+ const bytes = await read();
37
+ return {
38
+ body: (async function* () {
39
+ if (bytes.byteLength > 0)
40
+ yield bytes;
41
+ })(),
42
+ length: bytes.byteLength,
43
+ mediaType,
44
+ };
45
+ });
46
+ }
47
+ function invalidContent() {
48
+ throw new TypeError('Test file content must be a string, a Uint8Array, or a Blob.');
49
+ }
@@ -1,6 +1,6 @@
1
1
  /**
2
- * Development and test resources: schema-admitted demo Datasets, their lazy project references, and
3
- * an in-memory engine that runs durable Workflows.
2
+ * Development and test resources: schema-admitted demo Datasets, their lazy project references, an
3
+ * in-memory engine that runs durable Workflows, and file objects for handler unit tests.
4
4
  */
5
5
  export { DATASET_FORMAT, DATASET_VERSION, DatasetAdmissionError, decodeDataset, defineDataset, encodeDataset, isDataset, } from './dataset/index.js';
6
6
  export type { AuthoredDatasetVariables, Dataset, DatasetClasses, DatasetEdgeInput, DatasetEndpoint, DatasetGraph, DatasetInput, DatasetJson, DatasetNode, DatasetNodeInput, DatasetReferences, DatasetReferenceInput, DatasetVariable, DatasetVariableJson, DatasetVariables, DatasetVariablesOf, SchemaOfDataset, } from './dataset/index.js';
@@ -12,5 +12,7 @@ export { isTests, tests } from './tests.js';
12
12
  export type { Tests, TestsInput } from './tests.js';
13
13
  export { createTestWorkflowEngine } from './durable/index.js';
14
14
  export type { TestExecution, TestJournalEntry, TestStartOptions, TestStepCapabilities, TestWorkflowEngine, TestWorkflowEngineOptions, } from './durable/index.js';
15
+ export { file } from './file.js';
16
+ export type { TestFileOptions } from './file.js';
15
17
  export { checkQuery } from './query.js';
16
18
  export type { CheckQueryOptions } from './query.js';
@@ -1,10 +1,11 @@
1
1
  /**
2
- * Development and test resources: schema-admitted demo Datasets, their lazy project references, and
3
- * an in-memory engine that runs durable Workflows.
2
+ * Development and test resources: schema-admitted demo Datasets, their lazy project references, an
3
+ * in-memory engine that runs durable Workflows, and file objects for handler unit tests.
4
4
  */
5
5
  export { DATASET_FORMAT, DATASET_VERSION, DatasetAdmissionError, decodeDataset, defineDataset, encodeDataset, isDataset, } from './dataset/index.js';
6
6
  export { loadDataset, loadDatasets } from './load.js';
7
7
  export { dataset, isDatasetReference } from './reference.js';
8
8
  export { isTests, tests } from './tests.js';
9
9
  export { createTestWorkflowEngine } from './durable/index.js';
10
+ export { file } from './file.js';
10
11
  export { checkQuery } from './query.js';
@@ -17,7 +17,9 @@ it. Errors remain errors; a network failure is not a permission denial. Admissio
17
17
  installed Domain with token exchange, and runs the same delegate and token exchange chain as the
18
18
  Session `exchange` option and `session.exchange(issuer)`. Delegation uses explicit per-call
19
19
  attenuation, the Session's attenuation, or `self`, and can therefore narrow a composed Grant. A later
20
- invocation is independently authorized.
20
+ invocation is independently authorized. A Domain exchanges only a direct delegation, whose source
21
+ principal is its own caller (a user or Function credential): a Session acting for another caller,
22
+ such as a Domain-exchanged credential, cannot admit or exchange through another Domain.
21
23
 
22
24
  ## Constructor migration
23
25
 
@@ -18,6 +18,13 @@ remind: method({
18
18
  A durable callable needs `authenticated` or `authorized` auth, a value input and output, and a
19
19
  remote binding. Implement it with `defineWorkflow`; `defineAction` refuses a durable callable.
20
20
 
21
+ A durable Workflow receives each `file()` input field as a file reference, a string, not a file
22
+ object. A receipt is bound to the user who uploaded it and lives 15 minutes, while the Steps act as
23
+ the Domain and the run may last longer. At the durable start the Kernel therefore checks each
24
+ receipt for the caller and against the field's `maxBytes` and `mediaTypes`, and replaces it by a
25
+ reference bound to this Execution and to the Domain; neither the Execution record nor the engine
26
+ journal holds the receipt. See [Files in a durable Workflow](#files-in-a-durable-workflow).
27
+
21
28
  ```ts
22
29
  export const remind = defineWorkflow<typeof schema>()(
23
30
  'Invoice.remind',
@@ -202,6 +209,54 @@ a result the Workflow handles, such as a declared error; unmapped, the engine re
202
209
  Step spends its budget. A retried Step whose Mutation already committed still receives that commit's
203
210
  receipt, even though its precondition no longer holds.
204
211
 
212
+ ## Files in a durable Workflow
213
+
214
+ A `file()` field of a durable callable reaches the Workflow as a file reference: the Kernel
215
+ exchanged the caller's receipt for it when it started the Execution, after checking the receipt for
216
+ the caller and the file against the field's `maxBytes` and `mediaTypes`. A refused receipt refuses
217
+ the call with `FUNCTION_INPUT_INVALID`, the refusal's code as its reason and the field's JSON
218
+ Pointer as `path`, and no Execution is recorded. A replay of the same idempotency key compares each
219
+ file field by its content, so the same file under a fresh receipt is the same call; a replay still
220
+ needs a valid receipt.
221
+
222
+ A Step uses the reference wherever a receipt goes, through its own `kernel` and `mutate`, which act
223
+ as the Domain for this Execution:
224
+
225
+ ```ts
226
+ export const importBalance = defineWorkflow<typeof schema>()(
227
+ 'importBalance',
228
+ async ({ input, step }) => {
229
+ const lines = await step.run('count-lines', async ({ kernel }) => {
230
+ const { body } = await kernel.content.download({ receipt: input.balance })
231
+ // A Uint8Array, or chunks as they arrive.
232
+ const chunks = body instanceof Uint8Array ? [body] : await Array.fromAsync(body)
233
+ return new TextDecoder().decode(await new Blob(chunks).bytes()).split('\n').length
234
+ })
235
+ await step.mutate(
236
+ 'attach',
237
+ recordBalance, // writes input.balance as the TrialBalance `source` blob Property
238
+ { fiscalYear: input.fiscalYear, balance: input.balance },
239
+ { as: 'executor' },
240
+ )
241
+ return { lines }
242
+ },
243
+ )
244
+ ```
245
+
246
+ - **Bound to its run.** The reference is accepted only from a Step of the Execution it names, as
247
+ the Domain, while the engine holds that run unfinished and for at most 7 days. The caller cannot
248
+ use it, nor another Execution of the same Domain, nor anyone once the run ended. It never expires
249
+ within the run: a Step may read or attach it long after the original receipt expired.
250
+ - **Attach to keep the file.** While the run lasts its Execution keeps the content. Afterwards only
251
+ the Nodes a Step attached it to keep it: attach the file in a Step, and keep the Node.
252
+ - **Not passed on.** A Step cannot hand its reference to a child durable call, which accepts only a
253
+ receipt of its caller: attach the file, then pass the Node.
254
+ - **No file object yet.** The Workflow receives the reference string, not the file object an Action
255
+ receives (`stream()`, `text()`, `bytes()`), so the field's `maxBytes` and `mediaTypes` are checked
256
+ by the Kernel at the start and by the Property when a Step attaches the file, not on each read.
257
+ - **The envelope.** The run's engine input names each reference in `files`, its JSON Pointer and
258
+ `Ref`; the SDK does not need it to run the Workflow.
259
+
205
260
  ## Testing
206
261
 
207
262
  `createTestWorkflowEngine` from `@astrale-os/sdk/testing` runs a durable Workflow in memory with
@@ -102,98 +102,190 @@ refuses it for any other. Cancellation and the parent deadline are inherited. A
102
102
  the deadline; a child does not inherit the parent's idempotency key. Detached
103
103
  `const { invoke } = dependencies.directory.caller` keeps its types and authority binding.
104
104
 
105
+ ## Receiving a file
106
+
107
+ A file never travels inside a call. The client uploads its bytes to the Kernel first, and the call
108
+ carries the receipt the upload returned: a signed string, bound to the user who uploaded the file,
109
+ valid for 15 minutes. A callable declares where it takes a file with a `file()` input field. Its
110
+ handler receives a file object there, reads the file with the caller's authority if it needs to,
111
+ and attaches it to a blob Property, also as the caller.
112
+
113
+ ```ts
114
+ import { defineAction, type ReceivedFile } from '@astrale-os/sdk/action'
115
+ import { defineMutation } from '@astrale-os/sdk/mutation'
116
+ import { classIcon, defineSchema, file, func, nodeClass, property, schema } from '@astrale-os/sdk/schema'
117
+ import { z } from 'zod'
118
+
119
+ const source = property(schema.values.blob({ maxBytes: 20_000_000, mediaTypes: ['text/csv'] }))
120
+ const TrialBalance = nodeClass({
121
+ icon: classIcon.neutral,
122
+ properties: { fiscalYear: z.string(), source },
123
+ policies: { read: true },
124
+ })
125
+ const Schema = defineSchema('ledger.example', {
126
+ name: 'Ledger',
127
+ classes: { TrialBalance },
128
+ functions: {
129
+ importBalance: func({
130
+ auth: 'authenticated',
131
+ input: z.strictObject({
132
+ fiscalYear: z.string(),
133
+ balance: file(source), // the field states the Property's constraints
134
+ attachments: z.array(file({ maxBytes: 5_000_000 })).max(10),
135
+ }),
136
+ output: z.string(),
137
+ }),
138
+ },
139
+ })
140
+
141
+ const recordBalance = defineMutation<typeof Schema>()('trialBalance.record', {
142
+ build(input: { fiscalYear: string; balance: ReceivedFile }, { TrialBalance }, mutation) {
143
+ mutation.createNode({
144
+ as: 'balance',
145
+ class: TrialBalance,
146
+ props: { fiscalYear: input.fiscalYear, source: input.balance }, // attached as it is
147
+ })
148
+ },
149
+ })
150
+
151
+ export const importBalance = defineAction<typeof Schema>()(
152
+ 'importBalance',
153
+ async ({ input, mutate }) => {
154
+ const csv = await input.balance.text() // whole file, in memory: 10 MiB at most
155
+ if (!csv.startsWith('account,')) throw new Error('Not a trial balance.')
156
+ await mutate(recordBalance, input, { as: 'caller' })
157
+ return csv.split('\n').length.toString()
158
+ },
159
+ )
160
+ ```
161
+
162
+ `ReceivedFile` is exported by `@astrale-os/sdk/action`. A client sends the file in two steps,
163
+ upload then call, or lets the typed `invoke` of a Client Session upload a `Blob` or `File` found at
164
+ a `file()` field before it calls:
165
+
166
+ ```ts
167
+ const { receipt } = await session.content.upload(csv, { mediaType: 'text/csv' })
168
+ await session.invoke(reference(ledger, ledger.functions.importBalance), {
169
+ fiscalYear: '2026',
170
+ balance: receipt,
171
+ attachments: [],
172
+ })
173
+ ```
174
+
175
+ ### Reading the file
176
+
177
+ | Member | Returns |
178
+ | --- | --- |
179
+ | `receipt` | The receipt the caller sent. |
180
+ | `stream()` | A `ReadableStream<Uint8Array>` of the file, for a file of any size. |
181
+ | `text()` | The whole file decoded as UTF-8. |
182
+ | `bytes()` | The whole file as a `Uint8Array`. |
183
+
184
+ - **As the caller.** Each read downloads the file again with `kernel.caller.content.download({
185
+ receipt })`. The receipt is the caller's: the Kernel refuses it to this Domain's own authority,
186
+ and to any other user, with `BLOB_RECEIPT_INVALID`. Nothing is kept between reads; a file read
187
+ twice is downloaded twice.
188
+ - **In memory up to `FILE_MEMORY_LIMIT`.** `text()` and `bytes()` hold the whole file, so they
189
+ refuse a file larger than `FILE_MEMORY_LIMIT` (10 MiB, exported by `@astrale-os/sdk/action`) with
190
+ `FileReadError` `FILE_MEMORY_LIMIT`, before reading it when its size is known. Read a larger file
191
+ with `stream()`.
192
+ - **Complete or failed.** `text()` and `bytes()` resolve only once the whole file arrived with the
193
+ size the Kernel declared and passed its integrity check. `stream()` hands chunks over as they
194
+ arrive and fails at its end if the file does not: write nothing derived from it anywhere lasting
195
+ before the stream ends. Cancelling the stream cancels the download.
196
+ - **The field's constraints.** The SDK checks a field's `maxBytes` and `mediaTypes` on each read
197
+ and refuses a file outside them with `FileReadError` (`FILE_TOO_LARGE`, `FILE_MEDIA_TYPE`). The
198
+ Kernel never checks them against a receipt; clients check them before they upload. A file
199
+ attached without being read is checked by the Kernel against the Property's own constraints only,
200
+ so a field that feeds a Property should state them: `file(source)` copies them, and
201
+ `file(source, { maxBytes })` may narrow them.
202
+ - **Refusals reach the caller.** A `FileReadError` the handler does not catch reaches the caller as
203
+ `LIMIT_EXCEEDED` (size) or `VALIDATION_ERROR` (media type) with its code as the reason, and the
204
+ Kernel's refusal of a receipt reaches it as the Kernel sent it.
205
+
206
+ ### Attaching the file
207
+
208
+ A blob Property value takes the file object as it is in every Mutation the SDK authors (`mutate`,
209
+ `graph.mutate`, a defined Mutation's `build`, `createNode`, `updateNode`) and writes its receipt.
210
+ Attach as the caller, `mutate(definition, input, { as: 'caller' })` or `graph.caller.mutate`, since
211
+ only the user who uploaded the file can attach its receipt; the Kernel then applies the caller's
212
+ permissions to the write and the Property's constraints to the file. The raw Kernel builder of
213
+ `kernel.caller.mutate((m) => ...)` takes `file.receipt`. Attaching never reads the file.
214
+
215
+ - **Within 15 minutes.** A receipt expires 15 minutes after its upload. Read and attach the file in
216
+ the invocation that received it; keep the attached Node, never the receipt.
217
+ - **Authenticated callables only.** A file is read and attached as the caller, and a call to an
218
+ `anonymous` callable may carry no caller. The runtime refuses a `file()` field in the input of an
219
+ `anonymous` callable when it is built or served.
220
+ - **Passing it on.** To hand the file to a dependency that takes it in a `file()` field, send its
221
+ receipt as the caller: `dependencies.files.caller.invoke(d => d.functions.scan, { file:
222
+ input.balance.receipt })`.
223
+ - **Durable Workflows.** A durable Workflow's input holds a file reference at each `file()`
224
+ field, not a file object: at the durable start the Kernel exchanges the caller's receipt for a
225
+ reference bound to the Execution, which its Steps use as the Domain wherever a receipt goes
226
+ (`kernel.content.download({ receipt })`, a blob Property value) while the run lasts. See
227
+ [Files in a durable Workflow](durable-workflows.md#files-in-a-durable-workflow).
228
+
229
+ ### Testing a handler
230
+
231
+ `testing.file(content, { type })` from `@astrale-os/sdk/testing` makes a file object over bytes
232
+ held in memory: a handler unit test passes it in its input without a Kernel. It reads the same bytes
233
+ on every read, under the same limits, and a Mutation attaches it as its `receipt`.
234
+
235
+ ```ts
236
+ import * as testing from '@astrale-os/sdk/testing'
237
+
238
+ const balance = testing.file('account,amount\n512,10', { type: 'text/csv' })
239
+ await expect(balance.text()).resolves.toBe('account,amount\n512,10')
240
+ ```
241
+
105
242
  ## Binary Function input
106
243
 
244
+ A binary input carries a stream the Function processes as it arrives and does not store, such as a
245
+ payload it forwards, transforms, or measures. To receive a file the Domain stores, use a `file()`
246
+ field (see [Receiving a file](#receiving-a-file)).
247
+
107
248
  A Function can declare `input.binary(metadataSchema, { maximumBytes })`. The handler receives
108
249
  validated JSON metadata in `ctx.input` and a single-consumer `ReadableStream<Uint8Array>` plus its
109
250
  declared byte `length` in `ctx.body`. Consume the stream through EOF before returning a successful
110
251
  result. The bytes stay outside `Call.input` and are sent as the HTTP request body.
111
252
 
112
253
  ```ts
113
- const receipt = await dependencies.files.caller.invoke(
114
- d => d.functions.upload,
254
+ const digest = await dependencies.hasher.caller.invoke(
255
+ d => d.functions.digest,
115
256
  { mediaType: file.type },
116
257
  { body: file },
117
258
  )
118
- await kernel.invoke(uploadReference, { mediaType: file.type }, { body: file })
119
- await kernel.call({ target: uploadReference.target, input: { mediaType: file.type } }, { body: file })
259
+ await kernel.invoke(digestReference, { mediaType: file.type }, { body: file })
260
+ await kernel.call({ target: digestReference.target, input: { mediaType: file.type } }, { body: file })
120
261
  ```
121
262
 
122
263
  The typed `invoke` overload requires `body` for a binary Function and forbids it for a value-input
123
264
  Function. Raw `call` and `dispatch` also accept `{ body }`; the Server checks the resolved Function
124
265
  contract. A binary input cannot use `idempotencyKey`.
125
266
 
126
- ### Storing a received file
127
-
128
- `ctx.body` is the Kernel's own binary request body, `{ body: ReadableStream<Uint8Array>, length }`,
129
- and `kernel.content.upload` accepts it as its source. Hand it over unread: the upload streams the
130
- bytes to the Kernel as they arrive, so a Worker stores a file far larger than it could hold in
131
- memory. Decoding Base64 from a JSON input and uploading the resulting `Uint8Array` holds the whole
132
- file, several times over, in memory.
133
-
134
- ```ts
135
- const schema = defineSchema('files.example', {
136
- name: 'Files',
137
- functions: {
138
- attach: func({
139
- auth: 'authenticated',
140
- // Methods cannot take a binary input: the target Node travels in the metadata.
141
- input: input.binary(z.strictObject({ document: z.string(), mediaType: z.string() }), {
142
- maximumBytes: 100 * 1024 * 1024,
143
- }),
144
- output: z.null(),
145
- }),
146
- },
147
- })
148
-
149
- export const attach = defineWorkflow<typeof schema>()(
150
- 'attach',
151
- async ({ body, graph, input, kernel, step }) => {
152
- const receipt = await step.run('store-file', async () => {
153
- const uploaded = await kernel.caller.content.upload(body, { mediaType: input.mediaType })
154
- return uploaded.receipt
155
- })
156
- await step.run('record-file', () =>
157
- graph.caller.mutate(recordFile, { document: NodeId(input.document), receipt }),
158
- )
159
- return null
160
- },
161
- )
162
- ```
163
-
164
- `recordFile` stands for the Domain's own Mutation that sets the blob Property from the receipt. The
165
- rules:
166
-
167
- - **One attempt.** A stream is read once, so its upload is never retried, follows no Redirect, and
168
- is cancelled when it fails before reading through its end. A failed upload rejects, and only the
169
- caller can send the file again. Do not wrap the upload in a retry, do not read or `tee()` the body
170
- first, and do not upload it from a durable Workflow, whose Steps are retried: store it in an Action
171
- or in a Step of an inline Workflow, as above.
267
+ - **One reader.** `ctx.body` is the Kernel's own binary request body, `{ body:
268
+ ReadableStream<Uint8Array>, length }`. It is read once: do not `tee()` it or read it from a
269
+ durable Workflow, whose Steps are retried. `kernel.content.upload` still accepts it unread, and
270
+ streams it to the Kernel as it arrives in one attempt that is never retried, but a file the Domain
271
+ stores belongs in a `file()` field.
172
272
  - **The declared length is exact.** The Server admits the body against the length its caller
173
- declared and the upload sends exactly `length` bytes; a body that ends early or runs over fails.
273
+ declared; a body that ends early or runs over fails.
174
274
  - **Declare `maximumBytes` on each binary Function.** It bounds what that Function accepts, and is
175
- checked against the declared length before the handler runs. Keep it within the `maxBytes` of
176
- the blob Property the file is stored in, and within the Kernel's 100 MiB blob limit when the
177
- file goes to the Kernel: the Kernel refuses an upload past either, but only once the request has
178
- reached the handler.
275
+ checked against the declared length before the handler runs.
179
276
  - **The deployment follows the Domain.** The Server also caps every streamed request, before any
180
277
  Function is chosen, with its `maximumBinaryRequestBytes`. A Worker built by the Cloudflare
181
278
  adapter sets it to the largest `maximumBytes` among its Domain's binary Functions, so its
182
279
  `maximumRequestBytes` (1 MiB by default, 16 MiB at most) bounds only the bodies it buffers. A
183
280
  larger body is refused with `413` and `LIMIT_EXCEEDED` before the handler runs. A binary request
184
281
  lives up to 30 minutes, or the deployment's `invocationTimeoutMs` when that is longer, and is
185
- cancelled after 60 seconds without a new chunk while the handler reads it; the Kernel's own
186
- Server gives an upload the same budget. A Domain without a binary Function keeps the Server
187
- defaults. A host that composes `serve()` itself states these in its `server.limits`
188
- (`maximumBinaryRequestBytes`, `binaryRequestTimeoutMs`, `binaryRequestIdleTimeoutMs`).
189
- Cloudflare refuses a request body past its plan's limit before the Worker runs: 100 MB on Free
190
- and Pro, 200 MB on Business, more on Enterprise. 100 MiB is 104,857,600 bytes, slightly above
191
- 100 MB, so on Free and Pro declare at most `100_000_000`.
282
+ cancelled after 60 seconds without a new chunk while the handler reads it. A Domain without a
283
+ binary Function keeps the Server defaults. A host that composes `serve()` itself states these in
284
+ its `server.limits` (`maximumBinaryRequestBytes`, `binaryRequestTimeoutMs`,
285
+ `binaryRequestIdleTimeoutMs`). Cloudflare refuses a request body past its plan's limit before the
286
+ Worker runs: 100 MB on Free and Pro, 200 MB on Business, more on Enterprise.
192
287
  - **Methods cannot take a binary input.** Declare a Function that names its target Node in the
193
- metadata, and let the caller's authority decide: upload with `kernel.caller` and record with
194
- `graph.caller`, so the Kernel applies the caller's permissions to both.
195
- - **Receipts expire.** Record the receipt (`expiresAt`) right after the upload, in the same
196
- invocation.
288
+ metadata.
197
289
 
198
290
  `domain.dependencies` remains immutable loaded Schema metadata. `dependencies` is a separate frozen
199
291
  map containing only direct non-Kernel aliases. Each alias exposes exactly `.caller` and `.self`,
@@ -247,8 +339,8 @@ const shipment = await step.run('ship', ({ dependencies }) =>
247
339
  )
248
340
  ```
249
341
 
250
- Inline Steps do not imply a distributed transaction, durable replay, or remote deduplication. Stream and
251
- binary objects cannot become portable step results; a native streaming response belongs in an
342
+ Inline Steps do not imply a distributed transaction, durable replay, or remote deduplication. Stream,
343
+ binary, and received file objects cannot become portable step results; a native streaming response belongs in an
252
344
  Action. Invocation sessions remain open until a returned stream or binary body settles.
253
345
 
254
346
  Integrations remain useful for consumer-owned substitution, replay metadata, or failure translation.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astrale-os/sdk",
3
- "version": "0.6.0-beta.53",
3
+ "version": "0.6.0-beta.55",
4
4
  "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
5
5
  "keywords": [
6
6
  "astrale",
@@ -258,11 +258,11 @@
258
258
  "registry": "https://registry.npmjs.org/"
259
259
  },
260
260
  "dependencies": {
261
- "@astrale-os/kernel-client": "1.0.0-beta.37",
262
- "@astrale-os/kernel-core": "1.0.0-beta.34",
263
- "@astrale-os/kernel-dsl": "1.0.0-beta.22",
264
- "@astrale-os/kernel-protocol": "1.0.0-beta.34",
265
- "@astrale-os/kernel-server": "1.0.0-beta.34",
261
+ "@astrale-os/kernel-client": "1.0.0-beta.38",
262
+ "@astrale-os/kernel-core": "1.0.0-beta.35",
263
+ "@astrale-os/kernel-dsl": "1.0.0-beta.23",
264
+ "@astrale-os/kernel-protocol": "1.0.0-beta.35",
265
+ "@astrale-os/kernel-server": "1.0.0-beta.35",
266
266
  "@lucide/icons": "1.34.0",
267
267
  "@typescript/native-preview": "7.0.0-dev.20260707.2",
268
268
  "cross-spawn": "7.0.6",