obstat 0.2.0__tar.gz → 0.3.1__tar.gz

{obstat-0.2.0 → obstat-0.3.1}/.github/workflows/ci.yml

@@ -7,10 +7,17 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       matrix:
+        os: [ubuntu-latest]
         python: ["3.11", "3.12", "3.13"]
+        # Windows cannot fsync a directory (§8), which the first record write
+        # depends on. One leg, so the platform where that is skipped is a
+        # platform the tests actually run on.
+        include:
+          - os: windows-latest
+            python: "3.12"
     steps:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v5

{obstat-0.2.0 → obstat-0.3.1}/CLAUDE.md

@@ -7,7 +7,7 @@ that weakens that ordering is a bug, not an optimisation.
 ## Commands
 
 ```bash
-uv run pytest -q          # 26 tests, ~0.3s
+uv run pytest -q          # 42 tests, ~0.9s (TestConcurrency spawns two children)
 uv run ruff check .
 uv run ruff format .
 ```
@@ -44,9 +44,20 @@ when the spec is renumbered.
 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
+## Gotchas
 
 `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.
+local install seems to ignore your change, that is why. To exercise uncommitted
+work, `--with-editable` sidesteps the question entirely.
+
+**PyPI lags its own publish.** Minutes after `publish.yml` goes green,
+`uv pip install obstat==X` can still fail with *"there is no version of
+obstat==X"* while `https://pypi.org/pypi/obstat/json` reports X as latest — or
+the reverse; 0.2.0 and 0.3.0 each showed one. It cleared inside a minute both
+times. The symptom impersonates a failed upload, and every tempting response
+(re-tag, re-run, `force`) is wrong, one of them irreversibly. **The publish job
+log is authoritative**: it prints the `https://pypi.org/project/obstat/X/` that
+upload.pythonhosted.org returned, which means the file was accepted. Poll the
+install until it succeeds rather than diagnosing it.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: obstat
-Version: 0.2.0
+Version: 0.3.1
 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
@@ -47,6 +47,11 @@ is still weak.
 
 ## 60 seconds
 
+```console
+$ obstat init
+wrote obstat.toml — everything is denied until you uncomment a rule
+```
+
 `obstat.toml`:
 
 ```toml
@@ -173,6 +178,18 @@ permission, and a missing policy file is an error rather than an implicit allow.
 Patterns are globs. The file is re-read when it changes, so editing policy does
 not need a restart.
 
+They are matched **case-sensitively**, against an id built from arguments the
+caller sent. If your namespace is not case-sensitive — Jira keys, most
+filesystems — a rule written for `jira_issue:SEC-*` will not cover `sec-1`, and
+nothing will tell you. Normalise the id where you build it:
+
+```python
+@guard(resource=lambda a: f"jira_issue:{a['issue_key'].upper()}")
+```
+
+That is what the callable form is for; [§3.3](docs/obstat-spec.md#33-resource-resolution)
+has the whole story, including why obstat does not fold case for you.
+
 ## The order
 
 ```
