Skip to content

refactor: split history.py into owner modules bound on ConversationLog - #21014

Merged
bolichen97 merged 1 commit into
mainfrom
refactor/linecap-g17-history
Oct 16, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
refactor/linecap-g17-history

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Bring src/kiro_crew/history.py under 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.py is 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

  • No behaviour change: no new feature, no fix, no renamed or removed public name.
  • Not splitting the existing siblings (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.
  • Not changing the existing components' composition (TranscriptReadProjection, SessionMetadataProjection, ...).

What changed (motivation → approach → change)

ConversationLog holds most of history.py, so the split has to divide the class, not just the module. It follows the shape acp/client.py already uses: each moved member's body becomes a module-level function taking self in 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 through kiro_crew.history via kiro_crew._facade_mirror.

Owner Owns
history_files.py transcript stems and Slack aliases, session/archive dirs, archive write and retention, file stamps
history_schema.py metadata-key ownership, row provenance and identity, timestamp spelling and order
history_offload.py the on-loop persistence discipline and the off-loop writers
history_locks.py the transcript lock (in-process + flock), its release and hold witness, delete-in-flight marks
history_derivation.py the header's privacy contract and the derivation seam
history_threads.py the reply-thread sidecar
history_summaries.py the summary sidecar caches
history_append.py append / append_if_absent, write-boundary redaction, inline images
history_marker.py consolidation progress and the retry ledger

history.py keeps 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, a self: ConversationLog annotation, staticmethod(...) binding, six present-tense comment rewords, and type(self).<registry> for the class-level lock registries in history_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.history bound before still resolves to the same object (pinned by test/campaign_facade_inventories/kiro_crew.history.json, which test/test_campaign_facades_base_public_names.py checks), every ConversationLog member 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.py is re-exported by it, so from kiro_crew.history import <name> and kiro_crew.history.<name> return the owner's own object:

  • Reader: src/kiro_crew/dashboard/chat_persistence.py:carry_unowned_metadata -- chat -- imports it from kiro_crew.history, which re-exports history_schema's function (test_chat_persistence_composition_contract)
  • Reader: src/kiro_crew/dashboard/channel_slots.py:carry_provenance -- chat -- re-exported from history_schema, same object (test_chat_persistence_composition_contract)
  • Reader: src/kiro_crew/channel_transcript_migration.py:transcript_sort_key -- chat -- re-exported from history_schema, same object (test_campaign_facades_base_public_names)
  • Reader: src/kiro_crew/dashboard/chat_persistence.py:latest_transcript_ts -- chat -- re-exported from history_schema (test_chat_persistence_composition_contract)
  • Reader: src/kiro_crew/dashboard/session_control.py:metadata_now_iso -- chat -- re-exported from history_schema; a patch of kiro_crew.history.datetime still reaches it (test_history_composition_contract)
  • Reader: src/kiro_crew/dashboard/state.py:mint_row_mid -- chat -- re-exported from history_schema (test_campaign_facades_base_public_names)
  • Reader: src/kiro_crew/dashboard/session_transfer.py:monotonic_transcript_ts -- chat -- re-exported from history_schema; colliding_clock("kiro_crew.history") still patches it (test_transcript_row_ordering)
  • Reader: test/test_history_locking_remediation.py:allow_on_loop_persist -- release -- re-exported from history_offload, same context variable (test_history_locking_remediation)
  • Reader: test/test_knowledge_store_onloop_db.py:on_loop_persist_strict -- release -- re-exported from history_offload (test_knowledge_store_onloop_db)
  • Reader: src/kiro_crew/dashboard/chat_persistence.py:append_off_loop -- chat -- re-exported from history_offload (test_persist_off_loop)
  • Reader: src/kiro_crew/dashboard/cron_inject.py:append_rows_if_absent_off_loop -- cron -- re-exported from history_offload (test_persist_off_loop)
  • Reader: src/kiro_crew/dashboard/workflow_inject.py:append_if_absent_off_loop -- chat -- re-exported from history_offload (test_persist_off_loop)
  • Reader: src/kiro_crew/dashboard/chat_persistence.py:update_metadata_off_loop -- chat -- re-exported from history_offload (test_chat_persistence_composition_contract)
  • Reader: src/kiro_crew/portability.py:memory_mode_from_header_line -- crew page -- re-exported from history_derivation (test_portability_sessions)
  • Reader: src/kiro_crew/dashboard/chat_folder_suggest.py:is_incognito_transcript -- chat -- re-exported from history_derivation; history_projection reads it through the facade at call time (test_messaging_privacy_mode)
  • Reader: src/kiro_crew/messaging/privacy_mode.py:transcript_privacy_mode -- chat -- re-exported from history_derivation (test_messaging_privacy_mode)
  • Reader: src/kiro_crew/dashboard/chat_summary.py:transcript_withholds_derivation -- chat -- re-exported from history_derivation (test_transcript_derivation_seam)
  • Reader: src/kiro_crew/session_storage.py:threads_sidecar_for_stem -- crew page -- re-exported from history_threads (test_session_storage)
  • Reader: src/kiro_crew/dashboard/handlers/sessions.py:transcript_stem -- chat -- re-exported from history_files (test_dashboard_contract_pins)
  • Reader: src/kiro_crew/dashboard/chat_utils.py:transcript_stems -- chat -- re-exported from history_files (test_dashboard_contract_pins)
  • Reader: src/kiro_crew/dashboard/chat_summary.py:transcript_lock_stems -- chat -- re-exported from history_files (test_transcript_derivation_seam)
  • Reader: src/kiro_crew/history_projection.py:can_hold_tab_id_index_entry -- chat -- read through the facade at call time, which re-exports history_files' function (test_tab_id_index_sentinel)
  • Reader: src/kiro_crew/channel_transcript_migration.py:_invalidate_consolidation_offset -- chat -- docstring-only edit (its citation re-pointed to history_marker.py); no migration code changed (test_channel_transcript_migration)

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.py checks each resolves to its home module's object in a fresh interpreter.
  • test/link_screen_sites.py: regenerated (_write_thread_sidecar now in history_threads.py).

Local floor at the commit (Python 3.12, -n 3):

Run Files Result
every tree-scanning test file (tree_scan_* groups and every test that walks src/) 320 25,711 passed, 95 skipped, 5 xfailed
every other test file importing or patching kiro_crew.history / ConversationLog / an owner 225 (+6 re-checks) 12,397 passed, 5 skipped
the rest of local-gate.py's backend related set (752 files) 451 30,895 passed, 48 skipped, 4 xfailed
mypy src/kiro_crew (cold cache) 2,441 no issues
semgrep 1.78, CI configs, over the changed .py files 23 0 new findings against the merge-base, 0 parse errors
this head's code and test patch over main 766c658 (this head sits on 780af13, five commits earlier): the history-focused files, every re-pointed pin and guard, and every test of the new upstream importers, the consolidation split and the consolidation lease 138 9,261 passed, 21 skipped, 5 xfailed

local-gate.py --dry-run selects 752 backend and 754 frontend files (the frontend set comes only from textual references to changed paths; no website/ 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.py passes.

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 archive export) imports the facade and all nine owners from site-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 monkeypatch and restore): 5 runs at -n0, one at -n 3 and one in a shuffled order (seed 1729) pass.

Move audit

move_audit.py (AST, formatting and comments ignored):

src/kiro_crew/history.py: 4207 -> 1135 lines; moved 49.46% (python-ast)
units 226: 179 moved unchanged, 47 changed

Main's history.py is two lines longer than when this PR opened (#21159 added a require_write keyword to the update_metadata_if delegate), 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:

Normalization Units Why
self: ConversationLog annotation 45 the bound function's first parameter, for mypy (imported under TYPE_CHECKING only)
@staticmethod -> staticmethod(...) binding 2 _run_fd_cleanup_off_loop, _sub_offset_for_generation
docstring dedent 37 a method docstring carries four more spaces than the same text at module level
ConversationLog.<registry> -> type(self).<registry> 6 history_locks only (_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, and test_no_subclass_binds_its_own_registry pins that no subclass binds its own
comment-history rewords 3 docstrings + 3 comments six "no longer" phrasings restated in present tense (the gate judges moved lines as added)

A 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 under git diff and git diff --minimal, except src/kiro_crew/history.py: default 267/3339, --minimal 266/3338. The one re-shown line is the blank line between from typing import TYPE_CHECKING, Any, Literal, overload and the first kiro_crew import (granted under L41 for a blank line). Whole diff: 515,372 bytes.

Facade mechanism and logger (L25, L28, L42)

  • Moved module-level names are re-bound in history.py by explicit from kiro_crew.history_<owner> import ... # noqa: F401 blocks, 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 the TYPE_CHECKING manifest.
  • Owners log through logging.getLogger("kiro_crew.history"), the facade's own logger object (35 caplog pins and one direct handler on history.logger depend on that name).
  • The five moved exception classes keep kiro_crew.history as their __module__.

CI path references

N/A — no workflow path filter, AUTOSDE path list or sensitive-change glob names history.py or a history_* file.

Citations and registries edited

  • Prose citations corrected (L29): 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 stale history.py:NNN cites rewritten as symbols, their 12 docs-lint baseline rows pruned by hand).
  • Path re-points (L30), each mutation-proven: 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).
  • Registry rows: src/kiro_crew/security_posture.py _REDACTION_SINKS "Session history (JSONL)" now names history_append.py, where the write-boundary redaction lives; test/campaign_facade_inventories/kiro_crew.history.json holds the facade's inventory (a new file, per the per-facade layout); .github/file-line-cap-baseline.txt loses history.py's row.

