Skip to content
Treaty

card.ready v1

A card became ready to be claimed on a board opted into scheduling: it reached a stage an agent may claim from in a claimable state, or was resumed or returned there. A placement service reacts to it at once instead of waiting for its sweep; it is a hint, and the board read stays the truth. Sent only by a board with a placement window (charter: SuperDispatch owns the scheduler). Mirrors SuperPipeline’s CardReadyBody (apps/api/src/board/placement-window.ts). Readers ignore properties they do not know.

CloudEvents

Section titled “CloudEvents”

Every event below carries dataschema https://raw.githubusercontent.com/SuperJackfruitLabs/treaty/main/schemas/superpipeline/card.ready.v1.json.

Body event CloudEvents type Subject
card.ready com.superjackfruit.superpipeline.card.ready.v1 evt.<workspace>.superpipeline.card.ready

The subject is the NATS subject the relay files it under; <workspace> is the board’s workspace. See the envelope and subjects.

Who sends it, who reads it

Section titled “Who sends it, who reads it”
  • Produced by SuperPipeline, through the relay.
  • Consumed by:
    • SuperDispatch: Places the card at once, alone, inside the board’s placement window. A hint, not a fact: it reads the board before it places anything.

Fields

Section titled “Fields”

Readers ignore properties they do not know, so a field may be added without a new version.

Field Type Required Description Constraints
event "card.ready" yes
boardId string yes Never null: the event is routed by its board. at least 1 character
cardId string yes at least 1 character
stageKey string yes The stage the card is ready at. at least 1 character
readyAt string yes When the card became ready: where its placement window starts. format date-time
placementWindowUntil string no Until when the board holds the card back from pull so it can be placed. Absent when the board has no window. A hold made inside the window is claimable by its agent at once. format date-time
ts string yes format date-time

Example

Section titled “Example”

From fixtures/superpipeline-events/examples.json, case “windowed”:

{
  "event": "card.ready",
  "boardId": "brd_ceb6d1c7c02a4a6b",
  "cardId": "card_4d2e8f1a0b3c5d6e",
  "stageKey": "plan",
  "readyAt": "2026-11-13T09:30:00.000Z",
  "placementWindowUntil": "2026-11-13T09:30:10.000Z",
  "ts": "2026-11-13T09:30:00.000Z"
}

The corpus has 2 valid cases in all:

no-window 
{
  "event": "card.ready",
  "boardId": "brd_ceb6d1c7c02a4a6b",
  "cardId": "card_4d2e8f1a0b3c5d6e",
  "stageKey": "plan",
  "readyAt": "2026-11-13T09:30:00.000Z",
  "ts": "2026-11-13T09:30:00.000Z"
}

Refused

Section titled “Refused”

Each of these must fail. The corpus says why:

  • the event names itself
  • boardId is never null
  • cardId is required
  • readyAt is a date-time
  • placementWindowUntil is a date-time when present

Source

Section titled “Source”