approval

type AppliedEdit struct {
	Tool         string         `json:"tool"`
	Approver     string         `json:"approver"`
	ProposedKey  string         `json:"proposed_key"`
	ExecutedKey  string         `json:"executed_key"`
	ProposedArgs map[string]any `json:"proposed_args"`
	ExecutedArgs map[string]any `json:"executed_args"`
	Note         string         `json:"note,omitempty"`
}

type Authority string

type ChangeSetChecker struct {
	// Declares reports whether the workload's tool_catalog names this
	// tool.
	Declares func(toolName string) bool

	// Schema resolves the tool's declared input schema by name. It is
	// consulted only for tools Declares accepted.
	Schema func(toolName string) (*jsonschema.Schema, error)
}

type ChangeSetContext struct {
	// Specialist proposed the set; Changes are its calls in order.
	Specialist string           `json:"specialist"`
	Changes    []ProposedChange `json:"changes"`

	// Grantable reports whether `scope: change_set` is admissible for
	// this set, and Ungrantable says why it is not.
	Grantable   bool   `json:"grantable"`
	Ungrantable string `json:"ungrantable,omitempty"`

	// TTLSeconds is how long an approval of the whole set would
	// authorize its remaining calls for.
	TTLSeconds int `json:"ttl_seconds,omitempty"`

	// Preconditions names, per tool, the read each granted call will be
	// re-checked against before it fires — and says plainly where there
	// is none, because "approved for ten minutes" and "approved while
	// the Deployment still has 3 replicas" are very different promises.
	Preconditions map[string]string `json:"preconditions,omitempty"`
}

type Config struct {
	// Policy is the workload's hitl_policy.on_mutation. Required.
	Policy OnMutation

	// Mutating classifies a tool by name. Required. mast passes
	// effects.Predicate's classification so the outbox and the write
	// gate can never disagree about what counts as a mutation — a tool
	// that is recorded as an effect is a tool that needs approval.
	Mutating func(toolName string) bool

	// Gate adjudicates policy for a parked call and validates the
	// operator's verdict. Required when Policy is
	// OnMutationRequireApproval; unused otherwise.
	Gate *permissions.Gate

	// ChangeSet, when non-nil, enforces the change-set producer
	// contract (W7.0): a specialist's report may only carry a
	// proposed_change naming a tool this workload declares, with
	// arguments that satisfy that tool's declared input schema.
	//
	// It rides the write gate rather than being a plugin of its own
	// for the reason W2.4 paid for: every runner construction path
	// already registers this one, and a check that only some paths
	// install is a check with a hole in it. Nil is "this composition
	// has no catalog to check against" — a library embed with no
	// bundle — and leaves reports untouched.
	ChangeSet *ChangeSetChecker

	// Grants, when non-nil, lets one operator answer authorize a whole
	// change set (W7): approving a call that belongs to a recorded set
	// with `scope: change_set` mints a grant for each of the set's
	// other calls, bound to that call's exact signature, and this gate
	// consumes them instead of parking again.
	//
	// The value configures how long such an approval speaks for and
	// how mast re-checks the world before each granted call fires. Nil
	// is W7.0 behaviour: every mutating call is parked on its own, and
	// `scope: change_set` is refused rather than quietly treated as
	// `once` — see grant.go.
	Grants *Freshness

	// Workload names the workload whose bundle composed this gate, and
	// is stamped onto every Decision record so an exported adjudication
	// is legible without the session it came from (v0.4 W8). Optional:
	// a library embed that registers this plugin itself has no bundle to
	// name, and an unnamed workload is a thinner row rather than a
	// missing one.
	Workload string

	// Logger receives the audit trail. Defaults to slog.Default().
	Logger *slog.Logger
}

