@tinkered/core 0.0.0-stage → 0.18.0
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 +1720 -2
- package/dist/index.d.mts +219 -0
- package/dist/index.mjs +1 -0
- package/dist/rolldown-runtime-DK3Fl9T5.mjs +1 -0
- package/dist/rpc-BM2DzB6v.mjs +1 -0
- package/dist/rpc-transport-B3ibUqHk.d.mts +1699 -0
- package/dist/src-BRC-UQNd.mjs +1 -0
- package/dist/testing.d.mts +155 -0
- package/dist/testing.mjs +1 -0
- package/package.json +58 -4
- package/skills/core/SKILL.md +102 -0
- package/skills/core/capsule/SKILL.md +180 -0
- package/skills/core/data/SKILL.md +189 -0
- package/skills/core/operation/SKILL.md +172 -0
- package/skills/core/rpc/SKILL.md +203 -0
- package/skills/core/testing/SKILL.md +189 -0
package/README.md
CHANGED
|
@@ -1,3 +1,1721 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @tinkered/core
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## Install
|
|
4
|
+
|
|
5
|
+
On Bun, the main runtime:
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
R=https://github.com/lagz0ne/tinkered/\
|
|
9
|
+
releases/download/v0.18.0
|
|
10
|
+
bun add $R/tinker-core-0.18.0.tgz
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
On Node 22.18 or later, with npm:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
R=https://github.com/lagz0ne/tinkered/\
|
|
17
|
+
releases/download/v0.18.0
|
|
18
|
+
npm install $R/tinker-core-0.18.0.tgz
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Each version's URLs are in the
|
|
22
|
+
[changelog](../../CHANGELOG.md).
|
|
23
|
+
|
|
24
|
+
## Scope handles
|
|
25
|
+
|
|
26
|
+
A scope handle is passed by reference (ADR 0108).
|
|
27
|
+
Do not copy it with spread or pull out its verbs.
|
|
28
|
+
|
|
29
|
+
Plain scopes and both session forms share their verbs on one prototype,
|
|
30
|
+
the object they inherit from.
|
|
31
|
+
Opening and closing a plain scope makes no own verb functions.
|
|
32
|
+
|
|
33
|
+
Only `release` may be passed on its own, as in `cells.forEach(scope.release)`.
|
|
34
|
+
Its function is tied to the handle.
|
|
35
|
+
It is made on first read and kept for later reads.
|
|
36
|
+
|
|
37
|
+
## Test helpers
|
|
38
|
+
|
|
39
|
+
The main entry exports no test helpers.
|
|
40
|
+
Import them from `@tinkered/core/testing`:
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
import { createScope, data } from "@tinkered/core";
|
|
44
|
+
import { makeTestClock } from "@tinkered/core/testing";
|
|
45
|
+
import { makeTestRandom } from "@tinkered/core/testing";
|
|
46
|
+
import { preset } from "@tinkered/core/testing";
|
|
47
|
+
import type * as Core from "@tinkered/core";
|
|
48
|
+
import type { Clock, Random } from "@tinkered/core/testing";
|
|
49
|
+
|
|
50
|
+
const time: Clock.Options = { now: 100 };
|
|
51
|
+
const seed: Random.Options = { seed: 42 };
|
|
52
|
+
const clock: Clock.Test = makeTestClock(time);
|
|
53
|
+
const random: Core.Random.Handle = makeTestRandom(seed);
|
|
54
|
+
const source: Core.Clock.Handle = clock;
|
|
55
|
+
const count = data({ initial: 0 });
|
|
56
|
+
const scope = createScope({
|
|
57
|
+
clock: source,
|
|
58
|
+
random,
|
|
59
|
+
presets: [preset(count, 3)],
|
|
60
|
+
});
|
|
61
|
+
await scope.close();
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
`Clock.Handle` and `Random.Handle` stay in `@tinkered/core`.
|
|
65
|
+
`Clock.Test`, `Clock.Options`, and `Random.Options` live in
|
|
66
|
+
`@tinkered/core/testing`.
|
|
67
|
+
`preset` also lives in `@tinkered/core/testing`.
|
|
68
|
+
`Scope.Preset` and the scope's `presets` option stay in
|
|
69
|
+
`@tinkered/core`.
|
|
70
|
+
The test entry ships in the package beside the main entry.
|
|
71
|
+
Test files and source files do not ship.
|
|
72
|
+
|
|
73
|
+
### Test tooling
|
|
74
|
+
|
|
75
|
+
A capsule's author ships test tooling as a plain capsule
|
|
76
|
+
in a `*.testing.ts` file (ADR 0131). Only test files import
|
|
77
|
+
it, so a prod build leaves it out. An app's build check
|
|
78
|
+
refuses any `*.testing.ts` file in a prod bundle.
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
// auth.testing.ts
|
|
82
|
+
const signIn = operation({
|
|
83
|
+
label: "auth.testing.signIn",
|
|
84
|
+
depends: { verify: auth.verify },
|
|
85
|
+
run: ({ verify }) => verify.run({ input: TEST_CODE }),
|
|
86
|
+
});
|
|
87
|
+
|
|
88
|
+
export const authTesting = capsule({
|
|
89
|
+
label: "auth.testing",
|
|
90
|
+
exports: { signIn },
|
|
91
|
+
});
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
// auth.test.ts
|
|
96
|
+
await using app = createScope({
|
|
97
|
+
capsules: [auth({ api: fakeApi }), authTesting],
|
|
98
|
+
});
|
|
99
|
+
await app.run(authTesting.signIn);
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
- Its label is `auth.testing`.
|
|
103
|
+
- It takes `config`, `tags`, `exports`, and `hooks`, as a capsule does.
|
|
104
|
+
- It reaches `auth` through its exports only.
|
|
105
|
+
- Its ops reach `auth` through `auth`'s exports.
|
|
106
|
+
- So without `auth` installed, such a run raises `CapsuleMissing`.
|
|
107
|
+
|
|
108
|
+
## Operation input
|
|
109
|
+
|
|
110
|
+
Pass outside data with `scope.run(op, { rawInput: value })`. Core runs the operation's
|
|
111
|
+
input reader before its body. Pass an already typed value with
|
|
112
|
+
`scope.run(op, { input: typedValue })`; that path trusts the value and skips parsing.
|
|
113
|
+
Tests of rejected outside input should use `rawInput` or the real HTTP/CLI/tool entry.
|
|
114
|
+
|
|
115
|
+
An operation needs no `input` reader when its caller builds the value. The slot it fills
|
|
116
|
+
names the type, and that annotation types `ctx.input` — no reader, no cast:
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
const guard: Tinkerer.Gate = operation({
|
|
120
|
+
label: "guard",
|
|
121
|
+
depends: { allowed },
|
|
122
|
+
run: (_deps, ctx) => ({
|
|
123
|
+
allow: ctx.input.mode !== "read-only",
|
|
124
|
+
}),
|
|
125
|
+
});
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
`rawInput` belongs to an operation that parses: it is the process edge. Handing `rawInput`
|
|
129
|
+
to an operation with no reader leaves `ctx.input` `undefined` — there is nothing to parse
|
|
130
|
+
it with. A frame that builds the value calls `{ input }`.
|
|
131
|
+
|
|
132
|
+
Every `parse` slot (`data`, `tag`, an operation's `input`) takes one of two shapes:
|
|
133
|
+
|
|
134
|
+
- a function `(raw: unknown) => T` that returns the value or throws;
|
|
135
|
+
- a Standard Schema object (zod, valibot, arktype) passed as-is: `input: z.object({ ... })`.
|
|
136
|
+
|
|
137
|
+
A schema's refusal arrives as the `DataValidationFailed` cause: `SchemaRejected { issues }`.
|
|
138
|
+
A schema that answers with a promise is refused with `SchemaAsync { vendor }`; every edge parses
|
|
139
|
+
before it runs.
|
|
140
|
+
|
|
141
|
+
A run passes objects the way a function call does: no copy.
|
|
142
|
+
|
|
143
|
+
- `{ input: obj }` reaches `ctx.input` as `obj` itself. Core never copies it or freezes it.
|
|
144
|
+
- `{ rawInput: obj }` reaches `ctx.rawInput` as `obj`. `ctx.input` is what the parser returns.
|
|
145
|
+
- The caller gets the body's return value itself, or a promise of it.
|
|
146
|
+
- This holds for a scope run, a session run, and a controller run, tagged or namespaced.
|
|
147
|
+
- So a body that changes its input changes the caller's object.
|
|
148
|
+
|
|
149
|
+
## Root lifetime
|
|
150
|
+
|
|
151
|
+
A root given `capsules` has a starting type (ADR 0127, ADR 0128):
|
|
152
|
+
|
|
153
|
+
```ts
|
|
154
|
+
await using app = createScope({ capsules: [db] });
|
|
155
|
+
const rows = await app.run(listRows);
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
```ts
|
|
159
|
+
const live = await createScope({ capsules: [db] }).ready;
|
|
160
|
+
const now = live.run(countRows);
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
- On `app`, `run`, `settle`, `session` and `controller(op).run`
|
|
164
|
+
always return a promise.
|
|
165
|
+
- A call made before start ends waits for start.
|
|
166
|
+
- After a failed start or a close, a waiting `run` raises `Disposed`.
|
|
167
|
+
- A waiting `settle` returns its result; it never throws.
|
|
168
|
+
- `ready` resolves to the started handle; its sync calls stay sync.
|
|
169
|
+
- `isStarting(scope)` tells the two apart.
|
|
170
|
+
- A root with no `capsules` is a plain handle, as before.
|
|
171
|
+
- `await using` closes the scope at the end of the block.
|
|
172
|
+
|
|
173
|
+
Give a root a stop signal and await its final Result (ADR 0085):
|
|
174
|
+
|
|
175
|
+
```ts
|
|
176
|
+
const scope = createScope({ ...pieces, signal: stop });
|
|
177
|
+
const end = await scope.closed;
|
|
178
|
+
process.exitCode = exitCode(end);
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
- `signal` asks the root to close gracefully once `ready` resolves.
|
|
182
|
+
An abort before or during start waits for start to end.
|
|
183
|
+
The root stays usable until then.
|
|
184
|
+
In-flight work can finish; the stop never aborts `ctx.signal`.
|
|
185
|
+
A waiting run hook and its cleanup count as in-flight work.
|
|
186
|
+
- A failed start records its error and closes through the handle's current `close`.
|
|
187
|
+
Every close hook runs, including its after-work.
|
|
188
|
+
`ready` rejects with the start error only after that forced close ends.
|
|
189
|
+
A close already under way in core wins; the failed start joins it without running hooks again.
|
|
190
|
+
An abort adds no second close once a close reaches core.
|
|
191
|
+
A replaced `close` that waits first (NATS drains) is seen only when it calls core's close.
|
|
192
|
+
- The root drops its abort listener as soon as a close reaches core, before the hooks run.
|
|
193
|
+
A signal close runs each hook with `graceful: true`.
|
|
194
|
+
A later forced close joins it and keeps its Result.
|
|
195
|
+
- Only a root given a `signal` has `closed`; sessions take no stop signal.
|
|
196
|
+
`closed` stays pending while open, settles once, and never rejects.
|
|
197
|
+
It holds core's own Result after the close hooks finish their after-work.
|
|
198
|
+
A hook's returned substitute does not change it.
|
|
199
|
+
Each ordinary `close()` shares that Result; the first call's `withData` wins.
|
|
200
|
+
- Root close hooks run once, even across repeated close calls.
|
|
201
|
+
Skipping `next()` still runs inner hooks and resource cleanup.
|
|
202
|
+
Repeating `next()` joins its first call.
|
|
203
|
+
A hook cannot replace Core's Result.
|
|
204
|
+
A hook's throw is a teardown error in both `close()` and `closed`.
|
|
205
|
+
Both wait for every close hook's after-work.
|
|
206
|
+
|
|
207
|
+
The exit-code choice stays outside core.
|
|
208
|
+
Stack uses 1 for a failed Result or any teardown error, and 0 otherwise.
|
|
209
|
+
A cancelled Result is a clean stop there.
|
|
210
|
+
Process keeps its own forced stop and exit code 130.
|
|
211
|
+
|
|
212
|
+
```ts
|
|
213
|
+
import type { Scope } from "@tinkered/core";
|
|
214
|
+
|
|
215
|
+
function exitCode(end: Scope.Result): number {
|
|
216
|
+
if (end.status === "failed") return 1;
|
|
217
|
+
if (end.teardownErrors?.length) return 1;
|
|
218
|
+
return 0;
|
|
219
|
+
}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## Capsules
|
|
223
|
+
|
|
224
|
+
A capsule is a library's door (ADR 0121).
|
|
225
|
+
It holds the library's config, its hooks, and the units it exports.
|
|
226
|
+
Make one with `capsule()` and install it with `createScope({ capsules })`.
|
|
227
|
+
Wait with `await scope.ready`, then read its start value with `scope.resolve(mail)`.
|
|
228
|
+
A library that reads tags declares them as its `config` ([Config](#config)).
|
|
229
|
+
|
|
230
|
+
```ts
|
|
231
|
+
import { capsule, createScope } from "@tinkered/core";
|
|
232
|
+
|
|
233
|
+
export const mail = capsule({
|
|
234
|
+
label: "mail",
|
|
235
|
+
config: { smtpUrl, from },
|
|
236
|
+
exports: { enqueue, send },
|
|
237
|
+
hooks: {
|
|
238
|
+
start: async ({ run }) => {
|
|
239
|
+
await run(migrate, {}, {
|
|
240
|
+
role: "setup",
|
|
241
|
+
explain: "Brings the outbox up to date",
|
|
242
|
+
});
|
|
243
|
+
},
|
|
244
|
+
},
|
|
245
|
+
});
|
|
246
|
+
|
|
247
|
+
const scope = createScope({
|
|
248
|
+
capsules: [mail({ smtpUrl: url, from: "ops@example.com" })],
|
|
249
|
+
});
|
|
250
|
+
await scope.ready;
|
|
251
|
+
scope.run(mail.enqueue, { input: message });
|
|
252
|
+
await scope.close({ graceful: true });
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
A capsule with no required key is called with nothing: `health()`.
|
|
256
|
+
It also installs uncalled: `capsules: [health]`.
|
|
257
|
+
|
|
258
|
+
Start has a 10 000 ms limit on the scope clock (ADR 0119).
|
|
259
|
+
Set `createScope({ startTimeout: 5_000 })` to change it.
|
|
260
|
+
A hanging start rejects `ready` with `StartTimeout`.
|
|
261
|
+
Its payload holds the capsule's `label`.
|
|
262
|
+
Core closes the scope and runs cleanup before `ready` rejects.
|
|
263
|
+
The label names the innermost start still waiting.
|
|
264
|
+
A settled start cancels the timer.
|
|
265
|
+
Closing the root cancels it and rejects pending `ready` with the close reason.
|
|
266
|
+
Set `createScope({ startTimeout: 0 })` or `Infinity` to turn the timer off.
|
|
267
|
+
Negative limits and `NaN` raise `BadStartTimeout`.
|
|
268
|
+
Finite limits are capped at 2 147 483 647 ms.
|
|
269
|
+
A clock sleep throw or rejection leaves startup waiting without a timeout.
|
|
270
|
+
|
|
271
|
+
### Hooks
|
|
272
|
+
|
|
273
|
+
Each hook takes one event object.
|
|
274
|
+
`event.kind` names the hook and narrows its fields.
|
|
275
|
+
Common access is built on first use.
|
|
276
|
+
Reading `op`, `call`, `ns`, or `next` does not build that access.
|
|
277
|
+
|
|
278
|
+
- `start`: `next()`; returns the start value. Every start runs once, in `capsules` order.
|
|
279
|
+
- `run`: `op`, the original `call`, `next()`.
|
|
280
|
+
- `write`: `cell`, `value`, `next()`.
|
|
281
|
+
- `resolve`: `target`, `next()`.
|
|
282
|
+
- `close`: `options`, `next()` returns the close result. Close hooks run in reverse order.
|
|
283
|
+
- `session`: `handle`, `next()` returns the session result.
|
|
284
|
+
|
|
285
|
+
`resolve`, `run`, `write`, and `session` are onion middleware: install order, first is outermost.
|
|
286
|
+
A `start` that skips `next()` still lets the next start run once it returns.
|
|
287
|
+
A `close` that skips `next()` cannot skip cleanup (ADR 0085).
|
|
288
|
+
|
|
289
|
+
### What a hook reaches
|
|
290
|
+
|
|
291
|
+
Every event has `config`, `load`, `run`, and `settle`.
|
|
292
|
+
None has `resolve`, `controller`, or `scope`.
|
|
293
|
+
|
|
294
|
+
- `config`: the config values, read once after the binding, with defaults filled.
|
|
295
|
+
- `load(unit, meta, options?)`: a resource answers a promise of its value; a cell answers its
|
|
296
|
+
controller. `options.ns` reads it in that namespace; one made with `observe: false` is quiet.
|
|
297
|
+
- `run(op, options, meta)`: what `scope.run` answers, as a promise. No controller is made.
|
|
298
|
+
- `settle(op, options, meta)`: what `scope.settle` answers, as a promise.
|
|
299
|
+
|
|
300
|
+
The meta is what devtools show: `{ role, explain }`.
|
|
301
|
+
`role` is `setup`, `worker`, `handler`, or `state`.
|
|
302
|
+
Call options (`input`, `rawInput`, `signal`, `ns`, `tags`) go on the run, never in the meta.
|
|
303
|
+
|
|
304
|
+
```ts
|
|
305
|
+
const active = data({ initial: 0 });
|
|
306
|
+
const audit = capsule({
|
|
307
|
+
label: "audit",
|
|
308
|
+
hooks: {
|
|
309
|
+
run(event) {
|
|
310
|
+
const count = event.load(active, {
|
|
311
|
+
role: "state",
|
|
312
|
+
explain: "Counts runs in flight",
|
|
313
|
+
});
|
|
314
|
+
count.update((value) => value + 1);
|
|
315
|
+
event.defer((end) => {
|
|
316
|
+
event.log("finished", { status: end.status });
|
|
317
|
+
});
|
|
318
|
+
return event.next();
|
|
319
|
+
},
|
|
320
|
+
},
|
|
321
|
+
});
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
They use the hook's own owner, effective `ns` chain, trace, signal, and lifetime.
|
|
325
|
+
A controller one request loaded never serves another.
|
|
326
|
+
Run hooks share the run's trace, cancellation, and `defer` cleanup.
|
|
327
|
+
Other hooks defer cleanup to their session; start and close use the root.
|
|
328
|
+
All events also have `closing`, `signal`, `obs`, `log`, `clock`, `random`, and `raise`.
|
|
329
|
+
A namespace chain selects buckets in that owner; it does not find a sibling session.
|
|
330
|
+
A hook reads a tag through a unit that depends on it, or through a config key.
|
|
331
|
+
|
|
332
|
+
In a `close` hook, `load` reads units already built on the root until `next()` releases them.
|
|
333
|
+
After that, and for a unit never built, it raises `Disposed`.
|
|
334
|
+
|
|
335
|
+
`Capsule.Events[keyof Capsule.Events]` is the union of these event shapes.
|
|
336
|
+
`Capsule.Events["run"]` names one shape.
|
|
337
|
+
A run hook may refuse raw input before its parser runs.
|
|
338
|
+
|
|
339
|
+
One run hook serves every operation, so its event is untyped.
|
|
340
|
+
`event.is(op)` says if the run is `op`'s; a true answer gives `op`, `call`, `input`, and
|
|
341
|
+
`next()` that operation's types (ADR 0142).
|
|
342
|
+
`event.input` is the input the body gets: the caller's `input`, or its `rawInput` through the
|
|
343
|
+
operation's parser. A bad raw input raises `DataValidationFailed` at the read.
|
|
344
|
+
|
|
345
|
+
```ts
|
|
346
|
+
const tide = capsule({
|
|
347
|
+
label: "tide",
|
|
348
|
+
hooks: {
|
|
349
|
+
run(event) {
|
|
350
|
+
if (!event.is(press)) return event.next();
|
|
351
|
+
|
|
352
|
+
const hue = event.next();
|
|
353
|
+
const input = { ...event.input, hue };
|
|
354
|
+
return event.run(send, { input }, meta);
|
|
355
|
+
},
|
|
356
|
+
},
|
|
357
|
+
});
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
Graceful close joins hook waits before and after `next()`.
|
|
361
|
+
After a run finishes, a saved `next()` raises `Disposed` and starts no body.
|
|
362
|
+
A waiting hook can still use its saved `load` and `run` during graceful close.
|
|
363
|
+
Saved data controllers can read, update, and watch through the run's deferred cleanup.
|
|
364
|
+
Forced close aborts its signal and prevents a late `next()` from starting the body.
|
|
365
|
+
Resource loads through a run event retain the selected instance through hook and run cleanup.
|
|
366
|
+
A hook that starts `next()` and returns a substitute still owns that body's work.
|
|
367
|
+
That body keeps its span open until it ends; its failure still marks the span.
|
|
368
|
+
Catching a body's panic in its hook does not erase the owner's failure.
|
|
369
|
+
A hook-started run shares the active trace; a dropped failure stays on the owner.
|
|
370
|
+
`event.settle` receives a child failure without failing the owner.
|
|
371
|
+
A saved `settle` returns `cancelled` when a waiting hook is forced closed.
|
|
372
|
+
It returns `failed` with `Disposed` when called after that hook ends.
|
|
373
|
+
A run in a namespace made with `observe: false` leaves no span and no log line.
|
|
374
|
+
|
|
375
|
+
A tagged call enters its actual child before run hooks start.
|
|
376
|
+
Its session hook runs before its run hook; each runs once.
|
|
377
|
+
|
|
378
|
+
Start and close can load a root-owned resource to keep state apart across roots.
|
|
379
|
+
Concurrent and repeated closes join the same close hook once.
|
|
380
|
+
|
|
381
|
+
Resolve hooks cover direct root `resolve` calls only.
|
|
382
|
+
Session reads, dependency reads, controller reads, and event loads bypass them.
|
|
383
|
+
|
|
384
|
+
A `resolve` hook wraps snapshot reads on the root handle (skip `next()` to short-circuit with a
|
|
385
|
+
substitute):
|
|
386
|
+
|
|
387
|
+
```ts
|
|
388
|
+
const gate = capsule({
|
|
389
|
+
label: "gate",
|
|
390
|
+
hooks: {
|
|
391
|
+
resolve: (event) => (allowed ? event.next() : "denied"),
|
|
392
|
+
},
|
|
393
|
+
});
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
A `run` hook wraps every operation call, on the root or in a session (skip `next()` to refuse a
|
|
397
|
+
call with a substitute):
|
|
398
|
+
|
|
399
|
+
```ts
|
|
400
|
+
const audit = capsule({
|
|
401
|
+
label: "audit",
|
|
402
|
+
hooks: {
|
|
403
|
+
run: async (event) => {
|
|
404
|
+
console.log("before");
|
|
405
|
+
const out = await event.next();
|
|
406
|
+
console.log("after");
|
|
407
|
+
return out;
|
|
408
|
+
},
|
|
409
|
+
},
|
|
410
|
+
});
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
Await `ready` before the first `resolve(capsule)`.
|
|
414
|
+
|
|
415
|
+
A `start` can read, after `await next()`, only capsules listed after it.
|
|
416
|
+
So list a capsule that reads a server before that server: `[serve, server]`.
|
|
417
|
+
|
|
418
|
+
A `write` hook wraps cell writes at every layer (skip `next()` to refuse a write, leaving the value
|
|
419
|
+
and watchers unchanged):
|
|
420
|
+
|
|
421
|
+
```ts
|
|
422
|
+
const even = capsule({
|
|
423
|
+
label: "even",
|
|
424
|
+
hooks: {
|
|
425
|
+
write: (event) => {
|
|
426
|
+
const { value } = event;
|
|
427
|
+
if (typeof value !== "number" || value % 2 === 0) {
|
|
428
|
+
event.next();
|
|
429
|
+
}
|
|
430
|
+
},
|
|
431
|
+
},
|
|
432
|
+
});
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
A session read still skips `resolve` hooks; its runs and writes use inherited `run` and `write` hooks.
|
|
436
|
+
A root run and a session run each invoke the `run` hook once.
|
|
437
|
+
A tagged run invokes its `run` hook once with the original call, not again on its child session.
|
|
438
|
+
A subflow invokes `run` hooks once even when its caller is another operation.
|
|
439
|
+
An inline run in a session passes its original inline config to the `run` hook.
|
|
440
|
+
A `run` hook that skips `next()` stops a subflow and returns its substitute to the caller.
|
|
441
|
+
A `run` hook that throws stops a subflow before its body and throws to its caller.
|
|
442
|
+
An async `run` hook keeps a dropped subflow's rejection on the scope, not the host.
|
|
443
|
+
A root write and a session write each invoke the `write` hook once.
|
|
444
|
+
A write through a `depends: { x: cell.controller }` edge invokes the `write` hook.
|
|
445
|
+
A namespaced write invokes the `write` hook once and stores its value in that namespace.
|
|
446
|
+
Two hooks keep install order for both runs and writes on child layers.
|
|
447
|
+
|
|
448
|
+
### Exports
|
|
449
|
+
|
|
450
|
+
Exports are copied onto the handle and every binding (ADR 0057).
|
|
451
|
+
An op, a resource, or a tag is the same object: `mail.enqueue === enqueue`.
|
|
452
|
+
A cell is not. It shows as a read view (ADR 0123):
|
|
453
|
+
|
|
454
|
+
```ts
|
|
455
|
+
const talk = capsule({ label: "talk", exports: { point, clear } });
|
|
456
|
+
|
|
457
|
+
depends: { point: talk.point, clear: talk.clear }
|
|
458
|
+
// point.get(), point.watch(fn): no set
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
- A read view has no `controller` and no path to the cell.
|
|
462
|
+
- `depends`, `scope.resolve`, and a hook's `load` hand a reader: `get()` and `watch()`.
|
|
463
|
+
- `useData(talk.point)` reads it in React.
|
|
464
|
+
- A `depends` that names `talk.point.controller` is a type error, and `InvalidDependency` at
|
|
465
|
+
first touch.
|
|
466
|
+
- To change the cell from outside, call an op the capsule exports.
|
|
467
|
+
- The raw cell, imported from its own file, keeps full power. Lint `tinker/cell-write` warns
|
|
468
|
+
on `.controller` of another capsule's cell.
|
|
469
|
+
|
|
470
|
+
A value that is not a unit is a foreign export (ADR 0125), such as a React component:
|
|
471
|
+
|
|
472
|
+
```ts
|
|
473
|
+
const talk = capsule({ label: "talk", exports: { said, say, Panel } });
|
|
474
|
+
// <talk.Panel title="Talk" />
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
- It is the same object on the handle and on each binding, with its type.
|
|
478
|
+
- Core never marks, checks, or resolves it. It may be frozen.
|
|
479
|
+
- `CapsuleMissing` comes from the exported units it touches.
|
|
480
|
+
|
|
481
|
+
`label`, `config`, `hooks`, `exports`, and `tags` are reserved: a type error, and `ReservedExport`.
|
|
482
|
+
|
|
483
|
+
A capsule may carry fixed tags: `capsule({ label, tags: [side("server")] })`.
|
|
484
|
+
They take what `createScope({ tags })` takes and bind on the root at install, before the
|
|
485
|
+
command's own `tags`.
|
|
486
|
+
A tag bound twice follows the root list rule: the last binding wins, so a later capsule wins
|
|
487
|
+
over an earlier one, and the command's `tags` win over every capsule.
|
|
488
|
+
The record shows them in `tags`, by tag label.
|
|
489
|
+
|
|
490
|
+
An export needs its capsule.
|
|
491
|
+
A scope that first touches an exported unit whose capsule it does not install raises
|
|
492
|
+
`CapsuleMissing` with `{ unit, capsule }`, before any work.
|
|
493
|
+
A first touch is a run, a resolve, a `load`, or a `depends` of another unit.
|
|
494
|
+
A later run under the same root does not check again.
|
|
495
|
+
A unit that is not exported fails as before, at its first private tag (`MissingTag`).
|
|
496
|
+
|
|
497
|
+
A tag export is one the capsule binds per call, such as `http.request`.
|
|
498
|
+
It has no capsule check: an unbound one fails with `MissingTag`.
|
|
499
|
+
|
|
500
|
+
A span of an exported unit carries `attributes.capsule`.
|
|
501
|
+
A hook's log line carries `attributes.capsule`, the hook's capsule label.
|
|
502
|
+
|
|
503
|
+
### The record
|
|
504
|
+
|
|
505
|
+
`scope.capsules` is what the scope knows about each installed capsule, in `capsules` order.
|
|
506
|
+
|
|
507
|
+
```ts
|
|
508
|
+
scope.capsules[0];
|
|
509
|
+
// { label: "mail",
|
|
510
|
+
// config: { smtpUrl: "smtp://x", from: "ops@x" },
|
|
511
|
+
// tags: {},
|
|
512
|
+
// exports: ["enqueue", "send"],
|
|
513
|
+
// loaded: [{ unit: "mail.migrate",
|
|
514
|
+
// role: "setup",
|
|
515
|
+
// explain: "Brings the outbox up to date" }] }
|
|
516
|
+
```
|
|
517
|
+
|
|
518
|
+
It exists before the first `start`, and a read shows the state now.
|
|
519
|
+
A unit's first `load`, `run`, or `settle` adds one `loaded` line; a later one keeps the first meta.
|
|
520
|
+
A tag made with `secret: true` shows `"[hidden]"` for its whole value.
|
|
521
|
+
A config value that is a unit shows its label.
|
|
522
|
+
It holds no run status: runs and failures are spans.
|
|
523
|
+
|
|
524
|
+
### Config
|
|
525
|
+
|
|
526
|
+
A library reads tags to learn what it is configured against.
|
|
527
|
+
It declares them once, as its `config` (ADR 0120).
|
|
528
|
+
Calling the capsule fills the config and answers the binding a scope installs.
|
|
529
|
+
|
|
530
|
+
A key is required when its tag has no default.
|
|
531
|
+
Leaving it out is a type error: the error names the key.
|
|
532
|
+
A required key still takes `undefined`, since an env value may be unset.
|
|
533
|
+
An `undefined` value counts as unfilled, so such a key fails at start.
|
|
534
|
+
An optional key then reads its tag's default instead.
|
|
535
|
+
Use `tag.required` to make a key required whatever its tag says.
|
|
536
|
+
Use `tag.optional` to let the call leave it out.
|
|
537
|
+
Use `tag.all` for a list key: the call takes a list, and each item is one binding.
|
|
538
|
+
|
|
539
|
+
A filled key binds its tag on the root, before the app's own `tags`.
|
|
540
|
+
So a `tags` entry on the root still wins over the capsule's.
|
|
541
|
+
A list reads every binding last first, so a list key reads back in the reverse of the call's order.
|
|
542
|
+
|
|
543
|
+
A slot key holds a unit: a resource or an operation the app chooses.
|
|
544
|
+
|
|
545
|
+
```ts
|
|
546
|
+
const storeSlot = tag<Resource.Handle<Store>>({
|
|
547
|
+
label: "sync.store",
|
|
548
|
+
});
|
|
549
|
+
const migrateSlot = tag<Operation.Handle<string, void>>({
|
|
550
|
+
label: "sync.migrate",
|
|
551
|
+
});
|
|
552
|
+
|
|
553
|
+
const sync = capsule({
|
|
554
|
+
label: "sync",
|
|
555
|
+
config: { store: storeSlot, migrate: migrateSlot },
|
|
556
|
+
hooks: {
|
|
557
|
+
start: async ({ config, load, run }) => {
|
|
558
|
+
const store = await load(config.store, {
|
|
559
|
+
role: "state",
|
|
560
|
+
explain: "Holds the records",
|
|
561
|
+
});
|
|
562
|
+
const ran = await run(config.migrate, {}, {
|
|
563
|
+
role: "setup",
|
|
564
|
+
explain: "Migrates the store",
|
|
565
|
+
});
|
|
566
|
+
|
|
567
|
+
return { store, ran };
|
|
568
|
+
},
|
|
569
|
+
},
|
|
570
|
+
});
|
|
571
|
+
```
|
|
572
|
+
|
|
573
|
+
The library builds the held unit in its own start, through the scope.
|
|
574
|
+
A unit that reads the start value sees the instance the scope built, not a copy.
|
|
575
|
+
So a preset on that unit reaches every reader of it.
|
|
576
|
+
|
|
577
|
+
Core adds no owner mark on config tags. A library's index does not export them, so the app uses
|
|
578
|
+
the library through its capsule.
|
|
579
|
+
|
|
580
|
+
`createScope` checks the config once, before the root layer exists.
|
|
581
|
+
A required key written as `undefined` raises `MissingConfig` with `{ label, key }`.
|
|
582
|
+
One library installed twice on a root raises `DuplicateCapsule` with `{ label }`.
|
|
583
|
+
A bad value raises `DataValidationFailed` from the tag's own `parse`, there.
|
|
584
|
+
Resolve, run, and write add no work: the bindings sit on the root like any other tag.
|
|
585
|
+
|
|
586
|
+
`scope.resolve(sync)` and `scope.resolve(sync({ ... }))` both read the start value.
|
|
587
|
+
A binding in `depends` delivers the same start value.
|
|
588
|
+
|
|
589
|
+
A test fills config the same way, and swaps a heavy unit with a preset (ADR 0015):
|
|
590
|
+
|
|
591
|
+
```ts
|
|
592
|
+
const scope = createScope({
|
|
593
|
+
capsules: [sync({ store: sqlite, migrate })],
|
|
594
|
+
presets: [preset(sqlite, () => fakeStore)],
|
|
595
|
+
});
|
|
596
|
+
```
|
|
597
|
+
|
|
598
|
+
## Errors and panics
|
|
599
|
+
|
|
600
|
+
ADR 0067 splits failures in two:
|
|
601
|
+
|
|
602
|
+
- **error** — a managed error: an `Error` with a string `kind` and a `payload`.
|
|
603
|
+
- **panic** — anything else thrown: a `TypeError`, a bug, a primitive.
|
|
604
|
+
|
|
605
|
+
`ctx.raise(kind, payload)` throws an error. Operation and resource ctx both have it:
|
|
606
|
+
|
|
607
|
+
```ts
|
|
608
|
+
run: ({ users }, { input, raise }) =>
|
|
609
|
+
users.get(input.id) ??
|
|
610
|
+
raise("NotFound", { id: input.id }),
|
|
611
|
+
```
|
|
612
|
+
|
|
613
|
+
`raise` returns `never`. A later line sees the narrowed value only when
|
|
614
|
+
TypeScript knows the call never returns. It knows that only when every name
|
|
615
|
+
in the call has a written type. So the form decides:
|
|
616
|
+
|
|
617
|
+
- A destructured `raise(...)` does not narrow. That is TypeScript's rule;
|
|
618
|
+
no Core type changes it.
|
|
619
|
+
- `ctx.raise(...)` narrows only when the parameter is written
|
|
620
|
+
`ctx: Operation.Ctx<I>`.
|
|
621
|
+
- `return raise(...)` narrows in every form. Use it when a later line needs
|
|
622
|
+
the narrowed value.
|
|
623
|
+
|
|
624
|
+
`settle` runs like `run` but never throws. It returns a Result:
|
|
625
|
+
|
|
626
|
+
```ts
|
|
627
|
+
const r = await scope.settle(op, { input });
|
|
628
|
+
if (r.status === "failed") log(r.kind, r.origin);
|
|
629
|
+
```
|
|
630
|
+
|
|
631
|
+
- `success` carries `value`.
|
|
632
|
+
- `failed` carries `error`, `kind` (`"error"` or `"panic"`), and `origin` when known.
|
|
633
|
+
- `cancelled` carries the abort `reason`.
|
|
634
|
+
It reads like the web's `AbortError`: `String(reason)` is `"AbortError: The scope closed before this work finished."`.
|
|
635
|
+
|
|
636
|
+
The Result says what `run` would do.
|
|
637
|
+
A value returned under a forced close is `success`, as `run` returns it.
|
|
638
|
+
Only the abort `reason` thrown on an aborted scope is `cancelled`.
|
|
639
|
+
|
|
640
|
+
`scope.settle(op, call)` and a controller's `settle(call)` take the same calls as `run`.
|
|
641
|
+
A sync operation settles at once. A tagged call settles at once too when its child session ended
|
|
642
|
+
in place, and through a promise when the session must wait (ADR 0072).
|
|
643
|
+
An operation typed `unknown` may do either, so its type is a Result or a promise of one.
|
|
644
|
+
`await` it.
|
|
645
|
+
|
|
646
|
+
`originOf(error)` reads where an error was first thrown: `{ label, span?, path }`.
|
|
647
|
+
`span` is the failed span's id when the scope observes.
|
|
648
|
+
`path` lists the failed runs, outermost first.
|
|
649
|
+
It grows only while the error is in flight: a rethrown error keeps its first path.
|
|
650
|
+
A primitive throw has no origin. A failed session close carries `origin` too.
|
|
651
|
+
|
|
652
|
+
A panic is sticky.
|
|
653
|
+
It fails the layer its run ran in, at the moment the run fails.
|
|
654
|
+
A caller's `try/catch` does not undo it: the layer still closes `failed`.
|
|
655
|
+
`settle` is the one recover: a panic it receives does not fail the layer.
|
|
656
|
+
That holds at any depth, and for a panic in the received error's `cause` chain.
|
|
657
|
+
A panic caught before it reaches `settle` stays sticky.
|
|
658
|
+
An error thrown by a run is a value: a caller that catches it leaves the layer fine.
|
|
659
|
+
A failed build still fails its layer, whatever its error's kind.
|
|
660
|
+
A dropped subflow's panic fails the layer, even while its caller still runs.
|
|
661
|
+
A dropped subflow's error stays with its caller and shows on its span.
|
|
662
|
+
A root run's dropped error goes to the host as an unhandled rejection; the layer stays fine.
|
|
663
|
+
A forced close after a sticky panic settles `failed`, not `cancelled`.
|
|
664
|
+
|
|
665
|
+
### Your own error shapes
|
|
666
|
+
|
|
667
|
+
`raise` stays open for an app: any string `kind`, any object `payload`.
|
|
668
|
+
Core keeps no registry of app errors.
|
|
669
|
+
|
|
670
|
+
An app keeps each shape in its contracts. In the Hedl app, refusals live in
|
|
671
|
+
its `src/contracts/hedl/errors.ts`:
|
|
672
|
+
|
|
673
|
+
```ts
|
|
674
|
+
export const refused = "Refused" as const;
|
|
675
|
+
export type RefusedPayload = { message: string };
|
|
676
|
+
```
|
|
677
|
+
|
|
678
|
+
A body raises that kind with `satisfies`, so the payload must fit the shape:
|
|
679
|
+
|
|
680
|
+
```ts
|
|
681
|
+
run: (_deps, { raise }) => {
|
|
682
|
+
const payload = { message: "no seat" }
|
|
683
|
+
satisfies RefusedPayload;
|
|
684
|
+
return raise(refused, payload);
|
|
685
|
+
},
|
|
686
|
+
```
|
|
687
|
+
|
|
688
|
+
A caller reads `kind` and `payload` back. `settle` gives them on a Result of
|
|
689
|
+
kind `"error"`. A `catch` gets them with the app's own check.
|
|
690
|
+
|
|
691
|
+
`isError` and `Errors` cover Core's own kinds only. An app's kinds are the
|
|
692
|
+
app's to check.
|
|
693
|
+
|
|
694
|
+
## Resource cleanup
|
|
695
|
+
|
|
696
|
+
A call can own a stop signal (ADR 0090):
|
|
697
|
+
|
|
698
|
+
```ts
|
|
699
|
+
const stop = new AbortController();
|
|
700
|
+
const result = step.settle({
|
|
701
|
+
input: "check services",
|
|
702
|
+
signal: stop.signal,
|
|
703
|
+
});
|
|
704
|
+
stop.abort("new instruction");
|
|
705
|
+
const ended = await result;
|
|
706
|
+
```
|
|
707
|
+
|
|
708
|
+
- `run` and `settle` accept a call `signal`, including inline runs.
|
|
709
|
+
- The call opens a child session, just like a call with tags.
|
|
710
|
+
Its data writes and session resources belong to that child.
|
|
711
|
+
They are released before the call settles.
|
|
712
|
+
A later call gets new session resources; scope resources stay shared.
|
|
713
|
+
- Aborting the call stops its body and subflows through `ctx.signal`.
|
|
714
|
+
Work must pass that signal to its waits or check it.
|
|
715
|
+
This also stops waits, such as retry sleeps, that use `ctx.signal`.
|
|
716
|
+
- An already aborted call starts no body, parse, resource, or hook.
|
|
717
|
+
- A call stopped by its signal preserves the exact `signal.reason`.
|
|
718
|
+
`run` rejects with it; `settle` returns it after cleanup ends.
|
|
719
|
+
A different error after abort still returns `failed`.
|
|
720
|
+
A handled cancel or failure leaves the caller alive.
|
|
721
|
+
- A call keeps its input parsing, tags, and namespace.
|
|
722
|
+
The namespace selects values; the child session owns their lifetime.
|
|
723
|
+
- A call signal can still stop work while its owner closes gracefully.
|
|
724
|
+
Forced owner close stops the child even if the call signal stays live.
|
|
725
|
+
- Run and session hooks share the call's lifetime.
|
|
726
|
+
Abort blocks a late body start.
|
|
727
|
+
Graceful close keeps active run-hook access alive until the hook ends.
|
|
728
|
+
- Finishing the call removes its abort listener.
|
|
729
|
+
Calls without a signal keep their existing return shape and lifetime.
|
|
730
|
+
|
|
731
|
+
Stop in-flight work through `ctx.signal`. A forced close aborts the signal, waits for
|
|
732
|
+
in-flight operations and resource builds to settle, then runs resource `ctx.defer` hooks.
|
|
733
|
+
Waiting until `defer` to stop work that close is waiting for can deadlock.
|
|
734
|
+
|
|
735
|
+
An async factory can register `ctx.defer` after an `await`, up until its returned promise
|
|
736
|
+
settles, including while close waits for that factory. Registration after the factory has
|
|
737
|
+
settled throws `Disposed`.
|
|
738
|
+
|
|
739
|
+
After an `await`, the signal may already be aborted. Use `ctx.signal.throwIfAborted()`
|
|
740
|
+
before starting more work. When forwarding cancellation to a separate `AbortController`,
|
|
741
|
+
check `ctx.signal.aborted` first: abort it immediately if true; otherwise add the abort
|
|
742
|
+
listener. A listener added after abort will not fire. For lazy work, check again at the
|
|
743
|
+
point that actually starts it.
|
|
744
|
+
|
|
745
|
+
## Closing signal
|
|
746
|
+
|
|
747
|
+
Resources read `ctx.closing`; capsule hooks read `event.closing`.
|
|
748
|
+
It is an `AbortSignal` that fires when the owner begins closing.
|
|
749
|
+
It fires on graceful and forced close, before Core drains running work.
|
|
750
|
+
Its reason keeps the web abort name `AbortError` and code `20`.
|
|
751
|
+
Its message gives the caller a non-empty reason for the stop.
|
|
752
|
+
A parent's closing also fires in its child sessions.
|
|
753
|
+
Closing one session leaves its parent and siblings live.
|
|
754
|
+
Each owner keeps the same signal, created on first read.
|
|
755
|
+
A first read after closing began returns an aborted signal.
|
|
756
|
+
Reading a child also links its parents' controllers.
|
|
757
|
+
A tree with no reads creates no signal or controller.
|
|
758
|
+
|
|
759
|
+
A resource can end a wait it owns without blocking graceful close:
|
|
760
|
+
|
|
761
|
+
```ts
|
|
762
|
+
const waiting = resource({
|
|
763
|
+
label: "waiting",
|
|
764
|
+
factory: (_deps, { closing, defer }) => {
|
|
765
|
+
let finish = (): void => undefined;
|
|
766
|
+
const wait = new Promise<void>((resolve) => {
|
|
767
|
+
finish = resolve;
|
|
768
|
+
});
|
|
769
|
+
if (closing.aborted) finish();
|
|
770
|
+
else closing.addEventListener("abort", finish);
|
|
771
|
+
defer(() => {
|
|
772
|
+
closing.removeEventListener("abort", finish);
|
|
773
|
+
});
|
|
774
|
+
return { wait };
|
|
775
|
+
},
|
|
776
|
+
});
|
|
777
|
+
```
|
|
778
|
+
|
|
779
|
+
Running work still finishes during a graceful close.
|
|
780
|
+
`ctx.signal` keeps its work-cancellation timing.
|
|
781
|
+
`ctx.defer` still runs after the drain.
|
|
782
|
+
The close event's `scope` is the root handle whose close it observes.
|
|
783
|
+
|
|
784
|
+
## Closing and cell writes
|
|
785
|
+
|
|
786
|
+
Core seals a layer's cell writes when a forced close begins.
|
|
787
|
+
Later writes throw `Disposed`, including writes through held controllers from an abort
|
|
788
|
+
listener, an operation catch, or a resource `defer`.
|
|
789
|
+
A forced close cannot record a final status in that layer's cells.
|
|
790
|
+
Read the returned `Scope.Result` instead: a clean forced close is `cancelled`.
|
|
791
|
+
A real failure can make it `failed`.
|
|
792
|
+
|
|
793
|
+
`close({ graceful: true })` keeps state usable until running work and its cleanup finish.
|
|
794
|
+
Held cell controllers can write until that drain ends, even from outside a call.
|
|
795
|
+
A running call can call its `depends` operations, including after an await.
|
|
796
|
+
While a `session(fn)` body is running, anyone holding that handle can run or settle operations.
|
|
797
|
+
After the body returns or fails, that handle refuses calls during the drain.
|
|
798
|
+
The call's `ctx.defer` cleanup can also write and call helpers after an await.
|
|
799
|
+
This holds for a root stop signal, a direct root close, and a session close.
|
|
800
|
+
Both close modes refuse brand-new outside calls and sessions as soon as closing begins.
|
|
801
|
+
Saved operation controllers from finished calls also refuse calls during the drain.
|
|
802
|
+
A layer's `release()` and `releaseNs()` are refused during the drain.
|
|
803
|
+
A child also cannot release a resource owned by a closing parent.
|
|
804
|
+
New calls are refused before run hooks start.
|
|
805
|
+
New sessions are refused before session hooks start.
|
|
806
|
+
The closing signal still fires before the drain; the work signal stays live during graceful drain.
|
|
807
|
+
State is sealed after running calls and their cleanup finish, before resource cleanup.
|
|
808
|
+
A resource's `ctx.defer` write then becomes a `Disposed` teardown error.
|
|
809
|
+
A forced parent close also seals a child that was already closing gracefully.
|
|
810
|
+
A graceful close of a child already aborted by its parent keeps writes sealed.
|
|
811
|
+
Saved resource controllers stay usable during the drain.
|
|
812
|
+
A parent release keeps a draining child's resources usable, including named resources.
|
|
813
|
+
A draining session cannot release its parent's resource.
|
|
814
|
+
A panic from a running call's write makes `closed` report `failed`.
|
|
815
|
+
A failure received through `settle` stays recovered, as with any call.
|
|
816
|
+
Use plain `close()` when the work needs a stop signal.
|
|
817
|
+
Forced close aborts work instead of waiting for its normal finish.
|
|
818
|
+
The first close call chooses the mode.
|
|
819
|
+
A later forced close does not upgrade a graceful close already in progress.
|
|
820
|
+
|
|
821
|
+
A closed scope frees its data. `close({ withData: true })` hands it over instead (ADR 0069):
|
|
822
|
+
|
|
823
|
+
- `result.data.get(cell)` is present when the scope wrote the cell itself.
|
|
824
|
+
- It is absent for a value the scope only inherited; the parent still holds that.
|
|
825
|
+
- Every status carries `data` when asked: `success`, `cancelled`, and `failed`.
|
|
826
|
+
- `data.get(cell, { ns })` reads a named bucket, as `controller(cell, { ns })` does.
|
|
827
|
+
- Like `graceful`, `withData` is read from the first close call.
|
|
828
|
+
- A `session` hook still reads the session's cells and tags after `next()`, through `resolve`.
|
|
829
|
+
- That `resolve` also reads an ancestor's current write, or the initial value.
|
|
830
|
+
- That `resolve` takes `{ ns }` too, as `controller(cell, { ns })` does.
|
|
831
|
+
- Writes and resource reads there still throw `Disposed`.
|
|
832
|
+
- Once the hooks return, `resolve` and `controller(cell)` throw `Disposed`.
|
|
833
|
+
|
|
834
|
+
A held data controller keeps its last write alive until you drop it.
|
|
835
|
+
Once the hooks return, its reads no longer see that write.
|
|
836
|
+
They return the nearest ancestor's current write, or the initial value when no ancestor holds one.
|
|
837
|
+
|
|
838
|
+
## Sessions and cell writes
|
|
839
|
+
|
|
840
|
+
A child session inherits its parent's cells until it writes its own value. That write stays
|
|
841
|
+
in the child's copy: it does not change the parent or notify the parent's watchers. Closing
|
|
842
|
+
the child does not merge its cell values back into the parent.
|
|
843
|
+
|
|
844
|
+
A driver whose shared state belongs to the source scope must read and write through that
|
|
845
|
+
scope's handle, such as `scope.controller(cell).set(value)`. A cell controller supplied in
|
|
846
|
+
a session operation's `depends` writes to that session.
|
|
847
|
+
|
|
848
|
+
### Placed edges
|
|
849
|
+
|
|
850
|
+
The edge picks the layer a write lands on (ADR 0126).
|
|
851
|
+
The cell declares no place. The words are resource targets:
|
|
852
|
+
|
|
853
|
+
- `cell.controller`: the caller's own layer (as `session`).
|
|
854
|
+
- `cell.atNamespace.controller`: the root, in the caller's
|
|
855
|
+
namespace (as `namespace`).
|
|
856
|
+
- `cell.atScope.controller`: the root, outside any
|
|
857
|
+
namespace (as `scope`).
|
|
858
|
+
|
|
859
|
+
```ts
|
|
860
|
+
const token = data({ initial: null });
|
|
861
|
+
|
|
862
|
+
const renew = operation({
|
|
863
|
+
depends: { t: token.atScope.controller },
|
|
864
|
+
run: async ({ t }) => t.set(await refresh()),
|
|
865
|
+
});
|
|
866
|
+
|
|
867
|
+
// From a session, or a call with a `signal`:
|
|
868
|
+
await session.run(renew, { signal });
|
|
869
|
+
scope.resolve(token); // the new token
|
|
870
|
+
```
|
|
871
|
+
|
|
872
|
+
- A placed edge works from a session, a tagged call,
|
|
873
|
+
and a call with a `signal`.
|
|
874
|
+
- Nothing climbs by itself. A plain `controller` write
|
|
875
|
+
stays in its own layer.
|
|
876
|
+
- A namespace that holds its own value still reads it
|
|
877
|
+
after an `atScope` write.
|
|
878
|
+
- A read view (a capsule's cell export) has no
|
|
879
|
+
placed edge, at run time and in the types.
|
|
880
|
+
- `tinker/cell-write` flags a placed edge on another
|
|
881
|
+
capsule's raw cell.
|
|
882
|
+
- Before 0.12.0, a `scope`-target resource that takes
|
|
883
|
+
the controller wrote the root. It still works.
|
|
884
|
+
|
|
885
|
+
On an open scope, a repeat `controller(target)` read returns the same controller.
|
|
886
|
+
A controller read after close throws `Disposed`.
|
|
887
|
+
|
|
888
|
+
## Keyed data
|
|
889
|
+
|
|
890
|
+
A keyed cell holds members under keys (ADR 0135 to 0138).
|
|
891
|
+
Its `key` function reads the key from a member.
|
|
892
|
+
|
|
893
|
+
```ts
|
|
894
|
+
const tasks = data({
|
|
895
|
+
mode: "keyed",
|
|
896
|
+
parse: Task,
|
|
897
|
+
key: (t) => ({ project: t.project, id: t.id }),
|
|
898
|
+
});
|
|
899
|
+
|
|
900
|
+
const items = scope.controller(tasks);
|
|
901
|
+
items.set(task);
|
|
902
|
+
items.update({ project, id }, (t) => ({
|
|
903
|
+
...t,
|
|
904
|
+
done: true,
|
|
905
|
+
}));
|
|
906
|
+
items.delete({ project, id });
|
|
907
|
+
```
|
|
908
|
+
|
|
909
|
+
- `items.get()` reads all members, in the order they came.
|
|
910
|
+
- `of(key)` reads one member; `where(part)` reads the members whose
|
|
911
|
+
key holds the part's fields.
|
|
912
|
+
- `tasks.of(key)` and `tasks.where(part)` name a read; `scope.resolve`
|
|
913
|
+
gives its reader, and React's `useData` takes it.
|
|
914
|
+
- A write wakes the readers of its member and of its parts, and no other.
|
|
915
|
+
- `update` of a missing key raises `MissingMember`; a result with another
|
|
916
|
+
key raises `KeyChanged`; a number in a key that is not finite raises
|
|
917
|
+
`InvalidKey`.
|
|
918
|
+
|
|
919
|
+
On a `remoteData` board, a keyed cell is served by part: the first reader
|
|
920
|
+
of a part asks for it, and the guard runs at each ask. `board.invalidate`
|
|
921
|
+
marks parts dirty on either side. With `load`, the server reads each part
|
|
922
|
+
from a store and keeps no member (`docs/keyed-projector.md`).
|
|
923
|
+
|
|
924
|
+
## Tags
|
|
925
|
+
|
|
926
|
+
`scope.resolve(tag.all)` returns bindings nearest layer first, and last binding first
|
|
927
|
+
within each layer. For example, bindings `[region("first"), region("last")]` are read as
|
|
928
|
+
`["last", "first"]`. A driver that needs declaration order must arrange that order itself.
|
|
929
|
+
|
|
930
|
+
A custom binding builder names the value types it can return in `Tag.Binding<T>`. A binding
|
|
931
|
+
with a narrower value type can be assigned to one with a wider union of value types.
|
|
932
|
+
|
|
933
|
+
Every list a config takes is a `Many<T>`: one item, nothing (`null`, `undefined`, or `false`),
|
|
934
|
+
or a list of those to any depth. That covers a scope's or session's `tags`, a
|
|
935
|
+
call's `tags`, `presets`, `capsules`, and every driver's rows (`routes`, `tools`, `commands`,
|
|
936
|
+
`cells`). Core reads it once, flat, in authored order, so optional and grouped items need no
|
|
937
|
+
spread:
|
|
938
|
+
|
|
939
|
+
```ts
|
|
940
|
+
/** Only false is nothing; 0 and "" remain values. */
|
|
941
|
+
const shared = [group("net"), audit && trace(true)];
|
|
942
|
+
createScope({ tags: [region("eu"), shared] });
|
|
943
|
+
/** A single binding is a tagged call. */
|
|
944
|
+
scope.run(op, { tags: zone("us") });
|
|
945
|
+
/** An absent group is skipped. */
|
|
946
|
+
scope.createSession({
|
|
947
|
+
tags: [request(raw), wiring.tags?.(c)],
|
|
948
|
+
});
|
|
949
|
+
/** Capsules and presets take the same list shape. */
|
|
950
|
+
createScope({ capsules: [base?.capsules, mail()] });
|
|
951
|
+
```
|
|
952
|
+
|
|
953
|
+
A call whose `tags` is nothing, or a list that flattens to nothing, is an untagged call: it runs
|
|
954
|
+
inline and opens no session. A driver reads its rows with `readMany(rows)` at its seam; when the
|
|
955
|
+
rows are themselves arrays (sync's `[cell, key]` pairs) it passes the row discriminator.
|
|
956
|
+
|
|
957
|
+
## Observation
|
|
958
|
+
|
|
959
|
+
Core owns one hose for spans and log lines (ADR 0119).
|
|
960
|
+
`createScope({ observe })` adds one tap.
|
|
961
|
+
A start hook can add another with `event.tap(config)`.
|
|
962
|
+
Each tap is an `Observe.Config` and gets records made after it joins.
|
|
963
|
+
Each tap gets the same span object.
|
|
964
|
+
The hose uses the lowest tap level and largest history.
|
|
965
|
+
Each log sink still filters to its own level.
|
|
966
|
+
All taps share the first tap's clock.
|
|
967
|
+
No tap makes no spans.
|
|
968
|
+
One tap is called directly; two or more use a loop.
|
|
969
|
+
A throwing sink does not stop the other sinks.
|
|
970
|
+
|
|
971
|
+
```ts
|
|
972
|
+
const telemetry = capsule({
|
|
973
|
+
label: "telemetry",
|
|
974
|
+
hooks: {
|
|
975
|
+
start(event) {
|
|
976
|
+
event.tap({ export: sendSpan, history: 80 });
|
|
977
|
+
return event.next();
|
|
978
|
+
},
|
|
979
|
+
},
|
|
980
|
+
});
|
|
981
|
+
```
|
|
982
|
+
|
|
983
|
+
Enable `observe.history` to retain a bounded list of completed spans for `scope.spans()`.
|
|
984
|
+
Each call returns a list that keeps its entries when later runs replace the history.
|
|
985
|
+
Each resource build emits a `resource` span, so tests can count builds without a test-only
|
|
986
|
+
hook. If you keep the scope handle, its retained history is still readable after close.
|
|
987
|
+
|
|
988
|
+
When a driver creates its own scope and returns only its result (as the CLI does), pass
|
|
989
|
+
`observe.export` in the scope options before starting it. The callback receives each span
|
|
990
|
+
as it ends, including spans that finish during close; save those spans outside the driver.
|
|
991
|
+
Export works without retained history.
|
|
992
|
+
|
|
993
|
+
Each observed operation writes one step line to the `log` sink:
|
|
994
|
+
|
|
995
|
+
- `message` is the operation's label.
|
|
996
|
+
- `attributes` hold elapsed `ms` and `outcome` (`ok` or `failed`).
|
|
997
|
+
- `level` is `debug` when ok and `error` when failed; the scope's `level` can drop it.
|
|
998
|
+
- `span` is the operation's span.
|
|
999
|
+
|
|
1000
|
+
This needs observation (`export` or `history`) and a `log` sink.
|
|
1001
|
+
Resource builds write no step line.
|
|
1002
|
+
|
|
1003
|
+
Start events send logs before and after `await event.next()` to the scope's `observe.log`.
|
|
1004
|
+
They use its clock and level filter, even without span observation.
|
|
1005
|
+
The bare call uses `info`; `debug`, `info`, `warn`, and `error` pick a level.
|
|
1006
|
+
|
|
1007
|
+
Each line keeps caller attributes and sets `attributes.capsule` to the capsule's label.
|
|
1008
|
+
Start opens no span, so its log lines have `span: undefined`.
|
|
1009
|
+
Calling `event.tap` after the start chain settles raises `LateTap`.
|
|
1010
|
+
Close events use the same logger.
|
|
1011
|
+
|
|
1012
|
+
## Namespaces
|
|
1013
|
+
|
|
1014
|
+
`namespace({ observe: false })` makes a quiet bucket (ADR 0119).
|
|
1015
|
+
Operations, resource builds, nested work, and hook logs in that bucket emit no records.
|
|
1016
|
+
Use it for a tool's own sends, so they do not trace themselves.
|
|
1017
|
+
Quiet covers the call's namespace only.
|
|
1018
|
+
An explicit nested namespace uses its own setting.
|
|
1019
|
+
This keeps extra checks off plain runs.
|
|
1020
|
+
Other buckets still observe.
|
|
1021
|
+
|
|
1022
|
+
A resource factory's `ctx.ns` is the chain used for its dependencies.
|
|
1023
|
+
Scope-target resources expose no namespace; namespace and session targets expose their build chain.
|
|
1024
|
+
The default bucket exposes `undefined`.
|
|
1025
|
+
|
|
1026
|
+
`namespace(opts?)` makes a key, not a string name. Use its `tags` to bind settings
|
|
1027
|
+
for that key; use `namespace()` when only the stored values differ:
|
|
1028
|
+
|
|
1029
|
+
```ts
|
|
1030
|
+
const region = tag<string>({ label: "region" });
|
|
1031
|
+
const west = namespace({ tags: [region("west")] });
|
|
1032
|
+
const east = namespace();
|
|
1033
|
+
```
|
|
1034
|
+
|
|
1035
|
+
Pass `ns` to a run, a read, or a controller. A subflow can switch keys without
|
|
1036
|
+
leaving its caller's layer:
|
|
1037
|
+
|
|
1038
|
+
```ts
|
|
1039
|
+
scope.run(op, { input: value, ns: west });
|
|
1040
|
+
scope.resolve(region, { ns: west });
|
|
1041
|
+
scope.controller(cell, { ns: east }).set(1);
|
|
1042
|
+
// In a run with `depends: { child: op }`:
|
|
1043
|
+
child.run({ input: value, ns: east });
|
|
1044
|
+
```
|
|
1045
|
+
|
|
1046
|
+
`createSession({ ns })` sets an ambient namespace: child sessions, tagged subflows,
|
|
1047
|
+
inline runs, and controllers inherit it. An explicit `ns` changes just that call;
|
|
1048
|
+
the next call still uses the session's key:
|
|
1049
|
+
|
|
1050
|
+
```ts
|
|
1051
|
+
const request = scope.createSession({ ns: west });
|
|
1052
|
+
request.run(op); // west
|
|
1053
|
+
request.run(op, { ns: east }); // east for this call
|
|
1054
|
+
request.run(op); // west again
|
|
1055
|
+
```
|
|
1056
|
+
|
|
1057
|
+
A chain reads each named key, then the default, but checks the nearer layer
|
|
1058
|
+
before the farther one. Within each layer it checks the chain in order.
|
|
1059
|
+
A write goes to the current layer's first key, not its fallback:
|
|
1060
|
+
|
|
1061
|
+
```ts
|
|
1062
|
+
scope.controller(cell, { ns: east }).set(2);
|
|
1063
|
+
scope.resolve(cell, { ns: [west, east] }); // 2
|
|
1064
|
+
scope.controller(cell, { ns: [west, east] }).set(3);
|
|
1065
|
+
scope.resolve(cell, { ns: west }); // 3
|
|
1066
|
+
```
|
|
1067
|
+
|
|
1068
|
+
Pick a resource `target` by how long and where the value must be shared:
|
|
1069
|
+
|
|
1070
|
+
- `"scope"`: one build for everyone, regardless of namespace. Use it for a
|
|
1071
|
+
shared pool. Its build reads the root's bindings, never namespace or request tags.
|
|
1072
|
+
- `"namespace"`: one build per namespace for the scope's life, shared by
|
|
1073
|
+
request sessions. Use it for a tenant pool. Its build reads the namespace's
|
|
1074
|
+
and root tags, not the asking request's tags.
|
|
1075
|
+
- `"session"`: one build per session per namespace. Use it for a request
|
|
1076
|
+
transaction. A named bucket stays warm for later reads in that session.
|
|
1077
|
+
|
|
1078
|
+
```ts
|
|
1079
|
+
const db = resource({
|
|
1080
|
+
target: "namespace",
|
|
1081
|
+
factory: () => openDb(),
|
|
1082
|
+
});
|
|
1083
|
+
const tx = resource({
|
|
1084
|
+
target: "session",
|
|
1085
|
+
depends: { db },
|
|
1086
|
+
factory: ({ db }) => db.begin(),
|
|
1087
|
+
});
|
|
1088
|
+
```
|
|
1089
|
+
|
|
1090
|
+
`release(target)` clears all of that resource's buckets.
|
|
1091
|
+
`releaseNs(target, ns)` clears one namespace's bucket
|
|
1092
|
+
of a resource or a data cell (ADR 0063).
|
|
1093
|
+
Resources built on that bucket are released with it.
|
|
1094
|
+
Other namespaces and the default bucket stay.
|
|
1095
|
+
A `scope` resource has no namespace buckets,
|
|
1096
|
+
so `releaseNs` leaves it built.
|
|
1097
|
+
|
|
1098
|
+
```ts
|
|
1099
|
+
scope.releaseNs(pool, tenantA);
|
|
1100
|
+
```
|
|
1101
|
+
|
|
1102
|
+
The namespace tests also pin these guarantees:
|
|
1103
|
+
|
|
1104
|
+
- An ambient `createSession({ ns })` resolves there; a per-call `ns` wins for one run.
|
|
1105
|
+
- A named write lands at the current layer's first key and never notifies a default watcher.
|
|
1106
|
+
- Named calls keep the real layer lifecycle and capsule registry.
|
|
1107
|
+
- A tagged subflow in a named run uses session hooks.
|
|
1108
|
+
- Pass-through capsules preserve namespaces for writes and resolves.
|
|
1109
|
+
- A session-target resource builds once in each namespace and reuses its warm bucket.
|
|
1110
|
+
- A resource chain reuses its fallback, then switches to a nearer warm bucket.
|
|
1111
|
+
- A sync-failed named bucket is not filled by a sibling chain.
|
|
1112
|
+
- A named resource dependency reads a nearer default before a farther named entry.
|
|
1113
|
+
- Namespace resource dependencies see tenant and root tags but not request tags.
|
|
1114
|
+
- Namespace resources share a root bucket across request sessions.
|
|
1115
|
+
- Sessions without a namespace share one root default resource.
|
|
1116
|
+
- Request transactions share their tenant database but not each other.
|
|
1117
|
+
- Closing the root waits for a request and cleans each namespace bucket once.
|
|
1118
|
+
- Close waits for a named resource borrow and tears every bucket down once.
|
|
1119
|
+
- Namespace clients share one scope-target pool.
|
|
1120
|
+
- A scope-target resource is namespace-blind and keeps default storage clean.
|
|
1121
|
+
- An ambient namespace cannot enter a scope-target resource build.
|
|
1122
|
+
- Namespace-blind scope builds keep tagged operation dependencies blind.
|
|
1123
|
+
- A re-registered named watcher refreshes its comparison value.
|
|
1124
|
+
- A namespace-blind watcher observes default storage, never ambient tenant storage.
|
|
1125
|
+
- A chained watcher compares against the full resolved namespace chain.
|
|
1126
|
+
- A named write compares only its namespace watcher among a thousand.
|
|
1127
|
+
- A chain watcher sees its fallback key but not an unrelated key.
|
|
1128
|
+
- Unsubscribing a chain watcher removes it from every named key.
|
|
1129
|
+
- `releaseNs` notifies only chains containing the released key.
|
|
1130
|
+
- A child named watcher sees a parent's named write once.
|
|
1131
|
+
- A grandchild named watcher sees a root named write.
|
|
1132
|
+
- A child's own named entry shields its watcher from a parent's write.
|
|
1133
|
+
- A child's named entry skips comparisons in its subtree on a parent write.
|
|
1134
|
+
- A child's fallback chain sees its parent's write until the child shadows it.
|
|
1135
|
+
- Releasing a parent's named entry notifies a child watcher of its fallback.
|
|
1136
|
+
- `release(cell)` resets every named entry at its layer.
|
|
1137
|
+
- `release(cell)` notifies a named watcher of its reset value once.
|
|
1138
|
+
- `release(cell)` calls only the child watcher that inherits its named entry.
|
|
1139
|
+
- `release(cell)` unlinks clients of its named entries, not another layer's entries.
|
|
1140
|
+
- A new named client after `release(cell)` is still unlinked by `releaseNs`.
|
|
1141
|
+
- An empty namespace chain is rejected with `InvalidDependency`.
|
|
1142
|
+
- A non-namespace `ns` value fails with `InvalidDependency`, not a silent key.
|
|
1143
|
+
- Invalid input rejects before dependencies build.
|
|
1144
|
+
- A watcher that writes during notify does not rob a later watcher of its change.
|
|
1145
|
+
- Named and chained cell watches notify only when their resolved value changes.
|
|
1146
|
+
- A failed named resource retries without leaking to a sibling chain.
|
|
1147
|
+
|
|
1148
|
+
## Promises
|
|
1149
|
+
|
|
1150
|
+
This appendix states each behaviour the seam tests pin, one line per promise, grouped by unit.
|
|
1151
|
+
`node tools/jev/promises.mjs core` is its check: every seam-test title names a line below.
|
|
1152
|
+
Titles that name no user-facing guarantee (type checks, budgets, past-bug regressions) carry no line.
|
|
1153
|
+
|
|
1154
|
+
### Data
|
|
1155
|
+
|
|
1156
|
+
- A cell reads its initial value through `parse`, so the first read is already the typed value.
|
|
1157
|
+
- `set` and `update` show on the next read.
|
|
1158
|
+
- A watcher sees each next value beside its previous one.
|
|
1159
|
+
- A write that fails `parse` throws `DataValidationFailed` naming the cell, and the value stays.
|
|
1160
|
+
- A watcher fires once per real change: an equal write fires nothing, and stopping ends it.
|
|
1161
|
+
- A watcher measures against the value at subscribe time: one joining after a write fires when the value
|
|
1162
|
+
returns to it; one joining after the return fires on the next change.
|
|
1163
|
+
- The same listener subscribed twice fires twice; each stop ends one subscription.
|
|
1164
|
+
- An operation can write a cell over time; watchers see each write.
|
|
1165
|
+
- Two scopes keep separate data: a write in one never shows in the other.
|
|
1166
|
+
- A data preset replaces the cell for the whole scope; reads see it.
|
|
1167
|
+
- `isError` rejects a plain error with no kind.
|
|
1168
|
+
- `isError` rejects a real error of the wrong kind.
|
|
1169
|
+
- An empty nested list reads frozen.
|
|
1170
|
+
- A data controller get reads the latest write.
|
|
1171
|
+
- A scope with empty tag bindings reads defaults.
|
|
1172
|
+
- An operation depending on a non-unit fails with `InvalidDependency`.
|
|
1173
|
+
- Each placement lands where its resource-target word says.
|
|
1174
|
+
- With no namespace, `atNamespace` and `atScope` both land in the
|
|
1175
|
+
root's own bucket.
|
|
1176
|
+
- A session's own write never climbs; its shadow wins its own reads.
|
|
1177
|
+
- `atScope` from a call two levels below a session still lands at
|
|
1178
|
+
the root.
|
|
1179
|
+
- A read view has no placement, at run time and in the types.
|
|
1180
|
+
- A placed controller kept past its call still writes the root,
|
|
1181
|
+
and watchers see it.
|
|
1182
|
+
|
|
1183
|
+
### Keyed data
|
|
1184
|
+
|
|
1185
|
+
- A keyed cell starts empty and reads all members in the order they came.
|
|
1186
|
+
- `of` reads one member and `where` reads the members of a part.
|
|
1187
|
+
- `update` and `delete` change one member by its key.
|
|
1188
|
+
- A write wakes the watchers of its member and of its parts, and no other.
|
|
1189
|
+
- Two keys with the same fields in another order name one member.
|
|
1190
|
+
- A served keyed cell is read by part: a client asks for a part, and the
|
|
1191
|
+
last reader leaving drops it.
|
|
1192
|
+
- A set on the server makes each reader of its part ask for one member.
|
|
1193
|
+
- An answer that arrives after a later ask started is dropped.
|
|
1194
|
+
- With a load, the server keeps no member.
|
|
1195
|
+
- `board.part(call)` gives a guard the part of a keyed join or ask, typed;
|
|
1196
|
+
any other call gives `undefined`.
|
|
1197
|
+
- `board.status(read)` gives a part's state: `pending` until its first
|
|
1198
|
+
answer, then `ready` or `fault`; `undefined` when no reader holds it.
|
|
1199
|
+
- A part that rides a ready part is `ready` at once.
|
|
1200
|
+
- A `refused` or `invalid` part waits: no ask again until an
|
|
1201
|
+
`invalidate` names it. A broken link asks again by itself.
|
|
1202
|
+
|
|
1203
|
+
### Faults
|
|
1204
|
+
|
|
1205
|
+
- Each fault of `rpc` and `remoteData` says who
|
|
1206
|
+
spoke: `from` is `"server"` or `"local"`.
|
|
1207
|
+
- A server fault is the server's answer:
|
|
1208
|
+
`refused`, `invalid`, `failed`, `missing`, and
|
|
1209
|
+
`encode` or `decode` on the server.
|
|
1210
|
+
- `missing`: no one serves the address, so
|
|
1211
|
+
nothing ran (as HTTP 404).
|
|
1212
|
+
- A local fault also says `sent`: `false` when
|
|
1213
|
+
nothing left, so the server ran nothing.
|
|
1214
|
+
- `link` is local; a transport that cannot tell
|
|
1215
|
+
says `sent: true`.
|
|
1216
|
+
- No call is sent again by itself.
|
|
1217
|
+
- A backend's `send` and `open` end with a value,
|
|
1218
|
+
never a throw. A throw in a backend is a bug:
|
|
1219
|
+
logged, `failed` on this side, never `link`.
|
|
1220
|
+
|
|
1221
|
+
### Tags
|
|
1222
|
+
|
|
1223
|
+
- A tag edge reads the nearest binding, in an operation or through the seam, or its default; with
|
|
1224
|
+
neither it throws `MissingTag` naming the tag.
|
|
1225
|
+
- Resolving a tag edge delivers its form: `all` lists nearest-first, `optional` reports presence,
|
|
1226
|
+
`required` reads or throws.
|
|
1227
|
+
- `optional` tells absent apart from an undefined default: the default reads present, the missing reads
|
|
1228
|
+
absent.
|
|
1229
|
+
- A tag binding runs through `parse`; a bad value throws `DataValidationFailed` naming the tag.
|
|
1230
|
+
- A unit takes no meta: the option is a type error and the handle has no field. Tags bind on a
|
|
1231
|
+
scope, a session, or a call; a driver takes rows.
|
|
1232
|
+
|
|
1233
|
+
### Resources
|
|
1234
|
+
|
|
1235
|
+
- A scope resource builds once; every resolve shares the one instance.
|
|
1236
|
+
- A resource factory sees its owner's current deps.
|
|
1237
|
+
- A depended-on resource builds before the body runs, read or not; reading it twice builds once.
|
|
1238
|
+
- An async dependency arrives as its value, read without awaiting; an async factory's thenable resolves
|
|
1239
|
+
to its awaited value.
|
|
1240
|
+
- Concurrent resolves share one in-flight build; later resolves keep the same settled instance and promise.
|
|
1241
|
+
- A resource that resolves itself fails with `CircularResource` naming the resource.
|
|
1242
|
+
- `get` before `resolve` fails with `NotResolved` naming the resource; through a closed owner it fails
|
|
1243
|
+
with `Disposed`, and a resolve then builds nothing.
|
|
1244
|
+
- A scope-target resource is one instance shared across sessions, with one shared sticky rejection.
|
|
1245
|
+
- A session-target resource builds once per session, distinct across sessions; a child's own instance
|
|
1246
|
+
survives its parent's release.
|
|
1247
|
+
- A scope resource that needs a session-only tag fails with `MissingTag`.
|
|
1248
|
+
- A build in flight when released never publishes — even when the release starts inside its own factory;
|
|
1249
|
+
the next resolve rebuilds.
|
|
1250
|
+
- An old build settling late never drops its replacement; its late rejection never detaches the
|
|
1251
|
+
replacement's edges.
|
|
1252
|
+
- A rejected build is sticky: re-resolve returns the same rejection with no new build, until a release
|
|
1253
|
+
of it or of a dependency lets it rebuild fresh.
|
|
1254
|
+
- Releasing a resource runs its cleanup; a re-resolve builds a new instance. A sync borrower never delays
|
|
1255
|
+
it. Releasing a data cell resets it to its initial and notifies watchers.
|
|
1256
|
+
- Release drops only the resource's cleanup, never a shared `onClose` hook.
|
|
1257
|
+
- A release whose owner is already closing fails with `Disposed`.
|
|
1258
|
+
- A rejecting release cleanup surfaces as secondary: the status stands, the error lands in teardown errors.
|
|
1259
|
+
- Release cascades down: the dependent rebuilds, exactly once across diamonds, while upstream stays built;
|
|
1260
|
+
dependents tear down first, and the cascade re-runs no operation.
|
|
1261
|
+
- A throwing cleanup mid-cascade still drops every dependent's cache; a throwing watcher still runs
|
|
1262
|
+
the cleanups.
|
|
1263
|
+
- Releasing a scope resource cascades into each session's dependents; an uninvolved session keeps its
|
|
1264
|
+
instance, a closed or closing one is skipped while the others still release.
|
|
1265
|
+
- A release waits for a borrower: a running cross-owner operation keeps the resource and its scope
|
|
1266
|
+
dependency alive through their cleanups; teardown runs borrower-first.
|
|
1267
|
+
- A build superseded in flight leaves the rebuilt instance alive: its late cleanup never drops it.
|
|
1268
|
+
- A release nested inside a release cleanup never hangs close, nor does a session cleanup closing the
|
|
1269
|
+
root; closing another scope from a cleanup still awaits its real teardown.
|
|
1270
|
+
- A resource preset replaces the built instance, builds once per owner, resolves async factories, and
|
|
1271
|
+
runs its own cleanup at owner close; the real factory never runs.
|
|
1272
|
+
- A resource preset does not build the deps of the node it replaces.
|
|
1273
|
+
- A resource preset gets empty deps: the real node's deps are never read.
|
|
1274
|
+
- A child session reads its parent's cell value.
|
|
1275
|
+
- Releasing a resource drops its dependents so they rebuild.
|
|
1276
|
+
- A throwing operation defer is aggregated as `TeardownFailed`.
|
|
1277
|
+
- Releasing a cell cascades into a resource behind its controller edge.
|
|
1278
|
+
- A released resource rebuilds with a fresh generation.
|
|
1279
|
+
- Releasing a data cell resets it and releases only its dependents.
|
|
1280
|
+
- A factory that declares no ctx fails its defer with `Disposed`.
|
|
1281
|
+
- A factory that declares no ctx still reads its abort signal.
|
|
1282
|
+
- A resource context hands the same abort signal on every read.
|
|
1283
|
+
- Releasing a diamond leg then the root still tears down the other leg.
|
|
1284
|
+
- Releasing one resource leaves another resource's cleanup in place.
|
|
1285
|
+
- Releasing a mid-chain resource tears down each dependent once in order.
|
|
1286
|
+
- A resource cleanup that rejects asynchronously lands in teardown errors.
|
|
1287
|
+
- A child session reads its parent's latest write.
|
|
1288
|
+
- A child update builds on its parent's latest write.
|
|
1289
|
+
- Releasing a dependency after its dependent never tears down twice.
|
|
1290
|
+
- A release inside a run drains unrelated cleanups at once.
|
|
1291
|
+
- A build superseded in flight never publishes its value.
|
|
1292
|
+
- A build superseded twice never publishes its value.
|
|
1293
|
+
- A finished borrow is forgotten before the next release.
|
|
1294
|
+
- A defer from a superseded build never joins the live rebuild's drain.
|
|
1295
|
+
- A failing start fails the scope with its cause.
|
|
1296
|
+
- A forced close aborts a nested grandchild session.
|
|
1297
|
+
- A rejection from a superseded build never goes sticky.
|
|
1298
|
+
- Get on a rejected build returns its rejection.
|
|
1299
|
+
- Concurrent resolves share one tracked build.
|
|
1300
|
+
- A release waits for every borrower, not just the first done.
|
|
1301
|
+
- A build that releases itself still rebuilds on the next resolve.
|
|
1302
|
+
|
|
1303
|
+
### Operations
|
|
1304
|
+
|
|
1305
|
+
- An operation runs on every run; calls are never memoized and concurrent calls stay independent.
|
|
1306
|
+
- A tagged call replays typed input inside the child session.
|
|
1307
|
+
- A tagged call replays raw input inside the child session.
|
|
1308
|
+
- A tagged call with no input still reads the call tags.
|
|
1309
|
+
- An operation writes through a data controller edge.
|
|
1310
|
+
- A sync run retains its span in history before run returns.
|
|
1311
|
+
- A session body rejected with a primitive keeps its cause under close.
|
|
1312
|
+
- A dependency snapshot is captured before the body suspends: a later write never leaks in.
|
|
1313
|
+
- A read-mode dep delivers the current value; a write-mode dep hands the caller a controller that writes.
|
|
1314
|
+
- An operation composes through its controller, or through a bare dep delivered as a callable subflow;
|
|
1315
|
+
a void-input operation is always a callable subflow, never a value.
|
|
1316
|
+
- An async operation runs to its awaited value.
|
|
1317
|
+
- A rejecting operation rejects with its cause, and `settled` still drains when it finishes.
|
|
1318
|
+
- A scope run that catches a subflow's managed error returns normally without failing its scope.
|
|
1319
|
+
- A tagged scope run that catches a subflow's managed error returns normally without failing its child
|
|
1320
|
+
session.
|
|
1321
|
+
- A session run that catches a subflow's managed error returns normally without failing its session.
|
|
1322
|
+
- A tagged session run that catches a subflow's managed error returns normally without failing either
|
|
1323
|
+
session.
|
|
1324
|
+
- A graceful parent close stays successful when a still-running tagged subflow's managed error is caught.
|
|
1325
|
+
- A subflow failure that escapes its caller fails the session with that cause.
|
|
1326
|
+
- An orphan fails the session: its subflow failed after the caller finished.
|
|
1327
|
+
- A dropped subflow's panic fails the session while its caller still runs.
|
|
1328
|
+
- A dropped subflow's managed error does not fail the session; its span keeps the error.
|
|
1329
|
+
- An awaited catch of a managed subflow error leaves the session successful.
|
|
1330
|
+
- A controller subflow's managed error caught by its caller leaves the session successful.
|
|
1331
|
+
- An orphan through a controller edge fails its session.
|
|
1332
|
+
- A tagged orphan fails its parent session.
|
|
1333
|
+
- A catch after its caller returns does not undo an orphan failure.
|
|
1334
|
+
- An orphan reports the original failure once on its own span.
|
|
1335
|
+
- A detached callback rejection after its root closes belongs to the host.
|
|
1336
|
+
- A detached callback rejection after its session closes belongs to the host, not the root.
|
|
1337
|
+
- An async subflow that succeeds exports an ok span.
|
|
1338
|
+
- An awaited catch after finally receives a managed subflow error and leaves the session successful.
|
|
1339
|
+
- An awaited then rejection handler receives a managed subflow error and leaves the session successful.
|
|
1340
|
+
- An awaited catch after fulfillment-only then receives a managed subflow error and leaves the session
|
|
1341
|
+
successful.
|
|
1342
|
+
- A graceful close does not wait for an endless then callback after a successful subflow.
|
|
1343
|
+
- A forced close does not wait for an endless then callback after a successful subflow.
|
|
1344
|
+
- A graceful close reports an orphan without joining its endless catch callback.
|
|
1345
|
+
- A forced close reports an orphan without joining its endless catch callback.
|
|
1346
|
+
- An awaited slow rejection handler receives a managed error and keeps the session successful even
|
|
1347
|
+
before its own work finishes.
|
|
1348
|
+
- A caller awaiting finally can catch the original managed error and leave the session successful.
|
|
1349
|
+
- An async subflow returns a native promise that `Promise.resolve` keeps unchanged.
|
|
1350
|
+
- A managed subflow error awaited and caught inside an operation defer does not fail the session.
|
|
1351
|
+
- Returning a subflow promise to an outer caller that awaits and catches its managed error does not fail
|
|
1352
|
+
the session.
|
|
1353
|
+
- Promise.all receives both managed subflow errors; a caller that catches them leaves the session
|
|
1354
|
+
successful.
|
|
1355
|
+
- A handler added from a later timer cannot undo an unreceived failure already settled.
|
|
1356
|
+
- A failed subflow's span keeps its error when caught, while its caller's span closes ok.
|
|
1357
|
+
- A failed unreceived subflow's span keeps its error even though its caller finishes normally.
|
|
1358
|
+
- A forced close after a caught managed subflow error cancels the session, rather than failing it.
|
|
1359
|
+
- A caller two subflows deep can catch a managed error without failing the session.
|
|
1360
|
+
- `settled` stays pending until owned work finishes.
|
|
1361
|
+
- An operation preset replaces the run for a direct call, a downstream subflow, and an inline config.
|
|
1362
|
+
- An operation preset gets empty deps: the real node's deps are not built.
|
|
1363
|
+
- An operation preset does not read an unbound tag.
|
|
1364
|
+
- An operation preset gets empty deps under a run hook too.
|
|
1365
|
+
- An operation preset still parses the call's input and rejects a bad one.
|
|
1366
|
+
- An inline run resolves deps, delivers the full context, and shares nothing between runs; with no call,
|
|
1367
|
+
`ctx.input` is void. A tagged inline run sees the call's tags; a preset arrives through its deps.
|
|
1368
|
+
- A tagged call binds the whole flow: run, subflow, and nested subflow all read the call's tags; a
|
|
1369
|
+
tagged sync call that ended in place returns its value, and one that must wait returns a native
|
|
1370
|
+
promise (ADR 0072).
|
|
1371
|
+
- A tagged run builds session resources in the flow, scope resources at the root; an untagged run builds
|
|
1372
|
+
session resources at the root and opens no session; the tagged session closes with the run.
|
|
1373
|
+
- An operation reads the scope's clock; a resource factory does too (see Clock).
|
|
1374
|
+
- An operation reads the scope's random; a resource factory does too (see Random).
|
|
1375
|
+
- An operation's context exposes no borrow or drain internals.
|
|
1376
|
+
- An operation defer sees the run's own end: `success` on return, `failed` on throw, `cancelled` under
|
|
1377
|
+
a forced close.
|
|
1378
|
+
- A rejected promise with an `undefined` cause keeps that cause; a primitive body cause still settles the
|
|
1379
|
+
session.
|
|
1380
|
+
- A preset is scoped to its scope: another scope still builds the real value.
|
|
1381
|
+
- A nested controller run passes the caller's object to the callee and returns the callee's own.
|
|
1382
|
+
- An async nested controller run gives the caller the callee's own object.
|
|
1383
|
+
- A callee that changes `ctx.input` changes the caller's object.
|
|
1384
|
+
- A tagged nested call passes the caller's object into the child session.
|
|
1385
|
+
- A namespaced nested call passes the caller's object to the callee.
|
|
1386
|
+
- A scope run passes the caller's object to the callee and returns the callee's own object.
|
|
1387
|
+
- A session run passes the caller's object to the callee and returns the callee's own object.
|
|
1388
|
+
- A parser that hands back its raw object gives `ctx.input` that object.
|
|
1389
|
+
- A parser's new object is `ctx.input`, while `ctx.rawInput` stays the caller's.
|
|
1390
|
+
|
|
1391
|
+
### Errors and panics
|
|
1392
|
+
|
|
1393
|
+
- `settle` returns an async operation's success value.
|
|
1394
|
+
- `settle` classifies a registry-shaped `Error` as an error.
|
|
1395
|
+
- `settle` classifies a plain `Error` as a panic.
|
|
1396
|
+
- `settle` classifies a non-`Error` object, an `Error` with no `payload`, or one whose `kind`
|
|
1397
|
+
is not a string, as a panic.
|
|
1398
|
+
- `settle` returns a primitive panic without an origin.
|
|
1399
|
+
- `settle` returns the value when an operation returns under a forced close.
|
|
1400
|
+
- `settle` returns what `run` returns when a body answers its abort with a value.
|
|
1401
|
+
- `settle` reports cancellation when a forced close aborts its operation.
|
|
1402
|
+
- `settle` reports cancellation when a body rejects with its abort reason.
|
|
1403
|
+
- `settle` mirrors `run` for a sync operation under a forced close.
|
|
1404
|
+
- `settle` reports a cancel reason from another scope as a failure.
|
|
1405
|
+
- A forced close's cancel reason reads as `AbortError` text.
|
|
1406
|
+
- A forced close's cancel reason is named `AbortError`.
|
|
1407
|
+
- A forced close's cancel reason inspects as `AbortError` text.
|
|
1408
|
+
- `settle` reports a foreign `AbortError` rejecting during a forced close as a failure.
|
|
1409
|
+
- `settle` returns a sync Result for an untagged sync operation.
|
|
1410
|
+
- `settle` on a tagged sync call returns its Result directly when it ended in place.
|
|
1411
|
+
- `scope.settle` accepts a typed inline call without making it async.
|
|
1412
|
+
- `scope.settle` on a tagged inline config gives a Result in place, a native promise when it waits.
|
|
1413
|
+
- `settle` on an unknown-typed operation types as a Result or a promise of one.
|
|
1414
|
+
- `settle` on a generic operation assigns to a Result or a promise of one.
|
|
1415
|
+
- `scope.settle` keeps an unknown-typed inline a Result or a promise of one.
|
|
1416
|
+
- `settle` recovers a root operation's panic without failing the layer.
|
|
1417
|
+
- `settle` recovers through a controller edge and through a bare operation dependency.
|
|
1418
|
+
- A settle call remains recovered when its caller finishes first.
|
|
1419
|
+
- A tagged settle failure does not bubble through a graceful parent close.
|
|
1420
|
+
- `settle` returns a closed-scope error rather than throwing.
|
|
1421
|
+
- A sync throw gets the innermost run's origin.
|
|
1422
|
+
- An async rejection gets the innermost run's origin.
|
|
1423
|
+
- Three failed runs build a root-first origin path.
|
|
1424
|
+
- `originOf` follows cause chains to a stamped error.
|
|
1425
|
+
- Rethrowing an already-stamped error keeps its first origin.
|
|
1426
|
+
- A sentinel error thrown on every settle keeps a one-run path.
|
|
1427
|
+
- A sibling rethrow does not extend the first path.
|
|
1428
|
+
- A sentinel thrown by a tagged or namespaced root run five times keeps a one-run path.
|
|
1429
|
+
- A tagged subflow keeps its caller in the path.
|
|
1430
|
+
- An observed origin carries the failed run's span id.
|
|
1431
|
+
- An unobserved origin has no span id.
|
|
1432
|
+
- A destructured operation `raise` sets kind, payload, and message at the throw site.
|
|
1433
|
+
- A destructured `raise` call does not narrow a later value of its run.
|
|
1434
|
+
- A `ctx` read without a written type does not narrow a later value.
|
|
1435
|
+
- A `raise` call on a written `ctx` type narrows a later value.
|
|
1436
|
+
- A returned `raise` narrows a later value even when it is destructured.
|
|
1437
|
+
- A resource `raise` stamps the resource ctx before a run receives it.
|
|
1438
|
+
- An escaping operation `raise` adds its own run label only once.
|
|
1439
|
+
- An empty ctx `raise` gets its origin from the run it reaches.
|
|
1440
|
+
- A capsule `raise` stamps the start ctx.
|
|
1441
|
+
- A failed session close carries its error's origin.
|
|
1442
|
+
- A panic caught with `try/catch` still fails its layer, with the panic and its origin.
|
|
1443
|
+
- A panic received through `settle` leaves its layer successful.
|
|
1444
|
+
- `settle` recovers a panic that a nested subflow threw.
|
|
1445
|
+
- `settle` recovers a panic carried as the cause of the error it receives.
|
|
1446
|
+
- A panic swallowed inside a settled run still fails the layer.
|
|
1447
|
+
- `settle` recovers only the panic it receives, not one swallowed earlier.
|
|
1448
|
+
- A caught panic after an earlier failure leaves the first failure as the layer's error.
|
|
1449
|
+
- Two caught panics in one layer leave the first, with its origin, as the layer's error.
|
|
1450
|
+
- A caught panic before a failed resource build stays the layer's error.
|
|
1451
|
+
- A managed error caught with `try/catch` leaves its layer successful.
|
|
1452
|
+
- A caught panic in a session run fails that session and not its parent.
|
|
1453
|
+
- A caught panic in an inline run fails the scope it ran in.
|
|
1454
|
+
- A panic caught inside a tagged run fails the run's own session.
|
|
1455
|
+
- A tagged subflow's panic fails its caller's layer even when the caller catches it.
|
|
1456
|
+
- A forced close after a caught panic settles `failed`, not `cancelled`.
|
|
1457
|
+
|
|
1458
|
+
### Scopes, sessions, and close
|
|
1459
|
+
|
|
1460
|
+
- A child session reads its parent's cells and tags until it writes its own; the write stays local.
|
|
1461
|
+
- A nearer shadow wins for descendants below it, and the parent keeps its own value.
|
|
1462
|
+
- A watcher on the parent still sees the parent's later writes after a child shadows.
|
|
1463
|
+
- Once close resolves, a held controller no longer reads the scope's own writes.
|
|
1464
|
+
- A closed scope's held controller reads the nearest ancestor's current write, or the initial value.
|
|
1465
|
+
- Late writes fail with `Disposed` before write hooks or update functions run.
|
|
1466
|
+
- Close runs children first, then `onClose` hooks and cleanups latest-first — a later `onClose` before
|
|
1467
|
+
an earlier resource cleanup; a dependent's cleanup before its dependency's.
|
|
1468
|
+
- With no body, child, or pending work, close runs synchronous cleanup in its first promise job.
|
|
1469
|
+
It adds no wait between synchronous cleanups.
|
|
1470
|
+
If a cleanup returns a promise, close waits for it before the next cleanup.
|
|
1471
|
+
- A destructured operation defer keeps its run's cleanup.
|
|
1472
|
+
- Settle keeps the call signal chosen before its body runs.
|
|
1473
|
+
- A throwing hook or cleanup never stops the rest: every cause lands in teardown errors, in order.
|
|
1474
|
+
- Close is safe to repeat: hooks run once, a re-entering close tears down once, closing again re-reports.
|
|
1475
|
+
- A clean scope closes `success` when graceful, `cancelled` when forced, and never throws; a second close
|
|
1476
|
+
returns the same result.
|
|
1477
|
+
- A failed start rejects `ready` with its cause and fails the scope.
|
|
1478
|
+
- A hanging inner start times out on the scope clock and closes with its label.
|
|
1479
|
+
- Start defaults to ten seconds and names an outer hook hanging after next.
|
|
1480
|
+
- A settled start cancels its timeout.
|
|
1481
|
+
- Close cancels a hanging start and its timer with the close reason.
|
|
1482
|
+
- Zero and infinite start limits keep the timer off.
|
|
1483
|
+
- Negative start limits raise a managed error.
|
|
1484
|
+
- Finite start limits are capped at the largest timer delay.
|
|
1485
|
+
- A recovered inner start leaves ready and close successful.
|
|
1486
|
+
- A tap called after ready raises a managed error.
|
|
1487
|
+
- A clock sleep throw or rejection leaves startup waiting without a timeout.
|
|
1488
|
+
- A real start error after close begins fails `closed` and keeps the error.
|
|
1489
|
+
- An explicit nested namespace chooses its own observation setting.
|
|
1490
|
+
- A held controller keeps its last write alive after its root closes, with or without a watcher or an `onClose` hook.
|
|
1491
|
+
- A held controller keeps its last write alive after its session closes, fast, under a session hook, or swept by its root.
|
|
1492
|
+
- Without a held controller, a closed root frees its last write.
|
|
1493
|
+
- A scope with no capsules is ready at once on one shared promise; a session after ready is ready.
|
|
1494
|
+
- `scope.resolve` reads a cell's current value with no subscription, builds a resource once, and reads a
|
|
1495
|
+
tag's nearest binding, default, or throws `MissingTag`.
|
|
1496
|
+
- `scope.run` shares the controller path: same lookup, same CallArgs rules, stable controller identity.
|
|
1497
|
+
- A close hook wraps the structural close and sees its result.
|
|
1498
|
+
- `session(fn)` commits on return and rolls back on throw, closes the child itself, and passes the error
|
|
1499
|
+
on; a throwing outcome hook keeps the outcome and aggregates its error. The session's handle closes
|
|
1500
|
+
when its body ends (ADR 0071): after the body returned, `onClose`, `resolve` and `run` on a handle
|
|
1501
|
+
the body kept raise `Disposed`, and `close({ withData: true })` on it gets no data.
|
|
1502
|
+
- Failed owned work fails the session with its cause; a body failure still wins for caller and hooks.
|
|
1503
|
+
- A failure in a nested session bubbles to the caller and rolls back the leaf; a collecting parent keeps
|
|
1504
|
+
a running descendant's real failure and its cleanup error.
|
|
1505
|
+
- Closing a parent while a session runs joins the body: success commits, failure rolls back.
|
|
1506
|
+
- A session-owned build that rejects while the session closes still fails the session with its cause.
|
|
1507
|
+
- A session that finished before any cancel keeps its success; a settled result survives a later
|
|
1508
|
+
interrupt; a cancelled session rejects rather than resolving undefined.
|
|
1509
|
+
- A graceful close still rolls back children of an already-failed scope; a child closing graceful after
|
|
1510
|
+
an ancestor abort still rolls its own resources back.
|
|
1511
|
+
- A failure already known before the cascade rolls back the remaining children.
|
|
1512
|
+
- A reused error object counts as the later session's own body failure; a child's own throw wins over a
|
|
1513
|
+
manual close of the same cause, which never demotes the parent's own body failure.
|
|
1514
|
+
- `settled` inside `session(fn)` drains owned work without waiting on the body.
|
|
1515
|
+
- A teardown hook may return its own `close` without hanging; concurrent closes join the one teardown
|
|
1516
|
+
and share its error.
|
|
1517
|
+
- A close whose owned work waits on a child's hook still completes; closing another scope from a cleanup
|
|
1518
|
+
still awaits its real teardown and reports its error.
|
|
1519
|
+
- A forced close aborts in-flight work: a parked op stops, a sleep rejects, the run's defer sees
|
|
1520
|
+
`cancelled`, and close settles `cancelled`.
|
|
1521
|
+
- A close re-entered during a failing teardown reports the failure.
|
|
1522
|
+
- A close re-entered during a clean forced teardown reports cancelled.
|
|
1523
|
+
- A forced close with a cleanup still settles cancelled.
|
|
1524
|
+
- `settled` stays pending until an operation's async cleanup finishes.
|
|
1525
|
+
- A session hook that throws before next still lets the body run and rethrows the hook error.
|
|
1526
|
+
- Two session hooks see each ordered end in turn.
|
|
1527
|
+
- A body that rejects inside session fails the close with its cause.
|
|
1528
|
+
- A session body that throws sync rejects the session with its cause.
|
|
1529
|
+
- A cancelled session rejects with its reason.
|
|
1530
|
+
- A failing teardown inside session still reports the body failure alongside the cleanup error.
|
|
1531
|
+
- A wrapped session body that throws sync still drains cleanups then reports the cause.
|
|
1532
|
+
- Three session hooks nest in registration order.
|
|
1533
|
+
- A close hook sees the settled end.
|
|
1534
|
+
- A graceful close through hooks settles success.
|
|
1535
|
+
- A failing body with a failing cleanup reports both causes.
|
|
1536
|
+
- A session that ends cancelled rejects with its reason.
|
|
1537
|
+
- Session hooks wrap sessions nested two deep.
|
|
1538
|
+
- A wrapped session cut by a forced close rejects.
|
|
1539
|
+
- A clean body with a failing cleanup still reports the cleanup.
|
|
1540
|
+
- An operation that finishes after abort still sees cancelled.
|
|
1541
|
+
- A cleanup that closes another scope sees its real result.
|
|
1542
|
+
- An idle scope's close still reports an operation cleanup that threw.
|
|
1543
|
+
- A default close frees a session's data and returns none.
|
|
1544
|
+
- A withData close hands over what the session wrote, never what it inherited.
|
|
1545
|
+
- A family member and a namespaced session's cell read back from data.
|
|
1546
|
+
- A graceful withData close keeps what in-flight work wrote before it settled.
|
|
1547
|
+
- A session hook reads the session's cells and tags after next.
|
|
1548
|
+
- A session hook cannot write a cell or read a resource after next.
|
|
1549
|
+
- A hooked session's reads throw once its hooks return.
|
|
1550
|
+
|
|
1551
|
+
### Clock
|
|
1552
|
+
|
|
1553
|
+
- An operation and a resource factory read the scope's clock.
|
|
1554
|
+
- Span and log times read the scope's clock, so a test clock freezes them too; an explicit
|
|
1555
|
+
`observe.clock` wins over it.
|
|
1556
|
+
- The default clock reads real wall time; a test clock starts where built, moves on advance, jumps on
|
|
1557
|
+
set, and keeps precise nanos; a child session reads its parent's clock.
|
|
1558
|
+
- A test-clock sleep resolves only after virtual time passes it; a zero sleep resolves at once.
|
|
1559
|
+
- A sleep with an already-aborted signal rejects with the abort reason, on both clocks.
|
|
1560
|
+
- An aborted sleep rejects with the signal's reason, on both clocks.
|
|
1561
|
+
- The system clock's nanos advance with wall time after a sleep.
|
|
1562
|
+
- A system-clock sleep with no signal resolves.
|
|
1563
|
+
- A system-clock sleep with a live signal resolves.
|
|
1564
|
+
- Due test-clock sleeps wake earliest-first.
|
|
1565
|
+
- A system-clock sleep cleans its timer after an abort.
|
|
1566
|
+
- A test-clock sleep set into the past wakes at once.
|
|
1567
|
+
|
|
1568
|
+
### Random
|
|
1569
|
+
|
|
1570
|
+
- An operation and a resource factory read the scope's random.
|
|
1571
|
+
- The default random reads the system source (`Math.random` / `crypto.randomUUID`); a child session
|
|
1572
|
+
reads its parent's random.
|
|
1573
|
+
- A test random built from a seed replays the same `next()` stream across scopes; a different seed
|
|
1574
|
+
gives a different stream.
|
|
1575
|
+
- A test random built from a seed replays the same `uuid()` stream, each id v4-shaped; every `uuid()`
|
|
1576
|
+
call yields a distinct id.
|
|
1577
|
+
- A test random with no seed is a deterministic default generator.
|
|
1578
|
+
|
|
1579
|
+
### Observation
|
|
1580
|
+
|
|
1581
|
+
- One start tap receives a span and misses work before the tap.
|
|
1582
|
+
- Two taps receive the same span, filter their own levels, and keep the largest history.
|
|
1583
|
+
- A throwing tap does not stop another tap.
|
|
1584
|
+
- A quiet namespace emits no spans or logs from its work and hooks.
|
|
1585
|
+
|
|
1586
|
+
- Capsule start logs before and after next reach the scope sink without a span.
|
|
1587
|
+
- A destructured capsule start logger sends every level without span observation.
|
|
1588
|
+
- An info threshold drops capsule start debug lines before reading the clock.
|
|
1589
|
+
- Capsule start logging without a sink reads no clock or attributes.
|
|
1590
|
+
- A failed capsule start delivers the log before its throw.
|
|
1591
|
+
- A throwing capsule start log sink does not fail ready.
|
|
1592
|
+
- A capsule close hook logs before and after next with the scope filter and clock.
|
|
1593
|
+
- A destructured operation logger stays the same and sends every level in order.
|
|
1594
|
+
- A destructured resource logger stays the same and keeps the level threshold.
|
|
1595
|
+
- A resource keeps its observation tools and exports manual events and children.
|
|
1596
|
+
- A caught operation raise carries its span before the body reads observation tools.
|
|
1597
|
+
- A caught resource raise carries its span before the factory reads observation tools.
|
|
1598
|
+
|
|
1599
|
+
- An observed operation logs its label, elapsed time, outcome, level, and span.
|
|
1600
|
+
- A failed operation logs its failure at error level.
|
|
1601
|
+
- Nested subflows log child before parent, once each.
|
|
1602
|
+
- An info threshold drops ok step lines but keeps failed ones.
|
|
1603
|
+
- Logging without observation keeps `ctx.log` but emits no step line.
|
|
1604
|
+
- Observing without a log sink preserves operation and resource spans.
|
|
1605
|
+
- A throwing step log sink does not change the run result.
|
|
1606
|
+
- With observation off, the context carries no span and nothing is retained.
|
|
1607
|
+
- With observation on, values and instances keep their identity: measuring changes nothing.
|
|
1608
|
+
- A subflow nests its span under its caller; two interleaved async operations keep separate trees.
|
|
1609
|
+
- A failed parse still closes and exports its span as failed; an async resource build opens and closes
|
|
1610
|
+
one balanced span.
|
|
1611
|
+
- Each caller of a shared resource links its own `used` edge; the resource builds once.
|
|
1612
|
+
- A throwing exporter, a rejecting async exporter, a throwing logger, and a hostile thenable never fail
|
|
1613
|
+
the operation and never leak a rejection.
|
|
1614
|
+
- A child span never calls a non-promise thenable's `then`.
|
|
1615
|
+
- An inline run yields one span named `inline`, or its label, with the subflow under it; the same config
|
|
1616
|
+
run twice yields two spans and two bodies.
|
|
1617
|
+
- A manual child span exports its event.
|
|
1618
|
+
- A manual child span that returns a value closes as ok.
|
|
1619
|
+
- A manual child span that throws closes as failed and rethrows.
|
|
1620
|
+
- An async child span closes as ok when its promise resolves.
|
|
1621
|
+
- An async child span closes as failed when its promise rejects.
|
|
1622
|
+
- Sibling spans carry distinct ids in call order.
|
|
1623
|
+
|
|
1624
|
+
### Capsules
|
|
1625
|
+
|
|
1626
|
+
- An operation depending on a capsule receives the start value after ready; while pending it raises
|
|
1627
|
+
`NotResolved` naming the capsule.
|
|
1628
|
+
- Resolving a capsule that is not installed throws `NotResolved` naming it; `resolve(capsule)` reads
|
|
1629
|
+
the capsule's own start value, bypassing the resolve chain.
|
|
1630
|
+
- `capsule({ label, config })` declares the tags a library reads; call it to fill them and get the
|
|
1631
|
+
binding a scope installs (ADR 0120, 0121).
|
|
1632
|
+
- Leaving a required config key out is a type error; a key written as `undefined` raises
|
|
1633
|
+
`MissingConfig { label, key }` at start; one library installed twice raises `DuplicateCapsule`.
|
|
1634
|
+
- The capsule tests (I1-I5, N1-N3, A01-A23) live in `tests/capsule.test.ts` and
|
|
1635
|
+
`tests/capsule.types.test.ts`.
|
|
1636
|
+
- A filled config key binds its tag on the root, and the root's own `tags` win; a `tag.all` key binds
|
|
1637
|
+
one tag per item and reads every binding last first.
|
|
1638
|
+
- A slot key holds a resource or an operation, which the library resolves through the scope, so a
|
|
1639
|
+
preset on the held unit reaches its readers.
|
|
1640
|
+
- A run hook sees every call and passes it through unchanged; a start or run hook that skips `next`
|
|
1641
|
+
short-circuits: inner starts never run, the refused body never runs.
|
|
1642
|
+
- `update(fn)` runs through the write chain with the computed value; the cell controller is cached
|
|
1643
|
+
per cell.
|
|
1644
|
+
- Requesting a cell controller after close raises `Disposed`, even when it was cached.
|
|
1645
|
+
- A closed scope with session hooks refuses a new session with `Disposed`.
|
|
1646
|
+
- A write chain skips a capsule with no write hook.
|
|
1647
|
+
- A write chain that skips still refuses when the writer denies.
|
|
1648
|
+
- Resource and operation controllers from the extended handle stay plain: reads and runs bypass the write
|
|
1649
|
+
chain untouched.
|
|
1650
|
+
- A tagged call runs the session chain once; a session under a session is wrapped; with no session hook,
|
|
1651
|
+
sessions run as before.
|
|
1652
|
+
- Session hooks nest in registration order and each sees the end status.
|
|
1653
|
+
- A throwing session hook rejects the session with its error; a hook that skips `next` still lets the
|
|
1654
|
+
session run and close.
|
|
1655
|
+
- A session felled by a forced parent close settles the hook chain as `cancelled`; under a graceful close it
|
|
1656
|
+
settles as `success`.
|
|
1657
|
+
- `session(fn)` reports the close end through the chain: success, a failed run, a forced close.
|
|
1658
|
+
- Three write hooks nest in registration order.
|
|
1659
|
+
- Three resolve hooks nest in registration order.
|
|
1660
|
+
- A scope with no resolve hooks reads straight through.
|
|
1661
|
+
- A session chain is installed only when a hook exists.
|
|
1662
|
+
- Three run hooks nest in registration order.
|
|
1663
|
+
- A run hook that asks which op it wraps changes that op only; its event gives a raw call's input
|
|
1664
|
+
as the op parses it, refuses a bad raw input as the op does, gives an inline run the caller's
|
|
1665
|
+
input, and has no input for a run with no call (ADR 0142).
|
|
1666
|
+
- Two close hooks nest in reverse install order.
|
|
1667
|
+
- A scope with no close hooks closes straight through.
|
|
1668
|
+
- A forced close with a close hook still settles cancelled.
|
|
1669
|
+
- A close chain runs past a capsule with no close hook.
|
|
1670
|
+
- A resolve chain runs past a capsule with no resolve hook.
|
|
1671
|
+
|
|
1672
|
+
## Trace ids
|
|
1673
|
+
|
|
1674
|
+
- Importing core draws no random values; the id stream seeds on the first observed span.
|
|
1675
|
+
- A root span has nonzero W3C ids before its body runs.
|
|
1676
|
+
- Operation, resource, and manual children inherit the trace and name their parent span.
|
|
1677
|
+
- Two unseeded root spans start different traces.
|
|
1678
|
+
- A seeded random replays trace and span ids.
|
|
1679
|
+
- Reading ids later leaves the seeded random stream and ids unchanged.
|
|
1680
|
+
- Observation leaves seeded and custom user randomness unchanged.
|
|
1681
|
+
- User random reads do not change seeded trace and child span ids.
|
|
1682
|
+
- Seeded ids use generator bits in every hex position and stay nonzero.
|
|
1683
|
+
- Span JSON keeps public fields, ids, attributes, and events without internal state.
|
|
1684
|
+
- Observation off leaves the ambient random stream untouched.
|
|
1685
|
+
- A session copies its remote trace seed and child sessions inherit it.
|
|
1686
|
+
- A session seed overrides its scope seed without changing siblings.
|
|
1687
|
+
- A seeded subflow uses its local caller as parent and keeps the sampled flag.
|
|
1688
|
+
|
|
1689
|
+
- A null session seed starts a fresh trace without changing its parent.
|
|
1690
|
+
- A session seed follows direct resource builds to their scope owner.
|
|
1691
|
+
|
|
1692
|
+
Absent `trace` inherits the parent seed; `trace: null` clears it.
|
|
1693
|
+
Numeric `id` and `parentId` still order the local tree.
|
|
1694
|
+
A span is a class instance, so spread or `structuredClone` copies only its own fields; use JSON for its public fields.
|
|
1695
|
+
`traceId` is 32 lowercase hex digits; `spanId` and
|
|
1696
|
+
`parentSpanId` are 16.
|
|
1697
|
+
ID bits come from a private 32-bit generator at open.
|
|
1698
|
+
IDs are reproducible only with `makeTestRandom({ seed })`.
|
|
1699
|
+
It keeps a second generator for IDs; user `next()` and `uuid()` calls stay unchanged.
|
|
1700
|
+
The system source and custom random sources use a core-owned generator seeded once from crypto.
|
|
1701
|
+
Hex text is made on first read and kept for later reads.
|
|
1702
|
+
Children share the trace's numbers and saved text.
|
|
1703
|
+
A zero final number becomes one, so an id cannot be all zeros.
|
|
1704
|
+
`sampled` carries the remote hint; local observation still
|
|
1705
|
+
follows `observe`.
|
|
1706
|
+
A new local trace defaults to sampled.
|
|
1707
|
+
A driver validates the seed before passing it to core:
|
|
1708
|
+
|
|
1709
|
+
```ts
|
|
1710
|
+
scope.createSession({
|
|
1711
|
+
trace: {
|
|
1712
|
+
traceId: "4bf92f3577b34da6a3ce929d0e0e4736",
|
|
1713
|
+
parentSpanId: "00f067aa0ba902b7",
|
|
1714
|
+
sampled: false,
|
|
1715
|
+
},
|
|
1716
|
+
});
|
|
1717
|
+
```
|
|
1718
|
+
|
|
1719
|
+
The sink sets `service.name` from its own config.
|
|
1720
|
+
Core adds no OTel import, span kind hint, or links.
|
|
1721
|
+
`kind` still means operation, resource, or manual work.
|