37 KiB

Raw Blame History

Worker identity — Stage 1: what is running, and what it is doing

(Revision 1 was subtitled "and who asked for it". With owner removed that title overclaimed the lane: it answers what, and — under pmacs.workers.dispatch — under which registered handler. Neither is who owns it.)

Status: revision 4, APPROVED 2026-08-09. Implementation may proceed.

Revision 4 scopes rule 1's claim to what it can actually enforce, and takes Q#W-7 into this lane. Revision 3 said the rule covered "all yield points"; it covers the two supported pmacs yield APIs. Raw coroutine.yield stays reachable — R46 is a convention, and the scheduler diagnoses a non-Handle yield only after the coroutine has suspended (async.lua:197 resumes, :212 inspects), so no refusal sited in a yield helper can intercept it. The residual is named in §2 rather than papered over.

Revision 3 closes a hole in revision 2's ambient: the extent it called "synchronous" is not. A registered handler is arbitrary Lua and may Handle:await(), parking the coroutine with the name still pushed so that unrelated later work inherits it. Rule 1 now enforces non-yieldability rather than assuming it, following the guard this file already carries for pmacs.window.commit_to. Scouting that guard turned up a second supported yield API it does not cover — Q#W-7, a pre-existing defect in another lane's invariant. Revision 3 reported it rather than patching it in silence; revision 4 fixes it here, on approval, since it is the same helper, the same invariant and the same edit family.

Revision 2 removes owner and respecifies the handler-name path, after review found the first dishonest and the second unbuildable as described. owner populated from static per-subsystem constants is an origin, not an owner, and would misattribute third-party work at exactly the point §9 wants attribution. And "the name is in hand at the one place that throws it away" was wrong about the call chain — it is thrown away across three layers, one of which callers are documented to bypass. Both re-scouted in the tree.

1. Why this, and why now

COHERENCE.md §9 grades the worker model mechanism without identity, and §0 names step 11 (background-work ownership) as one of the two remaining thin ends of the golden journey. §20 Priority 1 is blunt about where that leaves things:

The remaining thin end is no longer inside this priority. Step 1 is install, which is P8; step 11 is background-work ownership, which is §9.

So this is the last of Priority 1's own journey, sitting in another section's arc. Everything else P1 named has landed.

The felt gap is smaller and sharper than the arc. §9's audit ends with a claim that is checkable, and I checked it:

No progress indicator exists anywhere — no statusline spinner, no busy count.

grep -c -i "spinner\|progress\|busy" src/statusline.rs returns 0. So §3's promise of "visible asynchronous work" is false today unless the user knows to run M-x editor.list-workers. Every build, LSP index, grep, parse and — as of the lane merging beside this one — every git status runs with no indication that anything is happening at all.

And the git Stage 1 lane in flight right now makes it worse, by its own admission. docs/git-integration-framing.md Q#G-5 states it plainly: git runs as a spawned process, spawned processes do not appear in *workers*, and the lane therefore "adds a fifth thing that runs in the background and is not attributable from one place". It accepted that cost because these are short-lived reads. This lane is the one that repays it.

2. Ground truth

Scouted in the tree, not recalled from the audit — and the audit has drifted in one place, recorded below.

The audit's PendingJob field list is stale, and the drift is informative. §9 lists seven fields; the struct (src/async_runtime.rs:367-411) carries eight. The addition is resource: Option<ResourceOp>, from dired Stage 2a — and its doc comment cites COHERENCE.md §9 by name as the reason it is a field on the job rather than a side map:

COHERENCE.md §9 is why this is a field on the job and not a side map — the parse job→buffer link already lives in a side map and §9 names that as the defect.

