modprotov2

type Accepted struct {
	// contains filtered or unexported fields
}

type Approval struct {
	// RequiredWhen holds reasons from the legal set: "chargeable",
	// "irreversible", "external_write", "product_checkpoint".
	RequiredWhen []string `json:"required_when"`
}

type ApprovalRecord struct {
	Granted bool   `json:"granted"`
	Reason  string `json:"reason"`

	// GrantedBy is never "model". An approval minted by a model is stripped by
	// the host before this point: the agent cannot approve spending on the
	// operator's behalf, and a field that could carry such a claim would make
	// the gate bypassable by the thing it gates.
	GrantedBy string `json:"granted_by"`
}

type Artifact struct {
	ID   string `json:"id"`
	Kind string `json:"kind"`
	Root string `json:"root"`
	Path string `json:"path"`

	Bytes  int64  `json:"bytes"`
	Digest string `json:"digest"`

	// Presentation names a rendering primitive the HOST owns. An unknown value
	// is ignored rather than honoured.
	Presentation string `json:"presentation,omitempty"`
}

type ArtifactKind struct {
	Kind      Kind       `json:"kind"`
	MediaType string     `json:"media_type"`
	Validator *Validator `json:"validator,omitempty"`
}

type Capability struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	Summary string `json:"summary"`

	RequestSchema string `json:"request_schema"`
	ResultSchema  string `json:"result_schema"`

	// Projects names the Operations this capability surfaces. EMPTY IS LEGAL
	// and is not a defect -- see the type doc.
	Projects []string `json:"projects"`

	// Effects are declared SEPARATELY from the projected Operations' effects,
	// in the SAME SHAPE, so the no-weakening comparison is mechanical rather
	// than a translation. A translation is where a weakening hides.
	Effects Effects `json:"effects"`
}

type Decision struct {
	Pin contractv2.PinResult

	// V2 is set only when the pin matched exactly.
	V2 *Accepted

	// V1 is set only when NO contract version was declared. That module is
	// served under v1 with v1 behaviour and NO v2 guarantee.
	V1 *modproto.Descriptor
}

type Descriptor struct {
	// Protocol is the WIRE format identity. ContractVersion is the BEHAVIOURAL
	// contract. Conflating them is the axis error that made v1's version list
	// look like negotiation, so both are carried and neither is derived from
	// the other.
	Protocol        string `json:"protocol"`
	ContractVersion string `json:"contract_version"`

	Module  string `json:"module"`
	Name    string `json:"name"`
	Version string `json:"version"`

	// Operations are LAYER 1: canonical semantic units. Their effects are the
	// product truth a capability's declaration must not weaken (§2, §9).
	//
	// v1 has no equivalent at all -- Capability was the only unit -- so the
	// no-weakening check had nothing to compare against. That absence is the
	// gap this field closes.
	Operations []Operation `json:"operations"`

	// Capabilities are LAYER 2: what a host invokes. The gate reads THESE
	// effects (§2a rule 2), which is why they must be no weaker than every
	// Operation projected.
	Capabilities []Capability `json:"capabilities"`

	// ArtifactKinds declares produced artifacts BY KIND (§7). Not all JSON:
	// v1's artifact_schemas implied a JSON Schema for everything and validated
	// nothing, which meant an mp4 was undeclarable without implying a
	// validator that cannot exist.
	ArtifactKinds map[string]ArtifactKind `json:"artifact_kinds"`

	RequestSchemas map[string]json.RawMessage `json:"request_schemas"`
	ResultSchemas  map[string]json.RawMessage `json:"result_schemas"`

	Permissions   Permissions `json:"permissions"`
	AgentOverlays []Overlay   `json:"agent_overlays"`
	Skills        []Skill     `json:"skills"`
}

type Effects struct {
	Network        bool   `json:"network"`
	ExternalWrites bool   `json:"external_writes"`
	Provider       string `json:"provider"`

	// MayCharge is chargeability, INDEPENDENT of whether an amount is known.
	//
	// THE GAP THIS CLOSES. v1 had only cost_known, which means "is a number
	// known", and this host gated on it as a proxy for spending. The two are
	// genuinely independent: one of Facet's tools declares cost_known TRUE and
	// network TRUE and requires no consent, and Midden's estimate capability --
	// whose entire purpose is checking cost BEFORE a paid run -- declared
	// cost_known false while its own summary said it never bills. Gating the
	// cost-checking tool as possibly-billing discourages the one behaviour that
	// makes a cost gate work.
	MayCharge MayCharge `json:"may_charge"`

	// CostKnown declares whether a NUMBER is known. Never a proxy for
	// spending; that is what MayCharge is for.
	CostKnown bool `json:"cost_known"`

	// Deterministic: same input, same bytes (§4).
	//
	// MUST be false if Network or MayCharge could be true. Enforced in
	// Validate rather than documented, because a determinism claim that is
	// merely asserted is the kind of guarantee this contract exists to stop
	// shipping as prose.
	Deterministic bool `json:"deterministic"`
}

type Envelope struct {
	Protocol        string `json:"protocol"`
	ContractVersion string `json:"contract_version"`

	Module    string `json:"module"`
	Operation string `json:"operation"`
	RequestID string `json:"request_id"`

	OK       bool            `json:"ok"`
	Result   json.RawMessage `json:"result,omitempty"`
	Warnings []string        `json:"warnings"`

	Execution *Execution `json:"execution,omitempty"`
	Error     *Error     `json:"error,omitempty"`
}

