@astrale-os/sdk 0.6.0-beta.50 → 0.6.0-beta.52

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.
@@ -7,11 +7,16 @@ export interface CheckQueryOptions {
7
7
  * against, or its Schema alone, which holds no requirements, so S12 is not checked.
8
8
  */
9
9
  readonly domain: DomainDefinitionIdentity | schema.DomainSchema;
10
+ /**
11
+ * The authority the Query is called with. `caller`, the default, checks S12 as a read for the
12
+ * caller is checked; `executor` reads as the Domain itself, which S12 does not check.
13
+ */
14
+ readonly as?: 'executor' | 'caller';
10
15
  }
11
16
  /**
12
17
  * Build a Query for `sampleInput` and lower its first step, as a call would, without a Kernel:
13
18
  * it throws what the call would raise before sending, a bound past S11 (`QueryError` `TOO_MANY` or
14
- * `INPUT_INVALID`), a relation across a Class the Domain's definition does not declare (S12), or a
15
- * step that does not build.
19
+ * `INPUT_INVALID`), a relation of a read for the caller that the Domain's definition does not
20
+ * declare (S12), or a step that does not build.
16
21
  */
17
22
  export declare function checkQuery<R extends DefinedQuery>(query: R, sampleInput: InputOf<R>, options: CheckQueryOptions): void;
