+ jHj@Rt^RIt^RIt^RItR>t.]ORN5tRRltRt]RRR3t]P]P3t R R lt R R lt R RltRRltRRltR?tRRltR@tRAt]!]RR4t]P.!R4tRRlt!R R!]4t!R"R#]4t!R$R%]4t!R&R']4t!R(R)]4t!R*R+]4t !R,R-]4t!!R.R/]4t"!R0R1]4t#!R2R3]#4t$^Dt%R4t&R5t'R6t(R7]( R82t)!R9R:]PT4t+R;t,]!R3]R3]R3]$R3]#R3]+R33t-RBRCRDRERF]R3RGRH3t.R<R=lt/R#)IzException 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.Nz database disk image is malformedc0V^8dQhR\R\/#excreturn BaseExceptionbool)formats"8/home/ubuntu/.hermes/hermes-agent/hermes_state_errors.py __annotate__r s}ca\S\P4;'dC\;QJd#V3Rl\4F 'gK R# R#!V3Rl\44#)uMalformed-schema OR generic corrupt-image error. Diagnostics / offline recovery only — runtime repair must use :func:`is_malformed_schema_error`.c3Z<"TF q\S4P49xK" R#5iNstrlower.0markerrs& r (is_malformed_db_error..s#:1Fv#c(..""1F(+TF) isinstancesqlite3 DatabaseErrorany_MALFORMED_DB_MARKERSrsfr is_malformed_db_errorr sY c700 1  cc:1F:cccc:1F:7r zdisk i/o errorzdatabase is lockedzdatabase table is lockedbusyc2V^8dQhR\R,/#)rrN)int)r s"r r r +s::d :r c^\VRR4p\V\4'd V^,#R#)zPPrimary result code (extended codes keep it in the low byte); None when unknown.sqlite_errorcodeN)getattrrr#) exc_or_strcodes& r _sqlite_primary_coder)+s, :14 8D$T3//4$;9T9r c$V^8dQhR\/#rrr )r s"r r r 1s...r c\V4pVe V\9#\V4P4pRV9;'gRV9#)zSQLITE_BUSY / SQLITE_LOCKED: wait and retry, never treat as damage. A known result code decides; only without one (our own re-raised messages, RPC-wrapped strings) does the text.lockedr!)r)_SQLITE_LOCK_CODESrrr'r(texts& r is_sqlite_lock_errorr21sI +D ))) z? "D t  - -v~-r cDV^8dQhR\PR\/#r)rErrorr )r s"r r r ;s88'--8D8r c:R\V4P49#)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_rowsr6;s $s3x~~'7 77r c0V^8dQhR\R\/#rr)r s"r r r A=Tr ca\S\P4;'dV\S4;'gC\;QJd#V3Rl\ 4F 'gK R# R#!V3Rl\ 44#)zi"Busy right now", not "damaged": one predicate so retry and the HTTP 503-vs-500 split cannot drift apart.c3Z<"TF q\S4P49xK" R#5irrrs& r r,is_transient_sqlite_error..Es!(lRk3s8>>3C)CRkrTF)rrOperationalErrorr2r_TRANSIENT_SQLITE_MARKERSrsfr is_transient_sqlite_errorr>As_ c733 4  S!llSS(lRk(lSS%(%((lRk(l%lr c0V^8dQhR\R\/#rr)r s"r r r Ir8r ca\S\P4;'dC\;QJd#V3Rl\4F 'gK R# R#!V3Rl\44#)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.c3Z<"TF q\S4P49xK" R#5irrrs& r r,is_malformed_schema_error..Ls#:1Jv#c(..""1JrTF)rrrr_MALFORMED_SCHEMA_MARKERSrsfr is_malformed_schema_errorrDIsY c700 1  cc:1J:cccc:1J:7r cTV^8dQhR\\,R,R\/#)rrNr)rrr )r s"r r r Xs(CCMC/$6C4Cr cfaVfR#\V\4'd#\VRR4\P8XdR#\V\ 4'dTM \ V4P 4o\;QJd#V3Rl\4F 'gK R# R#!V3Rl\44#)zFDisk-full / ENOSPC: OSError(ENOSPC), SQLITE_FULL, or matching strings.NFerrnoTc3,<"TF qS9xK R#5ir)rrlowereds& r r%is_disk_full_error.._sB/AV /A) rOSErrorr&rGENOSPCrrr_DISK_FULL_MARKERS)rrJs&@r is_disk_full_errorrPXsz {#wGC$$?5<<$O c**sC??AG 3B/AB33B3B3B/AB BBr compressioncompression_closed turn_leasecorruptreplaced deleted_walSQLITE_CORRUPT_VTABi z\bmessages_fts\w*c$V^8dQhR\/#r+r,)r s"r r r zsDD$Dr caVfR#\VRR4pVe V\8H#\V\4'dTM \V4P 4o\ P S4'gR#SPR4'd RS9dR#\;QJd#V3Rl\4F 'gK R# R#!V3Rl\44#)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. NFr%zfts5:rTTc3,<"TF qS9xK R#5irrIrrr1s& r r1is_fts_scoped_corruption_error..sC,B&~,BrL) r&rWrrr_FTS_OBJECT_REsearch startswithr_DB_CORRUPTION_MARKERSr0s& @r is_fts_scoped_corruption_errorrazs :14 8D ***$Z55J3z? Q Q SD   & & wI$5 3C,BC33C3C3C,BC CCr cBaa]tRt^toRtV3RlV3RlltRtVtV;t#)CompressionSessionClosedErrorz@A durable write targeted a parent already closed by compression.c <V^8dQhRS[/#)r session_idr)r __classdict__s"r r *CompressionSessionClosedError.__annotate__s  3 r c<<Wn\SV` RV: R24R#)zSession zP is closed by compression; adopt its live continuation before appending messagesN)resuper__init__)selfre __class__s&&r rk&CompressionSessionClosedError.__init__s($ zn%D D r )re) __name__ __module__ __qualname____firstlineno____doc__rk__static_attributes____classdictcell__ __classcell__)rmrgs@@r rcrcsJ   r rcc]tRt^tRtRtR#)CompressionSessionBusyErrorz>A non-owner tried to write while compression owns the session.rINrorprqrrrsrtrIr r rxrxsHr rxc]tRt^tRtRtR#)!SessionCompressionInProgressErroruA 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.rINryrIr r r{r{sEr r{c]tRt^tRtRtR#)PruneRowUnresolvedErrorzAn in-place prune rewrite could not name the exact live row of a changed message. Raised before any write, so the caller commits through ``archive_and_compact`` instead.rINryrIr r r}r}sQr r}c]tRt^tRtRtR#)PruneRowStaleErroruThe named live row no longer holds the body the pruner is pruning: another writer already rewrote this generation. Unlike plain ambiguity this must NOT fall back to the full writer — that writer archives rows it never compared and would republish the stale held text over the newer one. Subclassing keeps callers that only know the parent failing closed-enough (they stop the in-place path); the prune caller tells the two apart and skips the pass entirely.rINryrIr r rrs]r rc]tRt^tRtRtR#)HeldRowRewrittenErroruA full-writer commit found one of the held rows it was about to archive already rewritten in place by another writer. Raised INSIDE the commit's write transaction, after the caller's precheck but before any row is archived: a write that lands in that window is exactly the lost race the precheck cannot see (#124102). Callers treat it like ``StaleHeldHistory`` — nothing written, the pass is a no-op and the newer generation keeps the session.rINryrIr r rrsPr rc]tRt^tRtRtR#)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.rINryrIr r rrsXr rc]tRt^tRtRtR#)SessionActiveWriteGuardErrorzNRaised when an active turn lease or compression lock rejects session deletion.rINryrIr r rrsXr rc]tRt^tRtRtR#)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.rINryrIr r rrsCr rc]tRt^tRtRtR#)DeletedWalGenerationErroracA 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.rINryrIr r rrsAr rdb_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.c]tRt^tRtRtR#)StateDbCorruptErrorubA 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. rINryrIr r rrsr raFATAL: 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).c$V^8dQhR\/#r+rf)r s"r r r %s!!c!r cpaVfR#\Fwr\W4'gKVu# \V4'dR#\V4\9dR#\ VRR4\ P8XdR#\V4P4o\FIwr2\;QJdV3RlV4F 'gK RM R M!V3RlV44'gKGVu# \V4'gA\;QJdV3R lR 4F 'gK RM R M!V3R lR 44'dR #R#) aCoarse 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; "session_row_missing" = the session row was deleted under a live agent (FK rejection; the flush recreates it).Nunknown fts_indexr.r%session_row_missingc3,<"TF qS9xK R#5irrIr[s& r r-classify_persistence_error..Bs4G&~GrLTFc3,<"TF qS9xK R#5irrI)rmr1s& r rrDs,b@a1$Y@arLdisk)rreadonlyz read-only) _PERSISTENCE_CAUSE_BY_TYPErrar)r/r&rSQLITE_CONSTRAINT_FOREIGNKEYrr_PERSISTENCE_CAUSE_BY_PHRASErrP)r'exc_typecausemarkersr1s& @r classify_persistence_errorr%s 6 j + +L6 &j11J'+==z-t48\8\\$ z? "D6 34G43334G4 4 4L7*%%,b@a,b,b@a,b)b)b r )zmalformed database schema)zno space left on deviceznot enough spacezdatabase or disk is fullz disk fullz full diskenospc) r.rQrRrSrTrrUrVrrr) malformedzfile is not a databaseznot a databasezdatabase corruption))z turn leaserS))zclosed by compressionrR))zbeing compressedzcompression leaserQ))zdeleted state.db-walzdeleted state.db-shmrV))zwas replaced underneathrU))r.r!r.))zforeign key constraint failedr)0rsrGrerrCrr _DISK_IO_ERROR_MARKERr= SQLITE_BUSY SQLITE_LOCKEDr/r)r2r6r>rDrOrPPERSISTENCE_ERROR_CAUSESr`r&rWcompiler]ra RuntimeErrorrcrxr{r}rrrrrr_STATE_DB_APPLICATION_ID_OFFSET_STATE_DB_GENERATION_KEY_STATE_DB_REPLACED_MSGSTORAGE_RECOVERY_DOCS_URL_DELETED_WAL_GENERATION_MSGrr_STATE_DB_CORRUPT_MSGrrrrIr r rs/ ;X3X5WX) /1KV))7+@+@A: .8  C g'E.Y'"? !r