jcp-gateway: meter each call on the upstream server's own process tree #198

Merged

dcharlot merged 19 commits from feat/gateway-upstream-energy into main 2026-10-09 13:59:30 -04:00

Conversation 0 Commits 19 Files changed 17 +4408 -115

dcharlot commented 2026-10-09 10:51:22 -04:00

Owner

Copy link

Why

jcp-gateway metered each upstream tool call with the machine-wide meter. On macOS 27 every machine-wide CPU rail is frozen to an unprivileged reader, so every call was sealed Estimator.

The work of a call runs in the upstream MCP server, a process the gateway spawned. The kernel counts that process's own CPU energy (proc_pid_rusage ri_energy_nj), and any same-uid process can read it, live. This change reads that count across the server's process tree and seals the result as HwShunt. It is graded Whole only when nothing was seen missing and the operator has declared the server self-contained.

What

sandbox-meter: TreeMeter (src/probe/tree.rs, macOS). It meters the CPU energy of another live process tree: the root and every descendant (proc_listchildpids). A reading also carries the gaps it saw:

Gap	What it means
reaped-descendant	A descendant was reaped inside the span. Its energy is in no counter.
gone	A process present at the start is gone at the end.
exited	A process became a zombie inside the span. Its last on-core slice and its GPU time are lost.
predates-span	A process was found at the end but started before the span and was not read at the start.
unsettled-at-start / unsettled-at-stop	A process was still running when that end was read. At the start this over-counts; at the stop it under-counts.
tree-changing	The tree did not hold still long enough to read at the settle bound.
unreadable / unlisted	A member could not be read, or the tree could not be listed (another uid, sandbox denial).
gpu / gpu-unknown	The tree spent GPU time, or the meter cannot tell whether it did. Read from the I/O Registry by the new src/probe/gpu_clients.rs.
neural-engine	A process held in-process Neural Engine model memory (ri_lifetime_max_neural_footprint).

Settling. The count is folded only at a context switch. Read from another process, CPU time also moves in ~10 ms steps, so "CPU time unchanged" proves nothing. An end is read only when every member has no running thread (pti_numrunning) and two consecutive walks agree on membership, parents, reaped-descendant times and exit times.

jcp-gateway

• Upstream::pid() names the process. The tree meter is built lazily for it and follows a pid change.
• Each gated call is sealed as follows:
  • HwShunt, Whole: a tree reading with no gap, and the operator has called declare_upstream_self_contained() / passed --upstream-self-contained;
  • HwShunt, Partial: any other tree reading;
  • unchanged: no tree reading falls back to the machine meter, as before.
• The sealed figure and the debit are rounded up to whole µJ, so a measured call is never sealed as 0 µJ.
• The plaintext _meta gains energy_domain and, when Partial, energy_partial_because. The sealed receipt format is unchanged, and the plaintext provenance and coverage still equal the sealed ones.

Why Whole needs a declaration. No reader can see work a process hands outside its tree. One measured case: an on-device model client served by a system daemon showed no Neural Engine footprint while the Neural Engine drew about 1 W. Its own CPU count advanced only tens of millijoules. A system service over XPC, a database server or a remote API are the same. Only the operator can say the server does none of that.

Fixes to the binary

• Notifications. It waited for a reply to every line, so a real server's notifications/initialized hung it. Notifications are now sent with no wait.
• Unsolicited server lines. It took the server's first line as the reply. The server's stdout is now read on its own thread, responses are matched by id, and anything else (progress notifications, a sampling request) goes straight to the client. A call whose returned line is not its own response is sealed Partial with reply-not-the-response.
• Gated calls with no id. A tools/call, resources/read or prompts/get sent without an id is now refused before it reaches the server, with nothing sent back. The attempt is sealed on a frame whose action, notification:<tool>, no grant carries.

Spec. jcp/SPEC.md §5.1 rung 3 now covers metering another process tree: its domain, the settle rule (MUST), every gap that makes a figure Partial, and that Whole MUST NOT be sealed without the operator's declaration. jcp/README.md and sandbox/README.md are updated to match.

