arcaeon-adapter 0.1.0__tar.gz

arcaeon_adapter-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+*.log.jsonl
+.venv/
+mcp-publisher.exe

arcaeon_adapter-0.1.0/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+## 0.1.0 — 2026-08-19
+
+First version. An MCP stdio proxy that records every tool call to a tamper-evident
+ledger without the agent's cooperation.
+
+### Why this exists
+
+`arcaeon_ledger.Ledger.append()` records whatever a caller chooses to pass it.
+That is a diary: an agent that skips the append leaves no trace, and one that
+curates its appends leaves a flattering record. Any regime asking for *automatic*
+recording (EU AI Act Art. 12(1) is the one on our desk) cannot be met by a library
+the logged party calls voluntarily. MCP stdio is the seam where "no cooperation
+required" is literally true — the client and server talk newline-delimited
+JSON-RPC over a pipe, and a process sitting in that pipe sees everything at the
+protocol level, in a process the agent does not own.
+
+Design memo: `projects/online_business/ADAPTER_LAYER_DESIGN_2026-08-18.md`
+(seam ranking, schema, pricing sketch, and the frozen honest-limit copy).
+
+### Added
+
+- **`arcaeon_adapter/proxy.py`** — the proxy.
+  `python -m arcaeon_adapter --ledger PATH -- <server command...>`. Spawns the
+  wrapped server, relays stdin→child and child→stdout byte-for-byte, logs the
+  seam. Child's stderr is inherited (not piped); child's exit code is propagated.
+- **`arcaeon_adapter/observer.py`** — non-destructive stream observation.
+  `FrameSplitter` (chunk reassembly, unterminated final frame, bounded buffer with
+  resync) and `SeamObserver` (request/response pairing by JSON-RPC `id`, row
+  emission, session brackets).
+- **`arcaeon_adapter/_ledger.py`** — ledger binding, with a byte-compatible
+  fallback writer + verifier for machines without `arcaeon-ledger` installed.
+- **`arcaeon_adapter/selftest.py`** — mutation harness. Five cases, each observed
+  GREEN then forced RED on its own defect, with a no-op guard between.
+- **`arcaeon_adapter/_echo_server.py`** — deterministic synthetic MCP server, so
+  fidelity can be measured against an unproxied control run.
+- **Row schema:** `tool_call`, `session_begin`, `session_end`, `mcp_initialize`,
+  `tools_list`. Every row carries `seam="mcp-stdio"` + `seam_impl`, `session`,
+  `seq`, `server`.
+- **Flags:** `--ledger`, `--server`, `--session`, `--raw`, `--max-frame`.
+- 65 pytest tests.
+
+### Decisions, and what they cost
+
+- **Digest-only by default; `--raw` opt-in.** Rows prove *which* bytes crossed
+  the seam without warehousing them. Cost: you cannot reconstruct a payload from
+  a row after the fact. That is the trade we want — an audit log that silently
+  accumulates everyone's data is a liability, and person-free rows are far easier
+  to retain for years.
+- **Session is process-scoped, not `initialize`-scoped.** One proxy process = one
+  session, and `session_begin` fires at start rather than at the MCP handshake. A
+  begin row that waits for `initialize` does not exist when a client connects and
+  dies, and then there is nothing for `session_end` to pair with. What the
+  handshake tells us arrives separately as `mcp_initialize`.
+- **`seam` is `"mcp-stdio"`.** The design memo sketched `"mcp-proxy/0.1"`, folding
+  the tier and the version into one string. Split: `seam` names the *provenance
+  tier* and must stay stable for a downstream verifier to switch on, while
+  `seam_impl` carries the build. A tier identifier that changes every release is
+  not a tier identifier.
+- **An unanswered call is still rowed** (`status="unanswered"`, at shutdown).
+  Without it, killing the server mid-call erases the fact that the call crossed
+  the seam.
+- **Oversized frames are counted and reported**, not silently skipped. A gap in
+  the record has to be visible in the record.
+- **`arcaeon-ledger` is not a hard dependency.** This gets wrapped around
+  somebody else's working server by a config edit; a missing package must never be
+  why their server fails to start. The fallback is byte-compatible and labelled in
+  `ledger_backend`.
+- **`.proxy` is imported lazily from `__init__`.** Not tidiness: importing it
+  eagerly made runpy print a `RuntimeWarning` to stderr on every launch, and the
+  proxy inherits the wrapped server's stderr. A logging sidecar that dirties the
+  logs is a bad joke. Guarded by a test.
+
+### Found while building
+
+- The mutation harness's no-op guard fired twice, correctly, on mutations that
+  proved nothing:
+  1. The `reserialize` fidelity fault originally did `json.dumps(json.loads(f))`,
+     which reproduced the echo server's own output byte-for-byte — a no-op. It now
+     re-emits sorted + compact, which actually differs.
+  2. The `one_row_per_call` mutation originally delivered every frame twice, and
+     the row count did **not** change: popping the pending map makes the observer
+     idempotent against duplicate delivery. Good property, useless mutation. The
+     robustness is now its own test (`test_duplicate_response_delivery_does_not_
+     double_row`) and the mutation is a log-as-you-see observer that really does
+     break pairing.
+
+  Both are the harness doing its job — a check that stays green on its own defect
+  is decoration.
+
+### Deliberately left for v1
+
+- `--authority principal=...` — stamp `arcaeon_ledger.authority()` on every row.
+- `--bind-inputs` — auto `bind_artefact` on input payloads.
+- `--auto-pin N` — publish a head pin every N rows to a witness (this is the
+  metered surface; the library itself stays free).
+- Harness-hook recipe (`examples/claude_code_hooks/`) — catches built-ins the
+  proxy is structurally blind to, at the cost of being per-harness config and
+  cooperative-grade rather than infrastructure-grade.
+- HTTP/gateway seam — the widest view of agent *intent*, and the most
+  person-full; a hosted-tier feature, not a v0 move.
+- Streamable-HTTP MCP transport. v0 is stdio only, which is the transport where
+  a proxy is a config edit rather than a deployment.
+- A `verify`-side reader that reports seam coverage across many session logs.

arcaeon_adapter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arcaeon
+
+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.

arcaeon_adapter-0.1.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.5
+Name: arcaeon-adapter
+Version: 0.1.0
+Summary: MCP stdio proxy that records every tool call to a tamper-evident ledger, without the agent's cooperation.
+Project-URL: Homepage, https://arcaeon.io
+Project-URL: Changelog, https://github.com/dan8433-user/ledger/blob/main/adapter/CHANGELOG.md
+Project-URL: Source, https://github.com/dan8433-user/ledger/tree/main/adapter
+Project-URL: Issues, https://github.com/dan8433-user/ledger/issues
+Author: Arcaeon
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,audit,compliance,mcp,provenance,proxy,tamper-evident
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: arcaeon-ledger>=0.5.7; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: ledger
+Requires-Dist: arcaeon-ledger>=0.5.7; extra == 'ledger'
+Description-Content-Type: text/markdown
+
+# arcaeon-adapter
+
+**`arcaeon-ledger` proves a record wasn't altered. It can't prove the record is _complete_ — because the agent decides what to write. This moves the pen.**
+
+`arcaeon-adapter` is a stdio proxy that sits between an MCP client and an MCP
+server. It forwards JSON-RPC byte-for-byte, and on every `tools/call` it writes
+one hash-chained row to its own ledger: which tool, digests of the arguments and
+the result, ok or error, how long it took.
+
+It runs in its own OS process. The agent is not consulted, cannot skip it, and
+cannot see it.
+
+```
+pip install arcaeon-adapter arcaeon-ledger
+```
+
+Wrap any MCP server's command — one line of config, zero code:
+
+```json
+{ "mcpServers": {
+    "ledger": {
+      "command": "python",
+      "args": ["-m", "arcaeon_adapter", "--ledger", "seam.log.jsonl", "--",
+               "python", "-m", "arcaeon_ledger.mcp_server", "--log", "agent.log.jsonl"]
+    }
+} }
+```
+
+Or straight from a shell:
+
+```
+python -m arcaeon_adapter --ledger seam.log.jsonl -- <your mcp server command...>
+```
+
+## What lands in the log
+
+Real rows, from wrapping `arcaeon-ledger`'s own MCP server (the ledger logging
+itself through the ledger), trimmed for width:
+
+```json
+{"evt":"session_begin","seam":"mcp-stdio","seam_impl":"arcaeon-adapter/0.1.0",
+ "session":"25eda195-70e8-45cb-9035-be9f61cfc759","seq":1,
+ "server":"arcaeon_ledger.mcp_server","ledger_backend":"arcaeon-ledger/0.5.7",
+ "command":["python","-m","arcaeon_ledger.mcp_server","--log","agent.log.jsonl"],
+ "command_digest":"sha256:json-c14n:v1:ec06bd01…","raw_payloads":false,
+ "ts":"2026-08-19T14:18:08Z","chain":"0081ec1fe5d98395192f595e553b4133"}
+
+{"evt":"tools_list","seq":3,"tools":["ledger_append","ledger_verify"],"tool_count":2,
+ "tools_digest":"sha256:json-c14n:v1:b85c9fce…","status":"ok", …}
+
+{"evt":"tool_call","seq":4,"tool":"ledger_append","rpc_id":"3",
+ "args_digest":"sha256:json-c14n:v1:cfb2bb50…",
+ "result_digest":"sha256:json-c14n:v1:ba037f70…",
+ "status":"ok","ms":144, …}
+
+{"evt":"session_end","seq":6,"reason":"child_exit","exit_code":0,
+ "rows_before_end":5,"calls":2, …}
+```
+
+In that same run, the wrapped server's *own* log — the diary it keeps when the
+agent remembers to call `ledger_append` — had **one** row. The seam log had six.
+That difference is the entire product.
+
+| field | why it's there |
+|---|---|
+| `evt` | `tool_call`, `session_begin`, `session_end`, `mcp_initialize`, `tools_list` |
+| `seam` | always `"mcp-stdio"` — the **provenance tier**. A separate process saw this at the protocol level. A downstream verifier reads this field to tell infrastructure-grade capture from a cooperative in-process callback the agent could simply not call. |
+| `session` / `seq` | one proxy process = one session; `seq` is a dense total order within it. `session_begin` + `session_end` bracket the run so a reviewer can pair a session's start and end. |
+| `args_digest` / `result_digest` | `sha256:json-c14n:v1:<hex>` — self-describing, so a stranger holding only the row can reproduce the computation. |
+| `status` / `ms` | `ok` / `error` / `unanswered`, and wall-clock duration. `error` covers **both** a JSON-RPC `error` and a `result` carrying `isError: true`. |
+
+**Digests, not payloads, by default.** The row proves *which* bytes crossed the
+seam without keeping them. An audit log that quietly becomes a copy of every
+prompt and every result is a liability, not an asset — and a person-free core is
+much easier to retain for years. `--raw` embeds the payloads for deployers who
+own that risk; the digests stay either way.
+
+**A call that never gets an answer still gets a row** (`status: "unanswered"`).
+Otherwise "kill the server mid-call" would be a way to make an action leave no
+trace at the seam, which is the exact hole this exists to close.
+
+## Verify it
+
+The seam log is an ordinary `arcaeon-ledger` file:
+
+```
+python -m arcaeon_ledger.cli verify seam.log.jsonl
+```
+
+Edit a row, delete one, reorder them — every later link breaks and `verify` names
+the exact line.
+
+## The honest limit
+
+> **An adapter on one seam logs that seam completely — and nothing else.** An
+> agent can still act around it: a direct HTTP call, an un-wrapped MCP server, a
+> shell command never crosses this proxy and never hits this ledger. The
+> second-set-of-books problem does not go away; no logging layer can force total
+> honesty. What the adapter guarantees is narrower and real: *everything that
+> crossed the instrumented seam is in the record, automatically, and the record
+> proves itself.* Honesty is forced at the seams, not everywhere — not a lock, a
+> neighborhood.
+
+Specifically **blind** to:
+
+- your harness's built-in tools (Bash, file edits, web fetch) — they never touch MCP
+- any MCP server you did not wrap
+- HTTP the agent makes natively
+- the model's reasoning, which is not an action and leaves no wire trace
+- frames larger than `--max-frame` (relayed fine; counted and reported in
+  `session_end` as `oversize_frames_unlogged`, never a silent gap)
+
+And on compliance, plainly: **this does not make anyone compliant with
+anything.** Regulations like the EU AI Act's Art. 12 place duties on a *provider*
+or *deployer*, and duties land on people, not libraries. What this is: a
+mechanism that makes recording at one seam automatic rather than voluntary,
+which is a thing you would otherwise have to build. Retention policy, log
+semantics, risk classification, and every other obligation remain yours. Anyone
+selling you a package that "makes you compliant" is selling you a story.
+
+Whoever controls the config can also remove the wrapper. That is the same class
+of limit every logging layer has, and it is stated here rather than in a footnote.
+
+## Fidelity is the P0 property
+
+A proxy that corrupts, reorders, or delays a customer's JSON-RPC is worse than no
+proxy at all. So the design puts fidelity ahead of observation, structurally:
+
+- **Bytes are forwarded first, observed second, from a copy.** A parsing defect
+  here cannot alter or withhold traffic; the worst it can do is produce a wrong
+  row.
+- **Raw binary end to end.** No text mode anywhere — on Windows that would rewrite
+  `\n` as `\r\n` and silently alter every frame.
+- **No reframing, ever.** We never parse a frame and re-emit it. The classic proxy
+  bug is `json.dumps(json.loads(frame))`: semantically identical, byte-different.
+- **One thread per direction**, so ordering within a direction is the OS's.
+- **The child's stderr is inherited, not piped.** Its diagnostics land exactly
+  where they did unwrapped, and the proxy itself prints nothing on an honest run.
+- **Malformed frames are relayed untouched and not logged.** A server that prints
+  a stray line to stdout keeps working; we don't guess, because a guess in an
+  audit record is fiction.
+- **The child's exit code is the proxy's exit code.**
+
+This is tested by running a scripted client against a synthetic MCP server
+directly, then through the proxy, and requiring the two stdout streams to be
+identical *bytes* — including a 4 MB frame spanning ~64 pipe reads, unicode,
+embedded CRLF, malformed lines, a notification with no id, and a final frame with
+no trailing newline.
+
+## Prove the checks can fail
+
+```
+python -m arcaeon_adapter.selftest
+```
+
+An instrument that has never failed proves nothing. Every case runs GREEN on a
+clean fixture, then **mutates** and requires the same check to go RED — with a
+no-op guard in between, because a mutation that changes nothing proves nothing
+either.
+
+```
+PASS passthrough_fidelity GREEN: 2001202 bytes identical byte-for-byte through the proxy
+PASS passthrough_fidelity RED on reserialize: corruption detected (length 2001202 vs 2001097)
+PASS passthrough_fidelity RED on drop_byte: corruption detected (length 2001202 vs 2001168)
+PASS one_row_per_call GREEN: 5 tools/call frames -> 5 tool_call rows, 9 rows total, seq 1..9
+PASS one_row_per_call RED on log_on_request: count check caught 10 rows for 5 calls
+PASS unanswered_call_logged GREEN: unanswered `quiet` call rowed with args_digest bound
+PASS unanswered_call_logged RED on no_flush: dropping the shutdown flush loses the row
+PASS tamper_detected GREEN: seam log verifies (ok=True, rows=9)
+PASS tamper_detected RED on edited args_digest: first_break='line 4: chain mismatch'
+PASS digest_recipe_frozen GREEN: 3 frozen json-c14n:v1 vectors reproduce exactly
+PASS digest_recipe_frozen RED on unsorted_keys: drifted canonicalizer produces a different digest
+
+ALL CHECKS PASSED — and every one was observed failing on its own defect.
+```
+
+The fidelity mutations are injected into the **real relay**, not a mock, so what's
+proven is that the comparison would catch a regression in the shipping code path.
+
+## Options
+
+```
+--ledger PATH      seam ledger (required). Keep it SEPARATE from any ledger the
+                   wrapped server writes: one file, one writer, clean provenance.
+--server NAME      label for the wrapped server in every row (default: derived
+                   from the command — `-m pkg.mod` reads as "pkg.mod", not "python")
+--session ID       session id (default: a fresh uuid4 per proxy process)
+--raw              embed raw argument and result payloads. Off by default.
+--max-frame BYTES  frames larger than this are relayed but not logged (default 64 MiB)
+```
+
+## Install and dependencies
+
+Stdlib only at runtime. `arcaeon-ledger` is the intended writer and is what makes
+a row provable — but it is **not** a hard dependency, on purpose: this gets
+wrapped around somebody else's working MCP server by editing one line of config,
+and a missing package must never be why their server fails to start. Without it,
+rows are written by a byte-compatible fallback and `session_begin` says so in
+`ledger_backend`, so a reviewer never has to guess which writer produced a chain.
+(That byte-compatibility is asserted in the test suite, not just claimed here.)
+
+**No network calls at runtime.** Ever.
+
+```
+pytest -q                            # 65 tests
+python -m arcaeon_adapter.selftest   # the mutation harness
+```
+
+## Status
+
+v0. Works, tested, dogfooded on our own MCP server. Deliberately not yet built:
+`--authority` stamping, `--bind-inputs` artefact binding, `--auto-pin` witness
+publication, and harness-hook / HTTP-gateway seams. See `CHANGELOG.md`.
+
+MIT.

arcaeon_adapter-0.1.0/README.md

@@ -0,0 +1,215 @@
+# arcaeon-adapter
+
+**`arcaeon-ledger` proves a record wasn't altered. It can't prove the record is _complete_ — because the agent decides what to write. This moves the pen.**
+
+`arcaeon-adapter` is a stdio proxy that sits between an MCP client and an MCP
+server. It forwards JSON-RPC byte-for-byte, and on every `tools/call` it writes
+one hash-chained row to its own ledger: which tool, digests of the arguments and
+the result, ok or error, how long it took.
+
+It runs in its own OS process. The agent is not consulted, cannot skip it, and
+cannot see it.
+
+```
+pip install arcaeon-adapter arcaeon-ledger
+```
+
+Wrap any MCP server's command — one line of config, zero code:
+
+```json
+{ "mcpServers": {
+    "ledger": {
+      "command": "python",
+      "args": ["-m", "arcaeon_adapter", "--ledger", "seam.log.jsonl", "--",
+               "python", "-m", "arcaeon_ledger.mcp_server", "--log", "agent.log.jsonl"]
+    }
+} }
+```
+
+Or straight from a shell:
+
+```
+python -m arcaeon_adapter --ledger seam.log.jsonl -- <your mcp server command...>
+```
+
+## What lands in the log
+
+Real rows, from wrapping `arcaeon-ledger`'s own MCP server (the ledger logging
+itself through the ledger), trimmed for width:
+
+```json
+{"evt":"session_begin","seam":"mcp-stdio","seam_impl":"arcaeon-adapter/0.1.0",
+ "session":"25eda195-70e8-45cb-9035-be9f61cfc759","seq":1,
+ "server":"arcaeon_ledger.mcp_server","ledger_backend":"arcaeon-ledger/0.5.7",
+ "command":["python","-m","arcaeon_ledger.mcp_server","--log","agent.log.jsonl"],
+ "command_digest":"sha256:json-c14n:v1:ec06bd01…","raw_payloads":false,
+ "ts":"2026-08-19T14:18:08Z","chain":"0081ec1fe5d98395192f595e553b4133"}
+
+{"evt":"tools_list","seq":3,"tools":["ledger_append","ledger_verify"],"tool_count":2,
+ "tools_digest":"sha256:json-c14n:v1:b85c9fce…","status":"ok", …}
+
+{"evt":"tool_call","seq":4,"tool":"ledger_append","rpc_id":"3",
+ "args_digest":"sha256:json-c14n:v1:cfb2bb50…",
+ "result_digest":"sha256:json-c14n:v1:ba037f70…",
+ "status":"ok","ms":144, …}
+
+{"evt":"session_end","seq":6,"reason":"child_exit","exit_code":0,
+ "rows_before_end":5,"calls":2, …}
+```
+
+In that same run, the wrapped server's *own* log — the diary it keeps when the
+agent remembers to call `ledger_append` — had **one** row. The seam log had six.
+That difference is the entire product.
+
+| field | why it's there |
+|---|---|
+| `evt` | `tool_call`, `session_begin`, `session_end`, `mcp_initialize`, `tools_list` |
+| `seam` | always `"mcp-stdio"` — the **provenance tier**. A separate process saw this at the protocol level. A downstream verifier reads this field to tell infrastructure-grade capture from a cooperative in-process callback the agent could simply not call. |
+| `session` / `seq` | one proxy process = one session; `seq` is a dense total order within it. `session_begin` + `session_end` bracket the run so a reviewer can pair a session's start and end. |
+| `args_digest` / `result_digest` | `sha256:json-c14n:v1:<hex>` — self-describing, so a stranger holding only the row can reproduce the computation. |
+| `status` / `ms` | `ok` / `error` / `unanswered`, and wall-clock duration. `error` covers **both** a JSON-RPC `error` and a `result` carrying `isError: true`. |
+
+**Digests, not payloads, by default.** The row proves *which* bytes crossed the
+seam without keeping them. An audit log that quietly becomes a copy of every
+prompt and every result is a liability, not an asset — and a person-free core is
+much easier to retain for years. `--raw` embeds the payloads for deployers who
+own that risk; the digests stay either way.
+
+**A call that never gets an answer still gets a row** (`status: "unanswered"`).
+Otherwise "kill the server mid-call" would be a way to make an action leave no
+trace at the seam, which is the exact hole this exists to close.
+
+## Verify it
+
+The seam log is an ordinary `arcaeon-ledger` file:
+
+```
+python -m arcaeon_ledger.cli verify seam.log.jsonl
+```
+
+Edit a row, delete one, reorder them — every later link breaks and `verify` names
+the exact line.
+
+## The honest limit
+
+> **An adapter on one seam logs that seam completely — and nothing else.** An
+> agent can still act around it: a direct HTTP call, an un-wrapped MCP server, a
+> shell command never crosses this proxy and never hits this ledger. The
+> second-set-of-books problem does not go away; no logging layer can force total
+> honesty. What the adapter guarantees is narrower and real: *everything that
+> crossed the instrumented seam is in the record, automatically, and the record
+> proves itself.* Honesty is forced at the seams, not everywhere — not a lock, a
+> neighborhood.
+
+Specifically **blind** to:
+
+- your harness's built-in tools (Bash, file edits, web fetch) — they never touch MCP
+- any MCP server you did not wrap
+- HTTP the agent makes natively
+- the model's reasoning, which is not an action and leaves no wire trace
+- frames larger than `--max-frame` (relayed fine; counted and reported in
+  `session_end` as `oversize_frames_unlogged`, never a silent gap)
+
+And on compliance, plainly: **this does not make anyone compliant with
+anything.** Regulations like the EU AI Act's Art. 12 place duties on a *provider*
+or *deployer*, and duties land on people, not libraries. What this is: a
+mechanism that makes recording at one seam automatic rather than voluntary,
+which is a thing you would otherwise have to build. Retention policy, log
+semantics, risk classification, and every other obligation remain yours. Anyone
+selling you a package that "makes you compliant" is selling you a story.
+
+Whoever controls the config can also remove the wrapper. That is the same class
+of limit every logging layer has, and it is stated here rather than in a footnote.
+
+## Fidelity is the P0 property
+
+A proxy that corrupts, reorders, or delays a customer's JSON-RPC is worse than no
+proxy at all. So the design puts fidelity ahead of observation, structurally:
+
+- **Bytes are forwarded first, observed second, from a copy.** A parsing defect
+  here cannot alter or withhold traffic; the worst it can do is produce a wrong
+  row.
+- **Raw binary end to end.** No text mode anywhere — on Windows that would rewrite
+  `\n` as `\r\n` and silently alter every frame.
+- **No reframing, ever.** We never parse a frame and re-emit it. The classic proxy
+  bug is `json.dumps(json.loads(frame))`: semantically identical, byte-different.
+- **One thread per direction**, so ordering within a direction is the OS's.
+- **The child's stderr is inherited, not piped.** Its diagnostics land exactly
+  where they did unwrapped, and the proxy itself prints nothing on an honest run.
+- **Malformed frames are relayed untouched and not logged.** A server that prints
+  a stray line to stdout keeps working; we don't guess, because a guess in an
+  audit record is fiction.
+- **The child's exit code is the proxy's exit code.**
+
+This is tested by running a scripted client against a synthetic MCP server
+directly, then through the proxy, and requiring the two stdout streams to be
+identical *bytes* — including a 4 MB frame spanning ~64 pipe reads, unicode,
+embedded CRLF, malformed lines, a notification with no id, and a final frame with
+no trailing newline.
+
+## Prove the checks can fail
+
+```
+python -m arcaeon_adapter.selftest
+```
+
+An instrument that has never failed proves nothing. Every case runs GREEN on a
+clean fixture, then **mutates** and requires the same check to go RED — with a
+no-op guard in between, because a mutation that changes nothing proves nothing
+either.
+
+```
+PASS passthrough_fidelity GREEN: 2001202 bytes identical byte-for-byte through the proxy
+PASS passthrough_fidelity RED on reserialize: corruption detected (length 2001202 vs 2001097)
+PASS passthrough_fidelity RED on drop_byte: corruption detected (length 2001202 vs 2001168)
+PASS one_row_per_call GREEN: 5 tools/call frames -> 5 tool_call rows, 9 rows total, seq 1..9
+PASS one_row_per_call RED on log_on_request: count check caught 10 rows for 5 calls
+PASS unanswered_call_logged GREEN: unanswered `quiet` call rowed with args_digest bound
+PASS unanswered_call_logged RED on no_flush: dropping the shutdown flush loses the row
+PASS tamper_detected GREEN: seam log verifies (ok=True, rows=9)
+PASS tamper_detected RED on edited args_digest: first_break='line 4: chain mismatch'
+PASS digest_recipe_frozen GREEN: 3 frozen json-c14n:v1 vectors reproduce exactly
+PASS digest_recipe_frozen RED on unsorted_keys: drifted canonicalizer produces a different digest
+
+ALL CHECKS PASSED — and every one was observed failing on its own defect.
+```
+
+The fidelity mutations are injected into the **real relay**, not a mock, so what's
+proven is that the comparison would catch a regression in the shipping code path.
+
+## Options
+
+```
+--ledger PATH      seam ledger (required). Keep it SEPARATE from any ledger the
+                   wrapped server writes: one file, one writer, clean provenance.
+--server NAME      label for the wrapped server in every row (default: derived
+                   from the command — `-m pkg.mod` reads as "pkg.mod", not "python")
+--session ID       session id (default: a fresh uuid4 per proxy process)
+--raw              embed raw argument and result payloads. Off by default.
+--max-frame BYTES  frames larger than this are relayed but not logged (default 64 MiB)
+```
+
+## Install and dependencies
+
+Stdlib only at runtime. `arcaeon-ledger` is the intended writer and is what makes
+a row provable — but it is **not** a hard dependency, on purpose: this gets
+wrapped around somebody else's working MCP server by editing one line of config,
+and a missing package must never be why their server fails to start. Without it,
+rows are written by a byte-compatible fallback and `session_begin` says so in
+`ledger_backend`, so a reviewer never has to guess which writer produced a chain.
+(That byte-compatibility is asserted in the test suite, not just claimed here.)
+
+**No network calls at runtime.** Ever.
+
+```
+pytest -q                            # 65 tests
+python -m arcaeon_adapter.selftest   # the mutation harness
+```
+
+## Status
+
+v0. Works, tested, dogfooded on our own MCP server. Deliberately not yet built:
+`--authority` stamping, `--bind-inputs` artefact binding, `--auto-pin` witness
+publication, and harness-hook / HTTP-gateway seams. See `CHANGELOG.md`.
+
+MIT.

arcaeon_adapter-0.1.0/arcaeon_adapter/__init__.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+"""arcaeon-adapter — infrastructure-grade action logging at the MCP stdio seam.
+
+`arcaeon-ledger` proves a record wasn't altered. It cannot prove the record is
+*complete*, because `append()` records whatever a caller chooses to pass: the
+agent holds the pen. This package moves the pen into the pipe the agent's actions
+flow through — a stdio proxy, in its own OS process, that sees every `tools/call`
+and every response at the protocol level and writes a hash-chained row per pair
+without the agent's cooperation, knowledge, or consent.
+
+    python -m arcaeon_adapter.proxy --ledger seam.log.jsonl -- <mcp server command...>
+    python -m arcaeon_adapter.selftest        # every claimed check, observed failing
+
+The honest limit travels with the claim, always: an adapter on one seam logs that
+seam completely and nothing else. A direct HTTP call, an un-wrapped server, or a
+shell command never crosses this proxy and never lands in this ledger. This is
+not a lock. It is a neighborhood.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ._version import IMPL, VERSION
+from .observer import SEAM, FrameSplitter, SeamObserver
+
+__version__ = VERSION
+__all__ = ["SEAM", "IMPL", "VERSION", "__version__",
+           "FrameSplitter", "SeamObserver", "main", "relay", "run"]
+
+# `proxy` is imported LAZILY, and that is load-bearing rather than tidy.
+# `python -m arcaeon_adapter.proxy` runs this package's __init__ first; if we
+# imported .proxy here, runpy would then find it already in sys.modules and print
+#     RuntimeWarning: 'arcaeon_adapter.proxy' found in sys.modules ...
+# to STDERR — on every single launch. The proxy inherits the wrapped server's
+# stderr, so that warning lands in the customer's server log, from a tool whose
+# entire pitch is that it changes nothing about how their server behaves. A
+# logging sidecar that dirties the logs is a bad joke. PEP 562 lazy attributes
+# keep `from arcaeon_adapter import run` working without the import at load time.
+_LAZY = {"main", "relay", "run"}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _LAZY:
+        from . import proxy
+        return getattr(proxy, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list:
+    return sorted(__all__)

arcaeon_adapter-0.1.0/arcaeon_adapter/__main__.py

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: MIT
+"""`python -m arcaeon_adapter` == `python -m arcaeon_adapter.proxy`.
+
+The shorter form is what goes in an MCP client config, where the line is already
+long enough. Both spellings are supported forever; config files outlive advice.
+"""
+import sys
+
+from .proxy import main
+
+if __name__ == "__main__":
+    sys.exit(main())