phb-agentledger 0.1.0__tar.gz

phb_agentledger-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+demo_audit.jsonl
+demo_audit.jsonl.tail
+*.egg-info/
+build/
+dist/

phb_agentledger-0.1.0/LICENSE

@@ -0,0 +1,40 @@
+AgentLedger — Licence
+Copyright (c) 2026 Przemyslaw H. Budrewicz trading as PHB Studio.
+All rights reserved.
+
+This software is source-available, not open source. Two licences are offered.
+
+1. NON-COMMERCIAL LICENCE (free)
+
+You may use, copy, modify, and run this software free of charge for personal
+use, education, academic research, and internal evaluation, including
+evaluation inside a company. You may not use it in or as part of a product,
+service, or internal system that supports a commercial activity beyond
+evaluation. You must keep this notice intact in any copy you distribute.
+
+2. COMMERCIAL LICENCE (paid)
+
+Any use beyond the above — including use in production, in a product or
+service offered to others, or in the internal operations of a business —
+requires a commercial licence. A commercial licence is purchased directly at:
+
+    https://budrewicz.gumroad.com/l/AgentLedger
+
+It is perpetual for the version purchased, covers unlimited developers within
+the purchasing organisation, and does not require a separate negotiated
+agreement.
+
+NO WARRANTY
+
+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
+COPYRIGHT HOLDER 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.
+
+COMPLIANCE NOTE
+
+This software helps you keep a tamper-evident record of what an AI system did.
+It is not legal advice and it does not by itself make any system compliant with
+any regulation.

phb_agentledger-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: phb-agentledger
+Version: 0.1.0
+Summary: A tamper-evident, hash-chained audit ledger for AI agent actions.
+Project-URL: Homepage, https://budrewicz.gumroad.com/l/AgentLedger
+Project-URL: Commercial licence, https://budrewicz.gumroad.com/l/AgentLedger
+Author: PHB Studio
+License-Expression: LicenseRef-PHB-Studio-Commercial
+License-File: LICENSE
+Keywords: ai-agents,audit,compliance,ledger,provenance,tamper-evident
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Requires-Dist: filelock>=3.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentledger
+
+A tamper-evident, hash-chained audit ledger for AI agent actions.
+
+When an AI system does something consequential — calls a tool, spends money,
+escalates to a person, refuses a request — you need a record that still means
+something six months later, when someone asks what happened and why. An
+application log does not survive that question: anyone with file access can
+edit it, and nothing in the file says whether they did.
+
+`agentledger` writes each action as a validated, content-addressed record in a
+SHA-256 hash chain. Editing any stored record, in any field, breaks the chain,
+and `verify_chain()` says so.
+
+## Install
+
+```bash
+pip install phb-agentledger
+```
+
+Installed as `phb-agentledger`, imported as `agentledger`. One runtime
+dependency (`filelock`). Python 3.10+.
+
+## Sixty seconds
+
+```python
+from agentledger import AuditLedger, make_event
+
+ledger = AuditLedger(path="audit.jsonl")
+
+ledger.append_event(make_event(
+    "TOOL_CALL", "ACME-AGENT-001",
+    summary="looked up order 1234",
+    subject_refs=["order:1234"],
+))
+ledger.append_event(make_event(
+    "POLICY_DECISION", "ACME-GATE-001",
+    summary="refund above the auto-approve limit: escalated to a human",
+    subject_refs=["order:1234"],
+))
+
+ledger.verify_chain()                        # True
+ledger.query(subject_refs=["order:1234"])    # an AuditTrace of both events
+```
+
+Run `python demo.py` to see the same thing end to end, including a hand-edit of
+the stored file and the chain check catching it.
+
+## What it guarantees
+
+- **Order is assigned by the ledger, never by the caller.** Sequence numbers
+  and chain hashes are computed on append. A producer cannot claim a position
+  in history.
+- **Every record carries its own digest**, SHA-256 over JCS-1 canonical JSON
+  with the digest field omitted. A record that does not match its own content
+  is rejected before it is stored.
+- **Appends are idempotent** on `(record_id, event_id)`. Resubmitting the same
+  record is a no-op; resubmitting different content under the same key is a
+  rejected conflict, not a silent overwrite.
+- **Queries never overclaim.** A result is explicitly scoped to a ledger cut,
+  so "no matches in this view" is never returned as "this never happened".
+- **Concurrent writers are safe.** The load → mint → append critical section
+  is held under a cross-process file lock, and a torn tail from a killed
+  process is quarantined rather than silently truncating history.
+- **Two refusals are enforced in code, not documentation.** The ledger will
+  not store records classified as raw internal model reasoning, and it rejects
+  any event that asserts externally-verified truth without evidence lineage.
+
+## What it deliberately does not do
+
+- **It does not verify payloads it never saw.** `payload_digest` is your
+  assertion about content held elsewhere; the ledger stores and chains it, but
+  cannot confirm it.
+- **It is not a signing system.** Records are tamper-*evident* against edits to
+  the stored file. They are not signed, so a party who can rewrite the whole
+  file, including recomputing the chain, is out of scope. Signing is the next
+  layer, not this one.
+- **It does not make you compliant with anything.** It gives you a defensible
+  record. Whether that record satisfies a given regulation is a question for
+  your counsel.
+- **`SCHEMA_HASH_CATALOG` ships with a placeholder hash** for AuditEvent 1.0.0
+  rather than the digest of the shipped schema file. Set it from your deployed
+  schemas at boot if you want that check to be meaningful.
+
+## Event shape
+
+`make_event()` fills the 22-field envelope for you and computes both digests.
+The fields you supply are the ones that carry meaning:
+
+| Argument | Meaning |
+|---|---|
+| `event_type` | What happened, as a `SCREAMING_SNAKE` label you choose |
+| `actor` | Who did it, as `VENDOR-COMPONENT-NNN` (e.g. `ACME-AGENT-001`) |
+| `summary` *or* `payload_ref` | A short line, or a pointer to the payload held elsewhere |
+| `subject_refs` | What it was about (`order:1234`, `user:42`) |
+| `data_classification` | Sensitivity label; drives the refusals above |
+| `truth_refs` | Evidence lineage, required for external-truth claims |
+
+Hand-built dicts are still accepted — `make_event` is a convenience, not a
+bypass. `validate_audit_event()` judges both the same way.
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+python -m pytest tests -q
+```
+
+43 tests, no network, under a second.
+
+## Licence
+
+Source-available. Free for personal, educational, and evaluation use;
+commercial use requires a paid licence. See [LICENSE](LICENSE).

phb_agentledger-0.1.0/README.md

@@ -0,0 +1,114 @@
+# agentledger
+
+A tamper-evident, hash-chained audit ledger for AI agent actions.
+
+When an AI system does something consequential — calls a tool, spends money,
+escalates to a person, refuses a request — you need a record that still means
+something six months later, when someone asks what happened and why. An
+application log does not survive that question: anyone with file access can
+edit it, and nothing in the file says whether they did.
+
+`agentledger` writes each action as a validated, content-addressed record in a
+SHA-256 hash chain. Editing any stored record, in any field, breaks the chain,
+and `verify_chain()` says so.
+
+## Install
+
+```bash
+pip install phb-agentledger
+```
+
+Installed as `phb-agentledger`, imported as `agentledger`. One runtime
+dependency (`filelock`). Python 3.10+.
+
+## Sixty seconds
+
+```python
+from agentledger import AuditLedger, make_event
+
+ledger = AuditLedger(path="audit.jsonl")
+
+ledger.append_event(make_event(
+    "TOOL_CALL", "ACME-AGENT-001",
+    summary="looked up order 1234",
+    subject_refs=["order:1234"],
+))
+ledger.append_event(make_event(
+    "POLICY_DECISION", "ACME-GATE-001",
+    summary="refund above the auto-approve limit: escalated to a human",
+    subject_refs=["order:1234"],
+))
+
+ledger.verify_chain()                        # True
+ledger.query(subject_refs=["order:1234"])    # an AuditTrace of both events
+```
+
+Run `python demo.py` to see the same thing end to end, including a hand-edit of
+the stored file and the chain check catching it.
+
+## What it guarantees
+
+- **Order is assigned by the ledger, never by the caller.** Sequence numbers
+  and chain hashes are computed on append. A producer cannot claim a position
+  in history.
+- **Every record carries its own digest**, SHA-256 over JCS-1 canonical JSON
+  with the digest field omitted. A record that does not match its own content
+  is rejected before it is stored.
+- **Appends are idempotent** on `(record_id, event_id)`. Resubmitting the same
+  record is a no-op; resubmitting different content under the same key is a
+  rejected conflict, not a silent overwrite.
+- **Queries never overclaim.** A result is explicitly scoped to a ledger cut,
+  so "no matches in this view" is never returned as "this never happened".
+- **Concurrent writers are safe.** The load → mint → append critical section
+  is held under a cross-process file lock, and a torn tail from a killed
+  process is quarantined rather than silently truncating history.
+- **Two refusals are enforced in code, not documentation.** The ledger will
+  not store records classified as raw internal model reasoning, and it rejects
+  any event that asserts externally-verified truth without evidence lineage.
+
+## What it deliberately does not do
+
+- **It does not verify payloads it never saw.** `payload_digest` is your
+  assertion about content held elsewhere; the ledger stores and chains it, but
+  cannot confirm it.
+- **It is not a signing system.** Records are tamper-*evident* against edits to
+  the stored file. They are not signed, so a party who can rewrite the whole
+  file, including recomputing the chain, is out of scope. Signing is the next
+  layer, not this one.
+- **It does not make you compliant with anything.** It gives you a defensible
+  record. Whether that record satisfies a given regulation is a question for
+  your counsel.
+- **`SCHEMA_HASH_CATALOG` ships with a placeholder hash** for AuditEvent 1.0.0
+  rather than the digest of the shipped schema file. Set it from your deployed
+  schemas at boot if you want that check to be meaningful.
+
+## Event shape
+
+`make_event()` fills the 22-field envelope for you and computes both digests.
+The fields you supply are the ones that carry meaning:
+
+| Argument | Meaning |
+|---|---|
+| `event_type` | What happened, as a `SCREAMING_SNAKE` label you choose |
+| `actor` | Who did it, as `VENDOR-COMPONENT-NNN` (e.g. `ACME-AGENT-001`) |
+| `summary` *or* `payload_ref` | A short line, or a pointer to the payload held elsewhere |
+| `subject_refs` | What it was about (`order:1234`, `user:42`) |
+| `data_classification` | Sensitivity label; drives the refusals above |
+| `truth_refs` | Evidence lineage, required for external-truth claims |
+
+Hand-built dicts are still accepted — `make_event` is a convenience, not a
+bypass. `validate_audit_event()` judges both the same way.
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+python -m pytest tests -q
+```
+
+43 tests, no network, under a second.
+
+## Licence
+
+Source-available. Free for personal, educational, and evaluation use;
+commercial use requires a paid licence. See [LICENSE](LICENSE).

phb_agentledger-0.1.0/agentledger/__init__.py

@@ -0,0 +1,15 @@
+from .canonical import compute_record_digest, verify_record_digest
+from .events import make_event
+from .ledger import AuditLedger, AuditEventRejected, LedgerEntry
+from .validation import validate_audit_event, ValidationResult
+
+__all__ = [
+    "AuditLedger",
+    "make_event",
+    "AuditEventRejected",
+    "LedgerEntry",
+    "validate_audit_event",
+    "ValidationResult",
+    "compute_record_digest",
+    "verify_record_digest",
+]

phb_agentledger-0.1.0/agentledger/canonical.py

@@ -0,0 +1,43 @@
+"""
+Canonical JSON serialization and digest helpers.
+
+The RecordEnvelope contract (urn:neo:contract:RecordEnvelope:1.0.0) requires every
+record to be content-addressable: ``record_digest`` must equal SHA-256 over the
+record's JCS-1 canonical JSON with ``record_digest`` itself omitted.
+
+This module implements a canonicalization profile sufficient for records that
+never contain floats (Neo's schemas only use strings, ints, bools, null, arrays
+and objects), which covers every contract in this pack. It intentionally does
+NOT depend on any third-party library.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Mapping
+
+
+def canonicalize(value: Any) -> str:
+    """Serialize ``value`` to canonical JSON text (sorted keys, no insignificant
+    whitespace, UTF-8 safe)."""
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def sha256_hex(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def compute_record_digest(record: Mapping[str, Any]) -> str:
+    """Compute the record_digest a well-formed record MUST carry: SHA-256 of the
+    canonical JSON of the record with ``record_digest`` omitted."""
+    stripped = {k: v for k, v in record.items() if k != "record_digest"}
+    return sha256_hex(canonicalize(stripped))
+
+
+def verify_record_digest(record: Mapping[str, Any]) -> bool:
+    """True iff record['record_digest'] matches the value computed from the rest
+    of the record."""
+    claimed = record.get("record_digest")
+    if not isinstance(claimed, str):
+        return False
+    return claimed == compute_record_digest(record)

phb_agentledger-0.1.0/agentledger/events.py

@@ -0,0 +1,113 @@
+"""
+Build a valid AuditEvent without hand-assembling the envelope.
+
+The `AuditEvent` contract this ledger enforces is deliberately strict: 22
+required fields, a closed shape, two content digests and a canonicalisation
+profile. That strictness is the point — it is what makes a stored record
+independently checkable months later — but it makes the first five minutes
+with the library harder than they need to be.
+
+`make_event()` fills in everything that can be derived (the contract
+constants, the timestamps, the identifiers, the schema hash, and both
+digests) and leaves the caller with the handful of fields that actually carry
+meaning: what happened, who did it, what it was about. The result is a plain
+dict that `AuditLedger.append_event()` accepts, and that `validate_audit_event`
+independently agrees is well-formed — this helper is a convenience, never a
+bypass.
+"""
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Iterable, Mapping, Optional, Sequence
+
+from .canonical import compute_record_digest, sha256_hex
+
+# Imported lazily-by-name to keep the module graph one-directional
+# (events -> ledger is fine; ledger never imports events).
+from .ledger import SCHEMA_HASH_CATALOG
+
+__all__ = ["make_event"]
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _new_id(prefix: str) -> str:
+    # record_id / event_id must be 8..128 chars; a prefixed uuid4 hex is 37.
+    return f"{prefix}_{uuid.uuid4().hex}"
+
+
+def make_event(
+    event_type: str,
+    actor: str,
+    *,
+    summary: Optional[str] = None,
+    payload_ref: Optional[str] = None,
+    subject_refs: Sequence[str] = (),
+    truth_refs: Sequence[str] = (),
+    authority_refs: Sequence[str] = (),
+    data_classification: str = "OWNER_PRIVATE",
+    producer: Optional[str] = None,
+    correlation_ids: Iterable[Mapping[str, str]] = (),
+    provenance: Iterable[Mapping[str, str]] = (),
+    payload_digest: Optional[str] = None,
+    occurred_at: Optional[str] = None,
+    clock_quality: str = "SYNCHRONIZED",
+    record_id: Optional[str] = None,
+    event_id: Optional[str] = None,
+    created_at: Optional[str] = None,
+) -> dict[str, Any]:
+    """Return a complete, digest-correct AuditEvent dict.
+
+    `event_type` and `data_classification` are SCREAMING_SNAKE labels you
+    choose (e.g. `TOOL_CALL`, `POLICY_DECISION`). `actor` is the component
+    that did the thing, as `VENDOR-COMPONENT-NNN` (e.g. `ACME-AGENT-001`);
+    `producer` is the component writing the record, and defaults to `actor`.
+
+    Exactly one of `summary` or `payload_ref` must be given: a short
+    human-readable line, or a pointer to the payload held elsewhere. The
+    ledger stores the pointer or the summary — never a payload it was not
+    given ownership of.
+
+    `payload_digest` should be the SHA-256 of the real payload when you have
+    it. When omitted it is derived from the summary or ref, which keeps the
+    record structurally valid and self-consistent but says nothing about a
+    payload the ledger never saw.
+    """
+    if (summary is None) == (payload_ref is None):
+        raise ValueError("make_event: pass exactly one of summary= or payload_ref=")
+
+    payload = {"summary": summary} if summary is not None else {"payload_ref": payload_ref}
+    now = created_at or _now_iso()
+
+    record: dict[str, Any] = {
+        "contract_name": "AuditEvent",
+        "contract_version": "1.0.0",
+        "record_id": record_id or _new_id("record"),
+        "created_at": now,
+        "producer_module_id": producer or actor,
+        "correlation_ids": [dict(c) for c in correlation_ids],
+        "provenance": [dict(p) for p in provenance],
+        "schema_hash": SCHEMA_HASH_CATALOG[("AuditEvent", "1.0.0")],
+        "digest_algorithm": "SHA-256",
+        "canonicalization_profile": "JCS-1",
+        "event_id": event_id or _new_id("event"),
+        "event_schema_version": "1.0.0",
+        "event_type": event_type,
+        "actor_module": actor,
+        "subject_refs": list(subject_refs),
+        "authority_refs_if_relevant": list(authority_refs),
+        "truth_refs_if_relevant": list(truth_refs),
+        "payload_ref_or_summary": payload,
+        "payload_digest": payload_digest or sha256_hex(summary if summary is not None else payload_ref),
+        "data_classification": data_classification,
+        "producer_emitted_at": now,
+        "producer_clock_quality": clock_quality,
+    }
+    if occurred_at is not None:
+        record["producer_occurred_at_if_known"] = occurred_at
+
+    record["record_digest"] = compute_record_digest(record)
+    return record