+ jHj;,a0t$Rt^RIHt^RIt^RIt^RIt^RIt^RIt^RI H t ^RI H t ]P!]4t]P !4t/tR]R&!RR]4t!R R ]4tR R ltR RltRRltR4RRlltRRltRRltRRlt!RR4t!RR]]P>4t /t!R]R&RR lt"R!RR"R/R#R$llt#R%R&lt$R'R(lt%R)R*lt&R+^dR,R-/R.R/llt']PPR0R1/R2R3ll4t)R#)5aLock-safe inspection of SQLite database files. POSIX advisory locks are cancelled **process-wide** by ``close()`` on *any* fd for that file, so a bare ``open(db_path, "rb") ... close()`` on a live database drops every lock SQLite holds from this process (a VACUUM's EXCLUSIVE lock, an in-flight BEGIN IMMEDIATE's RESERVED lock). This module tracks live connections so raw reads happen only when none exist. ) annotationsN)Path)Optionalzdict[str, int]_live_connectionsc]tRt^tRtRtR#)UntrackableConnectionErrorzA connection to a probe-able database could not be tracked. Raised rather than returning an untracked connection: on these paths tracking is part of the correctness contract.N__name__ __module__ __qualname____firstlineno____doc____static_attributes__r@/home/ubuntu/.hermes/hermes-agent/hermes_cli/sqlite_safe_read.pyrrsZrrc]tRt^!tRtRtR#)LiveConnectionErrorzGA raw file operation was attempted on a database with live connections.rNr rrrrr!sQrrc V^8dQhRRRR/#)path Path | strreturnstrr)formats"r __annotate__r%szcrc\\V4P44# \d\T4u#i;i)z;Canonicalise a *filesystem* path for use as a registry key.)rrresolveOSErrorrs&r_keyr %s84:%%'(( 4ys !$==c V^8dQhRRRR/#)rconnsqlite3.Connectionr Optional[str]r)rs"rrr-s  / M rcVPR4P4pT'd \ T4^8gT^,'gR#\ T^,4# \PdR#i;i)zThe on-disk path of ``main`` as SQLite reports it (immune to ``file:`` URIs, relative paths, symlinks). ``None`` for in-memory/unnamed databases, which cannot be byte-probed.zPRAGMA database_listN)executefetchonesqlite3Errorlenr )r"rows& r_canonical_db_pathr,-s_ll12;;= #c(Q,c!ff A< ==sAA54A5c V^8dQhRRRR/#rrrrNoner)rs"rrr9s:$rc\;_uu_4\\V44RRR4R# +'giR#;i)zRecord that this process holds a connection to *path* (prefer :func:`connect_tracked`; this is for callers managing their own connection objects, and for tests).N _live_lock _track_keyr rs&rtrack_connectionr49s! 4: s. ? c$V^8dQhRRRRRR/#)rkeyrdeltaintrr/r)rs"rrr@s!))C))D)rc\PV^4V,pV^8d V\V&R#\PVR4R#)zQAdjust the live count for an already-canonical key (caller holds ``_live_lock``).N)rgetpop)r6r7 remainings&& rr3r3@s;!%%c1-5I1}!*#c4(rc V^8dQhRRRR/#r.r)rs"rrrIs##Z#D#rc\;_uu_4\\V4R4RRR4R# +'giR#;i)z5Record that one connection to *path* has been closed.Nr1rs&runtrack_connectionr@Is! 4:r" s / A c V^8dQhRRRR/#)rr6rrr$r)rs"rrrOs    rcV\9dV#RFEpVPV4'gKVR\V4)\9gK6VR\V4)u# R#)a The tracked main-database key that makes *key* live, or ``None`` (caller holds ``_live_lock``). SQLite locks the main file and its WAL sidecars; a raw ``close()`` of any of those inodes cancels this process's POSIX locks, but the registry is keyed by the main path.N)z-walz-shm)rendswithr*)r6suffixs& r_live_main_keyrEOsX   " <<  C #f+$6:K$K}V % %# rc V^8dQhRRRR/#)rrrrboolr)rs"rrr\s66j6T6rc\;_uu_4\\V44RJuuRRR4# +'giR#;i)aWhether this process holds a connection to *path* (or to the database it is a sidecar of). Point-in-time answer: a raw open/close right after it returns ``False`` can still race a new connection. Hold :func:`offline_file_access` across the I/O whenever possible.N)r2rEr rs&rhas_live_connectionrI\s& d4j)5 s 0 A cBa]tRt^et$RtRtR]R&RV3RlltRtV;t #)_TrackingMixinaUntrack-on-close behaviour, mixable into any Connection subclass. The real ``close()`` and the unregister happen together under ``_live_lock`` so a concurrent probe can never observe "no live connection" while this descriptor is still open. Unregister runs only after ``close()`` succeeds: untracking before a failing close (e.g. cross-thread ProgrammingError) would leave the FD open while the byte-probe guard thinks nothing is live. Nz str | None_hermes_tracked_pathcV^8dQhRR/#)rrr/r)rs"rr_TrackingMixin.__annotate__ps ) )t )rc <\;_uu_4\VRR4p\SV` 4VeRVn\ V4RRR4R# +'giR#;i)rLN)r2getattrsupercloserLr@)selfr __class__s& rrR_TrackingMixin.closepsD Z4!7>D GMO,0)"4(ZZZs 2A  A )rL) r r r r rrL__annotations__rRr __classcell__)rTs@rrKrKes(,*+ ) )rrKc]tRt^|tRtRtR#)TrackedConnectionzA ``sqlite3.Connection`` that untracks its path exactly once on close (callers close in many places, some via ``contextlib.closing``, so counting closes by hand is unreliable).rNr rrrrYrY|s[rrYzdict[type, type]_tracked_factory_cachec V^8dQhRRRR/#)rfactorytyperr)rs"rrrs  t  rcV\PJd\#\V\4'dV#\ P V4pVf*\RVP 2\V3/4pV\ V&V#)a Return *factory* augmented with untrack-on-close. Callers legitimately pass their own ``Connection`` subclasses (tests simulate FTS5-less or pragma-failing runtimes); leaving them untracked would quietly unguard the database, so the tracking ``close()`` is mixed in.Tracked) r( ConnectionrY issubclassrKrZr:r]r )r\cacheds& r_tracking_factoryrcsp'$$$  '>** # ' ' 0F ~ 0 012^W4MrR*0w' Mr tracking_path connect_fnc$V^8dQhRRRRRR/#)rrrrdzPath | str | Nonerr#r)rs"rrrs$ (9rc DVeTM\Pp\VPR\P44VR&\ ;_uu_4V!\ V43/VBpVe \V4M \V4pVf VuuRRR4#\V\4'g \WV4pWen \V4VuuRRR4# \d4\PPT4h \dhi;ii;i +'giR#;i)a_``sqlite3.connect`` that registers the connection for the lifetime of the fd (released on ``close()``). Use for any database that might be byte-probed (``state.db``, ``kanban.db``). Open and registration happen together under ``_live_lock`` so a concurrent :func:`read_header_bytes_preopen` cannot slip between them and cancel this connection's locks.Nr\)r(connectrcr:r`r2rr r, isinstancerK_retrofit_trackingrLr3 ExceptionrR)rrdrekwargsopenerr"resolveds&$$, rconnect_trackedros&1ZwF)&**Y@R@R*STF9 c$i*6* .;.GtM*M_`dMeH  dN33*$9(0 % x    ""((.       sHD%C 3C  D C98D 9 D D D D  D D c$V^8dQhRRRRRR/#)rr"r#rnrrr)rs"rrrs#  / 3 CU rc\V4p\V4VnV# \d#p\ RT RTP R24ThRp?ii;i)zGive an already-open connection untrack-on-close semantics by swapping ``__class__`` for one mixing in the tracking ``close()`` (used when an opener ignored the factory we asked for).zconnection to z uses factory zn, which cannot release its tracking entry on close; byte-probe safety for this database would be silently lostN)r]rcrT TypeErrorrr )r"rnclsexcs&& rrjrjsa t*C*3/ (XJnS\\NC7 7   s A AA c V^8dQhRRRR/#)rr"r#rz Optional[int]r)rs"rrrs  - - rcdVPR4P4^,pVPR4P4^,p\V4\V4,# \P\ \ \3d"p\PRT4Rp?R#Rp?ii;i)zLogical database size in bytes (``page_count * page_size``, the header field at offset 28) read via PRAGMA over *conn* so no new fd is opened. ``None`` when the pragmas cannot be read.zPRAGMA page_countzPRAGMA page_sizez$page_count/page_size unavailable: %sN) r&r'r8r(r)rr IndexError ValueErrorloggerdebug)r" page_count page_sizerts& rpage_count_bytesr}s\\"56??A!D LL!34==?B :Y// MM9j* = ;SAsA&A))%B/B**B/c V^8dQhRRRR/#)rr"r#rzOptional[bool]r)rs"rrrs  %7 N rc\V4pVfR#\V4pV'gR#\PP V4V8# \ dR#i;i)aWhether the file on disk is at least as long as the header claims ("torn extend" check), without opening the file (PRAGMA over *conn* + ``stat()``). Advisory in WAL mode: a freshly committed page may still live in ``-wal`` so the main file legitimately lags.N)r,r}osrgetsizer)r"path_strlogicals& rfile_length_matches_headerrsV"$'Ht$G wwx(G33 s!A AAlengthforceFc(V^8dQhRRRRRRRR/#) rrrrr8rrGrzOptional[bytes]r)rs"rrrs)J3T^mrc \;_uu_4V'g8\\V44e"\P RV4RRR4R#\ VR4;_uu_4pVP V4uuRRR4uuRRR4# +'giM;i \d RRR4R#i;iRRR4R# +'giR#;i)a_Read the first *length* bytes of *path* -- only when no connection is live. The ONLY sanctioned byte-level read of a database file, for first-open validation (real SQLite? zeroed? overwritten?). Check and open/read/close run together under ``_live_lock`` so a connection cannot be opened between deciding "nothing is live" and closing this descriptor.Nzqrefusing byte-level read of %s: a live connection exists in this process and close() would cancel its POSIX locksrb)r2rEr ryrzopenreadr)rrrhandles&$$ rread_header_bytes_preopenrs T 3? LLH   dD!!V{{6*"! "!   " sM6CB$B 5 B B BCB B4(C3B44C C whatrc V^8dQhRRRR/#)rrrrrr)rs"rrrs  j 3 rc #"\;_uu_4\\V44pVe-V\V48XdRMRV 2p\RV RV RV R24hRxRRR4R# +'giR#;i5i)aHold the connection-lifecycle lock across a raw read of a database file: checking :func:`has_live_connection` and *then* doing raw I/O is a check/use race (a connection opened in between loses its POSIX locks to the raw ``close()``). Held only for the raw I/O.Nitzits main database z Refusing to  z: a connection to z is still open in this process, and raw file access would cancel that connection's POSIX advisory locks. Close all database handles (stop the gateway/dashboard) and retry.)r2rEr r)rrmainsubjects&$ roffline_file_accessrsz d4j)  "d4j0d8J4&6QG%tfAdV+=gYGBBC C  sA8A A$ A8$ A5 / A8))*__conditional_annotations__r __future__r contextlibloggingrr( threadingpathlibrtypingr getLoggerr ryRLockr2rrV RuntimeErrorrrr r,r4r3r@rErIrKr`rYrZrcrorjr}rrcontextmanagerr)rs@rrs#    8 $__  $&>&ZZ R,R )# 6)).[(:(:[ ,.(- <@MQD    TY&    r