Repository navigation
feat(apps): let an app.json cron ask for an exact start time - #22752
Conversation
UX Review (Opus 5.5, fork) — ⏭️ skippedRevision |
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the change adds an optional, default-off field to the existing manifest → Notes
[DESIGN-REVIEWED] aabac03 Description read[DESCRIPTION-READ] a01a596b886cb01c339f1fbcbf724ccc5fc8856afbffed68c66674af031282c6 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, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS This is a narrow opt-in that defaults to off. Every layer it touches was already dropping a field that exists (#22519), so nothing blocks. One note: a general-purpose table was added to carry a single key. Notes
What this change shipsInventory (7 items) — 5 justifiedIntent: let an app author make a manifest cron fire at the exact time the user chose, with no random start delay. This is an ADDITION (it closes a gap in the bridge).
[FIRST-PRINCIPLES-REVIEWED] aabac03 Description read[DESCRIPTION-READ] 0b53683a00777dea51b2a48de3be28a2dcb1a6f9a3a99ed020ea08b9c57f8a06 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
CronJob.strict_schedule already skips the scheduler's random start delay, but an app could not set it: the manifest's CronEntry had no such field and the bridge never passed one, so every daily app cron at a fixed hour started up to 59 minutes late. An app.json cron entry now takes strict_schedule (a JSON boolean; any other type is reported at validation, like enabled). It travels to app-crons.json and to the cron SDK's add-if-absent create, and is manifest-owned on re-registration like the entry's other fields. A stamp written before the key existed reads it as false, so the first pass after an upgrade does not reset a value a person set on the Schedule page. Closes kirodotdev#22519 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ifest The apps.bridges facade's TYPE_CHECKING manifest must list every name it forwards from an owner. bridges_crons gained _LATE_KEY_DEFAULTS and _stored_digest in the previous commit, so test_every_mirrored_facade_manifest_names_what_it_forwards failed on Backend Tests shard 2. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
facf0f7 to
aabac03
Compare
|
HOLD: two unanswered AI review notes on aabac03. The change looks correct. Blockers, both from the First Principles review on this head, with no reply yet:
Answering both clears this hold. — crew-pr-reviewer (r120) |
|
Answering the HOLD on 1. Why The table also covers the next key, and keyed stamps exist so keys can be added. Any key added to 2. Note: the red |
bolichen97
left a comment
There was a problem hiding this comment.
Reviewed current head aabac03bcf5a2942938a6dd8b5044746eeb61585 as Tier 2. Deep review found no blocking issue.
Security check: strict_schedule is a strict boolean. Existing app-cron admission, ownership, and command checks remain unchanged. The safe default stays jittered. Auto-merge remains subject to branch protection.
Problem / Motivation
Goal: An app can declare a cron in
app.jsonthat fires exactly at its scheduled time instead of up to 59 minutes later.CronJob.strict_schedulealready exists andcompute_jitter()returns 0 when it is set, but an app cannot ask for it. The manifest'sCronEntryhas no such field andregister_app_crons_with_servicenever passes one, so every daily app cron at a fixed hour gets the scheduler's random start delay. The reporter's example: a report gathered at 06:50 so it is ready when work starts can arrive near 07:50. Two of their apps re-implemented "start exactly at the chosen time" to work around it.Why it matters
Jitter is the right default for background jobs, but some app crons run at a time a user picked on purpose. Today an app author has no way to opt out short of duplicating the scheduler, and the user sees a job that ignores the time they set.
Not a goal
strict_scheduleon the publishedctx.cron.add_job/add_job_asyncsignatures. Those stay unchanged; only the manifest bridge's add-if-absent create threads it.CronJobfields the app SDK still omits (model,hide_in_chat,delete_after_run,at_ts, ...).What changed (motivation → approach → change)
The field already works end to end once it reaches the job, so the change is plumbing at the three layers that dropped it, plus one rule for re-registration:
apps/manifest_sections.py):CronEntry.strict_schedule: bool = False. Parsed strictly, likeenabled: the string"false"is truthy, and reading it asTruewould drop the delay an author never gave up, so any non-boolean is ignored and reported byvalidate()("has the wrong JSON type (expected a boolean)").to_dict()emits it only whentrue, so an unset value leaves an already-signed manifest's payload unchanged.apps/bridges_crons.py): written toapp-crons.json, passed to the SDK create, and added to the manifest-owned keys, so an author turning it on or off reaches an installed job through the existing field-by-field re-sync._overwritten_fieldsreads the job'sstrict_scheduletoo, so when a re-sync replaces a value that differs from the job's, the existing overwrite warning namesstrict_schedulebeside the other manifest-owned fields it reset.apps/cron_sdk.py):add_job_if_absent_async(the one method the bridge calls) accepts it and threads it into the single locked create. It is sent toCronServiceonly whentrue, so the create kwargs of every existing caller are byte-identical.Upgrade rule. The re-sync stamp is keyed per field, and a stamp missing a key the build knows counts that key as changed. For a key added now, that would make the first pass after an upgrade send
strict_schedule=Falseto every app job, resetting a value a person set by hand on the Schedule page._LATE_KEY_DEFAULTSreads a missingstrict_schedulein an older stamp as its defaultfalse, so the field counts as changed only when the manifest actually asks fortrue. The same default is used when digesting anapp-crons.jsonentry written before the key existed, soNoneandfalsestamp alike.Backwards compatibility
Compatible: the field is optional and defaults to the current behaviour (jittered). A manifest without it registers, stamps and re-syncs exactly as before apart from the stamp gaining one key, and that key cannot change an installed job unless the manifest sets it to
true.Removes nothing: the change only adds an optional manifest field and threads it to a job field that already exists.
Tests
New
test/test_app_cron_strict_schedule_manifest.py(19 tests), one assertion per layer so a dropped field names its layer:CronService:strict_schedule: trueregisters a job withcompute_jitter(job) == 0; absent keepsfalse.CronEntryparses it,to_dict()emits it only when set, the bridge writes it toapp-crons.json, and the SDK create receives it; anapp-crons.jsonfrom before the key existed registersfalse."true","false",1,0,[True],{...}are ignored and reported by validation;nullmeans unset.trueis not reset, and an author who asks fortruestill gets it. Removing the_LATE_KEY_DEFAULTSread turns the first of these red (checked locally).Updated:
test_app_cron_manifest_resync.py(stamp now has 16 keys;strict_scheduleadded totest_every_manifest_owned_field_takes_part) andtest_app_bridges_crons.py(the SDK call now carriesstrict_schedule=False).Local (Windows, Python 3.13): those three files plus
test_app_cron_timeout_manifest.py,test_cron_sdk.py,test_app_manifest*.pyandtest_bridges_facade.py: 550 passed.test_flake_pattern_ratchet.py60 passed. black/isort/flake8/mypy clean on the touched files; comment-history, brand and file-line-cap gates anddocs_lint.pypass.Manual verification
N/A — unit coverage sufficient: the end-to-end tests register the manifest cron with a real
CronServiceand assert the persisted job and its computed jitter, which is everything the scheduler reads at fire time.Related Issues
Closes #22519
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)docs/app-kit/manifest-reference.md(cron field table) anddocs/system-specs/modules/learn-cron-dashboard.md(App SDK create allowlist)Contribution License Agreement
🤖 Generated with Claude Code