cli

type AgentExampleDisposition ¶ added in v1.0.57

type AgentExampleDisposition = contract.ExampleDisposition

AgentExampleDisposition narrows one exact example with an explicit typed dry-run capability to contract-only. Index is a pointer so a missing field cannot silently select example zero.

Dispositions are authored on the owning ContractFinal Selection.

type AgentExampleDispositionSource ¶ added in v1.0.57

type AgentExampleDispositionSource string

AgentExampleDispositionSource distinguishes the normal typed-contract classification from narrow reviewed exceptions.

const (
	AgentExampleDispositionDefault  AgentExampleDispositionSource = "default"
	AgentExampleDispositionReviewed AgentExampleDispositionSource = ProvenanceReviewedManual
)

type AgentExampleExecution ¶ added in v1.0.57

type AgentExampleExecution struct {
	CanonicalPath string
	Index         int
	Example       string
	Mode          AgentExampleMode
	DryRun        *contract.DryRunSpec
	ReasonCode    AgentExampleReasonCode
	Reason        string
	Source        AgentExampleDispositionSource
}

AgentExampleExecution is one resolved example and its effective test mode.

type AgentExampleExecutionPlan ¶ added in v1.0.57

type AgentExampleExecutionPlan struct {
	Examples             []AgentExampleExecution
	Total                int
	Contract             int
	DryRun               int
	ContractOnly         int
	ReviewedContractOnly int
	ContractOnlyByReason map[AgentExampleReasonCode]int
}

AgentExampleExecutionPlan is a stable, typed report used by the exhaustive real-Cobra dry-run test.

func BuildAgentExampleExecutionPlan(bound BoundCommandRegistry, registry SchemaRegistry) (AgentExampleExecutionPlan, error)

func ValidateAgentExampleDelivery(bound BoundCommandRegistry, registry SchemaRegistry) (AgentExampleExecutionPlan, error)

type AgentExampleMode ¶ added in v1.0.57

type AgentExampleMode = contract.ExampleDispositionMode

AgentExampleMode controls only how an already contract-validated example is exercised. Contract validation is the default. dry_run is used only when the final ToolSpec publishes an explicit reviewed capability; contract_only remains a precise reviewed exception for such a capability whose runtime preconditions cannot be exercised safely and deterministically in the isolated test process.

type AgentExampleReasonCode ¶ added in v1.0.57

type AgentExampleReasonCode = contract.ExampleDispositionReasonCode

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

type AgentSelectionCase ¶ added in v1.0.57

type AgentSelectionCase struct {
	ID                  string   `json:"id"`
	ProductID           string   `json:"product_id"`
	Scenario            string   `json:"scenario"`
	ExpectedCanonical   string   `json:"expected_canonical,omitempty"`
	ForbiddenCanonical  string   `json:"forbidden_canonical,omitempty"`
	CandidateCanonicals []string `json:"candidate_canonicals"`
}

AgentSelectionCase is one reproducible model-evaluation assertion derived from ContractFinal Selection prose. Positive cases require one exact canonical result; negative cases only forbid the command that owns the avoid_when text. CandidateCanonicals contains every bound tool in the same product, in stable order.

type AgentSelectionFixture ¶ added in v1.0.57

type AgentSelectionFixture struct {
	Version int                  `json:"version"`
	Cases   []AgentSelectionCase `json:"cases"`
}

AgentSelectionFixture is the stable input to an optional live Agent evaluation. It is built from contract.ProductDecl/ContractFinal selection prose and the real bound command tree; it is not a second authored hint source.

type AgentSelectionReport ¶ added in v1.0.57

type AgentSelectionReport struct {
	Tools              int
	PositiveAssertions int
	NegativeAssertions int
	FixtureSHA256      string
}

AgentSelectionReport records deterministic coverage and the exact fixture digest. It proves that all reviewed assertions are well-formed and executable; it deliberately does not claim that a language model understood their natural-language meaning.

func ValidateAgentSelectionContract(bound BoundCommandRegistry) (AgentSelectionReport, error)

type AgentToolSelection ¶ added in v1.0.57

