@nimbus-sh/core 0.4.0 → 0.6.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 (156) hide show
  1. package/README.md +35 -7
  2. package/dist/_shared/cache-stats.d.ts +23 -1
  3. package/dist/_shared/cache-stats.d.ts.map +1 -1
  4. package/dist/_shared/cache-stats.js +13 -1
  5. package/dist/_shared/error-text.d.ts +15 -0
  6. package/dist/_shared/error-text.d.ts.map +1 -0
  7. package/dist/_shared/error-text.js +21 -0
  8. package/dist/_shared/exports-resolver.d.ts +19 -7
  9. package/dist/_shared/exports-resolver.d.ts.map +1 -1
  10. package/dist/_shared/exports-resolver.js +1 -1
  11. package/dist/_shared/retry.d.ts.map +1 -1
  12. package/dist/_shared/retry.js +4 -2
  13. package/dist/constants.d.ts +5 -11
  14. package/dist/constants.d.ts.map +1 -1
  15. package/dist/constants.js +23 -49
  16. package/dist/runtime/assets-loader.js +1 -1
  17. package/dist/runtime/esbuild-service.d.ts +4 -3
  18. package/dist/runtime/esbuild-service.d.ts.map +1 -1
  19. package/dist/runtime/esbuild-service.js +9 -4
  20. package/dist/runtime/installed-runtimes.d.ts +4 -3
  21. package/dist/runtime/installed-runtimes.d.ts.map +1 -1
  22. package/dist/runtime/long-running-handle.d.ts +3 -3
  23. package/dist/runtime/long-running-handle.d.ts.map +1 -1
  24. package/dist/runtime/os-contracts.d.ts +7 -5
  25. package/dist/runtime/os-contracts.d.ts.map +1 -1
  26. package/dist/runtime/port-registry.d.ts +28 -0
  27. package/dist/runtime/port-registry.d.ts.map +1 -1
  28. package/dist/runtime/port-registry.js +79 -9
  29. package/dist/runtime/process-logs.d.ts +9 -1
  30. package/dist/runtime/process-logs.d.ts.map +1 -1
  31. package/dist/runtime/project-detect.d.ts +6 -1
  32. package/dist/runtime/project-detect.d.ts.map +1 -1
  33. package/dist/runtime/require-resolver.d.ts.map +1 -1
  34. package/dist/runtime/require-resolver.js +3 -4
  35. package/dist/runtime/runtime-registry.d.ts +4 -3
  36. package/dist/runtime/runtime-registry.d.ts.map +1 -1
  37. package/dist/runtime/runtime-registry.js +2 -1
  38. package/dist/runtime/sqlite-runtime-fs-bridge.js +1 -5
  39. package/dist/runtime/virtual-socket-kernel.d.ts.map +1 -1
  40. package/dist/runtime/virtual-socket-kernel.generated.d.ts +2 -2
  41. package/dist/runtime/virtual-socket-kernel.generated.d.ts.map +1 -1
  42. package/dist/runtime/virtual-socket-kernel.generated.js +3 -3
  43. package/dist/runtime/virtual-socket-kernel.js +10 -5
  44. package/dist/runtime/wasm-runner.d.ts.map +1 -1
  45. package/dist/runtime/wasm-runner.js +22 -14
  46. package/dist/shell/features.d.ts.map +1 -1
  47. package/dist/shell/features.js +5 -4
  48. package/dist/shell/unix-commands.d.ts +14 -1
  49. package/dist/shell/unix-commands.d.ts.map +1 -1
  50. package/dist/shell/unix-commands.js +115 -69
  51. package/dist/substrate/lifo/commands/net/ip.d.ts.map +1 -1
  52. package/dist/substrate/lifo/commands/system/ps.d.ts +2 -1
  53. package/dist/substrate/lifo/commands/system/ps.d.ts.map +1 -1
  54. package/dist/substrate/lifo/kernel/ServiceManager.d.ts.map +1 -1
  55. package/dist/substrate/lifo/kernel/ServiceManager.js +0 -2
  56. package/dist/substrate/lifo/kernel/network/NetworkStack.d.ts +22 -11
  57. package/dist/substrate/lifo/kernel/network/NetworkStack.d.ts.map +1 -1
  58. package/dist/substrate/lifo/kernel/network/NetworkStack.js +0 -2
  59. package/dist/substrate/lifo/kernel/network/tunnel/WebSocketTunnel.d.ts +2 -1
  60. package/dist/substrate/lifo/kernel/network/tunnel/WebSocketTunnel.d.ts.map +1 -1
  61. package/dist/substrate/lifo/kernel/network/tunnel/WebSocketTunnel.js +3 -4
  62. package/dist/substrate/lifo/kernel/vfs/VFS.d.ts +17 -0
  63. package/dist/substrate/lifo/kernel/vfs/VFS.d.ts.map +1 -1
  64. package/dist/substrate/lifo/kernel/vfs/VFS.js +33 -0
  65. package/dist/substrate/lifo/node-compat/esbuild.d.ts.map +1 -1
  66. package/dist/substrate/lifo/node-compat/esbuild.js +2 -4
  67. package/dist/substrate/lifo/node-compat/index.d.ts.map +1 -1
  68. package/dist/substrate/lifo/node-compat/index.js +3 -2
  69. package/dist/substrate/lifo/node-compat/loose-equality.d.ts +19 -0
  70. package/dist/substrate/lifo/node-compat/loose-equality.d.ts.map +1 -0
  71. package/dist/substrate/lifo/node-compat/loose-equality.js +91 -0
  72. package/dist/substrate/lifo/node-compat/process.d.ts.map +1 -1
  73. package/dist/substrate/lifo/node-compat/process.js +6 -3
  74. package/dist/substrate/lifo/shell/Shell.d.ts +19 -0
  75. package/dist/substrate/lifo/shell/Shell.d.ts.map +1 -1
  76. package/dist/substrate/lifo/shell/Shell.js +86 -75
  77. package/dist/substrate/lifo/shell/lexer.d.ts +9 -0
  78. package/dist/substrate/lifo/shell/lexer.d.ts.map +1 -1
  79. package/dist/substrate/lifo/shell/lexer.js +40 -0
  80. package/dist/vfs/seed-project.d.ts.map +1 -1
  81. package/dist/vfs/seed-project.js +9 -3
  82. package/dist/vfs/sqlite-vfs.d.ts +63 -31
  83. package/dist/vfs/sqlite-vfs.d.ts.map +1 -1
  84. package/dist/vfs/sqlite-vfs.js +206 -41
  85. package/package.json +3 -2
  86. package/src/_shared/cache-stats.ts +27 -1
  87. package/src/_shared/error-text.ts +21 -0
  88. package/src/_shared/exports-resolver.ts +24 -4
  89. package/src/_shared/retry.ts +5 -3
  90. package/src/constants.ts +37 -53
  91. package/src/runtime/assets-loader.ts +1 -1
  92. package/src/runtime/esbuild-service.ts +16 -11
  93. package/src/runtime/installed-runtimes.ts +4 -3
  94. package/src/runtime/long-running-handle.ts +3 -3
  95. package/src/runtime/os-contracts.ts +7 -5
  96. package/src/runtime/port-registry.ts +97 -9
  97. package/src/runtime/process-logs.ts +12 -3
  98. package/src/runtime/project-detect.ts +7 -1
  99. package/src/runtime/require-resolver.ts +7 -7
  100. package/src/runtime/runtime-registry.ts +9 -7
  101. package/src/runtime/sqlite-runtime-fs-bridge.ts +9 -6
  102. package/src/runtime/virtual-socket-kernel.generated.ts +3 -3
  103. package/src/runtime/virtual-socket-kernel.ts +10 -5
  104. package/src/runtime/wasm-runner.ts +55 -29
  105. package/src/shell/features.ts +5 -4
  106. package/src/shell/unix-commands.ts +273 -128
  107. package/src/substrate/lifo/commands/net/ip.ts +15 -15
  108. package/src/substrate/lifo/commands/system/ps.ts +2 -1
  109. package/src/substrate/lifo/kernel/ServiceManager.ts +0 -2
  110. package/src/substrate/lifo/kernel/network/NetworkStack.ts +24 -17
  111. package/src/substrate/lifo/kernel/network/tunnel/WebSocketTunnel.ts +37 -12
  112. package/src/substrate/lifo/kernel/vfs/VFS.ts +34 -0
  113. package/src/substrate/lifo/node-compat/esbuild.ts +16 -8
  114. package/src/substrate/lifo/node-compat/index.ts +3 -2
  115. package/src/substrate/lifo/node-compat/loose-equality.ts +81 -0
  116. package/src/substrate/lifo/node-compat/process.ts +5 -2
  117. package/src/substrate/lifo/shell/Shell.ts +92 -70
  118. package/src/substrate/lifo/shell/lexer.ts +38 -0
  119. package/src/vfs/seed-project.ts +13 -6
  120. package/src/vfs/sqlite-vfs.ts +233 -77
  121. package/dist/_shared/install-phase.d.ts +0 -47
  122. package/dist/_shared/install-phase.d.ts.map +0 -1
  123. package/dist/_shared/install-phase.js +0 -1
  124. package/dist/_shared/rpc-dispose.d.ts +0 -4
  125. package/dist/_shared/rpc-dispose.d.ts.map +0 -1
  126. package/dist/_shared/rpc-dispose.js +0 -30
  127. package/dist/_shared/w7-frame.d.ts +0 -79
  128. package/dist/_shared/w7-frame.d.ts.map +0 -1
  129. package/dist/_shared/w7-frame.js +0 -839
  130. package/dist/_shared/weighted-credit-pool.d.ts +0 -61
  131. package/dist/_shared/weighted-credit-pool.d.ts.map +0 -1
  132. package/dist/_shared/weighted-credit-pool.js +0 -196
  133. package/dist/observability/diag-counters.d.ts +0 -236
  134. package/dist/observability/diag-counters.d.ts.map +0 -1
  135. package/dist/observability/diag-counters.js +0 -195
  136. package/dist/observability/heap-estimate.d.ts +0 -225
  137. package/dist/observability/heap-estimate.d.ts.map +0 -1
  138. package/dist/observability/heap-estimate.js +0 -185
  139. package/dist/observability/heavy-alloc-coord.d.ts +0 -93
  140. package/dist/observability/heavy-alloc-coord.d.ts.map +0 -1
  141. package/dist/observability/heavy-alloc-coord.js +0 -181
  142. package/dist/observability/oom-classify.d.ts +0 -138
  143. package/dist/observability/oom-classify.d.ts.map +0 -1
  144. package/dist/observability/oom-classify.js +0 -261
  145. package/dist/observability/oom-discriminator.d.ts +0 -176
  146. package/dist/observability/oom-discriminator.d.ts.map +0 -1
  147. package/dist/observability/oom-discriminator.js +0 -272
  148. package/src/_shared/install-phase.ts +0 -56
  149. package/src/_shared/rpc-dispose.ts +0 -31
  150. package/src/_shared/w7-frame.ts +0 -1012
  151. package/src/_shared/weighted-credit-pool.ts +0 -244
  152. package/src/observability/diag-counters.ts +0 -343
  153. package/src/observability/heap-estimate.ts +0 -331
  154. package/src/observability/heavy-alloc-coord.ts +0 -241
  155. package/src/observability/oom-classify.ts +0 -253
  156. package/src/observability/oom-discriminator.ts +0 -405
