eb8d628c97
refactor(hermes_state): restore WHY comments dropped by round-2 sub-branches
...
Comment/docstring-only (AST-identical): surrogate-scrub rationale, persisted
marker stripping invariant, generation counter upgrade semantics, CJK marker
empty-vs-populated rule, WAL 0-page ordering precondition, repair backup
live-connection case, telegram topic delete precondition, mixed-mode
corruption definition, and similar.
2026-09-02 16:48:30 -07:00
d15c61b5dc
refactor(state): split SessionDB into domain mixins and free-function modules; unify SQL boilerplate
...
hermes_state.py 17,220 -> 6,442 LOC. Behavior-neutral: every moved body is
AST-identical to the original, verified per extraction.
SessionDB core
- _write_sql / _write_rowcount / _read_one / _read_all replace ~120 copies of
the `def _do(conn): conn.execute(...)` + `_execute_write(_do)` and
`with self._read_ctx() as conn: row = conn.execute(...).fetchone()` shapes.
- _set_lineage_column replaces four copies of the recursive compression-lineage
UPDATE (archived / pinned / hidden / last_read_at).
- _read_session_number unifies the three compression counter readers.
- Dead (zero refs repo-wide): restore_rewound, delete_gateway_routing_entries,
_is_duplicate_replayed_user_message, SessionPortabilityMixin.get_first_assistant_text.
New mixins bound onto SessionDB via the MRO (logger name stays "hermes_state"):
hermes_state_messages SessionMessagesMixin 48 methods
hermes_state_compression SessionCompressionMixin 30
hermes_state_gateway SessionGatewayMixin 26
hermes_state_maintenance SessionMaintenanceMixin 13
hermes_state_usage SessionUsageMixin 12
hermes_state_titles SessionTitlesMixin 13
hermes_state_telegram SessionTelegramTopicsMixin 11
Origin-internal symbols resolve through a lazy `from hermes_state import ...`
inside the few methods that need them (no import cycle).
New free-function modules, every name re-imported into hermes_state so
`hermes_state.<name>` (and test monkeypatches on it) keep working; intra-module
calls to patched helpers go through the lazy origin import:
hermes_state_repair repair/backup/preflight (43 defs)
hermes_state_wal journal-mode / PRAGMA policy (33 defs)
hermes_state_dbfile header probes, zeroed-db quarantine, stats, holders (21 defs)
Existing mixins: search — shared FTS MATCH/LIKE builders, unified rebuild
status/step/finish engines, state_meta helpers; schema — one legacy/v23 FTS init
branch, shared _live_pk_columns, Row/tuple dual access dropped; portability —
shared _PREVIEW_RAW_SUBQUERY_SQL and _rich_row; common — single
stat_db_file_identity (was 3 copies), AUTO_VACUUM_MIN_FREELIST_RATIO.
Docstrings/comments hand-compacted (AST-identical) keeping every invariant,
ordering rule, failure mode and WHY. Schema SQL, migration order and PRAGMAs
untouched. test_repair_path_has_no_bare_connects repointed to hermes_state_repair.
2026-09-02 13:32:13 -07:00
Teknium