jcp §4.11: an orchestrator's spend died with its process, so a restart was a fresh budget #189

Merged

dcharlot merged 2 commits from feat/orchestrate-journal into main 2026-10-09 08:46:22 -04:00

Conversation 0 Commits 2 Files changed 6 +782 -11

dcharlot commented 2026-10-08 10:47:05 -04:00

Owner

Copy link

jcp-orchestrate's module doc claims:

The whole run is an ordered ledger of sealed decisions — the audit a bare
meta-harness has no way to produce.

That was true for as long as the process lived. Item states, the receipts, and —
the part that matters — each harness's spend were held in memory. Spend lives
in self.runtime, and a fresh Runtime starts at zero.

So a crash loop could spend a harness's joule budget over and over, and a
task already paid for and run would be dispatched again. An audit trail that
dies with the process is not an audit trail, and a ceiling that resets on restart
bounds one process lifetime rather than the work.

The journal

A run emits a JournalEntry for every transition through a Journal the caller
supplies. MemoryJournal is the default and keeps exactly the old behaviour; a
deployment that wants the run to survive its process writes the entries
somewhere that does. Orchestrator::replay rebuilds a run from them — items,
attempts, the receipt ledger, and the spend.

Spend is re-derived, not asserted

Each allowed dispatch goes back through Runtime::decide, so the budgets land
where the original run left them. Two reasons to replay rather than restore a
total:

• a replay cannot produce a spend the gate would not have produced;
• a stored total is one more figure that can be wrong or tampered with.

The grants reproduce exactly because register mints them with a fixed nonce, so
an identical registration yields identical grant ids. Runtime has no spend
setter and did not need one.

The test that matters is not that the number comes back — it is that the
resumed budget still binds. A harness with 1 000 µJ that has spent 900 must
refuse the next 300 µJ dispatch, and does.

The interrupted case is left unresolved on purpose

The dispatch is journalled before the harness runs, because the decision has
already debited the grant; recording it afterwards would lose the debit for
anything interrupted between the two.

That ordering leaves one state the record cannot resolve. A Dispatched with no
Settled means the process died while a harness held the task, and whether the
work happened is not knowable from the journal — only that harness knows. Such
an item resumes as WorkState::Interrupted { harness, attempt }, is counted
separately in the report, keeps its joules debited, and is not re-dispatched
(the loop only offers Pending items).

Retrying risks paying twice for work already done; discarding risks losing it.
Choosing between those without asking the harness is not a decision this crate
can make.

A journal naming an unregistered harness, or a dispatch for a task no Submitted
entry introduced, is refused rather than guessed — the grant the decision was
made against cannot be reproduced.

Spec

Numbered §4.11, not §4.10: six places in jcp-runtime already cite
"SPEC §4.10" for the flow/taint gate, and no such section exists — the gate is
implemented and its normative text was never written. I took §4.11 rather than
claim a number the code has already spoken for; writing §4.10 for the flow gate
is a separate piece of work.

§4.11 Durable spend: a restart is not a fresh budget (REQUIRED where a run can
restart) — the hole is in any enforcement point that can restart, not just this
crate. Record every allowed decision durably; re-establish the spend before
deciding anything new (replay RECOMMENDED over a stored total); record the
decision before the action; never silently retry an interrupted one, nor report
it as completed or failed, and keep its energy debited.

Verification

jcp-rs workspace 409 passed, clippy clean on jcp-orchestrate.

reverted	caught by
replay does not re-debit	4 tests — including the resumed budget admitting work it cannot pay for
an interrupted item resumes as Pending	a_dispatch_with_no_settlement_resumes_unresolved_and_is_not_re_run
the dispatch journalled after the harness runs	the_dispatch_is_journalled_before_the_harness_runs
an unregistered harness guessed instead of refused	a_journal_naming_something_unregistered_is_refused_not_guessed

The third of those initially had no test: my first falsification of it only
failed to compile, which is not a pass. The ordering is only observable by
crashing between the decision and the harness run, so there is now a test that
does exactly that — a harness that panics where a process would — and asserts
the debited decision is on the record with no settlement after it.

Merge order with the sibling PR

