Concepts
Every entity in the domain model, where each one is documented, and the invariants that hold across all of them
Not built yet. None of the tables below exist. The Prisma schema in packages/database still ships
a single stub model inherited from the template this repository started as. These pages describe the
intended shape, taken from spec/01-domain-model.md.
Storage is Cloudflare D1 via @repo/database (Prisma schema for tooling).
Entity map
Every entity in the domain model, and the page that covers it.
| Entity | What it is | Documented in |
|---|---|---|
| Workspace | Tenant boundary, mapped to a Clerk organization | Agents and machines |
| User | Human, Clerk-backed, with a role | Agents and machines |
| Agent | The definition of a worker that may claim tasks | Agents and machines |
| Machine | A workstation that can host a runtime | Agents and machines |
| ApiKey / AgentToken | Scoped credential for machine access | Agents and machines |
| Project | Groups tasks; links a repository and a board | Tasks |
| Task | The unit of intent | Tasks |
| Schedule | Recurring task template | Tasks |
| Comment | Threaded human and agent conversation on a Task | Tasks |
| Run | One attempt at a Task by an Agent on a Machine | Runs and events |
| Event | Append-only timeline | Runs and events |
| WebhookSubscription | Outbound push so a runner is woken, not polling | Runs and events |
| Artifact | Any output worth keeping | Documents and artifacts |
| Document | Durable knowledge not tied to one task | Documents and artifacts |
| Approval | Human-in-the-loop gate | Approvals and leasing |
The task state machine is on the Tasks page, with its legal transitions and the guard on each one.
Record conventions
These are designed to apply to every table, not to a chosen few. They are repeated on the Tasks page with more detail.
| Convention | Rule |
|---|---|
| IDs | ULID primary keys, prefixed per entity, lexicographically sortable. No sequential integers are exposed. |
| Slugs | Stable, human and agent readable, unique per workspace. |
| Tenancy | Every row carries workspaceId. No cross-workspace read, including for agent tokens. |
| Versioning | Every mutable row carries version, surfaced as an ETag, checked with If-Match. |
| Provenance | createdByType (user, agent, system) and createdById, plus the same pair for updatedBy. |
| Soft delete | archivedAt. Rows are never hard deleted. |
| Timestamps | UTC, ISO-8601 on the wire. |
Invariants
The four statements the design treats as always true. Each one is a rule the service layer holds, not a convention a caller is trusted to follow.
- A Task in
in_progressalways has exactly one Run inrunning. - An Event is never updated and never deleted.
- An Artifact is immutable once written. A new version is a new row.
- No table stores a secret value. Only
secretRefpointers to the real store.
The last one is the reason there is no field anywhere in this model that holds a token, a password or a key. An agent that needs a credential receives a reference and resolves it on its own machine.