| Agent |
A z4j process running inside your app, connected to the brain over WebSocket or HTTPS long-poll. One per app process. |
| Brain |
The central z4j server - FastAPI + React dashboard + PostgreSQL or SQLite. |
| Broker |
The message transport underneath your queue engine (Redis, RabbitMQ, SQS). z4j observes queues but does not act as a broker. |
| Capability map |
JSON object each agent sends in hello, mapping each loaded engine and scheduler adapter name to the list of capability names it supports (action names such as retry_task, plus contract markers such as retry_by_reference_v1). It does not say which actions are native and which are polyfilled. |
| Control plane |
The management layer that observes and acts on task infrastructure without participating in the task runtime. |
| Engine |
A Python task-queue library (Celery, RQ, Dramatiq, Huey, arq, taskiq). z4j adapts to each. |
| Engine adapter |
A z4j pip package (z4j-celery, etc.) that bridges engine-specific APIs to the z4j wire protocol. |
| Event |
A timestamped record of a task lifecycle transition (task.sent, task.started, task.succeeded, ...). |
| Framework adapter |
A z4j pip package (z4j-django, etc.) that hooks into the framework's boot and settings. |
| HMAC chain |
The audit log's HMAC-chained integrity mechanism - each row's HMAC depends on the previous row's. |
| Polyfill |
When z4j implements an action that the engine doesn't expose natively (e.g., restart_worker as a graceful self-exit, or retry_task lowered to submit_task with the task name and explicit arguments on arq). |
| Project |
The tenancy boundary in z4j. Agents and tasks are scoped to a project; users are global and hold a per-project membership role (viewer, auditor, operator or admin). |
| Reconciliation |
The background process that finds "started-forever" tasks and queries the agent about their real state. |
| Redaction |
Stripping secrets from event payloads before they leave the agent. |
| Scheduler |
A periodic-task system paired with an engine (celery-beat, rq-scheduler, APScheduler, etc.). |
| Scheduler adapter |
A z4j pip package (z4j-celerybeat, etc.) that bridges schedule discovery and CRUD. |
| Setup URL |
The first-boot one-shot URL z4j prints so the operator can create the initial admin. |
| Wire protocol |
The JSON framing that agents and the brain speak, over WebSocket or HTTPS long-poll. Versioned independently of the packages: the agent advertises its protocol version in hello, the brain confirms the accepted version in hello_ack, and an unsupported version is closed with 4426. |
