roles

const (
	// RoleTitle names a session from its opening exchange.
	RoleTitle Role = "title"
	// RoleConsolidate is the dreaming pass over what a session has remembered:
	// one call over fifty short lines whose whole instruction is "merge the
	// duplicates and drop what is superseded" (internal/session's
	// memory_consolidate.go, which owns the call and registers it). Low — the
	// archetypal cheap call, made while nobody is waiting, over a file the next
	// idle minute passes over again.
	RoleConsolidate Role = "consolidate"
	// RoleGuardian answers "is this specific tool call safe to run without
	// asking the person?" — a cheap binary classification, so it sits low.
	RoleGuardian Role = "guardian"
	// RoleVision reads images for a chat model that cannot see them natively;
	// it wants to be genuinely good at seeing, not cheap.
	RoleVision Role = "vision"
	// RoleImageGen generates images — a different modality entirely; the chat
	// model never substitutes.
	RoleImageGen Role = "imagegen"
	// RolePlanner is the ADAPTIVE RUN'S BRAIN (internal/orchestrate): the call
	// that reads the goal, the digests of what has finished and the fuel left,
	// and answers with an amendment to the plan. It is the ONLY call in a run
	// that sees the run whole, it is made once at the start and once per node
	// completion, and every node the rest of the run pays for is a node it cut.
	// A planner that cuts badly spends a whole tank on work nobody wanted, so
	// it sits high.
	RolePlanner Role = "planner"
	// RoleDesigner writes a harness page and reviews it before it is offered
	// (internal/session's harness_build.go). What it writes is SAVED and run
	// again by everyone who picks it afterwards, so a bad page is not one wrong
	// answer, it is a wrong answer with a name on the menu; high.
	RoleDesigner Role = "designer"
	// RoleWorker is a node: one small question, a handful of turns, a digest at
	// the end. Low, because the shape of an adaptive run is many small workers
	// under one careful planner — width is where the work happens, and it is
	// where a run's money actually goes.
	RoleWorker Role = "worker"
	// RoleSpeech turns words into sound, and RoleVideo turns them into film.
	// They complete the set of media pins the v3 use-time resolver reads as its
	// second rung (docs/MULTIMODAL.md Decision 5), beside RoleImageGen and
	// RoleVision, so an operator can pin every modality by the same mechanism
	// rather than three of four.
	//
	// THEY ARE PIN NAMES AND ARE DELIBERATELY NOT REGISTERED. Registration
	// binds a role to a TIER, and a tier is a class of text model: resolving
	// "speech" through the low tier would hand a text model to an endpoint that
	// returns audio, which is the wrong answer delivered confidently. A media
	// role's ladder is the resolver's — slot, pin, catalog, curated name — and
	// every rung of it is capability-checked, which the tier ladder cannot be.
	// [Pinned] reads a key and needs no registration, which is exactly the
	// slice of this package a media resolver wants.
	RoleSpeech Role = "speech"
	RoleVideo  Role = "video"
	// RoleAuditor is the VERIFIED FRONTIER: the read-only judge that decides
	// whether a piece of finished-looking work is actually finished, against
	// hard evidence it gathered itself. It sits HIGH and it is the one role
	// where the tier is not an economy question at all — a wrong verdict
	// either lands broken work as done or throws good work away, and both are
	// mistakes nobody downstream can see to correct. Registered from
	// internal/session/task_audit.go, which owns the call.
	RoleAuditor Role = "auditor"
	// RoleReflex is the per-turn pair: the pre-turn router that reads the
	// message you just typed and answers which remembered lines belong in this
	// turn, and the post-turn extractor that reads the exchange and answers
	// whether anything in it is worth keeping. Both answer in a few words of
	// JSON, both run every single turn, and neither is allowed to think — which
	// is why they are their own tier rather than the low one. Registered here
	// with the built-ins because the tier IS the role's whole design, and a
	// reflex role assigned anywhere else would be the same mistake as putting
	// the reflex model on the high tier.
	RoleReflex Role = "reflex"
	// RoleRouter is the sidecar judge that reviews a tool-less answer and asks
	// whether it should have been work. It sits LOW because it SCREENS: it is
	// asked after every substantial turn that answered in words alone, which is
	// volume, and volume belongs on the cheap model.
	//
	// ITS OLD ECONOMICS ARE GONE AND THE LINE THAT STATED THEM WAS STALE. "A
	// wrong no costs an offer card that was never shown, never money" was true
	// while a yes raised a card somebody had to press; a yes now STARTS the work
	// (internal/session/route_judge.go), so a wrong yes spends a whole task's
	// money. What holds that shut is NOT a dearer model here — moving the screen
	// off the cheap tier would pay for thinking on every turn to correct the rare
	// one — it is [RoleRouterConfirm], asked once on the yes. A wrong no still
	// costs nothing but work that was never started.
	RoleRouter Role = "router"
	// RoleRouterConfirm is the SECOND question, asked only where RoleRouter has
	// already answered yes: the same brief, the same one-object contract, a
	// fresh context, on the tier that thinks. Only both-yes starts anything, and
	// the confirm's no is silence — no note, no retry.
	//
	// IT SITS ON THE MASTERMIND TIER AND ITS EXPECTED COST IS STILL NEARLY ZERO,
	// which is the whole shape of a cascade. It is never asked about the turns
	// the cheap screen already threw out — the trivial ones, the ones that called
	// tools, the plain nos — so what it costs is one mastermind call per yes, and
	// a yes is rare. What it prevents each time is a task's worth of spend, in a
	// worktree, on work nobody asked for. Registered from
	// internal/session/route_judge.go, which owns the call.
	RoleRouterConfirm Role = "routerconfirm"
	// RoleMarkReader reads ONE MARK of an answer that is still running: the
	// transcript the turn has built so far, and one question asking it to sketch
	// what is left as parts and arrows (internal/session/checkpoint.go, which owns
	// the call). The harness parses the shape it draws and hands the turn over
	// where the shape has independent parts in it.
	//
	// IT IS ITS OWN ROLE BECAUSE IT ASKS ITS OWN QUESTION. RoleRouterConfirm is
	// the second reader of a work-or-words judgement about a REQUEST nobody has
	// worked on yet; this reads a turn's own findings and answers what remains.
	// Sharing a name would mean one pin could only ever point both calls at one
	// model, and the two are billed on completely different rhythms.
	//
	// IT SITS ON THE MASTERMIND TIER BECAUSE THE CHEAP ANSWER WAS MEASURED AND IT
	// WAS NOT AN ANSWER. Asked mid-turn, the running chat model emitted a tool call
	// instead of answering between 17% and 53% of the time, depending on the
	// phrasing; the mastermind left 0% to 7% unanswered on the same transcripts
	// (bench/oneroad/replay/RESULTS.md). A reader that goes silent under tool
	// momentum is silent on exactly the turns this is for. What it costs is bounded
	// hard: at most three calls, and only on a turn that has already run ten rounds
	// of tools, which most turns never do.
	RoleMarkReader Role = "markreader"
	// RoleHandoff WRITES THE BRIEF a handed-over turn gives the worker that takes
	// it: the person's ask, the state card, an account of what the turn did and
	// what came back, and the draft the running model wrote — in, and one
	// instruction somebody who saw none of it can work from, out
	// (internal/session/checkpoint.go, which owns the call).
	//
	// IT IS ITS OWN ROLE BECAUSE THE DRAFT AND THE DOCUMENT ARE DIFFERENT JOBS.
	// The model that spent the turn is the only one holding the findings, so it
	// still drafts; it is also, by then, a tired model at the end of forty rounds,
	// and asking it to be its own editor was measured producing 5,882 characters
	// in which 39 of 85 clauses were distinct and 62% was one six-sentence loop —
	// which a cold worker was then started on as its whole world.
	//
	// IT SITS ON THE MASTERMIND TIER FOR THE MARK READER'S REASON, arrived at from
	// the other side: this document is the ENTIRE context of everything that
	// happens after the handover — the worker's instruction, what the division
	// reviewer reads, what the checker is eventually held against — so a cheap
	// answer here is not a cheap answer, it is a whole task's spend on the wrong
	// work. What it costs is bounded hard: at most two calls, and only on a turn
	// that is being handed over at all, which most turns never are.
	RoleHandoff Role = "handoff"
	// RoleTaskName is the two or three words a piece of work is CALLED on the
	// rail, the home card and the task list — made from the node's own gloss and
	// brief when whoever started it left a raw sentence there instead of a name.
	// Low, for the title's reason: a wrong name costs a glance at a column and
	// nothing downstream is decided from it. Registered from
	// internal/session/taskname.go, which owns the call.
	RoleTaskName Role = "taskname"
	// RoleJobName is the three or four words a background command is CALLED on
	// its row — made from the command itself when the registry left a raw
	// invocation there instead of a label. Low, for the title's reason: a wrong
	// name costs a glance at a column and nothing downstream is decided from it.
	// Registered from internal/session/jobname.go, which owns the call.
	RoleJobName Role = "jobname"
	// RoleCaption names the discrete step over a live tool batch — the checklist
	// item a person reads, never the model's thinking. LOW, for the title's
	// reason — a wrong caption costs a glance, the rows beneath it are the truth,
	// and nothing downstream is decided from it. Registered from
	// internal/session/caption.go, which owns the call.
	RoleCaption Role = "caption"
	// RoleShaper turns the words somebody typed after /task into the brief the
	// worker is actually handed: it reads one request and writes the paragraphs
	// and the done-condition around it. It sits HIGH for the auditor's reason
	// rather than the title's — the brief is the worker's whole world, and a
	// vague one is not a glance wasted but a whole task's spend on work nobody
	// wanted. Registered from internal/session/task_shape.go, which owns the
	// call.
	RoleShaper Role = "shaper"

	// RoleIntake fills a subharness's input form from what the conversation has
	// already said (docs/SUBHARNESS-PRD.md §4: infer, then confirm — never
	// interrogate). It sits LOW for the title's reason rather than the shaper's:
	// its answer lands on a card the person is looking at and about to confirm,
	// so a wrong guess costs one correction rather than a whole run's spend, and
	// the alternative to a cheap call here is not a better call but an empty form
	// somebody fills in by hand. Registered from
	// internal/session/subharness_intake.go, which owns the call.
	RoleIntake Role = "intake"

	// RoleRepair is the hands that fix what the cheap hands got wrong.
	//
	// THE TIER IS HIGH AND NOT THE MASTERMIND'S, for [RoleCareful]'s reason: a
	// repair round is many turns of ordinary work done by a model that can be
	// trusted with something subtle, not one answer that decides what every other
	// call does. Registered from internal/session/repair_role.go, which owns the
	// call.
	RoleRepair Role = "repair"

	// RoleSentinel is one standing item's cheap yes-or-no: is what this check
	// found worth telling the person about.
	//
	// IT SITS LOW for the guardian's reason — it reads a few kilobytes and
	// answers one binary question, and a wrong no costs a check that said nothing
	// rather than money. It is also the call this build makes most often with
	// nobody in front of it, once per check of every item forever. Registered
	// from internal/session/standing_run.go, which owns the call.
	RoleSentinel Role = "sentinel"

	// RoleSpellOut expands a half-written request into what it obviously meant,
	// for the person to read and keep or drop.
	//
	// IT SITS LOW, with the namer and the sentinel rather than with the shaper.
	// The shaper writes the only document an autonomous worker will ever read, so
	// a vague answer there costs a whole task's spend; this one writes three lines
	// a person reads on screen before deciding whether to keep them, and a weak
	// answer costs one esc. A person who wants it thought about harder pins it
	// (`roles.spellout: <model>`). Registered from internal/session/spellout.go,
	// which owns the call.
	//
	// THE WORD LIVES HERE AND NOT AT THE CALL SITE, which is the whole reason
	// this constant moved. It was `const spellOutRole roles.Role = "spellout"` in
	// internal/session, and every reader that asks this package what the role
	// vocabulary IS — cmd/codeaf-replay's roleWords, which parses this file — could
	// not see it. So `spellout` reached the cost report as an unrecognised tag and
	// was priced as a background errand with nobody waiting, when it is the one
	// auxiliary a person sits and watches. A role declared anywhere else is a role
	// that is invisible to everything that reads roles.
	RoleSpellOut Role = "spellout"

	// RoleDivision reviews a DIVISION as a plan. A worker halfway through its
	// own work has named the parts it wants to hand out, and this is the one
	// call that reads them TOGETHER — the evidence, the parent's own brief, and
	// every part's title, brief and done-condition — and answers with those
	// parts approved, amended, merged, or refused as not a division at all.
	//
	// IT IS ON THE MASTERMIND TIER FOR THAT TIER'S OWN STATED REASON: one answer
	// shapes all the other calls. A part's brief is that part's WHOLE WORLD — it
	// never sees the conversation and cannot ask anybody anything — and the
	// briefs arrive written by whichever model the parent task happens to be
	// running on, which on a cheap crew is the cheap one. Every turn every part
	// ever takes is downstream of those paragraphs. Registered from
	// internal/session/task_divide.go, which owns the call.
	RoleDivision Role = "division"
	// RoleCareful is the model a part graded `careful` runs on. It is not an
	// auxiliary call at all — it is a whole worker's model — and it is a role so
	// that the answer comes out of this registry rather than out of a model id
	// written into a source file somewhere.
	//
	// IT SITS HIGH AND NOT ON THE MASTERMIND TIER, and the difference is the
	// call rhythm the tiers are cut along. A mastermind call is one answer that
	// decides what the others do; a careful part is MANY turns of ordinary work,
	// done by a model that can be trusted with something subtle. It is
	// [RoleWorker]'s twin: the cheap tier for parts whose failure is "not done
	// yet", this one for parts whose failure is quiet wrongness. Registered from
	// internal/session/task_divide.go, which owns the field that reaches it.
	RoleCareful Role = "careful"
)

const (
	// TierReflex is the cheapest of all: a model small enough to read EVERY
	// TURN. The two calls on it — the router that decides which memories a turn
	// needs, the extractor that decides whether the turn is worth remembering —
	// run whether or not anybody asked, twice per exchange, for the whole life
	// of a conversation. That rhythm is the tier: a model here is chosen for
	// costing near nothing per call rather than for being good at anything, and
	// no role that has to REASON belongs on it.
	TierReflex Tier = "reflex"
	// TierLow is the cheap, fast model for the SMALL calls: a name, a digest,
	// the guardian's yes-or-no, the intake form.
	TierLow Tier = "low"
	// TierWorker is the model that DOES THE WORK: the worker of every task a
	// conversation hands off, the ordinary parts that worker divides its work
	// into, and every node of an adaptive run. It is the seat that pays most of
	// a task's bill — twenty or thirty tool turns against a handful of one-shot
	// calls around them — and until it existed no tier governed it: a chat task
	// rode whatever model the person happened to be talking to, and the crew
	// dial moved everything about a task except its cost. Its rhythm is the
	// mastermind's opposite — many turns of ordinary work — so the model here is
	// chosen for holding a thread through a long agentic run at a price that can
	// be paid thirty times over.
	TierWorker Tier = "worker"
	// TierHigh is the capable, expensive one.
	TierHigh Tier = "high"
	// TierMastermind is the one tier that is not an economy at all. What every
	// role on it has in common is that ONE ANSWER SHAPES ALL THE OTHER CALLS:
	// the planner that decides what an adaptive run does next, the designer that
	// writes a harness page everybody afterwards runs, the confirm standing
	// between a cheap judge's yes and a task that starts itself, and the review
	// that reads a division's parts before a single one of them is minted. A
	// planner that cuts badly spends a whole tank on work nobody wanted; a
	// designer that writes badly puts a wrong answer on the menu with a name on
	// it; a division reviewed badly hands four workers four briefs that nobody
	// inside them can correct. The first two were on the high tier, beside the
	// auditor, which made a person choosing "the capable model" choose one
	// figure for two very different bills: the careful calls are many and short,
	// the mastermind's are few and worth thinking about. Separating them is what
	// lets the shipped crew spend on thinking exactly where thinking pays.
	TierMastermind Tier = "mastermind"
)