checkpoint

type Envelope struct {
	// Version is the envelope schema version (see EnvelopeVersion).
	Version int `json:"version"`

	// Provider identifies the executor backend ("anthropic", "openai",
	// "google") that produced ProviderState.
	Provider string `json:"provider"`
	// Model is the model id in effect when the conversation suspended.
	Model string `json:"model"`
	// SDKVersion records the provider SDK version in effect at park time, for
	// diagnostics and telemetry. It is not compared on wake: SDK drift is
	// enforced through ConfigDigest — executors include the SDK version in the
	// digested configuration so a drifted binary trips the one fail-closed
	// gate rather than a second parallel check.
	SDKVersion string `json:"sdk_version,omitempty"`
	// ConfigDigest is DigestJSON over the resume-relevant configuration,
	// including the provider SDK version. A mismatch on wake signals "rebuild
	// from scratch" rather than resume. The digest is required: Validate
	// rejects an envelope without one at park time and ValidateForResume
	// rejects an empty digest on either side, so the drift gate can never be
	// vacuously satisfied.
	ConfigDigest string `json:"config_digest,omitempty"`

	// ReconcilerKey is the workqueue key the suspended run belongs to; combined
	// with the executor identity it names the single parked object.
	ReconcilerKey string `json:"reconciler_key"`
	// RunID disambiguates successive runs of the same key. It is a field of the
	// single per-{identity}/{key} object, NOT part of the storage path, so
	// Load(key) is never ambiguous.
	RunID string `json:"run_id"`

	// Turn is the 0-based conversation turn at which the suspension fired.
	Turn int `json:"turn"`
	// RemainingTurns is the overall turn budget still available across resumes,
	// so a conversation cannot loop forever by suspending and waking. It must
	// be positive to park: Validate rejects an exhausted budget at suspend
	// time, mirroring the ValidateForResume turn gate, so an envelope that
	// could never wake is never persisted.
	RemainingTurns int `json:"remaining_turns"`

	// Reason is a short machine-readable reason for the suspension.
	Reason string `json:"reason,omitempty"`

	// PendingToolCalls are the unanswered held-out ask-human calls from the
	// suspended turn (usually one; more only when the turn issued several).
	// Dispatched siblings never appear here — their real results were already
	// in ProviderState when the turn quiesced (see PendingToolCall).
	PendingToolCalls []PendingToolCall `json:"pending_tool_calls,omitempty"`

	// ProviderState is the full provider request payload (e.g. a serialized
	// anthropic.MessageNewParams) carried verbatim as raw JSON.
	//
	// The envelope's neutrality stops at this field: the SCHEMA is one format
	// for every executor, but the conversation inside ProviderState is bound
	// to the exact Provider and Model that produced it, and ValidateForResume
	// fails closed on any mismatch (including a model version bump). This is
	// deliberate — provider transcripts are not losslessly translatable:
	// Anthropic thinking blocks carry model-bound signatures, Gemini thinking
	// mode requires the thoughtSignature history replayed verbatim, and tool
	// call identifier schemes differ per provider. A cross-model "resume" that
	// silently transplanted a transcript would replay unverifiable state.
	//
	// TODO(DEV-2247): support continuing on a different model. One model's
	// conversation can never be handed to another model directly — it will not
	// verify or replay. The workable approach: start a brand-new run on the
	// target model and feed it the parked conversation as plain text, together
	// with the pending question and the human's answer. Everything needed for
	// that already lives in ProviderState, so no envelope schema change is
	// required.
	ProviderState json.RawMessage `json:"provider_state,omitempty"`
	// LoopState is executor-loop bookkeeping (turn index, cache-tail state, ...)
	// carried opaquely so each executor owns its own shape.
	LoopState json.RawMessage `json:"loop_state,omitempty"`

	// StateRef optionally points at externally stored large state (e.g. a GCS
	// object) when the payload is too big to inline.
	StateRef string `json:"state_ref,omitempty"`
	// TraceID is the originating trace, so the resumed run can link back to it.
	TraceID string `json:"trace_id,omitempty"`

	// Deadline is the wall-clock time after which the envelope must not be
	// resumed — ValidateForResume rejects an envelope whose Deadline has
	// passed (fail-closed on wake). Zero means no deadline.
	Deadline time.Time `json:"deadline,omitempty"`
}

type FramedAnswer struct {
	// ID is the pending tool call's provider identifier.
	ID string
	// Name is the pending tool call's tool name.
	Name string
	// Text is the framed answer body (delimited, capped, empty-substituted).
	Text string
}

type PendingToolCall struct {
	// ID is the provider-assigned tool call identifier (anthropic tool_use id,
	// openai tool_call id, genai FunctionCall.ID). Persisted, never re-derived.
	ID string `json:"id"`
	// Name is the tool name, retained for diagnostics/telemetry only.
	Name string `json:"name"`
	// InputJSON is the raw tool input as the model emitted it.
	InputJSON json.RawMessage `json:"input_json,omitempty"`
}

type Store interface {
	// Save durably writes env under key, overwriting any existing envelope and
	// advancing its CAS generation. Save is unconditional: claim-once ordering
	// is expressed with Load + Delete, not with Save.
	Save(ctx context.Context, key string, env *Envelope) error

	// Load returns the envelope stored under key together with its current CAS
	// Token. The bool is false (with a nil envelope, zero Token, and nil error)
	// when no envelope exists for key.
	Load(ctx context.Context, key string) (*Envelope, Token, bool, error)

	// Delete removes the envelope under key only if tok still matches the
	// stored object's current generation, returning ErrTokenMismatch otherwise
	// (including when the key is already gone). This is the claim primitive:
	// exactly one caller holding a given Token wins the delete.
	Delete(ctx context.Context, key string, tok Token) error
}

type Suspension struct {
	// Envelope is the serializable capture of the paused conversation.
	Envelope

	// Question is an optional human-facing prompt describing what the agent is
	// waiting on. The question/answer lifecycle itself lives above this package
	// (checkpoint stays a pure primitive); this field is only a convenience
	// carrier so a Suspension can round-trip the prompt text.
	Question string `json:"question,omitempty"`
}

type Token struct {
	Generation int64 `json:"generation"`
}