mustflow 2.117.0 → 2.118.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -0
- package/dist/cli/commands/run/args.js +5 -0
- package/dist/cli/commands/run/execution.js +7 -6
- package/dist/cli/commands/run/preview.js +6 -5
- package/dist/cli/commands/run/receipt.js +1 -0
- package/dist/cli/commands/run.js +2 -1
- package/dist/cli/commands/workspace.js +216 -81
- package/dist/cli/i18n/en.js +1 -0
- package/dist/cli/i18n/es.js +1 -0
- package/dist/cli/i18n/fr.js +1 -0
- package/dist/cli/i18n/hi.js +1 -0
- package/dist/cli/i18n/ko.js +1 -0
- package/dist/cli/i18n/zh.js +1 -0
- package/dist/cli/lib/manifest-lock.js +10 -1
- package/dist/cli/lib/repo-map.js +5 -0
- package/dist/cli/lib/run-context.js +136 -0
- package/dist/cli/lib/run-root-trust.js +22 -15
- package/dist/cli/lib/validation/index.js +8 -0
- package/dist/core/config-loading.js +107 -14
- package/dist/core/run-receipt.js +1 -0
- package/dist/core/workspace-command-authority.js +98 -0
- package/package.json +1 -1
- package/schemas/run-receipt.schema.json +10 -0
- package/schemas/workspace-command-catalog.schema.json +3 -0
- package/schemas/workspace-command-fragments.schema.json +2 -0
- package/schemas/workspace-status.schema.json +4 -1
- package/schemas/workspace-verification-plan.schema.json +3 -0
- package/templates/default/common/.mustflow/config/mustflow.toml +2 -0
- package/templates/default/i18n.toml +14 -2
- package/templates/default/locales/en/.mustflow/skills/INDEX.md +12 -3
- package/templates/default/locales/en/.mustflow/skills/ai-game-asset-production/SKILL.md +209 -0
- package/templates/default/locales/en/.mustflow/skills/ai-game-asset-production/references/asset-contract-validation.md +106 -0
- package/templates/default/locales/en/.mustflow/skills/ai-game-asset-production/references/raster-alpha-atlas-checklist.md +109 -0
- package/templates/default/locales/en/.mustflow/skills/ai-game-asset-production/references/tile-animation-checklist.md +98 -0
- package/templates/default/locales/en/.mustflow/skills/connection-lifecycle-integrity-review/SKILL.md +302 -0
- package/templates/default/locales/en/.mustflow/skills/connection-lifecycle-integrity-review/references/connection-fault-injection-resource-lifetime-validation.md +277 -0
- package/templates/default/locales/en/.mustflow/skills/connection-lifecycle-integrity-review/references/node-stream-transport-lifecycle-checklist.md +381 -0
- package/templates/default/locales/en/.mustflow/skills/memory-lifetime-review/SKILL.md +94 -2
- package/templates/default/locales/en/.mustflow/skills/memory-lifetime-review/references/cross-runtime-memory-stream-reproduction-harness.md +289 -0
- package/templates/default/locales/en/.mustflow/skills/memory-lifetime-review/references/node-memory-resource-backpressure-diagnostics.md +369 -0
- package/templates/default/locales/en/.mustflow/skills/routes.toml +23 -0
- package/templates/default/manifest.toml +17 -1
|
@@ -0,0 +1,369 @@
|
|
|
1
|
+
# Node Memory, Resource, and Backpressure Diagnostics
|
|
2
|
+
|
|
3
|
+
Use this reference when a Node.js process shows growing RSS, heap, external memory, buffers,
|
|
4
|
+
descriptors, sockets, native handles, cache residency, or streaming queues, especially when slow
|
|
5
|
+
consumers, retries, clones, transforms, HTTP/2, or HTTP/3 can blur ownership.
|
|
6
|
+
|
|
7
|
+
Do not force one exclusive root-cause label onto evidence that describes different dimensions. A
|
|
8
|
+
single incident can combine unbounded buffering, external-memory growth, allocator fragmentation,
|
|
9
|
+
and a missed transport close.
|
|
10
|
+
|
|
11
|
+
## Contents
|
|
12
|
+
|
|
13
|
+
1. [Classify three independent axes](#1-classify-three-independent-axes)
|
|
14
|
+
2. [Build one synchronized measurement ledger](#2-build-one-synchronized-measurement-ledger)
|
|
15
|
+
3. [Control the reproduction and compare floors](#3-control-the-reproduction-and-compare-floors)
|
|
16
|
+
4. [Distinguish common growth classes](#4-distinguish-common-growth-classes)
|
|
17
|
+
5. [Model request ownership as a DAG](#5-model-request-ownership-as-a-dag)
|
|
18
|
+
6. [Enforce terminal resource invariants](#6-enforce-terminal-resource-invariants)
|
|
19
|
+
7. [Trace backpressure from the final sink](#7-trace-backpressure-from-the-final-sink)
|
|
20
|
+
8. [Check each pipeline boundary](#8-check-each-pipeline-boundary)
|
|
21
|
+
9. [Run stop, plateau, and resume experiments](#9-run-stop-plateau-and-resume-experiments)
|
|
22
|
+
10. [Calculate the memory envelope](#10-calculate-the-memory-envelope)
|
|
23
|
+
11. [Infer the broken boundary](#11-infer-the-broken-boundary)
|
|
24
|
+
12. [Diagnostic acceptance gate](#12-diagnostic-acceptance-gate)
|
|
25
|
+
13. [Primary references](#13-primary-references)
|
|
26
|
+
|
|
27
|
+
## 1. Classify three independent axes
|
|
28
|
+
|
|
29
|
+
Classify every observation on all three axes:
|
|
30
|
+
|
|
31
|
+
| Axis | Question |
|
|
32
|
+
| --- | --- |
|
|
33
|
+
| Storage location | Are the bytes in the V8 heap, ArrayBuffer or Buffer backing stores, other native allocations, memory mappings, allocator residency, or kernel buffers? |
|
|
34
|
+
| Retention cause | Does a request, pending task, stream queue, cache, pool, native operation, retry, branch, or telemetry queue still own the bytes? |
|
|
35
|
+
| Terminal status | Is the owner still performing valid work, stuck in unbounded backlog, terminal but retained, or released while RSS remains resident? |
|
|
36
|
+
|
|
37
|
+
Call growth a leak only when the expected terminal condition has occurred, an owner or native
|
|
38
|
+
allocation remains live, and retained count or bytes grow with completed lifecycle repetitions under
|
|
39
|
+
comparable load. A queue that drains completely after a live request is not a strict leak, but an
|
|
40
|
+
unbounded queue is still an OOM defect and must not be reported as safe.
|
|
41
|
+
|
|
42
|
+
One common mixed sequence is:
|
|
43
|
+
|
|
44
|
+
```text
|
|
45
|
+
slow consumer
|
|
46
|
+
-> ignored writable backpressure
|
|
47
|
+
-> unbounded Buffer queue
|
|
48
|
+
-> external and array-buffer growth
|
|
49
|
+
-> queue release
|
|
50
|
+
-> allocator pages remain resident
|
|
51
|
+
-> external falls while RSS stays high
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Do not infer native memory as `rss - heapTotal - external`. The measurements use different
|
|
55
|
+
inclusion, reservation, and residency semantics. In Node, `arrayBuffers` is part of `external`, not
|
|
56
|
+
an independent addend.
|
|
57
|
+
|
|
58
|
+
## 2. Build one synchronized measurement ledger
|
|
59
|
+
|
|
60
|
+
Collect comparable samples from the same process and clock domain:
|
|
61
|
+
|
|
62
|
+
| Layer | Required evidence | Useful expansion |
|
|
63
|
+
| --- | --- | --- |
|
|
64
|
+
| V8 heap | `heapUsed`, `heapTotal`, post-major-GC floor | old space, large-object space, native and detached contexts, global handles |
|
|
65
|
+
| External memory | `external`, `arrayBuffers` | Buffer count, backing-store bytes, parser, codec, crypto, and TLS buffers |
|
|
66
|
+
| Process memory | RSS plus private or committed memory | anonymous, file-backed, shared mappings, PSS, thread stacks, code pages |
|
|
67
|
+
| Resources | descriptor, socket, or Windows handle counts by type | socket state, pool busy/idle/queued, TLS session cache, active resource categories |
|
|
68
|
+
| Application | started, completed, aborted, failed, retried, in-flight | logical request, attempt, branch, and owner counts |
|
|
69
|
+
| Data flow | admitted, accepted, committed, released, cancelled, and discarded bytes per edge | peak queue bytes, chunk size, transform expansion, sink durability boundary |
|
|
70
|
+
| Protocol | TCP queues, HTTP/2 windows and outbound queue, QUIC credit | reset, window update, blocked-frame, cancel, and session or stream counts |
|
|
71
|
+
|
|
72
|
+
Use V8 heap-space statistics to distinguish live-space growth from reserved capacity. A growing
|
|
73
|
+
native or detached context count is a retention lead, not a complete diagnosis.
|
|
74
|
+
|
|
75
|
+
On Linux, mapping summaries can separate anonymous, file-backed, and shared residency. On Windows,
|
|
76
|
+
pair Working Set with Private Bytes or Commit and handle counts by type. Treat mapping inspection,
|
|
77
|
+
native heap profilers, heap snapshots, packet capture, and platform handle tools as configured or
|
|
78
|
+
manual-only diagnostics; this reference does not authorize raw commands.
|
|
79
|
+
|
|
80
|
+
`process.getActiveResourcesInfo()` reports resource types keeping the event loop alive. It is not an
|
|
81
|
+
enumeration of every reference, descriptor, allocation, or leak. Pair it with ownership and
|
|
82
|
+
platform evidence.
|
|
83
|
+
|
|
84
|
+
## 3. Control the reproduction and compare floors
|
|
85
|
+
|
|
86
|
+
Fix more than request rate. Record concurrency, body and chunk sizes, compression, protocol,
|
|
87
|
+
retries, cache state, branch count, consumer rate, origin cardinality, runtime build, and allocator.
|
|
88
|
+
|
|
89
|
+
Run phases in this order:
|
|
90
|
+
|
|
91
|
+
1. idle baseline;
|
|
92
|
+
2. bounded warmup with fixed origins, keys, and connections;
|
|
93
|
+
3. normal consumer faster than producer;
|
|
94
|
+
4. slow consumer below producer rate;
|
|
95
|
+
5. fully stopped consumer;
|
|
96
|
+
6. admission stop followed by complete drain;
|
|
97
|
+
7. idle wait beyond pool and keep-alive deadlines; and
|
|
98
|
+
8. optional forced GC only in an isolated staging or canary process.
|
|
99
|
+
|
|
100
|
+
Do not take a production heap snapshot casually. Snapshot generation can block the event loop and
|
|
101
|
+
require substantial extra memory. Use an isolated process or removed-from-traffic instance and
|
|
102
|
+
record the diagnostic impact.
|
|
103
|
+
|
|
104
|
+
Compare floors and slopes rather than one peak:
|
|
105
|
+
|
|
106
|
+
```text
|
|
107
|
+
post_gc_slope
|
|
108
|
+
= change(post-major-GC heapUsed) / change(completed lifecycles)
|
|
109
|
+
|
|
110
|
+
post_quiescent_slope
|
|
111
|
+
= change(resource amount after admission stop, drain, and idle expiry)
|
|
112
|
+
/ change(completed lifecycles)
|
|
113
|
+
|
|
114
|
+
Q_edge(t)
|
|
115
|
+
= admitted_bytes_edge(t) - released_bytes_edge(t)
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Define release as the moment that edge no longer owns the bytes, not the moment it hands them to
|
|
119
|
+
another queue. Keep compressed, decompressed, transformed, and committed byte domains separate.
|
|
120
|
+
Use a predeclared statistical tolerance rather than demanding literal zero from noisy process
|
|
121
|
+
measurements.
|
|
122
|
+
|
|
123
|
+
## 4. Distinguish common growth classes
|
|
124
|
+
|
|
125
|
+
| Class | Decisive evidence | Common false conclusion |
|
|
126
|
+
| --- | --- | --- |
|
|
127
|
+
| JavaScript heap retention | Post-GC and post-quiescent live heap grows with completed work; repeated dominator paths lead to a long-lived map, cache, listener, promise continuation, closure, or context | Treating `heapTotal`, warmup, or a bounded cache as live-object growth |
|
|
128
|
+
| Native leak | JavaScript heap, external memory, queues, and handles are stable while still-live native allocation stacks grow | Calling JIT code, mappings, thread stacks, pools, or fragmentation a native leak |
|
|
129
|
+
| External buffer retention | Small wrappers or views retain large backing stores and `arrayBuffers` moves with owned queue bytes | Treating all `external` as Buffer memory or continuing to call it a Buffer leak after external falls |
|
|
130
|
+
| Unbounded buffering | Growth appears under a slow or stopped consumer near producer-minus-consumer rate and drains after consumption resumes | Calling it safe because it eventually drains, or calling it a terminal leak before the request ends |
|
|
131
|
+
| Descriptor, socket, or handle leak | After admission stop, terminal settlement, and pool idle expiry, owned resources fail to return to baseline, often one per abort or error | Counting a bounded warm pool or kernel `TIME_WAIT` as a process-owned leak |
|
|
132
|
+
| Cache growth | A named cache root owns the bytes and growth follows key, origin, tenant, or SNI cardinality; eviction or flush releases them | Assuming TTL alone is a byte bound or limiting entries while values remain unbounded |
|
|
133
|
+
| Allocator fragmentation or residency | Live heap, external memory, queues, and live native allocations stabilize or fall while allocator active-to-resident gap remains high | Declaring fragmentation merely because RSS did not fall immediately after release |
|
|
134
|
+
|
|
135
|
+
Persistent `CLOSE_WAIT` plus an owned descriptor is a stronger local-close signal than `TIME_WAIT`.
|
|
136
|
+
Confirm the owning process and lifecycle before assigning cause.
|
|
137
|
+
|
|
138
|
+
## 5. Model request ownership as a DAG
|
|
139
|
+
|
|
140
|
+
A strict tree is wrong when pools and multiplexed sessions are shared, retries or hedges create
|
|
141
|
+
multiple attempts, and `clone()` or `tee()` creates multiple body branches.
|
|
142
|
+
|
|
143
|
+
```text
|
|
144
|
+
process
|
|
145
|
+
-> process caches and telemetry queues
|
|
146
|
+
-> pool
|
|
147
|
+
-> connection or session
|
|
148
|
+
-> protocol stream leased by request attempt
|
|
149
|
+
-> logical request
|
|
150
|
+
-> root cancellation and context
|
|
151
|
+
-> attempt 1
|
|
152
|
+
-> attempt 2 or hedge
|
|
153
|
+
-> output branch A
|
|
154
|
+
-> output branch B
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Track at least:
|
|
158
|
+
|
|
159
|
+
```text
|
|
160
|
+
resource_id
|
|
161
|
+
resource_type
|
|
162
|
+
scope: process | pool | connection | request | attempt | branch | stream
|
|
163
|
+
owner_id
|
|
164
|
+
parent_id
|
|
165
|
+
leased_by_request_ids
|
|
166
|
+
created_at
|
|
167
|
+
created_stack_hash
|
|
168
|
+
state: CREATED | ACTIVE | CLOSING | CLOSED | FAILED
|
|
169
|
+
current_bytes
|
|
170
|
+
close_action
|
|
171
|
+
terminal_reason
|
|
172
|
+
closed_at
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Separate logical request, attempt, branch, protocol stream, shared connection, and process cache
|
|
176
|
+
ownership. A request normally returns a lease instead of closing a healthy shared connection.
|
|
177
|
+
Cancelling one HTTP/2 or HTTP/3 request normally resets its stream, not the whole session or
|
|
178
|
+
connection.
|
|
179
|
+
|
|
180
|
+
Track terminal reasons such as success, client abort, deadline, DNS, connect, TLS, upstream
|
|
181
|
+
headers, upstream body, transform, downstream, retry-superseded, and shutdown. Do not let the
|
|
182
|
+
success path be the only path with balanced counters.
|
|
183
|
+
|
|
184
|
+
## 6. Enforce terminal resource invariants
|
|
185
|
+
|
|
186
|
+
For every supported terminal reason, require the applicable invariants:
|
|
187
|
+
|
|
188
|
+
| Scope | Terminal invariant |
|
|
189
|
+
| --- | --- |
|
|
190
|
+
| Request | Registry, async context, listeners, timers, and request references from cancellation state are zero |
|
|
191
|
+
| Attempt | Fetch or provider task, retry or hedge task, body, parser, and timeout are terminal |
|
|
192
|
+
| Branch | Every clone or tee branch is consumed, cancelled, or errored |
|
|
193
|
+
| Stream | Reader and writer locks are released, pipe tasks settle, and both transform sides reach a terminal state |
|
|
194
|
+
| File | File handle, stream, temporary file, and quota reservation are released |
|
|
195
|
+
| Protocol | HTTP/1 exchange or HTTP/2/3 request stream is terminal |
|
|
196
|
+
| Shared resource | Request lease and reference count decrement exactly once; a healthy shared socket or session need not close |
|
|
197
|
+
| Memory | Request-owned queue bytes reach zero; shared pools and caches remain within declared byte and cardinality limits |
|
|
198
|
+
| Observation | Terminal reason records once and close actions are idempotent |
|
|
199
|
+
|
|
200
|
+
A useful cleanup order is: atomically select terminal state, abort the root scope, stop producers and
|
|
201
|
+
retries, cancel or abort sources and sinks, await task settlement, release locks, remove timers and
|
|
202
|
+
listeners, close files, return shared leases, and remove the registry entry. A finalizer or GC hook
|
|
203
|
+
is a safety net, not the normal protocol.
|
|
204
|
+
|
|
205
|
+
Promises require separate treatment from their work. A settled promise does not prove the socket,
|
|
206
|
+
file, fetch, codec, or native operation ended. A pending promise is not automatically a leak unless
|
|
207
|
+
a longer-lived owner retains it or its underlying operation past the intended boundary.
|
|
208
|
+
|
|
209
|
+
## 7. Trace backpressure from the final sink
|
|
210
|
+
|
|
211
|
+
Backpressure is a chain of local capacity translations, not one signal travelling unchanged through
|
|
212
|
+
the stack:
|
|
213
|
+
|
|
214
|
+
```text
|
|
215
|
+
final sink capacity falls
|
|
216
|
+
-> Web writer readiness blocks or Node write returns false
|
|
217
|
+
-> transform readable queue fills
|
|
218
|
+
-> transform writable pressure rises
|
|
219
|
+
-> body pull or read stops
|
|
220
|
+
-> parser and body ingress slow
|
|
221
|
+
-> HTTP/1 socket reading slows
|
|
222
|
+
or HTTP/2 flow-control credit stops increasing
|
|
223
|
+
or QUIC stream and connection credit stops increasing
|
|
224
|
+
-> remote producer rate falls
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
Instrument each request, attempt, and branch with compatible byte domains:
|
|
228
|
+
|
|
229
|
+
```text
|
|
230
|
+
wire_encoded_received
|
|
231
|
+
fetch_ingress_encoded
|
|
232
|
+
body_decoded_enqueued
|
|
233
|
+
body_delivered
|
|
234
|
+
transform_input
|
|
235
|
+
transform_output_enqueued
|
|
236
|
+
sink_accepted
|
|
237
|
+
sink_committed
|
|
238
|
+
sink_released
|
|
239
|
+
cancelled_bytes
|
|
240
|
+
discarded_bytes
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Keep accepted, committed, and released distinct. A sink that resolves `write()` after copying into
|
|
244
|
+
an internal array has accepted bytes but has not necessarily committed or released them. Compression
|
|
245
|
+
and expansion require separate encoded and decoded ledgers.
|
|
246
|
+
|
|
247
|
+
## 8. Check each pipeline boundary
|
|
248
|
+
|
|
249
|
+
| Boundary | Healthy pressure evidence | Failure pattern |
|
|
250
|
+
| --- | --- | --- |
|
|
251
|
+
| Final writable | Web writer readiness remains pending or Node `write()` returns false until drain; local queue plateaus | Adapter resolves before real capacity, ignores false, or grows a background queue |
|
|
252
|
+
| Transform | Transform invocation and output enqueue stop when readable capacity is exhausted; async transform returns its work promise | Background work or side arrays bypass the stream queues; count-based HWM hides huge chunks |
|
|
253
|
+
| Response body and manual pump | New reads stop when the sink blocks; early exit cancels; every write is awaited | Read loop accumulates promises or chunks, releases only a lock, or leaves a clone branch unread |
|
|
254
|
+
| Fetch or client bridge | Body ingress stops after bounded overshoot when delivery stops | Parser, decoder, or bridge continues consuming into user-space storage |
|
|
255
|
+
| HTTP/1 | Application delivery and socket reads stop after bounded transport and parser overshoot | User-space keeps draining the kernel while application Buffers grow; low kernel Recv-Q is misread as health |
|
|
256
|
+
| HTTP/2 | Stream credit stops increasing while connection control frames and healthy sibling streams still progress | Credit is returned when bytes enter an unbounded application queue, or the entire TCP socket is paused and siblings deadlock |
|
|
257
|
+
| HTTP/3 and QUIC | Stream and connection credit stop increasing; blocked telemetry appears; cancellation closes the narrow stream directions | QUIC returns credit before application consumption or one-direction cancellation leaves reassembly state retained |
|
|
258
|
+
| Transport | TCP receive window or QUIC flow control eventually stalls the sender after bounded in-flight bytes | Continued application reads keep transport open while downstream storage grows |
|
|
259
|
+
|
|
260
|
+
Treat high-water marks as pressure thresholds, not hard byte caps. Use a byte-length queuing strategy
|
|
261
|
+
for byte payloads and include maximum chunk, in-flight operations, protocol windows, and hidden side
|
|
262
|
+
queues in the budget.
|
|
263
|
+
|
|
264
|
+
Do not pause an entire HTTP/2 transport merely to slow one stream. Continue processing connection
|
|
265
|
+
control frames and healthy siblings; express pressure through stream and connection flow-control
|
|
266
|
+
accounting. Verify runtime-specific behavior against the target version and client implementation.
|
|
267
|
+
|
|
268
|
+
## 9. Run stop, plateau, and resume experiments
|
|
269
|
+
|
|
270
|
+
Start with HTTP/1, no compression, no retry or hedge, no cache, no clone or tee, concurrency one,
|
|
271
|
+
fixed incompressible chunks, and an origin faster than the sink. Add one variable at a time only
|
|
272
|
+
after the base experiment passes.
|
|
273
|
+
|
|
274
|
+
During normal consumption, queues should oscillate within a low bounded range. During slow
|
|
275
|
+
consumption, buffers may fill, but upstream rate should converge toward sink rate. During a full
|
|
276
|
+
stop, require the applicable observations after bounded overshoot:
|
|
277
|
+
|
|
278
|
+
- writer readiness blocks or Node write returns false;
|
|
279
|
+
- local writable and transform queues plateau;
|
|
280
|
+
- transform invocations and response reads stop;
|
|
281
|
+
- client body ingress stops;
|
|
282
|
+
- HTTP/2 window updates or QUIC credit increases stop for the affected stream; and
|
|
283
|
+
- remote sender throughput stops after in-flight transport data is exhausted.
|
|
284
|
+
|
|
285
|
+
On resume, require queue drain, writer readiness or drain, transform and body reads, protocol credit,
|
|
286
|
+
and remote sending to resume. A pipeline that stops but never resumes is deadlocked or cancelled,
|
|
287
|
+
not backpressure-correct.
|
|
288
|
+
|
|
289
|
+
Then add, one at a time: concurrency, HTTP/2, HTTP/3, gzip or Brotli expansion, output-expanding
|
|
290
|
+
transforms, retries, hedges, clones, tees, slow and fast branches, downstream abort, upstream reset,
|
|
291
|
+
transform failure, and graceful shutdown.
|
|
292
|
+
|
|
293
|
+
## 10. Calculate the memory envelope
|
|
294
|
+
|
|
295
|
+
Use an explicit envelope such as:
|
|
296
|
+
|
|
297
|
+
```text
|
|
298
|
+
pipeline_memory_bound
|
|
299
|
+
~= concurrency
|
|
300
|
+
* sum(
|
|
301
|
+
queue_high_water_mark_bytes
|
|
302
|
+
+ maximum_chunk_bytes
|
|
303
|
+
+ in_flight_operation_bytes
|
|
304
|
+
+ bounded_side_queue_bytes
|
|
305
|
+
)
|
|
306
|
+
+ protocol_receive_windows
|
|
307
|
+
+ protocol_send_windows
|
|
308
|
+
+ kernel_and_userspace_transport_buffers
|
|
309
|
+
+ clone_branch_multiplier
|
|
310
|
+
+ retry_or_hedge_multiplier
|
|
311
|
+
+ codec_expansion_working_set
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
The equation is a budgeting model, not proof of allocator RSS. Validate each term from current
|
|
315
|
+
implementation and workload evidence. A count HWM of one permits one arbitrarily large chunk; it is
|
|
316
|
+
not a one-byte budget.
|
|
317
|
+
|
|
318
|
+
## 11. Infer the broken boundary
|
|
319
|
+
|
|
320
|
+
| Observation | Likely broken boundary |
|
|
321
|
+
| --- | --- |
|
|
322
|
+
| `sinkCommitted` stops while `sinkAccepted` grows | Sink adapter resolves before durable or capacity-limited commit |
|
|
323
|
+
| `sinkAccepted` stops while transform output grows | Transform ignores readable pressure or uses a side queue |
|
|
324
|
+
| Transform input stops while body delivery grows | Manual pump is not serializing read and write |
|
|
325
|
+
| Body delivery stops while client ingress grows | Parser, decoder, or response bridge is over-reading |
|
|
326
|
+
| Application delivery stops while HTTP/2 DATA and credit continue | Credit is returned at intermediate copy instead of final consumption |
|
|
327
|
+
| Application delivery stops while QUIC credit continues | QUIC integration returns credit before application consumption |
|
|
328
|
+
| Application body stops while socket bytes rise and kernel receive queue stays low | HTTP/1 or client bridge continues draining into user-space buffers |
|
|
329
|
+
| Queues and array buffers fall while RSS remains high | Allocator residency, slabs, pools, or fragmentation, after excluding live native allocation |
|
|
330
|
+
| Bytes stabilize while descriptors or handles rise | Independent lifecycle leak |
|
|
331
|
+
| Descriptors stabilize while live native allocation stacks rise | Native memory leak |
|
|
332
|
+
| Live memory stabilizes while cache bytes rise | Cache policy or cardinality failure |
|
|
333
|
+
| Post-GC heap rises even with normal consumers | JavaScript retention unrelated to backpressure |
|
|
334
|
+
|
|
335
|
+
## 12. Diagnostic acceptance gate
|
|
336
|
+
|
|
337
|
+
Call the diagnosis complete only to the evidence level actually established:
|
|
338
|
+
|
|
339
|
+
- locate growth in at least one measurable storage class;
|
|
340
|
+
- identify the owner or bounded queue responsible for retaining it;
|
|
341
|
+
- prove request, attempt, branch, stream, file, and protocol terminal invariants for every supported
|
|
342
|
+
success, abort, timeout, retry, error, and shutdown path;
|
|
343
|
+
- show stopped-consumer queues plateau within a precomputed envelope and upstream rate eventually
|
|
344
|
+
stops;
|
|
345
|
+
- show resume restores drain, protocol credit, and upstream progress;
|
|
346
|
+
- show request-owned descriptors and handles return within predeclared tolerance after pool idle
|
|
347
|
+
expiry while shared pools remain within their limits;
|
|
348
|
+
- show post-GC or post-quiescent slopes remain within predeclared statistical tolerance; and
|
|
349
|
+
- distinguish fragmentation only after live heap, external, cache, queue, handle, mapping, and native
|
|
350
|
+
allocation evidence no longer explains resident growth.
|
|
351
|
+
|
|
352
|
+
If snapshots, native profilers, platform handle inspection, packet capture, qlog, or long-running
|
|
353
|
+
load are not configured, report them as manual-only or missing. RSS growth alone is an observation,
|
|
354
|
+
not a completed diagnosis.
|
|
355
|
+
|
|
356
|
+
## 13. Primary references
|
|
357
|
+
|
|
358
|
+
- [Node.js process memory and active resource APIs](https://nodejs.org/api/process.html)
|
|
359
|
+
- [Node.js V8 heap statistics and heap snapshots](https://nodejs.org/api/v8.html)
|
|
360
|
+
- [Node.js Buffer ownership and views](https://nodejs.org/api/buffer.html)
|
|
361
|
+
- [Node.js stream backpressure and high-water marks](https://nodejs.org/api/stream.html)
|
|
362
|
+
- [Node.js HTTP/2 state and flow control](https://nodejs.org/api/http2.html)
|
|
363
|
+
- [WHATWG Streams Standard](https://streams.spec.whatwg.org/)
|
|
364
|
+
- [RFC 9113: HTTP/2](https://www.rfc-editor.org/rfc/rfc9113.html)
|
|
365
|
+
- [RFC 9000: QUIC](https://www.rfc-editor.org/rfc/rfc9000.html)
|
|
366
|
+
|
|
367
|
+
Use documentation for the target runtime and client version. The current Node documentation and
|
|
368
|
+
standards establish API and protocol semantics; they do not prove a particular library build,
|
|
369
|
+
allocator, kernel, proxy, or application implements the lifecycle correctly.
|
|
@@ -663,6 +663,23 @@ route_type = "adjunct"
|
|
|
663
663
|
priority = 73
|
|
664
664
|
applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "performance_change", "ui_change", "security_change", "privacy_change", "data_change"]
|
|
665
665
|
|
|
666
|
+
[routes."memory-lifetime-review".contexts]
|
|
667
|
+
positive_terms = ["allocator-fragmentation", "arraybuffer", "backing-store", "buffer-retainer", "cache-bytes", "cross-runtime-repro", "detached-context", "external-memory", "fixed-observer", "handle-leak", "heap-snapshot", "memory-leak", "native-memory", "post-gc", "post-quiescent", "private-bytes", "queue-bytes", "resource-dag", "rss-growth", "runtime-bisect", "runtime-comparator", "same-source-repro", "slow-consumer", "stream-backpressure", "stream-leak-repro", "unbounded-buffer", "working-set"]
|
|
668
|
+
negative_terms = ["agent-memory", "bundle-size-only", "cpu-only", "latency-only", "payload-size-only", "persistent-memory", "schema-only"]
|
|
669
|
+
|
|
670
|
+
[routes."connection-lifecycle-integrity-review"]
|
|
671
|
+
category = "general_code"
|
|
672
|
+
route_type = "adjunct"
|
|
673
|
+
priority = 83
|
|
674
|
+
applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "security_change", "privacy_change", "data_change", "docs_change", "package_metadata_change", "release_risk"]
|
|
675
|
+
|
|
676
|
+
[routes."connection-lifecycle-integrity-review".dependencies]
|
|
677
|
+
suggests_adjuncts = ["memory-lifetime-review", "race-condition-review", "performance-measurement-integrity-review"]
|
|
678
|
+
|
|
679
|
+
[routes."connection-lifecycle-integrity-review".contexts]
|
|
680
|
+
positive_terms = ["abort-signal", "active-resources", "backpressure", "body-abandoned", "body-disposition", "body-lease", "close-wait", "connection-finalize", "connection-pool", "destroy", "drain", "end-finish-close", "fault-injection", "fault-peer", "fin", "half-close", "http-keep-alive", "http2-stream", "net-socket", "netem", "open-handle", "parser-boundary", "pending-write", "reader-cancel", "release-lock", "reset-and-destroy", "resource-soak", "rst", "slow-client", "soak-test", "socket-close", "socket-leak", "stream-cancel", "stream-lock", "time-wait", "transport-lifecycle", "undici", "unref"]
|
|
681
|
+
negative_terms = ["business-state-only", "cache-header-only", "compression-only", "database-connection-string", "domain-lifecycle-only", "http-schema-only"]
|
|
682
|
+
|
|
666
683
|
[routes."desktop-memory-footprint-review"]
|
|
667
684
|
category = "general_code"
|
|
668
685
|
route_type = "adjunct"
|
|
@@ -1697,6 +1714,12 @@ route_type = "adjunct"
|
|
|
1697
1714
|
priority = 82
|
|
1698
1715
|
applies_to_reasons = ["ui_change", "performance_change", "behavior_change", "code_change", "web_asset_change", "security_change", "privacy_change"]
|
|
1699
1716
|
|
|
1717
|
+
[routes."ai-game-asset-production"]
|
|
1718
|
+
category = "ui_assets"
|
|
1719
|
+
route_type = "primary"
|
|
1720
|
+
priority = 86
|
|
1721
|
+
applies_to_reasons = ["ui_change", "web_asset_change", "behavior_change", "code_change", "test_change", "docs_change", "product_change", "release_risk"]
|
|
1722
|
+
|
|
1700
1723
|
[routes."client-bundle-pruning-review"]
|
|
1701
1724
|
category = "ui_assets"
|
|
1702
1725
|
route_type = "adjunct"
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
id = "default"
|
|
2
2
|
name = "default"
|
|
3
|
-
version = "2.
|
|
3
|
+
version = "2.118.0"
|
|
4
4
|
description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
|
|
5
5
|
common_root = "common"
|
|
6
6
|
locales_root = "locales"
|
|
@@ -17,6 +17,9 @@ creates = [
|
|
|
17
17
|
".mustflow/skills/http-api-semantics-review/SKILL.md",
|
|
18
18
|
".mustflow/skills/backend-reliability-change/SKILL.md",
|
|
19
19
|
".mustflow/skills/http-delivery-streaming/SKILL.md",
|
|
20
|
+
".mustflow/skills/connection-lifecycle-integrity-review/SKILL.md",
|
|
21
|
+
".mustflow/skills/connection-lifecycle-integrity-review/references/connection-fault-injection-resource-lifetime-validation.md",
|
|
22
|
+
".mustflow/skills/connection-lifecycle-integrity-review/references/node-stream-transport-lifecycle-checklist.md",
|
|
20
23
|
".mustflow/skills/artifact-integrity-check/SKILL.md",
|
|
21
24
|
".mustflow/skills/architecture-deepening-review/SKILL.md",
|
|
22
25
|
".mustflow/skills/service-boundary-architecture/SKILL.md",
|
|
@@ -57,6 +60,8 @@ creates = [
|
|
|
57
60
|
".mustflow/skills/file-upload-security-review/references/file-upload-parser-ssrf-resource-checklist.md",
|
|
58
61
|
".mustflow/skills/error-message-integrity-review/SKILL.md",
|
|
59
62
|
".mustflow/skills/memory-lifetime-review/SKILL.md",
|
|
63
|
+
".mustflow/skills/memory-lifetime-review/references/cross-runtime-memory-stream-reproduction-harness.md",
|
|
64
|
+
".mustflow/skills/memory-lifetime-review/references/node-memory-resource-backpressure-diagnostics.md",
|
|
60
65
|
".mustflow/skills/desktop-memory-footprint-review/SKILL.md",
|
|
61
66
|
".mustflow/skills/hot-path-performance-review/SKILL.md",
|
|
62
67
|
".mustflow/skills/api-request-performance-review/SKILL.md",
|
|
@@ -311,6 +316,10 @@ creates = [
|
|
|
311
316
|
".mustflow/skills/visual-review-artifact/SKILL.md",
|
|
312
317
|
".mustflow/skills/visual-review-artifact/resources.toml",
|
|
313
318
|
".mustflow/skills/visual-review-artifact/assets/review-template.html",
|
|
319
|
+
".mustflow/skills/ai-game-asset-production/SKILL.md",
|
|
320
|
+
".mustflow/skills/ai-game-asset-production/references/asset-contract-validation.md",
|
|
321
|
+
".mustflow/skills/ai-game-asset-production/references/raster-alpha-atlas-checklist.md",
|
|
322
|
+
".mustflow/skills/ai-game-asset-production/references/tile-animation-checklist.md",
|
|
314
323
|
".mustflow/skills/web-asset-optimization/SKILL.md",
|
|
315
324
|
".mustflow/docs/agent-workflow.md",
|
|
316
325
|
".mustflow/config/mustflow.toml",
|
|
@@ -346,6 +355,7 @@ minimal = [
|
|
|
346
355
|
"http-api-semantics-review",
|
|
347
356
|
"backend-reliability-change",
|
|
348
357
|
"http-delivery-streaming",
|
|
358
|
+
"connection-lifecycle-integrity-review",
|
|
349
359
|
"auth-permission-change",
|
|
350
360
|
"security-flow-review",
|
|
351
361
|
"behavior-preserving-refactor",
|
|
@@ -550,6 +560,7 @@ patterns = [
|
|
|
550
560
|
"http-api-semantics-review",
|
|
551
561
|
"backend-reliability-change",
|
|
552
562
|
"http-delivery-streaming",
|
|
563
|
+
"connection-lifecycle-integrity-review",
|
|
553
564
|
"auth-permission-change",
|
|
554
565
|
"security-flow-review",
|
|
555
566
|
"behavior-preserving-refactor",
|
|
@@ -762,6 +773,7 @@ oss = [
|
|
|
762
773
|
"http-api-semantics-review",
|
|
763
774
|
"backend-reliability-change",
|
|
764
775
|
"http-delivery-streaming",
|
|
776
|
+
"connection-lifecycle-integrity-review",
|
|
765
777
|
"artifact-integrity-check",
|
|
766
778
|
"architecture-deepening-review",
|
|
767
779
|
"service-boundary-architecture",
|
|
@@ -998,6 +1010,7 @@ team = [
|
|
|
998
1010
|
"http-api-semantics-review",
|
|
999
1011
|
"backend-reliability-change",
|
|
1000
1012
|
"http-delivery-streaming",
|
|
1013
|
+
"connection-lifecycle-integrity-review",
|
|
1001
1014
|
"auth-permission-change",
|
|
1002
1015
|
"security-flow-review",
|
|
1003
1016
|
"behavior-preserving-refactor",
|
|
@@ -1224,6 +1237,7 @@ product = [
|
|
|
1224
1237
|
"http-api-semantics-review",
|
|
1225
1238
|
"backend-reliability-change",
|
|
1226
1239
|
"http-delivery-streaming",
|
|
1240
|
+
"connection-lifecycle-integrity-review",
|
|
1227
1241
|
"service-boundary-architecture",
|
|
1228
1242
|
"auth-permission-change",
|
|
1229
1243
|
"security-flow-review",
|
|
@@ -1455,6 +1469,7 @@ product = [
|
|
|
1455
1469
|
"vertical-slice-tdd",
|
|
1456
1470
|
"ui-quality-gate",
|
|
1457
1471
|
"visual-review-artifact",
|
|
1472
|
+
"ai-game-asset-production",
|
|
1458
1473
|
"web-asset-optimization",
|
|
1459
1474
|
]
|
|
1460
1475
|
library = [
|
|
@@ -1463,6 +1478,7 @@ library = [
|
|
|
1463
1478
|
"http-api-semantics-review",
|
|
1464
1479
|
"backend-reliability-change",
|
|
1465
1480
|
"http-delivery-streaming",
|
|
1481
|
+
"connection-lifecycle-integrity-review",
|
|
1466
1482
|
"artifact-integrity-check",
|
|
1467
1483
|
"architecture-deepening-review",
|
|
1468
1484
|
"service-boundary-architecture",
|