type AgentToolSelection struct {
	AgentSummary        string                    `json:"agent_summary"`
	UseWhen             []string                  `json:"use_when"`
	AvoidWhen           []string                  `json:"avoid_when"`
	Examples            []string                  `json:"examples"`
	ExampleDispositions []AgentExampleDisposition `json:"example_dispositions,omitempty"`
	Reviewed            bool                      `json:"reviewed"`
	Revision            string                    `json:"revision"`
	Reason              string                    `json:"reason"`
	Evidence            []string                  `json:"evidence"`
}

AgentToolSelection is the tool-level selection projection used by example planning and live-selection fixtures. Production authority remains ContractFinal Selection on the owning leaf.

type AliasKind ¶ added in v1.0.52

type AliasKind string

AliasKind records how a reviewed alias path is represented by Cobra. A Cobra alias resolves to the primary command pointer; a compatibility leaf is a separately registered (usually hidden) runnable command. Keeping the two forms explicit prevents downstream code from assuming that every alias has its own Cobra leaf.

const (
	AliasKindCobraAlias        AliasKind = "cobra_alias"
	AliasKindCompatibilityLeaf AliasKind = "compatibility_leaf"
)

type BoundAlias ¶ added in v1.0.52

type BoundAlias struct {
	Path         string
	Command      *cobra.Command
	Kind         AliasKind
	Source       string
	ReviewReason string
}

BoundAlias is one reviewed alias path resolved against the live Cobra tree.

type BoundCommandRegistry ¶ added in v1.0.52

type BoundCommandRegistry struct {
	Commands    []BoundCommandSpec
	ByCanonical map[string]BoundCommandSpec
	ByCLIPath   map[string]BoundCommandSpec
}

BoundCommandRegistry is the only command input the Schema assembler should consume. Every entry has passed exact path, executable-leaf, collision, and native-annotation consistency checks.

func BindEffectiveCommandRegistry(root *cobra.Command, effective EffectiveCommandRegistry) (BoundCommandRegistry, error)

type BoundCommandSpec ¶ added in v1.0.52

type BoundCommandSpec struct {
	CommandSpec
	PrimaryCommand *cobra.Command
	AliasCommands  []BoundAlias
}

BoundCommandSpec joins one stable registry identity to its executable primary leaf and all executable alias paths.

type CommandIdentity ¶ added in v1.0.55

type CommandIdentity struct {
	CLIPath   string   // "dev app delete"
	Canonical string   // "dev.delete_dev_app"
	Aliases   []string // ["search", ...]
	ProductID string   // "devapp"
	Title     string   // one-line description
}

CommandIdentity is the stable identity of a command.

type CommandMeta ¶ added in v1.0.55

type CommandMeta struct {
	Identity  CommandIdentity
	Safety    CommandSafety
	Selection CommandSelection
}

CommandMeta is the complete runtime metadata view for a single command. Consumers read this struct; they never touch the raw catalog maps.

func ResolveMeta(cliPath string) (CommandMeta, bool)

type CommandOverride ¶ added in v1.0.56

type CommandOverride struct {
	CommandPath   string
	Bind          map[string]string
	ScopedAliases map[string]string
	Block         []string
	Ambiguous     []string
	Confirm       bool
	ScopeStrict   bool
	Investigate   bool
	Note          string
}

CommandOverride is one reviewed per-command adjustment: binding a generic real flag to a concept, command-scoped aliases, blocks, and the reviewed co-occurrence whitelist.

type CommandPathFallback ¶ added in v1.0.58

type CommandPathFallback struct {
	From         string                  `json:"from"`
	Mode         CommandPathFallbackMode `json:"mode"`
	To           string                  `json:"to,omitempty"`
	Candidates   []string                `json:"candidates,omitempty"`
	Reviewed     bool                    `json:"reviewed"`
	ReviewReason string                  `json:"review_reason"`
}

CommandPathFallback is one validated, generated runtime recovery record. From is never advertised as a stable alias. To and Candidates are canonical real Cobra paths validated at generation time.

func LoadCommandPathFallbacks() ([]CommandPathFallback, error)

func LookupCommandPathFallback(rawPath string) (CommandPathFallback, bool)

func ReduceCommandPathFallbacks(root *cobra.Command) ([]CommandPathFallback, error)

type CommandPathFallbackMode ¶ added in v1.0.58

type CommandPathFallbackMode string

