Skip to content

fix(cron): keep a newer build's store fields through this build's save - #18894

Merged
bolichen97 merged 2 commits into
kirodotdev:mainfrom
javenciu:fix/cron-store-keeps-fields-from-a-newer-version
Oct 12, 2026
Merged

bolichen97 merged 2 commits into
kirodotdev:mainfrom
javenciu:fix/cron-store-keeps-fields-from-a-newer-version

Conversation

@javenciu

@javenciu javenciu commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An older build's save keeps the fields a newer build wrote into crons.json, up to 64 KiB per job and 1 MiB for the whole store, and never stamps the store's version lower.

The desktop updater allows downgrades: it runs with allowDowngrade=true so that a channel switch-back installs the older version (docs/build/release.md). After a rollback, the older build loads a crons.json a newer build wrote, and its first ordinary save deletes what the newer build added:

  • CronService._save (src/kiro_crew/cron.py) re-encodes every job through job_record (src/kiro_crew/cron_service/store.py), an explicit list of the fields this build knows. Any field a newer build added is dropped, on every job, including jobs the user never touched.
  • The document is stamped "version": _STORE_VERSION (2), so a store a newer build wrote at a higher version is stamped back down. After the user upgrades again, the newer build cannot tell that its fields were removed.

Why it matters

This already happened once. managed_by was added by merged #17683, and a build from before it deletes the field on its first save, so the installer that owns the job can no longer find it. The writer's own comment said an older build "simply ignores the extra key". That is true for reading, not for the rewrite.

Not a goal

  • A job with an unknown schedule kind still never fires (is_due returns False for an unknown kind). That is the safe direction, and this change does not touch it.
  • A record this build cannot load at all is still skipped with a warning and dropped on the next write, as today.
  • Keeping a newer build's keys past the two caps: 64 KiB for one item, 1 MiB for the store. A job whose unknown keys, with its schedule's, pass 64 KiB as JSON keeps none of them, and so does a document whose unknown top-level keys pass it (_kept_size logs each, cron_service/store.py:651-668). Nothing limits how many jobs a store holds, so the whole store keeps at most 1 MiB of them: the top-level keys first, then each job in file order, and a job whose keys would take the total past 1 MiB keeps none of them. One warning per load counts those jobs (store.py:815-828). The next save writes each such job, or the document, as this build knows it, as main does with every unknown key today. Keeping more would mean merging them back from the file at save time under the store lock; this PR does not.

What changed (motivation → approach → change)

  • Symptom: after a rollback, the older build's first save drops every field it does not know and stamps the store version 2.
  • Root cause: encode_store rebuilds each job from job_record, which writes only this build's fields, and always writes _STORE_VERSION; nothing carried the unknown keys or the higher version from the load to the save.
  • Change, src/kiro_crew/cron_service/store.py:
    • decode_store(raw) returns a StoreDocument with the jobs (decode_jobs is now a thin wrapper over it), the version read when it is an integer above this build's, the top-level keys other than version and jobs, and, for each job that loads, the keys of its record and of its schedule that this build does not know.
    • encode_store(jobs, *, version, extra, unknown_fields) writes them back fill-only, the rule KiroCrewConfig.to_dict already applies to unknown config keys (restore_extra_section_keys, src/kiro_crew/config/loader.py): a key this build writes itself is never overwritten; only a job still in jobs gets its unknown keys back, so a job this build deletes is gone with them; and the version is never written lower than the one read. A store with no unknown keys encodes exactly as before.
    • What is kept is bounded where decode_store keeps it, by two named constants, both measured as the JSON text it is written back as (_kept_size, cron_service/store.py:651). MAX_UNKNOWN_FIELDS_BYTES (64 KiB, :642) bounds one item: a job's unknown record and schedule keys together (_kept_size, :742) and the document's unknown top-level keys (:778). MAX_UNKNOWN_FIELDS_STORE_BYTES (1 MiB, :648) bounds the store's total, the top-level keys first and then each job in file order (:815). An item over its cap, or a job past the total, keeps none of them and is logged. The version is an integer and is kept regardless.
    • The known key sets are read off the encoder itself: _KNOWN_JOB_KEYS is job_record of a job that sets every conditionally written key (managed_by), and _KNOWN_SCHEDULE_KEYS is fields(CronSchedule), so the two cannot drift. A key this build knows and clears, such as managed_by set to "", stays cleared and is not restored.
  • Change, src/kiro_crew/cron.py: CronService._load keeps the document beside the jobs (_keep_store_document) and resets it when the file is missing or does not load (_forget_store_document); _save passes it to encode_store. Class-level defaults hold this build's own empty document, so a service built without __init__ still saves. Every load replaces the state whole, and nothing edits it in place. Main's fix(cron): keep a busy merge's run record across store reloads #18628 swaps a reloaded job list in only after it re-applies the run records a busy store refused, and its held-record save writes copies of the listed jobs. So _load keeps the document right after that swap (_keep_store_document, src/kiro_crew/cron.py:5101), and _save writes the kept fields into whichever list it is given (encode_store, src/kiro_crew/cron.py:5255-5256), including the copies _save_held_run_records_locked writes (src/kiro_crew/cron.py:2463), since the fields are matched by job id (fields_by_job, cron_service/store.py:691).
  • Sibling sweep, every other writer of crons.json: the import sanitizer (portability._sanitize_cron_text), the snapshot merge (snapshot_merge._merge_crons) and the execution-context migration (cron_service/identity.py) all edit the parsed document and write it back with json.dumps, so they already keep unknown keys. CronService._save is the only writer that re-encodes jobs.
  • Helpers reused: the fill-only rule of restore_extra_section_keys, and job_record itself as the source of the known keys.

