Versions, allowed roots, and what this build can and cannot do.

Compute a document's canonical digest — stable across a no-op Office save, and the key a receipt is stored under. Needs no session.

Check a document against its receipt. Reports three distinct outcomes: verified, unknown (no receipt matches this digest) and failed (a receipt matched but a tier failed). Needs no session — the same check runs in CI via ooxml-ledger verify.

Start an editing session: unpack the document to disk, record its baseline digest and part manifest, and sweep expired sessions. Reopening the same unchanged document resumes its live session instead of forking a second one.

End a session and delete its working directory WITHOUT sealing a receipt. Refuses when the journal holds recorded operations unless discard is set — closing over them would throw away the accountability record.

Report a session document's structure: which parts the digest covers, which it excludes, and the format's own units — paragraphs for docx, sheets for xlsx, slides (in <p:sldIdLst> order, never filesystem order) for pptx. Describes the session's working copy as opened; verify reports on the file on disk now.

Case-insensitive substring search over every text-bearing part the digest covers, returning the best address this build can give for each hit: paragraph id or index and hash for docx, slide id for pptx, sheet and cell for xlsx. Results come from the session's working copy as opened; verify is what reports on the file currently on disk.

List every receipt in the store beside a document, flagging the one whose result digest matches the document as it stands now, and naming every file that was skipped and why.

Write this document's receipt out as one self-contained sidecar file — the thing you attach to a submission, commit to git, or register alongside a DOI.

End a session by sealing its journal into a receipt, but only if the recorded operations account for every change to the document. If they do not, the commit is REFUSED. force overrides a failed gate VERDICT and the override is recorded in the receipt, where verify will surface it; it does not override a ledger that could not be read or replayed at all.

Report what a batch of edits WOULD do, writing nothing. Runs the same engine against a throwaway copy of the document as it stands on disk right now — including every edit already applied in this session — so a green preview and the apply that follows it cannot disagree. author and mode are required because the engine's refusals depend on both.

Apply a batch of edits to the document and record each one in the session's journal. ALL-OR-NOTHING: the document is written only if every edit applied, so a failed batch leaves the file byte-identical and journals nothing. mode 'tracked' emits Word revision marks a reviewer can see; 'direct' rewrites the text and is recorded in the ledger alone, which the receipt discloses. Seal the session with commit_document.

Delete one whole paragraph and record it in the session's journal. Address it by para_id — the w14:paraId find_text returns — or by para_index TOGETHER WITH para_hash, because an index alone silently addresses a different paragraph once anything above it moves. mode 'tracked' marks the paragraph mark AND every run with w:del, so a reviewer can reject it back and nothing is actually removed; 'direct' removes it outright and is accounted for by the ledger alone, which the receipt discloses. Refused if the paragraph carries a section break, or holds an unaccepted revision by another author. Seal the session with commit_document.

Insert a new paragraph carrying text, BESIDE a paragraph you name, and record it in the session's journal. Pass exactly one anchor — after_para_id or before_para_id, the w14:paraId find_text returns. para_hash is OPTIONAL and recommended: the paraId already names one specific paragraph, and passing the hash find_text reported with it additionally refuses the call if that paragraph's text has moved on since you read it. There is deliberately NO raw index parameter. The new paragraph becomes a SIBLING of the anchor, which keeps it inside the same table cell, textbox or content control. mode 'tracked' marks the new paragraph and its run with w:ins, so rejecting removes the whole paragraph; 'direct' writes it unmarked and is accounted for by the ledger alone, which the receipt discloses. Seal the session with commit_document.