Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,18 @@ Version source: `kennel.toml`; CLI and `kujo.toml` must agree. Historical releas
entries are retained below. Experimental contract versions are independent of
Dispatch's version.

## Unreleased — explicit graph attempt accounting

- Add opt-in durable reservations, permanent dispatch consumption and explicit safe
release under existing graph/child locks, with event-derived accounting reports.
- Permit an explicitly authorized second child run for the same logical node only
after a sealed Dispatch pre-admission refusal, binding original inputs and lineage.
Consumed or uncertain work cannot use retry budget as replay permission.
- Bind graph finalization and retained-host repair to exact accounting history;
branch/group control events and Eval/human instances remain separate units.
- Add input-binding/v1alpha4 commitments without changing historical vectors or
participant/result bytes. See `docs/contracts/graph-attempts/` for proof boundaries.

## Unreleased — bounded parent finalization

- Bind existing Workcell preservation `$ref` evidence through an additive exact-byte
Expand Down
87 changes: 87 additions & 0 deletions docs/audits/graph-attempt-accounting.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
# Explicit graph attempt accounting proof

Experimental retained trusted-host scope. Dispatch extends its existing static DAG,
run lock, journal, node admission, parent finalization and mechanical reconciliation.
The objective crosswalk is [requirements](../contracts/graph-attempts/requirements.md).
Exact gate results, source pins, commands, hashes, warnings and skips are in
[validation](../evidence/graph-attempt-accounting/validation.json). No partial or
interrupted run counts as a complete canonical pass.

## Verified result (2026-10-01)

The complete Dispatch release gate passed at source
`119de2e6f800e1cbceadcb01dec153c2e9394d19`: 106 suite groups, all 101 native
shard assertions, 55 new accounting checks, four new commitment vectors and 3/3
bounded release workloads. The independent Go/TypeScript/Python comparison reports
152 checks, five MCP checks and nine malformed-input checks; Kujo verifies all four
new vectors. No canonical suite is skipped. The pre-implementation baseline passed
252 focused checks. Both canonical failures and the environmental interruption are
retained rather than counted as successful runs.

Kujo documentation commit `2946f2a1a76700519292db3da8004ea1a9e31f61` passed format,
locked release build and 13 architecture/README/workflow contract tests. Two existing
artifact-dependent workflow tests remain explicitly ignored; vendor tiny_http emits
two existing warnings. No related repository was modified by this work. Kujo main
advanced independently during validation; the tested documentation branch retains its
original main base, with no claim that unrelated newer runtime changes were tested.

## Model

A logical node stays fixed while its explicitly declared child execution run changes.
A held reservation consumes availability; a durable graph dispatch permanently
consumes a program-dispatch unit. Node admission and effect admission remain separate.
Loss of delivery, reply or certainty does not refund dispatch. The current view is
journal-derived, not an independently mutable counter.

Release requires graph then child lock and exact proof of no dispatch, claim,
execution, refusal or uncertainty. A released reservation remains historical; its
surviving input binding grants no admission. Retry requires a sealed Dispatch-owned
resource-preflight refusal before node admission. An operator explicitly authorizes
a new child run, exact original logical inputs and lineage. The old child stays
sealed; the new child independently crosses execution, effects, Eval and finalization.
A descendant reservation or immutable child binding blocks retiring its source.

Only program dispatches use this unit. Inactive branches, branch activation and group
terminal receipts add none. Group members count once. Human decision and Eval instances
remain separate report categories. No price, token or elapsed-time measurement is
invented. The static graph ceiling and node ceiling remain anchored.

## Proof and limits

The integration chain is A → pre-admission refusal B1 → independently completed B2 → C.
The tests retain B1, validate actual typed downstream input, deny a third attempt,
reject changed artifacts and authority, and finalize all-complete work at zero
availability. Exhaustion with required work remaining blocks; it does not fabricate
failure or reclaim uncertain work.

Fresh-process races cover the last graph slot, release and retry/next-attempt creation.
Crash injection covers reservation before binding, binding before dispatch, durable
dispatch before delivery, child load before admission, consumed admission before work,
real SQLite mutation with lost reply, and immutable terminal/index publication gaps.
Retained-host repair reconstructs exact reserve/release/retry/refusal/terminal lineage
without execution, refund, missing event invention or graph finalization.

Portable additions are input-binding/v1alpha4 and program-attempt terminal/v1alpha2.
Four independent language implementations check the new commitments. Historical
schemas, alpha/beta commitments, execution-result/v1 and participant bytes stay intact.
Development failures and fixes are retained, including the wrong AJV draft validator.
A host restart interrupted a subsequent canonical run; its surviving evidence and
loss of temporary originals are explicit, and a complete rerun is required. The
post-restart run also exposed an assumption that historical observation-only journals
carried workflow definitions. Opt-in accounting now preserves their absence while
rejecting accounting events or unexplained ledger rows; the real effect-set crash
and renewal suite and three additional contract assertions verify the correction.

## Ownership and next phase

Dispatch owns accounting authority; Workcell supplies environment facts; Eval supplies
judgment facts; RunLedger reports; Watchdog observes. No unrelated repository change
or duplicate audit system is needed. The operator report is informational, not an
execution or retry ticket.

Next major phase: sourced resource and Eval measurement with bounded reservation
planning, evaluator budgets and fan-out quotas. Establish trustworthy units before
cost/time policy. General retries, automatic redelivery, ceiling extension, arbitrary
loops, dynamic topology, distributed scheduling, remote trust, machine-loss recovery,
mixed profiles, compensation, exactly-once, universal rollback, public/stable SDKs
and new language syntax remain outside scope.
81 changes: 81 additions & 0 deletions docs/contracts/graph-attempts/accounting.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
# Explicit attempts and reservations (implementation contract)

This is the opt-in implementation contract. The validation record distinguishes
focused proofs from the complete release gate. Existing static-policy runs retain
their original bytes and dispatch behavior.

## Authority and units

The anchored graph definition declares a maximum number of program dispatches.
Each program has one or two predeclared execution run identities. A logical node
remains the same DAG step across those instances. The child action attempt and its
effect attempts remain independent identities; neither is a reusable graph slot.

A graph reservation holds one program-dispatch unit. `node_start_requested`
permanently consumes it before calling the installed host. Consumption describes
Dispatch's durable dispatch decision, not delivery, execution, mutation or success.
A lost callback reply cannot establish which of those later boundaries occurred.
The controller must not redeliver a consumed dispatch automatically.

Available units equal the immutable ceiling minus held reservations minus consumed
dispatches. Released reservations remain in history but no longer hold capacity.
Read-only assessments, denied stale requests, branch activation and group receipts
consume no program unit. Subgraph members count individually, once per dispatch.
Inactive branches reserve and consume nothing. Evaluation terminal instances and
human decision requests are reported separately; they are not program dispatches.
Unknown runtime, token or monetary measurements remain unknown.

## Mechanical transitions

Reservation, release and retry use the existing graph lock and source-bound control
journal. Operator candidates bind current revision, journal, source state, anchored
workflow and installed authority. Apply revalidates after acquiring the lock and
records the actor. It does not start execution. Ordinary DAG advancement may reserve
and dispatch an eligible first attempt under its existing authority.

Release requires the graph lock followed by the child lock. The child must still be
pending, have no admission claim or event, no execution/result, and no refusal or
terminal event. The graph must contain no dispatch for this reservation. A released
never-dispatched child may be reserved again; a dispatched child may never be refunded.

Retry requires a sealed, independently reloaded pre-admission refusal. The initial
closed refusal reason is an installed resource-availability preflight rejection.
The dispatcher records it before creating an admission claim or invoking work. An
exception, missing reply or ordinary failed execution is not such a refusal.
A refusal seals that child permanently. A new predeclared child obtains its own
binding and admission; the prior refusal and all consumed dispatch units remain.

The new child binds the exact logical inputs, predecessor terminals and policy
receipts used by the original attempt. Only consumer execution identity and explicit
retry lineage differ. A newer producer output cannot silently replace an old input.
No dependent dispatch/binding, activated branch or finalized group may already have
used the prior attempt's terminal decision. Retry cannot invalidate downstream truth.

## Outcome and recovery

An explicitly retryable failure with remaining attempt allowance remains blocked for
an operator choice. Budget availability supplies no effect-safety evidence. Exhausted
node allowance exposes the failure to existing outcome policy. Required unfinished
work at a graph ceiling remains blocked. Already consumed work may still complete,
and a graph with all required terminal facts may finalize with zero available units.
Held reservations prevent sealing the graph, including reservations for optional work.

