Data Model

Package chronos/pkg/types defines the wire contracts and chronos/internal/store implements the Postgres persistence. The alarms table IS the durable timer — state lives in the DB, never in memory, so a restart never loses a scheduled wake (invariant i1).

Source files: pkg/types/types.go, internal/store/alarms.go, migrations/001_init.sql.

---

The alarms table

One row per scheduled wake. The row itself is the timer — the dispatch worker polls next_fire_at, not an in-memory heap.

CREATE TABLE alarms (
    id               UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    owner_did        TEXT NOT NULL,
    user_id          TEXT NOT NULL,
    label            TEXT NOT NULL DEFAULT '',
    kind             TEXT NOT NULL CHECK (kind IN ('once', 'cron')),
    fire_at          TIMESTAMPTZ,
    cron_expr        TEXT NOT NULL DEFAULT '',
    timezone         TEXT NOT NULL DEFAULT 'UTC',
    next_fire_at     TIMESTAMPTZ NOT NULL,
    conversation_id  TEXT NOT NULL DEFAULT '',
    wake_message     TEXT NOT NULL DEFAULT '',
    payload          JSONB NOT NULL DEFAULT '{}'::jsonb,
    status           TEXT NOT NULL DEFAULT 'active'
                     CHECK (status IN ('active', 'fired', 'cancelled', 'failed')),
    idempotency_key  TEXT NOT NULL DEFAULT '',
    max_failures     INT  NOT NULL DEFAULT 5,
    failure_count    INT  NOT NULL DEFAULT 0,
    last_error       TEXT NOT NULL DEFAULT '',
    claimed_at       TIMESTAMPTZ,
    created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
    last_fired_at    TIMESTAMPTZ
);

Indexes

---

Column reference

---

Go types

Alarm

Alarm is the internal representation, mapping 1:1 onto a row:

type Alarm struct {
    ID             string
    OwnerDID       string
    UserID         string
    Label          string
    Kind           string         // "once" | "cron"
    FireAt         *time.Time
    CronExpr       string
    Timezone       string
    NextFireAt     time.Time
    ConversationID string
    WakeMessage    string
    Payload        json.RawMessage
    Status         string
    IdempotencyKey string
    MaxFailures    int
    FailureCount   int
    LastError      string
    ClaimedAt      *time.Time
    CreatedAt      time.Time
    UpdatedAt      time.Time
    LastFiredAt    *time.Time
}

View

View is the JSON projection returned to the agent. High-entropy fields (payload, wake_message, ids) are passed through verbatim (invariant i4):

type View struct {
    ID             string          `json:"id"`
    Label          string          `json:"label"`
    Kind           string          `json:"kind"`
    CronExpr       string          `json:"cron_expr,omitempty"`
    Timezone       string          `json:"timezone,omitempty"`
    NextFireAt     *time.Time      `json:"next_fire_at,omitempty"`
    ConversationID string          `json:"conversation_id,omitempty"`
    WakeMessage    string          `json:"wake_message"`
    Payload        json.RawMessage `json:"payload,omitempty"`
    Status         string          `json:"status"`
    IdempotencyKey string          `json:"idempotency_key,omitempty"`
    MaxFailures    int             `json:"max_failures"`
    FailureCount   int             `json:"failure_count"`
    LastError      string          `json:"last_error,omitempty"`
    CreatedAt      time.Time       `json:"created_at"`
    LastFiredAt    *time.Time      `json:"last_fired_at,omitempty"`
}

ViewOf(a Alarm) projects an Alarm onto its wire shape. NextFireAt is only included when status == "active".

---

Lifecycle statuses

                  ┌─────────┐
                  │  active  │
                  └────┬─────┘
         ┌─────────────┼─────────────┐
         ▼             ▼             ▼
    ┌────────┐   ┌──────────┐   ┌────────┐
    │ fired  │   │ cancelled│   │ failed │
    └────────┘   └──────────┘   └────────┘
    (once only)  (explicit)    (once only,
                                retries
                                exhausted)

Cron alarms stay active indefinitely — they never self-delete. Each fire advances next_fire_at and the alarm remains active. Cancellation is explicit.

---

Idempotency

When idempotency_key is non-empty, CreateAlarm uses a partial unique index:

CREATE UNIQUE INDEX alarms_idempotency_idx
    ON alarms (owner_did, idempotency_key)
    WHERE idempotency_key <> '';

The insert uses ON CONFLICT (owner_did, idempotency_key) WHERE idempotency_key <> '' DO NOTHING. If the row already exists, the existing alarm is returned with deduped=true. No duplicate is created.

---

Store operations

All alarm mutations go through store.Store methods: