߲jB5dZddlZddlZddlZdZgedZdedefdZdZ e d d d fZ dejdefd Z dedefd Z dedefdZdZdeezdzdefdZdZdZeeddZej,dZdefdZGddeZGddeZGddeZGddeZGdd eZGd!d"eZd#Z d$Z!d%Z"d&Z#d'e#d(Z$Gd)d*ejJZ&d+Z'ed,fed-fed.fed/fed0fe&d1ffZ(d2d3d4d5d6ed1fd7fZ)defd8Z*y)9zException types and error-classification predicates for the state store. Shared by hermes_state and its mixins; string predicates match wrapped RPC strings as well as live sqlite3 exceptions.N)zmalformed database schemaz database disk image is malformedexcreturnclttjxrtfdtDS)uMalformed-schema OR generic corrupt-image error. Diagnostics / offline recovery only — runtime repair must use :func:`is_malformed_schema_error`.c3TK|]}|tjv!ywNstrlower.0markerrs 8/home/ubuntu/.hermes/hermes-agent/hermes_state_errors.py z(is_malformed_db_error..&:'-#c(.."":%() isinstancesqlite3 DatabaseErrorany_MALFORMED_DB_MARKERSrs`ris_malformed_db_errorrs3 c700 1 c:1F:7zdisk i/o errorzdatabase is lockedzdatabase table is lockedbusyc8dt|jvS)zTransient engine error on contended WAL appends (retries like locked/busy); message-scoped because some builds raise it as InterfaceError.zno more rows availablerrs r_is_no_more_rowsr%s $s3x~~'7 77rclttjxrtfdtDS)zm"Busy right now", not "damaged": one predicate so retry and the HTTP 503-vs-500 split cannot drift apart.c3TK|]}|tjv!ywrrr s rrz,is_transient_sqlite_error...s&='-#c(..""=r)rrOperationalErrorr_TRANSIENT_SQLITE_MARKERSrs`ris_transient_sqlite_errorr!+s3 c733 4 =1J=:rclttjxrtfdtDS)zOnly SQLite's explicit malformed-schema text: a generic "disk image is malformed" may be any B-tree page, so runtime repair must fail closed on it.c3TK|]}|tjv!ywrrr s rrz,is_malformed_schema_error..6rr)rrrr_MALFORMED_SCHEMA_MARKERSrs`ris_malformed_schema_errorr%3s3 c700 1 c:1J:7r)zno space left on deviceznot enough spacezdatabase or disk is fullz disk fullz full diskenospcc|yt|trt|ddtjk(ryt|t r|n t |j tfdtDS)zFDisk-full / ENOSPC: OSError(ENOSPC), SQLITE_FULL, or matching strings.NFerrnoTc3&K|]}|v ywr)r r lowereds rrz%is_disk_full_error..IsBVv B) rOSErrorgetattrr(ENOSPCr r r_DISK_FULL_MARKERS)rr+s @ris_disk_full_errorr1Bs[ {#wGC$$?5<<$O c*sC??AG B/AB BBr) locked compressioncompression_closed turn_leasecorrupt fts_indexreplaced deleted_waldiskunknown) malformedzfile is not a databaseznot a databasezdatabase corruptionSQLITE_CORRUPT_VTABi z\bmessages_fts\w*c|yt|dd}| |tk(St|tr|n t|j t j syjdrdvrytfdtDS)aCorruption SQLite itself attributes to the FTS index layer: the ONE provenance rule shared by the write-repair gate (``SessionDB._is_fts_write_corruption_error``), the gateway transcript retry and :func:`classify_persistence_error` (#96038, #97794). A known result code outranks prose: ``SQLITE_CORRUPT_VTAB`` is FTS-scoped even with the generic malformed-image text older SQLite builds emit, while bare ``SQLITE_CORRUPT`` / ``SQLITE_NOTADB`` carry no object scope and any other known code contradicts FTS-looking prose, so both fail closed. Only without a code (Python < 3.11, RPC-wrapped strings) does the text decide, and then only an ``fts5:`` corruption report or a corruption marker that names a ``messages_fts*`` object counts. NFsqlite_errorcodezfts5:r6Tc3&K|]}|v ywrr*r r texts rrz1is_fts_scoped_corruption_error..zsC&v~Cr,) r.r=rr r _FTS_OBJECT_REsearch startswithr_DB_CORRUPTION_MARKERS) exc_or_strcoderBs @ris_fts_scoped_corruption_errorrIds :14 8D ***$Z5J3z? Q Q SD   & wI$5 C,BC CCrc(eZdZdZdeffd ZxZS)CompressionSessionClosedErrorz@A durable write targeted a parent already closed by compression. session_idc:||_t| d|dy)NzSession zP is closed by compression; adopt its live continuation before appending messages)rLsuper__init__)selfrL __class__s rrOz&CompressionSessionClosedError.__init__s*$ zn%D D r)__name__ __module__ __qualname____doc__r rO __classcell__)rQs@rrKrK}sJ 3  rrKceZdZdZy)CompressionSessionBusyErrorz>A non-owner tried to write while compression owns the session.NrRrSrTrUr*rrrXrXsHrrXceZdZdZy)!SessionCompressionInProgressErroru+A concurrent writer collided with a *live* compression lock — transient (the compressor publishes in seconds; ``_execute_write`` waits), unlike the parent class's other case (a compressor whose own lease is gone: permanent, fail fast). Subclassing keeps every existing handler working.NrYr*rrr[r[sErr[ceZdZdZy)SessionTurnLeaseLostErrorzA transcript write presented a turn-lease holder that no longer owns it. Fail-fast fencing (no ``_execute_write`` retry): a later writer may already be persisting a newer turn, and landing this one would interleave a stale reply.NrYr*rrr]r]sXrr]ceZdZdZy)StateDbReplacedErrorzThe state.db path no longer names the file this SessionDB opened (out-of-band cp/mv/restore). In-place FTS repair and fail-open trigger dropping cannot fix a generation mismatch; they amplify it.NrYr*rrr_r_sCrr_ceZdZdZy)DeletedWalGenerationErrorasA live process holds a deleted state.db-wal / -shm generation. Opening or writing through this handle would mint a second WAL inode (split-brain -> intermittent SQLITE_CORRUPT / IOERR). Stop the writers; never unlink the WAL yourself. Subclasses StateDbReplacedError so every consumer that diverts transcripts on a replaced store handles this identically.NrYr*rrrarasArraDdb_file_generationzFATAL: state.db was replaced underneath the gateway; refusing further writes to this file. Divert transcripts to sessions/.jsonl (and the gateway pending_messages spool) and restore or reopen after operator intervention.zNhttps://hermes-agent.nousresearch.com/docs/user-guide/session-storage-recoveryaFATAL: session storage stopped writing because another Hermes process still holds a deleted state.db-wal or state.db-shm inode (an old copy of the write-ahead log). Nothing is lost: quit every Hermes process on this profile (Desktop app, gateway, dashboard, cron), run `hermes doctor` (it names the processes still holding the log), then start Hermes again. Do not delete the WAL yourself and do not run `hermes doctor --fix` while they are running. Guide: z Detail: the path names a different (or missing) generation than the one this process holds open; opening or writing through it would mint a second WAL (split-brain). database.journal_mode: delete is operator containment, not a new default.ceZdZdZy)StateDbCorruptErroruA live SessionDB observed structural (non-FTS, non-replaced) corruption and is quarantined: sticky for the handle's life — writes fail fast, no reopen, no close-time checkpoint (a handle that kept writing after the first error checkpointed 15 pages under wrong page numbers and turned a readable file into "file is not a database"; SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE on 3.12+ also stops SQLite's own). Subclasses sqlite3.DatabaseError so every degrade path keeps working. Recovery boundary: restart on a repaired/restored file. Stopping the writes is what prevents that; skipping the explicit checkpoint is the second line of defence. SQLite still runs its own last-connection checkpoint inside ``close()`` (and deletes the ``-wal`` sidecar) unless ``SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE`` is set — Python exposes it via ``Connection.setconfig()`` on 3.12+, so quarantine disables the close-time checkpoint there and the WAL survives on disk for forensics; on 3.11 the internal checkpoint is unavoidable (post-quarantine it can only carry pre-corruption committed frames, since no further writes are accepted). See #90837. NrYr*rrreresrreaFATAL: state.db reported structural corruption (database disk image is malformed outside the FTS shadow tables) on a live handle; refusing further writes, automatic reopen, and the close-time WAL checkpoint on this file. Stop the gateway, then run `hermes sessions recover --source --inspect-only` or restore a snapshot. Unwritten transcripts are diverted to sessions/.jsonl (and the gateway pending_messages spool).r5r4r3r9r8r6))z turn leaser5))zclosed by compressionr4))zbeing compressedzcompression leaser3))zdeleted state.db-walzdeleted state.db-shmr9))zwas replaced underneathr8))r2rr2c|ytD]\}}t||s|cSt|ryt|j t D]\}}t fd|Ds|cSt|st fddDryy)a:Coarse cause bucket (PERSISTENCE_ERROR_CAUSES) so the user's guidance matches: "locked" = busy, retry; "disk" = full/read-only/permissions; "compression" = a live lease refused the write; "compression_closed" = adopt the rotated session id; "turn_lease" = fencing, not storage; "corrupt" = file damage (repair path, not disk space); "fts_index" = SQLite scoped the corruption to the FTS index (the transcript store is not damaged); "replaced" = main-file replacement; "deleted_wal" = a retired sidecar generation requiring capture inspection.r;r7c3&K|]}|v ywrr*rAs rrz-classify_persistence_error.. s4&v~4r,c3&K|]}|v ywrr*)r mrBs rrz-classify_persistence_error..s,b1Q$Y,br,)r:readonlyz read-onlyr:)_PERSISTENCE_CAUSE_BY_TYPErrIr r _PERSISTENCE_CAUSE_BY_PHRASErr1)rGexc_typecausemarkersrBs @rclassify_persistence_errorrps 6% j( +L &j1 z? "D6 4G4 4L*%,b@a,b)b r)+rUr(rerr$r BaseExceptionboolr_DISK_IO_ERROR_MARKERr Errorrr!r%r0r r1PERSISTENCE_ERROR_CAUSESrFr.r=compilerCrI RuntimeErrorrKrXr[r]r_ra_STATE_DB_APPLICATION_ID_OFFSET_STATE_DB_GENERATION_KEY_STATE_DB_REPLACED_MSGSTORAGE_RECOVERY_DOCS_URL_DELETED_WAL_GENERATION_MSGrre_STATE_DB_CORRUPT_MSGrkrlrpr*rrrs%/ ;X3X5WX}) /1KV 8'--8D8 =T=T CMC/$6C4C g'E.Y'" cr