@taifoon/jev 0.2.14 → 0.2.16

package/workflows/0.2.15/README.md

@@ -0,0 +1,109 @@
+# Jev workflows 0.2.15
+
+The n8n workflows that run Jev on n8n.taifoon.dev, exported with credential references replaced by placeholders (`{ "id": "", "name": "REPLACE: <credential type>" }`: pick your own credential of that type after import). Import with n8n → Workflows → Import from File, or `n8n import:workflow --input=<file>`. Every step carries its contract: `meta.taifoon.steps` names the canonical entity it takes and emits by `$id`; the schemas are in `schemas/` (the `$id`s are identifiers, the files are here).
+
+## Nodes they need
+
+| Package | Tested with | Where |
+|---|---|---|
+| `@taifoon/n8n-nodes-typesafe` | 2.0.1 | npm (community node): npm i @taifoon/n8n-nodes-typesafe |
+| `n8n-nodes-taifoon` | 0.4.5 | custom extension (type prefix CUSTOM.); not on npm |
+| `n8n-nodes-taifoon-devnet-signer` | 0.3.0 | custom extension (type prefix CUSTOM.); not on npm |
+
+## Credentials they need
+
+| Type | What |
+|---|---|
+| `taifoonTypeSafeApi` | your TypeSafe key (console.typesafe.ai) — credential type "TypeSafe API" of @taifoon/n8n-nodes-typesafe |
+| `taifoonRelayerApi` | a Taifoon relayer key (tfr_…) for https://www.taifoon.io/v1 — credential type "Taifoon Relayer API" of n8n-nodes-taifoon |
+| `taifoonDevnetKeyApi` | a devnet 36927 key with gas from https://faucet.taifoon.dev — credential type "Taifoon Devnet Key API" of n8n-nodes-taifoon-devnet-signer |
+
+## HIRE → JUDGE → SETTLE (devnet 36927) — `hire-judge-settle.json`
+
+One hire from offer to settlement. The seller’s reply is held with its digest; prepare decides the facts (a hard fail skips Jev); your TypeSafe credential answers the four RUBRIC_v1 questions; answers composes the verdict under THRESHOLDS_v1, records decision.v2 and jev.answer.v1 and, with Record On = devnet (set in this file), anchors them on the devnet logs; a complete settles through the devnet assurance hook (approve, fund, submit, complete), needs_review is held until the job’s deadline, when anyone may call expire. Executions 86 and 88 of this workflow are the golden runs @taifoon/jev re-derives.
+
+**Needs:** n8n-nodes-taifoon ≥ 0.4.5 and n8n-nodes-taifoon-devnet-signer ≥ 0.3.0 (custom extensions), @taifoon/n8n-nodes-typesafe ≥ 2.0.1; a Taifoon relayer key, your TypeSafe key, and two devnet 36927 keys (buyer, seller) with gas and dUSDC. **Outputs:** the whole JOB (Receipt, then Proofs · wait): handshake, verdict, decision with its devnet anchor tx, and every settlement transaction with its proof link.
+
+- source: `tfnhiresettle001` on n8n.taifoon.dev · sha256 `b13b48369fb6cdba88371c22d5aba8710eab414ac30a818c2a8189116b86c94b`
+- nodes: `n8n-nodes-taifoon`, `@taifoon/n8n-nodes-typesafe`, `n8n-nodes-taifoon-devnet-signer`; built-ins manualTrigger v1, set v3.4, code v2, if v2.2, httpRequest v4.2
+- credentials: `taifoonRelayerApi`, `taifoonTypeSafeApi`, `taifoonDevnetKeyApi`
+
+| Step | Takes | Emits | Does |
+|---|---|---|---|
+| Start | — | — | start a run (swap for a Webhook or Schedule trigger) |
+| Inputs | — | hire.json | the hire intent: task, candidate seller, endpoint/tool, buyer, price, chain (a HIRE in state Open) |
+| Offer + deliver | hire.json | job.json | POST /v1/handshake {dispatch:true}: the offer goes to the seller’s own endpoint; the reply is held with its keccak digest |
+| Delivery | job.json | delivery.json | stop unless a reply digest is held (no digest = nothing to settle) |
+| Judge · prepare | delivery.json | facts.json | POST /v1/judge/compose (prepare): the facts decide first; hard_fail ends here; else the exact text Jev reads + prepare_digest |
+| Hard fail? | facts.json | facts.json | branch: a hard fail goes straight to the verdict without asking Jev |
+| Jev · TypeSafe (our credential) | facts.json | answers.json | TypeSafe ask on the prepared text: every RUBRIC_ASKED answer with its whole distribution |
+| Judge · answers | answers.json | verdict.json | POST /v1/judge/compose (answers): recompose under THRESHOLDS_v1, record decision.v2, anchor on JevDecisionLog |
+| Verdict | verdict.json + facts.json | verdict.json | the composed verdict (complete \| reject \| needs_review) with what settlement needs carried forward |
+| Settle | verdict.json | settlement.json | POST /v1/settle: the plan (jobId, price, premium, deposit, calls[] in order, who signs each) |
+| Seller · approve deposit | settlement.json | settlement.json | the seller approves D (> P); the tx joins settlement.txs |
+| Buyer · approve + fund | settlement.json | settlement.json | the buyer approves P + π and calls fundJob: machine Delivered → Funded |
+| Seller · submit | settlement.json | settlement.json | submit(jobId, evidenceDigest = delivery.digest): machine Funded → Submitted |
+| Verdict says complete? | settlement.json | settlement.json | branch on the composed verdict: complete → complete; otherwise hold (Submitted → Held) |
+| Buyer · complete + capture | settlement.json | settlement.json | complete(jobId) (+ capture): machine → Settled |
+| Settle row · decided | settlement.json | settlement.json | the settle row names the decision, not a document: POST /v1/settle/decided { jobId, decision_id, end_tx = the complete transaction } on the lane’s relayer key. The layer writes decided_by "jev" only when the chain proves it (an automatic complete, the decision’s anchor on the JevDecisionLog, the job bound to the handshake and its sealed reply, Completed for this job); it never errors the run |
+| Held for review | settlement.json | settlement.json | needs_review / reject: funded and sealed, nothing paid; the operator step (a record, then the evaluator’s postVerdict) or the deadline decides |
+| Receipt | settlement.json | job.json | the whole JOB: hire, delivery, facts, verdict, settlement — every transaction with its proof link |
+| Proofs · wait | job.json | job.json | GET /v1/proof/tx/36927/<tx> for every transaction of the run; pending is retried with backoff (5 s -> 60 s, <= 240 s), never reported as a gap |
+| Operator step · open | settlement.json | settlement.json | the evaluator leg, not a document: POST /v1/settle/evaluate {open:true} opens the operator step of a job held on needs_review. The workflow does not decide: the step waits for an operator record (decided_by loop-agent on the devnet, or operator with the operator key), anchored on chain before the evaluator posts. A composed reject is not an operator step (the layer answers not_needs_review) |
+
+## Jev on-chain grader (grade → stamp → devnet) — `jev-grader.json`
+
+Grades Base jobs that were paid and delivered and that nobody ruled on (GET /v1/judge/ready): four per run, each through prepare → Jev → answers, then the canonical verdict, then GradeStampRegistry.stamp on the devnet, signed by the devnet signer node; the stamp transaction is appended to the verdict’s anchors.
+
+- source: `tfnjevgrader0001` on n8n.taifoon.dev · sha256 `762248c554dd0607362e20361ec3efe0fda58326d89c2f1c18c525ea48e92e35`
+- nodes: `n8n-nodes-taifoon`, `@taifoon/n8n-nodes-typesafe`, `n8n-nodes-taifoon-devnet-signer`; built-ins manualTrigger v1, code v2, if v2.2
+- credentials: `taifoonRelayerApi`, `taifoonTypeSafeApi`, `taifoonDevnetKeyApi`
+
+| Step | Takes | Emits | Does |
+|---|---|---|---|
+| When clicking ‘Execute workflow’ | — | — | start a grading run |
+| Ready jobs (Base) | — | job.json | GET /v1/judge/ready: jobs on Base that were paid and delivered, and nobody ruled |
+| Pick 4 calibrated | job.json | job.json | keep four whose seller has a calibrated record; one item per job, no state built here |
+| Judge · prepare | job.json | facts.json | POST /v1/judge/compose (prepare) on the job: facts decide first; the pack comes from the job evidence (GRADEABLE labels 1–21) |
+| Hard fail? | facts.json | facts.json | a hard fail is final at prepare (Jev is not asked; nothing to stamp) |
+| Jev · TypeSafe (our credential) | facts.json | answers.json | TypeSafe ask on the prepared text (jevStateOf): every RUBRIC_ASKED answer with its whole distribution |
+| Judge · answers | answers.json | verdict.json | POST /v1/judge/compose (answers): recompose under THRESHOLDS_v1, record decision.v2 and the answers, anchor both |
+| Verdict | verdict.json | verdict.json | the recorded decision as a canonical VERDICT (fromDecision), composed from this run’s receipt |
+| Stamp Grade (unsigned) | verdict.json | verdict.json | POST /v1/assurance/call stampGrade: the unsigned GradeStampRegistry.stamp(subject_id, digest, verdict code, mode 2) |
+| Taifoon Devnet Signer | verdict.json | verdict.json | sign and send the stamp on devnet 36927 (anvil #0) |
+| Verdict + stamp | verdict.json | verdict.json | the same VERDICT with the stamp transaction appended to anchors |
+
+## Batch judge — `batch-judge.json`
+
+A batch of subjects, each as its own prepare → Jev → answers (so every answer is recorded), aggregated and posted to POST /v1/judge/batch.
+
+- source: `tfnbatchjudge001` on n8n.taifoon.dev · sha256 `8e66a8e261e9f1f8052bd0b7658cb2ef5212d8df89b8a5347b56762701f078fd`
+- nodes: `n8n-nodes-taifoon`, `@taifoon/n8n-nodes-typesafe`; built-ins manualTrigger v1, code v2, if v2.2, httpRequest v4.2
+- credentials: `taifoonRelayerApi`, `taifoonTypeSafeApi`
+
+| Step | Takes | Emits | Does |
+|---|---|---|---|
+| Grade a batch | — | — | start a batch (pass { subjects, jobId, threshold } or run the demo set) |
+| Build the batch | — | hire.json | one canonical HIRE per subject (a delivered handshake, or a job on chain); no state is built here |
+| Judge · prepare | hire.json | facts.json | POST /v1/judge/compose (prepare) per subject: the facts decide first; the pack is built from DELIVERY + FACTS; else the exact text Jev reads + prepare_digest |
+| Hard fail? | facts.json | facts.json | branch: a hard fail is final (Jev is not asked) and goes straight to the batch |
+| Jev · TypeSafe (our credential) | facts.json | answers.json | TypeSafe ask on the prepared text (jevStateOf): every RUBRIC_ASKED answer with its whole distribution |
+| Judge · answers | answers.json | verdict.json | POST /v1/judge/compose (answers): recompose under THRESHOLDS_v1, record decision.v2 and the answers (jev.answer.v1), anchor both |
+| Grade + aggregate | facts.json + verdict.json | — | the batch outcome from the recorded verdicts (Conformant / NonConformant / NoGrade counts, fail fraction vs threshold) — a batch record, not a canonical entity |
+| Record the batch to the coordination layer | — | — | POST /v1/judge/batch (relayer key): the batch record, keyed batch:<jobId> |
+
+## Stamp Grade (a recorded verdict → GradeStampRegistry) — `stamp-grade.json`
+
+Takes one recorded decision (by id), maps it to the canonical verdict, and stamps it on the devnet GradeStampRegistry; emits the verdict with the stamp transaction in its anchors.
+
+- source: `tfnstamp00000001` on n8n.taifoon.dev · sha256 `516d9483e3d26e1891dacb8c4493d609340e3c6a3b200784c72864f9cb931ebc`
+- nodes: `n8n-nodes-taifoon`, `n8n-nodes-taifoon-devnet-signer`; built-ins manualTrigger v1, code v2
+- credentials: `taifoonDevnetKeyApi`
+
+| Step | Takes | Emits | Does |
+|---|---|---|---|
+| Start | — | — | start (pass { decision_id } to stamp another verdict) |
+| Verdict | — | verdict.json | GET /v1/judge/decisions/:id → the canonical VERDICT (fromDecision) and its stamp code |
+| Stamp Grade | verdict.json | verdict.json | POST /v1/assurance/call stampGrade: the unsigned GradeStampRegistry.stamp(subject_id, digest, verdict code, mode) |
+| Taifoon Devnet Signer | verdict.json | verdict.json | sign and send the stamp on devnet 36927 (anvil #0) |
+| Verdict + stamp | verdict.json | verdict.json | the same VERDICT with the stamp transaction appended to anchors |

package/workflows/0.2.15/batch-judge.json

@@ -0,0 +1,341 @@
+{
+  "name": "Taifoon — batch judge scores for the coordination layer (TypeSafe/Jev)",
+  "nodes": [
+    {
+      "parameters": {},
+      "id": "trigger",
+      "name": "Grade a batch",
+      "type": "n8n-nodes-base.manualTrigger",
+      "typeVersion": 1,
+      "position": [
+        200,
+        300
+      ],
+      "notes": "in: — → out: — · start a batch (pass { subjects, jobId, threshold } or run the demo set)",
+      "notesInFlow": true
+    },
+    {
+      "parameters": {
+        "jsCode": "// The batch: subjects already delivered (a handshake, or a job read from the chain), one canonical HIRE each. The\n// judge builds every evidence pack itself from DELIVERY + FACTS (schemas/GRADEABLE.md) — nothing here hands Jev a\n// state. Pass { subjects: [{ handshake_id } | { chainId, jobId }], jobId, threshold } on the trigger, or run the demo set.\nconst t = $input.first().json || {};\nconst subjects = Array.isArray(t.subjects) && t.subjects.length ? t.subjects : [\n  { handshake_id: 'hs_97dcf5942e294f7ca28efd0a' }, { handshake_id: 'hs_ec150f74dbe6568982c6c93d' }, { handshake_id: 'hs_c07ccb807a29b94dffb18459' },\n];\nreturn subjects.map((s) => {\n  const hs = typeof s.handshake_id === 'string' && /^hs_[0-9a-f]{24}$/.test(s.handshake_id) ? s.handshake_id : null;\n  const chainId = s.chainId != null ? Number(s.chainId) : hs ? 36927 : 8453;\n  const id = hs ?? String(s.jobId);\n  const job = hs ? { key: 'hs:' + hs, lane: 'handshake', chain_id: chainId, id: hs, contract: null }\n    : { key: 'erc8183:' + chainId + ':' + id, lane: 'erc8183', chain_id: chainId, id, contract: '0x238e541bfefd82238730d00a2208e5497f1832e0' };\n  return { json: {\n    schema: 'taifoon.hire.v1', job, lane: job.lane, tenant: null, buyer: null, seller: null, seller_agent_key: null, seller_ids: [],\n    evaluator: null, hook: null, evaluator_kind: null, task: null, required_skills: [], budget: null, funding: null,\n    created_at: null, deadline: null, handshake_id: hs, offer_nonce: null, state: 'Delivered', ending: null,\n    anchors: [{ kind: 'offchain', store: hs ? 'coordd:coordination_handshakes' : 'observatory', key: id, digest: null, anchored_by: null, what: 'the subject this batch grades' }],\n    source: { kind: hs ? 'handshake' : 'observatory-job', url: hs ? 'https://www.taifoon.io/v1/handshake/' + hs : 'https://www.taifoon.io/v1/judge/evidence/' + chainId + '/' + id, read_at: Math.floor(Date.now() / 1000) },\n  } };\n});"
+      },
+      "id": "e177aad3-f294-4ac5-beae-395993bd7de5",
+      "name": "Build the batch",
+      "type": "n8n-nodes-base.code",
+      "typeVersion": 2,
+      "position": [
+        420,
+        300
+      ],
+      "notes": "in: — → out: hire.json · one canonical HIRE per subject (a delivered handshake, or a job on chain); no state is built here",
+      "notesInFlow": true
+    },
+    {
+      "name": "Judge · prepare",
+      "type": "CUSTOM.taifoon",
+      "typeVersion": 1,
+      "position": [
+        640,
+        300
+      ],
+      "parameters": {
+        "resource": "judge",
+        "operation": "compose",
+        "composeSubject": "={{ $json.lane === 'handshake' ? 'handshake' : 'job' }}",
+        "composeHandshakeId": "={{ $json.handshake_id }}",
+        "composeMode": "prepare",
+        "composeJobId": "={{ $json.job.id }}",
+        "composeChainId": "={{ $json.job.chain_id }}"
+      },
+      "credentials": {
+        "taifoonRelayerApi": {
+          "id": "",
+          "name": "REPLACE: taifoonRelayerApi"
+        }
+      },
+      "id": "62dca0ae-d853-414f-ac98-89592623c7d2",
+      "notes": "in: hire.json → out: facts.json · POST /v1/judge/compose (prepare) per subject: the facts decide first; the pack is built from DELIVERY + FACTS; else the exact text Jev reads + prepare_digest",
+      "notesInFlow": true
+    },
+    {
+      "name": "Hard fail?",
+      "type": "n8n-nodes-base.if",
+      "typeVersion": 2.2,
+      "position": [
+        860,
+        300
+      ],
+      "parameters": {
+        "conditions": {
+          "options": {
+            "caseSensitive": true,
+            "leftValue": "",
+            "typeValidation": "strict",
+            "version": 2
+          },
+          "conditions": [
+            {
+              "id": "h1",
+              "leftValue": "={{ $json.hard_fail === true }}",
+              "rightValue": "",
+              "operator": {
+                "type": "boolean",
+                "operation": "true",
+                "singleValue": true
+              }
+            }
+          ],
+          "combinator": "and"
+        },
+        "options": {}
+      },
+      "id": "65ffd12f-ea5f-4a36-98c4-eea5f9afec86",
+      "notes": "in: facts.json → out: facts.json · branch: a hard fail is final (Jev is not asked) and goes straight to the batch",
+      "notesInFlow": true
+    },
+    {
+      "name": "Jev · TypeSafe (our credential)",
+      "type": "@taifoon/n8n-nodes-typesafe.taifoonTypeSafe",
+      "typeVersion": 1,
+      "position": [
+        1080,
+        420
+      ],
+      "parameters": {
+        "operation": "ask",
+        "connection": "direct",
+        "state": "={{ JSON.stringify($json.jev.state) }}",
+        "questions": {},
+        "questionsJson": "={{ JSON.stringify($json.jev.questions) }}",
+        "routing": "{}",
+        "replyLanguage": "off",
+        "failClosed": true
+      },
+      "credentials": {
+        "taifoonTypeSafeApi": {
+          "id": "",
+          "name": "REPLACE: taifoonTypeSafeApi"
+        }
+      },
+      "notes": "in: facts.json → out: answers.json · TypeSafe ask on the prepared text (jevStateOf): every RUBRIC_ASKED answer with its whole distribution",
+      "id": "f2965735-6523-490f-a551-865edd654baf",
+      "notesInFlow": true
+    },
+    {
+      "name": "Judge · answers",
+      "type": "CUSTOM.taifoon",
+      "typeVersion": 1,
+      "position": [
+        1300,
+        420
+      ],
+      "parameters": {
+        "resource": "judge",
+        "operation": "compose",
+        "composeSubject": "={{ $('Build the batch').item.json.lane === 'handshake' ? 'handshake' : 'job' }}",
+        "composeHandshakeId": "={{ $('Build the batch').item.json.handshake_id }}",
+        "composeMode": "answers",
+        "composeAnswers": "={{ JSON.stringify($json.answers) }}",
+        "composeModel": "={{ $json.model }}",
+        "composePrepareDigest": "={{ $('Judge · prepare').item.json.prepare_digest }}",
+        "composeAnsweredBy": "n8n-typesafe",
+        "composeExecutionId": "={{ $execution.id }}",
+        "composeLatencyMs": "={{ $json.latency_ms }}",
+        "composeJobId": "={{ $('Build the batch').item.json.job.id }}",
+        "composeChainId": "={{ $('Build the batch').item.json.job.chain_id }}"
+      },
+      "credentials": {
+        "taifoonRelayerApi": {
+          "id": "",
+          "name": "REPLACE: taifoonRelayerApi"
+        }
+      },
+      "id": "0ca9f21a-aff6-4fa1-8cc7-c0924dc1cce3",
+      "notes": "in: answers.json → out: verdict.json · POST /v1/judge/compose (answers): recompose under THRESHOLDS_v1, record decision.v2 and the answers (jev.answer.v1), anchor both",
+      "notesInFlow": true
+    },
+    {
+      "parameters": {
+        "jsCode": "// The batch outcome from the recorded verdicts — each item was composed under THRESHOLDS_v1 and recorded (decision.v2\n// + jev.answer.v1) by Judge · answers; a hard fail was final at prepare. complete → Conformant, reject → NonConformant,\n// needs_review → NoGrade (the verdict crate's batch mapping). Runs once per branch that reaches it; the batch record\n// is keyed by jobId, so the last (complete) run is the one that stays.\nconst t = $('Grade a batch').first().json || {};\nconst jobId = t.jobId || 'batch-' + $execution.id;\nconst threshold = typeof t.threshold === 'number' ? t.threshold : 0.2;\nconst prepared = $('Judge · prepare').all().map((i) => i.json);\nlet answered = [];\ntry { answered = $('Judge · answers').all().map((i) => i.json); } catch (e) { answered = []; }\nconst items = [];\nfor (const p of prepared.filter((x) => x.hard_fail === true)) items.push({ item_id: p.subject, verdict: 'NonConformant', composed: 'reject', forced: 'hard_fail', mode: 'Deterministic', decision_id: null, answers_digest: null });\nfor (const a of answered) {\n  const v = a.receipt && a.receipt.verdict;\n  items.push({ item_id: (a.decision && a.decision.subject_id) || null, verdict: v === 'complete' ? 'Conformant' : v === 'reject' ? 'NonConformant' : 'NoGrade', composed: v || null, forced: null, mode: 'Calibrated',\n    decision_id: a.decision ? a.decision.id : null, decision_digest: a.decision ? a.decision.digest : null, answers_digest: a.decision ? a.decision.answers_digest ?? null : null });\n}\nconst conformant = items.filter((i) => i.verdict === 'Conformant').length, nonconformant = items.filter((i) => i.verdict === 'NonConformant').length, nograde = items.length - conformant - nonconformant;\nconst graded = conformant + nonconformant, failFraction = graded === 0 ? 1 : nonconformant / graded;\nreturn [{ json: { jobId, mode: 'Calibrated', total: items.length, conformant, nonconformant, nograde, failFraction, threshold,\n  verdict: graded === 0 ? 'NoGrade' : failFraction <= threshold ? 'Conformant' : 'NonConformant', items } }];"
+      },
+      "id": "64dce113-21e8-454e-8a12-53858bd7a303",
+      "name": "Grade + aggregate",
+      "type": "n8n-nodes-base.code",
+      "typeVersion": 2,
+      "position": [
+        1520,
+        300
+      ],
+      "notes": "in: facts.json | verdict.json → out: — · the batch outcome from the recorded verdicts (Conformant / NonConformant / NoGrade counts, fail fraction vs threshold) — a batch record, not a canonical entity",
+      "notesInFlow": true
+    },
+    {
+      "parameters": {
+        "method": "POST",
+        "url": "https://www.taifoon.io/v1/judge/batch",
+        "authentication": "predefinedCredentialType",
+        "nodeCredentialType": "taifoonRelayerApi",
+        "sendBody": true,
+        "specifyBody": "json",
+        "jsonBody": "={{ JSON.stringify($json) }}",
+        "options": {}
+      },
+      "id": "record",
+      "name": "Record the batch to the coordination layer",
+      "type": "n8n-nodes-base.httpRequest",
+      "typeVersion": 4.2,
+      "position": [
+        1740,
+        300
+      ],
+      "credentials": {
+        "taifoonRelayerApi": {
+          "id": "",
+          "name": "REPLACE: taifoonRelayerApi"
+        }
+      },
+      "notes": "in: — → out: — · POST /v1/judge/batch (relayer key): the batch record, keyed batch:<jobId>",
+      "notesInFlow": true
+    }
+  ],
+  "connections": {
+    "Grade a batch": {
+      "main": [
+        [
+          {
+            "node": "Build the batch",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Build the batch": {
+      "main": [
+        [
+          {
+            "node": "Judge · prepare",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Judge · prepare": {
+      "main": [
+        [
+          {
+            "node": "Hard fail?",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Hard fail?": {
+      "main": [
+        [
+          {
+            "node": "Grade + aggregate",
+            "type": "main",
+            "index": 0
+          }
+        ],
+        [
+          {
+            "node": "Jev · TypeSafe (our credential)",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Jev · TypeSafe (our credential)": {
+      "main": [
+        [
+          {
+            "node": "Judge · answers",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Judge · answers": {
+      "main": [
+        [
+          {
+            "node": "Grade + aggregate",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    },
+    "Grade + aggregate": {
+      "main": [
+        [
+          {
+            "node": "Record the batch to the coordination layer",
+            "type": "main",
+            "index": 0
+          }
+        ]
+      ]
+    }
+  },
+  "settings": {
+    "executionOrder": "v1"
+  },
+  "active": false,
+  "meta": {
+    "taifoon": {
+      "contract": "https://www.taifoon.io/schemas/coordination/v1/",
+      "steps": {
+        "Grade a batch": {
+          "in": null,
+          "out": null,
+          "does": "start a batch (pass { subjects, jobId, threshold } or run the demo set)"
+        },
+        "Build the batch": {
+          "in": null,
+          "out": "https://www.taifoon.io/schemas/coordination/v1/hire.json",
+          "does": "one canonical HIRE per subject (a delivered handshake, or a job on chain); no state is built here"
+        },
+        "Judge · prepare": {
+          "in": "https://www.taifoon.io/schemas/coordination/v1/hire.json",
+          "out": "https://www.taifoon.io/schemas/coordination/v1/facts.json",
+          "does": "POST /v1/judge/compose (prepare) per subject: the facts decide first; the pack is built from DELIVERY + FACTS; else the exact text Jev reads + prepare_digest"
+        },
+        "Hard fail?": {
+          "in": "https://www.taifoon.io/schemas/coordination/v1/facts.json",
+          "out": "https://www.taifoon.io/schemas/coordination/v1/facts.json",
+          "does": "branch: a hard fail is final (Jev is not asked) and goes straight to the batch"
+        },
+        "Jev · TypeSafe (our credential)": {
+          "in": "https://www.taifoon.io/schemas/coordination/v1/facts.json",
+          "out": "https://www.taifoon.io/schemas/coordination/v1/answers.json",
+          "does": "TypeSafe ask on the prepared text (jevStateOf): every RUBRIC_ASKED answer with its whole distribution"
+        },
+        "Judge · answers": {
+          "in": "https://www.taifoon.io/schemas/coordination/v1/answers.json",
+          "out": "https://www.taifoon.io/schemas/coordination/v1/verdict.json",
+          "does": "POST /v1/judge/compose (answers): recompose under THRESHOLDS_v1, record decision.v2 and the answers (jev.answer.v1), anchor both"
+        },
+        "Grade + aggregate": {
+          "in": [
+            "https://www.taifoon.io/schemas/coordination/v1/facts.json",
+            "https://www.taifoon.io/schemas/coordination/v1/verdict.json"
+          ],
+          "out": null,
+          "does": "the batch outcome from the recorded verdicts (Conformant / NonConformant / NoGrade counts, fail fraction vs threshold) — a batch record, not a canonical entity"
+        },
+        "Record the batch to the coordination layer": {
+          "in": null,
+          "out": null,
+          "does": "POST /v1/judge/batch (relayer key): the batch record, keyed batch:<jobId>"
+        }
+      }
+    }
+  },
+  "tags": []
+}