Skip to content

feat(apps): let an app.json cron ask for an exact start time - #22752

Merged
bolichen97 merged 2 commits into
kirodotdev:mainfrom
leonlaiyc:claude/22519-app-cron-strict-schedule
Oct 23, 2026
Merged

bolichen97 merged 2 commits into
kirodotdev:mainfrom
leonlaiyc:claude/22519-app-cron-strict-schedule

Conversation

@leonlaiyc

@leonlaiyc leonlaiyc commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An app can declare a cron in app.json that fires exactly at its scheduled time instead of up to 59 minutes later.

CronJob.strict_schedule already exists and compute_jitter() returns 0 when it is set, but an app cannot ask for it. The manifest's CronEntry has no such field and register_app_crons_with_service never 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

  • Exposing strict_schedule on the published ctx.cron.add_job / add_job_async signatures. Those stay unchanged; only the manifest bridge's add-if-absent create threads it.
  • Changing the jitter default or its range for any job that does not ask.
  • Other CronJob fields 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:

  • Manifest (apps/manifest_sections.py): CronEntry.strict_schedule: bool = False. Parsed strictly, like enabled: the string "false" is truthy, and reading it as True would drop the delay an author never gave up, so any non-boolean is ignored and reported by validate() ("has the wrong JSON type (expected a boolean)"). to_dict() emits it only when true, so an unset value leaves an already-signed manifest's payload unchanged.
  • Bridge (apps/bridges_crons.py): written to app-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_fields reads the job's strict_schedule too, so when a re-sync replaces a value that differs from the job's, the existing overwrite warning names strict_schedule beside the other manifest-owned fields it reset.
  • SDK (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 to CronService only when true, 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=False to every app job, resetting a value a person set by hand on the Schedule page. _LATE_KEY_DEFAULTS reads a missing strict_schedule in an older stamp as its default false, so the field counts as changed only when the manifest actually asks for true. The same default is used when digesting an app-crons.json entry written before the key existed, so None and false stamp 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:

  • end to end against a real CronService: strict_schedule: true registers a job with compute_jitter(job) == 0; absent keeps false.
  • CronEntry parses it, to_dict() emits it only when set, the bridge writes it to app-crons.json, and the SDK create receives it; an app-crons.json from before the key existed registers false.
  • "true", "false", 1, 0, [True], {...} are ignored and reported by validation; null means unset.
  • re-registration: an author turning it on, and off, reaches the installed job; a person's hand-set value survives a manifest change to another field.
  • upgrade: with a stamp written before the key existed, a hand-set true is not reset, and an author who asks for true still gets it. Removing the _LATE_KEY_DEFAULTS read turns the first of these red (checked locally).

Updated: test_app_cron_manifest_resync.py (stamp now has 16 keys; strict_schedule added to test_every_manifest_owned_field_takes_part) and test_app_bridges_crons.py (the SDK call now carries strict_schedule=False).

Local (Windows, Python 3.13): those three files plus test_app_cron_timeout_manifest.py, test_cron_sdk.py, test_app_manifest*.py and test_bridges_facade.py: 550 passed. test_flake_pattern_ratchet.py 60 passed. black/isort/flake8/mypy clean on the touched files; comment-history, brand and file-line-cap gates and docs_lint.py pass.

Manual verification

N/A — unit coverage sufficient: the end-to-end tests register the manifest cron with a real CronService and assert the persisted job and its computed jitter, which is everything the scheduler reads at fire time.

Related Issues

Closes #22519

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable): docs/app-kit/manifest-reference.md (cron field table) and docs/system-specs/modules/learn-cron-dashboard.md (App SDK create allowlist)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

🤖 Generated with Claude Code

@leonlaiyc
leonlaiyc requested review from a team and KiroCrewCaptain as code owners October 21, 2026 11:04
@leonlaiyc
leonlaiyc requested a review from iamwhatever October 21, 2026 11:04
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 21, 2026
@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision aabac03bcf5a2942938a6dd8b5044746eeb61585 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of aabac03bcf5a2942938a6dd8b5044746eeb61585 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the change adds an optional, default-off field to the existing manifest → app-crons.json → SDK path, and _LATE_KEY_DEFAULTS stops the upgrade pass from resetting a strict_schedule value someone set by hand.

Notes

  • After the upgrade, the first pass finds every job's existing stamp missing the new key, so it takes the full re-sync path at bridges_crons.py:681 instead of the fast path. That pass should only rewrite the stamp, with no field changes, because _stored_digest treats the missing key as false.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of aabac03bcf5a2942938a6dd8b5044746eeb61585 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • Item 4 — one consumer, generalized: _LATE_KEY_DEFAULTS: dict[str, Any] = {"strict_schedule": False} is a one-entry table, with a _stored_digest helper written for any key, but strict_schedule is the only late key that has one. Older keys such as timeout_secs still follow the base rule that a missing key "counts as changed on its own". Subtraction: delete the dict and _stored_digest, and instead special-case strict_schedule (stored digest missing means _field_digest(False)) inline in _stamp_digests and _resync_app_cron.

