Audit logs must log before execution, not after
Forget what you think you know about audit logs. If your governance layer writes its log after the tool call returns, the record is already half-fiction. The missing line might mean “never authorised,” or it might mean “authorised, then the process died before the log hit disk.” There is no way to tell. That ambiguity is why Marcin Marzeta built obstat, a small Python library that inverts the order: decisions go to disk—fsync’d—before the tool body executes.
A single fsync that changes everything
Most logging stacks batch, defer, or let the framework decide when to flush. obstat does the opposite. When @guard(resource="doc:{doc_id}") wraps delete_document, the library writes the decision record, calls fsync, and only then runs the function body. If the process crashes mid-call, the log still shows what was authorised, for whom, and against which resource—nothing else can claim it was “never logged.” The rest of the library is convenience; this one guarantee is what examiners will rely on.
The test that proves the promise
The claim is not a paragraph; it is a unit test that breaks when the guarantee fails. Inside the guarded function, record.read() fetches the log straight from disk. If anything were buffered, deferred, or written afterwards, the test would see an empty list. Move the write one line later and the assertion assert len(decisions) == 1 collapses. That brittleness is the point: the property is stated in code that fails when it stops being true.
Why resource-level rules matter
Traditional tiers like READ/WRITE/DESTRUCTIVE can’t capture nuance such as “may edit their own ticket, not yours.” obstat resolves a resource ID from the call arguments and matches rules like:
[[rule]] subject = "human:ana" resource = "jira_issue:ACME-*" effect = "allow"
Each approval is bound to one call, carries a digest of the arguments, and is single-use—enforced in a single BEGIN IMMEDIATE transaction so that two concurrent attempts cannot reuse the same clearance.
Why it matters
Examiners and incident responders need logs that are auditable, not merely collected. By forcing the decision record onto stable storage before the action runs, obstat turns logs from retrospective stories into verifiable evidence. It also shifts governance from coarse tiers to resource-level policies, making it harder to stretch a blanket permission beyond its intended scope. For teams serious about accountability, the cost of one extra fsync is small compared to the cost of a log that cannot distinguish “never authorised” from “authorised and lost.”
Source: DEV Community. AI-assisted editorial synthesis — TechnoExpress.