type Decision struct {
	// DecidedAt is when the gate adjudicated, not when the operator
	// answered — mast does not see the latter.
	DecidedAt time.Time `json:"decided_at"`

	// Session, Workload, Specialist and Invocation are what makes a row
	// legible without the session it came from. A dataset of calls with
	// no context is a dataset of trivia: "someone rejected
	// scale_deployment(api, 10)" is only a label if you can also say
	// which workload was running and which specialist proposed it.
	Session    string `json:"session"`
	Workload   string `json:"workload,omitempty"`
	Specialist string `json:"specialist,omitempty"`
	Invocation string `json:"invocation,omitempty"`

	// FunctionCallID keys the record and is the join back to the
	// transcript's FunctionCall/FunctionResponse pair.
	FunctionCallID string `json:"function_call_id,omitempty"`

	Tool string `json:"tool"`

	// Outcome is the operator's answer. Empty when there was not a
	// readable one — a malformed verdict is recorded rather than
	// dropped, because "clients keep sending mast payloads it cannot
	// read" is itself a finding.
	Outcome Outcome `json:"outcome,omitempty"`
	Scope   Scope   `json:"scope,omitempty"`

	Authority   Authority   `json:"authority"`
	Disposition Disposition `json:"disposition"`

	// Refusal is the machine-readable code the model was told, when the
	// call did not run: denied_by_operator, edit_refused,
	// denied_by_policy, and so on.
	Refusal string `json:"refusal,omitempty"`

	// ChangeSet names the approved set a granted call fired under
	// (Grant.Origin). Empty for an ordinary verdict.
	ChangeSet string `json:"change_set,omitempty"`

	// ProposedKey/ProposedArgs are the call as the model asked for it.
	ProposedKey  string         `json:"proposed_key"`
	ProposedArgs map[string]any `json:"proposed_args,omitempty"`

	// ExecutedKey/ExecutedArgs are set only when they differ from the
	// proposal — that is, on an edit. The proposed→executed pair is the
	// densest signal in the whole record: it is a human writing down
	// what the model should have said.
	ExecutedKey  string         `json:"executed_key,omitempty"`
	ExecutedArgs map[string]any `json:"executed_args,omitempty"`

	Approver string `json:"approver,omitempty"`
	Note     string `json:"note,omitempty"`
}

type Disposition string

type Freshness struct {
	// TTL is how long a minted grant lives. Zero means DefaultGrantTTL.
	TTL time.Duration

	// Now is the clock, for tests. Nil means time.Now.
	Now func() time.Time

	// Precondition returns the freshness declaration for a tool, or
	// nil if it declares none. An error is fail-closed: no grant is
	// minted, and the call parks as it would have before W7.
	Precondition func(toolName string) (*Precondition, error)

	// Read runs a read-only tool and returns its result. Required when
	// any tool declares a precondition; without it a declared
	// precondition cannot be evaluated and no grant is minted.
	Read func(ctx agent.Context, toolName string, args map[string]any) (map[string]any, error)
}

type Grant struct {
	// Signature is the exact call this grant authorizes, in the form
	// Signature renders. The whole grant hangs off this string being
	// byte-identical to the call that later arrives at the gate.
	Signature string `json:"signature"`

	Tool      string         `json:"tool"`
	Arguments map[string]any `json:"arguments"`

	// Origin is the call key of the parked call the operator actually
	// answered, and Approver is who answered it. Together they are the
	// audit answer to "who authorized this, and what were they looking
	// at when they did".
	Origin   string `json:"origin"`
	Approver string `json:"approver,omitempty"`
	Note     string `json:"note,omitempty"`

	MintedAt  time.Time `json:"minted_at"`
	ExpiresAt time.Time `json:"expires_at"`

	// Precondition is the snapshot of the world this grant was issued
	// against, or nil when the tool declares no precondition. Re-read
	// before the call fires.
	Precondition *PreconditionSnapshot `json:"precondition,omitempty"`

	// ConsumedBy is the function call id that spent this grant, and
	// VoidedBy is why it can never be spent (a failed freshness check).
	// Both empty on a live grant; a record is rewritten rather than
	// deleted so the audit trail keeps the whole life of the approval.
	ConsumedBy string `json:"consumed_by,omitempty"`
	VoidedBy   string `json:"voided_by,omitempty"`
}

type OnMutation string

type Outcome string

type Parked struct {
	// Hint is the one-line question the gate wrote.
	Hint string
	// Tool is the parked call's tool name, "" if it could not be read.
	Tool string
	// Args are the arguments the agent proposed.
	Args map[string]any
	// Request is the gate's own payload (an approval.Request), as the
	// map the event log round-trips it to. Nil when the confirmation
	// came from somewhere other than mast's write gate — a tool that
	// calls RequestConfirmation itself, for instance.
	Request map[string]any
}

type Precondition struct {
	// Read names a read-only tool in the same catalog. Refusing a
	// mutating one is the caller's job (internal/compose does it): a
	// freshness check that changes the cluster is not a check.
	Read string `json:"read"`

	// Args are literal arguments for the read.
	Args map[string]any `json:"args,omitempty"`

	// ArgsFrom maps a read argument name to the *change's* argument to
	// take it from, so one declaration covers every call to the tool:
	// {namespace: namespace, name: deployment} turns
	// scale_deployment(deployment=api, namespace=prod, replicas=5) into
	// get_deployment(name=api, namespace=prod).
	//
	// A named argument the change does not carry is an error, not an
	// omission: it means the declaration does not describe this call,
	// and guessing would produce a check against the wrong object.
	ArgsFrom map[string]string `json:"args_from,omitempty"`

	// Fields are dot-separated paths into the read's result, compared
	// individually so an operator is told what moved rather than that
	// something did.
	//
	// Empty means compare the whole result. That is the blunt option
	// and it is the default on purpose: a narrow read
	// (`get_deployment -o jsonpath={.spec.replicas}`) needs no paths,
	// and a broad one that changes on every heartbeat should be
	// narrowed at the source rather than filtered here.
	Fields []string `json:"fields,omitempty"`
}

type PreconditionSnapshot struct {
	Read string         `json:"read"`
	Args map[string]any `json:"args,omitempty"`

	// Digest is a hash of the whole result, always recorded. The result
	// itself is not: it is cluster state, it can be large, and a
	// session log is not where an operator expects to find it.
	Digest string `json:"digest"`

	// Fields are the declared paths and their rendered values, which
	// are recorded in full — they are small, and they are the
	// difference between "something changed" and "replicas went 3 → 5".
	Fields map[string]string `json:"fields,omitempty"`
}

type ProposedChange struct {
	Tool      string         `json:"tool"`
	Arguments map[string]any `json:"arguments"`
}

type Request struct {
	Tool    string         `json:"tool"`
	Args    map[string]any `json:"args"`
	Key     string         `json:"key"`
	Policy  string         `json:"policy"`
	Agent   string         `json:"agent"`
	Verdict map[string]any `json:"verdict_format"`

	// ChangeSet describes the approved-as-a-unit set this call belongs
	// to, when it belongs to one (W7). Present means `scope:
	// change_set` is on the table: the operator is being asked about
	// one call and can authorize the rest with the same answer, and
	// they can only make that trade if they are shown what the rest
	// are.
	ChangeSet *ChangeSetContext `json:"change_set,omitempty"`

	// Stale is why an approval this operator already gave no longer
	// covers this call. Its presence is the difference between "please
	// approve this" and "you approved this, and mast is asking again
	// because the ground moved" — which is the whole point of checking
	// freshness rather than trusting a clock.
	Stale string `json:"stale,omitempty"`
}

type Scope string

type Verdict struct {
	Verdict  Outcome        `json:"verdict"`
	Scope    Scope          `json:"scope,omitempty"`
	Args     map[string]any `json:"args,omitempty"`
	Note     string         `json:"note,omitempty"`
	Approver string         `json:"approver,omitempty"`
}