Evidence

• Probes on an M5 Max, macOS 27.0.1, unprivileged. These measured the fold lag, how a reaped descendant's energy is lost, that GPU time is lost about 2 ms after exit, and the Neural Engine footprint signal and its blind spot for daemon-side work. The footprint signal was confirmed against powermetrics and Core ML's compute plan.
• Oracle tests. Every tree reading equals an independent oracle, a raw proc_pid_rusage read sharing no code with the meter, to the nanojoule (sandbox-meter) and to the µJ rounded up (gateway). The servers range from a bare echo to tens of millijoules, and the tests ran at load average 150–190.
  • Partial cases tested on real processes: a shell that reaps a worker per call; a forking server whose worker is reaped during the stop walk; a Metal compute server with persistent and transient command queues; a listing denied by sandbox-exec; a server sending notifications and requests mid-call.
• Adversarial review. Five lenses (soundness, races/FFI, integration, tests/CI, docs) found 14 candidate defects, and three skeptics checked each one. 12 were confirmed and fixed, each with a test that fails when the fix is reverted. The worst: a worker born in the call and reaped during the stop walk vanished without trace, so the call read Whole. It reproduced by round trip 2 of 40 before the fix, and read Partial in 240 of 240 round trips after it.
• Suites. cargo test -p sandbox-meter and cargo test -p jcp-gateway are green at load average ~187. Linux cross-checks are clean, and clippy reports nothing new.
• CI. The macOS energy job gains a jcp-gateway (upstream process tree) step. The sandbox-meter step now also greps tree meter:. Each step fails unless its platform-gated tests printed their line.

Not covered

• Neural Engine on a real process. No test makes ri_lifetime_max_neural_footprint nonzero on a real process: building a Core ML model needs tooling the runner does not have. That gap is covered by unit tests and by today's probe.
• Metal tests in the runner context. They build a Metal compute server with /usr/bin/cc at test time. They passed in a user session but have not yet run under the macOS runner's launchd context; this PR's CI is their first run there.
• Linux. Unchanged. It has no per-process energy count, so the gateway keeps the machine meter there.

🤖 Generated with Claude Code

