Edictum Core Implementation
Read CLAUDE.md first. Understand the boundary principle before writing code.
Scope
Everything under src/edictum/ is the core library (MIT). This includes:
- Pipeline (
pipeline.py) — CheckPipeline, PreDecision, PostDecision
- Envelope (
envelope.py) — ToolCall, Principal, create_envelope()
- Contracts (
rules.py) — @precondition, @postcondition, @session_contract, Decision
- YAML engine (
yaml_engine/) — loader, evaluator, compiler (including sandbox compilation), templates
- Adapters (
adapters/) — all 7 framework adapters
- Audit (
audit.py) — AuditEvent, StdoutAuditSink, FileAuditSink, RedactionPolicy
- Session (
session.py) — Session, MemoryBackend
- CLI (
cli/) — validate, check, diff, replay, test
- Telemetry (
telemetry.py) — OTel spans, GovernanceTelemetry
- Server SDK (
server/) — client components for connecting to edictum-server
Architecture
Two deployment units:
- Core (
pip install edictum) — runs fully standalone. All 4 rule types (pre, post, session, sandbox), pipeline, 7 adapters, CLI, local audit, local approval.
- Server (
edictum-server) — separate deployment, coming soon. The Server SDK (pip install edictum[server]) provides the client-side connectivity.
Core provides protocols and interfaces. The server SDK provides HTTP-backed implementations.
What needs the server
Most features work without the server. These require it:
| Feature |
Core |
Server |
| Rule evaluation (all 4 types) |
Yes |
-- |
outside: block / action: block |
Yes |
-- |
outside: ask / action: ask (dev) |
Yes (LocalApprovalBackend) |
-- |
outside: ask / action: ask (production) |
-- |
Yes (ServerApprovalBackend) |
| Audit to stdout/file/OTel |
Yes |
-- |
| Centralized audit dashboard |
-- |
Yes (ServerAuditSink) |
| Session tracking (single process) |
Yes (MemoryBackend) |
-- |
| Session tracking (multi-process) |
-- |
Yes (ServerBackend) |
| Hot-reload rules |
-- |
Yes (ServerRuleSource) |
Workflow
- Read CLAUDE.md — understand boundaries and dropped features
- Read the Linear ticket or user description
- Read relevant source files before proposing changes
- Scenarios & use cases — before implementing, write down:
- What concrete scenarios does this feature enable?
- What user personas benefit?
- Does this overlap with existing features?
- Does this surface related features that should be designed separately?
- Include this analysis in BOTH:
- The PR body under a
## Scenarios section
- The docs page under a
## When to use this section (see .docs-style-guide.md page structure pattern)
- Scope with user — confirm approach before writing code
- Implement — small, focused changes
- Behavior test — every new/changed API parameter gets a test in
tests/test_behavior/test_{module}_behavior.py
- Docs-code sync —
pytest tests/test_docs_sync.py -v
- Adapter parity — if touching adapters:
pytest tests/test_adapter_parity.py -v
- Test —
pytest tests/ -v then ruff check src/ tests/
- Commit — conventional commits, no Co-Authored-By
Conventions
- Frozen dataclasses for immutable data
- All pipeline/session/audit methods are async
from __future__ import annotations in every file- Type hints everywhere
- Test file per module:
tests/test_{module}.py
Do NOT
- Implement Redis/DB StorageBackend — dropped feature
- Accept a parameter without testing its observable effect — if it's accepted, it must DO something testable
- Document a feature that doesn't exist in code —
pytest tests/test_docs_sync.py -v catches this
- Ship an adapter change without running parity checks —
pytest tests/test_adapter_parity.py -v
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: edictum-oss3description: Implement features in the Edictum OSS core (src/edictum/). Use when the task touches pipeline, adapters, YAML engine, CLI, audit, envelope, or session. Core NEVER imports from ee/. Use when this capability is needed.4---56# Edictum Core Implementation78Read CLAUDE.md first. Understand the boundary principle before writing code.910## Scope1112Everything under `src/edictum/` is the core library (MIT). This includes:1314- Pipeline (`pipeline.py`) — CheckPipeline, PreDecision, PostDecision15- Envelope (`envelope.py`) — ToolCall, Principal, create_envelope()16- Contracts (`rules.py`) — @precondition, @postcondition, @session_contract, Decision17- YAML engine (`yaml_engine/`) — loader, evaluator, compiler (including sandbox compilation), templates18- Adapters (`adapters/`) — all 7 framework adapters19- Audit (`audit.py`) — AuditEvent, StdoutAuditSink, FileAuditSink, RedactionPolicy20- Session (`session.py`) — Session, MemoryBackend21- CLI (`cli/`) — validate, check, diff, replay, test22- Telemetry (`telemetry.py`) — OTel spans, GovernanceTelemetry23- Server SDK (`server/`) — client components for connecting to edictum-server2425## Architecture2627Two deployment units:2829- **Core** (`pip install edictum`) — runs fully standalone. All 4 rule types (pre, post, session, sandbox), pipeline, 7 adapters, CLI, local audit, local approval.30- **Server** (`edictum-server`) — separate deployment, coming soon. The Server SDK (`pip install edictum[server]`) provides the client-side connectivity.3132Core provides protocols and interfaces. The server SDK provides HTTP-backed implementations.3334## What needs the server3536Most features work without the server. These require it:3738| Feature | Core | Server |39|---|---|---|40| Rule evaluation (all 4 types) | Yes | -- |41| `outside: block` / `action: block` | Yes | -- |42| `outside: ask` / `action: ask` (dev) | Yes (LocalApprovalBackend) | -- |43| `outside: ask` / `action: ask` (production) | -- | Yes (ServerApprovalBackend) |44| Audit to stdout/file/OTel | Yes | -- |45| Centralized audit dashboard | -- | Yes (ServerAuditSink) |46| Session tracking (single process) | Yes (MemoryBackend) | -- |47| Session tracking (multi-process) | -- | Yes (ServerBackend) |48| Hot-reload rules | -- | Yes (ServerRuleSource) |4950## Workflow51521. **Read CLAUDE.md** — understand boundaries and dropped features532. **Read the Linear ticket** or user description543. **Read relevant source files** before proposing changes554. **Scenarios & use cases** — before implementing, write down:56 - What concrete scenarios does this feature enable?57 - What user personas benefit?58 - Does this overlap with existing features?59 - Does this surface related features that should be designed separately?60 - Include this analysis in BOTH:61 - The PR body under a `## Scenarios` section62 - The docs page under a `## When to use this` section (see `.docs-style-guide.md` page structure pattern)635. **Scope with user** — confirm approach before writing code646. **Implement** — small, focused changes657. **Behavior test** — every new/changed API parameter gets a test in `tests/test_behavior/test_{module}_behavior.py`668. **Docs-code sync** — `pytest tests/test_docs_sync.py -v`679. **Adapter parity** — if touching adapters: `pytest tests/test_adapter_parity.py -v`6810. **Test** — `pytest tests/ -v` then `ruff check src/ tests/`6911. **Commit** — conventional commits, no Co-Authored-By7071## Conventions7273- Frozen dataclasses for immutable data74- All pipeline/session/audit methods are async75- `from __future__ import annotations` in every file76- Type hints everywhere77- Test file per module: `tests/test_{module}.py`7879## Do NOT8081- Implement Redis/DB StorageBackend — dropped feature82- Accept a parameter without testing its observable effect — if it's accepted, it must DO something testable83- Document a feature that doesn't exist in code — `pytest tests/test_docs_sync.py -v` catches this84- Ship an adapter change without running parity checks — `pytest tests/test_adapter_parity.py -v`8586---87> Converted and distributed by [TomeVault](https://tomevault.io/claim/acartag7) — claim your Tome and manage your conversions.88<!-- tomevault:4.0:skill_md:2026-04-13 -->
tomevault-io