Graph finalization binds the exact accounting projection. Recovery folds durable
reservation, release, retry, dispatch and terminal events, validates their identities,
and compares the derived view. It does not infer missing dispatches, erase old
attempts, refund consumed units, decide retry safety or invent graph finalization.

## Remaining boundaries

Only retained trusted-host authority is covered. Ceiling extensions, post-admission
retries, evaluator retries, monetary/token accounting, elapsed-time enforcement,
dynamic topology, distributed workers, remote authentication, machine-loss recovery,
mixed profiles, compensation, exactly-once effects and universal rollback remain
outside this contract. RunLedger and Watchdog may report these facts; neither owns
a reservation, refund, retry or admission decision.

The graph terminal decision references the exact internal ledger by SHA-256 over its
retained JSON bytes. The ledger is not serialized as one portable participant
commitment: a multi-node history legitimately exceeds that codec's 8 KiB bound.
The bound and all historical portable encodings remain unchanged. Only the compact
input-binding/v1alpha4 addition crosses the existing portable codec boundary.
40 changes: 40 additions & 0 deletions docs/contracts/graph-attempts/crash-matrix.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Retained-host attempt accounting matrix

The executable cases live in `tests/graph_attempt_recovery.mjs` and
`tests/graph_attempt_authority.mjs`. Controllers are fresh Kujo processes. Crash
cases terminate at actual publication/admission boundaries with SIGKILL; the orphan
cases interrupt the immutable-record/index boundary in an installed source copy.
The final validation record identifies the tested source and gate outcomes.

| Boundary | Surviving durable fact | Fresh-controller action | Prohibited inference/action |
| --- | --- | --- | --- |
| Reservation before input binding | Held reservation; no dispatch, claim or work | Operator may release under graph/child locks | Invent execution or a consumed attempt |
| Binding before dispatch | Held reservation and exact child binding | Operator may release; direct child start rejects | Treat binding as admission |
| Dispatch before child loads | Permanently consumed dispatch | Report delivery/admission as unproven | Redeliver, refund or retry from silence |
| Child loads before admission | Same consumed dispatch and child identity | Reload and preserve uncertainty | Create another attempt because no reply arrived |
| Admission before work | Permanent child claim/admission, no work result | Preserve consumed identity; require evidence/review | Clear claim or release capacity |
| SQLite mutation before reply | Consumed node/effect admission and real sink row | Independent sink verification may resolve effect fact | Replay or refund the mutation |
| Terminal fact, derived graph view stale | Exact immutable terminal observation | Mechanical retained-host repair reconstructs accounting | Invent graph finalization or erase consumption |
| Reservation immutable record, index missing | Source-bound orphan reservation | Exact reconciliation appends missing index/projection | Pick an unrelated child or run it |
| Release immutable record, index missing | Source-bound orphan release | Exact reconciliation retains release history | Release any dispatched reservation |
| Retry immutable record, index missing | New declared child and prior-terminal lineage | Reconstruct reserved next attempt; do not run | Replace old refusal or reuse its identity |
| Child refusal immutable record, index missing | Exact dispatcher refusal before claim | Reconstruct sealed refusal | Admit the refused child |
| Child authority changes after reservation | Old held reservation and stale child revision | Reject dispatch/release under stale authority | Treat remaining units as current authority |
| Operator authority revoked during apply | Informational candidate only | Final revalidation rejects | Publish the stale candidate |

Contention uses the existing locks and revision checks. Two independently loaded
controllers compete for the last graph unit, release, and the same retry/next-child
creation. Exactly one transition may publish. A rejected candidate, duplicate delivery
or read-only assessment consumes no additional unit.

Successful node truth remains independent of graph policy. The safe retry chain
preserves B1's refusal and B2's own execution, effect admission, output, Eval and parent
finalization. A downstream C consumes B2's exact output. Branch activation consumes no
program unit; inactive repair work has no reservation. A group receipt adds no unit
on top of its member dispatches. Held optional work must be explicitly released before
cancellation and graph sealing.

The recovery matrix assumes retained trusted local storage and valid immutable
history. Missing/conflicting authority, corrupt records and uncertain effects cannot
be repaired by an accounting refund. General machine recovery, remote trust,
distributed coordination, compensation and exactly-once effects remain unsolved.
Loading
Loading