Drive Posterior Desk from your own code

# Every call is the same three things: the base URL, your bearer token, and a
# JSON body. Keep the token in a shell variable.
BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="$SKILLSAFE_TOKEN"   # from https://posterior-desk.skillsafe.ai/tokens.html

call() {                   # call <path> [json-body]
  if [ -n "$2" ]; then
    curl -sS -X POST "$BASE/$1" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d "$2"
  else
    curl -sS "$BASE/$1" -H "Authorization: Bearer $TOKEN"
  fi
}

# Unwrap the envelope: print data, or exit non-zero with the API error code.
data() {
  python3 -c '
import sys, json
env = json.load(sys.stdin)
if not env.get("ok"):
    err = env.get("error") or {}
    raise SystemExit("%s: %s" % (err.get("code"), err.get("message")))
json.dump(env["data"], sys.stdout)
'
}

call me | data
# {"subject_type": "user", "subject_id": "usr_...", "credits": 51234}
#
# No X-App-Slug header. The slug was only ever needed by POST /guest.

import json, os, urllib.error, urllib.request

BASE = "https://api.skillsafe.ai/v1/app-api"
TOKEN = os.environ.get("SKILLSAFE_TOKEN", "YOUR_TOKEN")  # from /tokens.html

LANES = ("diagnose", "respec", "report")


class ApiError(RuntimeError):
    def __init__(self, code, message, details=None):
        super().__init__(f"{code}: {message}")
        self.code, self.message, self.details = code, message, details or {}


def call(path, body=None, headers=None):
    """Returns the unwrapped `data`, or raises ApiError with the API error code.

    Two headers only: Content-Type and Authorization. There is no X-App-Slug -
    the token is already bound to posterior-desk.
    """
    payload = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(
        f"{BASE}/{path}", data=payload, method="POST" if body is not None else "GET")
    req.add_header("Authorization", f"Bearer {TOKEN}")
    if payload is not None:
        req.add_header("Content-Type", "application/json")
    for k, v in (headers or {}).items():
        req.add_header(k, v)
    try:
        with urllib.request.urlopen(req) as res:
            env = json.load(res)
    except urllib.error.HTTPError as exc:          # 4xx and 5xx carry the envelope too
        env = json.loads(exc.read() or b"{}")
    if not env.get("ok"):
        err = env.get("error") or {}
        raise ApiError(err.get("code", "INTERNAL"), err.get("message", "no message"),
                       err.get("details"))
    return env["data"]


print(call("me"))
# {'subject_type': 'user', 'subject_id': 'usr_...', 'credits': 51234}

// Node 18+ or any browser. Paste a token from
// https://posterior-desk.skillsafe.ai/tokens.html, or mint a guest one in step 1.
const BASE = "https://api.skillsafe.ai/v1/app-api";
const TOKEN = "YOUR_TOKEN";

const LANES = ["diagnose", "respec", "report"];

class ApiError extends Error {
  constructor(code, message, details) {
    super(`${code}: ${message}`);
    this.code = code;
    this.details = details ?? {};
  }
}

// call("me") -> GET; call("estimate", input) -> POST with the input object as
// the whole body. Extra headers are for Idempotency-Key on a run.
async function call(path, body, extraHeaders = {}) {
  const res = await fetch(`${BASE}/${path}`, {
    method: body === undefined ? "GET" : "POST",
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      ...(body === undefined ? {} : { "Content-Type": "application/json" }),
      ...extraHeaders,
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const env = await res.json();
  if (!env.ok) throw new ApiError(env.error.code, env.error.message, env.error.details);
  return env.data;
}

console.log(await call("me"));
// { subject_type: 'user', subject_id: 'usr_...', credits: 51234 }
// Two headers, and no X-App-Slug: the token already carries the app.

package main

// Imports used across every Go sample on this page:
// bytes, crypto/sha256, encoding/json, fmt, io, net/http, os, strings, time

const base = "https://api.skillsafe.ai/v1/app-api"

// From https://posterior-desk.skillsafe.ai/tokens.html, or minted in step 1.
var token = func() string {
	if t := os.Getenv("SKILLSAFE_TOKEN"); t != "" {
		return t
	}
	return "YOUR_TOKEN"
}()

var lanes = []string{"diagnose", "respec", "report"}

type apiError struct {
	Code    string          `json:"code"`
	Message string          `json:"message"`
	Details json.RawMessage `json:"details"`
}

func (e *apiError) Error() string { return e.Code + ": " + e.Message }

type envelope struct {
	OK    bool            `json:"ok"`
	Data  json.RawMessage `json:"data"`
	Error *apiError       `json:"error"`
}

// call returns the raw `data` for the caller to unmarshal into its own struct.
// Two headers only - there is no X-App-Slug in this API.
func call(path string, body any, extra map[string]string) (json.RawMessage, error) {
	method := http.MethodGet
	var reader io.Reader
	if body != nil {
		method = http.MethodPost
		raw, err := json.Marshal(body)
		if err != nil {
			return nil, err
		}
		reader = bytes.NewReader(raw)
	}
	req, err := http.NewRequest(method, base+"/"+path, reader)
	if err != nil {
		return nil, err
	}
	req.Header.Set("Authorization", "Bearer "+token)
	if body != nil {
		req.Header.Set("Content-Type", "application/json")
	}
	for k, v := range extra {
		req.Header.Set(k, v)
	}
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()

	var env envelope
	if err := json.NewDecoder(res.Body).Decode(&env); err != nil {
		return nil, err
	}
	if !env.OK {
		if env.Error != nil {
			return nil, env.Error
		}
		return nil, fmt.Errorf("INTERNAL: no error body on HTTP %d", res.StatusCode)
	}
	return env.Data, nil
}

// java.net.http, single file. Imports: java.net.URI, java.net.http.*,
// java.security.MessageDigest, java.util.Map.
public final class PosteriorDesk {
    static final String BASE = "https://api.skillsafe.ai/v1/app-api";

    // From https://posterior-desk.skillsafe.ai/tokens.html, or minted in step 1.
    static String token = System.getenv("SKILLSAFE_TOKEN") == null
        ? "YOUR_TOKEN" : System.getenv("SKILLSAFE_TOKEN");

    static final HttpClient HTTP = HttpClient.newHttpClient();

    static class ApiError extends RuntimeException {
        final String code;
        ApiError(String code, String message) { super(code + ": " + message); this.code = code; }
    }

    /** GET when body is null, POST otherwise. Returns the raw response text.
     *  Two headers: Content-Type and Authorization. There is no X-App-Slug. */
    static String call(String path, String jsonBody, Map<String, String> extra) throws Exception {
        var b = HttpRequest.newBuilder(URI.create(BASE + "/" + path))
            .header("Authorization", "Bearer " + token);
        if (jsonBody == null) {
            b = b.GET();
        } else {
            b = b.header("Content-Type", "application/json")
                 .POST(HttpRequest.BodyPublishers.ofString(jsonBody));
        }
        for (var e : extra.entrySet()) b = b.header(e.getKey(), e.getValue());

        HttpResponse<String> res = HTTP.send(b.build(), HttpResponse.BodyHandlers.ofString());
        String text = res.body();
        // These samples keep the envelope as text and use a real JSON library in
        // production (Jackson, Gson). The only thing to get right is the check:
        // an envelope with "ok":false carries error.code and never data.
        if (text.contains("\"ok\":false")) throw new ApiError("API_ERROR", text);
        return text;
    }
}

require "json"
require "net/http"
require "uri"

BASE = "https://api.skillsafe.ai/v1/app-api"
# From https://posterior-desk.skillsafe.ai/tokens.html, or minted in step 1.
TOKEN = ENV.fetch("SKILLSAFE_TOKEN", "YOUR_TOKEN")

LANES = %w[diagnose respec report].freeze

class ApiError < StandardError
  attr_reader :code, :details
  def initialize(code, message, details = {})
    super("#{code}: #{message}")
    @code = code
    @details = details
  end
end

# call("me") -> GET; call("estimate", input) -> POST with the input object as
# the whole body. No X-App-Slug: the token already carries the app.
def call(path, body = nil, extra = {})
  uri = URI("#{BASE}/#{path}")
  req = body.nil? ? Net::HTTP::Get.new(uri) : Net::HTTP::Post.new(uri)
  req["Authorization"] = "Bearer #{TOKEN}"
  unless body.nil?
    req["Content-Type"] = "application/json"
    req.body = JSON.generate(body)
  end
  extra.each { |k, v| req[k] = v }

  res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
  env = JSON.parse(res.body)
  unless env["ok"]
    err = env["error"] || {}
    raise ApiError.new(err["code"], err["message"], err["details"] || {})
  end
  env["data"]
end

p call("me")
# {"subject_type"=>"user", "subject_id"=>"usr_...", "credits"=>51234}

<?php
const BASE = "https://api.skillsafe.ai/v1/app-api";
// From https://posterior-desk.skillsafe.ai/tokens.html, or minted in step 1.
define("TOKEN", getenv("SKILLSAFE_TOKEN") ?: "YOUR_TOKEN");

const LANES = ["diagnose", "respec", "report"];

class ApiError extends RuntimeException {
    public string $code;
    public array $details;
    public function __construct(string $code, string $message, array $details = []) {
        parent::__construct("$code: $message");
        $this->code = $code;
        $this->details = $details;
    }
}

// call("me") is a GET; call("estimate", $input) POSTs $input as the whole body.
// Two headers only - there is no X-App-Slug in this API.
function call(string $path, ?array $body = null, array $extra = []): array {
    $headers = ["Authorization: Bearer " . TOKEN];
    if ($body !== null) $headers[] = "Content-Type: application/json";
    foreach ($extra as $k => $v) $headers[] = "$k: $v";

    $ch = curl_init(BASE . "/" . $path);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    if ($body !== null) {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }
    $raw = curl_exec($ch);
    curl_close($ch);

    $env = json_decode($raw, true) ?: [];
    if (empty($env["ok"])) {
        $err = $env["error"] ?? [];
        throw new ApiError($err["code"] ?? "INTERNAL", $err["message"] ?? "no message",
                           $err["details"] ?? []);
    }
    return $env["data"];
}

print_r(call("me"));
// Array ( [subject_type] => user [subject_id] => usr_... [credits] => 51234 )

// .NET 8. Usings: System.Net.Http.Json, System.Security.Cryptography,
// System.Text, System.Text.Json.
static class PosteriorDesk
{
    const string Base = "https://api.skillsafe.ai/v1/app-api";

    // From https://posterior-desk.skillsafe.ai/tokens.html, or minted in step 1.
    public static string Token =
        Environment.GetEnvironmentVariable("SKILLSAFE_TOKEN") ?? "YOUR_TOKEN";

    public static readonly string[] Lanes = { "diagnose", "respec", "report" };

    static readonly HttpClient Http = new();

    public class ApiError : Exception
    {
        public string Code { get; }
        public ApiError(string code, string message) : base($"{code}: {message}") => Code = code;
    }

    /// GET when body is null, POST otherwise. Returns the unwrapped `data`.
    /// Two headers: Content-Type and Authorization. There is no X-App-Slug.
    public static async Task<JsonElement> Call(string path, object? body = null,
                                              Dictionary<string, string>? extra = null)
    {
        var req = new HttpRequestMessage(body is null ? HttpMethod.Get : HttpMethod.Post,
                                        $"{Base}/{path}");
        req.Headers.Add("Authorization", $"Bearer {Token}");
        if (body is not null)
            req.Content = new StringContent(JsonSerializer.Serialize(body),
                                            Encoding.UTF8, "application/json");
        foreach (var kv in extra ?? new()) req.Headers.Add(kv.Key, kv.Value);

        var res = await Http.SendAsync(req);
        var env = await res.Content.ReadFromJsonAsync<JsonElement>();
        if (!env.GetProperty("ok").GetBoolean())
        {
            var err = env.GetProperty("error");
            throw new ApiError(err.GetProperty("code").GetString() ?? "INTERNAL",
                               err.GetProperty("message").GetString() ?? "no message");
        }
        return env.GetProperty("data");
    }
}

var me = await PosteriorDesk.Call("me");
Console.WriteLine(me.GetProperty("credits").GetInt32());

# The slug goes in the BODY, not in a header. This is the only call that needs it.
TOKEN=$(curl -sS -X POST "https://api.skillsafe.ai/v1/app-api/guest" \
  -H "Content-Type: application/json" \
  -d '{"slug":"posterior-desk"}' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["data"]["token"])')

echo "${TOKEN:0:12}..."   # sk_guest_...

# Keep the whole object if you want guest_id and expires_at:
curl -sS -X POST "https://api.skillsafe.ai/v1/app-api/guest" \
  -H "Content-Type: application/json" \
  -d '{"slug":"posterior-desk"}' | python3 -m json.tool
# {
#   "ok": true,
#   "data": { "token": "sk_guest_...", "guest_id": "gst_...",
#             "expires_at": "2026-08-27T09:14:02Z" }
# }
#
# 201 Created, not 200. A guest token can /me and /estimate; a metered /run
# needs a personal token from https://posterior-desk.skillsafe.ai/tokens.html.

import datetime, json, urllib.request

BASE = "https://api.skillsafe.ai/v1/app-api"
SLUG = "posterior-desk"          # the ONLY place the slug appears in this API


def mint_guest():
    """POST /guest -> 201 with {token, guest_id, expires_at}. No auth header."""
    req = urllib.request.Request(
        f"{BASE}/guest", data=json.dumps({"slug": SLUG}).encode(), method="POST")
    req.add_header("Content-Type", "application/json")
    with urllib.request.urlopen(req) as res:
        assert res.status == 201, f"expected 201, got {res.status}"
        env = json.load(res)
    if not env.get("ok"):
        err = env.get("error") or {}
        raise RuntimeError(f"{err.get('code')}: {err.get('message')}")
    return env["data"]


tok = mint_guest()
print(tok["token"][:12], tok["guest_id"], tok["expires_at"])
# sk_guest_ gst_... 2026-08-27T09:14:02Z

# expires_at is real. A worker that runs for days re-mints rather than caching:
expiry = datetime.datetime.fromisoformat(tok["expires_at"].replace("Z", "+00:00"))
if expiry - datetime.datetime.now(datetime.timezone.utc) < datetime.timedelta(minutes=5):
    tok = mint_guest()

TOKEN = tok["token"]     # feed this to call() from step 0

const BASE = "https://api.skillsafe.ai/v1/app-api";
const SLUG = "posterior-desk";     // the ONLY place the slug appears

// POST /guest answers 201 Created. No Authorization header on this one call.
async function mintGuest() {
  const res = await fetch(`${BASE}/guest`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ slug: SLUG }),
  });
  // Test for 2xx, not for 200: this endpoint returns 201 and a strict
  // `res.status === 200` check reads a successful mint as a failure.
  const env = await res.json();
  if (!env.ok) throw new Error(`${env.error.code}: ${env.error.message}`);
  return env.data;               // { token, guest_id, expires_at }
}

const guest = await mintGuest();
console.log(guest.guest_id, guest.expires_at);

// Re-mint when it is close to lapsing rather than caching forever.
function expiring(g, marginMs = 5 * 60 * 1000) {
  return Date.parse(g.expires_at) - Date.now() < marginMs;
}

let TOKEN = guest.token;
if (expiring(guest)) TOKEN = (await mintGuest()).token;

// POST /guest is the one call with no Authorization header and the one call
// that answers 201. The slug goes in the body.
type guestToken struct {
	Token     string `json:"token"`
	GuestID   string `json:"guest_id"`
	ExpiresAt string `json:"expires_at"`
}

func mintGuest() (*guestToken, error) {
	body, _ := json.Marshal(map[string]string{"slug": "posterior-desk"})
	req, err := http.NewRequest(http.MethodPost, base+"/guest", bytes.NewReader(body))
	if err != nil {
		return nil, err
	}
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	if res.StatusCode/100 != 2 {
		return nil, fmt.Errorf("guest mint: HTTP %d", res.StatusCode)
	}

	var env struct {
		OK    bool       `json:"ok"`
		Data  guestToken `json:"data"`
		Error *apiError  `json:"error"`
	}
	if err := json.NewDecoder(res.Body).Decode(&env); err != nil {
		return nil, err
	}
	if !env.OK {
		return nil, env.Error
	}
	return &env.Data, nil
}

func mustToken() string {
	g, err := mintGuest()
	if err != nil {
		panic(err)
	}
	// expires_at is real; a long-lived worker re-mints rather than caching.
	if t, err := time.Parse(time.RFC3339, g.ExpiresAt); err == nil {
		if time.Until(t) < 5*time.Minute {
			if g2, err := mintGuest(); err == nil {
				g = g2
			}
		}
	}
	return g.Token
}

// POST /guest: no Authorization header, slug in the body, 201 on success.
static String mintGuest() throws Exception {
    HttpRequest req = HttpRequest.newBuilder(URI.create(BASE + "/guest"))
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString("{\"slug\":\"posterior-desk\"}"))
        .build();

    HttpResponse<String> res = HTTP.send(req, HttpResponse.BodyHandlers.ofString());
    // 201 Created, not 200. Accept any 2xx.
    if (res.statusCode() / 100 != 2)
        throw new ApiError("HTTP_" + res.statusCode(), res.body());

    String body = res.body();
    // Replace with Jackson in production; this keeps the sample dependency-free.
    int i = body.indexOf("\"token\":\"") + 9;
    token = body.substring(i, body.indexOf('"', i));
    return token;
}

public static void main(String[] args) throws Exception {
    if (System.getenv("SKILLSAFE_TOKEN") == null) mintGuest();
    System.out.println(call("me", null, Map.of()));
    // {"ok":true,"data":{"subject_type":"guest","subject_id":"gst_...","credits":1200}}
    //
    // A guest can /me and /estimate. A metered /run needs a personal token from
    // https://posterior-desk.skillsafe.ai/tokens.html
}

# POST /guest: no Authorization header, the slug in the body, 201 on success.
def mint_guest
  uri = URI("#{BASE}/guest")
  req = Net::HTTP::Post.new(uri)
  req["Content-Type"] = "application/json"
  req.body = JSON.generate({ slug: "posterior-desk" })

  res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
  # 201 Created, not 200 - check the class, not the exact code.
  raise "guest mint: HTTP #{res.code}" unless res.is_a?(Net::HTTPSuccess)

  env = JSON.parse(res.body)
  raise ApiError.new(env.dig("error", "code"), env.dig("error", "message")) unless env["ok"]
  env["data"]      # { "token" => ..., "guest_id" => ..., "expires_at" => ... }
end

guest = mint_guest
puts "#{guest['guest_id']} expires #{guest['expires_at']}"

# Re-mint near expiry rather than caching a token for days.
guest = mint_guest if Time.parse(guest["expires_at"]) - Time.now < 300
TOKEN_FROM_GUEST = guest["token"]

<?php
// POST /guest: no Authorization header, the slug in the body, 201 on success.
function mint_guest(): array {
    $ch = curl_init(BASE . "/guest");
    curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["slug" => "posterior-desk"]));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $raw = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    // 201 Created, not 200. Accept any 2xx.
    if (intdiv($status, 100) !== 2) throw new RuntimeException("guest mint: HTTP $status");

    $env = json_decode($raw, true) ?: [];
    if (empty($env["ok"])) {
        $err = $env["error"] ?? [];
        throw new ApiError($err["code"] ?? "INTERNAL", $err["message"] ?? "no message");
    }
    return $env["data"];   // ["token" => ..., "guest_id" => ..., "expires_at" => ...]
}

$guest = mint_guest();
printf("%s expires %s\n", $guest["guest_id"], $guest["expires_at"]);

// Re-mint near expiry.
if (strtotime($guest["expires_at"]) - time() < 300) $guest = mint_guest();

// POST /guest: no Authorization header, slug in the body, 201 on success.
static async Task<JsonElement> MintGuest()
{
    var res = await new HttpClient().PostAsync(
        "https://api.skillsafe.ai/v1/app-api/guest",
        new StringContent("{\"slug\":\"posterior-desk\"}", Encoding.UTF8, "application/json"));

    // 201 Created, not 200 - IsSuccessStatusCode covers both.
    if (!res.IsSuccessStatusCode)
        throw new Exception($"guest mint: HTTP {(int)res.StatusCode}");

    var env = await res.Content.ReadFromJsonAsync<JsonElement>();
    if (!env.GetProperty("ok").GetBoolean())
        throw new PosteriorDesk.ApiError(
            env.GetProperty("error").GetProperty("code").GetString() ?? "INTERNAL",
            env.GetProperty("error").GetProperty("message").GetString() ?? "");
    return env.GetProperty("data");
}

var guest = await MintGuest();
PosteriorDesk.Token = guest.GetProperty("token").GetString()!;
Console.WriteLine(guest.GetProperty("expires_at").GetString());

// Re-mint near expiry rather than caching for days.
if (DateTimeOffset.Parse(guest.GetProperty("expires_at").GetString()!) - DateTimeOffset.UtcNow
        < TimeSpan.FromMinutes(5))
    PosteriorDesk.Token = (await MintGuest()).GetProperty("token").GetString()!;

call me
# {"ok":true,"data":{"subject_type":"user","subject_id":"usr_...","credits":51234}}

# Branch on subject_type. There is no is_guest field to test, and no user_id -
# the id is subject_id for both kinds of subject.
call me | python3 -c '
import sys, json
me = json.load(sys.stdin)["data"]
kind = me["subject_type"]                       # "guest" or "user"
print(kind, me["subject_id"], me["credits"], "credits")
if kind == "guest":
    print("guest: /me and /estimate only - a metered run needs a personal token")
'

me = call("me")
print(me)
# {'subject_type': 'guest', 'subject_id': 'gst_...', 'credits': 1200}

# Three fields. No user_id, no is_guest, no email, no plan.
assert set(me) == {"subject_type", "subject_id", "credits"}, me

if me["subject_type"] == "guest":
    # A guest can price a run but not start one: /run answers 403 FORBIDDEN.
    print("guest session:", me["subject_id"], "- sign in before a metered run")
else:
    print("signed in as", me["subject_id"])

# Keep the balance for the step-3 comparison rather than calling /me twice.
credits = me["credits"]

const me = await call("me");
console.log(me);
// { subject_type: 'guest', subject_id: 'gst_...', credits: 1200 }

// The two mistakes this shape invites, written out so they are easy to avoid:
//   me.user_id   -> undefined, always. The id is me.subject_id.
//   if (me.is_guest) -> never true, for anybody. Branch on subject_type.
if (me.subject_type === "guest") {
  console.warn("guest token: /me and /estimate only, /run will 403");
}

const credits = me.credits;   // compare against min_credits from step 3

type meResponse struct {
	SubjectType string `json:"subject_type"` // "guest" | "user"
	SubjectID   string `json:"subject_id"`   // NOT user_id
	Credits     int64  `json:"credits"`
}

func whoAmI() (*meResponse, error) {
	raw, err := call("me", nil, nil)
	if err != nil {
		return nil, err
	}
	var me meResponse
	if err := json.Unmarshal(raw, &me); err != nil {
		return nil, err
	}
	return &me, nil
}

func main() {
	token = mustToken()
	me, err := whoAmI()
	if err != nil {
		panic(err)
	}
	fmt.Printf("%s %s: %d credits\n", me.SubjectType, me.SubjectID, me.Credits)

	// There is no IsGuest bool in the payload to unmarshal - the string is the flag.
	if me.SubjectType == "guest" {
		fmt.Println("guest: /run will answer 403 FORBIDDEN; sign in for a metered lane")
	}
}

String meJson = call("me", null, Map.of());
System.out.println(meJson);
// {"ok":true,"data":{"subject_type":"guest","subject_id":"gst_...","credits":1200}}

// Three fields only: subject_type, subject_id, credits. No user_id, no is_guest.
boolean isGuest = meJson.contains("\"subject_type\":\"guest\"");
if (isGuest) {
    System.out.println("guest token: /me and /estimate only, /run will 403");
}

// With Jackson:
//   var me = new ObjectMapper().readTree(meJson).get("data");
//   long credits = me.get("credits").asLong();
//   String kind  = me.get("subject_type").asText();   // "guest" | "user"

me = call("me")
p me
# {"subject_type"=>"guest", "subject_id"=>"gst_...", "credits"=>1200}

# Exactly three keys. Anything you reach for beyond them is nil.
raise "unexpected /me shape: #{me.keys}" unless
  me.keys.sort == %w[credits subject_id subject_type]

case me["subject_type"]
when "guest" then warn "guest token: a metered /run will answer 403 FORBIDDEN"
when "user"  then puts "signed in as #{me['subject_id']}"
end

credits = me["credits"]   # compare against min_credits from step 3

<?php
$me = call("me");
print_r($me);
// Array ( [subject_type] => guest [subject_id] => gst_... [credits] => 1200 )

// No user_id and no is_guest. $me["is_guest"] is null, which is falsy, which
// reads as "a real user" for a guest token. Branch on the string.
if ($me["subject_type"] === "guest") {
    fwrite(STDERR, "guest token: /me and /estimate only, /run will 403\n");
}

$credits = $me["credits"];   // compare against min_credits from step 3

var me = await PosteriorDesk.Call("me");
var kind = me.GetProperty("subject_type").GetString();   // "guest" | "user"
var id = me.GetProperty("subject_id").GetString();       // NOT user_id
var credits = me.GetProperty("credits").GetInt64();

Console.WriteLine($"{kind} {id}: {credits} credits");

// GetProperty throws on a missing key, which is the behaviour you want here:
// there is no is_guest and no user_id to reach for by accident.
if (kind == "guest")
    Console.Error.WriteLine("guest token: /run will answer 403 FORBIDDEN");

# The fit report and the summary table as shell variables, so the JSON stays
# readable. The table is TAB separated - printf, not echo, so \t survives.
FIT=$(cat <<'EOF'
Model: eight_schools_centred
Sampler: NUTS (PyMC)
Chains: 4 | Draws: 1000 | Tune: 500
target_accept: 0.8 | max_treedepth: 10
Wall time: 412 s
Observations: 8
Free parameters: 10 (mu, tau, theta[8])
Convergence: all chains converged, r_hat < 1.01
Warnings:
  There were 216 divergences after tuning. Increase `target_accept` or reparameterize.
  38 of 4000 iterations saturated the maximum tree depth of 10.
Model spec:
  mu    = pm.Normal('mu', 0, 5)
  tau   = pm.HalfCauchy('tau', 5)
  theta = pm.Normal('theta', mu=mu, sigma=tau, shape=8)   # centred
  y_obs = pm.Normal('y', mu=theta, sigma=sigma_known, observed=y)
EOF
)

TABLE=$(printf 'param\tmean\tsd\thdi_lo\thdi_hi\tmcse_mean\tmcse_sd\tess_bulk\tess_tail\tr_hat\n'
printf 'mu\t8.017\t5.086\t-0.958\t17.951\t0.24\t0.17\t452\t653\t1.01\n'
printf 'tau\t3.574\t3.281\t0.000\t9.190\t0.42\t0.30\t61\t92\t1.31\n'
printf 'theta[3]\t7.113\t5.512\t-2.900\t18.020\t0.31\t0.22\t318\t402\t1.08\n')

# Build the body with python3 so the tabs and newlines are escaped correctly.
# NOTE the shape: the input object IS the body. No "input" wrapper.
INPUT=$(FIT="$FIT" TABLE="$TABLE" python3 -c '
import json, os
print(json.dumps({
  "task": "diagnose",
  "fit": os.environ["FIT"],
  "table": os.environ["TABLE"],
  "goal": "publication",
  "stage": "first_fit",
  "notes": "reviewer 2 asked about the funnel",
}))')

call estimate "$INPUT" | data
# {"model":"gpt-5.6-terra","model_alias":"gpt-terra","markup_bps":1000,
#  "hold_credits":2140,"min_credits":260,"sponsor_enabled":false}
#
# Free, but authenticated: without the step-1 token this is a 401, not a price.

FIT = """Model: eight_schools_centred
Sampler: NUTS (PyMC)
Chains: 4 | Draws: 1000 | Tune: 500
target_accept: 0.8 | max_treedepth: 10
Wall time: 412 s
Observations: 8
Free parameters: 10 (mu, tau, theta[8])
Convergence: all chains converged, r_hat < 1.01
Warnings:
  There were 216 divergences after tuning. Increase `target_accept` or reparameterize.
  38 of 4000 iterations saturated the maximum tree depth of 10.
Model spec:
  mu    = pm.Normal('mu', 0, 5)
  tau   = pm.HalfCauchy('tau', 5)
  theta = pm.Normal('theta', mu=mu, sigma=tau, shape=8)   # centred
  y_obs = pm.Normal('y', mu=theta, sigma=sigma_known, observed=y)
"""

# Tab separated, with the ten canonical columns. If you have an InferenceData
# object to hand, `az.summary(idata).to_csv(sep="\t")` produces this directly;
# the header tokens are matched whole, so n_eff, ess, ESS bulk all land in
# ess_bulk and any hdi_NN% pair becomes hdi_lo / hdi_hi.
TABLE = "\t".join(["param", "mean", "sd", "hdi_lo", "hdi_hi", "mcse_mean",
                   "mcse_sd", "ess_bulk", "ess_tail", "r_hat"]) + "\n" + "\n".join([
    "mu\t8.017\t5.086\t-0.958\t17.951\t0.24\t0.17\t452\t653\t1.01",
    "tau\t3.574\t3.281\t0.000\t9.190\t0.42\t0.30\t61\t92\t1.31",
    "theta[3]\t7.113\t5.512\t-2.900\t18.020\t0.31\t0.22\t318\t402\t1.08",
])

# The input object IS the body. Never {"input": {...}}.
INPUT = {
    "task": "diagnose",
    "fit": FIT,
    "table": TABLE,
    "goal": "publication",
    "stage": "first_fit",
    "notes": "reviewer 2 asked about the funnel",
}

est = call("estimate", INPUT)
print(est)
# {'model': 'gpt-5.6-terra', 'model_alias': 'gpt-terra', 'markup_bps': 1000,
#  'hold_credits': 2140, 'min_credits': 260, 'sponsor_enabled': False}

assert est["model_alias"] == "gpt-terra", est          # wrong app or wrong slug
if not est["sponsor_enabled"] and credits < est["min_credits"]:
    raise SystemExit(f"need {est['min_credits']} credits, have {credits}")

const FIT = [
  "Model: eight_schools_centred",
  "Sampler: NUTS (PyMC)",
  "Chains: 4 | Draws: 1000 | Tune: 500",
  "target_accept: 0.8 | max_treedepth: 10",
  "Wall time: 412 s",
  "Observations: 8",
  "Free parameters: 10 (mu, tau, theta[8])",
  "Convergence: all chains converged, r_hat < 1.01",
  "Warnings:",
  "  There were 216 divergences after tuning. Increase `target_accept` or reparameterize.",
  "  38 of 4000 iterations saturated the maximum tree depth of 10.",
  "Model spec:",
  "  mu    = pm.Normal('mu', 0, 5)",
  "  tau   = pm.HalfCauchy('tau', 5)",
  "  theta = pm.Normal('theta', mu=mu, sigma=tau, shape=8)   // centred",
  "  y_obs = pm.Normal('y', mu=theta, sigma=sigma_known, observed=y)",
].join("\n");

// Ten canonical columns, tab separated. Send what your tooling prints; the
// parser accepts to_string(), to_csv(), markdown pipes and Stan-style columns
// and normalises them itself.
const TABLE = [
  "param\tmean\tsd\thdi_lo\thdi_hi\tmcse_mean\tmcse_sd\tess_bulk\tess_tail\tr_hat",
  "mu\t8.017\t5.086\t-0.958\t17.951\t0.24\t0.17\t452\t653\t1.01",
  "tau\t3.574\t3.281\t0.000\t9.190\t0.42\t0.30\t61\t92\t1.31",
  "theta[3]\t7.113\t5.512\t-2.900\t18.020\t0.31\t0.22\t318\t402\t1.08",
].join("\n");

// The input object IS the body. Never { input: {...} }.
const INPUT = {
  task: "diagnose",
  fit: FIT,
  table: TABLE,
  goal: "publication",
  stage: "first_fit",
  notes: "reviewer 2 asked about the funnel",
};

const est = await call("estimate", INPUT);
console.log(est);
// { model: 'gpt-5.6-terra', model_alias: 'gpt-terra', markup_bps: 1000,
//   hold_credits: 2140, min_credits: 260, sponsor_enabled: false }

if (est.model_alias !== "gpt-terra") throw new Error("not this app's model");
if (!est.sponsor_enabled && credits < est.min_credits) {
  throw new Error(`need ${est.min_credits} credits, have ${credits}`);
}

// The flat input object. Every field is top-level; there is no wrapper struct.
type runInput struct {
	Task     string         `json:"task"`
	Fit      string         `json:"fit"`
	Table    string         `json:"table,omitempty"`
	Goal     string         `json:"goal,omitempty"`
	Stage    string         `json:"stage,omitempty"`
	Notes    string         `json:"notes,omitempty"`
	Prescan  map[string]any `json:"prescan_facts,omitempty"`
}

type estimate struct {
	Model          string `json:"model"`
	ModelAlias     string `json:"model_alias"`
	MarkupBps      int    `json:"markup_bps"`
	HoldCredits    int64  `json:"hold_credits"`
	MinCredits     int64  `json:"min_credits"`
	SponsorEnabled bool   `json:"sponsor_enabled"`
}

const fitReport = `Model: eight_schools_centred
Sampler: NUTS (PyMC)
Chains: 4 | Draws: 1000 | Tune: 500
target_accept: 0.8 | max_treedepth: 10
Observations: 8
Free parameters: 10 (mu, tau, theta[8])
Convergence: all chains converged, r_hat < 1.01
Warnings:
  There were 216 divergences after tuning. Increase target_accept or reparameterize.
  38 of 4000 iterations saturated the maximum tree depth of 10.
Model spec: theta = pm.Normal('theta', mu=mu, sigma=tau, shape=8)   // centred`

// Tabs matter: these are the ten canonical columns.
var summaryTable = strings.Join([]string{
	"param\tmean\tsd\thdi_lo\thdi_hi\tmcse_mean\tmcse_sd\tess_bulk\tess_tail\tr_hat",
	"mu\t8.017\t5.086\t-0.958\t17.951\t0.24\t0.17\t452\t653\t1.01",
	"tau\t3.574\t3.281\t0.000\t9.190\t0.42\t0.30\t61\t92\t1.31",
	"theta[3]\t7.113\t5.512\t-2.900\t18.020\t0.31\t0.22\t318\t402\t1.08",
}, "\n")

func priceIt(in runInput) (*estimate, error) {
	raw, err := call("estimate", in, nil) // free, but authenticated
	if err != nil {
		return nil, err
	}
	var est estimate
	if err := json.Unmarshal(raw, &est); err != nil {
		return nil, err
	}
	if est.ModelAlias != "gpt-terra" {
		return nil, fmt.Errorf("unexpected model alias %q - wrong app?", est.ModelAlias)
	}
	return &est, nil
}

func example() {
	in := runInput{
		Task:  "diagnose",
		Fit:   fitReport,
		Table: summaryTable,
		Goal:  "publication",
		Stage: "first_fit",
		Notes: "reviewer 2 asked about the funnel",
	}
	est, err := priceIt(in)
	if err != nil {
		panic(err)
	}
	fmt.Printf("hold %d, min %d, markup %d bps\n",
		est.HoldCredits, est.MinCredits, est.MarkupBps)
}

// The fit report and the table as text blocks. \t in a text block is a real tab.
static final String FIT = """
    Model: eight_schools_centred
    Sampler: NUTS (PyMC)
    Chains: 4 | Draws: 1000 | Tune: 500
    target_accept: 0.8 | max_treedepth: 10
    Observations: 8
    Free parameters: 10 (mu, tau, theta[8])
    Convergence: all chains converged, r_hat < 1.01
    Warnings:
      There were 216 divergences after tuning. Increase target_accept or reparameterize.
      38 of 4000 iterations saturated the maximum tree depth of 10.
    Model spec: theta = pm.Normal('theta', mu=mu, sigma=tau, shape=8)   // centred
    """;

static final String TABLE = String.join("\n",
    "param\tmean\tsd\thdi_lo\thdi_hi\tmcse_mean\tmcse_sd\tess_bulk\tess_tail\tr_hat",
    "mu\t8.017\t5.086\t-0.958\t17.951\t0.24\t0.17\t452\t653\t1.01",
    "tau\t3.574\t3.281\t0.000\t9.190\t0.42\t0.30\t61\t92\t1.31",
    "theta[3]\t7.113\t5.512\t-2.900\t18.020\t0.31\t0.22\t318\t402\t1.08");

/** Build the flat input object. In production use Jackson's ObjectNode; this
 *  keeps the sample dependency-free. The body IS this object - no wrapper. */
static String inputJson(String task) {
    return "{"
        + "\"task\":" + q(task) + ","
        + "\"fit\":" + q(FIT) + ","
        + "\"table\":" + q(TABLE) + ","
        + "\"goal\":\"publication\","
        + "\"stage\":\"first_fit\","
        + "\"notes\":\"reviewer 2 asked about the funnel\""
        + "}";
}

/** Minimal JSON string escaper: quotes, backslashes, tabs and newlines. */
static String q(String s) {
    StringBuilder b = new StringBuilder("\"");
    for (char c : s.toCharArray()) {
        switch (c) {
            case '"'  -> b.append("\\\"");
            case '\\' -> b.append("\\\\");
            case '\n' -> b.append("\\n");
            case '\t' -> b.append("\\t");
            case '\r' -> b.append("\\r");
            default   -> b.append(c);
        }
    }
    return b.append('"').toString();
}

// Free, but authenticated: this line after step 1, never before it.
String est = call("estimate", inputJson("diagnose"), Map.of());
System.out.println(est);
// {"ok":true,"data":{"model":"gpt-5.6-terra","model_alias":"gpt-terra",
//  "markup_bps":1000,"hold_credits":2140,"min_credits":260,"sponsor_enabled":false}}
if (!est.contains("\"model_alias\":\"gpt-terra\"")) throw new IllegalStateException(est);

FIT = <<~TEXT
  Model: eight_schools_centred
  Sampler: NUTS (PyMC)
  Chains: 4 | Draws: 1000 | Tune: 500
  target_accept: 0.8 | max_treedepth: 10
  Observations: 8
  Free parameters: 10 (mu, tau, theta[8])
  Convergence: all chains converged, r_hat < 1.01
  Warnings:
    There were 216 divergences after tuning. Increase target_accept or reparameterize.
    38 of 4000 iterations saturated the maximum tree depth of 10.
  Model spec: theta = pm.Normal('theta', mu=mu, sigma=tau, shape=8)   # centred
TEXT

# Ten canonical columns, tab separated.
TABLE = [
  %w[param mean sd hdi_lo hdi_hi mcse_mean mcse_sd ess_bulk ess_tail r_hat].join("\t"),
  "mu\t8.017\t5.086\t-0.958\t17.951\t0.24\t0.17\t452\t653\t1.01",
  "tau\t3.574\t3.281\t0.000\t9.190\t0.42\t0.30\t61\t92\t1.31",
  "theta[3]\t7.113\t5.512\t-2.900\t18.020\t0.31\t0.22\t318\t402\t1.08",
].join("\n")

# The input object IS the body. Never { input: {...} }.
def build_input(task)
  {
    task: task,
    fit: FIT,
    table: TABLE,
    goal: "publication",
    stage: "first_fit",
    notes: "reviewer 2 asked about the funnel",
  }
end

est = call("estimate", build_input("diagnose"))
p est
# {"model"=>"gpt-5.6-terra", "model_alias"=>"gpt-terra", "markup_bps"=>1000,
#  "hold_credits"=>2140, "min_credits"=>260, "sponsor_enabled"=>false}

raise "wrong app: #{est['model_alias']}" unless est["model_alias"] == "gpt-terra"
if !est["sponsor_enabled"] && credits < est["min_credits"]
  abort "need #{est['min_credits']} credits, have #{credits}"
end

<?php
$FIT = <<<'TEXT'
Model: eight_schools_centred
Sampler: NUTS (PyMC)
Chains: 4 | Draws: 1000 | Tune: 500
target_accept: 0.8 | max_treedepth: 10
Observations: 8
Free parameters: 10 (mu, tau, theta[8])
Convergence: all chains converged, r_hat < 1.01
Warnings:
  There were 216 divergences after tuning. Increase target_accept or reparameterize.
  38 of 4000 iterations saturated the maximum tree depth of 10.
Model spec: theta = pm.Normal('theta', mu=mu, sigma=tau, shape=8)   # centred
TEXT;

// Ten canonical columns. Note the double-quoted strings: "\t" is a real tab,
// '\t' is a backslash and a t, and the second one silently breaks the parse.
$TABLE = implode("\n", [
    implode("\t", ["param", "mean", "sd", "hdi_lo", "hdi_hi", "mcse_mean",
                   "mcse_sd", "ess_bulk", "ess_tail", "r_hat"]),
    "mu\t8.017\t5.086\t-0.958\t17.951\t0.24\t0.17\t452\t653\t1.01",
    "tau\t3.574\t3.281\t0.000\t9.190\t0.42\t0.30\t61\t92\t1.31",
    "theta[3]\t7.113\t5.512\t-2.900\t18.020\t0.31\t0.22\t318\t402\t1.08",
]);

// The input object IS the body. Never ["input" => [...]].
function build_input(string $task, string $fit, string $table): array {
    return [
        "task"  => $task,
        "fit"   => $fit,
        "table" => $table,
        "goal"  => "publication",
        "stage" => "first_fit",
        "notes" => "reviewer 2 asked about the funnel",
    ];
}

$est = call("estimate", build_input("diagnose", $FIT, $TABLE));
print_r($est);
// [model] => gpt-5.6-terra [model_alias] => gpt-terra [markup_bps] => 1000
// [hold_credits] => 2140 [min_credits] => 260 [sponsor_enabled] =>

if ($est["model_alias"] !== "gpt-terra") throw new RuntimeException("wrong app");
if (!$est["sponsor_enabled"] && $credits < $est["min_credits"]) {
    exit("need {$est['min_credits']} credits, have $credits\n");
}

const string Fit = """
    Model: eight_schools_centred
    Sampler: NUTS (PyMC)
    Chains: 4 | Draws: 1000 | Tune: 500
    target_accept: 0.8 | max_treedepth: 10
    Observations: 8
    Free parameters: 10 (mu, tau, theta[8])
    Convergence: all chains converged, r_hat < 1.01
    Warnings:
      There were 216 divergences after tuning. Increase target_accept or reparameterize.
      38 of 4000 iterations saturated the maximum tree depth of 10.
    Model spec: theta = pm.Normal('theta', mu=mu, sigma=tau, shape=8)   // centred
    """;

// Ten canonical columns, tab separated.
static readonly string Table = string.Join("\n", new[]
{
    "param\tmean\tsd\thdi_lo\thdi_hi\tmcse_mean\tmcse_sd\tess_bulk\tess_tail\tr_hat",
    "mu\t8.017\t5.086\t-0.958\t17.951\t0.24\t0.17\t452\t653\t1.01",
    "tau\t3.574\t3.281\t0.000\t9.190\t0.42\t0.30\t61\t92\t1.31",
    "theta[3]\t7.113\t5.512\t-2.900\t18.020\t0.31\t0.22\t318\t402\t1.08",
});

// The input object IS the body - an anonymous object serialises flat.
static object BuildInput(string task) => new
{
    task,
    fit = Fit,
    table = Table,
    goal = "publication",
    stage = "first_fit",
    notes = "reviewer 2 asked about the funnel",
};

var est = await PosteriorDesk.Call("estimate", BuildInput("diagnose"));
Console.WriteLine(est);
// {"model":"gpt-5.6-terra","model_alias":"gpt-terra","markup_bps":1000,
//  "hold_credits":2140,"min_credits":260,"sponsor_enabled":false}

if (est.GetProperty("model_alias").GetString() != "gpt-terra")
    throw new InvalidOperationException("wrong app or wrong slug");

var min = est.GetProperty("min_credits").GetInt64();
if (!est.GetProperty("sponsor_enabled").GetBoolean() && credits < min)
    throw new InvalidOperationException($"need {min} credits, have {credits}");

# Always send an Idempotency-Key derived from the input, with the lane in it.
# A retried request with the same key returns the SAME job instead of billing twice.
KEY="posterior-desk:$(printf '%s' "$INPUT" | shasum -a 256 | cut -c1-16):diagnose:a1"

JOB=$(curl -sS -X POST "$BASE/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d "$INPUT" | python3 -c 'import sys,json; print(json.load(sys.stdin)["data"]["job_id"])')

echo "job $JOB"

# Poll on a fixed one-second interval, with a ceiling.
for i in $(seq 1 120); do
  RES=$(curl -sS "$BASE/jobs/$JOB" -H "Authorization: Bearer $TOKEN")
  STATUS=$(printf '%s' "$RES" | python3 -c 'import sys,json; print(json.load(sys.stdin)["data"]["status"])')
  case "$STATUS" in
    succeeded|failed) break ;;
  esac
  sleep 1
done

# Pull the review out of data.output.output and run the assertions.
printf '%s' "$RES" | TASK=diagnose python3 -c '
import json, os, sys
job = json.load(sys.stdin)["data"]
if job["status"] != "succeeded":
    raise SystemExit("job %s: %s" % (job["status"], job.get("error")))
if job.get("truncated"):
    raise SystemExit("truncated: retry, do not repair")

raw = job["output"]["output"]
review = json.loads(raw[raw.index("{"):raw.rindex("}") + 1])

assert review["lane"] == os.environ["TASK"], (review["lane"], "wrapped input?")
worst = {f["severity"] for f in review["findings"]}
if review["verdict"] == "not_supported": assert "blocking" in worst
if review["verdict"] == "sound":         assert not (worst - {"info"})

print(review["verdict"], "|", review["headline"])
print("charged", job["charged_credits"], "credits")
'

import hashlib, time

LANE_BODY_KEYS = {
    "diagnose": {"sampler_review", "convergence", "geometry", "efficiency",
                 "precision", "trust_scope"},
    "respec":   {"root_cause", "model_changes", "prior_changes", "sampler_changes",
                 "run_plan", "cost_note", "if_it_does_not_work"},
    "report":   {"methods_paragraph", "diagnostics_table", "results_wording",
                 "limitations", "reproducibility", "open_items"},
}
VERDICTS = {"sound", "sound_with_caveats", "revise", "not_supported"}
SEVERITIES = {"blocking", "high", "medium", "low", "info"}
AREAS = {"sampler", "convergence", "efficiency", "precision", "geometry",
         "interval", "model", "comparison", "reporting"}


def idem_key(body, attempt=1):
    """posterior-desk:<hash>:<lane>:a<attempt> - the lane is part of the key
    because it is part of the body."""
    blob = json.dumps(body, sort_keys=True).encode()
    return (f"posterior-desk:{hashlib.sha256(blob).hexdigest()[:16]}"
            f":{body.get('task', 'auto')}:a{attempt}")


def run(body, attempt=1, timeout=180):
    job = call("run", body, {"Idempotency-Key": idem_key(body, attempt)})
    job_id = job["job_id"]
    deadline = time.time() + timeout
    while time.time() < deadline:
        j = call(f"jobs/{job_id}")
        if j["status"] in ("succeeded", "failed"):
            return j
        time.sleep(1)
    raise TimeoutError(job_id)


def review_of(job, expected_task):
    """Unwrap data.output.output and assert everything worth asserting."""
    if job["status"] != "succeeded":
        raise RuntimeError(f"job {job['status']}: {job.get('error')}")
    if job.get("truncated"):
        raise RuntimeError("truncated reply: retry with a retry_note, do not repair")

    raw = job["output"]["output"]
    review = json.loads(raw[raw.index("{"):raw.rindex("}") + 1])

    # 1. the lane you asked for (a mismatch is what a wrapped input looks like)
    assert review["lane"] == expected_task, (review["lane"], expected_task)
    # 2. the body belongs to that lane, and to no other
    keys = set(review["body"])
    assert keys <= LANE_BODY_KEYS[review["lane"]], keys - LANE_BODY_KEYS[review["lane"]]
    # 3. enums in range
    assert review["verdict"] in VERDICTS, review["verdict"]
    for f in review["findings"]:
        assert f["severity"] in SEVERITIES and f["area"] in AREAS, f
    # 4. the verdict matches the worst severity
    worst = {f["severity"] for f in review["findings"]}
    if review["verdict"] == "not_supported":
        assert "blocking" in worst, "not_supported with no blocking finding"
    if review["verdict"] == "revise":
        assert worst & {"blocking", "high"}, "revise with nothing above medium"
    if review["verdict"] == "sound":
        assert not (worst - {"info"}), f"sound with {worst}"
    return review


job = run(INPUT)
review = review_of(job, INPUT["task"])

# 5. the reconciliation contract: one entry per prescan uid, exactly
sent = {f["uid"] for f in INPUT.get("prescan_facts", {}).get("flags", [])}
got = [r["flag_uid"] for r in review["reconciliation"]]
assert sorted(got) == sorted(sent), (set(got) ^ sent)
assert len(got) == len(set(got)), "a uid was reconciled twice"

# 6. trust_scope partitions, in the diagnose lane
if review["lane"] == "diagnose":
    ts = review["body"]["trust_scope"]
    both = set(ts["reportable"]) & set(ts["not_reportable"])
    assert not both, f"quantity on both sides of trust_scope: {both}"

# 7. notes came back as context_notes
if INPUT.get("notes"):
    assert review["context_notes"], "notes were sent and not read"

print(review["verdict"], "|", review["headline"])
print("charged", job["charged_credits"], "credits")

import { createHash } from "node:crypto";   // in a browser: SubtleCrypto

const LANE_BODY_KEYS = {
  diagnose: ["sampler_review", "convergence", "geometry", "efficiency",
             "precision", "trust_scope"],
  respec: ["root_cause", "model_changes", "prior_changes", "sampler_changes",
           "run_plan", "cost_note", "if_it_does_not_work"],
  report: ["methods_paragraph", "diagnostics_table", "results_wording",
           "limitations", "reproducibility", "open_items"],
};
const VERDICTS = ["sound", "sound_with_caveats", "revise", "not_supported"];
const SEVERITIES = ["blocking", "high", "medium", "low", "info"];
const AREAS = ["sampler", "convergence", "efficiency", "precision", "geometry",
               "interval", "model", "comparison", "reporting"];

// posterior-desk:<hash>:<lane>:a<attempt> - bump the attempt when the input changes.
function idemKey(body, attempt = 1) {
  const hash = createHash("sha256")
    .update(JSON.stringify(body, Object.keys(body).sort()))
    .digest("hex").slice(0, 16);
  return `posterior-desk:${hash}:${body.task ?? "auto"}:a${attempt}`;
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function run(body, attempt = 1, timeoutMs = 180_000) {
  const { job_id } = await call("run", body, { "Idempotency-Key": idemKey(body, attempt) });
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const job = await call(`jobs/${job_id}`);
    if (job.status === "succeeded" || job.status === "failed") return job;
    await sleep(1000);
  }
  throw new Error(`timed out polling ${job_id}`);
}

function reviewOf(job, expectedTask, sentUids = []) {
  if (job.status !== "succeeded") throw new Error(`job ${job.status}: ${job.error}`);
  if (job.truncated) throw new Error("truncated reply: retry, do not repair");

  const raw = job.output.output;
  const review = JSON.parse(raw.slice(raw.indexOf("{"), raw.lastIndexOf("}") + 1));

  // The lane you asked for. A mismatch is what a wrapped input looks like.
  if (review.lane !== expectedTask) throw new Error(`lane ${review.lane} != ${expectedTask}`);

  // The body belongs to that lane and to no other.
  const allowed = LANE_BODY_KEYS[review.lane];
  const stray = Object.keys(review.body).filter((k) => !allowed.includes(k));
  if (stray.length) throw new Error(`stray body keys: ${stray}`);

  // Enums in range.
  if (!VERDICTS.includes(review.verdict)) throw new Error(review.verdict);
  for (const f of review.findings) {
    if (!SEVERITIES.includes(f.severity) || !AREAS.includes(f.area)) throw new Error(f.id);
  }

  // The verdict matches the worst severity.
  const worst = new Set(review.findings.map((f) => f.severity));
  if (review.verdict === "not_supported" && !worst.has("blocking"))
    throw new Error("not_supported with no blocking finding");
  if (review.verdict === "sound" && [...worst].some((s) => s !== "info"))
    throw new Error(`sound with ${[...worst]}`);

  // The reconciliation contract, both directions.
  const got = review.reconciliation.map((r) => r.flag_uid).sort();
  const want = [...sentUids].sort();
  if (got.join() !== want.join()) throw new Error(`reconciliation drift: ${got} vs ${want}`);

  // trust_scope partitions.
  if (review.lane === "diagnose") {
    const { reportable, not_reportable } = review.body.trust_scope;
    const both = reportable.filter((q) => not_reportable.includes(q));
    if (both.length) throw new Error(`on both sides of trust_scope: ${both}`);
  }
  return review;
}

const job = await run(INPUT);
const review = reviewOf(job, INPUT.task,
  (INPUT.prescan_facts?.flags ?? []).map((f) => f.uid));
console.log(review.verdict, "|", review.headline);
console.log("charged", job.charged_credits, "credits");

type job struct {
	JobID          string `json:"job_id"`
	Status         string `json:"status"`
	Truncated      bool   `json:"truncated"`
	ChargedCredits int64  `json:"charged_credits"`
	Error          string `json:"error"`
	Output         struct {
		Output string `json:"output"` // the review, as a JSON string
	} `json:"output"`
}

type finding struct {
	ID       string `json:"id"`
	Severity string `json:"severity"`
	Area     string `json:"area"`
	Title    string `json:"title"`
	Detail   string `json:"detail"`
	Evidence string `json:"evidence"`
	Line     *int   `json:"line"`
	Fix      string `json:"fix"`
}

type review struct {
	Lane           string            `json:"lane"`
	Title          string            `json:"title"`
	Verdict        string            `json:"verdict"`
	Headline       string            `json:"headline"`
	Summary        string            `json:"summary"`
	Body           json.RawMessage   `json:"body"` // lane-specific; decode per lane
	Findings       []finding         `json:"findings"`
	Reconciliation []struct {
		FlagUID string `json:"flag_uid"`
		Status  string `json:"status"`
		Note    string `json:"note"`
	} `json:"reconciliation"`
	Caveats      []map[string]string `json:"caveats"`
	ContextNotes []map[string]string `json:"context_notes"`
	Unassessable []map[string]string `json:"unassessable"`
}

// posterior-desk:<hash>:<lane>:a<attempt>
func idemKey(in runInput, attempt int) string {
	blob, _ := json.Marshal(in)
	sum := sha256.Sum256(blob)
	lane := in.Task
	if lane == "" {
		lane = "auto"
	}
	return fmt.Sprintf("posterior-desk:%x:%s:a%d", sum[:8], lane, attempt)
}

func runAndPoll(in runInput, attempt int) (*job, error) {
	raw, err := call("run", in, map[string]string{"Idempotency-Key": idemKey(in, attempt)})
	if err != nil {
		return nil, err
	}
	var started job
	if err := json.Unmarshal(raw, &started); err != nil {
		return nil, err
	}

	deadline := time.Now().Add(3 * time.Minute)
	for time.Now().Before(deadline) {
		raw, err := call("jobs/"+started.JobID, nil, nil)
		if err != nil {
			return nil, err
		}
		var j job
		if err := json.Unmarshal(raw, &j); err != nil {
			return nil, err
		}
		if j.Status == "succeeded" || j.Status == "failed" {
			return &j, nil
		}
		time.Sleep(time.Second)
	}
	return nil, fmt.Errorf("timed out polling %s", started.JobID)
}

// Slice from the first brace to the last, then decode and assert.
func reviewOf(j *job, expectedTask string, sentUIDs []string) (*review, error) {
	if j.Status != "succeeded" {
		return nil, fmt.Errorf("job %s: %s", j.Status, j.Error)
	}
	if j.Truncated {
		return nil, fmt.Errorf("truncated reply: retry, do not repair")
	}
	raw := j.Output.Output
	start, end := strings.Index(raw, "{"), strings.LastIndex(raw, "}")
	if start < 0 || end < start {
		return nil, fmt.Errorf("no JSON object in output")
	}

	var r review
	if err := json.Unmarshal([]byte(raw[start:end+1]), &r); err != nil {
		return nil, err
	}
	if r.Lane != expectedTask {
		return nil, fmt.Errorf("lane %q != task %q - wrapped input?", r.Lane, expectedTask)
	}

	worst := map[string]bool{}
	for _, f := range r.Findings {
		worst[f.Severity] = true
	}
	if r.Verdict == "not_supported" && !worst["blocking"] {
		return nil, fmt.Errorf("not_supported with no blocking finding")
	}
	if r.Verdict == "sound" && (worst["blocking"] || worst["high"] ||
		worst["medium"] || worst["low"]) {
		return nil, fmt.Errorf("sound verdict with findings above info")
	}
	if len(r.Reconciliation) != len(sentUIDs) {
		return nil, fmt.Errorf("sent %d prescan uids, got %d reconciliation entries",
			len(sentUIDs), len(r.Reconciliation))
	}
	return &r, nil
}

/** posterior-desk:<hash>:<lane>:a<attempt> - the lane is part of the body, so
 *  it is part of the key. */
static String idemKey(String inputJson, String lane, int attempt) throws Exception {
    var md = MessageDigest.getInstance("SHA-256");
    byte[] d = md.digest(inputJson.getBytes("UTF-8"));
    var hex = new StringBuilder();
    for (int i = 0; i < 8; i++) hex.append(String.format("%02x", d[i]));
    return "posterior-desk:" + hex + ":" + lane + ":a" + attempt;
}

static String runAndPoll(String inputJson, String lane) throws Exception {
    String started = call("run", inputJson,
        Map.of("Idempotency-Key", idemKey(inputJson, lane, 1)));

    int i = started.indexOf("\"job_id\":\"") + 10;
    String jobId = started.substring(i, started.indexOf('"', i));

    long deadline = System.currentTimeMillis() + 180_000L;
    while (System.currentTimeMillis() < deadline) {
        String job = call("jobs/" + jobId, null, Map.of());
        if (job.contains("\"status\":\"succeeded\"")) return job;
        if (job.contains("\"status\":\"failed\"")) throw new ApiError("JOB_FAILED", job);
        Thread.sleep(1000);
    }
    throw new IllegalStateException("timed out polling " + jobId);
}

// The review is a JSON string at data.output.output. Slice from the first brace
// to the last before parsing - it costs nothing and survives small variations.
static String sliceObject(String s) {
    return s.substring(s.indexOf('{'), s.lastIndexOf('}') + 1);
}

public static void check(String jobJson, String expectedLane) {
    if (jobJson.contains("\"truncated\":true"))
        throw new IllegalStateException("truncated reply: retry, do not repair");
    // With Jackson:
    //   var job = mapper.readTree(jobJson).get("data");
    //   var review = mapper.readTree(sliceObject(job.get("output").get("output").asText()));
    //   if (!review.get("lane").asText().equals(expectedLane))
    //       throw new IllegalStateException("lane mismatch - wrapped input?");
    //   var worst = new HashSet<String>();
    //   review.get("findings").forEach(f -> worst.add(f.get("severity").asText()));
    //   var verdict = review.get("verdict").asText();
    //   if (verdict.equals("not_supported") && !worst.contains("blocking"))
    //       throw new IllegalStateException("not_supported with no blocking finding");
    //   if (verdict.equals("sound") && !worst.stream().allMatch("info"::equals))
    //       throw new IllegalStateException("sound with findings above info");
    //   if (review.get("reconciliation").size() != sentUids.size())
    //       throw new IllegalStateException("reconciliation does not cover the prescan");
}

String job = runAndPoll(inputJson("diagnose"), "diagnose");
check(job, "diagnose");
System.out.println(job);

require "digest"

LANE_BODY_KEYS = {
  "diagnose" => %w[sampler_review convergence geometry efficiency precision trust_scope],
  "respec"   => %w[root_cause model_changes prior_changes sampler_changes run_plan
                   cost_note if_it_does_not_work],
  "report"   => %w[methods_paragraph diagnostics_table results_wording limitations
                   reproducibility open_items],
}.freeze
VERDICTS = %w[sound sound_with_caveats revise not_supported].freeze

# posterior-desk:<hash>:<lane>:a<attempt>
def idem_key(body, attempt = 1)
  hash = Digest::SHA256.hexdigest(JSON.generate(body.sort.to_h))[0, 16]
  "posterior-desk:#{hash}:#{body[:task] || 'auto'}:a#{attempt}"
end

def run(body, attempt = 1, timeout = 180)
  started = call("run", body, { "Idempotency-Key" => idem_key(body, attempt) })
  job_id = started["job_id"]
  deadline = Time.now + timeout

  while Time.now < deadline
    job = call("jobs/#{job_id}")
    return job if %w[succeeded failed].include?(job["status"])
    sleep 1
  end
  raise "timed out polling #{job_id}"
end

def review_of(job, expected_task, sent_uids = [])
  raise "job #{job['status']}: #{job['error']}" unless job["status"] == "succeeded"
  raise "truncated reply: retry, do not repair" if job["truncated"]

  raw = job.dig("output", "output")
  review = JSON.parse(raw[raw.index("{")..raw.rindex("}")])

  # The lane you asked for. A mismatch is what a wrapped input looks like.
  raise "lane #{review['lane']} != #{expected_task}" unless review["lane"] == expected_task

  # The body belongs to that lane and to no other.
  stray = review["body"].keys - LANE_BODY_KEYS.fetch(review["lane"])
  raise "stray body keys: #{stray}" unless stray.empty?

  raise "bad verdict #{review['verdict']}" unless VERDICTS.include?(review["verdict"])

  worst = review["findings"].map { |f| f["severity"] }.uniq
  raise "not_supported with no blocking finding" if
    review["verdict"] == "not_supported" && !worst.include?("blocking")
  raise "sound with #{worst}" if
    review["verdict"] == "sound" && !(worst - ["info"]).empty?

  got = review["reconciliation"].map { |r| r["flag_uid"] }
  raise "reconciliation drift" unless got.sort == sent_uids.sort
  raise "a uid was reconciled twice" unless got.uniq.size == got.size

  if review["lane"] == "diagnose"
    ts = review["body"]["trust_scope"]
    both = ts["reportable"] & ts["not_reportable"]
    raise "on both sides of trust_scope: #{both}" unless both.empty?
  end
  review
end

body = build_input("diagnose")
job = run(body)
review = review_of(job, body[:task],
                   (body.dig(:prescan_facts, :flags) || []).map { |f| f[:uid] })
puts "#{review['verdict']} | #{review['headline']}"
puts "charged #{job['charged_credits']} credits"

<?php
const LANE_BODY_KEYS = [
    "diagnose" => ["sampler_review", "convergence", "geometry", "efficiency",
                   "precision", "trust_scope"],
    "respec"   => ["root_cause", "model_changes", "prior_changes", "sampler_changes",
                   "run_plan", "cost_note", "if_it_does_not_work"],
    "report"   => ["methods_paragraph", "diagnostics_table", "results_wording",
                   "limitations", "reproducibility", "open_items"],
];
const VERDICTS = ["sound", "sound_with_caveats", "revise", "not_supported"];

// posterior-desk:<hash>:<lane>:a<attempt>
function idem_key(array $body, int $attempt = 1): string {
    $hash = substr(hash("sha256", json_encode($body)), 0, 16);
    $lane = $body["task"] ?? "auto";
    return "posterior-desk:$hash:$lane:a$attempt";
}

function run_job(array $body, int $attempt = 1, int $timeout = 180): array {
    $started = call("run", $body, ["Idempotency-Key" => idem_key($body, $attempt)]);
    $jobId = $started["job_id"];
    $deadline = time() + $timeout;

    while (time() < $deadline) {
        $job = call("jobs/$jobId");
        if (in_array($job["status"], ["succeeded", "failed"], true)) return $job;
        sleep(1);
    }
    throw new RuntimeException("timed out polling $jobId");
}

function review_of(array $job, string $expectedTask, array $sentUids = []): array {
    if ($job["status"] !== "succeeded")
        throw new RuntimeException("job {$job['status']}: " . ($job["error"] ?? ""));
    if (!empty($job["truncated"]))
        throw new RuntimeException("truncated reply: retry, do not repair");

    $raw = $job["output"]["output"];
    $slice = substr($raw, strpos($raw, "{"), strrpos($raw, "}") - strpos($raw, "{") + 1);
    $review = json_decode($slice, true);

    // The lane you asked for. A mismatch is what a wrapped input looks like.
    if ($review["lane"] !== $expectedTask)
        throw new RuntimeException("lane {$review['lane']} != $expectedTask");

    $stray = array_diff(array_keys($review["body"]), LANE_BODY_KEYS[$review["lane"]]);
    if ($stray) throw new RuntimeException("stray body keys: " . implode(",", $stray));

    if (!in_array($review["verdict"], VERDICTS, true))
        throw new RuntimeException("bad verdict {$review['verdict']}");

    $worst = array_unique(array_column($review["findings"], "severity"));
    if ($review["verdict"] === "not_supported" && !in_array("blocking", $worst, true))
        throw new RuntimeException("not_supported with no blocking finding");
    if ($review["verdict"] === "sound" && array_diff($worst, ["info"]))
        throw new RuntimeException("sound with findings above info");

    $got = array_column($review["reconciliation"], "flag_uid");
    sort($got); sort($sentUids);
    if ($got !== $sentUids) throw new RuntimeException("reconciliation drift");

    if ($review["lane"] === "diagnose") {
        $ts = $review["body"]["trust_scope"];
        $both = array_intersect($ts["reportable"], $ts["not_reportable"]);
        if ($both) throw new RuntimeException("both sides of trust_scope");
    }
    return $review;
}

$body = build_input("diagnose", $FIT, $TABLE);
$job = run_job($body);
$review = review_of($job, $body["task"]);
echo $review["verdict"], " | ", $review["headline"], "\n";
echo "charged ", $job["charged_credits"], " credits\n";

static readonly Dictionary<string, string[]> LaneBodyKeys = new()
{
    ["diagnose"] = new[] { "sampler_review", "convergence", "geometry", "efficiency",
                           "precision", "trust_scope" },
    ["respec"]   = new[] { "root_cause", "model_changes", "prior_changes",
                           "sampler_changes", "run_plan", "cost_note",
                           "if_it_does_not_work" },
    ["report"]   = new[] { "methods_paragraph", "diagnostics_table", "results_wording",
                           "limitations", "reproducibility", "open_items" },
};
static readonly string[] Verdicts =
    { "sound", "sound_with_caveats", "revise", "not_supported" };

// posterior-desk:<hash>:<lane>:a<attempt>
static string IdemKey(object body, string lane, int attempt = 1)
{
    var json = JsonSerializer.Serialize(body);
    var hash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(json)))
                      .ToLowerInvariant()[..16];
    return $"posterior-desk:{hash}:{lane}:a{attempt}";
}

static async Task<JsonElement> Run(object body, string lane, int attempt = 1)
{
    var started = await PosteriorDesk.Call("run", body,
        new() { ["Idempotency-Key"] = IdemKey(body, lane, attempt) });
    var jobId = started.GetProperty("job_id").GetString();

    var deadline = DateTime.UtcNow.AddMinutes(3);
    while (DateTime.UtcNow < deadline)
    {
        var job = await PosteriorDesk.Call($"jobs/{jobId}");
        var status = job.GetProperty("status").GetString();
        if (status is "succeeded" or "failed") return job;
        await Task.Delay(1000);
    }
    throw new TimeoutException($"timed out polling {jobId}");
}

static JsonElement ReviewOf(JsonElement job, string expectedTask, string[] sentUids)
{
    if (job.GetProperty("status").GetString() != "succeeded")
        throw new InvalidOperationException("job did not succeed");
    if (job.TryGetProperty("truncated", out var t) && t.GetBoolean())
        throw new InvalidOperationException("truncated reply: retry, do not repair");

    var raw = job.GetProperty("output").GetProperty("output").GetString()!;
    var slice = raw[raw.IndexOf('{')..(raw.LastIndexOf('}') + 1)];
    var review = JsonDocument.Parse(slice).RootElement;

    // The lane you asked for. A mismatch is what a wrapped input looks like.
    var lane = review.GetProperty("lane").GetString()!;
    if (lane != expectedTask)
        throw new InvalidOperationException($"lane {lane} != {expectedTask}");

    foreach (var key in review.GetProperty("body").EnumerateObject())
        if (!LaneBodyKeys[lane].Contains(key.Name))
            throw new InvalidOperationException($"stray body key {key.Name}");

    var verdict = review.GetProperty("verdict").GetString()!;
    if (!Verdicts.Contains(verdict))
        throw new InvalidOperationException($"bad verdict {verdict}");

    var worst = review.GetProperty("findings").EnumerateArray()
        .Select(f => f.GetProperty("severity").GetString()).ToHashSet();
    if (verdict == "not_supported" && !worst.Contains("blocking"))
        throw new InvalidOperationException("not_supported with no blocking finding");
    if (verdict == "sound" && worst.Any(s => s != "info"))
        throw new InvalidOperationException("sound with findings above info");

    var got = review.GetProperty("reconciliation").EnumerateArray()
        .Select(r => r.GetProperty("flag_uid").GetString()!).OrderBy(s => s);
    if (!got.SequenceEqual(sentUids.OrderBy(s => s)))
        throw new InvalidOperationException("reconciliation drift");

    return review;
}

var job = await Run(BuildInput("diagnose"), "diagnose");
var review = ReviewOf(job, "diagnose", Array.Empty<string>());
Console.WriteLine($"{review.GetProperty("verdict")} | {review.GetProperty("headline")}");
Console.WriteLine($"charged {job.GetProperty("charged_credits")} credits");

# Same body, same Idempotency-Key, one extra header.
curl -sSN -X POST "$BASE/run-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "Idempotency-Key: $KEY" \
  -d "$INPUT"

# event: job
# data: {"job_id":"job_..."}
#
# event: delta
# data: {"text":"{\"lane\":\"diagnose\",\"title\":\"eight_schools_centred"}
#
# event: delta
# data: {"text":"\",\"verdict\":\"not_supported\",\"headline\":\"r_hat 1.31"}
#
# event: done
# data: {"status":"succeeded","charged_credits":915,"truncated":false}

# -N disables curl's buffering; without it the deltas arrive in one lump at the
# end and the stream was pointless. Reassemble the review from the delta texts:
curl -sSN -X POST "$BASE/run-stream" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" -H "Idempotency-Key: $KEY" -d "$INPUT" \
| python3 -c '
import json, sys
text = ""
for line in sys.stdin:
    if not line.startswith("data:"):
        continue
    payload = json.loads(line[5:].strip() or "{}")
    if "text" in payload:
        text += payload["text"]
        for key in ("findings", "reconciliation", "trust_scope", "summary"):
            if ("\"%s\"" % key) in text:
                print("...", key, file=sys.stderr)
    elif payload.get("status"):
        if payload.get("truncated"):
            raise SystemExit("truncated: retry, do not repair")
review = json.loads(text[text.index("{"):text.rindex("}") + 1])
print(review["verdict"], "|", review["headline"])
'

def stream(body, attempt=1, on_progress=None):
    """POST /run-stream. Yields nothing; returns the parsed review.

    Events are separated by a blank line, so accumulate and split on \\n\\n
    rather than assuming one data: line per event.
    """
    payload = json.dumps(body).encode()
    req = urllib.request.Request(f"{BASE}/run-stream", data=payload, method="POST")
    req.add_header("Authorization", f"Bearer {TOKEN}")
    req.add_header("Content-Type", "application/json")
    req.add_header("Accept", "text/event-stream")
    req.add_header("Idempotency-Key", idem_key(body, attempt))

    with urllib.request.urlopen(req) as res:
        ctype = res.headers.get("Content-Type", "")
        # An idempotent replay of a key that already ran answers with plain JSON.
        if "text/event-stream" not in ctype:
            env = json.load(res)
            job = env["data"]
            return review_of(job, body["task"])

        text, buf, done = "", "", None
        for chunk in res:
            buf += chunk.decode("utf-8", "replace")
            while "\n\n" in buf:
                raw, buf = buf.split("\n\n", 1)
                name, data = "message", ""
                for line in raw.splitlines():
                    if line.startswith("event:"):
                        name = line[6:].strip()
                    elif line.startswith("data:"):
                        data += line[5:].strip()
                if not data:
                    continue
                ev = json.loads(data)
                if name == "delta":
                    text += ev.get("text", "")
                    if on_progress:
                        on_progress(text)
                elif name == "done":
                    done = ev
                elif name == "error":
                    raise ApiError(ev.get("code", "INTERNAL"), ev.get("message", ""))

    if done and done.get("truncated"):
        raise RuntimeError("truncated reply: retry, do not repair")
    return json.loads(text[text.index("{"):text.rindex("}") + 1])


# Progress without parsing partial JSON: watch for key names arriving.
STAGES = ["findings", "reconciliation", "trust_scope", "summary"]


def progress(text):
    for key in STAGES:
        if f'"{key}"' in text:
            print("reached", key)
            STAGES.remove(key)
            break


review = stream(INPUT, on_progress=progress)
print(review["verdict"], "|", review["headline"])

async function stream(body, { attempt = 1, onProgress } = {}) {
  const res = await fetch(`${BASE}/run-stream`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
      Accept: "text/event-stream",
      "Idempotency-Key": idemKey(body, attempt),
    },
    body: JSON.stringify(body),
  });

  // An idempotent replay of a key that already ran answers with plain JSON,
  // not a stream. Check before you start reading lines.
  const ctype = res.headers.get("content-type") ?? "";
  if (!ctype.includes("text/event-stream")) {
    const env = await res.json();
    if (!env.ok) throw new ApiError(env.error.code, env.error.message);
    return reviewOf(env.data, body.task);
  }

  const reader = res.body.getReader();
  const dec = new TextDecoder();
  let buf = "", text = "", done = null;

  for (;;) {
    const { value, done: eof } = await reader.read();
    if (eof) break;
    buf += dec.decode(value, { stream: true });

    // Events are separated by a blank line - split on \n\n, not on \n.
    let i;
    while ((i = buf.indexOf("\n\n")) >= 0) {
      const raw = buf.slice(0, i);
      buf = buf.slice(i + 2);

      let name = "message", data = "";
      for (const line of raw.split("\n")) {
        if (line.startsWith("event:")) name = line.slice(6).trim();
        else if (line.startsWith("data:")) data += line.slice(5).trim();
      }
      if (!data) continue;
      const ev = JSON.parse(data);

      if (name === "delta") {
        text += ev.text ?? "";
        onProgress?.(text);
      } else if (name === "done") {
        done = ev;
      } else if (name === "error") {
        throw new ApiError(ev.code ?? "INTERNAL", ev.message ?? "stream error");
      }
    }
  }

  if (done?.truncated) throw new Error("truncated reply: retry, do not repair");
  return JSON.parse(text.slice(text.indexOf("{"), text.lastIndexOf("}") + 1));
}