@@ -197,6 +214,8 @@ reads "authorised, outcome unknown", which is the honest state; paying for a sec
 ## Operator commands
 
 ```console
+obstat init                 # a starter policy; refuses to overwrite one
+obstat check <tool> [res]   # what the policy would decide, without a call
 obstat pending              # approvals waiting on a human
 obstat approve <id> [--by]  # decide
 obstat deny <id> [--by]
@@ -209,14 +228,34 @@ obstat resume
 `obstat stop` is checked before policy, so stopping never depends on the policy
 file still being parseable.
 
-## What is not here yet
+`obstat check` exits 0 for an allow and 1 for anything else, so a policy can be
+tested in CI — and a policy that does not parse is reported there rather than by
+the next real call.
+
+## Arguments
 
-Arguments are fingerprinted (`sha256:…`), never stored — tool arguments carry
-credentials and personal data, and a governance log that leaks them is a liability
-rather than a control. A per-key allowlist for recording chosen values is the
-obvious next step.
+Fingerprinted by default, never stored: tool arguments carry credentials and
+personal data, and a governance log that leaks them is a liability rather than a
+control. Name the ones a human needs and those values are recorded too —
+
+```python
+@guard(resource="tool:send_email", record_args=("to",))
+def send_email(to: str, body: str) -> str: ...
+```
+
+```console
+$ obstat pending
+d41b88f29a43  send_email  human:ana  tool:send_email  871s left
+      to = 'board@example.com'
+```
+
+— because an approver deciding about `sha256:ae32e6…` is deciding about nothing.
+The digest still covers every argument; `body` is in it and nowhere else. Name
+identifiers, not payloads.
+
+## What is not here yet
 
-Also absent, deliberately: retention and rotation of the log, Slack and webhook
+Deliberately absent: retention and rotation of the log, Slack and webhook
 approval channels, a policy for where a result may be *sent*, and anything that
 talks to a cloud. Those belong at the edges, and the edges should be adapters
 rather than dependencies.
@@ -229,6 +268,7 @@ rather than dependencies.
 | `OBSTAT_LOG` | `.obstat/decisions.jsonl` |
 | `OBSTAT_DB` | `.obstat/approvals.db` |
 | `OBSTAT_HALT` | `.obstat/halt` |
+| `OBSTAT_APPROVAL_TTL` | `900` (seconds) |
 
 Read at call time, never at import. A library that raises on import is a library
 you cannot try.

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

@@ -26,6 +26,11 @@ is still weak.
 
 ## 60 seconds
 
+```console
+$ obstat init
+wrote obstat.toml — everything is denied until you uncomment a rule
+```
+
 `obstat.toml`:
 
 ```toml
@@ -152,6 +157,18 @@ permission, and a missing policy file is an error rather than an implicit allow.
 Patterns are globs. The file is re-read when it changes, so editing policy does
 not need a restart.
 
