@nimbus-sh/fabric 0.1.0 → 0.3.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.
Files changed (104) hide show
  1. package/README.md +208 -293
  2. package/dist/bindings.js +5 -5
  3. package/dist/budgets.d.ts +132 -0
  4. package/dist/budgets.d.ts.map +1 -0
  5. package/dist/budgets.js +248 -0
  6. package/dist/composition.d.ts +3 -0
  7. package/dist/composition.d.ts.map +1 -0
  8. package/dist/composition.js +2 -0
  9. package/dist/connections.d.ts +81 -0
  10. package/dist/connections.d.ts.map +1 -0
  11. package/dist/connections.js +114 -0
  12. package/dist/derived.d.ts +65 -0
  13. package/dist/derived.d.ts.map +1 -0
  14. package/dist/derived.js +95 -0
  15. package/dist/do-calls.d.ts +94 -0
  16. package/dist/do-calls.d.ts.map +1 -0
  17. package/dist/do-calls.js +111 -0
  18. package/dist/facet-pool.d.ts +90 -0
  19. package/dist/facet-pool.d.ts.map +1 -0
  20. package/dist/facet-pool.js +113 -0
  21. package/dist/{fanout-pool.d.ts → fanout.d.ts} +20 -20
  22. package/dist/fanout.d.ts.map +1 -0
  23. package/dist/{fanout-pool.js → fanout.js} +20 -20
  24. package/dist/{launch-journal.d.ts → fenced-work.d.ts} +58 -17
  25. package/dist/fenced-work.d.ts.map +1 -0
  26. package/dist/fenced-work.js +241 -0
  27. package/dist/generation.d.ts +69 -0
  28. package/dist/generation.d.ts.map +1 -0
  29. package/dist/generation.js +118 -0
  30. package/dist/{facet-image-store.d.ts → image-store.d.ts} +8 -8
  31. package/dist/image-store.d.ts.map +1 -0
  32. package/dist/{facet-image-store.js → image-store.js} +4 -4
  33. package/dist/index.d.ts +16 -8
  34. package/dist/index.d.ts.map +1 -1
  35. package/dist/index.js +16 -8
  36. package/dist/{loader-pool.d.ts → isolate-pool.d.ts} +19 -19
  37. package/dist/isolate-pool.d.ts.map +1 -0
  38. package/dist/{loader-pool.js → isolate-pool.js} +20 -20
  39. package/dist/journal.d.ts +111 -0
  40. package/dist/journal.d.ts.map +1 -0
  41. package/dist/journal.js +177 -0
  42. package/dist/outbox.d.ts +249 -0
  43. package/dist/outbox.d.ts.map +1 -0
  44. package/dist/outbox.js +355 -0
  45. package/dist/process-fabric.d.ts +33 -15
  46. package/dist/process-fabric.d.ts.map +1 -1
  47. package/dist/process-fabric.js +25 -15
  48. package/dist/process-host.d.ts +1 -1
  49. package/dist/process-host.d.ts.map +1 -1
  50. package/dist/process-host.js +19 -11
  51. package/dist/sealed.d.ts +78 -0
  52. package/dist/sealed.d.ts.map +1 -0
  53. package/dist/sealed.js +145 -0
  54. package/dist/timers.d.ts +138 -0
  55. package/dist/timers.d.ts.map +1 -0
  56. package/dist/timers.js +231 -0
  57. package/dist/{launch-pacer.d.ts → turn-budget.d.ts} +24 -21
  58. package/dist/turn-budget.d.ts.map +1 -0
  59. package/dist/{launch-pacer.js → turn-budget.js} +24 -12
  60. package/dist/workerd-facet-host.d.ts +67 -70
  61. package/dist/workerd-facet-host.d.ts.map +1 -1
  62. package/dist/workerd-facet-host.js +129 -181
  63. package/examples/agent-core-adapter.ts +191 -0
  64. package/package.json +4 -2
  65. package/src/bindings.ts +6 -6
  66. package/src/budgets.ts +308 -0
  67. package/src/composition.ts +16 -0
  68. package/src/connections.ts +140 -0
  69. package/src/derived.ts +135 -0
  70. package/src/do-calls.ts +156 -0
  71. package/src/facet-pool.ts +157 -0
  72. package/src/{fanout-pool.ts → fanout.ts} +35 -35
  73. package/src/{launch-journal.ts → fenced-work.ts} +129 -42
  74. package/src/generation.ts +144 -0
  75. package/src/{facet-image-store.ts → image-store.ts} +9 -9
  76. package/src/index.ts +16 -8
  77. package/src/{loader-pool.ts → isolate-pool.ts} +34 -34
  78. package/src/journal.ts +242 -0
  79. package/src/node-async-hooks.d.ts +14 -0
  80. package/src/outbox.ts +520 -0
  81. package/src/process-fabric.ts +43 -34
  82. package/src/process-host.ts +22 -20
  83. package/src/sealed.ts +150 -0
  84. package/src/timers.ts +294 -0
  85. package/src/{launch-pacer.ts → turn-budget.ts} +34 -27
  86. package/src/workerd-facet-host.ts +159 -208
  87. package/dist/alarms.d.ts +0 -134
  88. package/dist/alarms.d.ts.map +0 -1
  89. package/dist/alarms.js +0 -214
  90. package/dist/ctx-exports.d.ts +0 -47
  91. package/dist/ctx-exports.d.ts.map +0 -1
  92. package/dist/ctx-exports.js +0 -54
  93. package/dist/facet-image-store.d.ts.map +0 -1
  94. package/dist/fanout-pool.d.ts.map +0 -1
  95. package/dist/launch-journal.d.ts.map +0 -1
  96. package/dist/launch-journal.js +0 -154
  97. package/dist/launch-pacer.d.ts.map +0 -1
  98. package/dist/loader-ledger.d.ts +0 -57
  99. package/dist/loader-ledger.d.ts.map +0 -1
  100. package/dist/loader-ledger.js +0 -91
  101. package/dist/loader-pool.d.ts.map +0 -1
  102. package/src/alarms.ts +0 -275
  103. package/src/ctx-exports.ts +0 -77
  104. package/src/loader-ledger.ts +0 -112
