Schema — dispatch.json · schema-dispatch-json

Owner directive (2026-07-10), canonical. "Create a Dispatch, Wake you up every 10 minutes, check if all capability is allocated, check the conclusion of particles and atoms and if the run is moving." [src: wiki/development/prompts-archive/by-topic/knowledge-management-and-concept-modeling.md:646]

Content

The state file pb-003-run-dispatch reads and writes each tick. It is modelled directly on the proven RUN-015 autoloop state — run, status, cycle, startedAt, intervalSeconds, tick, a playbooks queue, rails, done/inflight/owner_gated lists [src: runs/RUN-015-autoloop.json:2] — extended with step cursors per playbook, squad states and an explicit heartbeats[] trail so the workstation page (bp-001-spatial-site page 3) can render the run live. intervalSeconds defaults to 600 (the owner's "every 10 minutes"; RUN-015 shipped the same value [src: runs/RUN-015-autoloop.json:8]).

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "hos://schemas/dispatch.json",
  "title": "HOS run dispatch state",
  "type": "object",
  "required": ["run", "status", "cycle", "tick", "startedAt",
               "intervalSeconds", "playbooks", "squads", "heartbeats"],
  "properties": {
    "run": { "type": "string", "description": "e.g. RUN-016-spatial-site", "pattern": "^RUN-[0-9]{3}" },
    "status": { "enum": ["queued", "in-progress", "paused", "blocked", "done"] },
    "cycle": { "type": "integer", "minimum": 1, "description": "increments on run extension (RUN-015 precedent: cycle 3)" },
    "tick": { "type": "integer", "minimum": 0, "description": "dispatch wake counter; strictly increasing" },
    "startedAt": { "type": "integer", "description": "epoch seconds" },
    "deadlineEpoch": { "type": "integer" },
    "intervalSeconds": { "type": "integer", "const": 600 },
    "self_extending": { "type": "string", "description": "optional policy string; RUN-015: 'At deadline cycle++ +5h, never finalize, until owner stops'" },
    "rails": { "type": "string", "description": "run guardrails, e.g. 'tsc0+build … never main; NEVER enter secrets'" },
    "resume": { "type": "string", "description": "path to the RESUME doc" },
    "playbooks": {
      "type": "object",
      "description": "queue keyed by playbook card id (e.g. pb-001-spatial-site-loop)",
      "additionalProperties": {
        "type": "object",
        "required": ["steps", "cursor", "squad"],
        "properties": {
          "steps": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
          "cursor": { "type": "integer", "minimum": 0, "description": "index of the next step (particles < cursor are concluded)" },
          "squad": { "type": "string", "description": "squad card id, e.g. squad-instance" },
          "blocked_on": { "type": "string" }
        }
      }
    },
    "squads": {
      "type": "object",
      "description": "keyed by squad card id",
      "additionalProperties": {
        "type": "object",
        "required": ["state"],
        "properties": {
          "state": { "enum": ["ready", "active", "blocked", "idle", "done"] },
          "particle": { "type": "string", "description": "current work particle" },
          "gear_set": { "type": "string", "description": "gear-sets entry equipped" },
          "last_commit": { "type": "string", "description": "sha of the squad's last loop commit" }
        }
      }
    },
    "heartbeats": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["tick", "at", "state"],
        "properties": {
          "tick": { "type": "integer" },
          "at": { "type": "integer", "description": "epoch seconds" },
          "state": { "type": "string", "description": "one-line run-motion summary" },
          "commits_since_last": { "type": "integer", "minimum": 0 }
        }
      }
    },
    "done": { "type": "array", "items": { "type": "string" } },
    "inflight": { "type": "array", "items": { "type": "string" } },
    "owner_gated": {
      "type": "array", "items": { "type": "string" },
      "description": "surfaced-never-entered items (credentials, DNS, certs) — RUN-015 pattern"
    },
    "pending_light": { "type": "array", "items": { "type": "string" } }
  }
}

Invariants: tick strictly increases and every tick appends exactly one heartbeat; a playbooks entry's cursor never decreases and never exceeds steps.length; run-motion rule — if commits_since_last == 0 on a heartbeat, the next tick must record a blocker or escalate ("if the run is moving" [src: wiki/development/prompts-archive/by-topic/knowledge-management-and-concept-modeling.md:646]); owner_gated items are never executed by the dispatcher (RUN-015 owner_gated precedent [src: runs/RUN-015-autoloop.json:93]).

Composition

• uses: playbook card ids (pb-001-spatial-site-loop, pb-002-library-authoring) · squad card ids (squad-eggtech, squad-schematic, squad-instance) · gear-sets
• used-by: pb-003-run-dispatch (per-tick contract) · sc-002-neural-engine-run (Library/dispatch lane) · bp-001-spatial-site (workstation page) · sop-003-run-dispatch

See also

• schema-library-json — the knowledge the dispatcher reads
• neural-engine