Skip to content

feat(dispatch): route factory jobs to the cheapest good-enough lane with capacity - #178

Draft
kvnloo wants to merge 5 commits into
masterfrom
feat/dispatch-20261020
Draft

kvnloo wants to merge 5 commits into
masterfrom
feat/dispatch-20261020

Conversation

@kvnloo

@kvnloo kvnloo commented Oct 20, 2026

Copy link
Copy Markdown
Owner

What

z0int dispatch (src/z0int/dispatch.py, stdlib-only; docs in docs/dispatch.md): assigns typed factory jobs (kind scan|label|qa|review|test|code, size, required quality, privacy, deadline, avoid_family) to the cheapest lane that is good enough and has capacity now, from Kerdoios kerdoios.capacity.v1.

  • Shadow-price cost: under-burn subscription headroom first (its quota perishes at reset), free lanes on top, capped Nous priced out of bulk work, hard-throttled/avoided pools infeasible, a job waits for a busy lane rather than take one >0.6 dearer.
  • Hard rules: code only on opus/sol; privacy never above the provider's data policy; quality bar per job; QA never on the checked family.
  • SQLite ledger of every decision (alternatives + rejection reasons), outcome and batch (burn-pace + Nous snapshots). Learns quality per lane×kind (QA agreement outranks completion), Nous $/job from cap snapshots, and Opus window %/job net of the pool's background burn. Throttles are forwarded to Kerdoios.
  • plan (dry run), assign (slots now, runner ceilings), record, qa, batch, report.

Proof (real batch, 2026-10-20)

88 jobs via the OSS-factory kitchen runner: 34/40 repo re-scans done at 10:40Z (Opus, paced at ~14/h by hourly headroom; DeepSeek/GLM free were spent), 40/40 labels (Groq 20, NIM 11, MiniMax 7, Opus 2), 6 QA (Luna, $0.54). 12 throttle events, no storm. Claude 52%→57% (batch share ≈1%), Nous $152.63→$153.17. Report: workspace/zer0/data/operations/kitchen/scan-wave3/REPORT.md (private host path).

Tests

PYTHONPATH=src pytest tests/test_dispatch.py → 13 passed; CLI/posture/receipt/backend suites unaffected (114 passed).

Draft; do not merge without the owner.

…ith capacity

Adds z0int.dispatch (and `z0int dispatch`): a stdlib-only dispatcher that
takes typed jobs (kind, size, required quality, privacy, deadline) and
assigns lanes from Kerdoios capacity.

- Shadow-price cost: under-burn subscriptions inside their hourly headroom
  are filled first (their quota perishes at reset), free lanes add speed,
  the capped Nous plan is kept for checks, avoided/throttled pools are
  infeasible.
- Hard rules: code only on opus/sol, privacy never above the provider's data
  policy, quality bar per job, QA never on the family it checks.
- Ledger (SQLite) of every decision with alternatives and rejection reasons,
  every outcome, and burn-pace/Nous snapshots per batch. Quality priors and
  per-job subscription cost are learned from it; throttles are forwarded to
  Kerdoios so the lane cools down for every caller.
- plan (dry run over a horizon), assign (slots now, runner ceilings), record,
  qa, batch, report.
…ors teach nothing

A runner restart re-sent 'batch start' and replaced the burn-pace baseline,
which would hide the batch's real subscription spend. Outcomes marked
harness_error (a runner bug, not the model) are excluded from quality priors.
…spend

A read-only Opus repo scan costs about $0.32 API-equivalent, and Hermes
alone logged $520 of Claude usage this week at 52% used, so one scan is at
most 0.032% of the weekly window. The old 0.05% guess held Opus to about
nine scans an hour while the pool was under-burning.
…shots

Batch start/end snapshots of the Nous cap notice give dollars spent; divided
by the batch's finished haiku/luna jobs this replaces the per-job prior (the
first QA batch measured $0.09 per Luna QA against a $0.06 prior).
…ground burn

The proof batch's Claude window moved 52% -> 57% over 2.1 h while 36 Opus
jobs ran, but other sessions were already burning about 1.7-1.9 %/h. Batch
start now stores Kerdoios' recent burn rate per pool and the learner
subtracts it, which gives about 0.03% per scan instead of 0.14%.