## Why jcp-gateway metered each upstream tool call with the machine-wide meter. On macOS 27 every machine-wide CPU rail is frozen to an unprivileged reader, so every call was sealed `Estimator`. The work of a call runs in the upstream MCP server, a process the gateway spawned. The kernel counts that process's own CPU energy (`proc_pid_rusage` `ri_energy_nj`), and any same-uid process can read it, live. This change reads that count across the server's process tree and seals the result as `HwShunt`. It is graded `Whole` only when nothing was seen missing **and** the operator has declared the server self-contained. ## What **sandbox-meter: `TreeMeter` (`src/probe/tree.rs`, macOS).** It meters the CPU energy of another live process tree: the root and every descendant (`proc_listchildpids`). A reading also carries the **gaps** it saw: | Gap | What it means | |---|---| | `reaped-descendant` | A descendant was reaped inside the span. Its energy is in no counter. | | `gone` | A process present at the start is gone at the end. | | `exited` | A process became a zombie inside the span. Its last on-core slice and its GPU time are lost. | | `predates-span` | A process was found at the end but started before the span and was not read at the start. | | `unsettled-at-start` / `unsettled-at-stop` | A process was still running when that end was read. At the start this over-counts; at the stop it under-counts. | | `tree-changing` | The tree did not hold still long enough to read at the settle bound. | | `unreadable` / `unlisted` | A member could not be read, or the tree could not be listed (another uid, sandbox denial). | | `gpu` / `gpu-unknown` | The tree spent GPU time, or the meter cannot tell whether it did. Read from the I/O Registry by the new `src/probe/gpu_clients.rs`. | | `neural-engine` | A process held in-process Neural Engine model memory (`ri_lifetime_max_neural_footprint`). | **Settling.** The count is folded only at a context switch. Read from another process, CPU time also moves in ~10 ms steps, so "CPU time unchanged" proves nothing. An end is read only when every member has **no running thread** (`pti_numrunning`) and **two consecutive walks agree** on membership, parents, reaped-descendant times and exit times. **jcp-gateway** - `Upstream::pid()` names the process. The tree meter is built lazily for it and follows a pid change. - Each gated call is sealed as follows: - **`HwShunt`, `Whole`:** a tree reading with no gap, and the operator has called `declare_upstream_self_contained()` / passed `--upstream-self-contained`; - **`HwShunt`, `Partial`:** any other tree reading; - **unchanged:** no tree reading falls back to the machine meter, as before. - The sealed figure and the debit are rounded **up** to whole µJ, so a measured call is never sealed as 0 µJ. - The plaintext `_meta` gains `energy_domain` and, when `Partial`, `energy_partial_because`. The sealed receipt format is unchanged, and the plaintext provenance and coverage still equal the sealed ones. **Why `Whole` needs a declaration.** No reader can see work a process hands outside its tree. One measured case: an on-device model client served by a system daemon showed no Neural Engine footprint while the Neural Engine drew about 1 W. Its own CPU count advanced only tens of millijoules. A system service over XPC, a database server or a remote API are the same. Only the operator can say the server does none of that. **Fixes to the binary** - **Notifications.** It waited for a reply to every line, so a real server's `notifications/initialized` hung it. Notifications are now sent with no wait. - **Unsolicited server lines.** It took the server's first line as the reply. The server's stdout is now read on its own thread, responses are matched by id, and anything else (progress notifications, a sampling request) goes straight to the client. A call whose returned line is not its own response is sealed `Partial` with `reply-not-the-response`. - **Gated calls with no id.** A `tools/call`, `resources/read` or `prompts/get` sent without an `id` is now refused before it reaches the server, with nothing sent back. The attempt is sealed on a frame whose action, `notification:<tool>`, no grant carries. **Spec.** `jcp/SPEC.md` §5.1 rung 3 now covers metering another process tree: its domain, the settle rule (MUST), every gap that makes a figure `Partial`, and that `Whole` MUST NOT be sealed without the operator's declaration. `jcp/README.md` and `sandbox/README.md` are updated to match. ## Evidence - **Probes on an M5 Max, macOS 27.0.1, unprivileged.** These measured the fold lag, how a reaped descendant's energy is lost, that GPU time is lost about 2 ms after exit, and the Neural Engine footprint signal and its blind spot for daemon-side work. The footprint signal was confirmed against `powermetrics` and Core ML's compute plan. - **Oracle tests.** Every tree reading equals an independent oracle, a raw `proc_pid_rusage` read sharing no code with the meter, to the nanojoule (sandbox-meter) and to the µJ rounded up (gateway). The servers range from a bare echo to tens of millijoules, and the tests ran at load average 150–190. - Partial cases tested on real processes: a shell that reaps a worker per call; a forking server whose worker is reaped during the stop walk; a Metal compute server with persistent and transient command queues; a listing denied by `sandbox-exec`; a server sending notifications and requests mid-call. - **Adversarial review.** Five lenses (soundness, races/FFI, integration, tests/CI, docs) found 14 candidate defects, and three skeptics checked each one. 12 were confirmed and fixed, each with a test that fails when the fix is reverted. The worst: a worker born in the call and reaped during the stop walk vanished without trace, so the call read `Whole`. It reproduced by round trip 2 of 40 before the fix, and read `Partial` in 240 of 240 round trips after it. - **Suites.** `cargo test -p sandbox-meter` and `cargo test -p jcp-gateway` are green at load average ~187. Linux cross-checks are clean, and clippy reports nothing new. - **CI.** The macOS energy job gains a `jcp-gateway (upstream process tree)` step. The sandbox-meter step now also greps `tree meter:`. Each step fails unless its platform-gated tests printed their line. ## Not covered - **Neural Engine on a real process.** No test makes `ri_lifetime_max_neural_footprint` nonzero on a real process: building a Core ML model needs tooling the runner does not have. That gap is covered by unit tests and by today's probe. - **Metal tests in the runner context.** They build a Metal compute server with `/usr/bin/cc` at test time. They passed in a user session but have not yet run under the macOS runner's launchd context; this PR's CI is their first run there. - **Linux.** Unchanged. It has no per-process energy count, so the gateway keeps the machine meter there. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dcharlot added 19 commits 2026-10-09 10:51:22 -04:00