// Progress without parsing partial JSON.
const stages = ["findings", "reconciliation", "trust_scope", "summary"];
const review = await stream(INPUT, {
  onProgress(text) {
    while (stages.length && text.includes(`"${stages[0]}"`)) {
      console.log("reached", stages.shift());
    }
  },
});
console.log(review.verdict, "|", review.headline);

// POST /run-stream: the same body and key, plus Accept: text/event-stream.
func streamRun(in runInput, attempt int) (*review, error) {
	raw, _ := json.Marshal(in)
	req, err := http.NewRequest(http.MethodPost, base+"/run-stream", bytes.NewReader(raw))
	if err != nil {
		return nil, err
	}
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Accept", "text/event-stream")
	req.Header.Set("Idempotency-Key", idemKey(in, attempt))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()

	// An idempotent replay answers with plain JSON, not a stream.
	if !strings.Contains(res.Header.Get("Content-Type"), "text/event-stream") {
		var env struct {
			OK   bool `json:"ok"`
			Data job  `json:"data"`
		}
		if err := json.NewDecoder(res.Body).Decode(&env); err != nil {
			return nil, err
		}
		return reviewOf(&env.Data, in.Task, nil)
	}

	body, err := io.ReadAll(res.Body) // or read incrementally for progress
	if err != nil {
		return nil, err
	}

	var text strings.Builder
	truncated := false
	// Events are separated by a blank line.
	for _, block := range strings.Split(string(body), "\n\n") {
		name, data := "message", ""
		for _, line := range strings.Split(block, "\n") {
			switch {
			case strings.HasPrefix(line, "event:"):
				name = strings.TrimSpace(line[6:])
			case strings.HasPrefix(line, "data:"):
				data += strings.TrimSpace(line[5:])
			}
		}
		if data == "" {
			continue
		}
		switch name {
		case "delta":
			var ev struct{ Text string `json:"text"` }
			if err := json.Unmarshal([]byte(data), &ev); err == nil {
				text.WriteString(ev.Text)
			}
		case "done":
			var ev struct{ Truncated bool `json:"truncated"` }
			if err := json.Unmarshal([]byte(data), &ev); err == nil {
				truncated = ev.Truncated
			}
		case "error":
			return nil, fmt.Errorf("stream error: %s", data)
		}
	}
	if truncated {
		return nil, fmt.Errorf("truncated reply: retry, do not repair")
	}

	s := text.String()
	start, end := strings.Index(s, "{"), strings.LastIndex(s, "}")
	if start < 0 || end < start {
		return nil, fmt.Errorf("no JSON object in the accumulated deltas")
	}
	var r review
	if err := json.Unmarshal([]byte(s[start:end+1]), &r); err != nil {
		return nil, err
	}
	return &r, nil
}

/** POST /run-stream with Accept: text/event-stream. Reads lines, accumulates
 *  the delta texts, and returns the review JSON. */
static String streamRun(String inputJson, String lane) throws Exception {
    HttpRequest req = HttpRequest.newBuilder(URI.create(BASE + "/run-stream"))
        .header("Authorization", "Bearer " + token)
        .header("Content-Type", "application/json")
        .header("Accept", "text/event-stream")
        .header("Idempotency-Key", idemKey(inputJson, lane, 1))
        .POST(HttpRequest.BodyPublishers.ofString(inputJson))
        .build();

    HttpResponse<java.util.stream.Stream<String>> res =
        HTTP.send(req, HttpResponse.BodyHandlers.ofLines());

    // An idempotent replay of a key that already ran answers with plain JSON.
    String ctype = res.headers().firstValue("content-type").orElse("");
    if (!ctype.contains("text/event-stream")) {
        return res.body().reduce("", String::concat);
    }

    StringBuilder text = new StringBuilder();
    boolean[] truncated = { false };
    java.util.Set<String> seen = new java.util.HashSet<>();

    res.body().forEach(line -> {
        if (!line.startsWith("data:")) return;         // event: lines and blanks
        String data = line.substring(5).trim();
        if (data.isEmpty()) return;

        if (data.contains("\"text\"")) {
            // Pull the delta text out; use Jackson in production.
            int i = data.indexOf("\"text\":\"") + 8;
            String piece = data.substring(i, data.lastIndexOf('"'));
            text.append(piece.replace("\\n", "\n").replace("\\\"", "\""));

            for (String key : new String[]{"findings", "reconciliation",
                                           "trust_scope", "summary"}) {
                if (text.indexOf("\"" + key + "\"") >= 0 && seen.add(key)) {
                    System.out.println("reached " + key);
                }
            }
        } else if (data.contains("\"truncated\":true")) {
            truncated[0] = true;
        }
    });

    if (truncated[0]) throw new IllegalStateException("truncated: retry, do not repair");
    String s = text.toString();
    return s.substring(s.indexOf('{'), s.lastIndexOf('}') + 1);
}

String reviewJson = streamRun(inputJson("diagnose"), "diagnose");
System.out.println(reviewJson.substring(0, Math.min(200, reviewJson.length())));

# POST /run-stream: same body, same key, plus Accept: text/event-stream.
def stream(body, attempt = 1)
  uri = URI("#{BASE}/run-stream")
  req = Net::HTTP::Post.new(uri)
  req["Authorization"] = "Bearer #{TOKEN}"
  req["Content-Type"] = "application/json"
  req["Accept"] = "text/event-stream"
  req["Idempotency-Key"] = idem_key(body, attempt)
  req.body = JSON.generate(body)

  text = ""
  truncated = false
  seen = []

  Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(req) do |res|
      # An idempotent replay answers with plain JSON rather than a stream.
      unless res["Content-Type"].to_s.include?("text/event-stream")
        env = JSON.parse(res.body)
        return review_of(env["data"], body[:task])
      end

      buf = ""
      res.read_body do |chunk|
        buf << chunk
        # Events are separated by a blank line.
        while (i = buf.index("\n\n"))
          block = buf.slice!(0, i + 2)
          name = block[/^event:\s*(.+)$/, 1] || "message"
          data = block.scan(/^data:\s*(.*)$/).flatten.join
          next if data.empty?

          ev = JSON.parse(data)
          case name.strip
          when "delta"
            text << ev.fetch("text", "")
            %w[findings reconciliation trust_scope summary].each do |key|
              next if seen.include?(key)
              next unless text.include?(%("#{key}"))
              seen << key
              warn "reached #{key}"
            end
          when "done"  then truncated = ev["truncated"]
          when "error" then raise ApiError.new(ev["code"], ev["message"])
          end
        end
      end
    end
  end

  raise "truncated reply: retry, do not repair" if truncated
  JSON.parse(text[text.index("{")..text.rindex("}")])
end

review = stream(build_input("diagnose"))
puts "#{review['verdict']} | #{review['headline']}"

<?php
// POST /run-stream. CURLOPT_WRITEFUNCTION gets the chunks as they arrive.
function stream_run(array $body, int $attempt = 1): array {
    $text = "";
    $buf = "";
    $truncated = false;
    $seen = [];

    $ch = curl_init(BASE . "/run-stream");
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer " . TOKEN,
        "Content-Type: application/json",
        "Accept: text/event-stream",
        "Idempotency-Key: " . idem_key($body, $attempt),
    ]);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    curl_setopt($ch, CURLOPT_WRITEFUNCTION,
        function ($ch, $chunk) use (&$text, &$buf, &$truncated, &$seen) {
            $buf .= $chunk;
            // Events are separated by a blank line.
            while (($i = strpos($buf, "\n\n")) !== false) {
                $block = substr($buf, 0, $i);
                $buf = substr($buf, $i + 2);

                $name = "message";
                $data = "";
                foreach (explode("\n", $block) as $line) {
                    if (str_starts_with($line, "event:")) $name = trim(substr($line, 6));
                    elseif (str_starts_with($line, "data:")) $data .= trim(substr($line, 5));
                }
                if ($data === "") continue;
                $ev = json_decode($data, true) ?: [];

                if ($name === "delta") {
                    $text .= $ev["text"] ?? "";
                    foreach (["findings", "reconciliation", "trust_scope", "summary"] as $k) {
                        if (!in_array($k, $seen, true) && str_contains($text, "\"$k\"")) {
                            $seen[] = $k;
                            fwrite(STDERR, "reached $k\n");
                        }
                    }
                } elseif ($name === "done") {
                    $truncated = !empty($ev["truncated"]);
                } elseif ($name === "error") {
                    throw new ApiError($ev["code"] ?? "INTERNAL", $ev["message"] ?? "");
                }
            }
            return strlen($chunk);
        });
    curl_exec($ch);
    curl_close($ch);

    if ($truncated) throw new RuntimeException("truncated: retry, do not repair");
    $slice = substr($text, strpos($text, "{"),
                     strrpos($text, "}") - strpos($text, "{") + 1);
    return json_decode($slice, true);
}

$review = stream_run(build_input("diagnose", $FIT, $TABLE));
echo $review["verdict"], " | ", $review["headline"], "\n";

// POST /run-stream with Accept: text/event-stream, read line by line.
static async Task<JsonElement> StreamRun(object body, string lane, int attempt = 1)
{
    var req = new HttpRequestMessage(HttpMethod.Post,
        "https://api.skillsafe.ai/v1/app-api/run-stream");
    req.Headers.Add("Authorization", $"Bearer {PosteriorDesk.Token}");
    req.Headers.Add("Accept", "text/event-stream");
    req.Headers.Add("Idempotency-Key", IdemKey(body, lane, attempt));
    req.Content = new StringContent(JsonSerializer.Serialize(body),
                                    Encoding.UTF8, "application/json");

    using var http = new HttpClient();
    var res = await http.SendAsync(req, HttpCompletionOption.ResponseHeadersRead);

    // An idempotent replay of a key that already ran answers with plain JSON.
    if (res.Content.Headers.ContentType?.MediaType != "text/event-stream")
    {
        var env = await res.Content.ReadFromJsonAsync<JsonElement>();
        return ReviewOf(env.GetProperty("data"), lane, Array.Empty<string>());
    }

    var text = new StringBuilder();
    var truncated = false;
    var stages = new List<string> { "findings", "reconciliation", "trust_scope", "summary" };

    using var reader = new StreamReader(await res.Content.ReadAsStreamAsync());
    string? name = null;
    while (await reader.ReadLineAsync() is { } line)
    {
        if (line.StartsWith("event:")) { name = line[6..].Trim(); continue; }
        if (!line.StartsWith("data:")) continue;         // blank line = end of event
        var data = line[5..].Trim();
        if (data.Length == 0) continue;

        var ev = JsonDocument.Parse(data).RootElement;
        if (name == "delta" && ev.TryGetProperty("text", out var piece))
        {
            text.Append(piece.GetString());
            while (stages.Count > 0 && text.ToString().Contains($"\"{stages[0]}\""))
            {
                Console.WriteLine($"reached {stages[0]}");
                stages.RemoveAt(0);
            }
        }
        else if (name == "done")
        {
            truncated = ev.TryGetProperty("truncated", out var t) && t.GetBoolean();
        }
        else if (name == "error")
        {
            throw new InvalidOperationException(data);
        }
    }

    if (truncated) throw new InvalidOperationException("truncated: retry, do not repair");
    var s = text.ToString();
    return JsonDocument.Parse(s[s.IndexOf('{')..(s.LastIndexOf('}') + 1)]).RootElement;
}

var streamed = await StreamRun(BuildInput("diagnose"), "diagnose");
Console.WriteLine(streamed.GetProperty("headline").GetString());