CommandPathFallbackMode determines whether an invalid reviewed path can be normalized exactly or must stop and surface reviewed candidates.

const (
	CommandPathFallbackRewrite   CommandPathFallbackMode = "rewrite"
	CommandPathFallbackAmbiguous CommandPathFallbackMode = "ambiguous"
)

type CommandRegistry ¶ added in v1.0.52

type CommandRegistry struct {
	Commands    []CommandSpec
	ByCLIPath   map[string]CommandSpec
	ByCanonical map[string]CommandSpec
}

CommandRegistry is an indexed command identity set.

func (registry CommandRegistry) SourceHash() string

type CommandSafety ¶ added in v1.0.55

type CommandSafety struct {
	Effect       string // read / write / destructive
	Risk         string // low / medium / high
	Confirmation string // not_required / user_required
	Idempotency  string // idempotent / non_idempotent
}

CommandSafety holds the safety metadata for a CLI command, resolved at runtime via ResolveMeta. This is a read-only view — NOT a second safety source. Production Meta is projected from the runtime-assembled SchemaRegistry into a cached map[cli_path]CommandMeta during deliverySchemaCatalog's sync.Once; steady-state ResolveMeta / leaf --help are O(1) map lookups (同源 with assembly, not a separate gob authority).

func SafetyForCLIPath(cliPath string) (CommandSafety, bool)

func (s CommandSafety) ShouldRender() bool

type CommandSelection ¶ added in v1.0.55

type CommandSelection struct {
	AgentSummary string
	UseWhen      []string
	AvoidWhen    []string
	Examples     []string
}

CommandSelection is the agent-facing selection metadata.

type CommandSpec ¶ added in v1.0.52

type CommandSpec struct {
	CanonicalPath   string
	SourceProductID string
	PrimaryCLIPath  string
	Aliases         []string
	Visibility      SchemaVisibility
	Source          string
	ReviewReason    string
}

CommandSpec is one command identity. Identity and navigation are deliberately kept together so no downstream renderer can independently invent a canonical name, primary path, or alias.

type Concept ¶ added in v1.0.56

type Concept struct {
	ID            string
	Denotes       string
	CanonicalHint string
	Members       []string
	Excludes      []string
	Commands      []string
	Risk          string
}

Concept is one reviewed set of equivalent flag spellings that all denote a single entity. Members reduce onto the command's real flag; Excludes lists spellings that denote a different entity and must never be reduced in.

type EffectiveCommandRegistry ¶ added in v1.0.52

type EffectiveCommandRegistry struct {
	Commands    []CommandSpec
	ByCLIPath   map[string]CommandSpec
	ByCanonical map[string]CommandSpec
}

EffectiveCommandRegistry is the collected command identity registry after indexing. It remains independent of Cobra; binding is a separate fail-closed step.

func BuildEffectiveCommandRegistry(root *cobra.Command) (EffectiveCommandRegistry, error)

func BuildEffectiveFromSpecs(specs []CommandSpec) (EffectiveCommandRegistry, error)

func (registry EffectiveCommandRegistry) SourceHash() string

type FixtureAgentProductSelection ¶ added in v1.0.57

type FixtureAgentProductSelection struct {
	AgentSummary string   `json:"agent_summary"`
	UseWhen      []string `json:"use_when"`
	AvoidWhen    []string `json:"avoid_when"`
	Reviewed     bool     `json:"reviewed"`
	Revision     string   `json:"revision"`
	Reason       string   `json:"reason"`
	Evidence     []string `json:"evidence"`
}

FixtureAgentProductSelection is retained for transitional fixtures only.

type FixtureAgentSelectionRevision ¶ added in v1.0.57

type FixtureAgentSelectionRevision struct {
	GeneratedBy   string `json:"generated_by"`
	Model         string `json:"model,omitempty"`
	PromptVersion string `json:"prompt_version,omitempty"`
	Reason        string `json:"reason"`
}

FixtureAgentSelectionRevision is retained for transitional fixtures only.

type FixtureAgentSelectionSet ¶ added in v1.0.57

type FixtureAgentSelectionSet struct {
	Revisions map[string]FixtureAgentSelectionRevision `json:"revisions,omitempty"`
	Products  map[string]FixtureAgentProductSelection  `json:"products,omitempty"`
	Tools     map[string]AgentToolSelection            `json:"tools,omitempty"`
}

FixtureAgentSelectionSet is a transitional Agent selection fixture type retained only so live-selection call sites can project candidate tables. Production paths must keep it empty; example planning reads ContractFinal.

type IdentityCollectionReport ¶ added in v1.0.57

type IdentityCollectionReport struct {
	Leaves          int      // runnable leaves walked (hidden included)
	WithIdentity    int      // primary leaves carrying a ContractFinal.Identity
	HiddenPrimaries int      // collected primaries that are Hidden deprecated/migration shims
	Excluded        int      // leaves matched by reviewed exclusions
	NoIdentity      []string // leaves without Identity (alias / compatibility / deprecated; informational)
	MissingPrimary  []string // canonicals with no collected primary (populated by spec-set comparisons)
}

IdentityCollectionReport summarises a collection walk.

type InterfaceRefKey ¶ added in v1.0.52

type InterfaceRefKey struct {
	ProductID string
	RPCName   string
}

InterfaceRefKey is the exact, typed identity of an embedded MCP operation. It is deliberately independent from a CLI canonical path: multiple commands may explicitly project the same operation.

type InterfaceRegistry ¶ added in v1.0.52

type InterfaceRegistry struct {
	ByCanonical    map[string]InterfaceRegistryEntry
	ByInterfaceRef map[InterfaceRefKey][]string
}

InterfaceRegistry is the typed interface fact model for optional MCP-shaped fixtures. ByCanonical supports exact navigation; ByInterfaceRef answers whether an explicitly selected (product_id, rpc_name) exists.

type InterfaceRegistryEntry ¶ added in v1.0.52

type InterfaceRegistryEntry struct {
	CanonicalPath string
	Ref           contract.InterfaceRefSpec
	Metadata      embeddedMCPToolMetadata
}

InterfaceRegistryEntry is one operation projection from an optional diagnostic MCP-shaped map (tests / fetch dumps). CanonicalPath is a lookup key, not command identity. Production assembly does not build this from a committed pin.

type ParamAliasEntry ¶ added in v1.0.56

type ParamAliasEntry struct {
	CLIPath   string            `json:"cli_path"`
	Aliases   map[string]string `json:"aliases,omitempty"`
	Blocked   []string          `json:"blocked,omitempty"`
	Ambiguous []string          `json:"ambiguous,omitempty"`
}

ParamAliasEntry is the reduced parameter-alias table for one runnable Cobra leaf. It is the typed value the build-time generator serializes into param_aliases_generated.go and that the runtime normalizer (P2) consumes.

Aliases maps an already-morphed emitted name to the command's canonical real flag; the runtime looks up Morph(emitted) here to resolve a synonym. Blocked lists morphed names that must never be reduced (they route to did-you-mean), and Ambiguous lists morphed names that a reviewed co-occurrence guard leaves unresolved on purpose.

func LookupParamAlias(rawCommandPath string) (ParamAliasEntry, bool)

func ReduceParamAliases(root *cobra.Command) ([]ParamAliasEntry, error)

func (e ParamAliasEntry) IsAmbiguous(morphed string) bool

func (e ParamAliasEntry) IsBlocked(morphed string) bool

func (e ParamAliasEntry) ResolveAlias(morphed string) (string, bool)

type ParamConcepts ¶ added in v1.0.56

type ParamConcepts struct {
	Version   int
	Morph     map[string]ParamMorphRule
	Concepts  []Concept
	ByConcept map[string]Concept
	Overrides []CommandOverride
	Fixture   []ParamFixtureCase
}

ParamConcepts is the decoded, validated reviewed concept dictionary.

func LoadParamConcepts() (ParamConcepts, error)

type ParamFixtureCase ¶ added in v1.0.56

type ParamFixtureCase struct {
	Command string
	Emitted string
	Expect  string
	Via     string
	Occ     int
}

ParamFixtureCase is one reviewed regression assertion derived from evaluation bad cases: the emitted name on Command must reduce to Expect (a real flag) or route to a did-you-mean sentinel.

type ParamMorphRule ¶ added in v1.0.56

type ParamMorphRule struct {
	Desc    string `json:"desc"`
	Enabled bool   `json:"enabled"`
	Guard   string `json:"guard,omitempty"`
	Reason  string `json:"reason,omitempty"`
}