sandbox-meter: meter the CPU energy of another live process tree ... e2b4337126

jcp-gateway meters each relayed MCP call with PowerMeter::detect(), which
is machine-wide, and on macOS 27 every unprivileged machine-wide CPU rail
is frozen, so every call is sealed as an estimate. The kernel's
per-process CPU energy count (proc_pid_rusage RUSAGE_INFO_V6
ri_energy_nj) is readable, live, for any process of this user, so the
upstream server and its descendants can be read directly.

TreeMeter walks the tree from a root pid (proc_listchildpids, which
returns a count and truncates silently, grown and retried), reads each
member twice around its run state, and applies a pure rule over the start
and stop snapshots. Every way the figure is seen to fall short is a gap:
a descendant reaped in the span (its energy is in no counter), a member
gone, or older than the span and missed at its start, a member exited in
the span (its GPU time is lost ~2 ms after exit), GPU time spent by the
tree or a GPU client lost, a member that ever held in-process Neural
Engine model memory (lifetime maximum, which nothing can reset), a member
unreadable or still running at an end. The root gone or unreadable, or a
zero advance, is no reading at all.

Settling uses the kernel's run state, not CPU time: read from another
process, a spinning thread's CPU time moved only in whole 10 ms quanta,
the same folds as its energy, so a "CPU unchanged over 500 us" rule read a
child that kept computing after its reply as settled and stale in 60 of
60 runs. Zero running threads (pti_numrunning) between two reads that
agree was settled and exact in 58 of 58. A zombie child reaped in the
span moves its reaper's reaped-descendant time by exactly its own and its
reaped CPU time (5 of 5 to the tick), so such a reap is no gap.

The GPU half ports jouleclaw-energy's I/O Registry client reader, telling
a client with no AppUsage apart from a zero time, and shares ioreport's
CoreFoundation declarations. Usage moves into tree.rs, built everywhere;
read_usage returns the errno so EPERM (another user) and ESRCH (gone) are
told apart; the rusage layout test pins every field read.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

sandbox-meter: test the tree meter against an oracle on real process trees ... 8f15c1b67c

tests/tree_energy.rs spawns servers of its own and meters request/response
round trips with a TreeMeter. The oracle shares no code with the meter:
the tree from ps, each member's proc_pid_rusage read into a raw buffer at
the SDK's offsets, read once the oracle has seen every member off-core at
two reads 20 ms apart whose energy agrees. A server waiting for its next
request does not move its count, so a reading must equal the oracle's
advance to the nanojoule: a single awk from a bare echo (~10-26 uJ) to
~10 ms of CPU; a shell and its awk worker; a request that starts a child
and a grandchild (counted whole); a reply followed by a few milliseconds
of work, read right after the reply at both ends (a stale stop reads
less, a stale start more); a perl parent reaping a child that had exited
before the span (no gap). A shell that forks and reaps a worker per
request carries exactly one gap, ReapedDescendant, with the worker's CPU
time to the nanosecond. 152 readings over 8 runs on a host at load ~150
matched the oracle exactly.

The first born-in-span design (awk replying, then starting a sleep via
system()) read 1.05 mJ short of a later oracle while every member was
off-core: settling makes a count exact at its instant, not the tree's
work finished. The module docs now say so, and the test's tree finishes
its work before its reply.

The tree module is public so its docs (what a reading covers) render.
CI's macOS energy step now also requires the tests' "tree meter:" line,
the proof that these platform-gated tests ran.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

jcp-gateway: meter each gated call on the upstream server's own process tree ... 62bd7b36dd