# Three lanes over one fit. The lane is in the key, so these are three jobs.
for LANE in diagnose respec report; do
  BODY=$(printf '%s' "$INPUT" | LANE="$LANE" python3 -c '
import json, os, sys
body = json.load(sys.stdin)
body["task"] = os.environ["LANE"]
print(json.dumps(body))
')
  KEY="posterior-desk:$(printf '%s' "$BODY" | shasum -a 256 | cut -c1-16):$LANE:a1"

  JOB=$(curl -sS -X POST "$BASE/run" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -H "Idempotency-Key: $KEY" -d "$BODY" \
    | python3 -c 'import sys,json; print(json.load(sys.stdin)["data"]["job_id"])')

  until [ "$(curl -sS "$BASE/jobs/$JOB" -H "Authorization: Bearer $TOKEN" \
      | python3 -c 'import sys,json; print(json.load(sys.stdin)["data"]["status"])')" \
      != "running" ]; do sleep 1; done

  curl -sS "$BASE/jobs/$JOB" -H "Authorization: Bearer $TOKEN" \
    | LANE="$LANE" python3 -c '
import json, os, sys
job = json.load(sys.stdin)["data"]
raw = job["output"]["output"]
review = json.loads(raw[raw.index("{"):raw.rindex("}") + 1])
assert review["lane"] == os.environ["LANE"], "wrapped input?"
print(review["lane"], review["verdict"], "|", review["headline"])
' > "review-$LANE.txt" || break

  # Do not write a reporting pack for a fit that cannot be reported.
  if [ "$LANE" = "diagnose" ] && grep -q not_supported "review-diagnose.txt"; then
    echo "diagnose says not_supported - running respec, skipping report"
  fi
done

def pipeline(base_input):
    """diagnose -> respec -> report, stopping where it makes sense to stop."""
    out = {}

    diag = review_of(run({**base_input, "task": "diagnose"}), "diagnose")
    out["diagnose"] = diag
    print("diagnose:", diag["verdict"], "|", diag["headline"])

    # respec is worth running exactly when diagnose objected.
    if diag["verdict"] in ("revise", "not_supported"):
        resp = review_of(run({**base_input, "task": "respec"}), "respec")
        out["respec"] = resp
        print("respec:", resp["body"]["root_cause"]["diagnosis"])
        for s in resp["body"]["run_plan"]:
            print(f"  {s['step']}. {s['action']}  [stop if: {s['stop_if']}]")

    # A reporting pack for an unusable fit is a document nobody should have.
    if diag["verdict"] == "not_supported":
        print("skipping report: the posterior does not support a write-up yet")
        return out

    rep = review_of(run({**base_input, "task": "report"}), "report")
    out["report"] = rep
    print("report:", rep["verdict"])
    for row in rep["body"]["diagnostics_table"]:
        if row["source"] == "not established":
            print("  not established:", row["quantity"])
    return out


results = pipeline({k: v for k, v in INPUT.items() if k != "task"})

# One fact must land at the same severity in every lane it appears in.
for lane, review in results.items():
    for f in review["findings"]:
        print(lane, f["id"], f["severity"], f["area"], f["title"])

async function pipeline(baseInput) {
  const out = {};
  const uids = (baseInput.prescan_facts?.flags ?? []).map((f) => f.uid);

  const diag = reviewOf(await run({ ...baseInput, task: "diagnose" }), "diagnose", uids);
  out.diagnose = diag;
  console.log("diagnose:", diag.verdict, "|", diag.headline);
  console.log("  not reportable:", diag.body.trust_scope.not_reportable);

  // respec is worth running exactly when diagnose objected.
  if (diag.verdict === "revise" || diag.verdict === "not_supported") {
    const resp = reviewOf(await run({ ...baseInput, task: "respec" }), "respec", uids);
    out.respec = resp;
    console.log("root cause:", resp.body.root_cause.diagnosis);
    for (const s of resp.body.run_plan) {
      console.log(`  ${s.step}. ${s.action} [stop if: ${s.stop_if}]`);
    }
  }

  // A reporting pack for an unusable fit is a document nobody should have.
  if (diag.verdict === "not_supported") {
    console.log("skipping report: nothing here is writable up yet");
    return out;
  }

  const rep = reviewOf(await run({ ...baseInput, task: "report" }), "report", uids);
  out.report = rep;
  for (const row of rep.body.diagnostics_table) {
    if (row.source === "not established") console.log("  not established:", row.quantity);
  }
  return out;
}

const { task, ...baseInput } = INPUT;
const results = await pipeline(baseInput);

// One fact, the same severity in every lane it appears in.
for (const [lane, review] of Object.entries(results)) {
  for (const f of review.findings) {
    console.log(lane, f.id, f.severity, f.area, f.title);
  }
}

// diagnose -> respec -> report over one fit, with the lane in every key.
func pipeline(in runInput) (map[string]*review, error) {
	out := map[string]*review{}

	in.Task = "diagnose"
	j, err := runAndPoll(in, 1)
	if err != nil {
		return out, err
	}
	diag, err := reviewOf(j, "diagnose", nil)
	if err != nil {
		return out, err
	}
	out["diagnose"] = diag
	fmt.Printf("diagnose: %s | %s\n", diag.Verdict, diag.Headline)

	// respec is worth running exactly when diagnose objected.
	if diag.Verdict == "revise" || diag.Verdict == "not_supported" {
		in.Task = "respec"
		j, err := runAndPoll(in, 1) // different body -> different key
		if err != nil {
			return out, err
		}
		resp, err := reviewOf(j, "respec", nil)
		if err != nil {
			return out, err
		}
		out["respec"] = resp

		// body is lane-specific: decode it into the shape for this lane.
		var b struct {
			RootCause struct {
				Diagnosis  string `json:"diagnosis"`
				Confidence string `json:"confidence"`
			} `json:"root_cause"`
			RunPlan []struct {
				Step   int    `json:"step"`
				Action string `json:"action"`
				StopIf string `json:"stop_if"`
			} `json:"run_plan"`
		}
		if err := json.Unmarshal(resp.Body, &b); err != nil {
			return out, err
		}
		fmt.Println("root cause:", b.RootCause.Diagnosis)
		for _, s := range b.RunPlan {
			fmt.Printf("  %d. %s [stop if: %s]\n", s.Step, s.Action, s.StopIf)
		}
	}

	// A reporting pack for an unusable fit is a document nobody should have.
	if diag.Verdict == "not_supported" {
		fmt.Println("skipping report: the posterior does not support a write-up yet")
		return out, nil
	}

	in.Task = "report"
	j, err = runAndPoll(in, 1)
	if err != nil {
		return out, err
	}
	rep, err := reviewOf(j, "report", nil)
	if err != nil {
		return out, err
	}
	out["report"] = rep
	return out, nil
}

/** diagnose -> respec -> report over one fit. Three lanes, three keys, three
 *  jobs: the lane is part of the body and therefore part of the key. */
static void pipeline() throws Exception {
    String diagJob = runAndPoll(inputJson("diagnose"), "diagnose");
    check(diagJob, "diagnose");
    System.out.println("diagnose done");

    // Cheap verdict read without a JSON library; use Jackson in production.
    boolean objected = diagJob.contains("\"verdict\":\"revise\"")
                    || diagJob.contains("\"verdict\":\"not_supported\"");
    boolean unusable = diagJob.contains("\"verdict\":\"not_supported\"");

    // respec is worth running exactly when diagnose objected.
    if (objected) {
        String respecJob = runAndPoll(inputJson("respec"), "respec");
        check(respecJob, "respec");
        System.out.println("respec done - read body.run_plan for the ordered steps");
    }

    // A reporting pack for an unusable fit is a document nobody should have.
    if (unusable) {
        System.out.println("skipping report: nothing here is writable up yet");
        return;
    }

    String reportJob = runAndPoll(inputJson("report"), "report");
    check(reportJob, "report");
    System.out.println("report done - rows with source \"not established\" are the gaps");
}

public static void main(String[] args) throws Exception {
    if (System.getenv("SKILLSAFE_TOKEN") == null) mintGuest();
    pipeline();
}

# diagnose -> respec -> report over one fit.
def pipeline(base)
  out = {}
  uids = (base.dig(:prescan_facts, :flags) || []).map { |f| f[:uid] }

  diag = review_of(run(base.merge(task: "diagnose")), "diagnose", uids)
  out["diagnose"] = diag
  puts "diagnose: #{diag['verdict']} | #{diag['headline']}"
  puts "  not reportable: #{diag.dig('body', 'trust_scope', 'not_reportable').join('; ')}"

  # respec is worth running exactly when diagnose objected.
  if %w[revise not_supported].include?(diag["verdict"])
    resp = review_of(run(base.merge(task: "respec")), "respec", uids)
    out["respec"] = resp
    puts "root cause: #{resp.dig('body', 'root_cause', 'diagnosis')}"
    resp.dig("body", "run_plan").each do |s|
      puts "  #{s['step']}. #{s['action']} [stop if: #{s['stop_if']}]"
    end
  end

  # A reporting pack for an unusable fit is a document nobody should have.
  if diag["verdict"] == "not_supported"
    puts "skipping report: the posterior does not support a write-up yet"
    return out
  end

  rep = review_of(run(base.merge(task: "report")), "report", uids)
  out["report"] = rep
  rep.dig("body", "diagnostics_table")
     .select { |r| r["source"] == "not established" }
     .each { |r| puts "  not established: #{r['quantity']}" }
  out
end

base = build_input("diagnose").reject { |k, _| k == :task }
results = pipeline(base)

# One fact, the same severity in every lane it appears in.
results.each do |lane, review|
  review["findings"].each { |f| puts "#{lane} #{f['id']} #{f['severity']} #{f['title']}" }
end

<?php
// diagnose -> respec -> report over one fit.
function pipeline(array $base): array {
    $out = [];
    $uids = array_column($base["prescan_facts"]["flags"] ?? [], "uid");

    $diag = review_of(run_job($base + ["task" => "diagnose"]), "diagnose", $uids);
    $out["diagnose"] = $diag;
    echo "diagnose: {$diag['verdict']} | {$diag['headline']}\n";
    echo "  not reportable: "
       . implode("; ", $diag["body"]["trust_scope"]["not_reportable"]) . "\n";

    // respec is worth running exactly when diagnose objected.
    if (in_array($diag["verdict"], ["revise", "not_supported"], true)) {
        $resp = review_of(run_job($base + ["task" => "respec"]), "respec", $uids);
        $out["respec"] = $resp;
        echo "root cause: {$resp['body']['root_cause']['diagnosis']}\n";
        foreach ($resp["body"]["run_plan"] as $s) {
            echo "  {$s['step']}. {$s['action']} [stop if: {$s['stop_if']}]\n";
        }
    }

    // A reporting pack for an unusable fit is a document nobody should have.
    if ($diag["verdict"] === "not_supported") {
        echo "skipping report: nothing here is writable up yet\n";
        return $out;
    }

    $rep = review_of(run_job($base + ["task" => "report"]), "report", $uids);
    $out["report"] = $rep;
    foreach ($rep["body"]["diagnostics_table"] as $row) {
        if ($row["source"] === "not established") {
            echo "  not established: {$row['quantity']}\n";
        }
    }
    return $out;
}

$base = build_input("diagnose", $FIT, $TABLE);
unset($base["task"]);
$results = pipeline($base);

// One fact, the same severity in every lane it appears in.
foreach ($results as $lane => $review) {
    foreach ($review["findings"] as $f) {
        echo "$lane {$f['id']} {$f['severity']} {$f['area']} {$f['title']}\n";
    }
}

// diagnose -> respec -> report over one fit. The lane is in every key.
static async Task<Dictionary<string, JsonElement>> Pipeline()
{
    var results = new Dictionary<string, JsonElement>();
    var noUids = Array.Empty<string>();

    var diag = ReviewOf(await Run(BuildInput("diagnose"), "diagnose"), "diagnose", noUids);
    results["diagnose"] = diag;
    var verdict = diag.GetProperty("verdict").GetString();
    Console.WriteLine($"diagnose: {verdict} | {diag.GetProperty("headline")}");

    foreach (var q in diag.GetProperty("body").GetProperty("trust_scope")
                          .GetProperty("not_reportable").EnumerateArray())
        Console.WriteLine($"  not reportable: {q.GetString()}");

    // respec is worth running exactly when diagnose objected.
    if (verdict is "revise" or "not_supported")
    {
        var resp = ReviewOf(await Run(BuildInput("respec"), "respec"), "respec", noUids);
        results["respec"] = resp;
        var body = resp.GetProperty("body");
        Console.WriteLine($"root cause: {body.GetProperty("root_cause").GetProperty("diagnosis")}");
        foreach (var s in body.GetProperty("run_plan").EnumerateArray())
            Console.WriteLine($"  {s.GetProperty("step")}. {s.GetProperty("action")} " +
                              $"[stop if: {s.GetProperty("stop_if")}]");
    }

    // A reporting pack for an unusable fit is a document nobody should have.
    if (verdict == "not_supported")
    {
        Console.WriteLine("skipping report: nothing here is writable up yet");
        return results;
    }

    var rep = ReviewOf(await Run(BuildInput("report"), "report"), "report", noUids);
    results["report"] = rep;
    foreach (var row in rep.GetProperty("body").GetProperty("diagnostics_table")
                           .EnumerateArray())
        if (row.GetProperty("source").GetString() == "not established")
            Console.WriteLine($"  not established: {row.GetProperty("quantity")}");

    return results;
}

var all = await Pipeline();
foreach (var (lane, review) in all)
    foreach (var f in review.GetProperty("findings").EnumerateArray())
        Console.WriteLine($"{lane} {f.GetProperty("id")} {f.GetProperty("severity")} " +
                          $"{f.GetProperty("title")}");