What this change ships

Inventory (7 items) — 5 justified

Intent: 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).

  1. An app.json cron entry can set strict_schedule: true, and the installed job then fires with no start jitter — justified
  2. A non-boolean strict_schedule (such as the string "false") is ignored and reported by manifest validation — justified
  3. When an author turns the field on or off in the manifest, the change reaches already-installed jobs on re-registration — justified
  4. After an upgrade, a strict_schedule value a person set on the Schedule page is not reset, because stamps written before the key existed read it as false — one consumer, generalized
  5. add_job_if_absent_async accepts strict_schedule; the published add_job signatures are unchanged — justified
  6. The log entry for a hand-edited field that a re-sync overwrites now includes strict_schedule — undeclared
  7. The manifest reference and the cron spec document the field; the spec removes it from the "still absent" allowlist — justified

[FIRST-PRINCIPLES-REVIEWED] aabac03

Description read

[DESCRIPTION-READ] 0b53683a00777dea51b2a48de3be28a2dcb1a6f9a3a99ed020ea08b9c57f8a06

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed aabac03bcf5a2942938a6dd8b5044746eeb61585 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] aabac03

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed aabac03bcf5a2942938a6dd8b5044746eeb61585 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] aabac03

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 21, 2026
leonlaiyc and others added 2 commits October 22, 2026 21:43
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>
@leonlaiyc
leonlaiyc force-pushed the claude/22519-app-cron-strict-schedule branch from facf0f7 to aabac03 Compare October 22, 2026 13:45
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 22, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD: two unanswered AI review notes on aabac03.

The change looks correct. strict_schedule is threaded from CronEntry through app-crons.json and add_job_if_absent_async, and the update path already accepts it (fields.py#L539-L540). _LATE_KEY_DEFAULTS stops the first pass after an upgrade from resetting a hand-set value, and I confirmed that pass sends only the new stamp for an unchanged job, as the Design Review note expected. CI is green on this head.

Blockers, both from the First Principles review on this head, with no reply yet:

  1. Notes item 4: _LATE_KEY_DEFAULTS plus _stored_digest is a general table for one key (bridges_crons.py#L236-L286). The review suggests inlining the strict_schedule special case instead. Either make that change or reply on the PR saying why the table should stay.
  2. Inventory item 6 is marked undeclared: _overwritten_fields now logs strict_schedule (bridges_crons.py#L573). Add one line about it to What changed.

Answering both clears this hold.

— crew-pr-reviewer (r120)

@leonlaiyc

leonlaiyc commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor Author

Answering the HOLD on aabac03. Neither answer needs a code change, so this head stays as reviewed.

1. Why _LATE_KEY_DEFAULTS stays a table. Inlining would not make the code smaller. The default has to be read in two places: _stamp_digests digests an app-crons.json entry that does not name the key, and _stored_digest reads an older stamp that lacks the key. Each of those must agree with the other, or None and false would stamp differently and every job would count as changed. An inlined version still needs both reads, each with its own if key == "strict_schedule" and its own False literal, so it would be the same amount of code with the default written twice.

The table also covers the next key, and keyed stamps exist so keys can be added. Any key added to _MANIFEST_OWNED_CRON_KEYS that a person can also set by hand has the same upgrade hazard: the first pass after the upgrade would see the key missing from every stored stamp and reset the hand-set value. With the table, avoiding that is one dict entry. With an inline special case, the next author has to notice the hazard on their own, and nothing would catch it if they missed it. test_app_cron_strict_schedule_manifest.py pins the behaviour: removing the _LATE_KEY_DEFAULTS read turns the upgrade test red.

2. _overwritten_fields logging strict_schedule. Added to What changed under the Bridge bullet. When a re-sync sends strict_schedule, the overwrite warning now names it beside the other manifest-owned fields, comparing against bool(job.strict_schedule). Like the other fields, it is logged only when the manifest's value differs from the job's.

Note: the red Sensitive Change Review on this head is the job failing to read the PR from the API at 08:02 UTC (Could not read the PR from the API (CalledProcessError); re-run this job.), the same blip as on #23117 at the same minute. It is not a verdict, and a maintainer rerun clears it. I am not pushing, so aabac03 stays the reviewed head.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: action required A blocking check or review needs attention labels Oct 23, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) October 23, 2026 20:06

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@bolichen97
bolichen97 merged commit 27e949d into kirodotdev:main Oct 23, 2026
112 of 113 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Apps: expose strict_schedule in app.json so an app cron can run at the exact time without start jitter

3 participants