The gateway metered every relayed call with PowerMeter::detect(), which is
machine-wide; on macOS 27 every unprivileged machine-wide CPU rail is
frozen, so every call was sealed as an estimate, and where a rail is live
the figure is the machine's, not the server's. sandbox-meter's TreeMeter
reads the kernel's per-process CPU energy count for every process of the
upstream server's tree, so the call can be read on the work's own process.

Upstream gains pid() (default None: the mocks, and any upstream with no
local process). The gateway builds a TreeMeter for that pid on the first
gated call, or at startup through call_meter(), and again only when the
upstream names another pid: the meter pins the root's identity, so a pid
that comes to name another process reads as gone, never as the server.
The tree span encloses the machine span, so the machine fallback's figure
(an estimate's wall time included) stays the call's alone.

Grading: a tree reading with no gap is HwShunt/Whole only when the
operator has declared the server self-contained (no work handed to a
process outside its tree), which no reader can see; any other reading is
HwShunt/Partial and is debited all the same; a span with no reading falls
back to the machine meter exactly as before. The plaintext _meta adds
energy_domain and, for a Partial tree figure, energy_partial_because (the
gap kinds, and not-declared-self-contained); the sealed receipt format is
unchanged, and the plaintext provenance and coverage still equal the
sealed ones. The binary takes --upstream-self-contained and its startup
line names the meter that applies.

Unit tests drive every reading shape through the pure grading and through
the whole relay path with a canned tree meter, sealing included.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

jcp-gateway: test tree-metered calls against an oracle on real servers ... ba523f293b

tests/upstream_tree.rs relays tools/call through Gateway::relay to real
MCP-ish servers it spawns: awk answering each JSON-RPC line itself, and a
shell answering each with an awk worker it forks and reaps before it
replies. The oracle shares no code with the meter or the gateway: the
server's proc_pid_rusage into a raw buffer at the SDK's offsets (energy at
336, reaped-descendant time at 96 and 104), read before and after each
relay once the server is quiet by pti_numrunning at byte 88 of a raw
PROC_PIDTASKINFO buffer. A server blocked on its next request does not
move its count, so each call's figure must be the oracle's advance rounded
down to the µJ, and it was: 99 of 99 readings over 9 runs at load ~150.

A declared single-process server is sealed HwShunt and whole; the same
server undeclared is HwShunt/Partial with not-declared-self-contained; the
reaping shell is HwShunt/Partial with reaped-descendant even when
declared, its figure the shell's own advance; an upstream naming a pid
this process may not read (launchd) is metered machine-wide. Each call's
plaintext grade equals its sealed one, and each receipt log verifies.

The jcp-rs matrix entry runs on Linux, where no tree meter exists, so the
macos-energy-backend job gains a jcp-gateway step that fails unless the
test printed its `upstream tree:` line. libc is a dev-dependency for the
oracle.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

jcp: specify metering a call on another process tree, and when it is whole ... 5c743e8900

SPEC §5.1 rung 3 covered only the metering process's own threads. It now
also covers the same per-process count read for every process of another
tree the meter can read, the process the work runs in: its domain (the
advance of members present at both ends plus the whole count of members
born in the span, not DRAM), that each end MUST be read with no thread of
a member on a core or queued, and every seen shortfall that makes the
figure Partial (a descendant reaped or a member exited in the span, a
member gone or older than the span and unread at its start, a member
unreadable, unlisted or still running, GPU time, in-process Neural Engine
memory). An empty list is not enough for Whole: an implementation MUST NOT
grade it Whole without the operator's declaration that the process hands
no work outside its tree, because no reader of the tree can see that.

The jcp README's jcp-gateway paragraph, the gateway's crate description,
the sandbox README and sandbox-meter's crate and probe docs say the same
of the tree meter and of the gateway's --upstream-self-contained.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

jcp-gateway: send notifications without waiting for a reply ... df1161418d

The binary's ChildServer::call writes a line and then blocks reading a
reply, and relay forwarded a client notification with up.call(line). An MCP
server answers no notification, and every client sends
notifications/initialized right after initialize, so the binary hung on the
first one and never read another line. A client's response to a request the
server made (a line with no method) is answered with nothing too.

Upstream gains notify(), which sends a line and waits for nothing; its
default goes through call() so in-process upstreams keep working, and
ChildServer overrides it to write and flush only. relay sends both kinds of
line with it. A unit test uses an upstream whose call() panics, and a new
integration test runs the real binary in front of an awk server that
answers only lines carrying an id: initialize, notifications/initialized,
then calls, each answered.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

sandbox-meter, jcp-gateway: round a tree reading up to a whole microjoule ... ec22ef9051

The tree figure was the meter's nanojoules floored to microjoules, so a
reading of 1 to 999 nJ sealed "HwShunt 0 µJ" and debited nothing: a
measured call presented as free. A budget's enforcement point never debits
less than was read. TreeReading::cpu_uj is now cpu_nj rounded up, and the
gateway seals and debits cpu_nj.div_ceil(1000) itself, whatever µJ figure a
reading carries; the error stays under one unit of the receipt's
resolution, always over. The integration tests' oracle equality is now
cost_uj == oracle_nj.div_ceil(1000), and new unit tests pin 1, 999, 1000
and 1001 nJ at both layers.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

jcp-gateway: keep Gateway Send ... 79baf40972

The boxed upstream tree meter was a bare Box<dyn TreeSpan>, which carries
no auto traits, so Gateway stopped being Send: an embedder that moves a
gateway to a thread, or holds it across an await on a multithreaded
executor, no longer compiled. TreeMeter is plain data, so the bound costs
nothing. TreeSpan now requires Send, and a compile-time assertion that
Gateway is Send fails the build if a field takes it away again.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

jcp-gateway: meter a call on the tree of the pid the upstream names now ... 00a0e52964

prepare_upstream_meter(None) keeps the meter built for an earlier pid, and
relay then used that meter without comparing it with up.pid(). So once a
tree meter existed for pid P, every call to an upstream that named no
process was read on P's tree and sealed HwShunt, "upstream-process-tree",
for a process the upstream no longer claimed, while call_meter() reported
the machine meter and the Upstream::pid contract promised machine-wide.

relay and call_meter now choose the meter with one function, tree_for(),
which returns the meter only when it was built for the pid named now. A
relay-level test switches pid() to None and back and checks energy_domain
on each call.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

sandbox-meter: read a failed child listing as a failure, not as childless ... 58a25c67a7

children() took a negative count as the only failure, but libproc's
proc_listchildpids returns 0, not -1, when the listing fails, leaving errno
set. A denied listing therefore read exactly like a childless process: the
walk recorded no Unlisted gap, so TreeGap::Unlisted could never fire, and a
tree whose listing was denied read as its root alone, whole. Measured under
sandbox-exec with (deny process-info-listpids): every listing 0 with EPERM,
while each process's usage stayed readable; a missing or childless pid
returns 0 with errno 0.

errno is now cleared before the call and a count of 0 with errno set is an
error. The test runs this test binary again under that sandbox and meters
a perl root relaying to an awk worker: each reading names the root alone,
is not whole, and carries Unlisted (EPERM) for the root at both ends.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

sandbox-meter, jcp-gateway: confirm each end's walk with a second one ... 771933602a

A walk reads a parent, then lists and reads its children. A descendant
born in the span that exits and is reaped by its parent between the two
was in the stop walk neither as a member (gone by its listing, or ESRCH at
its read, dropped silently) nor in the parent's reaped-descendant time
(read before the reap); the parent, blocked in wait, read as settled, so
the reading had no gap and a declared server's call was sealed HwShunt,
Whole while holding a small fraction of its CPU energy. Reproduced here
with a perl server whose worker writes the reply itself and is reaped
after it, 60 idle children beside it: whole without the worker by the
second of 40 round trips in each of 5 runs.

A walk is now accepted only when every member is settled and it agrees
with the walk before it on the tree's shape: the same processes (pid and
start time), parents, reaped-descendant and exit times, unreadable and
unlisted members, and no listed child gone by its read (a new vanished
flag). None of these returns to a value it left, so a reap between two
agreeing walks is impossible, and the next agreeing walk holds the reap,
which the reading then names. A tree still changing when the bound runs
out is a new gap, TreeGap::Changing, sent as "tree-changing". This also
makes the zombie-at-start credit sound: a start zombie absent from a
confirmed stop walk was reaped before it, and its reaper's read holds it.

