Review round 2, findings P2a and P2b, plus P3's stale recovery
summaries. Three defects, and the fix is deliberately different in each
place because the constraint is.
## P2a — invalid UTF-8 bypassed the `purpose` diagnostic
`required_purpose` read the field with `value.to_str()?`. Lua strings
are BYTE strings, so `purpose = string.char(255)` is a value a caller
can write, and `?` surfaced mlua's generic conversion error BEFORE this
lane's own diagnostic was ever constructed: the caller was told neither
the field nor the rule.
**This is the third time this project has hit the class** — an unowned
Lua string converted with `?` ahead of the owned message; the
destination-capture lane corrected the same shape two rounds ago. It
refused before spawning and nothing leaked, so the defect was the
message, not the outcome. The conversion failure is now mapped onto
this function's own message, and the new acceptance row asserts on
message CONTENT so retyping the read as a bare `?` breaks the test
rather than silently degrading the error.
Auditing the rest of the lane's diff for the same class turned up
exactly one more: `_push_dispatch_name` took `name: String`, so a
registered handler name that was not valid UTF-8 failed at first
dispatch with mlua's generic message. It now takes `mlua::String` and
maps that failure onto an owned diagnostic naming the argument and the
rule. Those are the only two Lua-string reads this lane added; every
other binding it adds takes `()`.
## P2b — no safe display-text boundary. Two halves, two different fixes
### Handler names are refused at the source
`pmacs.workers.register` type-checked its name and nothing more, which
was defensible while the name died inside `dispatch`. It no longer dies
there: the ambient carries it into every job the handler allocates and
composes it into `purpose`, which `*workers*` and the modeline both
render. So it now gets `purpose`'s meaningful-value standard —
non-empty, not whitespace-only — plus control characters, which have no
legitimate place in a registered identifier.
### Purposes are ESCAPED at presentation, not rejected at the registry
A purpose may legitimately contain a newline: a filesystem path can, and
`pmacs-magit`'s spawn purpose is a whole argv. **This is the shape of
the `#228` decision, and it is consistent with it** — the one-line
constraint belongs to the surface that has it, not to the registry that
does not. There, `Command.description` stays free-form and the two
single-row consumers clip with `description_first_line`. Here the
equivalent is escaping rather than clipping, because a purpose's later
words are load-bearing: an argv's second word says which file, and a
clip would drop it silently.
`purpose_for_one_row` states the property it exists for: **a row must
not be able to forge another row.** It escapes `\n`, `\r`, `\t` and the
rest of the Unicode `Cc` class (which covers ESC, so a purpose cannot
open a terminal escape sequence either), borrows unchanged when there is
nothing to escape — making byte-identity structural rather than
asserted — and deliberately does NOT escape backslashes: no number of
them produces a second row, and doubling them would cost byte-identity
for ordinary text.
Two surfaces call it: the `*workers*` rows, and `ActivitySummary`, which
exists for one consumer that has exactly one row.
`pmacs.workers.snapshot()` is this lane's `describe-command` and stays
raw, which is what makes this a rendering decision rather than data
loss — asserted, not assumed.
## P3 — two stale recovery summaries
`docs/worker-identity-framing.md` still said "Implementation may
proceed"; it is implemented. `docs/active-work.md` still said Stage 1
takes the "first two" of owner/purpose/parent — `owner` was REMOVED in
revision 2, so it takes one of the three, and the claim the whole
`owner` argument overturned was still standing in the volatile state of
record. Both fixed section-locally.
## Verification
`tests/worker_identity_acceptance.rs`, 18 -> 24 tests:
* invalid-UTF-8 purpose refused by THIS lane's message, asserted on
content, alongside the absent / empty / whitespace / wrong-type /
metatable rows;
* a whitespace-only handler name and a control-character one are each
refused AT `register`, asserted on the error and on the handler not
being installed (dispatch reports `unknown handler`);
* a non-UTF-8 handler name is refused before the handler runs, with the
dispatch-name stack left empty;
* a purpose containing a newline renders as ONE row in `*workers*` and
as one line in the modeline — through the real rendering path, the
latter through a painted frame as well as the evaluator;
* **a purpose crafted to look like a row boundary does not produce a
second row** — asserted by counting rows, with the escaped text
asserted present so a renderer that dropped the purpose entirely could
not pass;
* a purpose with no control characters is byte-identical on both
surfaces, fixtured with a literal backslash, a literal `\v`, quotes
and a non-ASCII character.
Mutation-checked, seven guards, each failing its own test and no other:
the purpose UTF-8 diagnostic; the `_push_dispatch_name` one; the
register whitespace guard; the register control-character guard; the
`*workers*` call site; the `ActivitySummary` call site; and
`purpose_for_one_row` itself neutered to the identity, which fails both
surfaces' tests and nothing else.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016bqGA6s9tTUFzYpbeW3tai
Two section-local edits, no reflowing.
**`docs/worker-identity-framing.md` §2** named the three existing
statusline adopters by FILE — `terminal.lua`, `syntax.lua`, `lsp.lua` —
which is accurate and misleading together: `syntax.lua` registers its
provider under the name **`"mode"`**, so the registry inventory reads
`["mode", "terminal", "lsp"]` and a reader looking for the syntax adopter
by name does not find one. That is what made this lane's change to
`tests/statusline_segments_acceptance.rs` surprising, and the next reader
should not have to rediscover it. Also records that where a fourth
registration sorts is decided by **load order**, not by name.
**`docs/active-work.md`'s lane block** records review round 1: the
`pmacs.process.spawn` blocker and its fix at `2162737`, the five refused
shapes, the eleven updated call sites, the two audit-fixture occurrences
that are deliberately untouched, the three added mutation checks, and the
two acceptance suites the round added to the gate line
(`compile_mode_acceptance` and `m8_6_acceptance`, because the round moved
their spawn call sites and `m8_6` covers the `pmacs-magit` package
fixture).
It also records the breaking-change decision with the reasoning that
justified it, rather than only the outcome: the binding has no
API-reference documentation and no stability promise, `lua_to_spec` has
one caller, and §10/P7 put the third-party population at ~zero — so the
cost of requiring the field is at its minimum now and rises from here.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016bqGA6s9tTUFzYpbeW3tai
Two changes, both from review, both about claiming exactly what is
enforced and no more.
Rule 1 said it covered "all yield points". It covers the two supported
pmacs yield APIs. Raw coroutine.yield remains reachable: R46 is a
convention ("package code uses :await() rather than coroutine.yield",
async.lua:26-27), not an enforcement, and the scheduler diagnoses a
non-Handle yield only after the fact --- step() resumes at :197 and
inspects what came back at :212, by which point the coroutine has
already suspended and the enclosing dispatch never returns to run its
pop. No refusal sited in a yield helper can intercept that.
So the property is stated as what it is: the supported ways to yield
are refused inside the scope, and an R46 violation can still leak the
name --- loudly, through pmacs.error into *errors*, but unrestored.
Section 6 says explicitly that this is NOT asserted, because a test
implying coverage the design lacks is worse than the recorded gap.
Q#W-7 is approved into this lane rather than split out. Same supported
helper, same invariant, same async.lua edit family; splitting would
preserve a known hole without reducing integration risk. So
yield_to_next_tick gains both refusals --- the new
_in_dispatch_name_scope and the missing _in_commit_scope --- and the
commit_to gap closes in the same commit as rule 1. Its witnesses are
the same pair as rule 1: the refusal fires AND the scope restores, on
the reasoning that a guard which raises while leaving the scope pushed
trades a silent fault for a loud one and fixes neither.
Reachability by a real caller stays UNPROVEN and the framing says so in
three places, including here. The defect was found by reading; the
tests pin the guard rather than reproducing a user-visible bug. Nobody
should later cite this as evidence the bug was observed.
The causal-extent paragraph and the Q#W-5 comparison were both
re-scoped to match, since both leaned on "non-yieldable" as an
unqualified property.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016bqGA6s9tTUFzYpbeW3tai
Review found that revision 2 asserted the property its whole design
rested on. It called the dispatch-name extent "synchronous" and never
checked. A registered handler is arbitrary Lua running inside
pmacs.async and may call Handle:await(), which parks the coroutine with
the name still pushed --- so every tick callback and every other
coroutine allocating a job in the meantime inherits it. The existing
tests already await inside pcall, so this is the ordinary shape of an
awaiting handler, not a corner case.
Rule 1 now enforces non-yieldability instead of assuming it, and the
enforcement was already in this file: Handle:await refuses to run
inside pmacs.window.commit_to (async.lua:87-90), with a comment giving
exactly this reasoning --- yielding "would restore the scope while this
coroutine is still parked". _in_dispatch_name_scope joins
_in_commit_scope in the same place.
Three details decide whether the guard holds, and all three are pinned:
it rejects before the park, not after; it rejects unconditionally
rather than only when the handle is incomplete, because a guard keyed
on whether the job happened to finish first passes under test and fails
intermittently in production; and it covers both yield points.
That last one is a finding. pmacs.async.yield_to_next_tick
(async.lua:243-245) also yields and is public. Guarding only await
would have left the hole open through a second door.
Which exposes Q#W-7: the existing commit_to guard has exactly that gap
today. yield_to_next_tick carries no _in_commit_scope refusal, so
Journey Stage 1a Q#JR14b invariant has a second entrance. Reported
rather than patched, and reachability by a real caller is explicitly
UNPROVEN --- it is a code reading, not a repro. My vote is to fix it in
this lane since the lane already edits that function family, but it is
another lane invariant so it is a question.
Q#W-5 justification is rewritten rather than left standing. It argued
parent was deferrable because its ambient would span asynchronous
lifetimes while this one did not --- an argument revision 2 was not
entitled to make, since its own ambient could be parked by any awaiting
handler. With rule 1 the distinction is real: this extent cannot be
suspended, and parent cannot be rescued by refusing to yield because
yielding is the mechanism it needs.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016bqGA6s9tTUFzYpbeW3tai
Two review blockers, both correct, both about the same failure: a field
or a claim that looks like attribution without being it.
BLOCKER 1 --- owner is not honest before P3. Revision 1 proposed
owner = package-or-builtin while populating it from static
per-subsystem constants at each dispatcher. Those disagree. A generic
dispatcher has no trustworthy knowledge of who invoked it, and
pmacs.process.spawn is callable by any package, so a static "lsp" label
is an origin or category and would confidently misattribute
third-party work to a builtin at exactly the point section 9 wants
attribution.
owner is removed rather than renamed. origin or subsystem would be
honest wording, but a second string field beside purpose, used to group
the view, gets adopted as ownership by the next reader regardless of
its name --- and it would squat on the slot P3 has to fill. Stage 2
needs a grouping key and should get a real one. No P3 alignment is
claimed any more.
BLOCKER 2 --- the handler name needs a mechanism, not a parameter.
Revision 1 said the name was "in hand at the one place that throws it
away". That was wrong about the call chain, and re-reading it is what
showed why: dispatch(name) calls an arbitrary handler, which calls a
Lua wrapper, which calls the Rust binding, and name is a parameter of
none of them. Worse, async.lua:337-345 documents the wrapper layer as
bypassable --- other runtime files are told to call their own raw
_dispatch_* primitives --- so capturing in the wrappers would miss
exactly the callers attribution exists for.
Q#W-2 is rewritten as a contract: a dispatch-name stack owned by the
async runtime and read at allocate, the same single funnel Q#W-1
collapses. Seven rules, including the two that decide whether it is
better than nothing --- unwind-safe popping, because one erroring
handler would otherwise poison every later dispatch with a stale name,
and composition rather than replacement of a caller-supplied purpose,
because replacing recreates blocker 1 in a new place.
It also answers the objection it invites: why is this ambient allowed
when Q#W-5 defers parent for needing one. Because they are different
mechanisms --- this is a synchronous single-threaded extent with a
deterministic pop, and parent needs a lifetime model spanning ticks and
post-settlement callbacks.
Verification takes the reviewer wording fix: presence is a type
obligation now that purpose is non-optional in a private JobSpec, so
the compiler proves it and the tests prove semantics at representative
entry paths. The handler witness must be a registered handler calling a
real dispatcher, not a synthetic funnel test.
The title changed too: "who asked for it" overclaimed once owner left.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016bqGA6s9tTUFzYpbeW3tai
COHERENCE.md section 0 names background-work ownership as one of two
remaining thin ends of the golden journey, and section 20 puts it
outside Priority 1 while conceding it is the last of that priority own
work. Section 9 grades the worker model "mechanism without identity".
The felt gap is narrower than the arc and is checkable: grep -c for
spinner/progress/busy in src/statusline.rs returns 0, so section 3
promise of "visible asynchronous work" is false today unless the user
knows to run M-x editor.list-workers. The git Stage 1 lane in flight
right now records a deliberate negative section 9 impact for exactly
this reason; this lane is the one that repays it.
Two scouting findings shaped the staging rather than confirmed it.
PendingJob carries eight fields, not the seven the audit lists, and the
eighth doc comment cites section 9 by name as the reason identity
belongs on the job and not in a side map. So this extends a merged
decision instead of introducing one.
pmacs.process.list filters to LineOriented, dating to the vterm Stage 1
commit, and three acceptance suites use #pmacs.process.list() as a leak
detector. Widening that accessor to show terminal PTYs would inflate
all three baselines. Making PTYs visible therefore moves to Stage 2
behind a separate accessor, which is a better answer than editing tests
that are correctly detecting a semantic change.
NO WIRE CHANGE, and that is load-bearing for scheduling: discovery
Stage 2 holds the v22-to-v23 bump slot and git Stage 2 is queued behind
it. The activity indicator is a fourth pmacs.statusline.register
provider on the existing StatuslineSegments vector.
The framing also flags a deliberate deviation from the audit rather
than quietly taking it: section 9 names owner/purpose/parent together,
and Stage 1 takes only the first two, because an unpopulated parent
field reads as "no parent" rather than "not tracked".
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016bqGA6s9tTUFzYpbeW3tai
Levi Neuwirth