module

type Artifact struct {
	ID        string `json:"id,omitempty"`
	Kind      string `json:"kind"`
	Path      string `json:"path"`
	Root      string `json:"root,omitempty"`
	MediaType string `json:"media_type,omitempty"`
	Bytes     int64  `json:"bytes,omitempty"`
	Digest    string `json:"digest,omitempty"`
	Title     string `json:"title,omitempty"`
	// Presentation names the host rendering primitive for this artefact.
	//
	// It exists for what a media type cannot express: a scene plan is
	// application/json and also a timeline, and only the module knows that.
	// The host honours a known value and ignores an unknown one, so a module
	// names a primitive the host owns rather than inventing one.
	Presentation string `json:"presentation,omitempty"`
}

type ArtifactManifest struct {
	Schema     string          `json:"schema"`
	Module     string          `json:"module"`
	Capability string          `json:"capability"`
	RequestID  string          `json:"request_id"`
	Source     *SeedResolution `json:"source,omitempty"`
	Artifacts  []Artifact      `json:"artifacts"`
	Execution  Execution       `json:"execution"`
	Review     ReviewState     `json:"review"`
}

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"`
	ArtifactSchemas []string `json:"artifact_schemas"`
	Effects         Effects  `json:"effects"`
	Skills          []string `json:"skills"`
	LongRunning     bool     `json:"long_running"`
	PollCapability  string   `json:"poll_capability,omitempty"`

	// Projects names the v2 Operations this capability can reach.
	//
	// WITHOUT IT THE NO-WEAKENING CHECK COMPARES NOTHING. facet-studio's
	// CheckNoWeakening iterates a capability's projections; an absent list
	// means zero iterations, so a capability declaring effects weaker than the
	// Operations it dispatches passes identically to an honest one. Measured:
	// their host performed 0 comparisons against a descriptor with 35
	// Operations and reported zero findings — a check with no input and a
	// check that passed produce the same observable.
	//
	// EMPTY IS LEGAL and means something different from absent: a registry
	// read transforms no product material and projects nothing, which the
	// frozen shape states explicitly. Five of Facet's seven capabilities are
	// exactly that.
	Projects []string `json:"projects"`
}

type Consent struct {
	PaidGenerationApproved bool   `json:"paid_generation_approved"`
	ApprovedBy             string `json:"approved_by"`
	Note                   string `json:"note,omitempty"`
}

type Descriptor struct {
	Module           string   `json:"module"`
	Name             string   `json:"name"`
	Version          string   `json:"version"`
	ProtocolVersions []string `json:"protocol_versions"`
	// ContractVersion is the single behavioural contract this module
	// implements. Singular by design: a list would read as negotiable, and
	// ProtocolVersions already proved that a list validated by a membership
	// test looks like a choice while being a constant.
	ContractVersion string         `json:"contract_version"`
	Capabilities    []Capability   `json:"capabilities"`
	RequestSchemas  map[string]any `json:"request_schemas"`
	ResultSchemas   map[string]any `json:"result_schemas"`
	ArtifactSchemas map[string]any `json:"artifact_schemas"`
	AgentOverlays   []Overlay      `json:"agent_overlays"`
	Skills          []Skill        `json:"skills"`
	Permissions     Permissions    `json:"permissions"`
	Requirements    []Requirement  `json:"requirements"`

	// --- xibodev.module/v2 semantic layer ---
	//
	// These ride in the SAME document as the v1 fields above. §10 requires a
	// v1 host to ignore fields it does not recognise, and facet-studio pinned
	// that direction by test (37835f6) precisely because "works because the
	// decoder is tolerant" and "works because the contract requires it"
	// produce the same observable.
	//
	// A v1 host therefore sees exactly the v1 descriptor it always saw; a v2
	// host reads contract_version, passes the gate, and finds the semantics.
	//
	// omitempty is deliberate: a module that has not built its v2 payload must
	// publish NOTHING rather than an empty list, because an empty `operations`
	// is an affirmative claim of having none.
	Operations    []toolbox.V2Operation             `json:"operations,omitempty"`
	ArtifactKinds map[string]toolbox.V2ArtifactKind `json:"artifact_kinds,omitempty"`
}

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

	// --- v2 ---
	//
	// The host decodes a CAPABILITY's effects into the SAME type as an
	// Operation's, so no-weakening is a field comparison rather than a
	// translation. A field absent here decodes to FALSE, which is an
	// affirmative claim the module never made.
	//
	// Measured: without may_charge, creative.tools.run declared false while
	// reaching eight chargeable Operations. That is a real weakening and the
	// host is right to refuse it -- it was invisible only because the
	// capability declared no projections, so nothing was ever compared.
	//
	// Additive to v1: these names did not exist in the v1 effects object, so a
	// v1 host ignores them exactly as it ignores `operations`.
	MayCharge     bool `json:"may_charge"`
	Deterministic bool `json:"deterministic"`
}

type Envelope struct {
	Protocol  string    `json:"protocol"`
	Module    string    `json:"module"`
	Operation string    `json:"operation"`
	RequestID string    `json:"request_id"`
	OK        bool      `json:"ok"`
	Result    any       `json:"result,omitempty"`
	Error     *Error    `json:"error,omitempty"`
	Warnings  []string  `json:"warnings"`
	Execution Execution `json:"execution"`
}

type Error struct {
	Code      string         `json:"code"`
	Message   string         `json:"message"`
	Retryable bool           `json:"retryable"`
	Details   map[string]any `json:"details"`
}

type Execution struct {
	Local          bool       `json:"local"`
	Network        bool       `json:"network"`
	ExternalWrites bool       `json:"external_writes"`
	Provider       string     `json:"provider"`
	EstimatedCost  *float64   `json:"estimated_cost"`
	ActualCost     *float64   `json:"actual_cost"`
	Artifacts      []Artifact `json:"artifacts"`
	// ContractVersion names the behavioural contract that GOVERNED this run,
	// omitted when the caller named none.
	//
	// Without it, "the host pinned v2" and "the host said nothing and was
	// served under v1" are both ok:true and indistinguishable to a reader of
	// the envelope. That does not lie today, because no v2 guarantee yet
	// differs from v1 here — it becomes a lie the moment one does, and a
	// consumer cannot then tell a v2 guarantee from a v1 coincidence.
	//
	// facet-studio found the same two-states-one-value collapse in their own
	// gate (absent and wrong both reported not-ok) and split it into three
	// outcomes. This is the mirror on the module side: they report which
	// contract they may RELY on, this reports which contract a run was SERVED
	// under.
	//
	// Additive and omitted when absent, per §10: a v1 caller sees exactly what
	// it saw before.
	ContractVersion string `json:"contract_version,omitempty"`
}

type Expectation struct {
	// RequestID the host generated. A module must echo it verbatim.
	RequestID string
	// CostKnown is the capability's declared Effects.CostKnown. When false, a
	// numeric cost in the response is under-reporting, not information.
	CostKnown bool
	// CostKnownSet distinguishes "declared false" from "not supplied", so an
	// absent expectation never silently asserts one.
	CostKnownSet bool
}

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 Job struct {
	JobID      string     `json:"job_id"`
	State      JobState   `json:"state"`
	Capability string     `json:"capability,omitempty"`
	Tool       string     `json:"tool,omitempty"`
	Percent    *float64   `json:"percent"`
	Detail     string     `json:"detail,omitempty"`
	StartedAt  time.Time  `json:"started_at"`
	FinishedAt *time.Time `json:"finished_at,omitempty"`

	// Result and Execution are populated once the job reaches a terminal
	// state, so the terminal poll can carry the authoritative outcome.
	Result    any        `json:"result,omitempty"`
	Error     *Error     `json:"error,omitempty"`
	Execution *Execution `json:"execution,omitempty"`
}

type JobState string

type JobStatusRequest struct {
	RequestID string `json:"request_id"`
	JobID     string `json:"job_id"`

	// Protocol fields the host sends on EVERY invocation. They are modelled
	// rather than acted on here, because decoding is strict: an unmodelled
	// field fails the decode, and the failure path minted a fresh request_id —
	// so the host's id was never echoed and it could not correlate the
	// response.
	//
	// Verified: {"request_id":"req_host_abc","job_id":...} echoed correctly,
	// but the same request carrying protocol and capability did not. This is
	// the identical mistake already fixed on the main request path; polling
	// has its own decoder and never got the fix.
	Protocol       string `json:"protocol,omitempty"`
	Capability     string `json:"capability,omitempty"`
	DeadlineMS     int    `json:"deadline_ms,omitempty"`
	MaxOutputBytes int    `json:"max_output_bytes,omitempty"`
}

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

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 {
	RequestID string          `json:"request_id"`
	Tool      string          `json:"tool"`
	Input     json.RawMessage `json:"input"`
	Consent   *Consent        `json:"consent,omitempty"`
	Seed      *SeedRef        `json:"seed,omitempty"`
	// Binaries maps a declared subprocess name to the ABSOLUTE path the host
	// resolved for it. A module inherits no environment, so this is the only
	// way a binary becomes reachable.
	//
	// An absolute path is an identity; a PATH is a search, and a search can
	// resolve to something the host never authorized. A binary the host could
	// not resolve must be ABSENT rather than empty, so "not supplied" and
	// "supplied as nothing" stay distinguishable.
	Binaries map[string]string `json:"binaries,omitempty"`
	// Async asks a long-running capability to return a job handle immediately
	// rather than blocking until the work completes. Opt-in: existing
	// consumers, including the human-facing CLI, expect a finished result.
	Async bool `json:"async,omitempty"`
	// Roots maps a logical root name declared in permissions.filesystem_* to a
	// canonicalized absolute path the host supplies per invocation. A module
	// resolves nothing itself: `facet_bundle` is how the Remotion composer is
	// found, and resolving it from the working directory made the renderer
	// depend on where the process happened to be launched.
	Roots map[string]Root `json:"roots,omitempty"`

	// The host sets these on every invocation. They are modelled so a strict
	// decoder accepts a real host request: rejecting a field the host always
	// sends would refuse every genuine call, and tolerating unknown fields
	// would silently discard a misspelled `consent`. Both are unacceptable, so
	// the protocol's own fields are named explicitly.
	Protocol string `json:"protocol,omitempty"`
	// ContractVersion is the BEHAVIOURAL contract the host expects, echoed
	// from what it read in the descriptor. Exact match or refusal — see
	// module.ContractVersion.
	ContractVersion string `json:"contract_version,omitempty"`
	Capability      string `json:"capability,omitempty"`
	// Grants are the permissions actually authorized for THIS invocation. A
	// module must assume it has nothing that is not listed.
	Grants *Grants `json:"grants,omitempty"`
	// DeadlineMS is the host's wall-clock budget; it enforces it by killing the
	// process tree regardless, so this is a courtesy rather than a promise.
	DeadlineMS int `json:"deadline_ms,omitempty"`
	// MaxOutputBytes is the stdout ceiling. Facet returns artifact pointers
	// rather than inline payloads, so it is recorded rather than acted on.
	MaxOutputBytes int `json:"max_output_bytes,omitempty"`
}

type Requirement struct {
	Name     string `json:"name"`
	Kind     string `json:"kind"`
	Required bool   `json:"required"`
	For      string `json:"for"`
}

type ReviewState struct {
	TechnicalQA   string `json:"technical_qa"`
	HumanApproved bool   `json:"human_approved"`
	Note          string `json:"note"`
}

type Root struct {
	Path string `json:"path"`
	// Mode is "ro" or "rw"; facet_bundle is always read-only.
	Mode string `json:"mode"`
}

type Seed struct {
	Schema               string   `json:"schema"`
	Goal                 string   `json:"goal,omitempty"`
	Title                string   `json:"title,omitempty"`
	Summary              string   `json:"summary,omitempty"`
	KeyPoints            []string `json:"key_points,omitempty"`
	Attachments          []string `json:"attachments,omitempty"`
	SuggestedOutputTypes []string `json:"suggested_output_types,omitempty"`
	EvidenceDigest       string   `json:"evidence_digest,omitempty"`
}

type SeedAttachment struct {
	Path    string `json:"path"`
	Digest  string `json:"digest,omitempty"`
	Bytes   int    `json:"bytes,omitempty"`
	Missing bool   `json:"missing,omitempty"`
}

type SeedRef struct {
	Schema string `json:"schema"`
	Path   string `json:"path"`
	Digest string `json:"digest"`
}

type SeedResolution struct {
	Schema         string `json:"schema"`
	Path           string `json:"path"`
	DigestExpected string `json:"digest_expected"`
	DigestActual   string `json:"digest_actual"`
	EvidenceDigest string `json:"evidence_digest,omitempty"`
	Verified       bool   `json:"verified"`
	// Attachments the seed named and Facet actually resolved, each with the
	// digest of the bytes on disk.
	//
	// The manifest names attachments relative to the bundle, and the field was
	// parsed and never read: Midden's video_brief — the document written
	// specifically to brief this render — was dropped, and nothing downstream
	// could tell it had existed. An artifact claiming provenance from a seed
	// should say which of the seed's documents it actually had.
	Attachments []SeedAttachment `json:"attachments,omitempty"`
}

type Skill struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	Summary string `json:"summary"`
	Path    string `json:"path"`
	Digest  string `json:"digest"`
	Tokens  int    `json:"tokens"`
}