shaped

type Ask struct {
	// Lane names the pass making the ask, in the words a person would use for
	// it: "plan", "gate", "compile". It is the memo's key beside the model and
	// the subject of the line the stream prints, so it is a name and never a
	// class identifier.
	Lane string

	// Messages are the request as the caller assembled it. The seam appends to
	// a copy when it repairs and never rewrites what is here.
	Messages []ai.Message

	// Schema is the shape being asked for. It is used for two things: sent on
	// the wire when Routed, and read by the ceiling derivation, which counts
	// what one answer of this shape has to hold.
	Schema json.RawMessage

	// Routed says whether this client can carry a structured-output request. A
	// build with no router has no second rung to unlock and sends none — the
	// tolerance in provider.DecodeJSONObject is what stands in for it.
	Routed bool

	// JSON asks for an object on the wire without pinning its shape: JSON mode
	// rather than a strict schema. It is for an ask whose shape is the prompt's
	// to extend — the compile's menu, charter and model note are fields the
	// prompt adds when they apply, and a schema would have to know every one.
	// A prompt alone was not enough: a model handed an issue written in Markdown
	// answered in Markdown, twice, and the whole job was forfeit for $0.0007.
	// It goes out on every send of the ask, the repairs included.
	JSON bool

	// Answers is how many objects of the schema's item shape the ask expects
	// back — the fan-out's permitted width, a panel's seat count. Zero and one
	// both mean "one object", which is every other call in the system.
	//
	// IT IS THE ASK'S OWN NUMBER AND NEVER A GUESS. Where a prompt tells the
	// model how many parts it may return, that same figure is what is passed
	// here, so the sentence the model reads and the room it is given can never
	// drift apart.
	Answers int

	// Echo is the material this answer has to carry back verbatim, when there is
	// any. The intent compiler's brief restates the user's instruction twice —
	// once inside the goal and once under "Verbatim request:" — so its reply
	// cannot be smaller than the ask however small the schema is. A pass whose
	// answer quotes nothing leaves this empty.
	Echo string
}

type Completer interface {
	CompleteWithMessages(ctx context.Context, messages []ai.Message, options ...ai.Option) (*ai.Response, error)
}

type Journal interface {
	Repaired(Repair)
}

type JournalFunc func(Repair)

type Repair struct {
	Lane    string     `json:"lane"`
	Model   string     `json:"model,omitempty"`
	Kind    RepairKind `json:"kind"`
	Round   int        `json:"round,omitempty"`
	Spent   int        `json:"spent,omitempty"`
	Ceiling int        `json:"ceiling,omitempty"`

	// Note is WHY the answer could not be read, in the reader's own words.
	//
	// "The answer was not readable" is two different facts and this seam was
	// journaling one word for both. A reply that never contained an object at
	// all is a model reasoning out loud, and the re-ask is the mechanism
	// working. A reply that decoded and was refused by the caller's own
	// contract — a delivery verdict naming a file the record does not hold, or
	// quoting something the request never states — is a model answering a
	// question it was asked badly, and the re-ask may be buying nothing.
	//
	// textual v4-flash s13 holds two of these on lane `gate` and no way to tell
	// which: settling it meant reading token counts out of the usage table
	// three events either side. The error the decode returned says it in one
	// line, and it is the line nobody had.
	Note string `json:"note,omitempty"`
}

type RepairKind string