References not edited (cost / owned elsewhere)

  • src/kiro_crew/apps/builtins/aws_control/crew/runtime/container/front/transcript.py:101 cites history.py:_safe_key; the function is now in history_files.py. Not edited: a container-source change starts the crew image build.
  • website/src/utils/sessionRefs.ts:49 names INCOGNITO_MEMORY_MODES as living in history.py; it is now in history_derivation.py (still re-exported by history.py). Not edited: a website/ 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 ConversationLog cover 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

  • 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

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 16, 2026 00:11
@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 645f61f
  • What rule changed: no rule changed; one _REDACTION_SINKS row in security_posture.py now names history_append.py instead of history.py, because the write-boundary redaction (_redact_at_write_boundary, called by append/append_if_absent) moved there verbatim.
  • Before -> after (what was allowed/blocked, now): unchanged behaviour; the same function redacts every non-user transcript row before persistence (credentials, exfiltration URLs); only the module path the posture listing names changes.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): the posture page would name the wrong file; no redaction is skipped, since the moved function body and both call sites are byte-identical to BASE (normalized move audit, 224/224 units).
  • Evidence checked (which sandbox result proves it): test_security_posture's drift guard requires every redactor caller be a registered sink; it failed with history_append.py unregistered and passes with the row re-keyed (mutation M4), and test_every_named_sink_module_actually_redacts passes for history_append.py.
  • No regression:
  • Tools still work (which tools/commands were run, result): append/append_if_absent tests (test_history, test_history_coverage, test_persist_off_loop, test_history_inline_attachments) pass on this head with the redaction applied.
  • Backward compatible (old config / old data / old callers still work, how checked): kiro_crew.history still re-exports _redact_at_write_boundary and both redactor names, checked by the base-public-names inventory and test_history_bindings.
  • Existing tests (which suites passed on this head): test_security_posture, test_transcript_derivation_seam, test_history_bindings and the touched history set, 2,330 passed; the full 752-file related backend set passed on the pre-rebase head.
  • How to undo: revert the one row to "history.py" together with the split commit; the row alone cannot be reverted while the redaction lives in history_append.py.

@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/security_posture.py

  • @bolichen97 posted a complete reasoning template for 811d7d6.

@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 811d7d61921cb0aea8f4908e56805ba3db03df51 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 added the readiness: checking Automated validation is still running label Oct 16, 2026
@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 811d7d61921cb0aea8f4908e56805ba3db03df51 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 .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 16, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 811d7d61921cb0aea8f4908e56805ba3db03df51 — 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: PASS

Check the one non-verbatim body edit: history_locks now reads the class-level lock registries through type(self).<registry>, so a subclass that rebinds a registry stops sharing it.

What this change ships

Inventory (8 items) — 8 justified

Intent: bring history.py under the 2,000-line cap that AGENTS.md requires, with no change in behaviour. This is a FIX (a mandated refactor), not an ADDITION.

  1. ConversationLog members move into nine owner modules (history_files … history_marker), bound back onto the class by name — justified
  2. history.py re-exports every moved public function and keeps patching through the facade working, using the existing kiro_crew._facade_mirror (also used by chat_utils.py, mcp_core.py, skills.py and others) — justified
  3. The history.py row is removed from .github/file-line-cap-baseline.txt — justified
  4. The redaction-sink row in security_posture.py now points at history_append.py, so the security posture report names the file that does the redacting — justified
  5. Docs, RFCs, docstrings and comments that cited history.py line numbers now point at the owner files and symbols, which also removes 12 docs-lint baseline rows — justified
  6. The fences in the derivation-seam test and the link-screen site list now cover the owner modules (entries added, none removed) — justified
  7. New test/test_history_bindings.py pins the member inventory and where each member is bound — justified
  8. The history.md spec is updated in the same commit — justified