kvnloo commented Oct 27, 2026

Copy link
Copy Markdown
Owner Author

N27-REV-Z0I-178

Reviewed exact head: 322932feb69e2f34dff420abd18680eb138607a2 (draft #178, target master; merge base 6cae99254bbb2f38329c081c15c2ce81c74a4be2). Read the complete four-file diff, all new files and the prior src/z0int/cli.py, AGENTS.md, README.md, and docs/ONBOARDING.md. No CONTRIBUTING.md exists at this head. There were no prior PR discussion comments. Source review only: tests NOT RUN - ChatGPT cannot execute code.

Acceptance criteria: The PR body does not explicitly link a numbered implementation issue. Assessment below uses its stated dispatch acceptance promises, plus the related capacity RFC #131 P1 / hard invariants as context, not as a claim that this PR implements the entire RFC.

Item Status Exact-head evidence
Typed jobs and z0int dispatch CLI / plan / assign / record / qa / batch / report MET (static) src/z0int/dispatch.py:85-108,578-651; src/z0int/cli.py:638-645,1172-1193; tests/test_dispatch.py:123-130.
Cheapest feasible lane, expiring subscription headroom, capped Nous cost, wait margin MET (algorithmic) src/z0int/dispatch.py:302-321,324-393,418-459; tests/test_dispatch.py:47-61,114-120. Measured economy / throughput remains UNTESTED by this review.
Code only to Opus/Sol; declared provider privacy and minimum numeric quality filters MET (static filtering) src/z0int/dispatch.py:44-66,334-345; tests/test_dispatch.py:64-87. Provider-policy truth and independently verified quality remain UNTESTED.
QA independent of the checked family NOT MET avoid_family is optional (src/z0int/dispatch.py:93,105-108), and rejection only occurs when supplied (:342-343). record_qa never validates verifier independence (:513-519). Test tests/test_dispatch.py:83-87 supplies a good value rather than testing missing/self QA.
Fresh, authoritative Kerdoios capacity; unknown is not available NOT MET src/z0int/dispatch.py:218-232,267-291: no check of schema or at freshness, and local test slots are invented from CPU count even without a capacity offer. This violates #131's unknown-capacity invariant.
Capacity and monetary quotas remain bounded across callers/batches NOT MET src/z0int/dispatch.py:302-321,403-455: read/score/insert is not an atomic reservation; capped estimated spend is summed only for the current batch, and pending free-window requests aren't reserved between calls. Two workers can receive the same offered slots/remaining budget.
All decisions and outcomes auditable, safe to replay NOT MET Only placements enter decisions (src/z0int/dispatch.py:418-455); waits/rejections do not. record_outcome permits unknown IDs and repeated terminal reports (:492-510); there is no unique (batch, job) admission/replay fence. Compare canonical dispatch authority and replay contract in README.md:15-25.
Quality from observed outcomes, with QA agreement preferred MET for arithmetic; NOT MET as evidence-based quality authority src/z0int/dispatch.py:139-158,513-519 treats an unverified status=ok plus schema validity as a quality success; arbitrary QA agreement updates its posterior. README.md:5-9 explicitly separates completion from verified outcome.
Forward throttles to Kerdoios for all supported capacity paths NOT MET load_capacity supports CLI fallback (src/z0int/dispatch.py:218-232), but observe_capacity silently returns on failed Python import (:235-246); record_outcome then appears completed (:505-510).
Batch snapshots, reporting, dry-run estimates MET structurally; UNTESTED operationally src/z0int/dispatch.py:169-213,462-489,522-573; docs/dispatch.md:41-66. No public independent reconstruction of the described live factory batch or actual Kerdoios integration in this review.
Repository evidence / privacy hygiene NOT MET AGENTS.md requires revision-bound unit + product smoke. Exact-head Evidence receipt job failed because the PR body has no YAML receipt containing issue, base revision and head revision; failed job. The PR description also includes a private-machine report path, and src/z0int/dispatch.py:69-72 includes account-specific usage observations; replace both with sanitized, authorized evidence.

Correctness bugs and minimal repairs (priority order):

  1. P0: double allocation / paid-cap overspend — src/z0int/dispatch.py:302-321,403-455. Concurrent callers independently read headroom, slots and shared Nous budget, then commit late. Use the existing dispatch authority's lease/idempotency contract and a serialized reservation/transaction against a revision-bound capacity offer; reconcile all outstanding batches before admission. Never let this SQLite analysis ledger become a second resource authority.
  2. P0: synthetic or stale capacity schedules work — src/z0int/dispatch.py:267-291,403-413. Reject missing/wrong schema, stale timestamps, and unknown offers; remove auto-created local slots unless Kerdoios/runtime explicitly offers and authorizes them.
  3. P0: QA/result evidence is spoofable or cross-batch — src/z0int/dispatch.py:97-108,139-158,492-519. Require avoid_family for QA, independently attested verifier identity/decision ID, finite agreement in [0,1], one terminal outcome per decision, and batch/decision-scoped QA updates. Never promote schema-valid completion as independent quality gold.
  4. P1: outcomes can silently fail to cool throttled lanes — src/z0int/dispatch.py:235-246,505-510. Use Kerdoios' documented capacity observe CLI when the Python API is unavailable, or report explicit failure / block subsequent dispatch. Do not quietly drop rate limits.
  5. P1: invalid request values bypass guards — src/z0int/dispatch.py:97-108,330,340-353. Validate size enum, finite quality in [0,1], positive tokens, finite positive deadlines and well-formed identifiers before routing. In particular, float('nan') makes q < job.quality false.
  6. P1: waits are absent from the promised audit ledger — src/z0int/dispatch.py:420-455. Persist wait/no-candidate results with alternatives, rejection reasons and capacity revision, not only successful allocations.

Missing exact tests (add to tests/test_dispatch.py, and include a top-level CLI smoke): test_dispatch_rejects_stale_or_wrong_schema_capacity, test_dispatch_unknown_capacity_does_not_invent_local_slots, test_dispatch_concurrent_claims_do_not_oversubscribe, test_dispatch_nous_reservations_are_global_across_batches, test_dispatch_deduplicates_batch_job_and_terminal_outcome, test_dispatch_qa_requires_independent_avoid_family, test_dispatch_qa_is_scoped_by_decision_not_job_id, test_dispatch_rejects_nonfinite_quality_and_invalid_size_tokens, test_dispatch_cli_capacity_observe_fallback, test_dispatch_wait_rejections_are_persisted, and test_dispatch_top_level_cli_roundtrip. Existing 13 tests (tests/test_dispatch.py:47-171) do not cover these negative/concurrency boundaries.

Overlaps / integration: #179 is explicitly stacked on this exact head and modifies src/z0int/dispatch.py, tests/test_dispatch.py, docs/dispatch.md (inline one-shot scans; quota cooldown; measured latency); preserve it when fixing #178. Open #176, #211 and #246 also edit src/z0int/cli.py on other bases, so recheck integration. Kerdoios #66 defines the live source contract; it is a separate draft dependency. Current master is 10 commits ahead of the merge base, and GitHub reports mergeable=false for #178; recheck actual conflicts after repairs.

Exact-head CI, not independently executed here: Core unit passed its offline-suite jobs on Python 3.11/3.13 (3.13 log: 1177 passed, 6 skipped, 5 deselected). Evidence receipt failed: missing exact-head YAML evidence block. Claimed live batch measurements are not reverified by these results.

Commands to run after fixing: PYTHONPATH=src python -m pytest -q tests/test_dispatch.py; PYTHONPATH=src python -m z0int dispatch --help; python -m pytest -q -m 'not live'; python -m z0int doctor --json; (cd results/raw && sha256sum -c SHA256SUMS); python benchmarks/verify_published.py; and an isolated two-worker, same-capacity Kerdoios reservation/cooldown integration smoke. Update the exact-head YAML receipt and rerun both CI gates. No source changed in this research review.

Verdict: NEEDS-FIX — CLI/selection baseline exists and offline tests pass, but unleased stale-capacity dispatch, unauthenticated quality/QA feedback, dropped throttle fallback and the failing evidence receipt prevent safe promotion. Do not merge.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:docs Documentation area:verify Tests, mutation, evidence

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant