themis-policy 0.1.0__tar.gz

themis_policy-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: themis-policy
+Version: 0.1.0
+Summary: Themis policy kernel for bounded-autonomy LLM agents — locks, drafts, scopes, audit. Python reference implementation of Themis RFC v0.
+Author: Adam Campbell
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Adam-Camp-King/Themis
+Project-URL: Specification, https://github.com/Adam-Camp-King/Themis/tree/main/spec
+Keywords: llm,agents,policy,safety,bounded-autonomy,multi-tenant,audit
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# themis-policy
+
+Python reference implementation of **Themis RFC v0** — a policy kernel for
+LLM agents that act on production systems. Four primitives — **locks**,
+**drafts**, **scopes**, **audit** — composed by one engine into a single
+decision per attempted action: `allow`, `deny`, `redirect`, or
+`require_approval`.
+
+Byte-compatible with [`themis-policy`](https://github.com/Adam-Camp-King/Themis)
+(TypeScript): both pass the same [conformance vectors](../spec/conformance).
+
+```python
+from themis import (
+    PolicyEngine, DefaultLockPolicy, DefaultScopePolicy, DefaultDraftPolicy,
+    Requestor, Action, PolicyContext, ConsoleSink, is_deny,
+)
+
+engine = PolicyEngine(audit_sink=ConsoleSink())
+engine.add_policy(DefaultLockPolicy())
+engine.add_policy(DefaultScopePolicy())
+engine.add_policy(DefaultDraftPolicy())
+
+decision = engine.evaluate(PolicyContext(
+    requestor=Requestor(id="key_1", kind="api_key", tenant_id=7, scopes=("pages:read",)),
+    action=Action(verb="pages.update", resource_type="page", tenant_id=7, resource_id=42,
+                  required_scope="pages:write"),
+    now=0, correlation_id="req-123",
+))
+if is_deny(decision):
+    print(decision.reason)          # missing_scope
+```
+
+The engine is synchronous (every core policy is pure CPU); `evaluate_async`
+exists for callers already inside an event loop. Stores (`LockStore`,
+`DraftStore`) are ports you implement against your persistence; audit sinks
+receive one event per evaluation and may never fail an evaluation.
+
+Install: `pip install themis-policy` (Python 3.11+, no dependencies).
+Tests: `pip install -e '.[test]' && pytest`.
+
+Apache-2.0 — see the repository LICENSE.

themis_policy-0.1.0/README.md

@@ -0,0 +1,41 @@
+# themis-policy
+
+Python reference implementation of **Themis RFC v0** — a policy kernel for
+LLM agents that act on production systems. Four primitives — **locks**,
+**drafts**, **scopes**, **audit** — composed by one engine into a single
+decision per attempted action: `allow`, `deny`, `redirect`, or
+`require_approval`.
+
+Byte-compatible with [`themis-policy`](https://github.com/Adam-Camp-King/Themis)
+(TypeScript): both pass the same [conformance vectors](../spec/conformance).
+
+```python
+from themis import (
+    PolicyEngine, DefaultLockPolicy, DefaultScopePolicy, DefaultDraftPolicy,
+    Requestor, Action, PolicyContext, ConsoleSink, is_deny,
+)
+
+engine = PolicyEngine(audit_sink=ConsoleSink())
+engine.add_policy(DefaultLockPolicy())
+engine.add_policy(DefaultScopePolicy())
+engine.add_policy(DefaultDraftPolicy())
+
+decision = engine.evaluate(PolicyContext(
+    requestor=Requestor(id="key_1", kind="api_key", tenant_id=7, scopes=("pages:read",)),
+    action=Action(verb="pages.update", resource_type="page", tenant_id=7, resource_id=42,
+                  required_scope="pages:write"),
+    now=0, correlation_id="req-123",
+))
+if is_deny(decision):
+    print(decision.reason)          # missing_scope
+```
+
+The engine is synchronous (every core policy is pure CPU); `evaluate_async`
+exists for callers already inside an event loop. Stores (`LockStore`,
+`DraftStore`) are ports you implement against your persistence; audit sinks
+receive one event per evaluation and may never fail an evaluation.
+
+Install: `pip install themis-policy` (Python 3.11+, no dependencies).
+Tests: `pip install -e '.[test]' && pytest`.
+
+Apache-2.0 — see the repository LICENSE.

themis_policy-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "themis-policy"
+version = "0.1.0"
+description = "Themis policy kernel for bounded-autonomy LLM agents — locks, drafts, scopes, audit. Python reference implementation of Themis RFC v0."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Adam Campbell" }]
+requires-python = ">=3.11"
+dependencies = []
+keywords = ["llm", "agents", "policy", "safety", "bounded-autonomy", "multi-tenant", "audit"]
+classifiers = [
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/Adam-Camp-King/Themis"
+Specification = "https://github.com/Adam-Camp-King/Themis/tree/main/spec"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+themis = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

themis_policy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

themis_policy-0.1.0/src/themis/__init__.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Adam Campbell
+"""Themis — a policy kernel for bounded-autonomy LLM agents.
+
+Python reference implementation of Themis RFC v0. Four primitives — locks,
+drafts, scopes, audit — composed by one engine into a single decision per
+attempted action: allow, deny, redirect, or require_approval.
+
+Conformance: ``spec/conformance/v0`` in the Themis repository holds the
+cross-language vectors; this package and ``themis-policy`` pass the same set.
+"""
+from .types import (
+    Action, Allow, AuditEvent, AuditSink, Decision, Deny, DraftableEntity, DraftStore, Entity, Id,
+    LockableEntity, LockStore, Policy, PolicyContext, Redirect, RequireApproval, Requestor, RequestorKind,
+    decision_from_dict,
+)
+from .engine import PolicyEngine, EmitPolicy, build_audit_event
+from .guards import is_allow, is_deny, is_redirect, is_require_approval
+from .sinks import ConsoleSink, MemorySink, MultiSink, NoOpSink
+from .policies import DefaultDraftPolicy, DefaultLockPolicy, DefaultScopePolicy
+
+__version__ = "0.1.0"
+__all__ = [
+    "Action", "Allow", "AuditEvent", "AuditSink", "Decision", "Deny", "DraftableEntity", "DraftStore", "Entity",
+    "Id", "LockableEntity", "LockStore", "Policy", "PolicyContext", "Redirect", "RequireApproval", "Requestor",
+    "RequestorKind", "decision_from_dict", "PolicyEngine", "EmitPolicy", "build_audit_event",
+    "is_allow", "is_deny", "is_redirect", "is_require_approval",
+    "ConsoleSink", "MemorySink", "MultiSink", "NoOpSink",
+    "DefaultDraftPolicy", "DefaultLockPolicy", "DefaultScopePolicy", "__version__",
+]

themis_policy-0.1.0/src/themis/engine.py

@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Adam Campbell
+"""themis.engine — the Themis kernel (RFC v0 § 6).
+
+Evaluation rules (normative, identical to ``themis-policy``):
+
+  0. Tenancy gate — requestor.tenant_id != action.tenant_id → deny
+     {policy: 'engine', reason: 'tenancy_mismatch'} before any policy runs.
+  1. Iterate policies in registration order.
+  2. ``deny`` short-circuits.
+  3. ``require_approval`` short-circuits.
+  4. ``redirect`` does NOT short-circuit; a later deny wins; otherwise the LAST
+     redirect wins, with the full policy chain recorded.
+  5. All ``allow`` → allow.
+  6. Exactly one audit event per evaluation (when emit_policy != 'off').
+     Sink failures never fail the evaluation (§ 9.4).
+
+The engine is synchronous: every policy here is pure CPU. ``evaluate_async``
+is provided for callers already inside an event loop.
+"""
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, Literal, Mapping, Optional, Sequence
+
+from .types import (
+    Allow, AuditEvent, AuditSink, Decision, Deny, Policy, PolicyContext, Redirect, RequireApproval,
+)
+
+EmitPolicy = Literal["all", "denials_only", "off"]
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def build_audit_event(
+    ctx: PolicyContext, decision: Decision, policy_chain: Sequence[str], latency_ms: float,
+) -> AuditEvent:
+    """Denormalize requestor/action — an audit event must not carry live references."""
+    requestor: dict[str, Any] = {
+        "id": ctx.requestor.id,
+        "kind": ctx.requestor.kind,
+        "scopes": list(ctx.requestor.scopes) if ctx.requestor.scopes else None,
+        "role": ctx.requestor.role,
+    }
+    action: dict[str, Any] = {
+        "verb": ctx.action.verb,
+        "resource_type": ctx.action.resource_type,
+        "resource_id": ctx.action.resource_id,
+        "area": ctx.action.area,
+        "required_scope": ctx.action.required_scope,
+    }
+    return AuditEvent(
+        id=str(uuid.uuid4()),
+        timestamp=ctx.now or _now_ms(),
+        correlation_id=ctx.correlation_id,
+        tenant_id=ctx.action.tenant_id,
+        requestor=requestor,
+        action=action,
+        decision=decision,
+        policy_chain=tuple(policy_chain),
+        latency_ms=latency_ms,
+        metadata=ctx.action.metadata,
+    )
+
+
+class PolicyEngine:
+    def __init__(self, audit_sink: Optional[AuditSink] = None, emit_policy: EmitPolicy = "all") -> None:
+        self.audit_sink = audit_sink
+        self._emit_policy: EmitPolicy = emit_policy
+        self._registrations: list[tuple[Policy, Mapping[str, Any]]] = []
+
+    def add_policy(self, policy: Policy, config: Optional[Mapping[str, Any]] = None) -> None:
+        self._registrations.append((policy, dict(config or {})))
+
+    @property
+    def policies(self) -> tuple[Policy, ...]:
+        return tuple(p for p, _ in self._registrations)
+
+    def evaluate(self, ctx: PolicyContext) -> Decision:
+        start = time.perf_counter()
+        chain: list[str] = []
+
+        # Rule 0 — tenancy gate
+        if ctx.requestor.tenant_id != ctx.action.tenant_id:
+            decision: Decision = Deny(
+                policy="engine",
+                reason="tenancy_mismatch",
+                message="requestor and action belong to different tenants",
+                detail={"requestor_tenant": ctx.requestor.tenant_id, "action_tenant": ctx.action.tenant_id},
+            )
+            self._emit_if_permitted(ctx, decision, chain, start)
+            return decision
+
+        current_redirect: Optional[Redirect] = None
+        for policy, _config in self._registrations:
+            d = policy.evaluate(ctx)
+            chain.append(policy.name)
+            if isinstance(d, (Deny, RequireApproval)):
+                self._emit_if_permitted(ctx, d, chain, start)
+                return d
+            if isinstance(d, Redirect):
+                current_redirect = d  # does not short-circuit
+            # Allow → continue
+
+        final: Decision = current_redirect if current_redirect is not None else Allow()
+        self._emit_if_permitted(ctx, final, chain, start)
+        return final
+
+    async def evaluate_async(self, ctx: PolicyContext) -> Decision:
+        return self.evaluate(ctx)
+
+    def _emit_if_permitted(self, ctx: PolicyContext, decision: Decision, chain: list[str], start: float) -> None:
+        if self.audit_sink is None or self._emit_policy == "off":
+            return
+        if self._emit_policy == "denials_only" and isinstance(decision, Allow):
+            return
+        latency_ms = (time.perf_counter() - start) * 1000.0
+        event = build_audit_event(ctx, decision, chain, latency_ms)
+        try:
+            self.audit_sink.emit(event)
+        except Exception:  # noqa: BLE001 — RFC § 9.4: audit failure never fails evaluation
+            pass
+
+
+__all__ = ["PolicyEngine", "EmitPolicy", "build_audit_event"]

themis_policy-0.1.0/src/themis/guards.py

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Adam Campbell
+"""Decision narrowing helpers — the Python twins of ``themis-policy`` guards."""
+from __future__ import annotations
+
+from typing import TypeGuard
+
+from .types import Allow, Decision, Deny, Redirect, RequireApproval
+
+
+def is_allow(d: Decision) -> TypeGuard[Allow]:
+    return isinstance(d, Allow)
+
+
+def is_deny(d: Decision) -> TypeGuard[Deny]:
+    return isinstance(d, Deny)
+
+
+def is_redirect(d: Decision) -> TypeGuard[Redirect]:
+    return isinstance(d, Redirect)
+
+
+def is_require_approval(d: Decision) -> TypeGuard[RequireApproval]:
+    return isinstance(d, RequireApproval)
+
+
+__all__ = ["is_allow", "is_deny", "is_redirect", "is_require_approval"]

themis_policy-0.1.0/src/themis/policies/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+from .lock import DefaultLockPolicy
+from .scope import DefaultScopePolicy
+from .draft import DefaultDraftPolicy
+
+__all__ = ["DefaultLockPolicy", "DefaultScopePolicy", "DefaultDraftPolicy"]

themis_policy-0.1.0/src/themis/policies/draft.py

@@ -0,0 +1,122 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Adam Campbell
+"""DefaultDraftPolicy — the T12 primitive (RFC v0 § 5.2, § 9.3).
+
+Decision rule:
+  1. entity is None (create)                → allow
+  2. entity is not draftable                → allow  (inert)
+  3. entity.is_published is not True        → allow
+  4. action.payload['publish'] is True      → allow  (explicit live write)
+  5. otherwise                              → redirect {target: 'draft', payload}
+
+Preview token — byte-identical to ``themis-policy``:
+  base64url( "v1.<entity_id>.<tenant_id>.<exp_ms>" + "." + hmac_sha256_hex )
+Verify uses constant-time comparison, rejects expired/tampered/wrong-secret/
+wrong-version tokens, and clamps TTL to 168 hours.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import math
+import re
+import time
+from typing import Any, Mapping, Optional, Union
+
+from ..types import Allow, Decision, DraftableEntity, Id, PolicyContext, Redirect
+
+TOKEN_VERSION = "v1"
+MAX_TTL_HOURS = 168
+DEFAULT_TTL_HOURS = 24
+_INT = re.compile(r"^-?\d+$")
+
+
+def _b64url(s: str) -> str:
+    return base64.urlsafe_b64encode(s.encode("utf-8")).decode("ascii").rstrip("=")
+
+
+def _from_b64url(s: str) -> str:
+    pad = (4 - len(s) % 4) % 4
+    return base64.urlsafe_b64decode((s + "=" * pad).encode("ascii")).decode("utf-8")
+
+
+def _hmac(secret: str, payload: str) -> str:
+    return hmac.new(secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+def _clamp_ttl(hours: float) -> int:
+    if not isinstance(hours, (int, float)) or math.isnan(hours) or math.isinf(hours) or hours <= 0:
+        return DEFAULT_TTL_HOURS
+    if hours > MAX_TTL_HOURS:
+        return MAX_TTL_HOURS
+    return int(hours)
+
+
+def _id_maybe_numeric(s: str) -> Id:
+    if _INT.match(s):
+        n = int(s)
+        if -(2**53 - 1) <= n <= 2**53 - 1:
+            return n
+    return s
+
+
+class DefaultDraftPolicy:
+    name = "draft"
+
+    def evaluate(self, ctx: PolicyContext) -> Decision:
+        entity = ctx.entity
+        if entity is None or not isinstance(entity, DraftableEntity):
+            return Allow(policy=self.name)
+        if entity.is_published is not True:
+            return Allow(policy=self.name)
+        payload = ctx.action.payload
+        if isinstance(payload, Mapping) and payload.get("publish") is True:
+            return Allow(policy=self.name)
+        return Redirect(policy=self.name, target="draft", payload=payload if payload is not None else None)
+
+    def merge(self, entity: DraftableEntity, draft_payload: Any) -> DraftableEntity:
+        return DraftableEntity(
+            id=entity.id, tenant_id=entity.tenant_id, is_published=True,
+            has_pending_draft=False, draft_updated_at=None, draft_updated_by=None,
+        )
+
+    def clear(self, entity: DraftableEntity) -> DraftableEntity:
+        return DraftableEntity(
+            id=entity.id, tenant_id=entity.tenant_id, is_published=entity.is_published,
+            has_pending_draft=False, draft_updated_at=None, draft_updated_by=None,
+        )
+
+    def sign_preview_token(self, entity_id: Id, tenant_id: Id, ttl_hours: float, secret: str) -> str:
+        if not secret:
+            raise ValueError("sign_preview_token: secret must be non-empty")
+        exp_ms = int(time.time() * 1000) + _clamp_ttl(ttl_hours) * 3_600_000
+        payload = f"{TOKEN_VERSION}.{entity_id}.{tenant_id}.{exp_ms}"
+        return _b64url(f"{payload}.{_hmac(secret, payload)}")
+
+    def verify_preview_token(self, token: str, secret: str) -> Optional[dict[str, Id]]:
+        if not token or not secret:
+            return None
+        try:
+            decoded = _from_b64url(token)
+        except Exception:  # noqa: BLE001 — malformed token is a None, never a raise
+            return None
+        parts = decoded.split(".")
+        if len(parts) != 5:
+            return None
+        version, entity_s, tenant_s, exp_s, mac = parts
+        if version != TOKEN_VERSION:
+            return None
+        expected = _hmac(secret, f"{version}.{entity_s}.{tenant_s}.{exp_s}")
+        if len(mac) != len(expected) or not hmac.compare_digest(mac, expected):
+            return None
+        try:
+            exp_ms = int(exp_s)
+        except ValueError:
+            return None
+        if exp_ms <= int(time.time() * 1000):
+            return None
+        return {"entity_id": _id_maybe_numeric(entity_s), "tenant_id": _id_maybe_numeric(tenant_s)}
+
+
+__all__ = ["DefaultDraftPolicy"]

themis_policy-0.1.0/src/themis/policies/lock.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Adam Campbell
+"""DefaultLockPolicy — the T10 primitive (RFC v0 § 5.1).
+
+Decision rule, first match wins:
+  1. entity is None (create)                         → allow
+  2. entity.agency_owner_id is None (self-serve)     → allow
+  3. requestor.is_super_admin                        → allow
+  4. requestor.role == 'agency'                      → allow
+  5. requestor.id == entity.agency_owner_id          → allow
+  6. action.area not set                             → allow
+  7. entity.locks[area] is not True                  → allow
+  8. otherwise                                       → deny
+Bypass rules 3–5 MUST NOT be removed by implementations.
+"""
+from __future__ import annotations
+
+from typing import Mapping, Sequence
+
+from ..types import Allow, Decision, Deny, LockableEntity, PolicyContext
+
+
+class DefaultLockPolicy:
+    name = "lock"
+
+    def evaluate(self, ctx: PolicyContext) -> Decision:
+        entity = ctx.entity
+        if entity is None or not isinstance(entity, LockableEntity):
+            return Allow(policy=self.name)
+        if entity.agency_owner_id is None:
+            return Allow(policy=self.name)
+        if ctx.requestor.is_super_admin is True:
+            return Allow(policy=self.name)
+        if ctx.requestor.role == "agency":
+            return Allow(policy=self.name)
+        if ctx.requestor.id == entity.agency_owner_id:
+            return Allow(policy=self.name)
+        area = ctx.action.area
+        if not area:
+            return Allow(policy=self.name)
+        if entity.locks.get(area) is not True:
+            return Allow(policy=self.name)
+        return Deny(
+            policy=self.name,
+            reason="agency_lock",
+            message=f"Area '{area}' is locked by the agency for this resource.",
+            detail={"area": area, "entity_id": entity.id, "agency_owner_id": entity.agency_owner_id},
+        )
+
+    def describe(self, entity: LockableEntity, areas: Sequence[str]) -> dict[str, bool]:
+        return {a: entity.locks.get(a) is True for a in areas}
+
+    def apply(self, entity: LockableEntity, areas: Sequence[str], locked: bool) -> LockableEntity:
+        nxt: dict[str, bool] = dict(entity.locks)
+        for a in areas:
+            nxt[a] = locked
+        return LockableEntity(id=entity.id, tenant_id=entity.tenant_id, agency_owner_id=entity.agency_owner_id, locks=nxt)
+
+
+__all__ = ["DefaultLockPolicy"]

themis_policy-0.1.0/src/themis/policies/scope.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Adam Campbell
+"""DefaultScopePolicy — flat-membership scope authorization (RFC v0 § 5.3).
+
+Decision rule, first match wins:
+  1. requestor.is_super_admin                    → allow
+  2. '*' in requestor.scopes                     → allow
+  3. requestor.kind == 'user' and no scopes      → allow  (session user)
+  4. required scope resolves to None             → allow
+  5. required scope in requestor.scopes          → allow
+  6. otherwise                                   → deny
+``required_scope`` comes from the action first, else from the registered rule
+table (method + path string/regex, or a predicate). Flat membership: no
+implied hierarchy; wildcards beyond '*' are extensions, not core.
+"""
+from __future__ import annotations
+
+import re
+from typing import Callable, Optional, Pattern, Union
+
+from ..types import Allow, Decision, Deny, PolicyContext
+
+Matcher = Union[tuple[str, Union[str, Pattern[str]]], Callable[[PolicyContext], bool]]
+
+
+class DefaultScopePolicy:
+    name = "scope"
+
+    def __init__(self) -> None:
+        self._rules: list[tuple[Matcher, str]] = []
+
+    def evaluate(self, ctx: PolicyContext) -> Decision:
+        r = ctx.requestor
+        if r.is_super_admin is True:
+            return Allow(policy=self.name)
+        if "*" in r.scopes:
+            return Allow(policy=self.name)
+        if r.kind == "user" and len(r.scopes) == 0:
+            return Allow(policy=self.name)
+        required = ctx.action.required_scope or self._resolve_required(ctx)
+        if not required:
+            return Allow(policy=self.name)
+        if required in r.scopes:
+            return Allow(policy=self.name)
+        return Deny(
+            policy=self.name,
+            reason="missing_scope",
+            message=f"Missing required scope '{required}'.",
+            detail={"required": required, "held": list(r.scopes)},
+        )
+
+    def add_rule(self, matcher: Matcher, required_scope: str) -> None:
+        self._rules.append((matcher, required_scope))
+
+    def list_scopes(self) -> list[str]:
+        seen: dict[str, None] = {}
+        for _, s in self._rules:
+            seen.setdefault(s, None)
+        return list(seen)
+
+    def _resolve_required(self, ctx: PolicyContext) -> Optional[str]:
+        meta = ctx.action.metadata or {}
+        method = str(meta.get("method", "") or "")
+        path = str(meta.get("path", "") or "")
+        for matcher, scope in self._rules:
+            if callable(matcher):
+                if matcher(ctx):
+                    return scope
+                continue
+            m_method, m_path = matcher
+            if method.upper() != m_method.upper():
+                continue
+            if isinstance(m_path, str):
+                if path == m_path:
+                    return scope
+            elif m_path.search(path):
+                return scope
+        return None
+
+
+__all__ = ["DefaultScopePolicy"]

themis_policy-0.1.0/src/themis/sinks.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Adam Campbell
+"""Reference audit sinks (RFC v0 § 7.3, § 9.4)."""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Callable, Optional, Sequence
+
+from .types import AuditEvent
+
+
+class ConsoleSink:
+    """NDJSON to stdout — one JSON line per event."""
+
+    def __init__(self, out: Optional[Callable[[str], None]] = None) -> None:
+        self._out = out or (lambda s: sys.stdout.write(s))
+
+    def emit(self, event: AuditEvent) -> None:
+        self._out(json.dumps(event.to_dict(), default=str) + "\n")
+
+
+class NoOpSink:
+    def emit(self, event: AuditEvent) -> None:  # noqa: D401 — intentional
+        pass
+
+    def flush(self) -> None:
+        pass
+
+
+class MemorySink:
+    """Collects events in memory — for tests and short-lived processes."""
+
+    def __init__(self) -> None:
+        self.events: list[AuditEvent] = []
+
+    def emit(self, event: AuditEvent) -> None:
+        self.events.append(event)
+
+
+class MultiSink:
+    """Fan-out. One child failing never stops delivery to the others; if EVERY
+    child fails the first error is raised so the engine's § 9.4 catch sees it."""
+
+    def __init__(self, children: Sequence) -> None:
+        self._children = list(children)
+
+    def emit(self, event: AuditEvent) -> None:
+        errors: list[BaseException] = []
+        for child in self._children:
+            try:
+                child.emit(event)
+            except Exception as e:  # noqa: BLE001
+                errors.append(e)
+        if errors and len(errors) == len(self._children):
+            raise errors[0]
+
+    def flush(self) -> None:
+        for child in self._children:
+            flush = getattr(child, "flush", None)
+            if callable(flush):
+                flush()
+
+
+__all__ = ["ConsoleSink", "NoOpSink", "MemorySink", "MultiSink"]

themis_policy-0.1.0/src/themis/types.py

@@ -0,0 +1,209 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Adam Campbell
+"""themis.types — the public types of the Themis policy kernel.
+
+Mirrors ``themis-policy`` ``types.ts`` one-for-one and conforms to Themis RFC v0.
+Decisions are frozen dataclasses with a ``kind`` discriminator; ``to_dict()``
+produces the exact wire shape the RFC specifies (keys with ``None`` omitted),
+which is what the cross-language conformance vectors compare.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Mapping, Optional, Protocol, Sequence, Union, runtime_checkable
+
+Id = Union[int, str]
+RequestorKind = Literal["user", "api_key", "agent", "service"]
+
+
+def _drop_none(d: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+# ── 1 — Requestor ──────────────────────────────────────────────────────────
+@dataclass(frozen=True)
+class Requestor:
+    id: Id
+    kind: RequestorKind
+    tenant_id: Id
+    scopes: tuple[str, ...] = ()
+    role: Optional[str] = None
+    is_super_admin: Optional[bool] = None
+    metadata: Optional[Mapping[str, Any]] = None
+
+
+# ── 2 — Action ─────────────────────────────────────────────────────────────
+@dataclass(frozen=True)
+class Action:
+    verb: str
+    resource_type: str
+    tenant_id: Id
+    resource_id: Optional[Id] = None
+    area: Optional[str] = None
+    required_scope: Optional[str] = None
+    payload: Any = None
+    metadata: Optional[Mapping[str, Any]] = None
+
+
+# ── 6/7 — Entities ─────────────────────────────────────────────────────────
+@dataclass(frozen=True)
+class LockableEntity:
+    id: Id
+    tenant_id: Id
+    agency_owner_id: Optional[Id]
+    locks: Mapping[str, bool]
+
+
+@dataclass(frozen=True)
+class DraftableEntity:
+    id: Id
+    tenant_id: Id
+    is_published: bool
+    has_pending_draft: bool
+    draft_updated_at: Optional[int]
+    draft_updated_by: Optional[Id]
+
+
+Entity = Union[LockableEntity, DraftableEntity]
+
+
+# ── 3 — PolicyContext ──────────────────────────────────────────────────────
+@dataclass(frozen=True)
+class PolicyContext:
+    requestor: Requestor
+    action: Action
+    now: int
+    correlation_id: str
+    entity: Optional[Entity] = None
+    policy_metadata: Optional[Mapping[str, Mapping[str, Any]]] = None
+
+
+# ── 4 — Decisions (discriminated union) ────────────────────────────────────
+@dataclass(frozen=True)
+class Allow:
+    kind: Literal["allow"] = "allow"
+    policy: Optional[str] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return _drop_none({"kind": self.kind, "policy": self.policy})
+
+
+@dataclass(frozen=True)
+class Deny:
+    policy: str
+    reason: str
+    message: Optional[str] = None
+    detail: Optional[Mapping[str, Any]] = None
+    kind: Literal["deny"] = "deny"
+
+    def to_dict(self) -> dict[str, Any]:
+        return _drop_none({
+            "kind": self.kind, "policy": self.policy, "reason": self.reason,
+            "message": self.message, "detail": dict(self.detail) if self.detail is not None else None,
+        })
+
+
+@dataclass(frozen=True)
+class Redirect:
+    policy: str
+    payload: Any
+    target: Literal["draft"] = "draft"
+    kind: Literal["redirect"] = "redirect"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"kind": self.kind, "policy": self.policy, "target": self.target, "payload": self.payload}
+
+
+@dataclass(frozen=True)
+class RequireApproval:
+    policy: str
+    approval_ref: str
+    message: Optional[str] = None
+    kind: Literal["require_approval"] = "require_approval"
+
+    def to_dict(self) -> dict[str, Any]:
+        return _drop_none({
+            "kind": self.kind, "policy": self.policy,
+            "approval_ref": self.approval_ref, "message": self.message,
+        })
+
+
+Decision = Union[Allow, Deny, Redirect, RequireApproval]
+
+
+def decision_from_dict(d: Mapping[str, Any]) -> Decision:
+    """Inverse of ``to_dict`` — used by adapters and the conformance harness."""
+    kind = d.get("kind")
+    if kind == "allow":
+        return Allow(policy=d.get("policy"))
+    if kind == "deny":
+        return Deny(policy=d["policy"], reason=d["reason"], message=d.get("message"), detail=d.get("detail"))
+    if kind == "redirect":
+        return Redirect(policy=d["policy"], payload=d.get("payload"), target=d.get("target", "draft"))
+    if kind == "require_approval":
+        return RequireApproval(policy=d["policy"], approval_ref=d["approval_ref"], message=d.get("message"))
+    raise ValueError(f"unknown decision kind: {kind!r}")
+
+
+# ── 5 — AuditEvent ─────────────────────────────────────────────────────────
+@dataclass(frozen=True)
+class AuditEvent:
+    id: str
+    timestamp: int
+    correlation_id: str
+    tenant_id: Id
+    requestor: Mapping[str, Any]
+    action: Mapping[str, Any]
+    decision: Decision
+    policy_chain: tuple[str, ...]
+    latency_ms: float
+    metadata: Optional[Mapping[str, Any]] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return _drop_none({
+            "id": self.id,
+            "timestamp": self.timestamp,
+            "correlation_id": self.correlation_id,
+            "tenant_id": self.tenant_id,
+            "requestor": _drop_none(dict(self.requestor)),
+            "action": _drop_none(dict(self.action)),
+            "decision": self.decision.to_dict(),
+            "policy_chain": list(self.policy_chain),
+            "latency_ms": self.latency_ms,
+            "metadata": dict(self.metadata) if self.metadata is not None else None,
+        })
+
+
+# ── 9/12 — Ports ───────────────────────────────────────────────────────────
+@runtime_checkable
+class Policy(Protocol):
+    name: str
+
+    def evaluate(self, ctx: PolicyContext) -> Decision: ...
+
+
+@runtime_checkable
+class AuditSink(Protocol):
+    def emit(self, event: AuditEvent) -> None: ...
+
+
+class LockStore(Protocol):
+    def get(self, entity_id: Id) -> Optional[LockableEntity]: ...
+    def set_lock(self, entity_id: Id, areas: Sequence[str], locked: bool) -> LockableEntity: ...
+    def request_unlock(self, entity_id: Id, requestor_id: Id, areas: Sequence[str], reason: str) -> None: ...
+
+
+class DraftStore(Protocol):
+    def get_entity(self, entity_id: Id) -> Optional[DraftableEntity]: ...
+    def write_draft(self, entity_id: Id, draft_payload: Any, updated_by: Id) -> None: ...
+    def write_live(self, entity_id: Id, payload: Any) -> None: ...
+    def list_pending_drafts(self, tenant_id: Id) -> Sequence[DraftableEntity]: ...
+    def publish(self, entity_id: Id) -> DraftableEntity: ...
+    def discard(self, entity_id: Id) -> DraftableEntity: ...
+
+
+__all__ = [
+    "Id", "RequestorKind", "Requestor", "Action", "LockableEntity", "DraftableEntity", "Entity",
+    "PolicyContext", "Allow", "Deny", "Redirect", "RequireApproval", "Decision", "decision_from_dict",
+    "AuditEvent", "Policy", "AuditSink", "LockStore", "DraftStore",
+]

themis_policy-0.1.0/src/themis_policy.egg-info/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: themis-policy
+Version: 0.1.0
+Summary: Themis policy kernel for bounded-autonomy LLM agents — locks, drafts, scopes, audit. Python reference implementation of Themis RFC v0.
+Author: Adam Campbell
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Adam-Camp-King/Themis
+Project-URL: Specification, https://github.com/Adam-Camp-King/Themis/tree/main/spec
+Keywords: llm,agents,policy,safety,bounded-autonomy,multi-tenant,audit
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+
+# themis-policy
+
+Python reference implementation of **Themis RFC v0** — a policy kernel for
+LLM agents that act on production systems. Four primitives — **locks**,
+**drafts**, **scopes**, **audit** — composed by one engine into a single
+decision per attempted action: `allow`, `deny`, `redirect`, or
+`require_approval`.
+
+Byte-compatible with [`themis-policy`](https://github.com/Adam-Camp-King/Themis)
+(TypeScript): both pass the same [conformance vectors](../spec/conformance).
+
+```python
+from themis import (
+    PolicyEngine, DefaultLockPolicy, DefaultScopePolicy, DefaultDraftPolicy,
+    Requestor, Action, PolicyContext, ConsoleSink, is_deny,
+)
+
+engine = PolicyEngine(audit_sink=ConsoleSink())
+engine.add_policy(DefaultLockPolicy())
+engine.add_policy(DefaultScopePolicy())
+engine.add_policy(DefaultDraftPolicy())
+
+decision = engine.evaluate(PolicyContext(
+    requestor=Requestor(id="key_1", kind="api_key", tenant_id=7, scopes=("pages:read",)),
+    action=Action(verb="pages.update", resource_type="page", tenant_id=7, resource_id=42,
+                  required_scope="pages:write"),
+    now=0, correlation_id="req-123",
+))
+if is_deny(decision):
+    print(decision.reason)          # missing_scope
+```
+
+The engine is synchronous (every core policy is pure CPU); `evaluate_async`
+exists for callers already inside an event loop. Stores (`LockStore`,
+`DraftStore`) are ports you implement against your persistence; audit sinks
+receive one event per evaluation and may never fail an evaluation.
+
+Install: `pip install themis-policy` (Python 3.11+, no dependencies).
+Tests: `pip install -e '.[test]' && pytest`.
+
+Apache-2.0 — see the repository LICENSE.

themis_policy-0.1.0/src/themis_policy.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+src/themis/__init__.py
+src/themis/engine.py
+src/themis/guards.py
+src/themis/py.typed
+src/themis/sinks.py
+src/themis/types.py
+src/themis/policies/__init__.py
+src/themis/policies/draft.py
+src/themis/policies/lock.py
+src/themis/policies/scope.py
+src/themis_policy.egg-info/PKG-INFO
+src/themis_policy.egg-info/SOURCES.txt
+src/themis_policy.egg-info/dependency_links.txt
+src/themis_policy.egg-info/requires.txt
+src/themis_policy.egg-info/top_level.txt
+tests/test_conformance.py

themis_policy-0.1.0/src/themis_policy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

themis_policy-0.1.0/src/themis_policy.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest>=8

themis_policy-0.1.0/src/themis_policy.egg-info/top_level.txt

@@ -0,0 +1 @@
+themis

themis_policy-0.1.0/tests/test_conformance.py

@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Run spec/conformance/v0/*.json and preview-tokens.json through the Python kernel.
+
+The same files are run by themis-policy. Passing them is what "conforms to
+Themis RFC v0" means (RFC § 11).
+"""
+from __future__ import annotations
+
+import json
+import pathlib
+from typing import Any
+
+import pytest
+
+from themis import (
+    Action, Allow, DefaultDraftPolicy, DefaultLockPolicy, DefaultScopePolicy, Deny, DraftableEntity,
+    LockableEntity, MemorySink, PolicyContext, PolicyEngine, Redirect, RequireApproval, Requestor,
+)
+
+SPEC = pathlib.Path(__file__).resolve().parents[2] / "spec" / "conformance"
+VECTOR_FILES = sorted((SPEC / "v0").glob("*.json"))
+
+
+class _Stub:
+    def __init__(self, spec: dict[str, Any]) -> None:
+        self.name = spec["name"]
+        self._spec = spec
+
+    def evaluate(self, ctx: PolicyContext):
+        s = self._spec
+        kind = s["stub"]
+        if kind == "allow":
+            return Allow(policy=self.name)
+        if kind == "deny":
+            return Deny(policy=self.name, reason=str(s.get("reason", "stub")), message=s.get("message"))
+        if kind == "redirect":
+            return Redirect(policy=self.name, target="draft", payload=s.get("payload"))
+        if kind == "require_approval":
+            return RequireApproval(policy=self.name, approval_ref=str(s.get("approval_ref", "ref")), message=s.get("message"))
+        raise ValueError(kind)
+
+
+def _build(spec: Any):
+    if spec == "lock":
+        return DefaultLockPolicy()
+    if spec == "draft":
+        return DefaultDraftPolicy()
+    if spec == "scope":
+        return DefaultScopePolicy()
+    if "stub" in spec:
+        return _Stub(spec)
+    p = DefaultScopePolicy()
+    for r in spec.get("rules", []):
+        p.add_rule((r["method"], r["path"]), r["required_scope"])
+    return p
+
+
+def _entity(e: Any):
+    if e is None:
+        return None
+    if "locks" in e and "agency_owner_id" in e:
+        return LockableEntity(id=e["id"], tenant_id=e["tenant_id"], agency_owner_id=e["agency_owner_id"], locks=dict(e["locks"]))
+    return DraftableEntity(
+        id=e["id"], tenant_id=e["tenant_id"], is_published=e["is_published"],
+        has_pending_draft=e.get("has_pending_draft", False),
+        draft_updated_at=e.get("draft_updated_at"), draft_updated_by=e.get("draft_updated_by"),
+    )
+
+
+def _canon(v: Any) -> Any:
+    if isinstance(v, list):
+        return [_canon(x) for x in v]
+    if isinstance(v, dict):
+        return {k: _canon(x) for k, x in v.items() if x is not None}
+    return v
+
+
+def _cases():
+    for f in VECTOR_FILES:
+        for c in json.loads(f.read_text())["cases"]:
+            yield pytest.param(c, id=f"{f.name} › {c['name']}")
+
+
+@pytest.mark.parametrize("c", list(_cases()))
+def test_vector(c: dict[str, Any]) -> None:
+    sink = MemorySink()
+    engine = PolicyEngine(audit_sink=sink, emit_policy=c.get("emit_policy", "all"))
+    for p in c.get("policies", []):
+        engine.add_policy(_build(p))
+    r, a = c["requestor"], c["action"]
+    ctx = PolicyContext(
+        requestor=Requestor(id=r["id"], kind=r["kind"], tenant_id=r["tenant_id"], scopes=tuple(r.get("scopes", [])),
+                            role=r.get("role"), is_super_admin=r.get("is_super_admin")),
+        action=Action(verb=a["verb"], resource_type=a["resource_type"], tenant_id=a["tenant_id"], resource_id=a.get("resource_id"),
+                      area=a.get("area"), required_scope=a.get("required_scope"), payload=a.get("payload"), metadata=a.get("metadata")),
+        entity=_entity(c.get("entity")),
+        now=1_700_000_000_000,
+        correlation_id=f"conf-{c['name']}",
+    )
+    decision = engine.evaluate(ctx)
+    assert _canon(decision.to_dict()) == _canon(c["expect"]["decision"])
+    audit = c["expect"].get("audit")
+    if audit == "none":
+        assert sink.events == []
+        return
+    assert len(sink.events) == 1, "exactly one audit event per evaluation"
+    e = sink.events[0]
+    assert list(e.policy_chain) == c["expect"]["policy_chain"]
+    assert _canon(e.decision.to_dict()) == _canon(c["expect"]["decision"])
+    assert e.tenant_id == a["tenant_id"]
+    assert e.correlation_id == ctx.correlation_id
+    if isinstance(audit, dict):
+        got = _canon({"requestor": dict(e.requestor), "action": dict(e.action)})
+        assert got == _canon(audit)
+
+
+def test_preview_tokens() -> None:
+    doc = json.loads((SPEC / "preview-tokens.json").read_text())
+    p = DefaultDraftPolicy()
+    for c in doc["cases"]:
+        assert p.verify_preview_token(c["token"], doc["secret"]) == c["expect"], c["name"]
+
+
+def test_sign_then_verify_roundtrip_and_ttl_clamp() -> None:
+    p = DefaultDraftPolicy()
+    tok = p.sign_preview_token(42, 7, 24, "s3cret")
+    assert p.verify_preview_token(tok, "s3cret") == {"entity_id": 42, "tenant_id": 7}
+    assert p.verify_preview_token(tok, "other") is None
+    with pytest.raises(ValueError):
+        p.sign_preview_token(1, 1, 1, "")
+
+
+def test_audit_sink_failure_never_fails_evaluation() -> None:
+    class Boom:
+        def emit(self, event):  # noqa: ANN001
+            raise RuntimeError("sink down")
+    engine = PolicyEngine(audit_sink=Boom())
+    r = Requestor(id=1, kind="user", tenant_id=1)
+    assert engine.evaluate(PolicyContext(requestor=r, action=Action(verb="x", resource_type="y", tenant_id=1), now=0, correlation_id="c")) == Allow()