z4j-core 2026.4.0a1

z4j domain core - models, protocols, transport, redaction, policy (Apache 2.0)

z4j-core

License: Apache 2.0 Status: Phase 1 — early implementation

The pure domain core of z4j. Imports nothing framework- or engine-specific — only Pydantic and the Python standard library. This is enforced by import-linter in CI. Any PR that tries to import Django, Celery, Redis, SQLAlchemy, FastAPI, etc. from z4j_core will fail the build.

Why this matters

Every other package in the z4j monorepo depends on z4j-core. The brain uses its domain models and wire protocol; every adapter implements one of its Protocols. Keeping this package free of framework coupling is what lets us:

1. Ship v1 with Django + Celery only, then add Flask / FastAPI / RQ / Dramatiq as peer packages without touching the core
2. Test the entire domain layer with no database, no broker, no HTTP
3. Evolve the protocol without rewriting the dashboard or the brain
4. Let contributors add a new engine adapter over a weekend without understanding any of the rest of the system

What's in here

Module	Purpose
z4j_core.models	Pydantic v2 domain models (Project, Agent, Task, Queue, Worker, Schedule, Command, Event, AuditEntry, User, Config, ...)
z4j_core.protocols	QueueEngineAdapter, FrameworkAdapter, SchedulerAdapter — the three adapter interfaces adapters implement
z4j_core.errors	Exception hierarchy (Z4JError, ValidationError, AuthenticationError, ...)
z4j_core.redaction	Secret redaction engine with default patterns and per-field overrides
z4j_core.transport	Wire protocol — frame shapes, version negotiation, HMAC signing
z4j_core.policy	Permission engine — can(user, action, project)

Documentation

• docs/ARCHITECTURE.md — full system architecture + Protocol signatures
• docs/API.md — REST + WebSocket agent protocol
• docs/SECURITY.md — threat model, redaction, HMAC
• docs/patterns.md — code patterns this package follows

Development

# From the repo root:
uv sync
make lint              # ruff + mypy + import-linter
make test-unit         # pytest packages/z4j-core/tests/unit
make check-imports     # import-linter — core purity check

License

Apache 2.0. See ../../LICENSE-APACHE. This package is deliberately permissively licensed so that proprietary Django / Flask / FastAPI applications can import it without any license concerns.