feat(vm): add resource diagnostics and macOS stability qualification
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-10-14 08:26:07 +01:00
parent 6c2a07e579
commit 3899b7f12c
21 changed files with 1502 additions and 33 deletions
@@ -0,0 +1,102 @@
---
id: LSN-0068
ticket: vm-resource-limits-handle-safety-and-long-run-stability
title: Resource Stability Needs Phase-Aware Evidence
created: 2026-10-14
tags: [vm, memory, gc, testing, ownership]
---
## Context
DEC-0056 and PLN-0187 delivered an audit of the existing VM resource contracts,
opt-in engineering diagnostics and reproducible macOS/arm64 workloads. The user
explicitly revised the closure criterion on 2026-10-14: accept the executed
functional, stationary and host evidence plus the observed extended run, waive
eight-hour completion for this delivery, and leave further testing to future
qualification. The discussion is closed; the interrupted timed run did not pass
an eight-hour endurance test. This lesson preserves the decision and its revision
after workflow cleanup; the [discussion index](../../index.ndjson) tracks closure.
Normative references remain [memory and GC](../../../docs/specs/runtime/03-memory-stack-heap-and-allocation.md),
[Registry/PBX](../../../docs/specs/runtime/02c-program-registry-and-pbx-v1.md),
[typed callables](../../../docs/specs/runtime/02b-vm-function-values-and-closures.md)
and [single-context lifecycle](../../../docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md).
The [published evidence report](../../../docs/vm-arch/resource-stability-qualification.md)
and its compact data record contain the enforcement matrix, commands, counters,
source-log hashes, environmental details and limitations. This lesson introduces
no new quotas, GC policy, instruction costs or runtime guarantees.
## Key Decisions
### Observe the existing collector before redesigning it
The implementation kept threshold-based collection at the published safepoints.
Fixed-size budget counters and logarithmic GC histograms expose behavior through
an opt-in Rust feature without expanding the guest ABI or retaining guest roots.
The audit did not reproduce a pre-existing VM contract violation requiring a
collector redesign. One newly added diagnostic needed before-step sampling to
count an entry whose first instruction immediately returns; its regression
distinguishes an observation defect from a change to execution semantics.
### Acceptance and run outcome are separate facts
Three stationary families each completed 216,000 frames and identical-input
replay with final session reservations zero. Functional suites, 1,000 headless
reset/reload cycles, desktop lifecycle tests and real-window controls also
passed. The longer release run reached a common checkpoint of 36,420,000 frames
per family/replay, with stable resource envelopes and no recorded replay failure.
External RSS ranged from 3,296 to 3,408 KiB over 369 samples.
That process exited with code 101 after approximately 3h22 elapsed when writing
stdout failed because the host disk was full. It never emitted completed active
duration, final replay/disposal or qualification-pass markers. The log occupied
about 5.7 MiB; its size alone did not explain exhaustion of the host volume.
The explicit scope revision accepted the available evidence, not an invented
successful run. Final disposal evidence comes from the normally completed
stationary and ownership/reset tests. Additional endurance, representative-game
headroom and unavailable-platform qualification remain unexecuted.
## Patterns and Algorithms
Compare memory at equivalent workload phases. A closure reachable during sync
collection can become unreachable at RET without enough subsequent allocation
to trigger another sweep. The observed stable 332-byte closure is expected
under the current policy; forcing collection to make every checkpoint zero
would test a different policy. Final owner disposal supplies a separate oracle.
Distinguish live guest objects, reserved capacities, retired/free handle slots,
native string owners and process RSS. Capacity can remain charged after objects
die, and a native string snapshot can legitimately retain its accounting domain
after VM disposal. A cloned budget observer retains accounting but no guest
owners, allowing the tests to assert zero only after the actual final owner dies.
Use independent sessions with identical input for lockstep replay. Compare logical
output, cycles and resource envelopes, while recording host timing separately.
Every frame has a finite slice guard; no-sync loops have a finite slice count
instead of an unreachable completed-frame target. Time-bounded runs must record
their actual logical progress rather than assuming identical frame counts across
equal wall durations or platforms.
## Pitfalls
- A no-op VM smoke cannot establish GC reachability. The replacement layer test
allocates 1,031 closures and checks that only the active environment survives.
- A fixed short sleep is not evidence of desktop responsiveness. Bounded polling
of logical progress removed the initial harness timing assumption.
- Reserved-capacity refusal counters can include speculative growth followed by
successful exact-capacity fallback; they are not guest trap counts.
- Histogram quantiles are bucket upper bounds, capped by the observed maximum.
Host timing includes scheduling effects and does not establish real-time safety.
- A stationary synthetic workload repeatedly exercises a bounded state space.
More elapsed time does not automatically supply more scenario coverage.
- An interrupted process supplies useful checkpoints but cannot prove execution
of its final assertions. An explicit acceptance revision must preserve that gap.
## Takeaways
Resource safety combines admission enforcement, ownership tests and integrated
observations; elapsed time alone cannot replace any of them. Preserve failures
and attribution, make acceptance changes explicit, and keep future qualification
separate from delivered evidence. The long-run example is manually invoked;
the repository pipelines run bounded automated tests and do not request the
eight-hour workload. Audio remains open and no audio behavior was qualified here.