@@ -11,8 +11,8 @@ const NO_KERNEL = Object.freeze({
11
11
  /**
12
12
  * Build a Query for `sampleInput` and lower its first step, as a call would, without a Kernel:
13
13
  * it throws what the call would raise before sending, a bound past S11 (`QueryError` `TOO_MANY` or
14
- * `INPUT_INVALID`), a relation across a Class the Domain's definition does not declare (S12), or a
15
- * step that does not build.
14
+ * `INPUT_INVALID`), a relation of a read for the caller that the Domain's definition does not
15
+ * declare (S12), or a step that does not build.
16
16
  */
17
17
  export function checkQuery(query, sampleInput, options) {
18
18
  const spec = querySpecOf(query);
@@ -22,7 +22,8 @@ export function checkQuery(query, sampleInput, options) {
22
22
  const domain = schemaApi.resolve(definition?.schema ?? options?.domain);
23
23
  // A definition types its requirements as written; the check reads any.
24
24
  const requirements = definition?.requirements;
25
- const declared = definition === undefined ? undefined : (requirements?.classes ?? []);
25
+ const checked = definition !== undefined && options?.as !== 'executor';
26
+ const declared = checked ? (requirements?.classes ?? []) : undefined;
26
27
  const run = new Run(NO_KERNEL, domain, query.id, declared);
27
28
  const build = spec.build;
28
29
  const built = build(sampleInput, handlesOf(domain), stepsFor(query.id));
package/docs/queries.md CHANGED
@@ -156,8 +156,8 @@ with `.via(edge, { direction })`, where `direction` is `outgoing`, `incoming` or
156
156
  `.via([e1, e2])` reads several Edge Classes. `direction` is required when both ends accept the
157
157
  Class, or when the Edges listed leave it in different directions.
158
158
 
159
- A relation reads with the root verbs, per parent row: `get`, `find`, `first`, `all`, `count` and
160
- `exists`. A relation's `get` that finds none, or a second row, raises `INTEGRITY` naming the
159
+ A relation reads with the root verbs, per parent row: `get`, `find`, `first`,
160
+ `first(n, { more: true })`, `all`, `count` and `exists`. A relation's `get` that finds none, or a second row, raises `INTEGRITY` naming the
161
161
  relation. A relation also takes `where`, `orderBy`, `with`, `ref`, `includeWithheld`, `distinct`
162
162
  and `withEdge()`, which adds the Edge's Class and Properties to each row under `$edge`.
163
163
 
@@ -180,8 +180,7 @@ declares none of its own, each go under `$` and their owner's name in lower came
180
180
 
181
181
  An Edge read at the root answers rows of `{ $class, $source, $target }`, the Edge's Properties,
182
182
  and both ends' rows under their roles. `edgeKey(row)` gives the `{ source, target, class }` a
183
- Mutation or a guard names an Edge by. An Edge root's `get()`, `find()` and `exists()` take no id,
184
- and its `first(n)` takes no `{ more }`.
183
+ Mutation or a guard names an Edge by. An Edge root's `get()`, `find()` and `exists()` take no id.
185
184
 
186
185
  An undirected Edge's ends have no order: neither of its roles is kept at a fixed end. A condition
187
186
  on its roles holds when one pairing of the Edge's two ends with its two roles meets the whole
@@ -259,10 +258,20 @@ const second = first.next
259
258
  : undefined
260
259
  ```
261
260
 
261
+ `query.all(query, input, { as, max })` reads every row of a page Query, page after page, and
262
+ answers the rows of its `output`; past `max` rows, it raises `TOO_MANY` as `all({ max })` does.
263
+ Each page is a read of its own, at its own snapshot and within its own bounds, and asks for no more
264
+ rows than `max` leaves, plus one:
265
+
266
+ ```ts
267
+ const titles = await query.all(articleTitles, undefined, { as: 'caller', max: 5_000 })
268
+ ```
269
+
262
270
  A durable Workflow reads in a Step, as its executor:
263
271
  `step.query('load-article', articleById, input.article, { as: 'executor' })`. The output is
264
- journaled, and a replay returns it. A `QueryError` other than `REFUSED`, or the `TypeError` of an
265
- undeclared crossing (S12), fails the Step at once, and a replay throws it again. A `REFUSED` read
272
+ journaled, and a replay returns it. A `QueryError` other than `REFUSED` fails the Step at once,
273
+ and a replay throws it again; so does the `TypeError` of an undeclared crossing (S12) a journal
274
+ holds. A Step reads as the Domain itself, which S12 does not check. A `REFUSED` read
266
275
  is a failed attempt like any Kernel refusal: a permanent one exhausts the Step at once, and a
267
276
  stale snapshot spends no attempt. An inline Workflow calls `query(query, input, { as })` from its
268
277
  context, as an Action does, inside a named `step.run`.
@@ -277,7 +286,7 @@ of that code:
277
286
  | `NOT_FOUND` | A root `get` found nothing. | `class`; `target` when the read named one |
278
287
  | `NOT_READABLE` | `get` or `find` met a fact the reader may not read. | `class`; `id`, a Node's id or an Edge's key |
279
288
  | `INTEGRITY` | A relation's `get` found none, or a second row came where one is allowed. | `relation`; `parent` for a relation; `found: 0 \| 2` |
280
- | `TOO_MANY` | Past a verb's `max`, a verb bound of 83,332, the Query's 100,000 rows or its 32 reads; or an answer past the bytes one response may carry. | `limit: 'max' \| 'rows' \| 'reads' \| 'bytes'`; `bound` |
289
+ | `TOO_MANY` | Past a verb's `max` or `query.all`'s, a verb bound of 83,332, the Query's 100,000 rows or its 32 reads; or an answer past the bytes one response may carry. | `limit: 'max' \| 'rows' \| 'reads' \| 'bytes'`; `bound` |
281
290
  | `REFUSED` | The Kernel refused the read. | `kernelCode`; `retryable`, whether a retry may succeed |
282
291
  | `INPUT_INVALID` | The SDK or the Kernel refused the document the Query built, before reading anything. | `kernelCode`, `phase` and `path` when the Kernel names them; `limit: 'in'` for an `in` past 16 values |
283
292
  | `OUTDATED` | The Host's Registry does not match the Domain's build. | `kernelCode: 'QUERY_EXPECTATION_MISMATCH'` |
@@ -327,17 +336,25 @@ Before a step sends anything, the SDK checks:
327
336
  the read raises `TOO_MANY`. An `in` takes at most 16 values; past them, it raises
328
337
  `INPUT_INVALID`. Fewer than 2 or more than 8 steps do not compile, and `steps` throws a
329
338
  `TypeError` when `build` calls it.
330
- - **Requirements (S12).** A relation that crosses a Class of a direct dependency needs `read` and
331
- `traverse` on that Class in the Domain's `requirements({ classes })`. A requirement on a parent
332
- covers its children. Otherwise the call throws a `TypeError` naming the Query, the relation and
333
- the requirement to add. Roots, Kernel Classes and the Domain's own Classes need nothing. A
339
+ - **Requirements (S12).** A read `{ as: 'caller' }` answers only what both the caller and the
340
+ Domain may observe, and leaves out the rest without saying so. Of a Class of a direct
341
+ dependency whose read and traverse rules both admit only some callers, a relation that crosses
342
+ it needs `read` or `traverse` on it in the Domain's `requirements({ classes })`. Of one whose
343
+ read rule admits only some callers, a relation's condition that tests one of its values needs
344
+ `read` on it: the Kernel drops what that test cannot decide. Otherwise the call throws a
345
+ `TypeError` naming the Query, the relation and the requirement to add. A rule that admits every
346
+ caller (`true`, or none) needs nothing. A requirement covers its own Class only, as the Kernel's
347
+ grants do; a Class a relation reaches stands for each concrete Class under it, itself when
348
+ concrete. Roots, Kernel Classes and the Domain's own Classes need nothing. A read
349
+ `{ as: 'executor' }` is the Domain's own, which no requirement changes: it is not checked. A
334
350
  relation an empty list folds away is checked as if the list were not empty. A condition the
335
351
  input leaves unbuilt, such as a falsy `where` entry or an `undefined` facet, is not checked.
336
352
 
337
- `checkQuery(query, sampleInput, { domain })` from `@astrale-os/sdk/testing` runs both checks in
338
- a test, without a Kernel, on the first step it builds for its sample input. Give it an input that
339
- builds every optional condition, and test later steps through a call. Given the Domain's
340
- definition it checks S12; given the Schema alone it skips S12.
353
+ `checkQuery(query, sampleInput, { domain, as? })` from `@astrale-os/sdk/testing` runs both
354
+ checks in a test, without a Kernel, on the first step it builds for its sample input. Give it an
355
+ input that builds every optional condition, and test later steps through a call. Given the
356
+ Domain's definition it checks S12 as a read for the caller is checked; `as: 'executor'` and the
357
+ Schema alone skip S12.
341
358
 
342
359
  Neither check sees an answer's size. One answer is bounded in bytes, 16 MiB by default, by the Host
343
360
  that sends it and by the Kernel client that receives it (`maximumResponseBytes`). Over HTTP, past
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astrale-os/sdk",
3
- "version": "0.6.0-beta.50",
3
+ "version": "0.6.0-beta.52",
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.32",
262
- "@astrale-os/kernel-core": "1.0.0-beta.29",
263
- "@astrale-os/kernel-dsl": "1.0.0-beta.20",
264
- "@astrale-os/kernel-protocol": "1.0.0-beta.29",
265
- "@astrale-os/kernel-server": "1.0.0-beta.29",
261
+ "@astrale-os/kernel-client": "1.0.0-beta.36",
262
+ "@astrale-os/kernel-core": "1.0.0-beta.33",
263
+ "@astrale-os/kernel-dsl": "1.0.0-beta.21",
264
+ "@astrale-os/kernel-protocol": "1.0.0-beta.33",
265
+ "@astrale-os/kernel-server": "1.0.0-beta.33",
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",
@@ -275,11 +275,11 @@
275
275
  "@astrale-os/ox": "0.1.4",
276
276
  "@astrale/commitlint-config": "npm:@jsr/astrale__commitlint-config@~2.0.5",
277
277
  "@astrale/typescript-config": "npm:@jsr/astrale__typescript-config@~2.0.0",
278
- "@cloudflare/workers-types": "^5.20260820.1",
278
+ "@cloudflare/workers-types": "^5.20261023.1",
279
279
  "@commitlint/cli": "~21.2.2",
280
280
  "@commitlint/config-conventional": "~21.2.2",
281
281
  "@hono/node-server": "^2.1.1",
282
- "@hono/node-server-v1": "npm:@hono/node-server@1.19.0",
282
+ "@hono/node-server-v1": "npm:@hono/node-server@1.19.10",
283
283
  "@restatedev/restate-sdk": "1.17.0",
284
284
  "@restatedev/restate-sdk-cloudflare-workers": "1.17.0",
285
285
  "@types/cross-spawn": "6.0.6",
@@ -288,12 +288,12 @@
288
288
  "husky": "~9.1.7",
289
289
  "lint-staged": "~17.3.0",
290
290
  "mermaid": "^11.16.1",
291
- "miniflare": "5.20260811.1-alpha",
292
- "oxfmt": "0.63.0",
291
+ "miniflare": "5.20261023.0-beta",
292
+ "oxfmt": "0.67.0",
293
293
  "oxlint": "1.78.0",
294
294
  "preact": "^10.29.8",
295
295
  "tsx": "^4.23.12",
296
- "vite": "^8.2.1",
296
+ "vite": "^8.2.4",
297
297
  "vitest": "^5.0.1",
298
298
  "yaml": "^2.9.0",
299
299
  "zod": "4.4.3"