transitionScratchpad

mutation · in the family Scratchpad

What it does

Move a scratchpad through its life — hold the plan for review, reopen it for editing, approve it, or abandon it.

One caller edge of the spine FSM (ready · reopen · approve · abandon — the Task class; retry is EXCLUDED, carried by realizeScratchpad: a bare wire retry would strand realizing with no engine running). ready holds the plan for human review (refuses VALIDATION/INVALID on an empty plan); reopen returns it to draft for editing; approve PINS the plan revision (refuses VALIDATION/INVALID while ANY step is marked, and AUTHZ/FORBIDDEN when the APPROVER's own capability could not run every step — the preview≡enforcement pre-check, evaluated strict); abandon closes without (full) realization — constructs already born LIVE ON (born records are real; the stamps keep the provenance).

What happens

Approve pins the exact plan it approved — the plan cannot change afterwards without a reopen and a fresh approval; approving also checks YOUR own permissions can run every step, and refuses naming the steps you could not.

Careful

Abandon is an endpoint. Records already created by earlier realization steps stay — abandoning the plan never deletes what it already made.

Who may call it

Capability area: Work and notes — Tasks, notes, messages, dashboards and the everyday tools every staff member keeps.

Owner
System Administrator
Manager
Associate Manager
Warehouse Associate
Sales Associate
Cashier
An API key whose scope allows api:transitionScratchpad

Arguments

Name	Type	Required	Notes
`id`	ID `ID!`	yes	The id of the record.
`revision`	ID `ID!`	yes	The revision id you read on the record; the change is refused if an edit landed in the meantime.
`op`	ScratchpadTransitionOp `ScratchpadTransitionOp!`	yes	No further notes.
`reason`	String	no	No further notes.

Returns

Scratchpad Scratchpad! — A Scratchpad: collects intent (free text now; wizard answers/imports/suggestions/consultations mint through their own entrances later) until it holds a PLAN — ordered {operation, input} steps in wire vocabulary (≤24; creates-only v1: each operation must be a live create-class registry mutation) — and, once a human approves, REALIZES the plan into born constructs through the ordinary ops under the realizing caller's OWN session and capability (the hardened-Aldric law: the spine holds ZERO special authority; AI is just one plan author, and the spine never knows the difference). USER-parented (the collector owns the walk), group-rooted. Invalid steps are MARKED, never repaired; a marked plan can be ready for human eyes but can never be approved. Approval PINS the plan revision (the approved plan IS the executed plan); realization is idempotent + convergent-resume (the realized-id stamps are the idempotency keys) and every step's born cause narrates the scratchpad. The ops event domain (at.ops.scratchpad.*).

Example request

mutation ExampleTransitionScratchpad($id: ID!, $revision: ID!, $op: ScratchpadTransitionOp!, $reason: String) {
  transitionScratchpad(id: $id, revision: $revision, op: $op, reason: $reason) {
    id
    sysId
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    origin
    intent
    planRevision
    approvedPlanRevision
    inFlightSeq
    realizationFault
  }
}

Variables:

{
  "id": "01900000-0000-7000-8000-37386ae00000",
  "revision": "01900000-0000-7000-8000-b7960e180000",
  "op": "ready",
  "reason": "Correcting a miscount."
}

Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.

Example response

{
  "data": {
    "transitionScratchpad": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "sysId": "SD-EXMP-0000-000F",
      "type": "Scratchpad",
      "caption": "Blue jeans",
      "status": "draft",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "origin": "<origin>",
      "intent": "<intent>",
      "planRevision": 1,
      "approvedPlanRevision": 1,
      "inFlightSeq": 1,
      "realizationFault": "<realization fault>"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

Errors this call can answer

VALIDATION/INVALID — Something in the request is not valid. (VALIDATION)
AUTHN/REQUIRED — Sign in to do this. (AUTHN)
AUTHZ/FORBIDDEN — Your role does not allow this action. (AUTHZ)
RATE_LIMIT/THROTTLED — Too many requests in a short time. (RATE_LIMIT)
NOT_FOUND/* — That record could not be found. (NOT_FOUND)
CONFLICT/* — The record’s state, or a change made in the meantime, does not allow this; the codes are on the CONFLICT page. (CONFLICT)
VALIDATION/VERSION_REQUIRED — The request did not say which app version it came from. (VALIDATION)