Repository navigation
feat(apps): add opt-in retention and a liveness predicate to the Job SDK - #22711
dodgeblaster wants to merge 1 commit into
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: retention is opt-in per kind and purely additive, and the Notes
[DESIGN-REVIEWED] ece318e Description read[DESCRIPTION-READ] e3c96e7e489b86998da82019ee00d3fba875e6063005e72da53fceea9b1ea493 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — 🔴 BLOCKPremise-level review of First-Principles-Verdict: BLOCK
Notes
What this change shipsInventory (8 items) — 4 justifiedIntent: let an app bound how many job run records each kind keeps without deleting a run that is still delivering results. ADDITION.
BlockersPublic contract arguments with no caller — zero consumers [FIRST-PRINCIPLES-REVIEWED] ece318e Description read[DESCRIPTION-READ] 8acd1ddec3324c36c383f2d776cfc299a97715e99eee9627e5caa3785b5e86fb That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
c2c7f77 to
b9162b7
Compare
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
|
b9162b7 to
60cc7a8
Compare
|
self-added: yes
|
0534199 to
5d3378a
Compare
|
5d3378a to
520cd91
Compare
|
Bound a Job SDK kind's run-record count and express when a finished run is still using its resources, so old records are pruned and a terminal-but- still-writing run is never evicted. All additive and opt-in per kind.
e6caf22 to
ece318e
Compare
|
Request for a maintainer ruling on the public App Kit contract in this PR The author (@dodgeblaster) would like to ship this contract as it stands:
Why ship it now, before an in-repo app uses it. Apps that move onto the Job SDK will need bounded retention and a liveness predicate. Without them, a job's history grows without limit, or an app evicts by status alone and drops a run that is still in use. Code Review Sage already hit that status-only eviction bug in its own registry. With apps leaving the core (the Nov 1 direction, and the level-1 seams in §32 of What is being asked. Under
This account will not post an |
|
Maintainer ruling on the public Job SDK contract at ece318e: accepted as it stands.
What this ruling asks in return: the first app that migrates should use these arguments, rather than adding its own retention again, and that PR should link back here. I will follow up with the code review of this head and the First Principles override. |
bolichen97
left a comment
There was a problem hiding this comment.
Correction to my earlier comment on this PR: the final maintainer decision is no override. That comment accepted the public contract ahead of a consumer, and it is withdrawn. I am sorry for the mixed signal.
Requesting changes at ece318e, as the First Principles lane asks:
- Defer
register(..., retention=, live=, on_evict=)and the persistedJobRun.seq(items 1 to 4) until an app actually calls them. Land them in the same PR as that first consumer's migration, or link that consumer PR from this one. - The parts that stand on their own can go ahead now: the
job_evictedaudit event,reconcilenot recreating a record retention removed, the store's delete and no-follow scan, and the spec section. Splitting them out is fine.
The code itself read well: the no-follow bounded scan, the seq seeding with a ceiling, the live-run exclusion and the sweep that never raises. So this is only about when the public arguments land, not how they work.
|
One addition to my request for changes above at ece318e, which already withdraws the earlier acceptance of the three parameters. The two ways forward, more concretely:
If ordering is still needed under (a), the First Principles lane's simpler option is worth taking. Sort on a nanosecond completion time stamped at the terminal write, instead of |
|
[operator: bolichen97] Continuing this in #33196; thanks for the start. |
The Job SDK writes one record file per run and removes them only when the app is disabled, so a kind's store grows with every run. register() takes an opt-in per-kind retention count: after each terminal write the sweep removes that kind's oldest finished records until at most that many remain. It never removes a run still running or one whose own sweep has not run yet, and it reads each record without following a link. aws_control's two backup kinds opt in at 100, at or above every reader's window. The liveness predicate and eviction callback are left to #33058. Builds on #22711. Closes #7588
The Job SDK writes one record file per run and removes them only when the app is disabled, so a kind's store grows with every run. register() takes an opt-in per-kind retention count: after each terminal write the sweep removes that kind's oldest finished records until at most that many remain. It never removes a run still running or one whose own sweep has not run yet, and it reads each record without following a link. aws_control's two backup kinds opt in at 100, at or above every reader's window. The liveness predicate and eviction callback are left to #33058. Builds on #22711. Closes #7588
The Job SDK writes one record file per run and removes them only when the app is disabled, so a kind's store grows with every run. register() takes an opt-in per-kind retention count: after each terminal write the sweep removes that kind's oldest finished records until at most that many remain. It never removes a run still running or one whose own sweep has not run yet, and it reads each record without following a link. aws_control's two backup kinds opt in at 100, at or above every reader's window. The liveness predicate and eviction callback are left to #33058. Builds on #22711. Closes #7588
The Job SDK writes one record file per run and removes them only when the app is disabled, so a kind's store grows with every run. register() takes an opt-in per-kind retention count: after each terminal write the sweep removes that kind's oldest finished records until at most that many remain. It never removes a run still running or one whose own sweep has not run yet, and it reads each record without following a link. aws_control's two backup kinds opt in at 100, at or above every reader's window. The liveness predicate and eviction callback are left to #33058. Builds on #22711. Closes #7588
|
Closing this PR as superseded by #33196.
The remaining parts of this PR are therefore superseded for now. This isn't a judgement on anyone's work. The branch |
Problem / Motivation
Goal: Let a Job SDK consumer bound how many run records a kind keeps, and tell the SDK when a finished run is still using its resources, so old records are pruned and a run that is terminal-but-still-writing is never deleted out from under itself.
JobStorewrites one JSON file per run and removes one only on app disable.list_recent'slimitcaps the response, not the store, so a consumer's per-run file count grows without bound and every full-set read opens every file. AndJobRun.is_terminalis pure status membership, so a run that has reached a terminal status while still delivering its results (Code Review Sage'spostingphase, which runs after the run goes terminal) reads as evictable — the moment eviction is added, a status-only test would delete such a run's directory while its poster is still writing.Why it matters
A consumer that migrates to the SDK gets unbounded growth today, and the obvious eviction predicate (
is_terminal) would delete a run mid-delivery — the exact defect Code Review Sage already had to fix inside its own registry. Bounding the store and expressing liveness are the two halves of making retention safe.This PR changes the public App Kit contract (the
registersignature gains three optional arguments, andJobRungains aseqfield), which is a public-contract decision pending a maintainer ruling. The shape built here — a bounded cap, an eviction callback, and alivepredicate registered alongside the runner — follows the proposal in the issue thread (the 2026-09-28 comment on #7588). That comment is a proposal, not a ruling: its author is not inMAINTAINERS.md, so underdocs/decisions/README.mdrule 4 it does not settle the contract. This PR is therefore a DRAFT for a maintainer to decide whether to promote.Not a goal
retentionkeeps every record exactly as before.postinginto the SDK. The SDK takes a predicate;postingis one app's implementation of it.seqis an SDK-minted integer, not data a runner or caller supplies.What changed (motivation → approach → change)
Nothing prunes the store and liveness cannot be expressed, so this adds both at
registerand leaves every existing kind untouched by defaulting the cap off.register(kind, fn, ..., retention=0, live=None, on_evict=None)binds a per-kind count cap, a liveness predicate over a terminal run, and an eviction callback. The retention logic lives in a new owner,src/kiro_crew/apps/job_sdk_retention.py, served through thejob_sdkfacade like its siblings and bound ontoJobSDK, which keepsjob_sdk.pyunder the 1,600-line split line. After each terminal write the sweep keeps the newestretentionterminal records of that kind. It spares runs still executing here and terminal runsliveclaims (neither is counted), callson_evictwith each dropped run, then deletes the file via a newJobStore.removeand audits a newjob_evictedevent. It readsjobs/(app-writable) through the bounded, no-followsafe_read_file_bytes_nolinkfunnel the disable scan uses, via a privateJobStore._iter_runs_nolink. That scan skips planted links, oversized or deeply nested files, names that are not run ids, and bodies whose id differs from the filename.iter_runsis unchanged. A disabled SDK sweeps nothing: the sweep checks the closed flag under the lock disable sets it with, so a worker that outlives disable cannot evict a re-enabled SDK's records. Newest-first uses a new SDK-mintedseqonJobRun(job_sdk_records.py), stamped at the terminal write (completion order, so a long run finishing last survives its own sweep) because the timestamps are second-resolution. Eachseqis at least the wall clock in nanoseconds and above the previous one, so a run finishing after a restart outranks earlier records even if the seed saw nothing; the counter is also seeded once per SDK above the highestseqon disk (off the event loop), which covers a clock that stepped back across the restart; each SDK has its own counter, so one app's store can steer only its own order; the seed ignores a diskseqoutside a signed 64-bit range and refuses a floor above half of it, and the sweep sorts an out-of-rangeseqas 0, so a planted huge integer cannot exhaust the counter or outrank a genuine run.reconcilestamps the runs it resolves and refuses to recreate a record retention removed. Seeding, stamping, the sweep, a raisinglive(treated as keep) and a raisingon_evictare all logged and never skip a run's terminal write. A run whoseliveclears is released at the kind's next completion.Backwards compatibility
Compatible: the three
registerarguments are keyword-only with defaults that reproduce today's behaviour (retention=0keeps every record,live=Noneevicts on terminal status alone only when a cap is set,on_evict=Nonecalls nothing), andJobRun.seqdefaults to0, whichfrom_dictsupplies for any record an older build wrote.Removes nothing: no field, method, kind, or key an app can see is renamed or removed; the addition is purely additive, so there is no reader to enumerate.
Tests
test/test_job_sdk_retention.py(new):retentionkeeps every record (the additive default);on_evictis called with the evicted run before its record is removed;livepredicate claims is kept past the cap while live and evicted once liveness clears, and a live run does not consume a cap slot;on_evict), a forged record whose body id differs from its filename, an oversized record and an unparseable one, and survives an absent directory or a listing failure. The symlink and forged-record tests red when the sweep is pointed back at the link-followingiter_runs;on_evict(reds with the closed checks removed).seqdoes not poison the counter (reds without the bound), and one app's near-ceilingseqdoes not reach another app's numbers (reds with a shared counter);Determinism:
test/test_job_sdk_retention.pypassed 10/10 repeats at-n4and 3/3 seeded shuffled orders at-n0, and the disable/funnel/forged tests 10/10 more at-n0, and the whole file 5/5 more at-n4after the module split; post-sweep state is awaited with a bounded_wait_untilon file names or existence (never by opening a record, which on Windows blocks the sweep's delete) or a thread join, never a sleep.test/test_job_sdk_facade.pylists the new owner inOWNERS.test/test_job_sdk.pyandtest/test_job_sdk_invariants.py: the two field-set guard tests addseqto their expected sets with the rationale that it is SDK-minted, so the sanitize backstop still haserroras its only runner-supplied input.Manual verification
N/A — unit coverage is sufficient; the SDK is a backend module with no user-visible surface in this diff, and the sweep, liveness and ordering are all exercised deterministically by the new tests (proven by reverting the sweep, which reds them).
Screenshots / video
Why no screenshot: backend-only change to the Job SDK; no frontend path is touched.
Related Issues
Closes #7588
Pattern harvest
Not generalizable: this is an additive feature on one module's public contract, not a fix to a defect class.
Checklist