type Error struct {
	Code   string `json:"code"`
	Reason string `json:"reason"`
	Remedy string `json:"remedy"`

	Retryable bool           `json:"retryable"`
	Details   map[string]any `json:"details,omitempty"`
}

type ExecProps struct {
	// DeadlineMSDefault bounds the WHOLE invocation, wall-clock, from process
	// start (§8).
	DeadlineMSDefault int `json:"deadline_ms_default"`
}

type Execution struct {
	Network        bool   `json:"network"`
	ExternalWrites bool   `json:"external_writes"`
	Provider       string `json:"provider"`

	// Charged is what happened, distinct from may_charge which is what was
	// declared possible.
	Charged bool `json:"charged"`

	// EstimatedCost and ActualCost are POINTERS on purpose. null means
	// genuinely UNKNOWN; 0 means genuinely free. Collapsing them would let an
	// unpriced provider call render as free and slip past a cost gate.
	EstimatedCost *float64 `json:"estimated_cost"`
	ActualCost    *float64 `json:"actual_cost"`

	// Resolution is requirements as evaluated at runtime, three-valued (§5).
	Resolution []Resolution `json:"resolution"`

	Artifacts []Artifact `json:"artifacts"`
}

type Finding struct {
	Code   string
	Where  string
	Reason string
	Remedy string
}

type Grants struct {
	Network       []string `json:"network"`
	Credentials   []string `json:"credentials"`
	PaidProviders []string `json:"paid_providers"`
	Publish       bool     `json:"publish"`
	Subprocess    []string `json:"subprocess"`
}

type Kind string

type MayCharge struct {
	// Always is the plain boolean form. When Field is empty this is the whole
	// declaration.
	Always bool

	// Field names a request field to evaluate. Empty means unconditional.
	Field string
	// WhenIn lists values of Field for which this charges.
	WhenIn []string
	// Default is the answer for a value not in WhenIn, or when the field
	// cannot be resolved.
	//
	// §3a requires this to be TRUE for an unlisted or unresolvable value, and
	// Validate enforces it. Midden verified the sequencing rather than
	// assuming it: content.produce REFUSES a request with no kind, so an
	// unevaluable condition resolves true, approval is sought, the request
	// arrives, and the module refuses deterministically -- over-gate then
	// refusal, which is annoying and strictly safe. The opposite default would
	// send an UNAPPROVED request whose kind might have been chargeable.
	Default bool
}

type Operation struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	Summary string `json:"summary"`

	Effects   Effects   `json:"effects"`
	Execution ExecProps `json:"execution"`

	// Requirements carry STRENGTH (§5). v1 could not say whether a missing
	// dependency was fatal or merely degrading.
	Requirements []Requirement `json:"requirements"`

	// Approval carries a REASON (§6). v1 gated on one field, so a
	// free-but-irreversible step was ungated entirely.
	Approval Approval `json:"approval"`

	// Produces names artifact kinds by key into Descriptor.ArtifactKinds.
	Produces []string `json:"produces"`
}

type Overlay struct {
	ID     string `json:"id"`
	Title  string `json:"title"`
	Path   string `json:"path"`
	Digest string `json:"digest"`
}

type Permissions struct {
	FilesystemRead  []string `json:"filesystem_read"`
	FilesystemWrite []string `json:"filesystem_write"`
	Network         []string `json:"network"`
	Credentials     []string `json:"credentials"`
	PaidProviders   []string `json:"paid_providers"`
	Publish         bool     `json:"publish"`
	Subprocess      []string `json:"subprocess"`
}

type Request struct {
	Protocol        string `json:"protocol"`
	ContractVersion string `json:"contract_version"`

	Capability string          `json:"capability"`
	RequestID  string          `json:"request_id"`
	Input      json.RawMessage `json:"input"`

	Roots    map[string]Root   `json:"roots"`
	Grants   Grants            `json:"grants"`
	Binaries map[string]string `json:"binaries"`

	DeadlineMS     int `json:"deadline_ms"`
	MaxOutputBytes int `json:"max_output_bytes"`

	// Approval states WHETHER approval was obtained and FOR WHAT (§6).
	//
	// ABSENT MEANS NONE WAS OBTAINED, and a module MUST NOT infer approval
	// from the field being missing. A pointer rather than a value type so that
	// absence is representable at all: a zero-valued struct with Granted false
	// says "asked and refused", which is a different fact from "never asked".
	Approval *ApprovalRecord `json:"approval,omitempty"`
}

type Requirement struct {
	// Kind is "binary", "version", "config", "env", or "credential".
	Kind     string   `json:"kind"`
	Name     string   `json:"name"`
	Strength Strength `json:"strength"`
	Detail   string   `json:"detail,omitempty"`
}

type Resolution struct {
	Kind   string `json:"kind"`
	Name   string `json:"name"`
	State  State  `json:"state"`
	Detail string `json:"detail,omitempty"`
}

type Root struct {
	Path string `json:"path"`
	Mode string `json:"mode"`
}

type Skill struct {
	ID     string `json:"id"`
	Title  string `json:"title"`
	Path   string `json:"path"`
	Digest string `json:"digest"`
}

type State string

type Strength string

type Validator struct {
	Type   string `json:"type"`
	Schema string `json:"schema"`
}