@@ -1,5 +1,5 @@
1
1
  /**
2
- * launch-pacer.ts — spreading a resident launch across Durable Object turns.
2
+ * turn-budget.ts — spreading a resident launch across Durable Object turns.
3
3
  *
4
4
  * Building a resident process is the largest single span of computation this
5
5
  * session performs: for pi it walks a 17 MB source tree through eight
@@ -33,7 +33,7 @@
33
33
  * bytes and treats its wall guard as coarse.
34
34
  */
35
35
  /** How a paced launch gets back onto a fresh Durable Object turn. */
36
- export interface LaunchTurnScheduler {
36
+ export interface TurnScheduler {
37
37
  /**
38
38
  * Suspend until a fresh turn is running this launch again.
39
39
  *
@@ -52,7 +52,7 @@ export interface LaunchTurnScheduler {
52
52
  * each an alarm round trip — small enough not to dominate a launch. pi's
53
53
  * 22.9 MB map crosses this about a dozen times per phase that handles it.
54
54
  */
55
- export declare const LAUNCH_CHUNK_MAX_BYTES = 2000000;
55
+ export declare const TURN_CHUNK_MAX_BYTES = 2000000;
56
56
  /**
57
57
  * Accounts launch progress and ends the turn when a chunk's worth has been
58
58
  * spent.
@@ -63,7 +63,7 @@ export declare const LAUNCH_CHUNK_MAX_BYTES = 2000000;
63
63
  * behaviour and cost. Nothing here decides WHAT the launch does, only where it
64
64
  * is allowed to stop.
65
65
  */
66
- export declare class LaunchPacer {
66
+ export declare class TurnBudget {
67
67
  private readonly scheduler;
68
68
  private readonly maxChunkBytes;
69
69
  private readonly stillWanted?;
@@ -81,7 +81,7 @@ export declare class LaunchPacer {
81
81
  * place a launch can be interrupted, rather than at whichever phases
82
82
  * remembered to ask.
83
83
  */
84
- constructor(scheduler: LaunchTurnScheduler, maxChunkBytes?: number, stillWanted?: (() => void) | undefined);
84
+ constructor(scheduler: TurnScheduler, maxChunkBytes?: number, stillWanted?: (() => void) | undefined);
85
85
  /**
86
86
  * Account `bytes` of completed work, ending the turn if a chunk is full.
87
87
  *
@@ -97,32 +97,31 @@ export declare class LaunchPacer {
97
97
  */
98
98
  settle(): void;
99
99
  }
100
- /** What {@link LaunchTurnPump} needs from the Durable Object hosting it. */
101
- export interface LaunchTurnPumpHost {
100
+ /** `Promise.withResolvers` for the runtime the project targets. */
101
+ export declare function withResolvers<T = void>(): {
102
+ promise: Promise<T>;
103
+ resolve: (value: T | PromiseLike<T>) => void;
104
+ };
105
+ /** What {@link PacedWork} needs from the Durable Object hosting it. */
106
+ export interface PacedWorkHost {
102
107
  /**
103
- * Arrange for {@link LaunchTurnPump.pump} to run on a fresh Durable Object
108
+ * Arrange for {@link PacedWork.pump} to run on a fresh Durable Object
104
109
  * turn.
105
110
  *
106
111
  * The embedder satisfies this with an alarm, which is the only primitive
107
112
  * that genuinely re-enters the object: a fresh turn is both a released
108
113
  * thread and a fresh CPU budget, and a launch needs each for a different
109
114
  * reason. Without it the pump degrades to a same-context timer — see
110
- * {@link LaunchTurnPump.nextTurn}.
115
+ * {@link PacedWork.nextTurn}.
111
116
  */
112
117
  requestTurn?: () => void;
113
- /**
114
- * Awaited first on every pump, before any waiter resumes. Where the
115
- * resident-launch journal's recovery sits: the pump is what an alarm calls,
116
- * and the first turn after a reset is the re-delivered alarm of a launch
117
- * the reset interrupted.
118
- */
119
- recover?: () => Promise<void>;
120
118
  }
121
119
  /**
122
- * The granting side of {@link LaunchTurnScheduler}: parks suspended launches
120
+ * The granting side of {@link TurnScheduler}: parks suspended launches
123
121
  * and resumes every one of them when the host grants a fresh turn.
124
122
  */
125
- export declare class LaunchTurnPump implements LaunchTurnScheduler {
123
+ export declare class PacedWork implements TurnScheduler {
124
+ private readonly ctx;
126
125
  private readonly host;
127
126
  /**
128
127
  * Launches suspended between chunks, waiting for a turn of their own.
@@ -135,7 +134,11 @@ export declare class LaunchTurnPump implements LaunchTurnScheduler {
135
134
  * from its inputs is the same idempotent work again.
136
135
  */
137
136
  private waiters;
138
- constructor(host: LaunchTurnPumpHost);
137
+ /**
138
+ * `ctx` keys the cold-start queue the pump drains first on every turn it
139
+ * grants — see {@link pump}.
140
+ */
141
+ constructor(ctx: object, host: PacedWorkHost);
139
142
  /**
140
143
  * How a paced launch asks for a fresh turn.
141
144
  *
@@ -169,5 +172,5 @@ export declare class LaunchTurnPump implements LaunchTurnScheduler {
169
172
  * `git/commands.ts` carries `NIMBUS_GIT_CHECKOUT_CHUNK_ENTRIES`. Unset in
170
173
  * production, where the default applies.
171
174
  */
172
- export declare function launchChunkMaxBytes(env: unknown): number;
173
- //# sourceMappingURL=launch-pacer.d.ts.map
175
+ export declare function turnChunkMaxBytes(env: unknown): number;
176
+ //# sourceMappingURL=turn-budget.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"turn-budget.d.ts","sourceRoot":"","sources":["../src/turn-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAE9C;;;;;;;;;GASG;AACH,qBAAa,UAAU;IAkBnB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAnB/B,qEAAqE;IACrE,MAAM,SAAK;IACX,iDAAiD;IACjD,KAAK,SAAK;IAEV,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,UAAU,CAA8D;IAEhF;;;;;;;OAOG;gBAEgB,SAAS,EAAE,aAAa,EACxB,aAAa,GAAE,MAA6B,EAC5C,WAAW,CAAC,GAAE,MAAM,IAAI,aAAA;IAG3C;;;;;;OAMG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAczC;;;;OAIG;IACH,MAAM,IAAI,IAAI;CAIf;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,CAAC,GAAG,IAAI,KAAK;IAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAAC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;CAAE,CAI/G;AAED,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED;;;GAGG;AACH,qBAAa,SAAU,YAAW,aAAa;IAkB3C,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAlBvB;;;;;;;;;OASG;IACH,OAAO,CAAC,OAAO,CAAgE;IAE/E;;;OAGG;gBAEgB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,aAAa;IAGtC;;;;;;;;;OASG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlD;;;;;;;OAOG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAa3B,0DAA0D;IAC1D,IAAI,UAAU,IAAI,OAAO,CAExB;CACF;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAMtD"}
@@ -1,5 +1,5 @@
1
1
  /**
2
- * launch-pacer.ts — spreading a resident launch across Durable Object turns.
2
+ * turn-budget.ts — spreading a resident launch across Durable Object turns.
3
3
  *
4
4
  * Building a resident process is the largest single span of computation this
5
5
  * session performs: for pi it walks a 17 MB source tree through eight
@@ -32,6 +32,7 @@
32
32
  * `git/network-facet.ts` bounds its checkout chunks by entries and decoded
33
33
  * bytes and treats its wall guard as coarse.
34
34
  */
35
+ import { runColdStart } from './generation.js';
35
36
  /**
36
37
  * Bytes of launch work one turn may perform before it must yield.
37
38
  *
@@ -40,7 +41,7 @@
40
41
  * each an alarm round trip — small enough not to dominate a launch. pi's
41
42
  * 22.9 MB map crosses this about a dozen times per phase that handles it.
42
43
  */
43
- export const LAUNCH_CHUNK_MAX_BYTES = 2_000_000;
44
+ export const TURN_CHUNK_MAX_BYTES = 2_000_000;
44
45
  /**
45
46
  * Accounts launch progress and ends the turn when a chunk's worth has been
46
47
  * spent.
@@ -51,7 +52,7 @@ export const LAUNCH_CHUNK_MAX_BYTES = 2_000_000;
51
52
  * behaviour and cost. Nothing here decides WHAT the launch does, only where it
52
53
  * is allowed to stop.
53
54
  */
54
- export class LaunchPacer {
55
+ export class TurnBudget {
55
56
  scheduler;
56
57
  maxChunkBytes;
57
58
  stillWanted;
@@ -69,7 +70,7 @@ export class LaunchPacer {
69
70
  * place a launch can be interrupted, rather than at whichever phases
70
71
  * remembered to ask.
71
72
  */
72
- constructor(scheduler, maxChunkBytes = LAUNCH_CHUNK_MAX_BYTES, stillWanted) {
73
+ constructor(scheduler, maxChunkBytes = TURN_CHUNK_MAX_BYTES, stillWanted) {
73
74
  this.scheduler = scheduler;
74
75
  this.maxChunkBytes = maxChunkBytes;
75
76
  this.stillWanted = stillWanted;
@@ -105,16 +106,18 @@ export class LaunchPacer {
105
106
  this.chunkEnded = undefined;
106
107
  }
107
108
  }
108
- function withResolvers() {
109
+ /** `Promise.withResolvers` for the runtime the project targets. */
110
+ export function withResolvers() {
109
111
  let resolve;
110
112
  const promise = new Promise((r) => { resolve = r; });
111
113
  return { promise, resolve };
112
114
  }
113
115
  /**
114
- * The granting side of {@link LaunchTurnScheduler}: parks suspended launches
116
+ * The granting side of {@link TurnScheduler}: parks suspended launches
115
117
  * and resumes every one of them when the host grants a fresh turn.
116
118
  */
117
- export class LaunchTurnPump {
119
+ export class PacedWork {
120
+ ctx;
118
121
  host;
119
122
  /**
120
123
  * Launches suspended between chunks, waiting for a turn of their own.
@@ -127,7 +130,12 @@ export class LaunchTurnPump {
127
130
  * from its inputs is the same idempotent work again.
128
131
  */
129
132
  waiters = [];
130
- constructor(host) {
133
+ /**
134
+ * `ctx` keys the cold-start queue the pump drains first on every turn it
135
+ * grants — see {@link pump}.
136
+ */
137
+ constructor(ctx, host) {
138
+ this.ctx = ctx;
131
139
  this.host = host;
132
140
  }
133
141
  /**
@@ -159,7 +167,11 @@ export class LaunchTurnPump {
159
167
  * the runtime may tear the context down mid-chunk.
160
168
  */
161
169
  async pump() {
162
- await this.host.recover?.();
170
+ // Deferred reconciliation runs first, before any waiter resumes. Where
171
+ // the resident-launch journal's recovery sits (`onColdStart`): the pump
172
+ // is what an alarm calls, and the first turn after a reset is the
173
+ // re-delivered alarm of a launch the reset interrupted.
174
+ await runColdStart(this.ctx);
163
175
  const waiting = this.waiters;
164
176
  if (waiting.length === 0)
165
177
  return;
@@ -183,11 +195,11 @@ export class LaunchTurnPump {
183
195
  * `git/commands.ts` carries `NIMBUS_GIT_CHECKOUT_CHUNK_ENTRIES`. Unset in
184
196
  * production, where the default applies.
185
197
  */
186
- export function launchChunkMaxBytes(env) {
198
+ export function turnChunkMaxBytes(env) {
187
199
  const raw = env
188
200
  ?.NIMBUS_LAUNCH_CHUNK_BYTES;
189
201
  if (!raw)
190
- return LAUNCH_CHUNK_MAX_BYTES;
202
+ return TURN_CHUNK_MAX_BYTES;
191
203
  const parsed = Number(raw);
192
- return Number.isFinite(parsed) && parsed > 0 ? parsed : LAUNCH_CHUNK_MAX_BYTES;
204
+ return Number.isFinite(parsed) && parsed > 0 ? parsed : TURN_CHUNK_MAX_BYTES;
193
205
  }
@@ -12,7 +12,7 @@
12
12
  * that is not a Durable Object implements `ProcessHost` against the same
13
13
  * `HostedProcess` and never imports this file.
14
14
  */
15
- import { type HostedProcess, type OneShotParams, type ProcessHostParams, type ResidentDiskReader, type ResidentSupervisorProps } from './process-fabric.js';
15
+ import { type HostedProcess, type OneShotParams, type ProcessHostParams, type ResidentBootSpec, type ResidentDiskReader, type ResidentSupervisorProps } from './process-fabric.js';
16
16
  /** Structural surface of a NimbusLoadedEntrypoint RPC stub. */
17
17
  export interface LoadedWorkerEntrypointStub {
18
18
  handleHttpRequest?: (request: Request) => Promise<Response>;
@@ -45,30 +45,6 @@ export declare function createLoadedWorkerEntrypoint(ctxExports: NimbusCtxExport
45
45
  pid: number;
46
46
  writerId: string;
47
47
  }, stage: unknown, name?: string | null): Promise<LoadedWorkerEntrypointStub>;
48
- /**
49
- * Total bytes a dynamic Worker's module map may carry, across every member of
50
- * it. A hard platform limit, not a policy knob: 62 MiB lands and 64 MiB is
51
- * refused with "Dynamic Worker code size (N bytes) exceeds the maximum allowed
52
- * size of 67108864 bytes", confirmed at five sizes with two trials each. The
53
- * budget is shared, so a ruby process is already 34.3 MiB down before its disk
54
- * is counted.
55
- */
56
- export declare const DYNAMIC_WORKER_CODE_LIMIT_BYTES = 67108864;
57
- /**
58
- * Refuse a module map over {@link DYNAMIC_WORKER_CODE_LIMIT_BYTES}, naming
59
- * the largest members. The platform's own refusal reports one number for a
60
- * budget shared across every member of the map, which tells the operator
61
- * nothing about WHAT to shrink — so every fabric seam that assembles a map
62
- * runs this before the loader sees it.
63
- *
64
- * Costed to its two paths. Under the ceiling: one length read per member —
65
- * UTF-16 code units for text, which equal UTF-8 bytes for the ASCII module
66
- * text the generators emit and undercount otherwise; the platform's own
67
- * refusal still backstops the exotic case, because this check exists to name
68
- * members, not to be the ceiling. Over it: exact UTF-8 sizes, computed only
69
- * then, sorted so the biggest lever is first.
70
- */
71
- export declare function assertModuleMapWithinCodeLimit(modules: Record<string, unknown>): void;
72
48
  /** What an unkeyed `LOADER.load` hands back. */
73
49
  interface LoadedWorkerStub {
74
50
  getEntrypoint(): LoadedWorkerEntrypointStub;
@@ -81,15 +57,20 @@ interface LoadedWorkerStub {
81
57
  * Durable Object class, so a resident process can be re-entered; `load` is
82
58
  * unkeyed and yields a stateless entrypoint, which is all a program that ends
83
59
  * with its call can ever need.
60
+ *
61
+ * `get` stays wide on purpose: the platform passes a null id for the unkeyed
62
+ * call and answers the callback with the code object or a promise of it, so a
63
+ * narrower declaration would refuse the real binding. The fabric itself always
64
+ * passes a string id and a promise callback.
84
65
  */
85
66
  interface WorkerLoaderBinding {
86
- get(id: string, code: () => Promise<unknown>): {
67
+ get(id: string | null, code: () => unknown): {
87
68
  getDurableObjectClass(name: string): unknown;
88
69
  };
89
70
  load(code: unknown): LoadedWorkerStub;
90
71
  }
91
72
  /**
92
- * The bindings `openResidentFacet` needs off whichever DO is hosting. A
73
+ * The bindings `processes` needs off whichever DO is hosting. A
93
74
  * staged boot's assembler may read more off the same env (Nimbus's reads
94
75
  * ASSETS); the env travels to it whole, so nothing further is named here.
95
76
  */
@@ -124,13 +105,13 @@ export interface ResidentFacetEnv {
124
105
  * storage budget grants no copy-on-write credit — crossing it resets the
125
106
  * object rather than raising an error.
126
107
  */
127
- export declare function cloneFacetStorage(ctx: DurableObjectState, clone: {
108
+ export declare function cloneStorage(ctx: DurableObjectState, clone: {
128
109
  src: string;
129
110
  dst: string;
130
111
  populated(name: string): boolean | Promise<boolean>;
131
112
  }): Promise<void>;
132
113
  /**
133
- * The facet name for a slot. Reused, and that is the entire point.
114
+ * The facet name for an ephemeral slot. Reused, and that is the entire point.
134
115
  *
135
116
  * A Durable Object admits 65,536 facets over its LIFETIME: the IDs are
136
117
  * append-only and are never reclaimed, so the bound is on facets ever CREATED,
@@ -142,66 +123,82 @@ export declare function cloneFacetStorage(ctx: DurableObjectState, clone: {
142
123
  * Reusing a NAME costs no new ID. So the name comes from a free list and the
143
124
  * pid stays what it always was: the process identity in the ProcessTable. The
144
125
  * two were only ever conflated because one of them happened to be handy.
126
+ *
127
+ * The book shares the facet-ID space with one other namespace: durable
128
+ * applications, which mint `app-slot-<n>` names of their own (one ID per app,
129
+ * ever). The prefixes are disjoint BY CONSTRUCTION, and that disjointness is
130
+ * load-bearing — a proc-slot name reissued onto a durable app's retained
131
+ * storage would boot the wrong process into someone else's disk.
145
132
  */
146
133
  export declare function residentFacetName(slot: number): string;
134
+ /** The prefix every durable application's facet name carries. */
135
+ export declare const DURABLE_FACET_NAME_PREFIX = "app-slot-";
147
136
  /**
148
- * Facet IDs a Durable Object is granted over its LIFETIME. Append-only and
149
- * never reclaimed, so crossing it is unrecoverable for the object — which is
150
- * why the ledger below counts consumption durably instead of leaving the
151
- * bound as prose the slot book merely respects.
152
- */
153
- export declare const FACET_ID_LIFETIME_BUDGET = 65536;
154
- /** Where the ledger persists the count of facet names ever minted. */
155
- export declare const FACET_NAME_HIGH_WATER_KEY = "fabric_facet_name_high_water";
156
- /**
157
- * The lifetime facet-ID ledger: how many facet names this fabric has ever
158
- * minted on the Durable Object, against the 65,536 the platform will ever
159
- * grant it. `consumed` only ever counts FIRST uses — a reused name, in this
160
- * incarnation or any earlier one, cost no new ID, which is the slot book's
161
- * whole reason to exist. Surfaced so an operator can see proximity to a wall
162
- * whose crossing is unrecoverable, instead of discovering it from the
163
- * platform's opaque failure.
137
+ * Drop one facet's SQLite by name — the ONLY call site that may delete facet
138
+ * storage. `spawnResident` releases ephemeral processes with abort+delete
139
+ * (storage is slot-reuse hygiene) and durable ones with abort alone (the
140
+ * storage IS the durable application's state); explicit removal arrives here
141
+ * through the coordinator's durable-slot book, owner-checked.
164
142
  */
165
- export declare function facetIdBudget(ctx: DurableObjectState): Promise<{
166
- consumed: number;
167
- budget: number;
168
- }>;
143
+ export declare function deleteFacetStorage(ctx: DurableObjectState, name: string): void;
169
144
  /**
170
- * What `openResidentFacet` hands back: a running process, minus its placement.
145
+ * What `processes(ctx, env).spawn` hands back: a running process, minus its placement.
171
146
  *
172
- * `slot` rides along because the caller's `describe` needs the facet's real
173
- * name and the slot is not derivable from the pid — that indirection is the
174
- * whole point of the free list. Reading it back out of the book later would
175
- * also race the release that empties it.
147
+ * `name` is the facet's real name and `slot` its ephemeral book entry (absent
148
+ * for a durable spawn, whose name its coordinator allocated out of storage).
149
+ * Both ride along because the caller's `describe` needs them and neither is
150
+ * derivable from the pid — reading a slot back out of the book would race the
151
+ * release that empties it.
176
152
  */
177
153
  export type ResidentFacet = Omit<HostedProcess, 'describe'> & {
178
- slot: number;
154
+ name: string;
155
+ slot?: number;
179
156
  };
180
157
  /**
181
- * Open a resident process as a facet of the actor whose `ctx` and `env` are
182
- * given, and start its runner.
158
+ * The process surface of one hosting actor: how a resident process comes
159
+ * into existence on workerd, and how a one-shot program runs to completion.
183
160
  *
184
- * This is the ONE way a resident process comes into existence, and every
161
+ * `spawn` is the ONE way a resident process comes into existence, and every
185
162
  * substrate goes through it: the facet host calls it with the coordinator's
186
163
  * own `ctx`, the peer host calls it — over one RPC — with a sibling session
187
164
  * DO's. Everything a substrate could plausibly want to special-case is a
188
165
  * PARAMETER here rather than a branch: which actor hosts the child, and how
189
166
  * the boot spec's by-path members are read.
190
167
  */
191
- export declare function openResidentFacet(ctx: DurableObjectState, env: ResidentFacetEnv, disk: () => ResidentDiskReader, supervisor: ResidentSupervisorProps, params: ProcessHostParams): ResidentFacet;
168
+ export declare function processes(ctx: DurableObjectState, env: ResidentFacetEnv): Processes;
169
+ export declare class Processes {
170
+ private readonly ctx;
171
+ private readonly env;
172
+ constructor(ctx: DurableObjectState, env: ResidentFacetEnv);
173
+ /** Open a resident process as a facet of this actor, and start its runner. */
174
+ spawn(disk: () => ResidentDiskReader, supervisor: ResidentSupervisorProps, params: ProcessHostParams): ResidentFacet;
175
+ /**
176
+ * Run one program to completion as an UNKEYED dynamic worker.
177
+ *
178
+ * Unkeyed is the whole difference from `spawn`: nothing can re-resolve this
179
+ * worker into a later request's context, so it can never be a routeable
180
+ * target and never has to be released by name. It exists for the duration
181
+ * of one call and its stubs are dropped as that call unwinds.
182
+ *
183
+ * Shared by both substrates on purpose. `peer` places processes that have a
184
+ * residency to place; a one-shot has none, and shipping its fully-inline
185
+ * map across a sibling hop would meet the 32 MiB RPC ceiling that by-path
186
+ * boot specs exist to avoid — for a run that gains nothing by moving.
187
+ */
188
+ run<T>(supervisor: ResidentSupervisorProps, params: OneShotParams, consume: (response: Response) => Promise<T>): Promise<T>;
189
+ }
192
190
  /**
193
- * Run one program to completion as an UNKEYED dynamic worker.
194
- *
195
- * Unkeyed is the whole difference from `openResidentFacet`: nothing can
196
- * re-resolve this worker into a later request's context, so it can never be a
197
- * routeable target and never has to be released by name. It exists for the
198
- * duration of one call and its stubs are dropped as that call unwinds.
191
+ * The WorkerCode the loader callback returns for one resident boot: the
192
+ * module map from {@link residentLoaderConfig} (or the staged assembler),
193
+ * plus the isolate's env and network posture.
199
194
  *
200
- * Shared by both substrates on purpose. `peer` places processes that have a
201
- * residency to place; a one-shot has none, and shipping its fully-inline map
202
- * across a sibling hop would meet the 32 MiB RPC ceiling that by-path boot
203
- * specs exist to avoid — for a run that gains nothing by moving.
195
+ * A `code` boot with an explicit `env` — defined, even as `{}` — is the
196
+ * embedder's whole statement about the isolate: the env rides through
197
+ * exactly as minted (loopback stubs by reference), and the composed supervisor
198
+ * entrypoint is not consulted at all, so no SUPERVISOR binding appears.
199
+ * Without one, the default holds: inherited network plus a SUPERVISOR
200
+ * minted from the composed entrypoint for the coordinator's identity.
204
201
  */
205
- export declare function runOneShotWorker<T>(ctx: DurableObjectState, env: ResidentFacetEnv, supervisor: ResidentSupervisorProps, params: OneShotParams, consume: (response: Response) => Promise<T>): Promise<T>;
202
+ export declare function residentWorkerConfig(env: ResidentFacetEnv, disk: () => ResidentDiskReader, supervisor: ResidentSupervisorProps, boot: ResidentBootSpec): Promise<Record<string, unknown>>;
206
203
  export {};
207
204
  //# sourceMappingURL=workerd-facet-host.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"workerd-facet-host.d.ts","sourceRoot":"","sources":["../src/workerd-facet-host.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"workerd-facet-host.d.ts","sourceRoot":"","sources":["../src/workerd-facet-host.ts"],"names":[],"mappings":"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"}