obstat 0.1.0__tar.gz → 0.2.0__tar.gz

{obstat-0.1.0 → obstat-0.2.0}/.gitignore

@@ -9,3 +9,6 @@ build/
 
 # obstat's own working files: a decision record is per-deployment, never committed.
 .obstat/
+
+# IDE config: per-developer, not per-project.
+.idea/

obstat-0.2.0/CLAUDE.md

@@ -0,0 +1,52 @@
+# obstat
+
+An auditable decision record for agent tool calls. The one claim the project
+makes: **the decision is on disk, fsynced, before the tool body runs.** Anything
+that weakens that ordering is a bug, not an optimisation.
+
+## Commands
+
+```bash
+uv run pytest -q          # 26 tests, ~0.3s
+uv run ruff check .
+uv run ruff format .
+```
+
+## Rules that are not negotiable
+
+- **No runtime dependencies.** `tomllib`, `sqlite3`, `hashlib`, `json` are
+  stdlib. `mcp` is an optional extra for `examples/server.py` only. A governance
+  library nobody can try on a laptop is one nobody adopts.
+- **`docs/obstat-spec.md` is normative.** Behaviour changes update the spec in
+  the same commit. Where spec and code disagree, one of them is a bug.
+- **Nothing matching the policy is a deny**, and a missing policy file is an
+  error — never an implicit allow.
+- **Denials reach the caller with a record id and nothing else.** The reason goes
+  to the record. A denial that explains itself teaches a caller what to work
+  around.
+
+## Conventions
+
+Comments say *why*, not what, and name the alternative that was rejected. A
+`ponytail:` comment marks a deliberate shortcut and its upgrade path — those are
+debts, not decoration.
+
+Spec section numbers (`§5.1`) are referenced from docstrings; keep them in step
+when the spec is renumbered.
+
+## Releasing
+
+1. Bump `version` in `pyproject.toml` **and** `__version__` in
+   `obstat/__init__.py` — two places, no single source yet.
+2. `git tag vX.Y.Z && git push --tags`
+
+`.github/workflows/publish.yml` runs the tests against the tag, builds, and
+uploads via PyPI trusted publishing (OIDC — there is no token anywhere). **A PyPI
+version is immutable**: a bad build can be superseded, never withdrawn.
+
+## Gotcha
+
+`uv run --with /path/to/obstat` serves a **cached wheel** and will happily run
+code you edited minutes ago as if you hadn't. `--reinstall-package` does not
+dislodge it; `--refresh` does. Two verification runs were wasted on this — if a
+local install seems to ignore your change, that is why.

