Record GPU invocation review closure
Advance the framing to Revision 5 and record the reviewed lifecycle, CLI, and
acceptance contracts. Update the durable and volatile handoffs with checkpoint
82355ca and the completed verification matrix.
This commit is contained in:
parent
82355ca529
commit
c0ec8f75c2
|
|
@ -57,17 +57,25 @@ If it does not, stop and repair the remote/fetch configuration.
|
|||
- Portable branch: `githubsucks/gpu-invocation`
|
||||
- Pull request: **#141 OPEN — do not merge without explicit user approval.**
|
||||
- Base: `githubsucks/main` @ `96d0bae`; protocol remains v19.
|
||||
- Implementation checkpoint: `6fd5834` (approved Revision-4 framing is the
|
||||
preceding `821835b`).
|
||||
- State: implementation and all 18 acceptance criteria complete; awaiting user
|
||||
review. Public path is additive `pmacs --gpu [--socket NAME|PATH]`; bare
|
||||
`pmacs [FILE]` remains TUI and `pmacs --gpu FILE` remains rejected.
|
||||
- Verification: strict workspace Clippy; 1,768 default + 1,944 CRDT library
|
||||
tests; root CLI 33; GPU 145 required; GPU invocation acceptance 1 default +
|
||||
9 CRDT; Vterm Stage 3 7; M4 121 with 3 ignored and the requested
|
||||
`basedpyright` skip; formatting and diff check clean. Unified release build
|
||||
passed. Two real Wayland/Vulkan launches attached at protocol v19; the
|
||||
second reused the daemon retained after the first GPU process exited.
|
||||
- Implementation checkpoints: `82355ca` (first implementation-review fixes)
|
||||
atop `6fd5834`; approved framing began at `821835b` and is now Revision 5.
|
||||
- State: all six implementation-review findings are resolved, all 18
|
||||
acceptance criteria complete, and the PR awaits another user review. Public
|
||||
path is additive `pmacs --gpu [--socket NAME|PATH]`; bare `pmacs [FILE]`
|
||||
remains TUI and `pmacs --gpu FILE` remains rejected.
|
||||
- Review fixes: pre-state GPU events are buffered until winit state exists;
|
||||
daemon stderr is detached; spawned-child ownership is handed off without a
|
||||
leak window; direct CLI guidance, help operands, and sibling-file discovery
|
||||
are strict; transient retry, timeout reporting, hermetic socket paths, and
|
||||
deterministic concurrent-loser reaping have behavioral coverage.
|
||||
- Verification: strict workspace and CRDT acceptance Clippy; 1,768 default +
|
||||
1,944 CRDT library tests; root CLI 33; GPU 149 required; GPU invocation
|
||||
acceptance 1 default + 9 CRDT; Vterm Stage 3 7; M4 121 with 3 ignored and
|
||||
the requested `basedpyright` skip; full workspace 2,961 across 85 suites
|
||||
with 19 ignored and 1 requested skip; formatting and diff check clean.
|
||||
Unified release build passed. Two real Wayland/Vulkan launches attached at
|
||||
protocol v19; the second reused the daemon retained after the first GPU
|
||||
process exited.
|
||||
- Distribution remains source-checkout/workspace oriented: `pmacs-gpu` is
|
||||
still unpublished. No install/service packaging claim was added.
|
||||
|
||||
|
|
|
|||
|
|
@ -24,14 +24,16 @@ commands, read `docs/active-work.md` immediately after this file.
|
|||
`ThemeFacts`, v17 = `FontFacts`, v18 = `StatuslineSegments`, v19 = terminal
|
||||
frames/events).
|
||||
- **One-command GPU invocation is implemented on OPEN PR #141, not yet on
|
||||
`main`** (`gpu-invocation`, implementation checkpoint `6fd5834`, framing
|
||||
Revision 4). The additive public path is `pmacs --gpu [--socket NAME|PATH]`;
|
||||
bare `pmacs [FILE]` remains the TUI. Root owns the CRDT gate, socket
|
||||
resolution, sibling-first GPU discovery/PATH fallback, and GPU outcome.
|
||||
The separate `pmacs-gpu` binary owns connect-or-start, a five-second /
|
||||
50-ms retry window, daemon process-group isolation, and named child
|
||||
reaping. Direct `pmacs-gpu --attach RAW_PATH` remains strict and never
|
||||
auto-starts. No protocol change.
|
||||
`main`** (`gpu-invocation`, implementation-review checkpoint `82355ca`,
|
||||
framing Revision 5). The additive public path is
|
||||
`pmacs --gpu [--socket NAME|PATH]`; bare `pmacs [FILE]` remains the TUI.
|
||||
Root owns the CRDT gate, socket resolution, sibling-regular-file GPU
|
||||
discovery/PATH fallback, and GPU outcome. The separate `pmacs-gpu` binary
|
||||
owns connect-or-start, a five-second / 50-ms retry window, pre-winit event
|
||||
buffering, daemon process-group/stdin/stdout/stderr isolation, and named
|
||||
child reaping with explicit ownership handoff. Direct
|
||||
`pmacs-gpu --attach RAW_PATH` remains strict, is documented as advanced,
|
||||
and never auto-starts. No protocol change.
|
||||
- **Config registry LANDED — #127** (`docs/config-registry-framing.md`
|
||||
rev 3; merge `2e37c04`; two review rounds). `pmacs.config` is the
|
||||
typed, introspectable options registry the backlog ranked first, and
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# GPU invocation — one-command broker framing
|
||||
|
||||
**Revision 4 — implemented on `gpu-invocation`. Ground truth: canonical
|
||||
`main` @ `96d0bae`, protocol v19, 2026-07-23.**
|
||||
**Revision 5 — implementation review complete on `gpu-invocation`. Ground
|
||||
truth: canonical `main` @ `96d0bae`, protocol v19, 2026-07-23.**
|
||||
|
||||
The GPU editor works, but reaching it is still a development-session ritual:
|
||||
build two packages with different feature requirements, keep a foreground
|
||||
|
|
@ -35,6 +35,13 @@ managed connector, process-group isolation, named child reaper, deterministic
|
|||
managed probe, acceptance suite, coherent workspace build, and one-command
|
||||
visible smoke are implemented and verified.
|
||||
|
||||
Revision 5 closes the first implementation review. Managed attach now buffers
|
||||
messages that arrive before winit creates application state, spawned-daemon
|
||||
ownership remains local until the named reaper accepts it, and the daemon
|
||||
inherits no launcher stdio. Direct GPU help points normal users to the root
|
||||
broker and labels raw socket attach as advanced. The retry, timeout, socket
|
||||
type, and concurrent-loser contracts now have deterministic behavioral tests.
|
||||
|
||||
## Ground truth
|
||||
|
||||
### Current user path
|
||||
|
|
@ -547,8 +554,10 @@ Vterm probe continues to cover offscreen wgpu.
|
|||
does not weaken the gate, and fake GPU/daemon executables record zero
|
||||
invocations. The default socket remains unowned.
|
||||
3. **Sibling discovery wins:** with executable fixtures at the current-exe
|
||||
sibling and on PATH, the sibling receives the managed arguments. Removing
|
||||
it uses PATH. With neither, the error names both lookup attempts.
|
||||
sibling and on PATH, the sibling regular file receives the managed
|
||||
arguments. A directory at the sibling pathname is ignored in favor of
|
||||
PATH. With neither executable available, the error names both lookup
|
||||
attempts.
|
||||
4. **Existing daemon fast path:** start a real CRDT daemon on a private socket,
|
||||
run `--headless-managed-probe`, and assert a v19 session establishes and a
|
||||
real `BufferSnapshot` arrives without invoking the supplied daemon spawner.
|
||||
|
|
@ -563,10 +572,11 @@ Vterm probe continues to cover offscreen wgpu.
|
|||
session remain usable. This does not require a controlling terminal or a
|
||||
foreground-process-group claim in CI. Direct foreground `pmacs --daemon`
|
||||
still exits cleanly on SIGINT.
|
||||
7. **Concurrent launchers converge:** start two managed probes together on an
|
||||
absent named socket. Exactly one daemon owns the lock; both clients
|
||||
establish sessions; the losing daemon child is reaped rather than becoming
|
||||
a zombie or aborting its frontend.
|
||||
7. **Concurrent launchers converge:** hold two daemon wrappers behind a shared
|
||||
barrier so both managed probes authorize and spawn before either daemon
|
||||
binds the absent named socket. Exactly one daemon owns the lock; both
|
||||
clients establish sessions; exactly one probe reports its losing daemon
|
||||
child reaped rather than leaving a zombie or aborting its frontend.
|
||||
8. **Stale socket recovery stays daemon-owned:** leave a stale Unix socket
|
||||
with no lock owner, launch managed GPU, and assert the daemon replaces it
|
||||
and the frontend attaches. The launcher itself performs no unlink.
|
||||
|
|
@ -574,9 +584,11 @@ Vterm probe continues to cover offscreen wgpu.
|
|||
permission-denied initial socket path invokes no daemon spawner and reports
|
||||
the path/error immediately. A regular file at the socket path survives
|
||||
unchanged, invokes no daemon, and reports that managed startup refuses to
|
||||
replace a non-socket entry. An injected post-spawn sequence of
|
||||
`Interrupted`, `WouldBlock`, then a successful real connection stays
|
||||
within the deadline and establishes the session.
|
||||
replace a non-socket entry. A unit connector injects post-spawn
|
||||
`Interrupted`, `WouldBlock`, then a successful real `UnixStream::connect`
|
||||
inside a private temporary directory; it stays within the deadline,
|
||||
establishes the protocol session, and hands the spawned child to the
|
||||
reaper.
|
||||
10. **Live capability mismatch is not replaced:** against a non-CRDT daemon,
|
||||
managed launch reports the existing capability mismatch, invokes no
|
||||
second daemon, and leaves the live daemon untouched.
|
||||
|
|
@ -585,9 +597,10 @@ Vterm probe continues to cover offscreen wgpu.
|
|||
invokes no daemon spawner, and leaves the listener/path untouched.
|
||||
12. **Bounded startup failure:** substitute a daemon executable that exits
|
||||
nonzero without binding. Managed GPU exits after five seconds (50 ms
|
||||
polls) and reports socket + child status. A concurrent-winner fixture
|
||||
proves an early losing-child exit does not abort while another process
|
||||
binds before the deadline.
|
||||
polls) and reports socket + child status. Unit tests with a one-millisecond
|
||||
deadline assert the configured duration appears in `StartupTimeout`.
|
||||
A concurrent-winner fixture proves an early losing-child exit does not
|
||||
abort while another process binds before the deadline.
|
||||
13. **Post-attach daemon exit is reaped:** let the spawned daemon establish a
|
||||
managed session, wait for the probe's `phase=ready`, then terminate the
|
||||
daemon while keeping the probe's stdin open. Poll the atomically replaced
|
||||
|
|
@ -598,11 +611,13 @@ Vterm probe continues to cover offscreen wgpu.
|
|||
succeed; fake nonzero and spawn failure make it fail with the executable
|
||||
named.
|
||||
15. **GPU argv is strict without breaking probes:** bare invocation points to
|
||||
`pmacs --gpu`; direct `--attach PATH`, existing
|
||||
`--headless-probe SOCKET REPORT`, and hidden
|
||||
`--headless-managed-probe SOCKET REPORT DAEMON_EXE` accept exactly their
|
||||
operands. Missing/trailing/unknown/incomplete args exit 2. `--version`
|
||||
prints package and protocol versions without initializing winit/wgpu.
|
||||
`pmacs --gpu`; `--help` leads with normal root-broker usage and labels
|
||||
direct `--attach PATH` as advanced. Existing `--headless-probe SOCKET
|
||||
REPORT` and hidden `--headless-managed-probe SOCKET REPORT DAEMON_EXE`
|
||||
accept exactly their operands. Missing/trailing/unknown/incomplete args
|
||||
exit 2; trailing help/version operands say those flags accept no operands.
|
||||
`--version` prints package and protocol versions without initializing
|
||||
winit/wgpu.
|
||||
16. **Existing direct and Vterm paths remain intact:** rebuilt
|
||||
`pmacs-gpu --attach RAW_PATH` still renders an existing CRDT daemon, and
|
||||
`tests/vterm_stage3_acceptance.rs` still invokes its unchanged
|
||||
|
|
@ -625,29 +640,36 @@ Vterm probe continues to cover offscreen wgpu.
|
|||
socket resolution, test override, sibling-first GPU discovery with PATH
|
||||
fallback, child argv, and exit-status propagation.
|
||||
- `pmacs-gpu/src/main.rs` accepts only explicit direct, managed, and headless
|
||||
modes. Managed windowed attach completes before winit creates a window.
|
||||
Bare invocation is an exit-2 usage error pointing users to `pmacs --gpu`.
|
||||
modes. Managed windowed attach completes before winit creates a window;
|
||||
decoded messages arriving first are buffered and drained in order once
|
||||
application state exists. Bare invocation is an exit-2 usage error pointing
|
||||
users to `pmacs --gpu`; help labels raw-socket attach as advanced.
|
||||
- `pmacs-gpu/src/attach.rs` owns connect-or-start policy, the five-second /
|
||||
50-ms retry window, socket-type protection, daemon process-group isolation,
|
||||
and the named child-reaper thread. The first successful protocol connection
|
||||
wins; protocol/capability failures never authorize replacement.
|
||||
and the named child-reaper thread. A spawned child stays owned by the
|
||||
connector until it is handed to that reaper, and daemon stdio is null. The
|
||||
first successful protocol connection wins; protocol/capability failures
|
||||
never authorize replacement.
|
||||
- `--headless-managed-probe SOCKET REPORT DAEMON_EXE` drives the production
|
||||
managed connector, writes atomic `phase=ready` / `phase=complete` reports,
|
||||
holds on stdin, and exposes disconnect plus daemon-reaper observations.
|
||||
- `tests/gpu_invocation_acceptance.rs` covers the root broker, non-CRDT gate,
|
||||
existing/missing/stale/racing daemon paths, process-group SIGINT isolation,
|
||||
capability and protocol mismatches, bounded startup failure, child reaping,
|
||||
outcome propagation, and strict headless CLI behavior.
|
||||
capability and protocol mismatches, bounded startup failure, deterministic
|
||||
losing-child reaping, outcome propagation, and strict headless CLI behavior.
|
||||
|
||||
Verification on 2026-07-23:
|
||||
Verification on 2026-07-23 after the implementation review:
|
||||
|
||||
- root CLI unit suite: 33 passed;
|
||||
- required GPU suite: 145 passed;
|
||||
- required GPU suite: 149 passed;
|
||||
- managed invocation acceptance: 1 default + 9 CRDT passed;
|
||||
- Vterm Stage 3: 7 passed with `PMACS_REQUIRE_GPU=1`;
|
||||
- default / CRDT libraries: 1,768 / 1,944 passed;
|
||||
- M4 acceptance: 121 passed, 3 ignored, 1 requested skip;
|
||||
- strict workspace Clippy and formatting passed;
|
||||
- full workspace sweep: 2,961 passed across 85 suites, 19 ignored, 1 requested
|
||||
skip;
|
||||
- strict workspace Clippy, CRDT invocation-acceptance Clippy, formatting, and
|
||||
`git diff --check` passed;
|
||||
- the documented release workspace build and `cargo run --release --
|
||||
--version` passed;
|
||||
- two real `target/release/pmacs --gpu` launches on Wayland/Vulkan attached at
|
||||
|
|
|
|||
Loading…
Reference in New Issue