Backwards compatibility

Compatible: a store this build wrote has no unknown keys and encodes byte-for-byte as before (pinned by the store-bytes fixtures in test/test_cron_refactor_contract.py); only a store a newer build wrote keeps more than it did.
Removes nothing: the change keeps keys and a version that were dropped before; it deletes no field, key or function.
Security: no redaction, auth or sandbox rule is touched.

Tests

In short: red on origin/main 64e1cbb, 7 failed and 3 passed in each of 3 runs; green on this branch, the file 10 passed in 3 of 3 runs, the tests of the two cron changes merged since pass, and the 56 neighbouring test files 4,050 passed, 36 skipped. The commands and failures are below.

New file test/test_cron_store_newer_version.py, driving a real CronService on a tmp_path store that a newer build wrote (version 3, an unknown job field, an unknown schedule field and an unknown top-level key):

  • test_an_older_builds_save_keeps_a_newer_builds_fields_and_version: after one ordinary save, the job field, the schedule field, the top-level key and version 3 survive.
  • test_a_known_field_this_build_changes_is_written_with_its_new_value: the new value of a known field wins, and the unknown key beside it is kept.
  • test_a_job_this_build_deletes_is_gone_with_its_unknown_keys: a deleted job does not come back through its unknown keys.
  • test_a_16_mib_field_from_a_newer_build_is_not_kept_in_memory: a job with a 16 MiB unknown field keeps none of it in the service's memory, the refusal is logged, the save writes that job without it, and a second job under the cap keeps its field.
  • test_the_cap_keeps_a_job_at_the_cap_and_refuses_one_byte_over: a job whose unknown keys serialize to exactly 64 KiB keeps them through the save; one byte more keeps none.
  • test_a_16_mib_top_level_key_from_a_newer_build_is_not_kept: a 16 MiB unknown top-level key is not kept or written back, and version 3 still is.
  • test_many_jobs_past_the_store_total_keep_only_what_fits: 40 jobs carry a 60 KB unknown field each, every one under the per-job cap and 2.4 MB together. The store keeps at most 1 MiB, the first 17 jobs in file order keep theirs, the other 23 keep none, one warning counts the 23, and the save writes the first job's field and not the last's.
  • Controls, passing before and after: test_a_store_from_this_version_round_trips_unchanged, test_a_known_field_this_build_clears_stays_cleared, test_a_job_with_an_unknown_schedule_kind_still_never_fires.

Red on origin/main (64e1cbb, this test file copied into a clean checkout, pytest -n 0, 3 of 3 serial runs): 7 failed, 3 passed each. Three fail on the defect:

E       AssertionError: the newer job field was dropped: {'id': 'feea5e53', 'name': 'new-field', 'message': 'm', 'schedule': {'kind': 'cron', 'every_secs': None, 'at_ts': None, 'cron_expr': '0 10 * * *'}, 'channel': None ...
E       assert None == {'max_attempts': 3}
E       KeyError: 'retry_policy'
E       KeyError: 'retry_policy'
FAILED test/test_cron_store_newer_version.py::test_an_older_builds_save_keeps_a_newer_builds_fields_and_version
FAILED test/test_cron_store_newer_version.py::test_a_known_field_this_build_changes_is_written_with_its_new_value
FAILED test/test_cron_store_newer_version.py::test_a_job_this_build_deletes_is_gone_with_its_unknown_keys

The two KeyError failures are the kept-field assertions of the second and third tests: on main the unknown key is gone after the save. The four cap tests read state main does not have (AttributeError on _unknown_fields and _store_extra, ImportError on the cap), so they cannot run there. The 3 passes are the controls.

The cap tests are the witness for the caps. These witness runs were made on 843abe3; the rebase onto 64e1cbb changes neither cron_service/store.py nor the test file. On this change with the per-item cap removed (the same tree before it was added, 3 of 3 serial runs), they fail, 3 failed, 6 passed:

E       AssertionError: the 16 MiB field stayed in memory: 16777228 bytes
FAILED test/test_cron_store_newer_version.py::test_a_16_mib_field_from_a_newer_build_is_not_kept_in_memory
E       ImportError: cannot import name 'MAX_UNKNOWN_FIELDS_BYTES' from 'kiro_crew.cron_service.store'
FAILED test/test_cron_store_newer_version.py::test_the_cap_keeps_a_job_at_the_cap_and_refuses_one_byte_over
E       AssertionError: the 16 MiB top-level key stayed in memory
FAILED test/test_cron_store_newer_version.py::test_a_16_mib_top_level_key_from_a_newer_build_is_not_kept

With the per-item cap and without the store total (3 of 3 serial runs), the many-jobs test fails, 1 failed, 9 passed: all 40 jobs keep their fields.

E       AssertionError: 2400480 bytes kept for one store
FAILED test/test_cron_store_newer_version.py::test_many_jobs_past_the_store_total_keep_only_what_fits

Green on this branch (rebased onto origin/main 64e1cbb): the file passes 10 of 10 in 3 of 3 serial runs. The tests of the two cron changes merged since, which the rebase keeps, pass in 3 of 3 serial runs: test/test_cron_merge_result_reload.py and test/test_portability.py (#18628), 185 passed, 5 skipped; test/test_cron_refused_one_shot_retry_floor.py and test/test_cron_undispatched_one_shot.py (#18591), 10 passed. The 56 test files that name the store's decoder, encoder or crons.json, the new file first, include test_cron_refactor_contract.py, whose store-bytes fixtures pin encode_store(decode_jobs(doc)) == json.dumps(doc) for this build's own documents: 4,050 passed, 36 skipped. Seven files that read the real home directory were left out of that run. A second set, the 31 cron test files that name cancel, _force_reap, _merge_terminal_state_locked or user_paused (with test/test_cron_merge_result_cascade.py added and two that read the home directory left out), run serially: 1,183 passed.

Manual verification

N/A: unit coverage is sufficient; the tests write a newer build's store to disk, run a real CronService save over it, and read the file back.

Related Issues

Related: merged #17683 (added managed_by, the field an older build drops). On the earlier base 843abe3, all 629 open PRs were checked with git merge-tree, with and without this change. 13 touched cron_service/store.py or cron.py; 11 of them had the same conflicts either way. Two gained one cron.py conflict, both on neighbouring lines, and each resolves by keeping both sides:

Pattern harvest

Rule candidate: review-prompt
Pattern: a store writer that re-encodes records from an explicit field list, so a rollback's first save deletes every field a newer build added.

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)
  • No secrets, credentials, or internal references in the diff

@javenciu
javenciu requested review from a team and KiroCrewCaptain as code owners October 10, 2026 17:35
@javenciu
javenciu requested a review from iamwhatever October 10, 2026 17:35
@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 readiness: checking Automated validation is still running labels Oct 10, 2026
@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

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

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

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — 🟡 CONCERNS

Premise-level review of c0ce2b70e76d9f99fcc662503a83044080eba283 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/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The two size caps throw away the very newer-build keys this fix exists to keep, and nothing in the diff or the codebase shows what harm they prevent.

Not justified as shipped

  • Item 5 — inherited: the fix copies the fill-only rule of restore_extra_section_keys (config/resolution.py:306), and that function has no cap at all. These keys are slices of raw, which json.loads has already fully read into memory, so a cap saves no more than one copy of data the process already holds. No reported defect or measured cost backs "64 KiB for one item, 1 MiB for the whole store".
    Subtraction: delete MAX_UNKNOWN_FIELDS_BYTES, MAX_UNKNOWN_FIELDS_STORE_BYTES, _kept_size, the kept_total/past_total count and its warning, and the three cap tests. Keep every unknown key, as the config path does.
    Clears when: a measured memory or latency cost, or a linked issue, shows that keeping keys the file already held hurts someone.

What this change ships

Inventory (8 items) — 7 justified

Intent: after a desktop rollback, the older build's ordinary cron save must not delete what a newer build wrote. FIX.

  1. Job fields this build doesn't know survive the older build's save — justified
  2. Schedule fields this build doesn't know survive the save — justified
  3. Unknown top-level store keys survive the save — justified
  4. The store version is never written lower than the one read — justified
  5. Newer-build keys over 64 KiB per job, or 1 MiB per store, are dropped with a warning — inherited (config sibling has no cap)
  6. A job this build deletes doesn't come back through its kept keys — justified
  7. A key this build clears (e.g. managed_by set to "") stays cleared — justified
  8. job_record comment no longer says an older build "simply ignores" the key — justified

[FIRST-PRINCIPLES-REVIEWED] c0ce2b7

Description read

[DESCRIPTION-READ] 53ccb119d7e656231dfebb15a98d4bd3f383fba3fef3e70fbe3ad7b75758f350

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 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — 🟡 CONCERNS

Design-level review of c0ce2b70e76d9f99fcc662503a83044080eba283 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

When a cap drops a newer build's keys, the save still writes the newer version, so the newer build can't tell anything was removed.

Watch

  • The version stays high after keys are dropped. The description names this harm: "a store a newer build wrote at a higher version is stamped back down. After the user upgrades again, the newer build cannot tell that its fields were removed."

    • decode_store keeps version "regardless", even when _kept_size or the 1 MiB store total throws away a job's or the document's unknown keys.
    • encode_store then writes max(_STORE_VERSION, version).
    • So when the cap path drops data, the store still says 3, while some of version 3's fields are gone. A re-upgraded build trusts that document. Before this PR, the lowered version at least showed that an older build had rewritten the store.
    • The same blind spot covers a job this build edits. A kept schedule key such as jitter_secs is copied back onto a schedule this build rewrote, and the version still reads as one the newer build wrote cleanly.

    Clears when: decode_store records that it dropped something, encode_store then writes _STORE_VERSION (or a marker key), and a test pins it. Otherwise the description says plainly that the kept version doesn't promise the newer fields are all there or still match the rest of the record.

[DESIGN-REVIEWED] c0ce2b7

Description read

[DESCRIPTION-READ] 71ad46011407f340b5fb9e06fa4f99111d92fda7a61e8fd08c4539aa60f3c9ad

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 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] c0ce2b7

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] c0ce2b7

@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 10, 2026
@javenciu
javenciu force-pushed the fix/cron-store-keeps-fields-from-a-newer-version branch from 3534901 to 9f5fe51 Compare October 11, 2026 08:51
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 11, 2026
After a rollback (the desktop updater allows downgrades), the older build
loaded a crons.json a newer build wrote and its first save re-encoded
every job from its own field list, dropping every field the newer build
added, and stamped the store back to version 2.

decode_store keeps the version read when it is higher, the unknown
top-level keys, and each loaded job's unknown record and schedule keys.
encode_store writes them back fill-only, the rule the config file uses
for unknown keys: a key this build writes is never overwritten, a job
this build deleted is gone with its keys, and the version is never
lowered. A store with no unknown keys encodes exactly as before.

What is kept is bounded, measured as the JSON it is written back as:
at most 64 KiB per job (its unknown keys with its schedule's) and for
the document's unknown top-level keys, and at most 1 MiB for the whole
store, the top-level keys first and then each job in file order. An
item over its cap, or a job past the store's total, keeps none of them
and is logged, so its next save writes it as this build knows it.
The store test's module docstring wrote the product name as one word.
The brand-name gate requires "Kiro Crew". No test changes behaviour.
@javenciu
javenciu force-pushed the fix/cron-store-keeps-fields-from-a-newer-version branch from 9f5fe51 to c0ce2b7 Compare October 11, 2026 21:00
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 11, 2026

@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.

Approved at head c0ce2b7: PR Readiness is green, no open change requests, and the review lanes passed. (AI-assisted review at bolichen97's request.)

@bolichen97
bolichen97 merged commit dd6b027 into kirodotdev:main Oct 12, 2026
104 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 12, 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.

2 participants