{obstat-0.1.0 → obstat-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: obstat
-Version: 0.1.0
+Version: 0.2.0
 Summary: An auditable decision record for agent tool calls. The clearance is written down before the call runs.
 Project-URL: Homepage, https://github.com/marcinmarzeta/obstat
 Project-URL: Issues, https://github.com/marcinmarzeta/obstat/issues
@@ -21,6 +21,11 @@ Description-Content-Type: text/markdown
 
 # obstat
 
+[![PyPI](https://img.shields.io/pypi/v/obstat)](https://pypi.org/project/obstat/)
+[![Python](https://img.shields.io/pypi/pyversions/obstat)](https://pypi.org/project/obstat/)
+[![CI](https://github.com/marcinmarzeta/obstat/actions/workflows/ci.yml/badge.svg)](https://github.com/marcinmarzeta/obstat/actions/workflows/ci.yml)
+[![License](https://img.shields.io/pypi/l/obstat)](LICENSE)
+
 **An auditable decision record for agent tool calls.** The clearance is written
 down before the call runs — not reconstructed from logs afterwards.
 
@@ -37,6 +42,9 @@ pip install obstat
 No dependencies. Not AWS, not an identity provider, not a policy service — the
 decorator, `tomllib`, `sqlite3` and a file.
 
+[`docs/obstat-spec.md`](docs/obstat-spec.md) is normative, and its §8 lists what
+is still weak.
+
 ## 60 seconds
 
 `obstat.toml`:
@@ -87,7 +95,7 @@ the whole story.
 ## What it is not
 
 There are several good libraries that gate MCP tool calls. This one is built
-around a narrower claim: **the record is the product.** Three things follow from
+around a narrower claim: **the record is the product.** Four things follow from
 that, and they are the reason to pick this over a permission wrapper.
 
 **The decision is durable before the body runs.** Not flushed after, not written
@@ -117,6 +125,19 @@ q3-report" cannot be spent on deleting something else, and cannot be spent twice
 This is enforced in one `BEGIN IMMEDIATE` transaction, so two concurrent retries
 cannot both win.
 
+**The record says when it has been edited.** Every record carries the hash of the
+one before it, and `obstat verify` recomputes the chain:
+
+```console
+$ obstat verify
+line 3: record cd53f9db… follows a record that is no longer in the log
+```
+
+An edited line and a deleted line both show up. A truncated tail does not, and
+anyone who can write the file can recompute the whole chain — this is
+tamper-evidence, not non-repudiation, and
+[§8](docs/obstat-spec.md#8-still-open) says so in those words.
+
 ## Identity is optional
 
 Most MCP servers today have no token at all: stdio, one local user, or a gateway
@@ -180,6 +201,7 @@ obstat pending              # approvals waiting on a human
 obstat approve <id> [--by]  # decide
 obstat deny <id> [--by]
 obstat log -n 50            # the decision record
+obstat verify               # recompute the chain; exit 1 if anything was edited
 obstat stop                 # deny every guarded call
 obstat resume
 ```
@@ -213,4 +235,4 @@ you cannot try.
 
 ## License
 
-Apache-2.0.
+Apache-2.0. Copyright 2026 Marcin Marzęta.

{obstat-0.1.0 → obstat-0.2.0}/README.md

@@ -1,5 +1,10 @@
 # obstat
 
+[![PyPI](https://img.shields.io/pypi/v/obstat)](https://pypi.org/project/obstat/)
+[![Python](https://img.shields.io/pypi/pyversions/obstat)](https://pypi.org/project/obstat/)
+[![CI](https://github.com/marcinmarzeta/obstat/actions/workflows/ci.yml/badge.svg)](https://github.com/marcinmarzeta/obstat/actions/workflows/ci.yml)
+[![License](https://img.shields.io/pypi/l/obstat)](LICENSE)
+
 **An auditable decision record for agent tool calls.** The clearance is written
 down before the call runs — not reconstructed from logs afterwards.
 
@@ -16,6 +21,9 @@ pip install obstat
 No dependencies. Not AWS, not an identity provider, not a policy service — the
 decorator, `tomllib`, `sqlite3` and a file.
 
+[`docs/obstat-spec.md`](docs/obstat-spec.md) is normative, and its §8 lists what
+is still weak.
+
 ## 60 seconds
 
 `obstat.toml`:
@@ -66,7 +74,7 @@ the whole story.
 ## What it is not
 
 There are several good libraries that gate MCP tool calls. This one is built
-around a narrower claim: **the record is the product.** Three things follow from
+around a narrower claim: **the record is the product.** Four things follow from
 that, and they are the reason to pick this over a permission wrapper.
 
 **The decision is durable before the body runs.** Not flushed after, not written
@@ -96,6 +104,19 @@ q3-report" cannot be spent on deleting something else, and cannot be spent twice
 This is enforced in one `BEGIN IMMEDIATE` transaction, so two concurrent retries
 cannot both win.
 
+**The record says when it has been edited.** Every record carries the hash of the
+one before it, and `obstat verify` recomputes the chain:
+
+```console
+$ obstat verify
+line 3: record cd53f9db… follows a record that is no longer in the log
+```
+
+An edited line and a deleted line both show up. A truncated tail does not, and
+anyone who can write the file can recompute the whole chain — this is
+tamper-evidence, not non-repudiation, and
+[§8](docs/obstat-spec.md#8-still-open) says so in those words.
+
 ## Identity is optional
 
 Most MCP servers today have no token at all: stdio, one local user, or a gateway
@@ -159,6 +180,7 @@ obstat pending              # approvals waiting on a human
 obstat approve <id> [--by]  # decide
 obstat deny <id> [--by]
 obstat log -n 50            # the decision record
+obstat verify               # recompute the chain; exit 1 if anything was edited
 obstat stop                 # deny every guarded call
 obstat resume
 ```
@@ -192,4 +214,4 @@ you cannot try.
 
 ## License
 
-Apache-2.0.
+Apache-2.0. Copyright 2026 Marcin Marzęta.