So the precedent for putting identity on the job is already set, already argued, and already merged. This lane extends a decision rather than introducing one.
There is a SINGLE allocation funnel, and that is what makes this tractable. Every job in the system is born in allocate (src/async_runtime.rs:746), which delegates to allocate_with_resource (:757). The ten dispatch_* methods (:803–:980) and register_external (:1011, used by MCP and LSP) all pass through it. An identity field added there reaches every job by construction — there is no second birth site to miss.
The two-function split is itself a warning. allocate_with_resource exists only because one prior lane needed one extra parameter. A second lane doing the same produces allocate_with_resource_and_identity, and a third produces something worse. This is the point to collapse it (Q#W-1).
JobKind is still a closed 12-variant enum (src/async_runtime.rs:305-343) — Sleep, ComputeSum, EmitN, Grep, Parse, FsReadDir, FsStat, FsRename, FsChmod, FsRemove, McpRequest, LspRequest. Confirmed unchanged since the audit.
A third-party job's own name is retained nowhere, and recovering it is NOT cheap. Revision 1 said it was, and was wrong about the call chain. The full path, read rather than assumed:
```
pmacs.workers.dispatch(name, args, opts)   -- async.lua:369
  → handlers[name](args, opts)             -- arbitrary Lua
    → dispatch_grep(spec, opts)            -- Lua wrapper, :312
      → async_mod._dispatch_grep(spec, supersede_key(opts), max_batch)
        → the Rust binding → allocate()
```
name is not a parameter of any layer below the first. The Rust dispatchers accept job arguments, a supersede key and stream data — nothing else. So revision 1's "change the allocation funnel and the name is recovered" is false: changing allocate gives the name nowhere to arrive from.

And the wrapper layer cannot be the capture point either. async.lua:337-345 deliberately exposes pmacs.workers._new_handle / _new_stream so that "other builtin runtime files (pmacs.fs in M8.1, future siblings) can construct handles for ids dispatched through their own raw _dispatch_* primitives". A handler that goes straight to async_mod._dispatch_* bypasses dispatch_grep and friends entirely — and those are precisely the callers doing non-standard work, i.e. the ones attribution is for.

The audit's "every third-party job renders under a builtin's label" is exact. The mechanism that fixes it is Q#W-2, and it is a real mechanism, not a parameter.
ProcessSpec has one identity field and it is a convention (src/process.rs:193-235): label: String, documented as "human-readable ... surfaced in events and the pmacs.process.list output". No owner, no purpose, no parent. Callers spell it however they like (lsp:{name}, a terminal buffer name).
A dynamic scope that must not be yielded out of ALREADY EXISTS here, guard and rationale included. Handle:await() refuses to run inside pmacs.window.commit_to (builtin/runtime/async.lua:87-90), raising "await: cannot await inside pmacs.window.commit_to; await first, then commit". Its comment states the hazard in general terms: yielding out of the extent "would restore the scope while this coroutine is still parked, so the rest of the commit would resume ambient". commit_to itself is "an RAII guard on the Rust stack" — the same shape this lane needs.
There are TWO SUPPORTED yield APIs, not one. Handle:await() yields at async.lua:95; pmacs.async.yield_to_next_tick() yields at async.lua:244 and is public (pmacs.async is async_public, :247). Any rule about a non-yieldable extent has to cover both. The commit_to guard covers only the first — see Q#W-7.
Raw coroutine.yield remains reachable, and NO guard of this shape can cover it. R46 is a convention — "package code uses :await() rather than coroutine.yield" (async.lua:26-27) — not an enforcement. The scheduler does diagnose a non-Handle yield (async.lua:217-223, "use Handle:await() per R46"), but only after the fact: step calls coroutine.resume(co) at :197 and inspects what came back at :212, by which point the coroutine has already suspended. A refusal placed in a yield helper is never consulted, and the enclosing pmacs.workers.dispatch never returns to run its pop.

So the honest bound is: a package that violates R46 inside a dispatch-name scope can leak the name. It is not silent — the scheduler raises it through pmacs.error into *errors* — but the scope is not restored, and this framing does not claim otherwise.

And the two findings that actually shape the design:

A statusline provider API already exists, with three Lua adopters. pmacs.statusline.register is live in terminal.lua:477, syntax.lua:551 and lsp.lua:1145, taking { name, side, priority, face, fn(ctx) } and returning a string or nil. An activity indicator is a fourth registration, not a new mechanism.

And it is evaluated per frame: evaluate_statusline is called inside paint_frame (src/editor.rs:4560), before the long mutable core borrow. So an indicator updates while work is in flight without any new tick machinery — and, decisively for scheduling, without touching the wire. EvaluatedStatuslineSegment is already Vec-valued on an existing message; a fourth provider adds an element, not a variant.
pmacs.process.list deliberately hides terminal PTYs, and un-hiding them is NOT free. The binding filters to AnsiParserProfile::LineOriented (src/lua_bindings/mod.rs:8980-8984). git log -S dates that filter to bbc1f33 feat(vterm): add Stage 1 terminal core — terminals were excluded on purpose.

Three acceptance suites use #pmacs.process.list() as a leak detector: tests/m6_8_multi_repl_acceptance.rs:385/:459 ("size must not grow across cycles"), tests/compile_mode_acceptance.rs:133/ :458 ("process list returns to baseline"), and tests/lean4_stage1_acceptance.rs:327/:349. Removing the filter would inflate every one of those baselines by each open terminal.

This is why §9's "a terminal PTY appears in no user-visible activity view" is a real defect with a non-obvious fix, and why this lane does not casually widen the existing accessor (Q#W-4).

3. The staging, and why the line falls where it does

§9's full statement wants owner, workspace, buffer, parent, children, latency class, cancellation scope, resource budget, execution location, progress, and failure attribution. Two of those cannot be built at all right now: Workspace is §7, graded missing, and Location is §8, graded missing (architecture ready). A lane that added workspace: Option<WorkspaceId> would be adding a field typed on a thing that does not exist.

Stage 1 (this lane): a required purpose on the job and the process, and the first indicator. NO WIRE CHANGE. NO owner.

purpose, non-optional, on PendingJob, carried through the single allocation funnel, and on ProcessSpec alongside the existing label.
A dispatch-identity ambient so pmacs.workers.dispatch stops discarding the registered handler name (Q#W-2).
*workers* renders purpose.
A statusline activity indicator — the fourth provider registration, and the part a user feels on day one.

owner is deliberately absent, and revision 1 was wrong to include it. The proposal was owner = "lsp" populated from a static per-subsystem constant at each dispatcher. But a generic dispatcher has no trustworthy knowledge of who invoked it, and pmacs.process.spawn is callable by any package — so a static subsystem label is an origin or category, not an owner, and it would confidently misattribute third-party work to a builtin at exactly the point §9 wants attribution. A field that asserts a falsehood is worse than an absent one: *workers* would look attributed while naming the wrong party.

Nor is it retained under a safer name. Calling it origin or subsystem would be honest, but a second string field sitting beside purpose and grouping the view would be adopted as ownership by the next reader regardless of its name — and it would squat on the slot P3's real package signal has to fill. Stage 2 needs a grouping key; it should get a real one, not a placeholder promoted by use.

Stage 2 (separate lane): join the planes. One activity view over jobs, processes, LSP servers and terminals. This is what Stage 1's identity is for — the audit's own conclusion is that "the four views exist precisely because there is no common key to merge them on". It also owns the terminal-visibility decision (Q#W-4), because that is a question about the unified view, not about the accessor.

Stage 3 (unscheduled): the tree and scoped cancellation. parent/children, and cancel-by-owner / by-buffer / by-subtree. This needs an ambient "currently-running job" context so a child dispatched inside a job can find its parent without every call site threading it — a real mechanism with its own failure modes, and the reason parent is not in Stage 1 (Q#W-5).

Workspace and location are never this arc's, at any stage. They arrive from §7 and §8 and this arc consumes them.

The line falls at the wire on purpose, and it is again a scheduling decision. The discovery Stage 2 lane holds the v22→v23 bump slot, and git Stage 2 is already queued behind it. PROTOCOL_VERSION is a strict serialization point. Stage 1 here touching no wire is what lets it run beside both.

4. Coherence impact (§20)

§9 worker ownership — the direct target, and specifically the audit's named prerequisite: "Owner/purpose/parent fields on the job and process specs are the prerequisite; the unified view and the ownership tree fall out of them." Stage 1 takes ONE of the three — purpose. owner waits for P3 to supply a package signal worth recording (§3); parent waits for Stage 3 (Q#W-5). Taking one of three named prerequisites is a deviation from the audit, and it is stated here rather than left to be noticed.
Journey step 11 — the direct target. §0 names background-work ownership as one of two remaining thin ends. This does not close the step (Stage 2's unified view is most of that) but it is the first thing that makes work visible, which is what step 11 is about.
§3 zero-configuration state: repairs a claim that is currently false. "Visible asynchronous work" becomes true by default, with no configuration and no command to know about.
Interaction islands (§6): none added. The indicator is a statusline provider; it intercepts no keys and adds no precedence rung.
§14 workbench primitives: untouched. *workers* already exists; this changes what it renders, not what renders it.
Config registry: one setting at most, and my vote is a visibility toggle only (Q#W-6).
The debt this repays is named and dated. git-integration-framing.md Q#G-5 recorded a deliberate negative §9 impact. This lane does not fully discharge it — a labelled process is still not in *workers* until Stage 2 — but it makes the process state what it is doing in a required field rather than a caller-spelled convention.
No P3 alignment is claimed. Revision 1 argued this lane aligned with P3's ownership arc. With owner removed, it does not: P3 stays entirely ahead of it, and this lane deliberately leaves that slot empty rather than filling it with something P3 would have to displace.

5. Open questions

Q#W-1 — how is identity supplied at the allocation funnel?

The existing shape is allocate(kind, supersede, stream) delegating to allocate_with_resource(kind, supersede, stream, resource). Adding two more positional parameters gives a five-argument function and a six-argument variant, and the next lane adds a seventh.

My vote: collapse the pair into one funnel taking a struct, e.g. allocate(JobSpec { kind, supersede, stream, resource, purpose }), so the ten dispatchers read as named-field literals rather than positional soup. Ten call sites plus register_external is a bounded, mechanical edit, and it removes the _with_resource wart rather than adding beside it.

JobSpec is private, and purpose is non-optional. Private because the public dispatcher APIs should not grow a parameter every time this arc adds a field; non-optional because that is what makes the compiler, rather than a test, the thing that proves every caller supplied one (§6). A Default impl would defeat exactly that, so purpose is not defaulted even if other fields are.

The counter-argument, which is real: this touches every dispatcher in a lane whose subject is identity, which is scope the reviewer did not ask for. If review prefers the minimal edit, the alternative is one more parameter on the existing pair, and the collapse becomes its own small lane. I would rather be told than assume.

Q#W-2 — the dispatch identity path (rewritten in rev 2, rule 1 added in rev 3)

Revision 1 treated this as a parameter-passing detail. §2 shows it is not: name dies at pmacs.workers.dispatch and nothing below it takes a name, so the value must be carried out of band across an arbitrary handler.

Revision 2 then called the extent "synchronous" and assumed it. Review found that it is not. A registered handler is arbitrary Lua running inside pmacs.async, and it may call Handle:await() — a legal, yieldable path that the existing tests already exercise inside pcall. While a handler is parked, its pushed name stays on the stack, and every tick callback and every other coroutine that allocates a job in the meantime inherits it. That is not a corner case; it is the ordinary shape of a handler that awaits.

So rule 1 below is no longer an observation about how handlers happen to behave. It is an enforced property, and the enforcement already has a precedent in this exact file (§2a).

The capture point is Rust, not Lua, and the reason is the bypass in §2. If the ambient lived in the Lua wrapper layer, a handler calling async_mod._dispatch_* directly — the documented pattern for runtime files with their own primitives — would produce an unattributed job, and those are the callers attribution exists for. Putting it in the runtime means it is read at allocate, the same single funnel Q#W-1 is already collapsing. One mechanism, one site, no path around it.

My vote: a dispatch-name stack owned by the async runtime, with pmacs.workers.dispatch bracketing its handler call through two runtime-internal bindings (_push_dispatch_name / _pop_dispatch_name).

The contract, in full:

THE EXTENT IS NON-YIELDABLE, AND THAT IS ENFORCED, NOT ASSUMED. Awaiting inside a dispatch-name scope is refused, because yielding would park the coroutine with the name still pushed and hand it to whatever allocates next.

The guard is modelled on the one already in the file (§2): _in_dispatch_name_scope() joins _in_commit_scope() as a refusal in the same place, with the same shape of message and the same remedy — await first, then dispatch.

Three details that decide whether the guard actually holds:
- It rejects BEFORE parking. The commit_to guard is the first thing in await, ahead of the _is_complete check and the coroutine.yield. The new one sits beside it, for the same reason: a guard that fires after the yield has already happened guards nothing.
- It rejects UNCONDITIONALLY, not only when the handle is incomplete. A guard that fires only when a yield would really occur has behaviour depending on whether the job happened to finish first — it would pass under test and fail in production, intermittently. commit_to's guard is unconditional and this one matches it.
- It covers BOTH SUPPORTED YIELD APIs — and that is the exact extent of the claim. pmacs.async.yield_to_next_tick() (async.lua:243-245) yields too, and is public, so it gets the same refusal; guarding only await would leave the hole open through a second door (and Q#W-7 is the proof that this happens, because commit_to has exactly that gap today).
  
  What rule 1 does NOT cover is raw coroutine.yield (§2). R46 forbids it to package code by convention only, and the scheduler's diagnostic fires after suspension, so no refusal sited in a yield helper can intercept it. Revision 3 said "all yield points" and was overclaiming. The property is: the supported ways to yield are refused inside the scope; an R46 violation can still leak the name, loudly.
Work dispatched later is NOT covered, deliberately. A job dispatched from an on_complete callback or a resumed coroutine runs ticks later, outside the extent, and carries only its own purpose. Pretending otherwise would need the asynchronous lifetime mechanism this lane defers (Q#W-5).
Nesting is a stack; innermost wins. Handler a calling pmacs.workers.dispatch("b", …) gives jobs allocated inside b the name b, and restores a on return.
Fan-out shares the name. A handler dispatching five jobs produces five jobs named alike. They were all dispatched under it; that is the fact being recorded, not a collision.
Unwind-safe, and this is the one that makes a naive version worse than none. A handler that errors must still pop — otherwise one failure poisons every subsequent dispatch in the session with a stale name, and the feature silently starts lying. pmacs.workers. dispatch runs the handler under pcall, pops, and rethrows.
Precedence over a caller-supplied purpose: COMPOSE, do not replace. Where the dispatch site supplied its own purpose, the recorded value is "<name>: <purpose>"; where it did not, the recorded value is "<name>". Replacing would recreate blocker 1 in a new place — dispatch_grep supplies "grep: …", and letting that win would lose the third party again, while letting the name win would discard the only description of the actual work. Composition is capped at the innermost name by rule 3, so no unbounded chain.
Outside any extent, nothing changes. A builtin invoked directly records its own purpose.

A known and accepted property, stated rather than discovered later: the ambient captures causal extent, not intent. If a handler triggers unrelated work within its extent — an edit that schedules a parse — that job takes the name. Because rule 1 refuses both supported yield APIs, that window is bounded by a single un-parked call for any caller obeying R46, and within such a window I think "this ran because that handler ran" is the honest reading. (A caller violating R46 is outside this property, and outside rule 1 — §2.) It is also the only definition enforceable at a single funnel. If review disagrees, the alternative is capture-at-the-Lua-wrapper, which is narrower and misses the raw _dispatch_* callers — a trade of false positives for false negatives, and I would rather over-attribute inside a bounded call than silently drop the third-party case.

Why this ambient is admissible while Q#W-5's is not. They are not the same mechanism — and revision 2 was entitled to that claim only after rule 1 made it true. As written in revision 2 the extent could be parked by any awaiting handler, which is most of the way to the asynchronous lifetime I used as the reason for deferring parent. With rule 1 the difference is real and enforced: this is a single-threaded dynamic extent that cannot be suspended, with a deterministic pop on both the normal and the error path. A parent ambient must span a job's asynchronous lifetime by design — across ticks, through callbacks that run after the parent settled — and cannot be fixed by refusing to yield, because yielding is the whole point. The first is a stack; the second is a lifetime model.

Q#W-3 — what does the indicator actually show?

My vote: a count plus the oldest in-flight job's purpose, and nothing when idle — e.g. ⋯2 lsp: indexing, absent entirely at zero. With owner gone (§3) purpose is the only identity there is, which is also why it is required rather than optional.

Oldest, not newest or "busiest". Revision 1 said "busiest", which is not a defined quantity — jobs carry no cost estimate. Oldest is computable from dispatched_at, which PendingJob already has, and it answers the question a user actually asks of a stuck editor: what is taking so long?

Absent at zero, not 0 jobs. A statusline segment that is always present costs width forever to say "nothing is happening". The existing providers already return nil to render nothing (lsp.lua:1156), so this is the established idiom.
A count, not a spinner. A spinner needs an animation frame clock and says only "something"; a count says how much. Per-frame evaluation makes either possible, so this is a product choice, not a constraint.
Not names plural. One purpose keeps it to a bounded width; the full list is what *workers* is for.

Q#W-4 — do terminal PTYs become visible in Stage 1?

No — and the reason is evidence, not caution. pmacs.process.list filters to LineOriented, and three acceptance suites assert on #pmacs.process.list() as a leak baseline (§2). Widening that accessor would inflate all three with every open terminal, and "fix the tests" is the wrong response to a test that is correctly detecting a semantic change.

My vote: leave the accessor alone in Stage 1, and let Stage 2's unified view introduce a separate enumeration that includes PTYs. The leak detectors keep asserting what they were written to assert; the new surface answers the new question. Two accessors with different contracts is better than one accessor whose meaning silently changed under its existing callers.

Q#W-5 — does `parent` belong in Stage 1?

My vote: no. The audit names owner/purpose/parent together as the prerequisite, and after revision 2 this lane takes only purpose — so both omissions need justifying, not just this one. owner's is in §3; parent's is here.

purpose is a value the dispatcher already knows at the call site. A parent is not — it is whatever job is currently running when a child is dispatched. A parent field that nothing populates is worse than no field: it renders as None everywhere and reads as "this job has no parent" rather than "this system does not track parents".

And the objection this has to answer, since the lane now builds an ambient of its own (Q#W-2): why is one admissible and not the other? Because Q#W-2's extent cannot be suspended — rule 1 refuses both yield points, so it is bounded by one un-parked call with a deterministic pop on the normal and the error path.

That distinction is only load-bearing because rule 1 exists. Revision 2 asserted this same paragraph while its ambient could be parked by any awaiting handler, which made the two mechanisms far more alike than the argument admitted. The honest version: a parent ambient must identify the running job across ticks — a job dispatched from an on_complete callback should name the job whose completion fired it, and that callback runs after the parent settled, outside any dispatch call. Refusing to yield cannot rescue it, because yielding is the mechanism it needs. That is a lifetime model, not a stack, and it is Stage 3's subject rather than a field this lane can add cheaply.

Stage 3 builds the lifetime model and the field together, where the field can be tested by a populated case.

Q#W-7 — the same hole exists in `commit_to` today — RESOLVED, fixed here (rev 4)

Found while scouting rule 1, and reported rather than quietly patched.

Handle:await() refuses to run inside pmacs.window.commit_to (async.lua:87-90) precisely so a coroutine cannot park with the frontend scope pushed. But pmacs.async.yield_to_next_tick() (async.lua:243-245) also yields, is public, and carries no such refusal. A coroutine inside commit_to can therefore park through that door and produce exactly the misrouting the await guard exists to prevent. Journey Stage 1a's Q#JR14b invariant has a second entrance.

I have not verified that a real caller does this — the reachability of the bug is unproven, and I would rather say so than dress a code-reading up as a repro.

RESOLVED — approved for this lane. It is the same supported yield helper, the same invariant, and the same async.lua edit family; splitting it 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's, not a smoke test: the refusal fires, and the commit scope is restored afterwards. A guard that raises while leaving the scope pushed converts a silent misrouting into a noisy one and fixes nothing.

Reachability by a real caller stays unproven — this is a defect found by reading, and the tests pin the guard rather than reproducing a user-visible bug. That distinction belongs in the commit message too, so nobody later cites this as evidence the bug was observed.

Q#W-6 — is any of this configurable?

My vote: one boolean, ui.activity-indicator (default true), through pmacs.config.define. §11 grades the registry "partial (foundation only)" and this document's sibling framings have both resisted speculative settings — but a permanently-visible statusline element is different in kind from an internal behaviour: it costs width on every frame, and "I do not want this in my modeline" is a preference someone will genuinely hold on day one rather than a hypothetical. git.enabled and ui.line-wrap are the precedent shape.

No setting for purpose capture itself — that is substrate, not preference.

6. Verification

Presence is enforced by the COMPILER, not by a test. purpose is non-optional in JobSpec, so a dispatcher that supplies none does not build. Revision 1 claimed a single funnel assertion proved "every job carries an identity"; it does not — a funnel test proves the funnel stores what it was handed, and says nothing about whether fourteen callers handed it anything meaningful. Presence is a type obligation; the tests below are for semantics.
Representative entry paths assert the semantics, one per distinct shape rather than one per dispatcher: a pool dispatcher, an register_external job (MCP/LSP bypass the worker pool entirely and are the likeliest to be missed), and a spawned process.
A pmacs.workers.dispatch("name", …) job reports "name", and the witness is a handler registered from Lua that calls a real dispatcher — not a synthetic funnel test. A test that pushes the ambient by hand proves the stack works and leaves the actual defect (name dying in an arbitrary handler) unwitnessed.
Awaiting inside a handler is REFUSED, and the scope restores after the refusal (Q#W-2 rule 1). Two assertions, and the second is the load-bearing one: a guard that raises but leaves the name pushed has converted a silent misattribution into a silent misattribution plus an error. The witness dispatches again after the rejection and asserts the new job carries no stale name.
pmacs.async.yield_to_next_tick() inside a handler is refused too, with the same restore-after assertion. Guarding one supported yield API and not the other leaves the hole open through a second door (§2).
yield_to_next_tick inside pmacs.window.commit_to is refused, and the commit scope restores after the refusal (Q#W-7) — the pre-existing gap, closed here. Both halves asserted, for the same reason as rule 1's: a refusal that leaves the scope pushed has swapped a silent fault for a loud one.
NOT asserted, and deliberately: that a raw coroutine.yield inside either scope is prevented. It is not (§2). Writing a test that "proves" coverage this design does not have would be worse than the gap, and the gap is recorded instead.
The refusal fires even when the awaited handle is already complete (rule 1) — the case that separates an unconditional guard from one whose behaviour depends on a race.
The ambient survives a failing handler (Q#W-2 rule 5): a handler that errors, then a subsequent unrelated dispatch, asserting the second job does not carry the first's name. This is the regression that would otherwise appear as intermittent misattribution long after the lane lands.
Nesting and fan-out (rules 3–4): a handler dispatching two jobs gives both its name; a handler dispatching through another registered handler gives the inner jobs the inner name and restores the outer.
Composition, not replacement (rule 6): a handler calling a dispatcher that supplies its own purpose yields "<name>: <purpose>" — asserted for both halves, since a test on the prefix alone passes when the description is dropped.
Work dispatched from an on_complete callback carries no handler name (rule 2) — the boundary of the extent, asserted deliberately so it reads as designed rather than broken.
The statusline shows nothing at idle, asserted as absent segment, not as empty string — a zero-width segment still consumes a separator.
The statusline shows a count while work is in flight, witnessed through the real per-frame evaluation path (paint_frame), not by calling the provider function directly. A provider that works in isolation and never gets evaluated is the failure this must exclude.
The indicator honours ui.activity-indicator = false (Q#W-6), witnessed as an absent segment with work genuinely in flight — the case that separates "disabled" from "idle".
#pmacs.process.list() is UNCHANGED for every existing caller (Q#W-4). The three leak-detector suites (m6_8_multi_repl_acceptance, compile_mode_acceptance, lean4_stage1_acceptance) are the assertion, and they must pass untouched. If any of them needs editing, the design is wrong, and that is the signal to stop rather than to adjust a baseline.
A spawned process carries a required purpose alongside its existing label, and label's current callers keep working unchanged — lsp:{name} and terminal buffer names are live conventions with existing consumers.
Both frontends render the segment, since it rides the existing StatuslineSegments path — asserted for the grid TUI and pmacs-gpu, because "it is on an existing message" is a claim about the producer and says nothing about whether a consumer draws it.

What this will NOT prove: that background work is attributable from one place (that is Stage 2's unified view — this lane makes it possible, not done), that a terminal PTY is visible anywhere (Q#W-4), that cancellation can range over an owner (Stage 3), or that any job is attributed to the PACKAGE responsible for it — purpose records what work is being done and, under pmacs.workers.dispatch, which registered handler it ran under. Neither is package ownership, which waits for P3 (§3).

Gates via scripts/gate --acceptance <the new suite>. No --protocol: this lane has no wire change, which is the property that lets it run beside the two lanes already in flight.

7. Not in scope

Making raw coroutine.yield safe inside either dynamic scope (§2, rule 1). R46 forbids it by convention and the scheduler diagnoses it after the fact; closing it properly means enforcement the runtime does not have, and this lane claims only the two supported yield APIs. owner, in any spelling — including origin or subsystem (§3). The slot stays empty until P3 can fill it with a package signal; nothing in this lane may be promoted into it later by use. Workspace and Location fields (§7/§8 — the entities do not exist). parent/children and the ownership tree (Stage 3, Q#W-5). Scoped cancellation of any kind — cancel-all, by-kind, by-buffer, by-owner, by-subtree (Stage 3; there is nothing to range over until identity exists). The unified activity view joining the four planes (Stage 2). Making terminal PTYs visible (Stage 2, Q#W-4). Widening JobKind or making it open — third-party jobs are described by purpose, which is the point, and reopening a closed wire-adjacent enum is a separate decision. Latency classes and resource budgets (§9 names them; neither has a consumer yet). Supersession coverage — §9 notes parse jobs and MCP requests pass None, which is a real defect and a different one. P3's package-ownership signal — §3 defers owner to it and makes no claim of alignment with it.

37 KiB Raw Blame History Unescape Escape