ParamMorphRule documents one table-free name normalization behavior. It is evidence for the shared Morph function; it is not a per-command alias.

type ParameterSpec ¶ added in v1.0.52

type ParameterSpec struct {
	Name                 string
	Type                 string
	Description          string
	Property             string
	Required             bool
	CLIRequired          bool
	RequiredWhen         string
	Default              json.RawMessage
	InterfaceDefault     json.RawMessage
	Example              json.RawMessage
	Format               string
	Enum                 []string
	InterfaceDescription string
	InterfaceType        string
	FieldProvenance      map[string]contract.FieldProvenance
}

ParameterSpec is one resolved CLI flag projection. Name is the CLI flag key used in the legacy parameters object. Default and Example are RawMessage because JSON literals are polymorphic; they are still typed JSON values and never participate in precedence as map[string]any.

func (p ParameterSpec) ToPayload() (map[string]any, error)

type ProductSpec ¶ added in v1.0.52

type ProductSpec struct {
	ID              string
	Name            string
	Description     string
	Runtime         bool
	Tools           []ToolSpec
	Selection       contract.SelectionSpec
	FieldProvenance map[string]contract.FieldProvenance
}

ProductSpec is one deterministic product grouping in SchemaRegistry.

func (p ProductSpec) ToPayload() (map[string]any, error)

func (p ProductSpec) ToSummaryPayload() (map[string]any, error)

type ResolvedSchemaBuild ¶ added in v1.0.52

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

ResolvedSchemaBuild is the single source-to-delivery hand-off used by the Catalog generator. Effective, Bound, and Registry are three views of one resolution pass: reviewed identity, executable Cobra binding, and the final typed Agent contract. Downstream gates and serializers must consume this value instead of rebuilding any view from the command tree.

The command root is intentionally private. It lets delivery completeness inspect the same executable tree without allowing callers to construct a seemingly resolved build by assembling the exported fields themselves.

func ResolveSchemaBuild(root *cobra.Command) (ResolvedSchemaBuild, error)

func (resolved ResolvedSchemaBuild) CommandCount() int

func (resolved ResolvedSchemaBuild) RegistryHash() string

type RuntimeCompatibilityEquivalence ¶ added in v1.0.52

type RuntimeCompatibilityEquivalence struct {
	ID       string `json:"id"`
	Reason   string `json:"reason"`
	Reviewed bool   `json:"reviewed"`
}

RuntimeCompatibilityEquivalence is an implementation-side review record for two separately registered Cobra leaves that intentionally share one Schema identity despite using different execution handlers. Registry alias review alone is not enough: different handlers may inject fixed arguments or route to different business operations while exposing identical flags.

type RuntimeSchemaCompletenessReport ¶ added in v1.0.52

type RuntimeSchemaCompletenessReport struct {
	Covered           []string
	Excluded          []string
	Missing           []string
	InvalidExclusions []string
	StaleExclusions   []string
	DeliveryErrors    []string
}

RuntimeSchemaCompletenessReport compares the public executable Cobra leaves with a reviewed Schema command set, such as runtime annotations or the final generated Catalog.

func RuntimeSchemaCompleteness(root *cobra.Command, exclusions []RuntimeSchemaExclusion) RuntimeSchemaCompletenessReport

type RuntimeSchemaConstraints ¶ added in v1.0.52

type RuntimeSchemaConstraints = runtimeannotate.RuntimeSchemaConstraints

type RuntimeSchemaExclusion ¶ added in v1.0.52

type RuntimeSchemaExclusion struct {
	CLIPath  string
	Reason   string
	Reviewed bool
}

RuntimeSchemaExclusion records a reviewed reason why a public executable command is intentionally not advertised as an Agent tool.

func ReviewedRuntimeSchemaExclusions() ([]RuntimeSchemaExclusion, error)

type RuntimeSchemaParameterMetadata ¶ added in v1.0.52

type RuntimeSchemaParameterMetadata struct {
	Inherited    []string
	Required     []string
	RequiredWhen map[string]string
	Formats      map[string]string
	Enums        map[string][]string
	Examples     map[string]string
}