[FIRST-PRINCIPLES-REVIEWED] 811d7d6

Description read

[DESCRIPTION-READ] d5ed065d1868dc05ff55a131a8f0ca9a6d1cd19b68b68eb25f0886601e3e44f9

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 811d7d61921cb0aea8f4908e56805ba3db03df51 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 811d7d6

Verdict parsed from the review's SHA-scoped output markers for commit 811d7d61921cb0aea8f4908e56805ba3db03df51.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 811d7d61921cb0aea8f4908e56805ba3db03df51: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 811d7d61921cb0aea8f4908e56805ba3db03df51 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 811d7d6

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 811d7d61921cb0aea8f4908e56805ba3db03df51: <one-sentence reason>

@bolichen97
bolichen97 enabled auto-merge (squash) October 16, 2026 00:35
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Punchline: confirm the six rewords and the type(self).<registry> rewrite change no behaviour — fixed (verified before publication)

The six rewords touch comment and docstring text only: three are comments (invisible to the AST) and three are docstrings; a normalized move audit removing only docstring whitespace, the self annotation, the staticmethod binding, those rewords and the registry read finds 224/224 moved units AST-identical to BASE.
type(self).<registry> reads the same class-attribute dict objects ConversationLog.<registry> named: the registries stay on ConversationLog, and test_no_subclass_binds_its_own_registry (AST scan with alias resolution over src+test, plus a runtime __subclasses__ walk, with a self-test) pins that no subclass binds its own.
Behaviour is exercised end to end by the lock tests (test_history_locking_remediation, test_history_cache_fill_race, test_session_storage), all green on this head; the campaign's independent 6-lane review also checked the re-plumb.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Punchline: confirm the full backend suite is green; facade patches reach moved code only through _facade_mirror — fixed (confirmed)

