contract

type ContractFinalPayload ¶

type ContractFinalPayload struct {
	Title       string
	Description string
	Positionals []RuntimeSchemaPositional
	Parameters  []ParamDecl
	Safety      *SafetySpec
	DryRun      *DryRunSpec
	Wait        *WaitSpec
	Result      *ResultSpec
	Pagination  *PaginationSpec
	Interface   *InterfaceSpec
	Selection   *SelectionSpec
	Identity    *ToolIdentitySpec
}

ContractFinalPayload is the Contract-authored final Schema leaf overlay. Registered in-process by the framework via the corecmd/contractfinal seam; Schema assembly reads it as pass-through. No JSON bridge. Treat as read-only after Register.

The Cobra-keyed runtime store and Register live in internal/corecmd/contractfinal (not this DTO package). AnnotateRuntime* writers live in internal/corecmd/runtimeannotate. All callers register via contractfinal.RegisterRuntimeContractFinal directly (corecmd.New registers internally).

type DryRunSpec ¶

type DryRunSpec struct {
	PreviewKind string `json:"preview_kind"`
	RemoteReads bool   `json:"remote_reads,omitempty"`
}

DryRunSpec is a positive capability declaration. A nil ToolSpec.DryRun means the command has not declared reviewed --dry-run support; the Schema does not publish a negative or inferred capability in that case.

The whole object is one atomic contract field. Runtime execution remains owned by the command runner; Schema only projects the reviewed capability.

func (d DryRunSpec) Validate(canonical string) error

type ExampleDisposition ¶

type ExampleDisposition struct {
	Index      *int                         `json:"index"`
	Mode       ExampleDispositionMode       `json:"mode"`
	ReasonCode ExampleDispositionReasonCode `json:"reason_code"`
	Reason     string                       `json:"reason"`
	Reviewed   bool                         `json:"reviewed"`
}

ExampleDisposition narrows one exact example to contract-only validation. Index is a pointer so a missing index cannot silently select example zero.

type ExampleDispositionMode ¶

type ExampleDispositionMode string

ExampleDispositionMode controls how an already contract-validated example is exercised by the Agent example gate.

const (
	ExampleDispositionModeContract     ExampleDispositionMode = "contract"
	ExampleDispositionModeDryRun       ExampleDispositionMode = "dry_run"
	ExampleDispositionModeContractOnly ExampleDispositionMode = "contract_only"
)

type ExampleDispositionReasonCode ¶

type ExampleDispositionReasonCode string

ExampleDispositionReasonCode is the closed taxonomy for reviewed contract-only exceptions to an explicit dry-run capability.

const (
	ExampleDispositionReasonLocalState        ExampleDispositionReasonCode = "local_state"
	ExampleDispositionReasonStatefulPreflight ExampleDispositionReasonCode = "stateful_preflight"
)

type FieldCandidateProvenance ¶

type FieldCandidateProvenance struct {
	Value        json.RawMessage `json:"value,omitempty"`
	Source       string          `json:"source"`
	SourceRef    string          `json:"source_ref,omitempty"`
	Precedence   string          `json:"precedence,omitempty"`
	ReviewReason string          `json:"review_reason,omitempty"`
	Selected     *bool           `json:"selected,omitempty"`
}

FieldCandidateProvenance retains one winning or non-winning source value.

type FieldProvenance ¶

type FieldProvenance struct {
	Value                json.RawMessage            `json:"value,omitempty"`
	Source               string                     `json:"source"`
	SourceRef            string                     `json:"source_ref,omitempty"`
	Precedence           string                     `json:"precedence,omitempty"`
	Resolution           string                     `json:"resolution"`
	ReviewReason         string                     `json:"review_reason,omitempty"`
	Candidates           []FieldCandidateProvenance `json:"candidates,omitempty"`
	OverriddenCandidates []FieldCandidateProvenance `json:"overridden_candidates,omitempty"`
}

FieldProvenance records how one final field was selected. Value is raw JSON so provenance can describe strings, booleans and structured extension values without weakening the resolved ToolSpec itself.

func ResolvedFieldProvenance(value any, source, sourceRef, precedence, resolution, reviewReason string) FieldProvenance

type FormatAlternative ¶ added in v1.0.62

type FormatAlternative struct {
	Format string `json:"format"`
}

FormatAlternative is a format-only JSON Schema anyOf branch. The parameter owns its type; branches describe alternative accepted string formats.

type HelpDocumentation ¶ added in v1.0.61

type HelpDocumentation struct {
	Label string
	URL   string
}

HelpDocumentation is one stable, human-readable documentation link shown in service and leaf Help. It is deliberately not part of SelectionSpec or the public Schema wire: Help references guide further reading without changing the executable command contract.

func SkillDocumentation(label, skill, relativePath string) HelpDocumentation

type HelpReferences ¶ added in v1.0.61

type HelpReferences struct {
	RelatedSkills []string
	Documentation []HelpDocumentation
}

HelpReferences declares the embedded Skills and deeper documentation that are relevant to a product. Leaf Help inherits the declaration by ProductID.

type InterfaceRefSpec ¶

type InterfaceRefSpec struct {
	ProductID string `json:"product_id"`
	RPCName   string `json:"rpc_name"`
}

InterfaceRefSpec identifies the backing operation, independently from the executable command identity.

type InterfaceSpec ¶

type InterfaceSpec struct {
	Ref          *InterfaceRefSpec
	Mode         string
	Availability string
	Reason       string
}

InterfaceSpec describes whether and how the Agent may invoke the backing interface.

func (i InterfaceSpec) AgentExecutable() bool

func (i InterfaceSpec) Validate(canonical string) error

type PaginationSpec ¶ added in v1.0.58

type PaginationSpec struct {
	Kind                  string `json:"kind"`
	CursorParameter       string `json:"cursor_parameter"`
	MetaPath              string `json:"meta_path"`
	EndpointExhaustedPath string `json:"endpoint_exhausted_path"`
	NextTokenPath         string `json:"next_token_path"`
}

PaginationSpec is a command-level declaration for framework pagination metadata. It is deliberately separate from ResultSpec because pagination is emitted under envelope meta, not inside the business response data.

func NormalizePaginationSpec(in *PaginationSpec, canonical string) (*PaginationSpec, error)

type ParamDecl ¶

type ParamDecl struct {
	Name          string
	Property      string
	Required      *bool
	InterfaceType string
	Description   string
	RequiredWhen  string
	Enum          []string
	AnyOf         []FormatAlternative
}

ParamDecl is one parameter-level Schema fact declared on a command. It is stored at DeclareLeafMetadata time and applied as annotations at assembly time, when all flags are guaranteed to exist on the fully-built command tree.

type ProductDecl ¶

type ProductDecl struct {
	ID             string
	Selection      ProductSelectionDecl
	HelpReferences HelpReferences
}

ProductDecl is the product-level Schema routing declaration. Assembly writes ProductSpec.Selection with provenance contract_final. HelpReferences remains internal-only and is consumed exclusively by Help rendering.

func LookupProductDecl(productID string) (ProductDecl, bool)

type ProductSelectionDecl ¶

type ProductSelectionDecl struct {
	AgentSummary string
	UseWhen      []string
	AvoidWhen    []string
}

ProductSelectionDecl is the product-level Agent routing prose declared in code. Fields mirror the leaf SelectionSpec routing triple: agent summary, use-when, and avoid-when.

type ResultOutcome ¶ added in v1.0.58

type ResultOutcome string

ResultOutcome is one closed unified-output envelope outcome.

const (
	ResultOutcomeSuccess        ResultOutcome = "success"
	ResultOutcomePending        ResultOutcome = "pending"
	ResultOutcomePartialFailure ResultOutcome = "partial_failure"
	ResultOutcomeFailure        ResultOutcome = "failure"
)

type ResultSpec ¶ added in v1.0.58

type ResultSpec struct {
	Outcomes       []ResultOutcome `json:"outcomes"`
	DataSchema     json.RawMessage `json:"data_schema"`
	SensitivePaths []string        `json:"sensitive_paths,omitempty"`
}

ResultSpec is the reviewed return-value contract for one command and is projected unchanged into both full-leaf and compact-leaf Schema. Outcomes and DataSchema are required; Pagination and SensitivePaths are omitted when absent. DataSchema is a canonical recursive JSON Schema object; every path is relative to the unified-output envelope data value.

func NormalizeResultSpec(in *ResultSpec, canonical string) (*ResultSpec, error)

type RuntimeSchemaConstraints ¶ added in v1.0.63

type RuntimeSchemaConstraints struct {
	MutuallyExclusive [][]string `json:"mutually_exclusive,omitempty"`
	RequireOneOf      [][]string `json:"require_one_of,omitempty"`
	RequireTogether   [][]string `json:"require_together,omitempty"`
}

