wardn 0.1.0.dev0__tar.gz

wardn-0.1.0.dev0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

wardn-0.1.0.dev0/.gitignore

@@ -0,0 +1,12 @@
+# spike outputs are regenerable (and byte-deterministic — run spike/spike.py)
+spike/out/
+
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+.pytest_cache/
+*.egg-info/
+
+# flagship example outputs are regenerable
+examples/flagship/runs/

wardn-0.1.0.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pi-Wi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wardn-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: wardn
+Version: 0.1.0.dev0
+Summary: Bounded, auditable action governor for LLM agents — a policy gate between an MCP client and its servers.
+Project-URL: Repository, https://github.com/Pi-Wi/warden
+Project-URL: Documentation, https://github.com/Pi-Wi/warden/tree/main/docs
+Author: Pi-Wi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,audit,governance,ledger,llm,mcp,model-context-protocol,policy
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# wardn
+
+Bounded, auditable action governor for LLM agents — a policy gate between an
+MCP client and its servers. Every tool call is allowed, denied, or
+quarantined by a rule you declared; run-wide budgets cap total side-effects
+with loud refusals; and every attempt lands in an append-only,
+timestamp-free, byte-deterministic ledger that replays offline and diffs in
+CI.
+
+wardn bounds and audits. It does not sandbox, and it is not a content-safety
+product.
+
+## Status
+
+**Pre-release — M2 (adoptable, CI-integrable) is built.** The proxy governs
+one or more real MCP servers over stdio; `wardn review` decides quarantined
+calls from any terminal; `wardn replay` reproduces every decision offline;
+`wardn revert` undoes declared-reversible effects from the ledger file
+alone; and `wardn diff` turns two ledgers into a CI verdict — exit 4 the
+moment governed activity drifts. Two identical runs emit byte-identical
+ledgers, including against the real
+`@modelcontextprotocol/server-filesystem`.
+
+Not yet on PyPI — install from a clone (`pip install .`). The roadmap,
+locked decisions, and spike record live in [TODO.md](TODO.md).
+
+## The gap
+
+Permission systems exist (per-client allow/ask/deny rules), approval
+services exist, security gateways exist, eval-time diffs exist. But none of
+them owns the middle: side-effect governance that is *declared* (a policy
+file, not scattered client settings), *bounded* ("at most 2 writes", not
+just "ask"), and *auditable* — emitted as a single deterministic artifact a
+CI job can diff with an exit code.
+
+That artifact is the whole point of wardn. A permission prompt leaves no
+record. An observability stream isn't deterministic. wardn's ledger is
+both: the decision log and the drift detector, one file.
+
+## The core idea: one ledger, three uses
+
+Every attempt — allowed, denied, quarantined, refused by a budget — is one
+recorded event stream: what was attempted, which rule matched, how the call
+was classified (and by what authority), what was decided, why, and what came
+back.
+
+- **Read it forward** → the audit report. Every side-effect, explained.
+- **Replay it** (`wardn replay`) → the decisions, reproduced offline from
+  policy + file alone. A tampered ledger or a swapped policy refuses loudly.
+- **Replay it inverted** (`wardn revert`) → the undo. Declared-reversible
+  effects are reverted from the file alone — the undo call was resolved and
+  recorded at capture time, so revert needs no policy, only the ledger and a
+  live server. If the world drifted since the run, revert refuses rather
+  than guesses.
+
+And because the file is byte-deterministic — no timestamps, no PIDs, no
+nonces — `wardn diff yesterday.jsonl today.jsonl` is a CI gate: same
+policy, same attempts, same decisions, or exit 4.
+
+## Quick look
+
+A policy is an ordered list of rules, first match wins, with a mandatory
+explicit default — a policy that doesn't say what happens to unmatched
+calls is invalid:
+
+```json
+{
+  "format": "wardn-policy/1",
+  "default": "deny",
+  "budget": {"max_calls": 20, "max_writes": 5, "max_spend": 1.0},
+  "approval_timeout_s": 300,
+  "rules": [
+    {
+      "id": "allow-reads",
+      "match": {"server": "filesystem", "tool": "read_text_file"},
+      "effect": "read",
+      "disposition": "allow",
+      "reason": "reads are harmless here"
+    },
+    {
+      "id": "bound-writes",
+      "match": {"server": "filesystem", "tool": "write_file",
+                "args": {"path": {"path_prefix": "/work/out/"}}},
+      "effect": "write",
+      "disposition": "allow",
+      "bound": {"max_calls": 2},
+      "cost_per_call": 0.1,
+      "capture": {"tool": "read_text_file", "args_from": {"path": "path"}},
+      "inverse": {"tool": "write_file",
+                  "args": {"path": "$args.path", "content": "$capture.value"},
+                  "expect": "$args.content"},
+      "reason": "writes capped at 2, under out/ only, pre-state captured"
+    },
+    {
+      "id": "quarantine-moves",
+      "match": {"server": "filesystem", "tool": "move_file"},
+      "effect": "destructive",
+      "disposition": "quarantine",
+      "reason": "moves need a human"
+    }
+  ]
+}
+```
+
+Put wardn between your client and the server — the client config points at
+wardn, wardn spawns the real server:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "wardn",
+      "args": ["proxy", "--policy", "policy.json", "--ledger", "run.jsonl",
+               "--", "npx", "-y", "@modelcontextprotocol/server-filesystem",
+               "/work"]
+    }
+  }
+}
+```
+
+The agent now reads freely, gets its third write refused loudly (an error
+result naming the rule and the bound — the agent can read why and adapt),
+and blocks on `move_file` until someone, in any terminal, runs:
+
+```console
+$ wardn review list --queue run.jsonl.queue.json
+q6  move_file  {"source":"/work/report.txt","destination":"/work/old.txt"}  rule=quarantine-moves  — moves need a human
+
+$ wardn review approve q6 --queue run.jsonl.queue.json --by phiwir
+q6: approve by phiwir
+```
+
+Afterwards, the run is a file:
+
+```console
+$ wardn replay --policy policy.json --ledger run.jsonl
+replayed 8 attempt(s) — every decision reproduced by this policy
+
+$ wardn revert --ledger run.jsonl -- npx -y @modelcontextprotocol/server-filesystem /work
+applied 2 undo(s) — revert ledger: run.jsonl.revert.jsonl
+
+$ wardn diff approved/run.jsonl run.jsonl && echo "no drift"
+```
+
+Several servers can sit behind one gate — `wardn proxy --servers
+servers.json` takes a file in the same shape as an MCP client config, and
+rules match on the server's name. See [docs/concepts.md](docs/concepts.md)
+for what multi-server mode honestly does and doesn't proxy.
+
+## What wardn is not
+
+- **Not a sandbox.** wardn is a policy gate in front of cooperative
+  transports. A hostile server, or a client that bypasses the proxy, is out
+  of scope — and argument constraints are string constraints:
+  `path_prefix: "out/"` happily matches `out/../secret.txt`. wardn does not
+  resolve paths; that is a sandbox's job. Never treat a wardn policy as an
+  isolation boundary.
+- **Not content safety.** wardn governs side-effects, not text. Prompt
+  injection defense is a different layer.
+- **No LLM anywhere in the enforcement path.** A decision is a pure
+  function of policy + request + recorded approvals. Ever.
+- **No measured spend.** `max_spend` refuses on arithmetic over *declared*
+  costs (`cost_per_call`), never on billing APIs — wardn cannot observe
+  real spend and doesn't pretend to.
+
+## Docs
+
+- [docs/concepts.md](docs/concepts.md) — rules, dispositions, bounds,
+  classification, quarantine, capture/revert, and the determinism claim
+  stated precisely (including its honest asterisks).
+- [docs/policy-format.md](docs/policy-format.md) — `wardn-policy/1`,
+  normative.
+- [docs/ledger-format.md](docs/ledger-format.md) — `wardn-ledger/1`, the
+  compatibility contract. The ledger format and the proxy CLI are the two
+  things wardn promises stability for.
+- [docs/ci.md](docs/ci.md) — the CI story: budgets as drift tripwires,
+  `wardn diff` as the gate.
+- [docs/embedding.md](docs/embedding.md) — the engine API for non-MCP
+  embeddings: `govern_call` in front of any tool-calling boundary.
+
+## Family
+
+Sibling to [agentrec](https://github.com/Pi-Wi/agent-rec) (records what
+models *say*) and [mendr](https://github.com/Pi-Wi/mendr) (repairs what data
+*got wrong*) — wardn governs what agents *do*. Same ethos: declared,
+bounded, recorded; the record is the product; no LLM anywhere in the
+enforcement path.

wardn-0.1.0.dev0/README.md

@@ -0,0 +1,187 @@
+# wardn
+
+Bounded, auditable action governor for LLM agents — a policy gate between an
+MCP client and its servers. Every tool call is allowed, denied, or
+quarantined by a rule you declared; run-wide budgets cap total side-effects
+with loud refusals; and every attempt lands in an append-only,
+timestamp-free, byte-deterministic ledger that replays offline and diffs in
+CI.
+
+wardn bounds and audits. It does not sandbox, and it is not a content-safety
+product.
+
+## Status
+
+**Pre-release — M2 (adoptable, CI-integrable) is built.** The proxy governs
+one or more real MCP servers over stdio; `wardn review` decides quarantined
+calls from any terminal; `wardn replay` reproduces every decision offline;
+`wardn revert` undoes declared-reversible effects from the ledger file
+alone; and `wardn diff` turns two ledgers into a CI verdict — exit 4 the
+moment governed activity drifts. Two identical runs emit byte-identical
+ledgers, including against the real
+`@modelcontextprotocol/server-filesystem`.
+
+Not yet on PyPI — install from a clone (`pip install .`). The roadmap,
+locked decisions, and spike record live in [TODO.md](TODO.md).
+
+## The gap
+
+Permission systems exist (per-client allow/ask/deny rules), approval
+services exist, security gateways exist, eval-time diffs exist. But none of
+them owns the middle: side-effect governance that is *declared* (a policy
+file, not scattered client settings), *bounded* ("at most 2 writes", not
+just "ask"), and *auditable* — emitted as a single deterministic artifact a
+CI job can diff with an exit code.
+
+That artifact is the whole point of wardn. A permission prompt leaves no
+record. An observability stream isn't deterministic. wardn's ledger is
+both: the decision log and the drift detector, one file.
+
+## The core idea: one ledger, three uses
+
+Every attempt — allowed, denied, quarantined, refused by a budget — is one
+recorded event stream: what was attempted, which rule matched, how the call
+was classified (and by what authority), what was decided, why, and what came
+back.
+
+- **Read it forward** → the audit report. Every side-effect, explained.
+- **Replay it** (`wardn replay`) → the decisions, reproduced offline from
+  policy + file alone. A tampered ledger or a swapped policy refuses loudly.
+- **Replay it inverted** (`wardn revert`) → the undo. Declared-reversible
+  effects are reverted from the file alone — the undo call was resolved and
+  recorded at capture time, so revert needs no policy, only the ledger and a
+  live server. If the world drifted since the run, revert refuses rather
+  than guesses.
+
+And because the file is byte-deterministic — no timestamps, no PIDs, no
+nonces — `wardn diff yesterday.jsonl today.jsonl` is a CI gate: same
+policy, same attempts, same decisions, or exit 4.
+
+## Quick look
+
+A policy is an ordered list of rules, first match wins, with a mandatory
+explicit default — a policy that doesn't say what happens to unmatched
+calls is invalid:
+
+```json
+{
+  "format": "wardn-policy/1",
+  "default": "deny",
+  "budget": {"max_calls": 20, "max_writes": 5, "max_spend": 1.0},
+  "approval_timeout_s": 300,
+  "rules": [
+    {
+      "id": "allow-reads",
+      "match": {"server": "filesystem", "tool": "read_text_file"},
+      "effect": "read",
+      "disposition": "allow",
+      "reason": "reads are harmless here"
+    },
+    {
+      "id": "bound-writes",
+      "match": {"server": "filesystem", "tool": "write_file",
+                "args": {"path": {"path_prefix": "/work/out/"}}},
+      "effect": "write",
+      "disposition": "allow",
+      "bound": {"max_calls": 2},
+      "cost_per_call": 0.1,
+      "capture": {"tool": "read_text_file", "args_from": {"path": "path"}},
+      "inverse": {"tool": "write_file",
+                  "args": {"path": "$args.path", "content": "$capture.value"},
+                  "expect": "$args.content"},
+      "reason": "writes capped at 2, under out/ only, pre-state captured"
+    },
+    {
+      "id": "quarantine-moves",
+      "match": {"server": "filesystem", "tool": "move_file"},
+      "effect": "destructive",
+      "disposition": "quarantine",
+      "reason": "moves need a human"
+    }
+  ]
+}
+```
+
+Put wardn between your client and the server — the client config points at
+wardn, wardn spawns the real server:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "wardn",
+      "args": ["proxy", "--policy", "policy.json", "--ledger", "run.jsonl",
+               "--", "npx", "-y", "@modelcontextprotocol/server-filesystem",
+               "/work"]
+    }
+  }
+}
+```
+
+The agent now reads freely, gets its third write refused loudly (an error
+result naming the rule and the bound — the agent can read why and adapt),
+and blocks on `move_file` until someone, in any terminal, runs:
+
+```console
+$ wardn review list --queue run.jsonl.queue.json
+q6  move_file  {"source":"/work/report.txt","destination":"/work/old.txt"}  rule=quarantine-moves  — moves need a human
+
+$ wardn review approve q6 --queue run.jsonl.queue.json --by phiwir
+q6: approve by phiwir
+```
+
+Afterwards, the run is a file:
+
+```console
+$ wardn replay --policy policy.json --ledger run.jsonl
+replayed 8 attempt(s) — every decision reproduced by this policy
+
+$ wardn revert --ledger run.jsonl -- npx -y @modelcontextprotocol/server-filesystem /work
+applied 2 undo(s) — revert ledger: run.jsonl.revert.jsonl
+
+$ wardn diff approved/run.jsonl run.jsonl && echo "no drift"
+```
+
+Several servers can sit behind one gate — `wardn proxy --servers
+servers.json` takes a file in the same shape as an MCP client config, and
+rules match on the server's name. See [docs/concepts.md](docs/concepts.md)
+for what multi-server mode honestly does and doesn't proxy.
+
+## What wardn is not
+
+- **Not a sandbox.** wardn is a policy gate in front of cooperative
+  transports. A hostile server, or a client that bypasses the proxy, is out
+  of scope — and argument constraints are string constraints:
+  `path_prefix: "out/"` happily matches `out/../secret.txt`. wardn does not
+  resolve paths; that is a sandbox's job. Never treat a wardn policy as an
+  isolation boundary.
+- **Not content safety.** wardn governs side-effects, not text. Prompt
+  injection defense is a different layer.
+- **No LLM anywhere in the enforcement path.** A decision is a pure
+  function of policy + request + recorded approvals. Ever.
+- **No measured spend.** `max_spend` refuses on arithmetic over *declared*
+  costs (`cost_per_call`), never on billing APIs — wardn cannot observe
+  real spend and doesn't pretend to.
+
+## Docs
+
+- [docs/concepts.md](docs/concepts.md) — rules, dispositions, bounds,
+  classification, quarantine, capture/revert, and the determinism claim
+  stated precisely (including its honest asterisks).
+- [docs/policy-format.md](docs/policy-format.md) — `wardn-policy/1`,
+  normative.
+- [docs/ledger-format.md](docs/ledger-format.md) — `wardn-ledger/1`, the
+  compatibility contract. The ledger format and the proxy CLI are the two
+  things wardn promises stability for.
+- [docs/ci.md](docs/ci.md) — the CI story: budgets as drift tripwires,
+  `wardn diff` as the gate.
+- [docs/embedding.md](docs/embedding.md) — the engine API for non-MCP
+  embeddings: `govern_call` in front of any tool-calling boundary.
+
+## Family
+
+Sibling to [agentrec](https://github.com/Pi-Wi/agent-rec) (records what
+models *say*) and [mendr](https://github.com/Pi-Wi/mendr) (repairs what data
+*got wrong*) — wardn governs what agents *do*. Same ethos: declared,
+bounded, recorded; the record is the product; no LLM anywhere in the
+enforcement path.