Tests: pure tests of the agreement and of the new gap; a real-process
meter test with that server (40 round trips, never whole, each naming the
worker as Exited or the server's ReapedDescendant); and a gateway test
with a declared server of the same shape, never sealed whole. SPEC 5.1
requires the confirming walk and lists the new gap.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

sandbox-meter: test the settle loop on given walks ... db4048e42f

The loop that accepts a walk only once the next one agrees lived inside
the macOS-only sys module, so only real processes exercised it, and the
reap-race test mostly hits the vanished-child half of the rule (a child
listed and gone by its read), not the half where the child is reaped
before it is even listed. The loop is now settle(), over any source of
walks, and sys::settled_walk feeds it real walks. Pure tests drive it: a
quiet walk that missed a reap is not accepted until the next walk reads
the reap and the one after confirms it; a walk that saw a child vanish
confirms nothing; a member still running is waited out; and a tree that
keeps changing is returned unconfirmed at the bound, after two walks even
with no bound.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

sandbox-meter, jcp-gateway: a GPU client whose time did not move is unknown use ... 3fdbd6d0d0

The reading took an unchanged GPU client time as proof the tree used no
GPU. A client's AppUsage holds one entry per live command queue, and a
released queue's entry leaves with its time: a request on a command queue
created and released inside the span (5.2 ms of GPU work by its command
buffer's own timestamps) moved its client's time by 0, so gpu_spent
returned (0, []) and a declared Metal server's call was sealed HwShunt,
Whole with its GPU energy unmeasured.

gpu_spent now reports, besides the recorded time (a lower bound, carried
as Gpu), every tree pid that holds a GPU client at either end and recorded
no GPU time over the span as GpuUnknown, as well as one whose client was
lost: only a tree with no GPU client reads whole. The docs in tree.rs,
gpu_clients.rs, the gateway, SPEC 5.1 and both READMEs say so.

The GPU half had no real-process test, so a blinded reader (a misspelt
time key reads every client as 0) passed every suite. A Metal compute
server, built at test time with the system C compiler, now backs a meter
test (persistent-queue work must read as Gpu time > 0; transient-queue
and CPU-only requests must carry a GPU gap for the server; none whole)
and a gateway test (a declared Metal server is sealed Partial with "gpu"
or "gpu-unknown" on every call). The registry test also requires some
client to have recorded GPU time.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

jcp-gateway: end a call at its own response, and relay what comes before it ... fb91899026

ChildServer::call returned the first line the server wrote. During a
tools/call an MCP server may first send notifications (progress, log
messages) or requests of its own (sampling); the gateway took that line as
the reply, so the tree span stopped before the call's work, the stop walk
found the server blocked and settled, and a declared server's call was
sealed HwShunt, Whole holding a sliver of it. The real response then
answered the next call, sealed Whole with the previous call's work and
debited from that call's grant, possibly another tool's.

The binary now reads the server's stdout on a thread and routes each
line: a response (an id and no method) to the call waiting for it,
everything else straight to the client. A call returns the response
carrying its request's id and hands any other response to the client.
The client's stdin is read on a thread too, so a client's answer to a
server's mid-call request reaches the server while the call is open
instead of deadlocking behind it.

As a defence for any Upstream, relay grades a figure Partial, tree or
machine, with "reply-not-the-response" in energy_partial_because, unless
the returned line is the JSON-RPC response with the call's id and a result
or an error. A unit test covers each kind of wrong line; a binary test runs
the real gateway in front of an awk server that sends a progress
notification and a sampling request inside each call and waits for the
client's answer.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

sandbox-meter, jcp-gateway: say which way a gap errs, and where deferred work lands ... fb68d61090

SPEC 5.1, the sandbox README and the TreeGap and TreeReading.gaps docs
called every gap a part of the tree's energy the figure does not hold, and
5.2 reads Partial as "remainder unmeasured", a lower bound. But a member
still running at the START was read stale-low, so its advance includes up
to a quantum per running thread spent just before the span: the one gap by
which the figure can exceed the span's energy, sealed Partial and debited.
The docs now say so, and the wire names the end: energy_partial_because
carries "unsettled-at-start" or "unsettled-at-stop" instead of one
"unsettled", so a client can tell a possible over-count from a shortfall.
The figure is still counted either way: a budget's enforcement point does
not drop a member's whole advance, which would under-debit.

The tree docs also said a server's work after the stop "belongs to no
span" and the gateway's Phase 2 comment that the span stops "when the work
it meters is done". Back-to-back spans read all the tree spends inside
them: work a server defers past one reply, or does on a timer, lands in
the next call's span, and a server waiting on a timer reads as settled at
its start. The tree module docs, the gateway docs and SPEC 5.1 now say
that a whole reading means nothing was seen missing from the tree's energy
over the span, not that all of it was the span's own work.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

sandbox-meter, jcp-gateway: say what an exited member's record lacks, and what a delegating client reads ... 746a6b606a

SPEC 5.1, TreeGap::Exited (doc and Display) and the settling paragraph
said an exited member's count is final and counted, with only its GPU time
unknown, and that settling makes each member's count exact. A zombie's
record holds its complete CPU time but not the energy of its last time on
a core, which is folded only when a thread leaves a core and never for an
exiting thread: measured, a child that ran 3.3 ms of CPU and exited at
once left 0 to 0.32 mJ, some exactly 0 nJ, against about 1.5 mJ per CPU-ms
for the same work in a process that blocks first. The figure was already
Partial for it; the stated reason now says the energy is short too.

The tree module docs and Gateway::declare_upstream_self_contained said a
client whose model inference ran in a system daemon "read zero on every
unprivileged counter". Its Neural Engine footprint reads zero, but its own
CPU count, the one the tree meter sums, advanced tens of millijoules per
request: the failure the declaration guards against is a plausible
nonzero figure, not a zero. Both now say what was measured.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

sandbox-meter: compare a walk's shape piece by piece ... b78c6299a4

Clippy flagged the one-tuple shape in Snapshot::agrees_with as too
complex a type. The members, the unreadable and the unlisted lists are
now compared one after the other; the rule is unchanged.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

sandbox: say the tree meter confirms each end with a second walk ... 451987e1cb

The README described each end as read once no thread is on a core; it is
also accepted only when a second walk finds the same processes, parents,
reaped and exit times, which is what keeps a child reaped mid-walk from
vanishing without a gap.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

jcp-gateway: refuse a gated call sent as a notification, unsent and sealed ... 08be85834d

A tools/call, resources/read or prompts/get with no `id` is a JSON-RPC
notification: its result and its receipt could reach no one, and no reply
bounds the span it would be metered over. The binary now matches replies by
id, so such a call waited forever. It is refused before anything else and
never reaches the server, nothing is sent back, and the attempt is sealed
as a denial on a frame whose action is `notification:<tool>`, which no
grant carries. The ungranted-tool trick (decide against another tool's
grant) would have ALLOWED a granted tool's frame, so it is not used here.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

dcharlot merged commit 03ca161a91 into main 2026-10-09 13:59:30 -04:00

dcharlot referenced this pull request from a commit 2026-10-09 13:59:30 -04:00

Merge pull request 'jcp-gateway: meter each call on the upstream server's own process tree' (#198) from feat/gateway-upstream-energy into main

dcharlot referenced this pull request 2026-10-10 23:19:29 -04:00

sandbox-meter + jcp-gateway: count, and flag, work services did on the tree's behalf #214

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Transaction-Science/open-standards!198

No description provided.