+They are matched **case-sensitively**, against an id built from arguments the
+caller sent. If your namespace is not case-sensitive — Jira keys, most
+filesystems — a rule written for `jira_issue:SEC-*` will not cover `sec-1`, and
+nothing will tell you. Normalise the id where you build it:
+
+```python
+@guard(resource=lambda a: f"jira_issue:{a['issue_key'].upper()}")
+```
+
+That is what the callable form is for; [§3.3](docs/obstat-spec.md#33-resource-resolution)
+has the whole story, including why obstat does not fold case for you.
+
 ## The order
 
 ```
@@ -176,6 +193,8 @@ reads "authorised, outcome unknown", which is the honest state; paying for a sec
 ## Operator commands
 
 ```console
+obstat init                 # a starter policy; refuses to overwrite one
+obstat check <tool> [res]   # what the policy would decide, without a call
 obstat pending              # approvals waiting on a human
 obstat approve <id> [--by]  # decide
 obstat deny <id> [--by]
@@ -188,14 +207,34 @@ obstat resume
 `obstat stop` is checked before policy, so stopping never depends on the policy
 file still being parseable.
 
-## What is not here yet
+`obstat check` exits 0 for an allow and 1 for anything else, so a policy can be
+tested in CI — and a policy that does not parse is reported there rather than by
+the next real call.
+
+## Arguments
 
-Arguments are fingerprinted (`sha256:…`), never stored — tool arguments carry
-credentials and personal data, and a governance log that leaks them is a liability
-rather than a control. A per-key allowlist for recording chosen values is the
-obvious next step.
+Fingerprinted by default, never stored: tool arguments carry credentials and
+personal data, and a governance log that leaks them is a liability rather than a
+control. Name the ones a human needs and those values are recorded too —
+
+```python
+@guard(resource="tool:send_email", record_args=("to",))
+def send_email(to: str, body: str) -> str: ...
+```
+
+```console
+$ obstat pending
+d41b88f29a43  send_email  human:ana  tool:send_email  871s left
+      to = 'board@example.com'
+```
+
+— because an approver deciding about `sha256:ae32e6…` is deciding about nothing.
+The digest still covers every argument; `body` is in it and nowhere else. Name
+identifiers, not payloads.
+
+## What is not here yet
 
-Also absent, deliberately: retention and rotation of the log, Slack and webhook
+Deliberately absent: retention and rotation of the log, Slack and webhook
 approval channels, a policy for where a result may be *sent*, and anything that
 talks to a cloud. Those belong at the edges, and the edges should be adapters
 rather than dependencies.
@@ -208,6 +247,7 @@ rather than dependencies.
 | `OBSTAT_LOG` | `.obstat/decisions.jsonl` |
 | `OBSTAT_DB` | `.obstat/approvals.db` |
 | `OBSTAT_HALT` | `.obstat/halt` |
+| `OBSTAT_APPROVAL_TTL` | `900` (seconds) |
 
 Read at call time, never at import. A library that raises on import is a library
 you cannot try.

{obstat-0.2.0 → obstat-0.3.1}/docs/obstat-spec.md

@@ -1,7 +1,7 @@
 # obstat — specification
 
-Normative. Where this document and the code disagree, one of them is a bug; say
-which in an issue.
+Normative, §10 excepted. Where this document and the code disagree, one of them
+is a bug; say which in an issue.
 
 The claim obstat makes is narrow: **a tool call leaves a written decision before
 it runs.** Everything below exists to make that claim true without an identity
@@ -109,6 +109,28 @@ effect on the next call rather than the next restart. The cost is one `stat()`
 per call, which is cheaper than the class of incident where someone tightened a
 rule, saw no change, and concluded the tightening was wrong.
 
+### 2.3 Writing one, and asking what it would do
+
+```console
+obstat init                                    # a starter obstat.toml
+obstat check delete_document doc:q3-report     # deny (rule 0)
+obstat check read_doc --subject human:ana      # allow (rule 1)
+```
+
+`init` writes every rule commented out and one live `deny`, so a policy nobody
+finished editing permits nothing. It refuses to overwrite an existing file: that
+file is the only thing standing between an agent and every guarded tool.
+
+`check` evaluates §2 against the file on disk and prints the effect with the rule
+that produced it. The resource argument is optional and defaults to
+`tool:<name>`, the same default §3.3 applies. Exit status is 0 for `allow` and 1
+for anything else, including a policy that does not parse — which is otherwise
+discovered by the next real call, in front of a real agent.
+
+It writes no record, resolves no resource and touches no approval. It answers
+what the policy *would* say, which is the question §2.2's reload leaves a reader
+unable to ask.
+
 ---
 
 ## 3. `@guard`
@@ -118,6 +140,7 @@ def guard(
     *,
     resource: str | Callable[[dict[str, Any]], str] | None = None,
     tool: str | None = None,
+    record_args: tuple[str, ...] = (),
 ) -> Callable[[F], F]: ...
 ```
 
@@ -149,8 +172,10 @@ Normative. Each step's failure is terminal.
 **Step 6 before step 7 is the whole point.** `record.decision()` returns only
 after `write` and `fsync` — and, on the write that creates the log file, an
 `fsync` of the containing directory too, since a synced file whose directory
-entry is not synced can survive a crash with nothing pointing at it. If the
-process dies between 6 and 7, the
+entry is not synced can survive a crash with nothing pointing at it. That
+directory sync opens a directory as a file descriptor, which POSIX allows and
+Windows does not; where it cannot be opened it is skipped, and §8 says what that
+costs. If the process dies between 6 and 7, the
 record says `allow` and no outcome follows, which reads as "authorised, did not
 complete" — a state an examiner can act on. The reverse ordering produces
 "executed, no idea whether it was allowed", which is the state that costs an
@@ -194,6 +219,37 @@ policy needs to distinguish. A template that raises (`KeyError`, `IndexError`,
 `AttributeError`, `TypeError`) denies with the resource recorded as `unresolved`.
 It never falls back to a wildcard.
 
+#### The id is caller-controlled text, matched byte for byte
+
+A template interpolates arguments the caller supplied, and §2 matches the result
+with a case-sensitive glob. Where the system behind the tool treats two spellings
+as one object, the policy does not:
+
+```toml
+[[rule]]
+resource = "jira_issue:SEC-*"
+effect = "deny"
+```
+
+`transition_issue("SEC-1", …)` is denied. `transition_issue("sec-1", …)` is
+allowed, and Jira resolves both to the same issue.
+
+obstat does not fix this centrally, and folding case for everyone would be worse
+than the problem: whether `ACME-1` and `acme-1` name one thing is a fact about
+the caller's namespace, and case-folding one that is genuinely case-sensitive
+would silently widen every `allow` rule to cover objects it was never written
+for. **Normalising is the tool author's job.** It is what the callable form
+exists for:
+
+```python
+@guard(resource=lambda a: f"jira_issue:{a['issue_key'].upper()}")
+```
+
+Normalising the id does not loosen the approval binding. §5.2 binds an approval
+to `args_digest`, which is taken over the raw arguments, so an approval granted
+for `SEC-1` is refused when it is retried as `sec-1` — `approval_mismatch` —
+even though both produce the same resource.
+
 ### 3.4 The stop file
 
 Every other control answers "may this call proceed". This one answers "is
@@ -245,10 +301,20 @@ The wrapper's `__signature__` is the wrapped function's, minus `subject`, plus:
 obstat_approval_id: str | None = None  # keyword-only
 ```
 
+The **return annotation is widened** to `R | dict[str, Any]`, where `R` is what
+the body declared. A tool declaring `-> str` is telling the truth about its own
+result and not about its wrapper's: policy may send the call to a human and
+obstat returns §5.1's payload instead. A server validates a tool's result against
+this annotation, so without the widening an approval reaches the client as a
+protocol error — the exact outcome §5.1 returns rather than raises to avoid. An
+undeclared return is left undeclared; there is nothing to validate against.
+
 MCP servers generate their tool schema from that signature, so a client sees the
 approval argument — it needs to, for §5.2 — and cannot see `subject`. Verified
-against the MCP SDK in the example server: `delete_document` advertises
-`['doc_id', 'obstat_approval_id']`.
+against the MCP SDK by calling through it, not by reading the signature:
+`delete_document` advertises `['doc_id', 'obstat_approval_id']`, an allowed call
+returns its result, and an approval-required call returns the §5.1 payload with
+`is_error` false.
 
 ---
 
@@ -264,8 +330,8 @@ Policy said `approve` and no usable approval was supplied. obstat:
 1. Derives the approval id: `sha256(tool | subject | resource | args_digest)[:12]`.
 2. Writes a decision record with `effect: "approval_required"`, naming that id.
 3. Inserts a `pending` row bound to `(tool, subject, resource, args_digest)` with
-   `expires = now + 900s` — **or rejoins** the row already there, if one is still
-   `pending` or `approved` and unexpired.
+   `expires = now + OBSTAT_APPROVAL_TTL` (§7, 900s by default) — **or rejoins**
+   the row already there, if one is still `pending` or `approved` and unexpired.
 4. Returns — **does not raise** — this value:
 
 ```python
@@ -280,9 +346,21 @@ Policy said `approve` and no usable approval was supplied. obstat:
 ```
 
 A return rather than an error, so the agent can reason about it and tell the user
-what it is waiting for instead of treating a working control as a failure.
-`waiting` is `True` when this rejoined an existing request, which is how an agent
-distinguishes "asked" from "asked again".
+what it is waiting for instead of treating a working control as a failure. This
+is why §4.2 widens the advertised return: a server that validates results against
+the declared type would otherwise turn this payload back into the error it exists
+not to be. `waiting` is `True` when this rejoined an existing request, which is
+how an agent distinguishes "asked" from "asked again".
+
+The approvals table holds the argument *digest*, so `obstat pending` reads what
+the call was for off the record named in step 2 — anything the tool recorded
+under §6.1 is printed beneath the row:
+
+```console
+$ obstat pending
+d41b88f29a43  send_email  human:ana  tool:send_email  871s left
+      to = 'board@example.com'
+```
 
 **The id is derived, not invented.** A random id would mean every retry opens
 another approval, so an agent polling a slow human produces a queue of identical
@@ -379,7 +457,7 @@ fragment, so one failed write costs one record instead of two — `obstat verify
 reports the fragment and everything after it still reads.
 
 ```json
-{"schema": 3,
+{"schema": 4,
  "id": "6430f1a38f8e470a898ca9a116dfb4cc",
  "ts": 1785545412.241792,
  "phase": "decision",
@@ -401,27 +479,61 @@ reports the fragment and everything after it still reads.
 the policy file, so a record points at the line that decided it. `prev` and
 `hash` are the chain (§6.3).
 
-Schema 2 added `prev` and `hash`; schema 3 added `code`. Records written at
-schema 1 have no chain fields and verify as *unverifiable* rather than as damaged
-— a log that predates the chain is not evidence of tampering.
+Schema 2 added `prev` and `hash`; schema 3 added `code`; schema 4 added
+`args_recorded` (§6.1). Records written at schema 1 have no chain fields and
+verify as *unverifiable* rather than as damaged — a log that predates the chain is
+not evidence of tampering.
 
 `via` (§1) is present on an `allow` record only when the subject carries a
 delegation chain: `"via": ["human:ana"]`. It is omitted rather than written empty,
 because `"via": []` on every record of every deployment that never delegates is
-noise in the thing an examiner has to read.
+noise in the thing an examiner has to read. `args_recorded` is omitted on the
+same grounds.
 
-### 6.1 Arguments are fingerprinted, not stored
+### 6.1 Arguments are fingerprinted, and named values are recorded
 
 `args` is `sha256:` over the canonical JSON of the bound arguments. The values
-are deliberately absent: tool arguments carry credentials, personal data and free
+are absent by default: tool arguments carry credentials, personal data and free
 text, and a governance log that leaks them is a liability rather than a control.
 The digest is enough to prove the call that executed is the call that was
 approved, which is what the record is for.
 
+A digest is not enough for the *other* reader. An approver deciding about
+`sha256:ae32e6…` is deciding about nothing, and the resource id only sometimes
+carries the answer — `doc:q3-report` does, `tool:send_email` does not. So a tool
+may name parameters whose values are recorded:
+
+```python
+@guard(record_args=("to", "issue_key"))
+```
+
+```json
+"args_recorded": {"to": "ana@example.com", "issue_key": "ACME-14"}
+```
+
+Normative:
+
+- The allowlist is **explicit and per tool**. There is no wildcard and no
+  "record everything" switch — the absent default is the safe one, and a
+  deployment that wants values names them.
+- Naming a parameter the tool does not have is a `TypeError` **at decoration**.
+  A name that matched nothing would record nothing and say nothing about it,
+  which is the same quiet widening §2 refuses from a typo'd policy key.
+- `args` still covers **every** argument. Recorded values are written beside the
+  digest, never instead of it, so the binding an approval rests on (§5.2) is
+  unchanged by what anyone chose to display.
+- The field is omitted when nothing was named, on the §6 grounds `via` is.
+- It appears on `allow`, `deny` and `approval_required` records alike: an
+  examiner asking what was refused deserves the same answer as an approver
+  asking what is waiting.
+
+Name identifiers, not payloads. The point is that a human can tell which issue,
+which document, which recipient — not that the log holds a copy of the message.
+
 ### 6.2 Outcome records
 
 ```json
-{"schema": 3, "id": "<same id>", "ts": …, "phase": "outcome", "ok": true, "error": null,
+{"schema": 4, "id": "<same id>", "ts": …, "phase": "outcome", "ok": true, "error": null,
  "prev": "…", "hash": "…"}
 ```
 
@@ -523,6 +635,12 @@ is a library nobody can try.
 | `OBSTAT_LOG` | `.obstat/decisions.jsonl` |
 | `OBSTAT_DB` | `.obstat/approvals.db` |
 | `OBSTAT_HALT` | `.obstat/halt` |
+| `OBSTAT_APPROVAL_TTL` | `900` (seconds) |
+
+A TTL that is not a positive number raises rather than falling back to the
+default. An approval window of zero turns every `approve` rule into a call that
+asks, expires and asks again, and a silent fallback is how that gets diagnosed as
+obstat being broken instead of as a typo.
 
 ---
 
@@ -530,10 +648,23 @@ is a library nobody can try.
 
 Ranked by how much they weaken the claim in the first paragraph.
 
+**A resource id is caller-controlled text and nothing normalises it.** §3.3. A
+policy written against `jira_issue:SEC-*` says nothing about `sec-1`, and the
+cost of noticing is a denial that silently did not happen. The callable form of
+`resource` is the entire answer today, which means the answer is applied only
+where a tool author thought of the question. What is missing is not a fold — that
+would be wrong for case-sensitive namespaces — but a way for a *policy* to say
+which of its rules describe a namespace that is case-insensitive.
+
 **No approver authority.** §5.4. Anything beyond a single operator needs the
 approver to be authenticated and distinct from the requester.
 
-**The stop file is all-or-nothing.** §3.4.
+**An approver sees only what the tool chose to show.** §6.1 gives a tool
+`record_args`, and `obstat pending` prints it — but a tool that names nothing
+still sends a human a digest and a resource id to decide on. Nothing warns an
+operator that a rule with `effect = "approve"` sits in front of a tool that
+records no values, which is the configuration where the approval is a rubber
+stamp.
 
 **The chain is unkeyed, and nothing anchors its head.** §6.3 makes an edit or a
 deletion visible, which is where most of the value is — but anyone who can write
@@ -542,8 +673,19 @@ dangling. The answers are a head published where the log's owner cannot reach it
 or append-only storage. Neither is here, so this is tamper-evidence and not proof
 against the operator.
 
+**The stop file is all-or-nothing.** §3.4.
+
 **No retention or rotation on the log.** It grows without bound, and nothing says
-how long a record must be kept.
+how long a record must be kept. Rotation has to carry the chain across files as
+well, or every new file begins at `prev: null` and a deletion at the seam is
+indistinguishable from a rollover.
+
+**The directory sync does not happen on Windows.** It opens a directory as a file
+descriptor, which Windows refuses, so there it is skipped rather than performed
+(§3.1) and the guarantee it exists for — that the log's own directory entry
+survives a crash — is unavailable on that platform. The record's `fsync` still
+happens, so this costs the *first* write of a new log file and nothing after it.
+A platform that can open the directory and then fails to sync it still raises.
 
 **No egress control.** Nothing asks where a result is allowed to go, which is the
 control that matters for tools that send mail or post to channels.
@@ -556,10 +698,14 @@ adapters, not dependencies.
 ## 9. Required tests
 
 These encode the claims above; `tests/test_guard.py` is the current
-implementation of them.
+implementation of them, with §2.3's two commands in `tests/test_cli.py`.
 
 | Property | Test |
 |---|---|
+| a starter policy parses and permits nothing | `test_init_writes_a_policy_that_permits_nothing` |
+| `init` does not overwrite a policy | `test_init_will_not_overwrite_a_policy` |
+| `check` names the rule that decided | `test_check_names_the_rule_that_decided` |
+| a broken policy is reported, not raised | `test_check_reports_a_broken_policy_instead_of_raising` |
 | the record is durable before the body runs | reads the log from inside the body and asserts its own decision is already there |
 | an outcome follows a decision, sharing its id | `test_outcome_is_recorded_after` |
 | a failing body still leaves both records | `test_a_failing_body_still_leaves_both_records` |
@@ -568,14 +714,27 @@ implementation of them.
 | a caller cannot name itself | `test_a_caller_cannot_supply_its_own_subject` |
 | a colliding `subject` parameter is refused at decoration | `test_a_subject_that_would_collide_is_refused_at_decoration` |
 | a delegation chain reaches the record | `test_a_delegation_chain_reaches_the_record` |
+| the approval window is configurable, and a useless one raises | `test_the_approval_window_is_configurable` |
 | an edited record is caught | `TestChain::test_an_edited_record_is_caught` |
 | a removed record is caught | `TestChain::test_a_removed_record_is_caught` |
 | recomputing one hash does not hide the edit | `TestChain::test_a_reused_hash_does_not_hide_an_edit` |
 | a torn line does not swallow the next record | `TestChain::test_a_torn_line_does_not_swallow_the_next_record` |
+| concurrent processes interleave records without splitting one | `TestConcurrency::test_two_processes_write_one_log` |
+| within one process the chain stays a line | `TestConcurrency::test_threads_do_not_split_a_record` |
+| a forked chain verifies | `TestConcurrency::test_a_forked_chain_still_verifies` |
 | `subject` unadvertised, approval id advertised | `test_injected_subject_is_not_advertised…` |
+| an approval is a return value through a real MCP server | `test_an_approval_survives_a_real_mcp_server` |
 | the resource comes from the arguments | `test_resource_comes_from_the_arguments` |
+| a template matches only the spelling it was given | `test_a_template_matches_only_the_spelling_it_was_given` |
+| a callable resource normalises what policy matches | `test_a_callable_resource_normalises_what_policy_matches` |
+| an unknown effect is refused | `test_an_unknown_effect_is_refused` |
 | an unresolvable resource denies | `test_an_unresolvable_resource_denies` |
 | arguments are fingerprinted, not stored | `test_arguments_are_fingerprinted_not_stored` |
+| only the named arguments are recorded | `test_only_the_named_arguments_are_recorded` |
+| nothing is recorded unless it was named | `test_nothing_is_recorded_unless_it_was_named` |
+| an argument that does not exist is refused at decoration | `test_recording_an_argument_that_does_not_exist_is_refused_at_decoration` |
+| a denial records the named arguments | `test_a_denial_records_the_named_arguments` |
+| an approver can see what they are approving | `test_pending_shows_what_is_being_approved` |
 | the stop file denies, and lifting it restores | `test_the_stop_file_denies_everything` |
 | approval is two-phase and does not run early | `TestApproval::test_first_call_asks_and_does_not_run` |
 | approval is single-use | `TestApproval::test_retry_after_approval_runs_once` |
@@ -585,3 +744,50 @@ implementation of them.
 | approval does not travel to another call | `TestApproval::test_an_approval_does_not_travel_to_another_call` |
 | a denied or invented approval denies | `TestApproval::test_a_denied_approval_denies`, `…invented_approval_id…` |
 | async tools take the same path | `test_async_tools_go_through_the_same_gate` |
+
+---
+
+## 10. Direction
+
+**Not normative. Nothing in this section is implemented**, and code that
+disagrees with it is not a bug. It is here so a reader can tell a missing feature
+from an undecided one: §8 is what is weak, this is what is next.
+
+**Shadow mode, and a policy written from traffic.** Decisions recorded without
+being enforced, so obstat can be installed in front of a live server for a week
+before it denies anything — then `obstat suggest` reads the log back and emits
+candidate rules. Policy authoring is the barrier to adoption, and an empty file
+is not a starting point.
+
+**Counterfactual replay.** `obstat check --policy new.toml --against
+decisions.jsonl`: run decisions already recorded through a proposed policy and
+print only what changes. Answers "I tightened a rule, what breaks" from real
+traffic rather than from imagination, and needs nothing that §2 and §6 do not
+already provide.
+
+**An evidence pack.** One command producing what a controls walkthrough asks
+for over a period: every call that required an approval, who decided it and
+when, every denial, and the result of §6.3 across the same range. The log is
+already the input; what is missing is the deliverable.
+
+**An anchored head.** §8. Counter-signing the chain head somewhere the log's
+owner cannot reach is the difference between tamper-evidence and
+non-repudiation, and it is the only item here that changes what obstat can
+*claim*.
+
+**Result digests.** §6.1 fingerprints the arguments, which proves the call that
+ran is the call that was approved. The same over the return value would say
+something about what came back, and is the groundwork any egress rule needs.
+
+**Break-glass with a retrospective.** The stop file's opposite: one call
+permitted against policy, recorded as an override, and listed as outstanding
+until somebody signs it off. That it is visible matters more than that it is
+rare.
+
+**The record as a format rather than a library.** §6 is language-agnostic. A
+second implementation writing the same lines, verified by the same rules, would
+make this document the product and the Python package one implementation of it.
+
+Also wanted and unremarkable: approval channels beyond the CLI (§8), per-subject
+call budgets as a rule key, and a trace id on the record so it joins traces a
+host already collects.

{obstat-0.2.0 → obstat-0.3.1}/obstat/__init__.py

@@ -8,4 +8,4 @@ from .guard import Denied, Subject, guard, set_subject_resolver
 from .policy import PolicyError
 
 __all__ = ["Denied", "PolicyError", "Subject", "guard", "set_subject_resolver"]
-__version__ = "0.2.0"
+__version__ = "0.3.1"