AlmondTill/G3N API

On this page

realizeScratchpad

mutation · in the family Work and notes

What it does

Execute an approved plan — create its records one step at a time under YOUR OWN permissions.

Execute an APPROVED plan: flips approved|realization_failed → realizing, then runs each unrealized step IN ORDER through the ordinary create operations UNDER YOUR OWN session, capability, and every normal gate (the hardened-Aldric law — the spine holds no authority of its own; per-step atomicity: each create is its own transaction). Every born id stamps back onto its step (the idempotency key — a re-run RESUMES, skipping realized steps, and never creates twice); every born record's history narrates this scratchpad and step. A step refusal stamps the fault VERBATIM and lands realization_failed — retry here to resume, or abandon (records already born stay). A crash caught between a step's commit and its stamp refuses auto-resume (the ambiguity fence — no silent duplicate is ever minted). Refuses CONFLICT/REF_STATE when the plan revision drifted from the approved pin. Requires authentication (user sessions) + the record's current revision. Template class (universal staff work).

What happens

Each step runs as if you called that create yourself, through every normal permission and validation gate. Every created record is stamped back onto the plan step; a re-run continues where it left off and never creates a step’s record twice.

Careful

Steps that already ran stay real even if a later step fails — the scratchpad shows the fault verbatim, and you retry (it resumes) or abandon (what was born stays).

Who may call it

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

Arguments

NameTypeRequiredNotes
idID ID!yesThe id of the record.
revisionID ID!yesThe revision id you read on the record; the change is refused if an edit landed in the meantime.
reasonStringnoNo 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 ExampleRealizeScratchpad($id: ID!, $revision: ID!, $reason: String) {
  realizeScratchpad(id: $id, revision: $revision, 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",
  "reason": "Correcting a miscount."
}

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

Example response

{
  "data": {
    "realizeScratchpad": {
      "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

Used in