Repository navigation
refactor: split history.py into owner modules bound on ConversationLog - #21014
Conversation
Sensitive change review
|
Sensitive Change ReviewSensitive files changed:
|
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check. [DESIGN-REVIEWED] 811d7d6 Description read[DESCRIPTION-READ] 957a6fd07c5eca1a94c9a6aee5fe50ee84a6a58b658cf20a57dd094882b1f703 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) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Check the one non-verbatim body edit: What this change shipsInventory (8 items) — 8 justifiedIntent: bring
[FIRST-PRINCIPLES-REVIEWED] 811d7d6 Description read[DESCRIPTION-READ] d5ed065d1868dc05ff55a131a8f0ca9a6d1cd19b68b68eb25f0886601e3e44f9 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: |
|
|
645f61f to
af240ac
Compare
Sensitive change review
|
|
|
af240ac to
b46cf70
Compare
|
Rebased onto main 0ad64e6 (G16's consolidation split #20868). This head supersedes the outside rebase at af240ac, which predated that merge and carried the earlier patch.
|
Sensitive change review
|
Sensitive change review
|
|
|
Acknowledged: this waits for a maintainer's sign-off. The current head is
|
…cements Rotation, compaction, clear_closed, _update_metadata_locked, the selection rollback and the channel transcript migration merge now replace the whole transcript synced (history_rewrite.rewrite_transcript). The three hot metadata writes (mark_consolidated, the sub-offset write, update_metadata) stage and sync the replacement before taking the session lock and rename under it only if the file is unchanged (rewrite_metadata_line). A failed archive write or sync removes its file, and archive_dedup is required. Rebased onto main after kirodotdev#21014 split history.py: the _archive_lines change lands in history_files.py and the marker writes in history_marker.py; the TestReducedLockHold pins move to test_history_locking_remediation_locked_section.py after kirodotdev#21783. Co-authored-by: iamwhatever <iamwhatever@users.noreply.github.com>
…cements Rotation, compaction, clear_closed, _update_metadata_locked, the selection rollback and the channel transcript migration merge now replace the whole transcript synced (history_rewrite.rewrite_transcript). The three hot metadata writes (mark_consolidated, the sub-offset write, update_metadata) stage and sync the replacement before taking the session lock and rename under it only if the file is unchanged (rewrite_metadata_line). A failed archive write or sync removes its file, and archive_dedup is required. Rebased onto main after kirodotdev#21014 split history.py: the _archive_lines change lands in history_files.py and the marker writes in history_marker.py; the TestReducedLockHold pins move to test_history_locking_remediation_locked_section.py after kirodotdev#21783. Co-authored-by: iamwhatever <iamwhatever@users.noreply.github.com>
…cements Rotation, compaction, clear_closed, _update_metadata_locked, the selection rollback and the channel transcript migration merge now replace the whole transcript synced (history_rewrite.rewrite_transcript). The three hot metadata writes (mark_consolidated, the sub-offset write, update_metadata) stage and sync the replacement before taking the session lock and rename under it only if the file is unchanged (rewrite_metadata_line). A failed archive write or sync removes its file, and archive_dedup is required. Rebased onto main after kirodotdev#21014 split history.py: the _archive_lines change lands in history_files.py and the marker writes in history_marker.py; the TestReducedLockHold pins move to test_history_locking_remediation_locked_section.py after kirodotdev#21783. Co-authored-by: iamwhatever <iamwhatever@users.noreply.github.com>
…cements Rotation, compaction, clear_closed, _update_metadata_locked, the selection rollback and the channel transcript migration merge now replace the whole transcript synced (history_rewrite.rewrite_transcript). The three hot metadata writes (mark_consolidated, the sub-offset write, update_metadata) stage and sync the replacement before taking the session lock and rename under it only if the file is unchanged (rewrite_metadata_line). A failed archive write or sync removes its file, and archive_dedup is required. Rebased onto main after kirodotdev#21014 split history.py: the _archive_lines change lands in history_files.py and the marker writes in history_marker.py; the TestReducedLockHold pins move to test_history_locking_remediation_locked_section.py after kirodotdev#21783. Co-authored-by: iamwhatever <iamwhatever@users.noreply.github.com>
…cements Rotation, compaction, clear_closed, _update_metadata_locked, the selection rollback and the channel transcript migration merge now replace the whole transcript synced (history_rewrite.rewrite_transcript). The three hot metadata writes (mark_consolidated, the sub-offset write, update_metadata) stage and sync the replacement before taking the session lock and rename under it only if the file is unchanged (rewrite_metadata_line). A failed archive write or sync removes its file, and archive_dedup is required. Rebased onto main after kirodotdev#21014 split history.py: the _archive_lines change lands in history_files.py and the marker writes in history_marker.py; the TestReducedLockHold pins move to test_history_locking_remediation_locked_section.py after kirodotdev#21783. Co-authored-by: iamwhatever <iamwhatever@users.noreply.github.com>
…cements Rotation, compaction, clear_closed, _update_metadata_locked, the selection rollback and the channel transcript migration merge now replace the whole transcript synced (history_rewrite.rewrite_transcript). The three hot metadata writes (mark_consolidated, the sub-offset write, update_metadata) stage and sync the replacement before taking the session lock and rename under it only if the file is unchanged (rewrite_metadata_line). A failed archive write or sync removes its file, and archive_dedup is required. Rebased onto main after kirodotdev#21014 split history.py: the _archive_lines change lands in history_files.py and the marker writes in history_marker.py; the TestReducedLockHold pins move to test_history_locking_remediation_locked_section.py after kirodotdev#21783. Co-authored-by: iamwhatever <iamwhatever@users.noreply.github.com>
…cements Rotation, compaction, clear_closed, _update_metadata_locked, the selection rollback and the channel transcript migration merge now replace the whole transcript synced (history_rewrite.rewrite_transcript). The three hot metadata writes (mark_consolidated, the sub-offset write, update_metadata) stage and sync the replacement before taking the session lock and rename under it only if the file is unchanged (rewrite_metadata_line). A failed archive write or sync removes its file, and archive_dedup is required. Rebased onto main after kirodotdev#21014 split history.py: the _archive_lines change lands in history_files.py and the marker writes in history_marker.py; the TestReducedLockHold pins move to test_history_locking_remediation_locked_section.py after kirodotdev#21783. Co-authored-by: iamwhatever <iamwhatever@users.noreply.github.com>
…cements Rotation, compaction, clear_closed, _update_metadata_locked, the selection rollback and the channel transcript migration merge now replace the whole transcript synced (history_rewrite.rewrite_transcript). The three hot metadata writes (mark_consolidated, the sub-offset write, update_metadata) stage and sync the replacement before taking the session lock and rename under it only if the file is unchanged (rewrite_metadata_line). A failed archive write or sync removes its file, and archive_dedup is required. Rebased onto main after kirodotdev#21014 split history.py: the _archive_lines change lands in history_files.py and the marker writes in history_marker.py; the TestReducedLockHold pins move to test_history_locking_remediation_locked_section.py after kirodotdev#21783. Co-authored-by: iamwhatever <iamwhatever@users.noreply.github.com>
…archives (#27514) * fix(history): sync rotation, compaction and metadata transcript replacements Rotation, compaction, clear_closed, _update_metadata_locked, the selection rollback and the channel transcript migration merge now replace the whole transcript synced (history_rewrite.rewrite_transcript). The three hot metadata writes (mark_consolidated, the sub-offset write, update_metadata) stage and sync the replacement before taking the session lock and rename under it only if the file is unchanged (rewrite_metadata_line). A failed archive write or sync removes its file, and archive_dedup is required. Rebased onto main after #21014 split history.py: the _archive_lines change lands in history_files.py and the marker writes in history_marker.py; the TestReducedLockHold pins move to test_history_locking_remediation_locked_section.py after #21783. Co-authored-by: iamwhatever <iamwhatever@users.noreply.github.com> * fix(history): free the stale staged copy before the locked metadata rebuild GPT 6.1 on 185dd9b: when a write lands between staging and the lock, rewrite_metadata_line kept the stale staged file until its finally while rewrite_transcript wrote a second whole copy, so a disk with room for one replacement failed the edit with ENOSPC. Discard it first. Pinned by test_the_fallback_frees_the_stale_staged_copy_before_writing (3 writes; red without the fix). Also keep atomic_write and replace_with_retry on the history_projection facade: test_campaign_facades_base_public_names pins every public name the base facade served. --------- Co-authored-by: iamwhatever <iamwhatever@users.noreply.github.com>
Problem / Motivation
Goal: Bring
src/kiro_crew/history.pyunder the 2,000-line cap (4,205 -> 1,133 lines) without changing how the conversation history behaves or how callers and tests reach it.history.pyis one of the files over the repo's 2,000-line rule. Most of it was one 2,566-line class,ConversationLog, so moving whole top-level definitions out could not get it under the cap.Why it matters
The file changes many times a week, so every feature PR touching session transcripts lands in a 4,000-line file over the cap, and the next one makes it worse. Splitting it by responsibility gives new work a home that is not the facade, and stops the line-cap baseline row from growing.
Not a goal
history_consolidation.py,history_projection.py,history_search.py,history_cache.py,history_rewrite.py); other line-cap scopes own those that are over the cap.TranscriptReadProjection,SessionMetadataProjection, ...).What changed (motivation → approach → change)
ConversationLogholds most ofhistory.py, so the split has to divide the class, not just the module. It follows the shapeacp/client.pyalready uses: each moved member's body becomes a module-level function takingselfin an owner module, and the class binds it by name (append = _history_append.append). Every member stays an attribute of the one class, so callers, subclasses and every class or instance patch keep working; module globals stay reachable and patchable throughkiro_crew.historyviakiro_crew._facade_mirror.history_files.pyhistory_schema.pyhistory_offload.pyhistory_locks.pyflock), its release and hold witness, delete-in-flight markshistory_derivation.pyhistory_threads.pyhistory_summaries.pyhistory_append.pyappend/append_if_absent, write-boundary redaction, inline imageshistory_marker.pyhistory.pykeeps the class's identity and construction,_path, the process-wide registries, the delegates to the existing components, and every name it bound before. The moved bodies are verbatim apart from: dedent, aself: ConversationLogannotation,staticmethod(...)binding, six present-tense comment rewords, andtype(self).<registry>for the class-level lock registries inhistory_locks. The spec (docs/system-specs/modules/history.md), the docs that cited moved code, the redaction-sink registry row, the derivation-seam fence and the line-cap baseline move with the code.Backwards compatibility
Compatible: every name
kiro_crew.historybound before still resolves to the same object (pinned bytest/campaign_facade_inventories/kiro_crew.history.json, whichtest/test_campaign_facades_base_public_names.pychecks), everyConversationLogmember keeps its kind and signature (test/test_history_bindings.py), and a patch through the facade reaches the moved code (_facade_mirror,test/test_facade_mirror_guards.py).Each public module-level function that left
history.pyis re-exported by it, sofrom kiro_crew.history import <name>andkiro_crew.history.<name>return the owner's own object:Tests
test/test_history_bindings.py(new): the frozen member inventory (kind, signature digest, owner), each bound member IS its owner's function, no class-only construct in a moved body, no runtime facade import, owner import order, the field docstrings, the logger, moved-class__module__, no subclass binding its own lock registry, and the mirror's reach — each scan with a self-test that shows it can fail.test/test_transcript_derivation_seam.py: the moved plain reads named as plumbing in their new homes; the publication-hold scan reads the facade and every owner.test/campaign_facade_inventories/kiro_crew.history.json(new): the facade's frozen inventory, 104 base public names and 102 re-bound homes;test_campaign_facades_base_public_names.pychecks each resolves to its home module's object in a fresh interpreter.test/link_screen_sites.py: regenerated (_write_thread_sidecarnow inhistory_threads.py).Local floor at the commit (Python 3.12,
-n 3):tree_scan_*groups and every test that walkssrc/)kiro_crew.history/ConversationLog/ an ownerlocal-gate.py's backend related set (752 files)mypy src/kiro_crew(cold cache).pyfileslocal-gate.py --dry-runselects 752 backend and 754 frontend files (the frontend set comes only from textual references to changed paths; nowebsite/file changed), so per the campaign rule the floor above runs instead and CI runs the rest. Comment-history, brand (incl.--test), harness parity, subprocess-encoding, agent-sdk boundary, sync-io-in-async, black gate, memory-store seam, file-line-cap, docs-lint (incl.--test), feature-map and focus-cue gates all pass;test/test_flake_pattern_ratchet.pypasses.Per-module line coverage over the 40 most history-focused test files: history.py 97.1%, history_append 97.3%, history_derivation 100%, history_files 93.1%, history_locks 100%, history_marker 90.8%, history_offload 96.7%, history_schema 100%, history_summaries 93.7%, history_threads 94.8% (the CI floor is 80% per file).
The installed wheel (built from a
git archiveexport) imports the facade and all nine owners fromsite-packages.Each re-pointed or joined pin was proven to reach the moved code: 19 mutations (a planted violation in the owner, or the old row restored) each turn the check red — the PLUMBING fence (2), the publication-hold scan, the redactor census, the sync-io gate over each of the nine owners, the kill and dir-fd ratchets, the persistence-writer inventory, the link-screen baseline, and two of the new binding scans.
No test was moved, so no flaky shape moved (determinism proof N/A for moved tests). The new test is static (AST and identity checks; its patch checks use
monkeypatchand restore): 5 runs at-n0, one at-n 3and one in a shuffled order (seed 1729) pass.Move audit
move_audit.py(AST, formatting and comments ignored):Main's
history.pyis two lines longer than when this PR opened (#21159 added arequire_writekeyword to theupdate_metadata_ifdelegate), and the facade keeps those lines, so the counts read 4,207 -> 1,135.The 47 "changed" units are exactly the 47 bound members. A normalized audit removes only the binding's own changes from both sides and finds all 224 non-import units identical to BASE:
self: ConversationLogannotationTYPE_CHECKINGonly)@staticmethod->staticmethod(...)binding_run_fd_cleanup_off_loop,_sub_offset_for_generationConversationLog.<registry>->type(self).<registry>history_locksonly (_file_lock,_locked_stem,_schedule_flock_release,delete_in_flight_window,delete_in_flight,_flock_hold_witness); an owner cannot import the class at run time, the registries stay class attributes, andtest_no_subclass_binds_its_own_registrypins that no subclass binds its ownA comment audit finds every BASE comment of every moved unit in its owner unchanged apart from those three comment rewords, and every comment of every kept unit still in the facade.
Diff shape (L36)
Every changed file has the same
+/-counts undergit diffandgit diff --minimal, exceptsrc/kiro_crew/history.py: default 267/3339,--minimal266/3338. The one re-shown line is the blank line betweenfrom typing import TYPE_CHECKING, Any, Literal, overloadand the firstkiro_crewimport (granted under L41 for a blank line). Whole diff: 515,372 bytes.Facade mechanism and logger (L25, L28, L42)
history.pyby explicitfrom kiro_crew.history_<owner> import ... # noqa: F401blocks, so mypy sees every BASE name through the facade; the two globals an owner rebinds at run time (_last_cleanup,_on_loop_warn_last) are served by the mirror and listed in theTYPE_CHECKINGmanifest.logging.getLogger("kiro_crew.history"), the facade's own logger object (35caplogpins and one direct handler onhistory.loggerdepend on that name).kiro_crew.historyas their__module__.CI path references
N/A — no workflow path filter, AUTOSDE path list or sensitive-change glob names
history.pyor ahistory_*file.Citations and registries edited
src/kiro_crew/channel_transcript_migration.py,src/kiro_crew/on_loop_db.py(3),src/kiro_crew/dashboard/chat_api/slot_detail.py(2),test/test_dashboard_chat_unflushed_tail.py(1),test/test_knowledge_store_onloop_db.py(3),test/test_channel_row_identity.py(1),test/test_lazy_data_home_paths.py(1),test/test_persist_off_loop.py(1),src/kiro_crew/mcp_core_parts/history.py(1),src/kiro_crew/knowledge/store.py(1); docs:history.md,code-style.md,session-summary.md,knowledge.md,feature-map/README.md,soft-stop.md, and four RFCs (rfc-resumable-subagent-sessions.md's 12 stalehistory.py:NNNcites rewritten as symbols, their 12 docs-lint baseline rows pruned by hand).test/test_transcript_derivation_seam.py(six PLUMBING rows; the publication-hold scan joined with the owners),test/link_screen_sites.py(regenerated; one row).src/kiro_crew/security_posture.py_REDACTION_SINKS"Session history (JSONL)" now nameshistory_append.py, where the write-boundary redaction lives;test/campaign_facade_inventories/kiro_crew.history.jsonholds the facade's inventory (a new file, per the per-facade layout);.github/file-line-cap-baseline.txtloseshistory.py's row.References not edited (cost / owned elsewhere)
src/kiro_crew/apps/builtins/aws_control/crew/runtime/container/front/transcript.py:101citeshistory.py:_safe_key; the function is now inhistory_files.py. Not edited: a container-source change starts the crew image build.website/src/utils/sessionRefs.ts:49namesINCOGNITO_MEMORY_MODESas living inhistory.py; it is now inhistory_derivation.py(still re-exported byhistory.py). Not edited: awebsite/comment change starts the frontend lanes for a backend split. Tracked on docs: fix comment citations left pointing at files the line-cap splits moved #21320.Manual verification
N/A — a structural move; the unit suites that exercise
ConversationLogcover it, and the installed wheel imports every new module (see Tests).Related Issues
Part of #20192
Follow-up: #21320 (the deferred comment citation under "References not edited")
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)