RuntimeSchemaConstraints describes cross-parameter rules that cannot be represented by an individual parameter's required bit.

func NormalizeRuntimeSchemaConstraints(constraints RuntimeSchemaConstraints) RuntimeSchemaConstraints

type RuntimeSchemaPositional ¶

type RuntimeSchemaPositional struct {
	Name        string `json:"name"`
	Type        string `json:"type,omitempty"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required"`
	Variadic    bool   `json:"variadic,omitempty"`
	Index       int    `json:"index"`
}

RuntimeSchemaPositional describes one ordered CLI argument. Name is also used by RuntimeSchemaConstraints when a one-of group mixes flags and args.

type SafetySpec ¶

type SafetySpec struct {
	Effect       string
	EffectSource string
	Risk         string
	Confirmation string
	Idempotency  string
}

SafetySpec is the resolved operation behavior. This model deliberately does not impose a value lattice: precedence policy belongs to the resolver, so a reviewed higher-priority source may intentionally raise or lower a value.

type SelectionSpec ¶

type SelectionSpec struct {
	AgentSummary       string
	AgentSummarySource string
	UseWhen            []string
	AvoidWhen          []string
	Prerequisites      []string
	Tips               []string
	WorkflowRefs       []string
	Examples           []string
	// ExampleDispositions narrows an exact example with a reviewed local or
	// stateful precondition from dry-run execution to contract validation.
	// It does not change the command's declared DryRun capability.
	ExampleDispositions []ExampleDisposition
	// Reviewed is a legacy-path (hints/registry) marker only. The Contract
	// declaration path must not set it: declared selection is final by
	// construction, and assembly rejects a declared payload carrying it.
	Reviewed       *bool
	SourceRefs     []string
	MetadataSource string
}

SelectionSpec contains Agent command-selection guidance. Product specs use the common summary/use/avoid/source subset; tool specs may use every field.

func ProductSelectionFromDecl(decl ProductDecl) (SelectionSpec, map[string]FieldProvenance)

func (s SelectionSpec) Normalized() SelectionSpec

type ToolIdentitySpec ¶

type ToolIdentitySpec struct {
	ProductID       string
	SourceProductID string
	Name            string
	CLIName         string
	CanonicalPath   string
	Path            string
	CLIPath         string
	PrimaryCLIPath  string
	Group           string
	Aliases         []string
	IsAlias         bool
	Source          string
}

ToolIdentitySpec contains only command identity. It is intentionally separate from interface identity: an executable Cobra leaf and an RPC are related by InterfaceSpec, but are not interchangeable sources of truth.

type WaitSpec ¶ added in v1.0.63

type WaitSpec struct {
	Mode          string                   `json:"mode"`
	PollCommand   string                   `json:"poll_command,omitempty"`
	StatusQuery   string                   `json:"status_query"`
	Terminal      map[string]ResultOutcome `json:"terminal"`
	PendingValues []string                 `json:"pending_values,omitempty"`
	// EventKey is the push channel key the WaitEvents hook subscribes to
	// (event/auto modes). Declared for the catalog; the transport stays
	// leaf-owned.
	EventKey string `json:"event_key,omitempty"`
	// MatchField is the event-document path holding the resource identifier
	// (event/auto modes); its value must equal the ResourceQuery resolution
	// of the accepted result.
	MatchField string `json:"match_field,omitempty"`
	// ResourceQuery is the dotted path into the accepted result data that
	// yields the resource identifier correlated against MatchField
	// (event/auto modes).
	ResourceQuery string `json:"resource_query,omitempty"`
	// DefaultTimeoutSecs is the reviewed default for --wait-timeout. Zero
	// means the framework default (300s); the user flag always wins.
	DefaultTimeoutSecs int `json:"default_timeout_secs"`
}

WaitSpec is a positive capability declaration for terminal-state waiting (approval flows, async exports, batch jobs). A nil ToolSpec.Wait means the command has not declared reviewed --wait support; the flag is not registered and the Schema does not publish the capability.

Like DryRunSpec, the object is one atomic contract field: Schema only projects the reviewed capability; runtime execution stays owned by the command runner through the leaf's WaitPoll / WaitEvents hooks. PollCommand names the read command that observes status — it is a declared, catalog-visible fact (the same command an agent would poll manually), not a framework-owned invocation: how one poll or event subscription executes is decided by the leaf.

func NormalizeWaitSpec(in *WaitSpec, canonical string) (*WaitSpec, error)

func (w WaitSpec) Validate(canonical string) error