RuntimeSchemaParameterMetadata contains reviewed CLI parameter semantics that Cobra cannot represent by itself. It is an independent generation input: generated Catalog data is never read back into this registry.

type RuntimeToolSpecInput ¶ added in v1.0.52

type RuntimeToolSpecInput struct {
	Identity        contract.ToolIdentitySpec
	Display         string
	Title           string
	Description     string
	MetadataSource  string
	Parameters      []ParameterSpec
	Constraints     RuntimeSchemaConstraints
	Positionals     []contract.RuntimeSchemaPositional
	DryRun          *contract.DryRunSpec
	Result          *contract.ResultSpec
	Pagination      *contract.PaginationSpec
	Safety          contract.SafetySpec
	Interface       contract.InterfaceSpec
	Selection       contract.SelectionSpec
	FieldProvenance map[string]contract.FieldProvenance
}

RuntimeToolSpecInput is the typed hand-off from runtime source resolution to contract assembly. Adapters resolve candidates first, then call ToolSpecFromRuntime exactly once; payload rendering does no further merging.

type SchemaCatalogBuildOptions ¶ added in v1.0.52

type SchemaCatalogBuildOptions struct {
	RegistryHash string
}

SchemaCatalogBuildOptions carries release-envelope inputs which are checked against the effective reviewed CommandRegistry. The command set is not an option: visibility is resolved by EffectiveCommandRegistry before assembly, and every public command must be delivered.

type SchemaCatalogSnapshot ¶ added in v1.0.52

type SchemaCatalogSnapshot struct {
	Version     int                       `json:"version"`
	SourceHash  string                    `json:"source_hash"`
	SurfaceHash string                    `json:"surface_hash,omitempty"`
	Catalog     map[string]any            `json:"catalog"`
	Tools       map[string]map[string]any `json:"tools"`
}

SchemaCatalogSnapshot is the release-stable Agent contract. Catalog holds the progressive product/tool index; Tools holds full leaf parameter schemas. It intentionally contains no endpoint, credential, or runtime cache data.

func BuildSchemaCatalogSnapshot(resolved ResolvedSchemaBuild, options SchemaCatalogBuildOptions) (SchemaCatalogSnapshot, error)

type SchemaIndex ¶ added in v1.0.52

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

SchemaIndex is the immutable navigation view over one normalized registry. It mirrors Lark's typed catalog split: SchemaRegistry owns data, SchemaIndex owns deterministic identity/path resolution, and serializers only render a resolved ToolSpec.

func (i SchemaIndex) CanonicalPaths() []string

func (i SchemaIndex) Product(id string) (ProductSpec, bool)

func (i SchemaIndex) Registry() SchemaRegistry

func (i SchemaIndex) Resolve(path string) (ToolSpec, bool)

func (i SchemaIndex) ResolveQuery(path string) (ToolSpec, bool)

type SchemaMetaIndexEntry ¶ added in v1.0.57

type SchemaMetaIndexEntry struct {
	CLIPath      string   `json:"cli_path"`
	Canonical    string   `json:"canonical_path"`
	Aliases      []string `json:"aliases,omitempty"`
	ProductID    string   `json:"product_id,omitempty"`
	Title        string   `json:"title,omitempty"`
	Effect       string   `json:"effect,omitempty"`
	Risk         string   `json:"risk,omitempty"`
	Confirmation string   `json:"confirmation,omitempty"`
	Idempotency  string   `json:"idempotency,omitempty"`
	AgentSummary string   `json:"agent_summary,omitempty"`
	UseWhen      []string `json:"use_when,omitempty"`
	AvoidWhen    []string `json:"avoid_when,omitempty"`
	Examples     []string `json:"examples,omitempty"`
}

SchemaMetaIndexEntry is one primary-path CommandMeta record. Aliases are expanded into the ResolveMeta lookup at decode time.

type SchemaMetaIndexSnapshot ¶ added in v1.0.57

type SchemaMetaIndexSnapshot struct {
	Version     int                    `json:"version"`
	SourceHash  string                 `json:"source_hash"`
	SurfaceHash string                 `json:"surface_hash,omitempty"`
	Entries     []SchemaMetaIndexEntry `json:"entries"`
}

SchemaMetaIndexSnapshot is the CommandMeta summary shape written by CI Catalog dumps for determinism checks. Runtime delivery does not embed or decode this artifact.

