@opencode/codemode 2.2.6 → 2.2.7

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.
@@ -9,7 +9,7 @@ import { extensionGlobals } from "./extensions.js";
9
9
  import { createBuiltins } from "./intrinsics.js";
10
10
  import { Interpreter } from "./interpreter.js";
11
11
  import { formatLocation, sourceLocation } from "./model.js";
12
- import { Driver, SUSPENDED } from "./driver.js";
12
+ import { callPath, Driver, SUSPENDED } from "./driver.js";
13
13
  import { Interruption } from "./signals.js";
14
14
  import { Source } from "./source.js";
15
15
  /** Turns a suspended outcome into a failure, for callers that only run programs to their end. */
@@ -25,10 +25,10 @@ export const finishExecution = (outcome) => Effect.map(outcome, (outcome) => {
25
25
  /** Runs a program on the VM with `CodeMode.make`'s extensions and JSON bindings. */
26
26
  export const execute = (code, prepared, limits, hooks, extensions, bindings) => executeProgram(code, prepared, limits, hooks, extensions.length === 0 ? undefined : (ctx) => extensionGlobals(ctx, extensions), bindings === undefined
27
27
  ? undefined
28
- : (ctx) => Object.entries(bindings).map(([name, value]) => [name, fromJson(ctx, value)]), extensions.length > 0);
28
+ : (ctx) => Object.entries(bindings).map(([name, value]) => [name, fromJson(ctx, value)]), extensions.some((extension) => extension.snapshot === undefined));
29
29
  export const executeProgram = (code, prepared, limits, hooks, globals, bindings, lossy = false) => finishExecution(startProgram({ prepared, limits, hooks, globals, lossy }, code, bindings).run());
30
30
  /** A program ready to run on the VM: nothing runs until `run`. */
31
- export const startProgram = (setup, code, bindings) => new Running(setup, 0, () => {
31
+ export const startProgram = (setup, code, bindings, runId = crypto.randomUUID()) => new Running(setup, 0, () => {
32
32
  if (code.trim().length === 0) {
33
33
  return { ok: false, error: { kind: "ParseError", message: "Code cannot be empty." }, toolCalls: [] };
34
34
  }
@@ -36,6 +36,7 @@ export const startProgram = (setup, code, bindings) => new Running(setup, 0, ()
36
36
  if (!parsed.ok)
37
37
  return { ok: false, error: parsed.error, toolCalls: [] };
38
38
  const runtime = instantiate(setup, bindings);
39
+ runtime.vm.hosts.runId = runId;
39
40
  runtime.vm.start(parsed.source);
40
41
  return runtime;
41
42
  });
@@ -58,6 +59,13 @@ export const resumeProgram = (setup, saved) => Effect.try({
58
59
  };
59
60
  const fresh = instantiate(resumed);
60
61
  const snapshot = restoreInto(state, fresh.vm);
62
+ for (const call of fresh.vm.calls()) {
63
+ if (call.status !== "started")
64
+ continue;
65
+ if (call.request.kind !== "tool" || fresh.tools.mode(call.request.path)?._tag !== "CodeModeDurable") {
66
+ throw new SnapshotError(`The pending durable call ${call.key} (${callPath(call)}) cannot resume because that tool is no longer a durable tool in this runtime.`);
67
+ }
68
+ }
61
69
  return new Running(resumed, snapshot.header.budget.activeMs, () => fresh, true);
62
70
  },
63
71
  catch: (error) => (error instanceof SnapshotError ? error : new SnapshotError(String(error))),
@@ -142,7 +150,6 @@ export class Running {
142
150
  if (roundTrip)
143
151
  self.driver.checkpoint = Effect.sync(() => self.trip());
144
152
  self.startedAt = Date.now();
145
- yield* Deferred.succeed(self.started, undefined);
146
153
  return yield* self.execute();
147
154
  }).pipe(Effect.onExit((exit) => Effect.andThen(Deferred.succeed(self.started, undefined), Deferred.done(self.done, exit))));
148
155
  }
@@ -177,6 +184,7 @@ export class Running {
177
184
  const driver = self.driver;
178
185
  if (self.resuming)
179
186
  driver.resume();
187
+ yield* Deferred.succeed(self.started, undefined);
180
188
  const outcome = yield* driver.run();
181
189
  if (outcome === SUSPENDED)
182
190
  return self.suspended;
@@ -248,6 +256,14 @@ export class Running {
248
256
  running,
249
257
  });
250
258
  }
259
+ // Idempotent calls in flight are saved as queued so they run again on resume under the same key.
260
+ const idempotent = vm.calls().filter((call) => call.status === "running");
261
+ for (const call of idempotent)
262
+ call.status = "queued";
263
+ const restoreRunning = () => {
264
+ for (const call of idempotent)
265
+ call.status = "running";
266
+ };
251
267
  const limits = this.setup.limits;
252
268
  const saved = attempt(() => vm.capture({
253
269
  limits: {
@@ -259,6 +275,7 @@ export class Running {
259
275
  strict: false,
260
276
  }));
261
277
  if (!saved.ok) {
278
+ restoreRunning();
262
279
  const error = saved.error;
263
280
  return new SuspendError({
264
281
  message: `The run's state couldn't be saved: ${error instanceof Error ? error.message : String(error)}`,
@@ -269,6 +286,7 @@ export class Running {
269
286
  if (maxBytes !== undefined) {
270
287
  const size = toBytes(snapshot).byteLength;
271
288
  if (size > maxBytes) {
289
+ restoreRunning();
272
290
  return new SuspendError({
273
291
  message: `The run's state takes ${size} bytes, more than the ${maxBytes}-byte limit, so it couldn't be suspended.`,
274
292
  running: [],
@@ -278,8 +296,8 @@ export class Running {
278
296
  return { ok: "suspended", state: snapshot };
279
297
  }
280
298
  // The round-trip test mode's checkpoint: saves the state to bytes and continues in a brand-new runtime. States that
281
- // hold live host values (an extension call in flight, a function an extension returned) can't round-trip, so they
282
- // are skipped; a lost value anywhere else is a codec gap and fails the run.
299
+ // hold live host values (an extension call in flight, a function an extension without `snapshot` hooks returned)
300
+ // can't round-trip, so they are skipped; a lost value anywhere else is a codec gap and fails the run.
283
301
  trip() {
284
302
  const driver = this.driver;
285
303
  if (this.trips >= ROUND_TRIP_MAX) {
@@ -293,13 +311,23 @@ export class Running {
293
311
  if (driver.holdsHostValues)
294
312
  return;
295
313
  this.trips++;
296
- const saved = this.ctx.vm.capture({ strict: !this.setup.lossy });
314
+ const attempted = attempt(() => this.ctx.vm.capture({ strict: !this.setup.lossy }));
315
+ // An extension's `snapshot` hooks may refuse to save a value, which fails a suspend, not the run.
316
+ if (!attempted.ok) {
317
+ const error = attempted.error;
318
+ if (error instanceof SnapshotError && error.message.startsWith("The extension "))
319
+ return;
320
+ throw error;
321
+ }
322
+ const saved = attempted.value;
297
323
  const bytes = toBytes(saved.snapshot);
298
324
  this.skip = Math.floor(saved.snapshot.records.length / 200 + bytes.byteLength / 100_000);
299
325
  if (saved.lost.length > 0)
300
326
  return;
301
327
  const fresh = instantiate(this.setup);
302
328
  restoreInto(fromBytes(bytes), fresh.vm);
329
+ for (const [key, invocation] of this.ctx.tools.invocations)
330
+ fresh.tools.invocations.set(key, invocation);
303
331
  this.ctx = fresh;
304
332
  driver.vm = fresh.vm;
305
333
  driver.tools = fresh.tools;
@@ -13,4 +13,4 @@ export declare const extensionGlobals: <R>(ctx: Interpreter<R>, extensions: Read
13
13
  * Calls a synchronous extension function's host function, once its `extension.before` hook allowed it: a promise for
14
14
  * a result that settles later (an Effect or a Promise), or the request that settles what it returned or threw now.
15
15
  */
16
- export declare const startExtensionCall: <R>(ctx: Interpreter<R>, host: Function, args: ReadonlyArray<unknown>, call: Pick<ExtensionRequest, "label" | "invocation">, site: AstNode | undefined) => PromiseObj | ExtensionRequest;
16
+ export declare const startExtensionCall: <R>(ctx: Interpreter<R>, host: Function, args: ReadonlyArray<unknown>, call: Pick<ExtensionRequest, "label" | "extension" | "invocation">, site: AstNode | undefined) => PromiseObj | ExtensionRequest;
@@ -9,6 +9,7 @@ import { native } from "./native.js";
9
9
  import { define, get, has, hidden, keys, Arr, Bytes, DateObj, ErrorObj, HeadersObj, PromiseObj, MapObj, Obj, RegExpObj, SetObj, URLObj, URLSearchParamsObj, coerceToString, } from "./objects.js";
10
10
  import { describeValue, isOpaque } from "./references.js";
11
11
  import { Push } from "./signals.js";
12
+ import { SnapshotError } from "../snapshot/codec.js";
12
13
  /**
13
14
  * The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data and built-in
14
15
  * wrappers are copied, a host function becomes a program function whose calls cross the same way, and a host Promise
@@ -16,6 +17,9 @@ import { Push } from "./signals.js";
16
17
  */
17
18
  export const extensionGlobals = (ctx, extensions) => {
18
19
  const builtins = ctx.builtins;
20
+ const byName = new Map(extensions.map((extension) => [extension.name, extension]));
21
+ // The program functions wrapping functions inside values a hooked extension returned, by where they came from.
22
+ const origins = new WeakMap();
19
23
  const toHost = (value, label, depth = 0, seen = new Set()) => {
20
24
  if (depth > MAX_VALUE_DEPTH)
21
25
  throw typeError(`${label} exceeds the maximum value depth of ${MAX_VALUE_DEPTH}.`);
@@ -53,16 +57,19 @@ export const extensionGlobals = (ctx, extensions) => {
53
57
  seen.delete(value);
54
58
  return copied;
55
59
  };
56
- // `extension` is set under an extension's global object, whose functions are entry points that fire the hooks.
57
- const fromHost = (value, label, depth = 0, seen = new Set(), extension) => {
60
+ // `within` says where the value is, so a function inside it fires the hooks, or can be saved; see `Within`.
61
+ const fromHost = (value, label, depth = 0, seen = new Set(), within) => {
58
62
  if (depth > MAX_VALUE_DEPTH)
59
63
  throw typeError(`${label} exceeds the maximum value depth of ${MAX_VALUE_DEPTH}.`);
60
64
  if (isPrimitive(value))
61
65
  return value;
62
66
  if (typeof value === "function")
63
- return wrap(value, label, extension);
67
+ return wrap(value, label, within);
64
68
  if (value !== null && typeof value === "object") {
65
- const next = (item, path) => fromHost(item, path, depth + 1, seen, extension);
69
+ const next = (item, path, key) => fromHost(item, path, depth + 1, seen, within && {
70
+ ...within,
71
+ path: key === undefined || within.path === undefined ? undefined : [...within.path, key],
72
+ });
66
73
  // Nothing a host value hands back is kept: results are read as primitives or copied. Where the value's own
67
74
  // method could hand back host storage or an object (`getTime`, `slice`, `map`), its internal data is read.
68
75
  if (value instanceof Date)
@@ -91,7 +98,7 @@ export const extensionGlobals = (ctx, extensions) => {
91
98
  const field = fields[key];
92
99
  if (typeof field === "function")
93
100
  continue;
94
- const item = crossing(() => next(field, `${label}.${key}`));
101
+ const item = crossing(() => next(field, `${label}.${key}`, key));
95
102
  if (item === left)
96
103
  continue;
97
104
  define(copied, key, item, key === "cause" ? hidden : undefined);
@@ -130,7 +137,7 @@ export const extensionGlobals = (ctx, extensions) => {
130
137
  const items = [];
131
138
  for (let index = 0; index < length; index += 1) {
132
139
  if (index in value)
133
- items[index] = next(value[index], `${label}[${index}]`);
140
+ items[index] = next(value[index], `${label}[${index}]`, index);
134
141
  }
135
142
  items.length = length;
136
143
  seen.delete(value);
@@ -140,7 +147,7 @@ export const extensionGlobals = (ctx, extensions) => {
140
147
  if (prototype === Object.prototype || prototype === null) {
141
148
  const copied = new Obj(builtins.Object);
142
149
  for (const [key, item] of Object.entries(value))
143
- define(copied, key, next(item, `${label}.${key}`));
150
+ define(copied, key, next(item, `${label}.${key}`, key));
144
151
  seen.delete(value);
145
152
  return copied;
146
153
  }
@@ -150,26 +157,67 @@ export const extensionGlobals = (ctx, extensions) => {
150
157
  // A host function as a program function. Arguments cross in; for a global or a global object's function, the
151
158
  // `extension.before` hook runs before the host function is called, so a call it denies never reaches the host. The
152
159
  // host's result, or what it threw, crosses out so the program catches a copy, and `extension.after` sees how the
153
- // call ended. Functions inside results are part of a value's API and skip the hooks.
154
- const wrap = (value, label, extension) => {
160
+ // call ended. Functions inside results are part of a value's API and skip the hooks; one inside a value an extension
161
+ // with `snapshot` hooks returned is known by where it came from, so a suspended run can save it.
162
+ const wrap = (value, label, within) => {
155
163
  // The host function's own `name` and `length` can be anything, even getters: each is read once, and only text
156
164
  // and a count cross.
157
165
  const name = value.name;
158
166
  const length = value.length;
159
- return native(builtins, {
167
+ const extension = within?.extension.name;
168
+ const root = within?.root;
169
+ const wrapped = native(builtins, {
160
170
  runtime: "extension",
161
171
  name: typeof name === "string" ? name : "",
162
172
  length: typeof length === "number" && Number.isSafeInteger(length) && length >= 0 ? length : 0,
163
173
  call: (_, values, site) => {
164
174
  const args = values.map((item, index) => toHost(item, `Argument ${index + 1} to ${label}`));
165
- const invocation = extension === undefined ? undefined : { extension, name: label, args };
175
+ const invocation = within !== undefined && root === undefined ? { extension: extension, name: label, args } : undefined;
166
176
  // A denied call fails the way the global would: an async global rejects its promise, a sync one throws.
167
177
  if (isAsync(value)) {
168
- return pending(ctx, { stage: "run", label, invocation, host: value, args, threw: false }, site);
178
+ return pending(ctx, { stage: "run", label, extension, invocation, host: value, args, threw: false }, site);
169
179
  }
170
- return new Push("extension call", [value, args, label, invocation]);
180
+ return new Push("extension call", [value, args, label, invocation, extension]);
171
181
  },
172
182
  });
183
+ if (root !== undefined && within.path !== undefined) {
184
+ origins.set(wrapped, { extension: extension, root, path: within.path, label });
185
+ }
186
+ return wrapped;
187
+ };
188
+ ctx.hosts = {
189
+ extensions: extensions.map((extension) => ({ name: extension.name, hooked: extension.snapshot !== undefined })),
190
+ origin: (value) => origins.get(value),
191
+ encode: (name, root) => hostStep(name, "save", () => hooks(name).encode(root)),
192
+ decode: (name, data) => {
193
+ const root = hostStep(name, "restore", () => hooks(name).decode(data));
194
+ if ((typeof root !== "object" && typeof root !== "function") || root === null) {
195
+ throw new SnapshotError(`The extension "${name}" restored a value it returned as ${typeof root}, not an object.`);
196
+ }
197
+ return root;
198
+ },
199
+ rewrap: (target, origin) => {
200
+ const host = origin.path.reduce((at, key) => (typeof at === "object" && at !== null) || typeof at === "function"
201
+ ? at[key]
202
+ : undefined, origin.root);
203
+ if (typeof host !== "function") {
204
+ throw new SnapshotError(`The extension "${origin.extension}" restored a value with no function at ${origin.label}, so this state can't resume.`);
205
+ }
206
+ const made = wrap(host, origin.label, {
207
+ extension: byName.get(origin.extension),
208
+ root: origin.root,
209
+ path: origin.path,
210
+ });
211
+ // The restored function keeps its own properties; only what calling it does comes from the new one.
212
+ Object.assign(target, { tag: made.tag, call: made.call, construct: made.construct, callback: made.callback });
213
+ origins.set(target, origin);
214
+ },
215
+ };
216
+ const hooks = (name) => {
217
+ const snapshot = byName.get(name)?.snapshot;
218
+ if (snapshot === undefined)
219
+ throw new SnapshotError(`The extension "${name}" has no snapshot hooks.`);
220
+ return snapshot;
173
221
  };
174
222
  // The Effect each step of an extension call runs as, with the program's services in its requirements.
175
223
  ctx.extensionWork = (request) => {
@@ -181,12 +229,20 @@ export const extensionGlobals = (ctx, extensions) => {
181
229
  if (request.stage === "before")
182
230
  return before ?? Effect.void;
183
231
  const after = call && hooks["extension.after"];
184
- const settle = (effect) => (after ? hooked(call, undefined, after, effect) : effect).pipe(Effect.mapBoth({ onFailure: cross, onSuccess: (result) => fromHost(result, label) }));
232
+ const extension = request.extension === undefined ? undefined : byName.get(request.extension);
233
+ // What a function returns is a value of its extension's, which its `snapshot` hooks save, when it has them.
234
+ const settle = (effect) => (after ? hooked(call, undefined, after, effect) : effect).pipe(Effect.mapBoth({
235
+ onFailure: cross,
236
+ onSuccess: (result) => fromHost(result, label, 0, new Set(), extension?.snapshot !== undefined &&
237
+ ((typeof result === "object" && result !== null) || typeof result === "function")
238
+ ? { extension, root: result, path: [] }
239
+ : undefined),
240
+ }));
185
241
  if (request.stage === "settle")
186
242
  return settle(outcome(request.host, request.threw));
187
243
  return Effect.andThen(before ?? Effect.void, settle(Effect.suspend(() => outcome(...callHost(request.host, request.args)))));
188
244
  };
189
- return extensions.flatMap((extension) => Object.entries(extension.globals).map(([name, value]) => [name, fromHost(value, name, 0, new Set(), extension.name)]));
245
+ return extensions.flatMap((extension) => Object.entries(extension.globals).map(([name, value]) => [name, fromHost(value, name, 0, new Set(), { extension, root: undefined, path: undefined })]));
190
246
  };
191
247
  // An asynchronous host call: the program holds a promise that settles when the host's work does.
192
248
  const pending = (ctx, call, site) => {
@@ -205,6 +261,17 @@ export const startExtensionCall = (ctx, host, args, call, site) => {
205
261
  return pending(ctx, request, site);
206
262
  return request;
207
263
  };
264
+ // Runs an extension's `snapshot` hook; what goes wrong is the state's problem, said as such.
265
+ const hostStep = (extension, what, step) => {
266
+ try {
267
+ return step();
268
+ }
269
+ catch (error) {
270
+ if (error instanceof SnapshotError)
271
+ throw error;
272
+ throw new SnapshotError(`The extension "${extension}" couldn't ${what} a value it returned: ${error instanceof Error ? error.message : String(error)}`);
273
+ }
274
+ };
208
275
  /** Calls a host function: what it returned, or what it threw. */
209
276
  const callHost = (value, args) => {
210
277
  try {
@@ -1,5 +1,6 @@
1
1
  import type { ToolRuntime } from "../../tool-runtime.js";
2
2
  import type { ExtensionRequest } from "../scheduler.js";
3
+ import type { HostBridge } from "../snapshot/codec.js";
3
4
  import { Vm } from "../vm.js";
4
5
  import type { Builtins } from "./intrinsics.js";
5
6
  import { IntrinsicNames } from "./intrinsic-names.js";
@@ -21,6 +22,8 @@ export declare class Interpreter<R> {
21
22
  readonly prelude: Prelude;
22
23
  /** Makes the Effect an extension function's host work runs as; set by the extension bridge. */
23
24
  extensionWork: ((request: ExtensionRequest) => unknown) | undefined;
25
+ /** Saves and restores values returned by extensions with `snapshot` hooks; set by the extension bridge. */
26
+ hosts: HostBridge | undefined;
24
27
  /** The parsed sources this execution runs, by id, so a `NodeId` resolves to its node. */
25
28
  readonly sources: Map<string, Source>;
26
29
  /** The global bindings: the intrinsics, the host's globals, and the program's bindings. */
@@ -19,6 +19,8 @@ export class Interpreter {
19
19
  prelude;
20
20
  /** Makes the Effect an extension function's host work runs as; set by the extension bridge. */
21
21
  extensionWork;
22
+ /** Saves and restores values returned by extensions with `snapshot` hooks; set by the extension bridge. */
23
+ hosts;
22
24
  /** The parsed sources this execution runs, by id, so a `NodeId` resolves to its node. */
23
25
  sources = new Map();
24
26
  /** The global bindings: the intrinsics, the host's globals, and the program's bindings. */
@@ -101,6 +101,7 @@ export type HostRequest = {
101
101
  export type ExtensionRequest = {
102
102
  readonly stage: "before" | "settle" | "run";
103
103
  readonly label: string;
104
+ readonly extension?: string | undefined;
104
105
  invocation: ExtensionInvocation | undefined;
105
106
  host: unknown;
106
107
  args: ReadonlyArray<unknown>;
@@ -113,6 +114,8 @@ export type ExtensionRequest = {
113
114
  */
114
115
  export declare class HostCall {
115
116
  readonly id: number;
117
+ /** The call's stable idempotency key, `<runId>:<callId>`. */
118
+ readonly key: string;
116
119
  readonly request: HostRequest;
117
120
  /** What runs: a tool path, or an extension function's label. */
118
121
  readonly label: string;
@@ -124,9 +127,18 @@ export declare class HostCall {
124
127
  readonly resolving: Resolving | undefined;
125
128
  /** The call that started the work, where a defect it raises is located. */
126
129
  readonly site: AstNode | undefined;
127
- /** Where the call is: `queued` (written ahead, not started), `running`, or `completed`. */
128
- status: "queued" | "running" | "completed";
129
- constructor(id: number, request: HostRequest,
130
+ /**
131
+ * Where the call is: `queued` (written ahead, not started), `running` (or in `start` for a durable tool),
132
+ * `started` (a durable tool whose `start` returned its `data`, now in `wait`), or `completed`.
133
+ */
134
+ status: "queued" | "running" | "started" | "completed";
135
+ /** The JSON data a durable tool's `start` returned, saved so a resumed run can call `wait(data)`. */
136
+ data: Json | undefined;
137
+ /** Whether a tool call has already been counted against `maxToolCalls` and recorded in `toolCalls`. */
138
+ admitted: boolean;
139
+ constructor(id: number,
140
+ /** The call's stable idempotency key, `<runId>:<callId>`. */
141
+ key: string, request: HostRequest,
130
142
  /** What runs: a tool path, or an extension function's label. */
131
143
  label: string,
132
144
  /** The running job waits for it: its outcome continues the frame that asked, before any other job. */
@@ -6,15 +6,25 @@ import { locate } from "./runtime/errors.js";
6
6
  */
7
7
  export class HostCall {
8
8
  id;
9
+ key;
9
10
  request;
10
11
  label;
11
12
  blocking;
12
13
  result;
13
14
  resolving;
14
15
  site;
15
- /** Where the call is: `queued` (written ahead, not started), `running`, or `completed`. */
16
+ /**
17
+ * Where the call is: `queued` (written ahead, not started), `running` (or in `start` for a durable tool),
18
+ * `started` (a durable tool whose `start` returned its `data`, now in `wait`), or `completed`.
19
+ */
16
20
  status = "queued";
17
- constructor(id, request,
21
+ /** The JSON data a durable tool's `start` returned, saved so a resumed run can call `wait(data)`. */
22
+ data = undefined;
23
+ /** Whether a tool call has already been counted against `maxToolCalls` and recorded in `toolCalls`. */
24
+ admitted = false;
25
+ constructor(id,
26
+ /** The call's stable idempotency key, `<runId>:<callId>`. */
27
+ key, request,
18
28
  /** What runs: a tool path, or an extension function's label. */
19
29
  label,
20
30
  /** The running job waits for it: its outcome continues the frame that asked, before any other job. */
@@ -26,6 +36,7 @@ export class HostCall {
26
36
  /** The call that started the work, where a defect it raises is located. */
27
37
  site) {
28
38
  this.id = id;
39
+ this.key = key;
29
40
  this.request = request;
30
41
  this.label = label;
31
42
  this.blocking = blocking;
@@ -1,5 +1,5 @@
1
1
  import { type AstNode } from "../runtime/model.js";
2
- import { Obj } from "../runtime/objects.js";
2
+ import { Native, Obj } from "../runtime/objects.js";
3
3
  import { Interruption } from "../runtime/signals.js";
4
4
  /** A plain JSON value, as a snapshot holds it. */
5
5
  export type Json = null | boolean | number | string | ReadonlyArray<Json> | {
@@ -24,6 +24,34 @@ export type Record = {
24
24
  /** A saved state can't be read, or doesn't fit this runtime. */
25
25
  import { SnapshotError } from "../../suspend-error.js";
26
26
  export { SnapshotError };
27
+ /**
28
+ * Where a function inside a value an extension returned came from, so a saved state can name it instead of losing it:
29
+ * the extension, the value its function returned (`root`), which the extension's `snapshot` hooks save, and the path
30
+ * from there to the function.
31
+ */
32
+ export type HostOrigin = {
33
+ readonly extension: string;
34
+ readonly root: object;
35
+ readonly path: ReadonlyArray<string | number>;
36
+ /** What the program calls it, for its errors (`fetch.text`). */
37
+ readonly label: string;
38
+ };
39
+ /** The extension bridge's side of saving and restoring those functions; see `extensionGlobals`. */
40
+ export type HostBridge = {
41
+ /** Each extension's name, and whether it has `snapshot` hooks: a state resumes only where both match. */
42
+ readonly extensions: ReadonlyArray<{
43
+ readonly name: string;
44
+ readonly hooked: boolean;
45
+ }>;
46
+ /** Where a program function wrapping a host function came from, when its extension can save it. */
47
+ readonly origin: (value: object) => HostOrigin | undefined;
48
+ /** A returned value as its extension saves it. */
49
+ readonly encode: (extension: string, root: object) => unknown;
50
+ /** A returned value back from what `encode` gave. */
51
+ readonly decode: (extension: string, data: unknown) => object;
52
+ /** Makes `target`, a restored program function, call the host function `origin` leads to. */
53
+ readonly rewrap: (target: Native, origin: HostOrigin) => void;
54
+ };
27
55
  /** What the encoder asks of the runtime whose state it saves. */
28
56
  export type EncodeEnv = {
29
57
  /** The name of a built-in or host global object. */
@@ -36,6 +64,7 @@ export type EncodeEnv = {
36
64
  /** Values with no data form are reported here; strict encoding throws on the first instead. */
37
65
  readonly lost: Array<string>;
38
66
  readonly strict: boolean;
67
+ readonly hosts?: HostBridge | undefined;
39
68
  /** More classes to save, an engine's own (the VM's frames and closures), after the built-in ones. */
40
69
  readonly specs?: ReadonlyArray<ClassSpec> | undefined;
41
70
  /** The data an engine names an object or symbol by, saved as `["x", data]`, instead of copying it. */
@@ -48,6 +77,7 @@ export type DecodeEnv = {
48
77
  readonly node: (source: string, index: number) => AstNode | undefined;
49
78
  /** An `Interruption` (it holds an Effect cause, which this module does not make). */
50
79
  readonly interruption: () => Interruption;
80
+ readonly hosts?: HostBridge | undefined;
51
81
  readonly specs?: ReadonlyArray<ClassSpec> | undefined;
52
82
  /** What `EncodeEnv.external` named. */
53
83
  readonly external?: ((data: Json) => unknown) | undefined;
@@ -110,7 +110,7 @@ const builtinSpecs = () => [
110
110
  {
111
111
  name: "HostCall",
112
112
  ctor: HostCall,
113
- fields: ["status", "id", "request", "label", "blocking", "result", "resolving", "site"],
113
+ fields: ["status", "data", "admitted", "id", "key", "request", "label", "blocking", "result", "resolving", "site"],
114
114
  },
115
115
  { name: "Resolving", ctor: Resolving, fields: ["done", "scheduler", "promise", "site"] },
116
116
  { name: "Throw", ctor: Throw, fields: ["value"] },
@@ -124,7 +124,7 @@ const builtinSpecs = () => [
124
124
  ctor: Interpreter,
125
125
  anchor: "ctx",
126
126
  fields: ["logs", "globalScope", "modules", "namespaces"],
127
- skip: ["tools", "builtins", "vm", "intrinsics", "extensionWork", "sources", "prelude"],
127
+ skip: ["tools", "builtins", "vm", "intrinsics", "extensionWork", "hosts", "sources", "prelude"],
128
128
  },
129
129
  ];
130
130
  let builtins;
@@ -186,6 +186,8 @@ class Encoder {
186
186
  // A URL's `searchParams` is the same host object its URLSearchParams wraps; it is encoded once every URL is known.
187
187
  owners = new Map();
188
188
  params = [];
189
+ // One `HostValue` record per value an extension returned, however many of its functions the state holds.
190
+ roots = new Map();
189
191
  specs;
190
192
  constructor(env) {
191
193
  this.env = env;
@@ -296,7 +298,14 @@ class Encoder {
296
298
  return { t: spec.name, ...this.fields(object, spec) };
297
299
  }
298
300
  if (object instanceof Native) {
299
- // A host function made while the program ran, inside a value an extension returned: its name says what was lost.
301
+ // A host function made while the program ran: inside a value an extension returned. Its extension saves that
302
+ // value when it has `snapshot` hooks; otherwise its name says what was lost.
303
+ const origin = this.env.hosts?.origin(object);
304
+ if (origin !== undefined) {
305
+ const root = this.hostValue(origin.extension, origin.root);
306
+ const fields = this.fields(object, hostFunction, hostFunction.fields);
307
+ return { t: "HostFunction", e: origin.extension, h: root, k: [...origin.path], l: origin.label, ...fields };
308
+ }
300
309
  this.lose(`the function ${functionName(object)}`);
301
310
  return { t: "LostNative", ...this.fields(object, hostFunction, hostFunction.fields) };
302
311
  }
@@ -332,6 +341,19 @@ class Encoder {
332
341
  this.lose(what);
333
342
  return { t: "Lost", f: [what] };
334
343
  }
344
+ // A value an extension returned, as its `snapshot.encode` saves it: plain data, checked before it is copied.
345
+ hostValue(extension, root) {
346
+ const known = this.roots.get(root);
347
+ if (known !== undefined)
348
+ return known;
349
+ const data = plainData(this.env.hosts.encode(extension, root), extension, new Set());
350
+ const id = this.records.length;
351
+ const ref = ["r", id];
352
+ this.roots.set(root, ref);
353
+ this.records.push(undefined);
354
+ this.records[id] = { t: "HostValue", e: extension, d: this.value(data) };
355
+ return ref;
356
+ }
335
357
  lose(what) {
336
358
  if (this.env.strict)
337
359
  throw new SnapshotError(`Codec gap: ${what} has no data form.`);
@@ -421,6 +443,10 @@ class Decoder {
421
443
  filled;
422
444
  // Derived state is rebuilt once every record is filled in, since it reads other records.
423
445
  resets = [];
446
+ // Functions inside values extensions returned, wrapped again once every record is filled in.
447
+ hostFunctions = [];
448
+ // Those values, given back once each by their extension's `snapshot.decode`, by `HostValue` record.
449
+ hostValues = new Map();
424
450
  specs;
425
451
  constructor(records, env) {
426
452
  this.records = records;
@@ -464,7 +490,10 @@ class Decoder {
464
490
  return named;
465
491
  }
466
492
  case "LostNative":
493
+ case "HostFunction":
467
494
  return Object.create(Native.prototype);
495
+ case "HostValue":
496
+ return {};
468
497
  case "Interruption":
469
498
  return this.env.interruption();
470
499
  case "Error": {
@@ -607,6 +636,11 @@ class Decoder {
607
636
  native.callback = true;
608
637
  return;
609
638
  }
639
+ case "HostFunction":
640
+ this.fillClass(target, record, hostFunction, false);
641
+ this.hostFunctions.push([target, record]);
642
+ return;
643
+ case "HostValue":
610
644
  case "Interruption":
611
645
  case "URL":
612
646
  case "URLSearchParams":
@@ -643,6 +677,32 @@ class Decoder {
643
677
  finish() {
644
678
  for (const reset of this.resets)
645
679
  reset();
680
+ if (this.hostFunctions.length === 0)
681
+ return;
682
+ const hosts = this.env.hosts ?? invalid("a function from an extension is saved, and this runtime has no extensions.");
683
+ for (const [target, record] of this.hostFunctions) {
684
+ const extension = text(record.e, "an extension");
685
+ const path = list(record.k, "a path").map((key) => typeof key === "number" ? count(key, "a path index") : text(key, "a path key"));
686
+ hosts.rewrap(target, {
687
+ extension,
688
+ root: this.hostValue(hosts, record.h, extension),
689
+ path,
690
+ label: text(record.l, "a label"),
691
+ });
692
+ }
693
+ }
694
+ // A value an extension returned, given back once by its `snapshot.decode` from the data it saved.
695
+ hostValue(hosts, ref, extension) {
696
+ const id = Array.isArray(ref) && ref[0] === "r" ? count(ref[1], "a record id") : invalid("a host value is not a record.");
697
+ const known = this.hostValues.get(id);
698
+ if (known !== undefined)
699
+ return known;
700
+ const record = id < this.records.length ? this.at(id) : invalid(`record ${id} does not exist.`);
701
+ if (record.t !== "HostValue" || record.e !== extension)
702
+ invalid(`record ${id} is not a value of ${extension}.`);
703
+ const root = hosts.decode(extension, this.value(record.d));
704
+ this.hostValues.set(id, root);
705
+ return root;
646
706
  }
647
707
  // An object's prototype, extensibility, and properties. A named object's accessors stay the ones it was made with.
648
708
  fillObj(target, record) {
@@ -730,6 +790,43 @@ class Decoder {
730
790
  return invalid(`unknown tag ${String(value[0])}.`);
731
791
  }
732
792
  }
793
+ // What an extension's `snapshot.encode` gives must be plain data the codec copies and hands back to `decode`: JSON
794
+ // values and Uint8Arrays. Views (such as a `Buffer` slice on a shared slab) are copied into standalone `Uint8Array`s.
795
+ const plainData = (data, extension, seen) => {
796
+ if (data === null || typeof data === "string" || typeof data === "boolean")
797
+ return data;
798
+ if (typeof data === "number" && Number.isFinite(data))
799
+ return data;
800
+ if (data instanceof Uint8Array) {
801
+ return data.constructor === Uint8Array && data.byteOffset === 0 && data.byteLength === data.buffer.byteLength
802
+ ? data
803
+ : new Uint8Array(data);
804
+ }
805
+ const fail = (what) => {
806
+ throw new SnapshotError(`The extension "${extension}" saved a value it returned as data holding ${what}; snapshot.encode must give plain data (JSON values and Uint8Arrays).`);
807
+ };
808
+ if (typeof data !== "object") {
809
+ return fail(data === undefined ? "undefined" : typeof data === "number" ? String(data) : `a ${typeof data}`);
810
+ }
811
+ if (seen.has(data))
812
+ return fail("a circular reference");
813
+ const proto = Object.getPrototypeOf(data);
814
+ if (!Array.isArray(data) && proto !== Object.prototype && proto !== null) {
815
+ const name = data.constructor?.name ?? "object";
816
+ return fail(`${/^[AEIOU]/.test(name) ? "an" : "a"} ${name}`);
817
+ }
818
+ seen.add(data);
819
+ if (Array.isArray(data)) {
820
+ const out = data.map((item) => plainData(item, extension, seen));
821
+ seen.delete(data);
822
+ return out;
823
+ }
824
+ const out = proto === null ? Object.create(null) : {};
825
+ for (const [key, item] of Object.entries(data))
826
+ out[key] = plainData(item, extension, seen);
827
+ seen.delete(data);
828
+ return out;
829
+ };
733
830
  const functionName = (fn) => {
734
831
  const slot = fn.props.get("name");
735
832
  return slot !== undefined && "value" in slot && typeof slot.value === "string" && slot.value !== ""