#190 adds §4.10 (the flow gate) and this one adds §4.11. They conflict with
each other, though each merges cleanly against main: both insert a new §4.x at
the same anchor, after §4.9 and before §5. Nothing else overlaps —
jcp-orchestrate and jcp-runtime are disjoint, and neither references the
other's symbols.

Merge #190 first. Then rebase this one; the resolution is to keep both
sections in numeric order, which is also the order they must read in: §4.10
Flow, §4.11 Durable spend. I checked the landing by merging the whole set onto
main in a scratch branch — the sequence comes out §4.9, §4.10, §4.11, §5, and
afterwards §4.10 has 13 code references against 1 spec section and §4.11 has 0
against 1.

(A git merge-tree between the two branches reported no conflict and I believed
it; a real merge disagrees. The textual check was wrong, not the branches.)

Its only consumer would have mishandled the new state

jouledesk has a path dependency on jcp-orchestrate and matches on
WorkState. Adding Interrupted did not break the build — the match has a
catch-all — so an interrupted task fell through and came out
TagOutcome::Failed("no terminal state"). Then the next branch sealed it:

// a `Failed` is spend that bought no result (waste)
if matches!(outcome, TagOutcome::Done | TagOutcome::Failed(_)) {

A task whose work may well have completed, whose joules were debited, and whose
outcome nobody knows, would have been reported to a person as failed and
sealed in an efficiency/1 receipt as waste — exactly what §4.11, written in
this same PR, forbids. No compiler could catch it, and nor could CI: the
catch-all made it compile and the jouledesk-rs job would have passed.

TagOutcome::Interrupted { harness } now names it, carrying who can settle it.
The sealing branch excludes it alongside Denied — a denied tag ran nothing, an
interrupted one may have run everything. Five consumers updated; four were
exhaustive matches the compiler found, including jouledesk-github's seal.

Falsifying it caught my own test being worthless

The first version asserted !matches!(interrupted, Done | Failed(_)) — a
property of the enum, not of the code — so changing the sealing branch, or
deleting the match arm entirely, left it green.

The obstacle was real: Interrupted could not arise through Teammate's API,
since tag runs to a terminal state in one process. So the fix was to make it
reachable rather than assert around it. Teammate gains the minimum resume
surface over this PR's journal — with_journal, replay, outcome_of — which
is the composition the journal exists for. The mapping and the sealing rule are
now named functions used by the real code paths, so the test reads the rule
instead of restating it.

The test is end to end: tag once with a journal, truncate it after the dispatch
(the crash this models), replay into a fresh teammate, assert the tag reports
Interrupted { harness } and seals nothing. Both earlier falsifications now
fail it.

jouledesk-rs workspace: 40 passed, clippy clean.

🤖 Generated with Claude Code

`jcp-orchestrate`'s module doc claims: > The whole run is an ordered ledger of sealed decisions — the audit a bare > meta-harness has no way to produce. That was true for as long as the process lived. Item states, the receipts, and — the part that matters — each harness's **spend** were held in memory. Spend lives in `self.runtime`, and a fresh `Runtime` starts at zero. So a crash loop could spend a harness's joule budget **over and over**, and a task already paid for and run would be dispatched again. An audit trail that dies with the process is not an audit trail, and a ceiling that resets on restart bounds one process lifetime rather than the work. ## The journal A run emits a `JournalEntry` for every transition through a `Journal` the caller supplies. `MemoryJournal` is the default and keeps exactly the old behaviour; a deployment that wants the run to survive its process writes the entries somewhere that does. `Orchestrator::replay` rebuilds a run from them — items, attempts, the receipt ledger, and the spend. ### Spend is re-derived, not asserted Each allowed dispatch goes back through `Runtime::decide`, so the budgets land where the original run left them. Two reasons to replay rather than restore a total: - a replay **cannot produce a spend the gate would not have produced**; - a stored total is one more figure that can be wrong or tampered with. The grants reproduce exactly because `register` mints them with a fixed nonce, so an identical registration yields identical grant ids. `Runtime` has no spend setter and did not need one. **The test that matters is not that the number comes back — it is that the resumed budget still binds.** A harness with 1 000 µJ that has spent 900 must refuse the next 300 µJ dispatch, and does. ## The interrupted case is left unresolved on purpose The dispatch is journalled **before** the harness runs, because the decision has already debited the grant; recording it afterwards would lose the debit for anything interrupted between the two. That ordering leaves one state the record cannot resolve. A `Dispatched` with no `Settled` means the process died while a harness held the task, and **whether the work happened is not knowable from the journal** — only that harness knows. Such an item resumes as `WorkState::Interrupted { harness, attempt }`, is counted separately in the report, keeps its joules debited, and is **not** re-dispatched (the loop only offers `Pending` items). Retrying risks paying twice for work already done; discarding risks losing it. Choosing between those without asking the harness is not a decision this crate can make. A journal naming an unregistered harness, or a dispatch for a task no `Submitted` entry introduced, is refused rather than guessed — the grant the decision was made against cannot be reproduced. ## Spec Numbered **§4.11**, not §4.10: six places in `jcp-runtime` already cite "SPEC §4.10" for the flow/taint gate, and no such section exists — the gate is implemented and its normative text was never written. I took §4.11 rather than claim a number the code has already spoken for; writing §4.10 for the flow gate is a separate piece of work. **§4.11 Durable spend: a restart is not a fresh budget (REQUIRED where a run can restart)** — the hole is in any enforcement point that can restart, not just this crate. Record every allowed decision durably; re-establish the spend before deciding anything new (replay RECOMMENDED over a stored total); record the decision before the action; never silently retry an interrupted one, nor report it as completed or failed, and keep its energy debited. ## Verification `jcp-rs` workspace **409 passed**, clippy clean on `jcp-orchestrate`. | reverted | caught by | |---|---| | replay does not re-debit | **4 tests** — including the resumed budget admitting work it cannot pay for | | an interrupted item resumes as `Pending` | `a_dispatch_with_no_settlement_resumes_unresolved_and_is_not_re_run` | | the dispatch journalled *after* the harness runs | `the_dispatch_is_journalled_before_the_harness_runs` | | an unregistered harness guessed instead of refused | `a_journal_naming_something_unregistered_is_refused_not_guessed` | The third of those initially had **no test**: my first falsification of it only failed to compile, which is not a pass. The ordering is only observable by crashing *between* the decision and the harness run, so there is now a test that does exactly that — a harness that panics where a process would — and asserts the debited decision is on the record with no settlement after it. ## Merge order with the sibling PR **#190 adds §4.10 (the flow gate) and this one adds §4.11. They conflict with each other**, though each merges cleanly against main: both insert a new §4.x at the same anchor, after §4.9 and before §5. Nothing else overlaps — `jcp-orchestrate` and `jcp-runtime` are disjoint, and neither references the other's symbols. **Merge #190 first.** Then rebase this one; the resolution is to keep both sections in numeric order, which is also the order they must read in: §4.10 Flow, §4.11 Durable spend. I checked the landing by merging the whole set onto main in a scratch branch — the sequence comes out §4.9, §4.10, §4.11, §5, and afterwards §4.10 has 13 code references against 1 spec section and §4.11 has 0 against 1. (A `git merge-tree` between the two branches reported no conflict and I believed it; a real merge disagrees. The textual check was wrong, not the branches.) ## Its only consumer would have mishandled the new state `jouledesk` has a path dependency on `jcp-orchestrate` and matches on `WorkState`. Adding `Interrupted` did **not** break the build — the match has a catch-all — so an interrupted task fell through and came out `TagOutcome::Failed("no terminal state")`. Then the next branch sealed it: ```rust // a `Failed` is spend that bought no result (waste) if matches!(outcome, TagOutcome::Done | TagOutcome::Failed(_)) { ``` A task whose work may well have completed, whose joules were debited, and whose outcome nobody knows, would have been reported to a person as **failed** and sealed in an `efficiency/1` receipt as **waste** — exactly what §4.11, written in this same PR, forbids. No compiler could catch it, and nor could CI: the catch-all made it compile and the `jouledesk-rs` job would have passed. `TagOutcome::Interrupted { harness }` now names it, carrying who can settle it. The sealing branch excludes it alongside `Denied` — a denied tag ran nothing, an interrupted one may have run everything. Five consumers updated; four were exhaustive matches the compiler found, including `jouledesk-github`'s `seal`. ### Falsifying it caught my own test being worthless The first version asserted `!matches!(interrupted, Done | Failed(_))` — a property of the *enum*, not of the code — so changing the sealing branch, or deleting the match arm entirely, left it green. The obstacle was real: `Interrupted` could not arise through `Teammate`'s API, since `tag` runs to a terminal state in one process. So the fix was to make it **reachable** rather than assert around it. `Teammate` gains the minimum resume surface over this PR's journal — `with_journal`, `replay`, `outcome_of` — which is the composition the journal exists for. The mapping and the sealing rule are now named functions used by the real code paths, so the test reads the rule instead of restating it. The test is end to end: tag once with a journal, truncate it after the dispatch (the crash this models), replay into a fresh teammate, assert the tag reports `Interrupted { harness }` and seals nothing. Both earlier falsifications now fail it. `jouledesk-rs` workspace: 40 passed, clippy clean. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dcharlot added 1 commit 2026-10-08 10:47:05 -04:00

jcp §4.10: an orchestrator's spend died with its process, so a restart was a fresh budget ... e000df1fca

`jcp-orchestrate`'s module doc claims "the whole run is an ordered ledger of
sealed decisions — the audit a bare meta-harness has no way to produce." That
was true for as long as the process lived. Item states, the receipts, and — the
part that matters — each harness's spend were held in memory: spend lives in
`self.runtime`, and a fresh `Runtime` starts at zero. A crash loop could spend a
harness's joule budget over and over, and a task already paid for and run would
be dispatched again.

A run now emits a `JournalEntry` for every transition through a `Journal` the
caller supplies. `MemoryJournal` is the default and keeps exactly the old
behaviour; a deployment that wants the run to survive its process writes the
entries somewhere that does. `Orchestrator::replay` rebuilds a run from them:
items, attempts, the receipt ledger, and the spend.

**Spend is re-derived, not asserted.** Each allowed dispatch goes back through
`Runtime::decide`, so the budgets land where the original run left them. Two
reasons for replaying rather than restoring a total: a replay cannot produce a
spend the gate would not have produced, and a stored total is one more figure
that can be wrong. The grants reproduce exactly because `register` mints them
with a fixed nonce, so an identical registration yields identical grant ids.
`Runtime` has no spend setter and did not need one.

The test that matters is not that the number comes back: it is that the resumed
budget still **binds**. A harness with 1 000 µJ that has spent 900 must refuse
the next 300 µJ dispatch, and does.

**The interrupted case is left unresolved on purpose.** The dispatch is
journalled *before* the harness runs, because the decision has already debited
the grant and recording it afterwards would lose the debit for anything
interrupted between the two. So a `Dispatched` with no `Settled` means the
process died while a harness held the task, and whether the work happened is not
knowable from the journal — only that harness knows. Such an item resumes as
`WorkState::Interrupted { harness, attempt }`, is counted separately in the
report, keeps its joules debited, and is **not** re-dispatched: the loop only
offers `Pending` items. Retrying risks paying twice for work already done,
discarding risks losing it, and choosing between those without asking the
harness is not a decision this crate can make.

A journal naming an unregistered harness, or a dispatch for a task no
`Submitted` entry introduced, is refused rather than guessed — the grant the
decision was made against cannot be reproduced.

SPEC §4.10 makes it normative beyond this crate, since the hole is in any
enforcement point that can restart: record every allowed decision durably,
re-establish the spend before deciding anything new (replay RECOMMENDED over a
stored total), record the decision before the action, and never silently retry
or mis-report an interrupted one.

jcp-rs workspace: 409 passed, clippy clean on jcp-orchestrate.

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

dcharlot force-pushed feat/orchestrate-journal from e000df1fca to 59af9a6b6a 2026-10-08 10:59:42 -04:00 Compare

dcharlot referenced this pull request from a commit 2026-10-08 11:13:40 -04:00

jcp §4.10: the flow gate had no spec section, and six code references cited it

dcharlot referenced this pull request 2026-10-08 11:14:14 -04:00

jcp §4.10: the flow gate had no spec section, and six code references cited it #190

dcharlot changed title from jcp §4.10: an orchestrator's spend died with its process, so a restart was a fresh budget to jcp §4.11: an orchestrator's spend died with its process, so a restart was a fresh budget 2026-10-08 11:14:51 -04:00

dcharlot referenced this pull request from a commit 2026-10-08 11:40:25 -04:00

ci: a rebase ran every path-filtered workflow, because `paths:` matches the push delta

dcharlot referenced this pull request 2026-10-08 11:41:09 -04:00

ci: a rebase ran every path-filtered workflow, because paths: matches the push delta #191

dcharlot referenced this pull request from a commit 2026-10-09 02:47:46 -04:00

jouledesk: an interrupted tag is not a failed one, and is not sealed as waste

dcharlot added 1 commit 2026-10-09 02:47:46 -04:00

jouledesk: an interrupted tag is not a failed one, and is not sealed as waste ... 0c4b724f57

This completes #189 at its only consumer, and closes a hole that PR opened.

`jouledesk` has a path dependency on `jcp-orchestrate` and matches on
`WorkState`. Adding `WorkState::Interrupted` did not break the build — the match
has a catch-all — so an interrupted task fell through it and came out
`TagOutcome::Failed("no terminal state")`. Then the next branch sealed it:

    // a `Failed` is spend that bought no result (waste)
    if matches!(outcome, TagOutcome::Done | TagOutcome::Failed(_)) {

So a task whose work may well have completed, whose joules were debited, and
whose outcome nobody knows, would have been reported to a person as failed and
sealed in an `efficiency/1` receipt as waste. That is exactly what §4.11 — which
#189 writes — forbids: an implementation MUST NOT report such an action as
completed or as failed.

A compiler could not catch it, and nor could CI: the catch-all made it compile,
and the still-pending `jouledesk-rs` job would have passed.

`TagOutcome::Interrupted { harness }` now carries the harness that held the task,
because that is who can settle it. The sealing branch excludes it alongside
`Denied` — a denied tag ran nothing, an interrupted one may have run everything,
and sealing it either way states as fact something unknown. Its joules stay
debited on the grant regardless; the dispatch decision that incurred them is
sealed in the orchestrator's own ledger.

Five consumers updated. Four were exhaustive matches the compiler found,
including `jouledesk-github`'s `seal`, which now reports `interrupted (held by
<harness>)` rather than `failed`. Every surface renders it, so no binding tells a
different story about the same outcome.

**Falsifying it caught my own test being worthless.** The first version
asserted `!matches!(interrupted, Done | Failed(_))` — a property of the *enum*,
not of the code — so changing the sealing branch, or deleting the match arm
entirely, left it green. The same vacuousness I had just caught in #190.

The obstacle was real: `WorkState::Interrupted` could not arise through
`Teammate`'s API, because `tag` submits and runs to a terminal state in one
process. So the fix was to make it reachable rather than to assert around it.
`Teammate` gains the minimum resume surface over #189's journal —
`with_journal`, `replay`, and `outcome_of` — which is the composition that
journal exists for, and jouledesk's whole purpose is composing
`jcp-orchestrate`. The mapping and the sealing rule are now named functions
(`outcome_for`, `seals_efficiency`) used by the real code paths, so a test reads
the rule instead of restating it.

The test is now end to end: tag once with a journal, truncate it after the
dispatch — the crash this models — replay into a fresh teammate, and assert the
tag reports `Interrupted { harness }` and seals nothing. Both earlier
falsifications now fail it: sealing an interrupted tag as waste, and removing the
match arm so it falls back to the catch-all.

jouledesk-rs workspace: 40 passed, clippy clean.

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

dcharlot referenced this pull request from a commit 2026-10-09 02:51:14 -04:00

jouledesk: an interrupted tag is not a failed one, and is not sealed as waste

dcharlot force-pushed feat/orchestrate-journal from 0c4b724f57 to 2bfde7fb19 2026-10-09 02:51:14 -04:00 Compare

dcharlot merged commit 17b7559ad7 into main 2026-10-09 08:46:22 -04:00

dcharlot referenced this pull request from a commit 2026-10-09 08:46:24 -04:00

Merge pull request 'jcp §4.11: an orchestrator's spend died with its process, so a restart was a fresh budget' (#189) from feat/orchestrate-journal into main

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!189

No description provided.