func BuildSchemaMetaIndex(snapshot SchemaCatalogSnapshot) (SchemaMetaIndexSnapshot, error)

func DecodeSchemaMetaIndex(data []byte) (SchemaMetaIndexSnapshot, error)

func DecodeSchemaMetaIndexJSON(data []byte) (SchemaMetaIndexSnapshot, error)

type SchemaMetadataLoadCounts ¶ added in v1.0.52

type SchemaMetadataLoadCounts struct {
	Catalog          uint64
	MetaIndex        uint64
	AgentMetadata    uint64
	ParameterBinding uint64
}

SchemaMetadataLoadCounts exposes read-only diagnostics for startup tests and profiling. Counts are incremented only when a lazy delivery snapshot is assembled / projected for the first time.

func RuntimeSchemaMetadataLoadCounts() SchemaMetadataLoadCounts

type SchemaRegistry ¶ added in v1.0.52

type SchemaRegistry struct {
	Kind          string
	Level         string
	Source        string
	Products      []ProductSpec
	AgentMetadata json.RawMessage
}

SchemaRegistry is the resolved, typed Agent contract. Source adapters and precedence resolvers populate this model; wire payloads are rendered only at the outer boundary by ToPayload. This keeps map[string]any out of the contract assembly path.

func AssembleSchemaRegistry(root *cobra.Command) (SchemaRegistry, error)

func AssembleSchemaRegistryFromBound(bound BoundCommandRegistry) (SchemaRegistry, error)

func SchemaRegistryFromRuntime(source string, products []ProductSpec) (SchemaRegistry, error)

func (r SchemaRegistry) Index() (SchemaIndex, error)

func (r SchemaRegistry) Sorted() SchemaRegistry

func (r SchemaRegistry) ToOverviewPayload() (map[string]any, error)

func (r SchemaRegistry) ToPayload() (map[string]any, error)

func (r SchemaRegistry) ToSnapshotPayload() (SchemaSnapshotPayload, error)

type SchemaSnapshotPayload ¶ added in v1.0.52

type SchemaSnapshotPayload struct {
	Catalog map[string]any
	Tools   map[string]map[string]any
}

SchemaSnapshotPayload is the final wire boundary for the release snapshot. Catalog summaries and full Tools are both derived from the same typed ToolSpec instances, preventing the two snapshot layers from drifting.

type SchemaVisibility ¶ added in v1.0.52

type SchemaVisibility string

SchemaVisibility is the reviewed CommandRegistry visibility class for a command identity.

const (
	SchemaVisibilityPublic   SchemaVisibility = "public"
	SchemaVisibilityCompat   SchemaVisibility = "compat"
	SchemaVisibilityInternal SchemaVisibility = "internal"
)

type StdinGuard ¶

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

StdinGuard ensures stdin is consumed at most once per command invocation. Multiple flags using @- or implicit stdin fallback would race on the same reader; StdinGuard detects and rejects the second claim with a clear error.

func NewStdinGuard() *StdinGuard

func (g *StdinGuard) Claim(source string) error

func (g *StdinGuard) Claimed() bool

type ToolSpec ¶ added in v1.0.52

type ToolSpec struct {
	Identity        contract.ToolIdentitySpec
	Display         string
	Title           string
	Description     string
	MetadataSource  string
	Parameters      []ParameterSpec
	Constraints     RuntimeSchemaConstraints
	Positionals     []contract.RuntimeSchemaPositional
	DryRun          *contract.DryRunSpec
	Result          *contract.ResultSpec
	Pagination      *contract.PaginationSpec
	Safety          contract.SafetySpec
	Interface       contract.InterfaceSpec
	Selection       contract.SelectionSpec
	FieldProvenance map[string]contract.FieldProvenance
}

ToolSpec is the single assembled representation of a command contract. Safety, interface and selection are typed sub-models even though ToPayload preserves the historical flat JSON shape for compatibility.

func ToolSpecFromRuntime(input RuntimeToolSpecInput) (ToolSpec, error)

func (t ToolSpec) ToPayload() (map[string]any, error)

func (t ToolSpec) ToSummaryPayload() (map[string]any, error)

func (t ToolSpec) Validate() error