@@ -1,61 +0,0 @@
1
- export interface CreditLease {
2
- readonly bytes: number;
3
- release(): void;
4
- }
5
- export interface ResizableCreditLease extends CreditLease {
6
- shrinkTo(bytes: number): void;
7
- }
8
- export interface WeightedCreditPoolStats {
9
- readonly current: number;
10
- readonly peak: number;
11
- readonly queued: number;
12
- }
13
- export interface WeightedCreditPoolOptions {
14
- /**
15
- * Requests at or below this size draw from `reserve` instead of the shared
16
- * capacity. Omit to keep a single lane.
17
- */
18
- readonly smallRequestBytes?: number;
19
- /**
20
- * Bytes set aside for small requests. Held apart from `capacity` so a
21
- * full-capacity owner stays grantable and small requests stay servable
22
- * while it works.
23
- */
24
- readonly reserve?: number;
25
- }
26
- /**
27
- * FIFO byte-credit pool shared by concurrent allocation owners.
28
- * Capacity is measured in retained bytes, not operation count.
29
- *
30
- * One FIFO queue makes every request wait behind the one ahead of it even
31
- * when the pool has room to spare — `tryAcquire` refuses outright while
32
- * anyone is queued — so a single multi-megabyte owner parks every request
33
- * behind it for as long as it holds. Between owners of comparable size that
34
- * is the point. For a chunk-sized filesystem read it means a wait with
35
- * nothing to do with its own cost.
36
- *
37
- * So a request at or below `smallRequestBytes` takes shared capacity when
38
- * that can be granted outright, and otherwise falls back to a separate
39
- * `reserve` where it queues only among its own kind. It never joins the
40
- * shared queue, so it is never parked behind a larger owner.
41
- *
42
- * Neither side can starve the other. Shared capacity stops admitting small
43
- * requests the moment anything is queued for it, so a large waiter is never
44
- * overtaken; and the reserve is held apart from `capacity`, so a
45
- * full-capacity owner stays grantable while small requests stay servable.
46
- * Peak occupancy only reaches `capacity + reserve` while the shared lane is
47
- * contended.
48
- */
49
- export declare class WeightedCreditPool {
50
- readonly capacity: number;
51
- private readonly general;
52
- private readonly small;
53
- private readonly smallRequestBytes;
54
- constructor(capacity: number, options?: WeightedCreditPoolOptions);
55
- get stats(): WeightedCreditPoolStats;
56
- private isSmall;
57
- tryAcquire(bytes: number): ResizableCreditLease | null;
58
- acquire(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease>;
59
- private validateRequest;
60
- }
61
- //# sourceMappingURL=weighted-credit-pool.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"weighted-credit-pool.d.ts","sourceRoot":"","sources":["../../src/_shared/weighted-credit-pool.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,oBAAqB,SAAQ,WAAW;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAkHD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,kBAAkB;IAKjB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAJrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;gBAEtB,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,yBAA8B;IAoB9E,IAAI,KAAK,IAAI,uBAAuB,CASnC;IAED,OAAO,CAAC,OAAO;IAIf,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI;IAOtD,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAiB3E,OAAO,CAAC,eAAe;CAOxB"}
@@ -1,196 +0,0 @@
1
- /** One FIFO queue over one byte capacity. */
2
- class CreditLane {
3
- capacity;
4
- current = 0;
5
- peak = 0;
6
- waiters = [];
7
- constructor(capacity) {
8
- this.capacity = capacity;
9
- }
10
- get stats() {
11
- return { current: this.current, peak: this.peak, queued: this.waiters.length };
12
- }
13
- tryAcquire(bytes) {
14
- if (this.waiters.length > 0 || this.current + bytes > this.capacity)
15
- return null;
16
- return this.grant(bytes);
17
- }
18
- acquire(bytes, signal) {
19
- if (signal?.aborted)
20
- return Promise.reject(abortError(signal));
21
- const immediate = this.tryAcquire(bytes);
22
- if (immediate)
23
- return Promise.resolve(immediate);
24
- return new Promise((resolve, reject) => {
25
- const waiter = {
26
- bytes,
27
- resolve,
28
- reject,
29
- signal,
30
- onAbort: signal
31
- ? () => {
32
- const index = this.waiters.indexOf(waiter);
33
- if (index < 0)
34
- return;
35
- this.waiters.splice(index, 1);
36
- signal.removeEventListener('abort', waiter.onAbort);
37
- reject(abortError(signal));
38
- this.drain();
39
- }
40
- : undefined,
41
- };
42
- this.waiters.push(waiter);
43
- signal?.addEventListener('abort', waiter.onAbort, { once: true });
44
- if (signal?.aborted) {
45
- waiter.onAbort();
46
- return;
47
- }
48
- this.drain();
49
- });
50
- }
51
- grant(bytes) {
52
- this.current += bytes;
53
- this.peak = Math.max(this.peak, this.current);
54
- let leasedBytes = bytes;
55
- let released = false;
56
- return {
57
- get bytes() {
58
- return leasedBytes;
59
- },
60
- shrinkTo: (nextBytes) => {
61
- if (released) {
62
- throw new Error('cannot shrink a released weighted credit lease');
63
- }
64
- if (!Number.isSafeInteger(nextBytes)
65
- || nextBytes <= 0
66
- || nextBytes > leasedBytes) {
67
- throw new RangeError(`weighted credit lease can only shrink to a positive safe integer no larger than ${leasedBytes}: ${nextBytes}`);
68
- }
69
- this.current -= leasedBytes - nextBytes;
70
- leasedBytes = nextBytes;
71
- this.drain();
72
- },
73
- release: () => {
74
- if (released)
75
- return;
76
- released = true;
77
- this.current -= leasedBytes;
78
- if (this.current < 0) {
79
- throw new Error('weighted credit accounting underflow');
80
- }
81
- this.drain();
82
- },
83
- };
84
- }
85
- drain() {
86
- while (this.waiters.length > 0) {
87
- const waiter = this.waiters[0];
88
- if (waiter.signal?.aborted) {
89
- this.waiters.shift();
90
- waiter.signal.removeEventListener('abort', waiter.onAbort);
91
- waiter.reject(abortError(waiter.signal));
92
- continue;
93
- }
94
- if (this.current + waiter.bytes > this.capacity)
95
- return;
96
- this.waiters.shift();
97
- waiter.signal?.removeEventListener('abort', waiter.onAbort);
98
- waiter.resolve(this.grant(waiter.bytes));
99
- }
100
- }
101
- }
102
- /**
103
- * FIFO byte-credit pool shared by concurrent allocation owners.
104
- * Capacity is measured in retained bytes, not operation count.
105
- *
106
- * One FIFO queue makes every request wait behind the one ahead of it even
107
- * when the pool has room to spare — `tryAcquire` refuses outright while
108
- * anyone is queued — so a single multi-megabyte owner parks every request
109
- * behind it for as long as it holds. Between owners of comparable size that
110
- * is the point. For a chunk-sized filesystem read it means a wait with
111
- * nothing to do with its own cost.
112
- *
113
- * So a request at or below `smallRequestBytes` takes shared capacity when
114
- * that can be granted outright, and otherwise falls back to a separate
115
- * `reserve` where it queues only among its own kind. It never joins the
116
- * shared queue, so it is never parked behind a larger owner.
117
- *
118
- * Neither side can starve the other. Shared capacity stops admitting small
119
- * requests the moment anything is queued for it, so a large waiter is never
120
- * overtaken; and the reserve is held apart from `capacity`, so a
121
- * full-capacity owner stays grantable while small requests stay servable.
122
- * Peak occupancy only reaches `capacity + reserve` while the shared lane is
123
- * contended.
124
- */
125
- export class WeightedCreditPool {
126
- capacity;
127
- general;
128
- small;
129
- smallRequestBytes;
130
- constructor(capacity, options = {}) {
131
- this.capacity = capacity;
132
- if (!Number.isSafeInteger(capacity) || capacity <= 0) {
133
- throw new RangeError(`weighted credit capacity must be a positive safe integer: ${capacity}`);
134
- }
135
- const smallRequestBytes = options.smallRequestBytes ?? 0;
136
- const reserve = options.reserve ?? 0;
137
- if (!Number.isSafeInteger(smallRequestBytes) || smallRequestBytes < 0
138
- || !Number.isSafeInteger(reserve) || reserve < 0) {
139
- throw new RangeError('weighted credit reserve and small-request size must be non-negative safe integers');
140
- }
141
- if (smallRequestBytes > reserve) {
142
- throw new RangeError(`a small request (${smallRequestBytes}) must fit in the reserve (${reserve}) or it could never be granted`);
143
- }
144
- this.general = new CreditLane(capacity);
145
- this.smallRequestBytes = smallRequestBytes;
146
- this.small = smallRequestBytes > 0 ? new CreditLane(reserve) : null;
147
- }
148
- get stats() {
149
- const general = this.general.stats;
150
- if (!this.small)
151
- return general;
152
- const small = this.small.stats;
153
- return {
154
- current: general.current + small.current,
155
- peak: general.peak + small.peak,
156
- queued: general.queued + small.queued,
157
- };
158
- }
159
- isSmall(bytes) {
160
- return this.small !== null && bytes <= this.smallRequestBytes;
161
- }
162
- tryAcquire(bytes) {
163
- this.validateRequest(bytes);
164
- const shared = this.general.tryAcquire(bytes);
165
- if (shared || !this.isSmall(bytes))
166
- return shared;
167
- return this.small.tryAcquire(bytes);
168
- }
169
- acquire(bytes, signal) {
170
- try {
171
- this.validateRequest(bytes);
172
- }
173
- catch (error) {
174
- return Promise.reject(error);
175
- }
176
- if (this.isSmall(bytes)) {
177
- // Shared capacity while it is free — a small request should get the
178
- // same concurrency as any other when nothing is contending. It never
179
- // joins the shared queue, so it cannot be parked behind a large owner.
180
- const shared = this.general.tryAcquire(bytes);
181
- if (shared)
182
- return Promise.resolve(shared);
183
- return this.small.acquire(bytes, signal);
184
- }
185
- return this.general.acquire(bytes, signal);
186
- }
187
- validateRequest(bytes) {
188
- if (!Number.isSafeInteger(bytes) || bytes <= 0 || bytes > this.capacity) {
189
- throw new RangeError(`weighted credit request must be a positive safe integer no larger than ${this.capacity}: ${bytes}`);
190
- }
191
- }
192
- }
193
- function abortError(signal) {
194
- const reason = signal.reason;
195
- return new DOMException(reason instanceof Error ? reason.message : String(reason ?? 'The operation was aborted'), 'AbortError');
196
- }
@@ -1,236 +0,0 @@
1
- /**
2
- * diag-counters.ts — application-level memory + phase observability.
3
- *
4
- * Why: workerd's `process.memoryUsage()` returns 0 for all fields inside
5
- * a Durable Object class context (only dynamic-worker isolates under
6
- * nodejs_compat get the real implementation). Without a working heap
7
- * probe we have no way to confirm OOM hypotheses or verify a fix.
8
- *
9
- * Replacement: deterministic counters bumped at known allocation sites.
10
- * Cumulative bytes decoded, in-flight stub counts, and phase markers
11
- * give us the same operational signal as a heap probe — and they're
12
- * exact, not estimated.
13
- *
14
- * Singleton-per-isolate. Lives at module scope so any code path in the
15
- * supervisor bundle can write to it (installer and RPC handlers) and
16
- * the request handler in nimbus-session.ts:/api/_diag/memory can read
17
- * it. Survives across requests within the same isolate; resets on DO
18
- * reboot — itself a useful signal (counters at 0 immediately after the
19
- * banner reprinted = the killed isolate took its state with it).
20
- */
21
- /**
22
- * Phase tags surfaced via /api/_diag/memory. Strings are ASCII so
23
- * humans can grep for them in logs.
24
- *
25
- * installPhase tracks the high-level npm-install state machine:
26
- * idle → resolve → hoist → diff → fetch → write → link-bins → bundle → done
27
- *
28
- */
29
- import type { InstallPhase } from '../_shared/install-phase.js';
30
- export interface DiagCounters {
31
- /** Top-level install phase. */
32
- installPhase: InstallPhase;
33
- /**
34
- * Sum of payload bytes claimed by RPCs currently in flight on the
35
- * SUPERVISOR boundary [Phase 2 A'.2].
36
- *
37
- * Bumped at RPC entry by `rpcPayloadStart(bytes)` in the DO-side
38
- * byte-returning handlers in src/session/rpc.ts; debited at exit by
39
- * `rpcPayloadEnd(bytes)`. Goes back to zero after every RPC settles.
40
- *
41
- * The C'.1 heap estimator surfaces this as
42
- * `breakdown.streamingBuffersBytes` so any RPC path that buffers
43
- * MORE than the W7 streaming guarantee shows up as supervisor heap
44
- * pressure rather than disappearing into the bundle baseline.
45
- *
46
- * Streamed payloads (writeBatchStream over W7 frames) report -1
47
- * up-front; we substitute 0 here because the bytes flow with
48
- * backpressure and the supervisor-resident buffer is bounded by
49
- * the W7 chunk size (a few KiB), not by the total payload.
50
- */
51
- inFlightRpcPayloadBytes: number;
52
- /**
53
- * Bytes reserved by prefetch-bundle builds currently in flight.
54
- *
55
- * `buildPrefetchBundle` accumulates raw VFS file contents into an in-heap
56
- * bundle object, and used to do so with nothing observing it: the estimator
57
- * read 9.4 MiB while those bytes were resetting the DO. Each build now takes
58
- * an `acquireSupervisorAllocation` lease for the budget it may use and bumps
59
- * this alongside it, so the reservation is ATTRIBUTED to the bundle path
60
- * rather than landing in `unattributedReservationBytes`.
61
- *
62
- * Surfaced as `breakdown.prefetchBundleBytes`. Back to zero between builds.
63
- */
64
- prefetchBundleBytes: number;
65
- /**
66
- * Bytes retained by the FacetManager's prefetch-bundle LRU right now.
67
- *
68
- * Unlike the counter above these bytes persist ACROSS execs — each entry
69
- * holds the raw bundle plus its serialized source, manifest and metadata.
70
- * The LRU used to be bounded by entry count alone, which bounded nothing:
71
- * 16 pi-sized entries exceed the supervisor ceiling several times over. It
72
- * is now bounded by PREFETCH_CACHE_MAX_BYTES and reports its live total
73
- * here, so the retained cost is a measurement rather than a cap.
74
- *
75
- * Surfaced as `breakdown.prefetchCacheBytes`. A gauge, not a delta.
76
- */
77
- prefetchCacheBytes: number;
78
- /** Install-facet counters. Populated by npm-installer after a
79
- * successful batch-facet dispatch returns. Confirms the install ran
80
- * in the facet (tarballsCompleted > 0) and surfaces the
81
- * facet-internal byte count. */
82
- installFacet: {
83
- /** Number of tarballs the install-batch-facet successfully streamed. */
84
- tarballsCompleted: number;
85
- /** Cumulative tarball body bytes the facet decoded (gunzip input). */
86
- cumulativeBytesDecoded: number;
87
- /** Peak in-flight tarball pipelines inside the facet at any one moment. */
88
- peakInFlight: number;
89
- };
90
- /** Pre-bundle facet counters. Tracks the fire-and-forget pre-bundle
91
- * phase. Aggregates across all dispatches in this DO's lifetime. */
92
- preBundleFacet: {
93
- /** Specifiers attempted (queue depth at start of phase). */
94
- attempted: number;
95
- /** Bundles that completed successfully (esmCode produced). */
96
- bundlesCompleted: number;
97
- /** Bundles that failed (errorText set on PrebundleResult). */
98
- errors: number;
99
- /** Bundles skipped before facet dispatch (e.g. slice cap exceeded). */
100
- skipped: number;
101
- /** First-call wasm-fetch payload size. 0 until first successful dispatch
102
- * records it; stays at first-seen value (RPC returns the same Module
103
- * every time, but the cumulativeBytes the FACET reports may grow on
104
- * retries). */
105
- wasmBootBytes: number;
106
- /** Per-module errors from the MOST RECENT pre-bundle batch, keyed by
107
- * specifier (e.g. "lucide-react", "framer-motion"). REPLACED on each
108
- * recordPreBundleSummary() call so the map is bounded by the batch
109
- * size (≤ pending.length, typically <20).
110
- *
111
- * Example: { "lucide-react": "Worker exceeded memory limit." }
112
- *
113
- * Empty when the most recent batch had zero errors. */
114
- errorsByModule: Record<string, string>;
115
- };
116
- /** Pipelined R2 race outcomes. All counts are cumulative since
117
- * DO-isolate start. Per-tier cache statistics live in cache-stats. */
118
- r2: {
119
- /** Pipelined-RPC race wins for tarballs (R2 came back first; network
120
- * was cancelled). */
121
- pipelinedTarballRaceWins: number;
122
- /** Pipelined-RPC race losses for tarballs (R2 came back too slow or
123
- * empty; network response used). */
124
- pipelinedTarballRaceLosses: number;
125
- /** Pipelined-RPC race wins for packuments. */
126
- pipelinedPackumentRaceWins: number;
127
- /** Pipelined-RPC race losses for packuments. */
128
- pipelinedPackumentRaceLosses: number;
129
- };
130
- }
131
- /** Read a snapshot — caller-side mutations don't affect the singleton. */
132
- export declare function readDiagCounters(): DiagCounters;
133
- /** Set the install phase. */
134
- export declare function setInstallPhase(p: InstallPhase): void;
135
- /**
136
- * Track an in-flight supervisor RPC payload [Phase 2 A'.2].
137
- *
138
- * Call at RPC entry, BEFORE awaiting any work that depends on
139
- * `payload`. Pair with `rpcPayloadEnd(bytes)` in the matching `finally`
140
- * so the counter goes back to zero on both success and failure.
141
- *
142
- * `bytes` is the supervisor-resident byte cost of the RPC's argument
143
- * (or return value, whichever is bigger). For structured-clone RPCs
144
- * this is the size of the cloned payload in bytes.
145
- *
146
- * Streamed payloads (ReadableStream-over-RPC) flow with backpressure
147
- * and the supervisor-resident bound is the chunk size, not the total
148
- * payload. Pass the chunk-size estimate (typically ≤ 1 MiB) — never
149
- * the unknown total. -1 is silently coerced to 0 to keep the counter
150
- * non-negative; callers that don't know the size should call this
151
- * with 0 explicitly rather than relying on coercion.
152
- */
153
- export declare function rpcPayloadStart(bytes: number): void;
154
- /**
155
- * Release an in-flight supervisor RPC payload [Phase 2 A'.2].
156
- * Pass the same byte count given to the matching `rpcPayloadStart`.
157
- *
158
- * Floors at 0 to absorb arithmetic drift (e.g. if a payload-byte
159
- * counter rounding gave a slightly different number on entry vs.
160
- * exit). Drift in routine paths should be zero — a non-zero floor
161
- * hit is a bug worth investigating.
162
- */
163
- export declare function rpcPayloadEnd(bytes: number): void;
164
- /**
165
- * Track an in-flight prefetch-bundle build. Call with the byte reservation the
166
- * build took from the supervisor allocation budget, and pair with
167
- * `prefetchBundleEnd` in the matching `finally` so it returns to zero whether
168
- * the build succeeded or threw.
169
- */
170
- export declare function prefetchBundleStart(bytes: number): void;
171
- /** Release an in-flight prefetch-bundle reservation. Floors at 0. */
172
- export declare function prefetchBundleEnd(bytes: number): void;
173
- /**
174
- * Publish the prefetch-bundle LRU's live retained total. A gauge: the cache
175
- * owns the number and reports it whenever it admits or evicts an entry.
176
- */
177
- export declare function setPrefetchCacheBytes(bytes: number): void;
178
- /** Fold facet-returned counters into the supervisor's diag state.
179
- * Called by npm-installer after the batch-facet returns; aggregates
180
- * rather than replaces so multiple install runs in the same DO
181
- * lifetime accumulate in cumulativeBytesDecoded. */
182
- export declare function recordInstallFacetCounters(c: {
183
- tarballsCompleted: number;
184
- cumulativeBytesDecoded: number;
185
- peakInFlight: number;
186
- }): void;
187
- /** Record pre-bundle phase summary. Aggregates lifetime totals across
188
- * all phases run in this DO's lifetime, but REPLACES the
189
- * errorsByModule map every call so it reflects only the most recent
190
- * batch. Losing prior-batch errors is fine — they're already aggregated
191
- * into `errors` (count); the map is for "which modules failed this
192
- * time." */
193
- export declare function recordPreBundleSummary(s: {
194
- attempted: number;
195
- bundlesCompleted: number;
196
- errors: number;
197
- skipped: number;
198
- wasmBootBytes?: number;
199
- errorsByModule?: Record<string, string>;
200
- }): void;
201
- /** Bump pipelined-RPC race outcome counters. The facet returns these
202
- * in its result counters; the supervisor folds them in alongside the
203
- * existing installFacet counters. */
204
- export declare function recordR2RaceCounters(c: {
205
- pipelinedTarballRaceWins: number;
206
- pipelinedTarballRaceLosses: number;
207
- pipelinedPackumentRaceWins: number;
208
- pipelinedPackumentRaceLosses: number;
209
- }): void;
210
- /**
211
- * cache-obs-2: fold facet-collected per-tier cache events into the
212
- * DO-side cache-stats singleton. Called from installer.ts after a
213
- * batch-facet / resolve-facet returns — mirrors recordR2RaceCounters
214
- * (the facet collects metrics in its result and the supervisor folds
215
- * them into the DO isolate).
216
- *
217
- * Each event has shape:
218
- * { kind: 'hit', tier: 'L2'|'L3'|'L4', cacheKind: 'tarball'|'packument'|'asset', bytes: number }
219
- * { kind: 'miss', tier: ..., cacheKind: ... }
220
- *
221
- * The recordHit/recordMiss surface is defined in
222
- * src/_shared/cache-stats.ts.
223
- */
224
- import { type CacheTier, type CacheKind } from '../_shared/cache-stats.js';
225
- export type CacheStatEvent = {
226
- kind: 'hit';
227
- tier: CacheTier;
228
- cacheKind: CacheKind;
229
- bytes: number;
230
- } | {
231
- kind: 'miss';
232
- tier: CacheTier;
233
- cacheKind: CacheKind;
234
- };
235
- export declare function recordCacheStatEvents(events: readonly CacheStatEvent[] | undefined): void;
236
- //# sourceMappingURL=diag-counters.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"diag-counters.d.ts","sourceRoot":"","sources":["../../src/observability/diag-counters.ts"],"names":[],"mappings":"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"}