Every check on this head completed: 89 success, 9 skipped, 0 failed, including all 8 Linux and 8 Windows Backend Tests shards and the coverage gate.
Mirror reach is pinned twice: test/test_facade_mirror_guards.py checks every name the test trees patch through kiro_crew.history reaches each owner binding it, and test/test_history_bindings.py checks every owner read of a facade-bound name is a mirror holder (with a self-test), plus behavioural patch-and-undo checks for _FLOCK_ACQUIRE_TIMEOUT_S, THREADS_SIDECAR_MAX_BYTES, _sessions_dir and datetime.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 16, 2026
@bolichen97
bolichen97 force-pushed the refactor/linecap-g17-history branch from 645f61f to af240ac Compare October 16, 2026 08:14
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: passed Eligible automated validation passed for the current revision labels Oct 16, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: af240ac
  • What rule changed: no rule changed; one _REDACTION_SINKS row in security_posture.py now names history_append.py instead of history.py, because the write-boundary redaction (_redact_at_write_boundary, called by append/append_if_absent) moved there verbatim. This head is a mechanical rebase of 645f61f onto main 7e77836; the only conflict was one docs/feature-map/README.md table row, and the 36-file diff is unchanged (+4960/-3400).
  • Before -> after (what was allowed/blocked, now): unchanged behaviour; the same function redacts every non-user transcript row before persistence (credentials, exfiltration URLs); only the module path the posture listing names changes.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): the posture page would name the wrong file; no redaction is skipped, since the moved function body and both call sites are byte-identical to BASE (history.py is unchanged on main since the previous head's base).
  • Evidence checked (which sandbox result proves it): test_security_posture's drift guard requires every redactor caller be a registered sink, and test_every_named_sink_module_actually_redacts passes for history_append.py, both on this head.
  • No regression:
    • Tools still work (which tools/commands were run, result): append/append_if_absent tests (test_history, test_history_coverage, test_persist_off_loop, test_history_inline_attachments) pass on this head with the redaction applied.
    • Backward compatible (old config / old data / old callers still work, how checked): kiro_crew.history still re-exports _redact_at_write_boundary and both redactor names, checked by the base-public-names inventory and test_history_bindings; the names main added imports of since the last head (HUMAN_TURN_META_KEY, metadata_now_iso, transcript_stem) still import from kiro_crew.history.
    • Existing tests (which suites passed on this head): test_security_posture, test_transcript_derivation_seam, test_history_bindings and the touched history set, 944 passed; the PR's changed tests plus the history, facade, line-cap and docs-lint tests, 4,944 passed; isort, flake8, mypy and docs-lint clean.
  • How to undo: revert the one row to "history.py" together with the split commit; the row alone cannot be reverted while the redaction lives in history_append.py.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 16, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Punchline: check that no ConversationLog subclass binds its own _flock_state, _file_locks or _deletes_in_flight — fixed (pinned by a test)

The three registries are bound only on ConversationLog (history.py:317, :339, :351); the two subclasses in the tree (test_slack_dashboard_live_sync.py _FailsFirstAppend, _ThreadRecordingLog) override methods only.
test_history_bindings.py::test_no_subclass_binds_its_own_registry (AST scan with alias resolution over src+test, plus a runtime __subclasses__ walk, with a self-test) fails the build if one ever does; it passes on this head, which is a mechanical rebase of 645f61f (one feature-map row conflict, same 36-file diff).

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Punchline: history_locks reads type(self)._file_locks / _flock_state where base read ConversationLog.<registry> — fixed (pinned by a test)

type(self).<registry> resolves to the same class-attribute dicts as long as no subclass shadows them, and nothing does: the registries are bound only on ConversationLog (history.py:317, :339, :351).
test_history_bindings.py::test_no_subclass_binds_its_own_registry (AST scan over src+test plus a runtime __subclasses__ walk) fails the build on any shadowing subclass; it passes on this head, a mechanical rebase of 645f61f with the same 36-file diff.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 16, 2026
@bolichen97
bolichen97 force-pushed the refactor/linecap-g17-history branch from af240ac to b46cf70 Compare October 16, 2026 10:39
@bolichen97

Copy link
Copy Markdown
Contributor Author

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.

  • Conflicts were rows only: .github/file-line-cap-baseline.txt (both main's removed history_consolidation.py row and this PR's removed history.py row stay removed) and one docs/feature-map/README.md row (main's row, with its history_threads.py path).
  • src/kiro_crew/knowledge/store.py:269: the comment naming the dev-mode guard it keeps quiet now cites history_offload.py, where _on_loop_persist_strict lives.
  • No moved code changed upstream; the split recipe reproduces all ten history*.py files byte-for-byte on the new base.
  • Re-run on this head: 102 test files (the touched set, the consolidation split's tests, the new upstream callers), 7,412 passed; mypy src/kiro_crew clean; comment-history, brand, harness, docs-lint, line-cap and the other script gates pass.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: b46cf70
  • What rule changed: no rule changed; one _REDACTION_SINKS row in security_posture.py now names history_append.py instead of history.py, because the write-boundary redaction (_redact_at_write_boundary, called by append/append_if_absent) moved there verbatim.
  • Before -> after (what was allowed/blocked, now): unchanged behaviour; the same function redacts every non-user transcript row before persistence (credentials, exfiltration URLs); only the module path the posture listing names changes.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): the posture page would name the wrong file; no redaction is skipped, since the moved function body and both call sites are byte-identical to BASE (normalized move audit, 224/224 units).
  • Evidence checked (which sandbox result proves it): test_security_posture's drift guard requires every redactor caller be a registered sink; it failed with history_append.py unregistered and passes with the row re-keyed (mutation M4), and test_every_named_sink_module_actually_redacts passes for history_append.py.
  • No regression:
  • Tools still work (which tools/commands were run, result): append/append_if_absent tests (test_history, test_history_coverage, test_persist_off_loop, test_history_inline_attachments) pass on this head with the redaction applied.
  • Backward compatible (old config / old data / old callers still work, how checked): kiro_crew.history still re-exports _redact_at_write_boundary and both redactor names, checked by the base-public-names inventory and test_history_bindings; the history names main's new callers import (HUMAN_TURN_META_KEY, metadata_now_iso, transcript_stem) still resolve from kiro_crew.history.
  • Existing tests (which suites passed on this head): test_security_posture, test_transcript_derivation_seam, test_history_bindings, the touched history set, the consolidation split's tests and every test of the new upstream importers, 102 files, 7,412 passed; mypy clean; the full 752-file related backend set passed on the first READY head.
  • How to undo: revert the one row to "history.py" together with the split commit; the row alone cannot be reverted while the redaction lives in history_append.py.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 16, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 811d7d6
  • What rule changed: no rule changed; one _REDACTION_SINKS row in security_posture.py now names history_append.py instead of history.py, because the write-boundary redaction (_redact_at_write_boundary, called by append/append_if_absent) moved there verbatim.
  • Before -> after (what was allowed/blocked, now): unchanged behaviour; the same function redacts every non-user transcript row before persistence (credentials, exfiltration URLs); only the module path the posture listing names changes.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): the posture page would name the wrong file; no redaction is skipped, since the moved function body and both call sites are byte-identical to BASE.
  • Evidence checked (which sandbox result proves it): test_security_posture's drift guard requires every redactor caller be a registered sink, and test_every_named_sink_module_actually_redacts passes for history_append.py, on this head.
  • No regression:
    • Tools still work (which tools/commands were run, result): append/append_if_absent tests (test_history, test_history_coverage, test_persist_off_loop, test_history_inline_attachments) pass on this head with the redaction applied.
    • Backward compatible (old config / old data / old callers still work, how checked): kiro_crew.history still re-exports _redact_at_write_boundary and both redactor names (test_history_bindings); main's new consolidation-lease caller imports transcript_lock_stems from kiro_crew.history and it still resolves (test_history_consolidation_lease passes).
    • Existing tests (which suites passed on this head): rebased onto main 780af13. Only change beyond the rebase: two test_history_bindings signature pins updated for main's require_write / -> bool change to update_metadata_if and _update_metadata_locked (delegation already carried it). test_security_posture, test_security_gate_liveness, test_transcript_derivation_seam, test_history_bindings, the history/consolidation/attachment set: 2,444 passed locally; mypy, black, isort, flake8, file-line-cap and docs-lint clean.
  • How to undo: revert the one row to "history.py" together with the split commit; the row alone cannot be reverted while the redaction lives in history_append.py.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 16, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Punchline: check the one non-verbatim body edit — history_locks reads the class-level lock registries through type(self).<registry>, so a subclass that rebinds a registry stops sharing it — fixed (confirmed on this head)

No subclass rebinds one: test_no_subclass_binds_its_own_registry scans src and test with an AST walk that resolves aliases, and walks ConversationLog.__subclasses__() at run time; its self-test (test_the_subclass_registry_scan_can_fail) shows the scan goes red on a planted rebinding.
With no rebinding subclass, type(self).<registry> and the BASE spelling ConversationLog.<registry> name the same dict objects, so every instance still shares one lock and generation table; an owner cannot import the class at run time, which is why the read is spelled through type(self).
The normalized move audit counts exactly these six members as the only type(self) rewrites (224/224 units otherwise identical), and the lock suites (test_history_locking_remediation, test_history_cache_fill_race, test_session_storage) pass on this patch.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Acknowledged: this waits for a maintainer's sign-off. The current head is 811d7d61921cb0aea8f4908e56805ba3db03df51 (the same code and test patch as b46cf70088, plus #21159's two delegate lines on main). For the reviewer, the evidence on the two areas the hold names:

  • Write-boundary redaction: _redact_at_write_boundary and both its call sites (append, append_if_absent) moved verbatim into history_append.py; the _REDACTION_SINKS row follows it so the posture report names the file that redacts. test_security_posture's drift guard fails with that module unregistered and passes with the row re-keyed. Details: the Sensitive change review comment for this head.
  • Delete-in-flight marks and the flock registries: the registries stay ConversationLog class attributes; the moved bodies in history_locks.py read them through type(self), and test_no_subclass_binds_its_own_registry (with a self-test) pins that no subclass rebinds one, so every instance shares the same tables as before.

@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: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Oct 16, 2026
@bolichen97
bolichen97 merged commit 0b5d524 into main Oct 16, 2026
113 of 115 checks passed
@bolichen97
bolichen97 deleted the refactor/linecap-g17-history branch October 16, 2026 22:24
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 16, 2026
iamwhatever added a commit to jeeshofone/KiroCrew that referenced this pull request Oct 22, 2026
…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>
jeeshofone added a commit to jeeshofone/KiroCrew that referenced this pull request Oct 23, 2026
…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>
jeeshofone added a commit to jeeshofone/KiroCrew that referenced this pull request Oct 28, 2026
…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>
jeeshofone added a commit to jeeshofone/KiroCrew that referenced this pull request Oct 28, 2026
…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>
iamwhatever added a commit to jeeshofone/KiroCrew that referenced this pull request Oct 29, 2026
…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>
jeeshofone added a commit to jeeshofone/KiroCrew that referenced this pull request Nov 1, 2026
…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>
jeeshofone added a commit to jeeshofone/KiroCrew that referenced this pull request Nov 2, 2026
…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>
jeeshofone added a commit to jeeshofone/KiroCrew that referenced this pull request Nov 2, 2026
…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>
bolichen97 pushed a commit that referenced this pull request Nov 2, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants