cli

package
v1.0.63 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 3, 2026 License: Apache-2.0 Imports: 43 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	AgentExampleModeContract     = contract.ExampleDispositionModeContract
	AgentExampleModeDryRun       = contract.ExampleDispositionModeDryRun
	AgentExampleModeContractOnly = contract.ExampleDispositionModeContractOnly
)
View Source 
const (
	AgentExampleReasonLocalState        = contract.ExampleDispositionReasonLocalState
	AgentExampleReasonStatefulPreflight = contract.ExampleDispositionReasonStatefulPreflight
)
View Source 
const (
	ProvenanceEmbeddedSkillMetadata = "embedded-skill-metadata"
	ProvenanceReviewedManual        = "reviewed_manual"
)

Wire provenance / metadata_source labels (#602 Catalog contract). Const identifiers may be renamed; the string values must not change.

View Source 
const CommandSourceContractIdentity = "contract_identity"

CommandSourceContractIdentity is the delivery source label for command identity collected from ContractFinal.Identity declarations. The collector (CollectIdentitySpecs) is the single identity source since the reviewed schema_command_registry retirement.

View Source 
const (

	// DefaultSchemaCacheBuilderTimeout defines the maximum duration allowed for
	// isolated schema cache generation before timing out.
	DefaultSchemaCacheBuilderTimeout = 30 * time.Second
)
View Source 
const SchemaCatalogSnapshotVersion = schemareader.CatalogSnapshotVersion
View Source 
const SchemaMetaIndexVersion = 1

SchemaMetaIndexVersion is the CommandMeta summary index format used by CI dumps (cmd_schema_catalog) and unit-test encode/decode fixtures. Production ResolveMeta projects from the runtime-assembled SchemaRegistry — there is no committed schema_meta_index.gob embed.

View Source 
const SchemaSourceRuntimeAssembled = "runtime-assembled"

SchemaSourceRuntimeAssembled is stamped on SchemaRegistry.Source for declare→ResolveSchemaBuild delivery.

Variables

View Source 
var (
	AttachRuntimeSchema                = runtimeannotate.AttachRuntimeSchema
	AnnotateRuntimeFlag                = runtimeannotate.AnnotateRuntimeFlag
	AnnotateRuntimeFlagProperty        = runtimeannotate.AnnotateRuntimeFlagProperty
	AnnotateRuntimeRequiredFlags       = runtimeannotate.AnnotateRuntimeRequiredFlags
	AnnotateRuntimeFlagRequiredValue   = runtimeannotate.AnnotateRuntimeFlagRequiredValue
	AnnotateRuntimeFlagRequiredWhen    = runtimeannotate.AnnotateRuntimeFlagRequiredWhen
	AnnotateRuntimeFlagFormat          = runtimeannotate.AnnotateRuntimeFlagFormat
	AnnotateRuntimeFlagInterfaceType   = runtimeannotate.AnnotateRuntimeFlagInterfaceType
	AnnotateRuntimeFlagEnum            = runtimeannotate.AnnotateRuntimeFlagEnum
	AnnotateRuntimeFlagExample         = runtimeannotate.AnnotateRuntimeFlagExample
	RuntimeContractRisk                = runtimeannotate.RuntimeContractRisk
	RuntimeContractGate                = runtimeannotate.RuntimeContractGate
	AnnotateRuntimeConstraints         = runtimeannotate.AnnotateRuntimeConstraints
	AnnotateRuntimePositionals         = runtimeannotate.AnnotateRuntimePositionals
	HasDeclaredOrAnnotatedConfirmation = contractfinal.HasDeclaredOrAnnotatedConfirmation
	RuntimeContractFinal               = contractfinal.RuntimeContractFinal
	HasRuntimeContractFinal            = contractfinal.HasRuntimeContractFinal
	ClearRuntimeContractFinalForTest   = contractfinal.ClearRuntimeContractFinalForTest
	ApplyParamDecls                    = contractfinal.ApplyParamDecls
)
View Source 
var (
	SchemaRegistryFromRuntime = schemaruntime.SchemaRegistryFromRuntime
	ToolSpecFromRuntime       = schemaruntime.ToolSpecFromRuntime
)
View Source 
var ErrSchemaAssemblyConsumedDelivery = errors.New("Schema declaration assembly consumed runtime delivery")

Functions

func AnnotateRuntimeCompatibilityEquivalence added in v1.0.52 

func AnnotateRuntimeCompatibilityEquivalence(primary, compatibility *cobra.Command, review RuntimeCompatibilityEquivalence)

AnnotateRuntimeCompatibilityEquivalence records the same typed review on both sides of one independently executable compatibility pair. Invalid review data panics during command construction so production cannot silently accept an unreviewed handler mismatch.

func AuditSchemaAssembly added in v1.0.63 

func AuditSchemaAssembly(assemble func() error) (err error)

AuditSchemaAssembly is an exclusive build-time audit, not a runtime lock. The identity generator uses it around the entire declaration/projection path. Any delivery access, including an already cached lookup, aborts immediately before it can enter a loader Once. Do not run alongside runtime consumers. Normal production readers do not install an audit and retain concurrency.

func AwaitSchemaCachePrewarmForTest added in v1.0.63 

func AwaitSchemaCachePrewarmForTest()

AwaitSchemaCachePrewarmForTest blocks until the registered runtime's speculative prewarm (if any) settles, so counter and filesystem assertions are deterministic.

func BuildAgentSelectionEvalFixture added in v1.0.57 

func BuildAgentSelectionEvalFixture(bound BoundCommandRegistry) (AgentSelectionFixture, AgentSelectionReport, error)

BuildAgentSelectionEvalFixture turns every ContractFinal use_when and avoid_when entry into a typed, reproducible evaluation case and validates it against the exact BoundCommandRegistry.

func CaptureSchemaAssemblyEnviron added in v1.0.63 

func CaptureSchemaAssemblyEnviron()

CaptureSchemaAssemblyEnviron snapshots the environment before runtime plugin discovery. The snapshot is used as a child-process environment only.

func ClearBuildTimeAgentMetadata added in v1.0.57 

func ClearBuildTimeAgentMetadata()

ClearBuildTimeAgentMetadata removes a cmd_schema_catalog dump-helper injection.

func CollectIdentitySpecs added in v1.0.57 

func CollectIdentitySpecs(root *cobra.Command) ([]CommandSpec, IdentityCollectionReport, error)

CollectIdentitySpecs walks the runnable leaves under root and synthesises a CommandSpec from each leaf's ContractFinal.Identity (public visibility; SourceProductID defaulting is handled by the shared indexer). It is the single identity source consumed by BuildEffectiveCommandRegistry.

func CompareCommandSpecEquivalence added in v1.0.57 

func CompareCommandSpecEquivalence(collected, reviewed []CommandSpec) []string

CompareCommandSpecEquivalence returns a human-readable, deterministic diff between two CommandSpec sets keyed by canonical path. An empty slice means the two sets agree on every compared field.

func DeliverySchemaAllPayloadForTest added in v1.0.57 

func DeliverySchemaAllPayloadForTest() (map[string]any, error)

DeliverySchemaAllPayloadForTest returns schema --all through the installed delivery loader (catalog_hash comes from Snapshot.SourceHash).

func DeliverySchemaOverviewPayloadForTest added in v1.0.63 

func DeliverySchemaOverviewPayloadForTest() (map[string]any, error)

DeliverySchemaOverviewPayloadForTest exercises the production route split.

func DeliverySchemaQueryPayloadForTest added in v1.0.63 

func DeliverySchemaQueryPayloadForTest(path string) (map[string]any, error)

DeliverySchemaQueryPayloadForTest exercises one production path query.

func DiagnoseMissingPrimaries added in v1.0.57 

func DiagnoseMissingPrimaries(root *cobra.Command, missing []CommandSpec) []string

DiagnoseMissingPrimaries resolves each spec that has no collected primary and reports why: the primary CLI path may not exist as a Cobra leaf, the leaf may lack ContractFinal, or its declared canonical may drift from the expected one.

func EncodeSchemaMetaIndex added in v1.0.57 

func EncodeSchemaMetaIndex(index SchemaMetaIndexSnapshot) ([]byte, error)

EncodeSchemaMetaIndex marshals a CI/test SchemaMetaIndex dump (gob). Production ResolveMeta does not embed or load this artifact.

func EncodeSchemaMetaIndexJSON added in v1.0.57 

func EncodeSchemaMetaIndexJSON(index SchemaMetaIndexSnapshot) ([]byte, error)

EncodeSchemaMetaIndexJSON is retained for diagnostics / fixtures that need a human-readable projection of the same snapshot struct.

func InstallBuildTimeAgentMetadataJSON added in v1.0.57 

func InstallBuildTimeAgentMetadataJSON(data []byte) error

InstallBuildTimeAgentMetadataJSON installs generator-produced Agent metadata for cmd_schema_catalog CI/local dump assembly only. Production binaries never call this; production authority remains leaf ContractFinal / ProductDecl. The dump helper injects an in-memory snapshot so schema_agent_metadata/ is neither committed nor embedded.

func InstallProductionSchemaAssemblyForTest added in v1.0.57 

func InstallProductionSchemaAssemblyForTest(factory func() *cobra.Command)

InstallProductionSchemaAssemblyForTest installs the production assembleSchemaCatalogFromRoot delivery path with factory and clears lazy caches. Tests must Cleanup via RegisterSchemaSourceRoot(nil) or a restore helper that reinstalls their prior delivery stub.

func InvalidatePersistedSchemaCacheIdentities added in v1.0.63 

func InvalidatePersistedSchemaCacheIdentities()

InvalidatePersistedSchemaCacheIdentities deletes identity.json and legacy identity.*.json files under every candidate .../dws/schema tree. It never recurses a wide cache base (LOCALAPPDATA, ProgramData root, /var/cache) so unrelated apps' identity files stay untouched. dws upgrade calls this after replacing the executable so binary B cannot keep serving binary A's Schema.

func LoadSchemaParameterBindings added in v1.0.57 

func LoadSchemaParameterBindings() (map[string]map[string]string, error)

LoadSchemaParameterBindings returns a defensive copy of the reviewed active public flag-to-interface bindings. Active bindings are empty; property delivery comes from ParamDecl.Property. Mapping exclusions and removals remain on the Go mapping ledger (not returned here).

func LocalSchemaCacheIdentityFileName added in v1.0.63 

func LocalSchemaCacheIdentityFileName() string

LocalSchemaCacheIdentityFileName is the stable per-edition identity sidecar stored next to protobuf shards. Cache identity is the content hashes inside the record (source/surface/build_id and artifact digests) plus binary_build_id, which must match the running binary's buildversion.Digest. Sidecars are not keyed by a per-fingerprint filename.

func MarkSchemaCacheRuntimeUncertain added in v1.0.63 

func MarkSchemaCacheRuntimeUncertain()

MarkSchemaCacheRuntimeUncertain disables persistent cache publication for a process whose runtime state changed after registration. The process may still read an authenticated existing cache; cache repair is delegated to the isolated declaration builder.

func NewMCPCommand 

func NewMCPCommand() *cobra.Command

NewMCPCommand registers the mcp product declaration and returns its root command. The app layer attaches reviewed static MCP helpers as subcommands; live discovery surfaces are retired.

func NewSchemaCommand 

func NewSchemaCommand() *cobra.Command

NewSchemaCommand serves the typed Schema contract. Production assembles from declarations via ResolveSchemaBuild (factory registered by internal/app). A malformed assembly fails closed; the command takes no discovery loader because queries never run service discovery.

func OverridePriority 

func OverridePriority(cmd *cobra.Command) int

OverridePriority delegates to cobracmd.OverridePriority.

func ParseAgentExampleArgv added in v1.0.57 

func ParseAgentExampleArgv(input string) ([]string, error)

ParseAgentExampleArgv exposes the shell-free argv parser used by example validation and dry-run tests.

func PrewarmSchemaCache added in v1.0.63 

func PrewarmSchemaCache()

PrewarmSchemaCache starts the speculative payload read for the registered runtime. It is a no-op unless an enabled, eligible runtime is registered. The probe opens noCreate: a missing cache is left for the synchronous path.

func ReadFileArg 

func ReadFileArg(value string) (string, bool, error)

ReadFileArg reads the contents of a file referenced by the @filename syntax. Returns the original value unchanged if it does not start with "@" or is otherwise not a file-path-shaped value (e.g. "@所有人" is treated as plain text, not a path). Returns an error if the file cannot be read or exceeds the size limit.

Note: @- (stdin) is NOT handled here; use ResolveInputSource instead.

func ReadStdin 

func ReadStdin() (string, error)

ReadStdin reads all data from stdin unconditionally (up to maxStdinSize). Use this when the caller has explicitly requested stdin via @-.

func ReadStdinIfPiped 

func ReadStdinIfPiped() (string, error)

ReadStdinIfPiped reads all data from stdin if it is a pipe (not a terminal). Returns empty string if stdin is a terminal or has no data.

func RegisterRuntimeSchemaConstraints added in v1.0.52 

func RegisterRuntimeSchemaConstraints(canonicalPath string, constraints RuntimeSchemaConstraints)

RegisterRuntimeSchemaConstraints records reviewed cross-parameter CLI rules independently from the delivered Catalog so reviewed constraints always apply, regardless of which snapshot is shipped.

func RegisterRuntimeSchemaParameterMetadata added in v1.0.52 

func RegisterRuntimeSchemaParameterMetadata(canonicalPath string, metadata RuntimeSchemaParameterMetadata)

RegisterRuntimeSchemaParameterMetadata records strong, code-owned parameter semantics for one canonical command path.

func RegisterSchemaCacheIsolatedBuilder added in v1.0.63 

func RegisterSchemaCacheIsolatedBuilder(builder SchemaCacheIsolatedBuilder)

RegisterSchemaCacheIsolatedBuilder installs the production child-process builder. Passing nil is intended for tests only.

func RegisterSchemaCacheOptions added in v1.0.63 

func RegisterSchemaCacheOptions(options SchemaCacheOptions) error

RegisterSchemaCacheOptions replaces the cache registration. Invalid options fail closed to disabled before schemacache.Open or any filesystem operation.

func RegisterSchemaSourceRoot added in v1.0.57 

func RegisterSchemaSourceRoot(factory func() *cobra.Command)

RegisterSchemaSourceRoot installs the root factory used by runtime Schema delivery (dws schema / ResolveMeta). Production registers from internal/app before runtime plugin discovery, so each registration also captures the pristine child-process environment. Passing nil clears the factory (tests only) and resets lazy delivery / Meta state.

func RenderHelpAffordances added in v1.0.61 

func RenderHelpAffordances(cmd *cobra.Command)

RenderHelpAffordances appends the Agent-facing metadata that Cobra cannot express in its native command template. Leaf guidance and Safety come from ResolveMeta (the assembled Schema source); references come from the owning ProductDecl. Direct product/service Help renders references only.

func RenderSafetyAnnotation added in v1.0.55 

func RenderSafetyAnnotation(cmd *cobra.Command)

RenderSafetyAnnotation writes the reviewed Safety tuple to the command's stdout. Prefer RenderHelpAffordances for production Help; this focused entry point remains for compatibility and direct safety tests.

func ResetSchemaCacheRuntimeUncertaintyForTest added in v1.0.63 

func ResetSchemaCacheRuntimeUncertaintyForTest()

ResetSchemaCacheRuntimeUncertaintyForTest resets process state between tests.

func ResolveInputSource 

func ResolveInputSource(value string, flagName string, guard *StdinGuard) (string, error)

ResolveInputSource resolves a flag value that may reference an external input source. It supports three forms:

  • "@-" reads from stdin (requires StdinGuard claim)
  • "@<path>" reads from the named file
  • anything else returned unchanged

The flagName parameter is used only for error messages and StdinGuard tracking.

func RestorePackageCLISchemaDeliveryForTest added in v1.0.57 

func RestorePackageCLISchemaDeliveryForTest()

RestorePackageCLISchemaDeliveryForTest reinstalls the package-cli TestMain assembled-delivery stub after a production-assembly exercise. Outside package cli TestMain it clears the factory and resets lazy delivery state.

func ReviewedDryRunCapabilities added in v1.0.52 

func ReviewedDryRunCapabilities() (map[string]contract.DryRunSpec, error)

ReviewedDryRunCapabilities returns a defensive copy of the positive, reviewed capability registry for delivery gates.

func RuntimeSchemaParameterMetadataDefinitions added in v1.0.52 

func RuntimeSchemaParameterMetadataDefinitions() map[string]RuntimeSchemaParameterMetadata

RuntimeSchemaParameterMetadataDefinitions returns a defensive copy for build-time contract validation.

func SchemaAssemblyEnvironmentSnapshot added in v1.0.63 

func SchemaAssemblyEnvironmentSnapshot() []string

SchemaAssemblyEnvironmentSnapshot returns an immutable copy for child process setup. It never changes the caller's environment.

func SchemaAssemblyWorkingDirectory added in v1.0.63 

func SchemaAssemblyWorkingDirectory() string

SchemaAssemblyWorkingDirectory returns the registration-time working directory for isolated child-process assembly.

func SchemaCachePrewarmPayloadsHandleForTest added in v1.0.63 

func SchemaCachePrewarmPayloadsHandleForTest() *schemacache.Registry

SchemaCachePrewarmPayloadsHandleForTest returns the never-adopted prewarm payloads handle after it settles, so tests can assert repair reset closes it.

func SchemaSourceRootRegistered added in v1.0.57 

func SchemaSourceRootRegistered() bool

SchemaSourceRootRegistered reports whether runtime assembly has a root factory.

func SetOverridePriority 

func SetOverridePriority(cmd *cobra.Command, priority int)

SetOverridePriority delegates to cobracmd.SetOverridePriority.

func StdinIsPipe 

func StdinIsPipe() bool

StdinIsPipe reports whether stdin is a pipe (not a terminal). This is a non-consuming check — it only inspects file mode via stat.

func ValidateCatalogStructure added in v1.0.55 

func ValidateCatalogStructure(data []byte) error

ValidateCatalogStructure checks that every tool entry in a schema_catalog snapshot conforms to the unified command data structure. It returns an error aggregating up to schemaCatalogStructureMaxViolations violations.

func ValidateInputSchema 

func ValidateInputSchema(params map[string]any, schema map[string]any) error

ValidateInputSchema performs strict local validation for reviewed tool inputs. It enforces required/type/enum checks and rejects unknown properties by default.

func ValidateJSONSchemaValue added in v1.0.60 

func ValidateJSONSchemaValue(value any, schema map[string]any) error

ValidateJSONSchemaValue validates one decoded JSON value against the required/type/enum/properties/items subset used by reviewed CLI contracts.

func ValidateReviewedDryRunCapabilityDelivery added in v1.0.52 

func ValidateReviewedDryRunCapabilityDelivery(registry SchemaRegistry) error

ValidateReviewedDryRunCapabilityDelivery proves that every positive source entry reaches the final typed registry and no serializer invents one. It deliberately imposes no minimum capability count or all-command coverage.

func ValidateRuntimeSchemaCompleteness added in v1.0.57 

func ValidateRuntimeSchemaCompleteness(root *cobra.Command) error

ValidateRuntimeSchemaCompleteness enforces the reviewed reverse command-tree contract used by generation and CI.

func ValidateSchemaDeliveryInvariants added in v1.0.52 

func ValidateSchemaDeliveryInvariants(source SchemaRegistry, snapshot SchemaCatalogSnapshot) error

ValidateSchemaDeliveryInvariants proves that the serialized snapshot which will be embedded in the release binary is an exact delivery of source and has one content-identical ToolSpec behind every public Schema view. The snapshot is deliberately encoded and decoded through the production loader before any comparison is made.

This is a content gate, not a count gate: replacing one tool with another, consistently dropping a source field from every snapshot view, drifting a summary, or changing an alias payload while preserving all aggregate counts still fails.

func ValidateSchemaMetaIndexAgainstCatalog added in v1.0.57 

func ValidateSchemaMetaIndexAgainstCatalog(index SchemaMetaIndexSnapshot, registry SchemaRegistry) error

ValidateSchemaMetaIndexAgainstCatalog proves the summary index matches the Identity / Safety / Selection projection of every delivered ToolSpec.

func ValidateSchemaMetaIndexAgainstSnapshot added in v1.0.57 

func ValidateSchemaMetaIndexAgainstSnapshot(index SchemaMetaIndexSnapshot, snapshot SchemaCatalogSnapshot) error

ValidateSchemaMetaIndexAgainstSnapshot proves the summary index matches the Identity / Safety / Selection projection of every ToolSpec in a Catalog snapshot (generation-time gate before writing the index).

func ValidateSchemaParameterBindingDelivery added in v1.0.52 

func ValidateSchemaParameterBindingDelivery(bound BoundCommandRegistry, registry SchemaRegistry) error

ValidateSchemaParameterBindingDelivery proves that every reviewed mapping ledger entry reaches the final public typed registry it was written for.

func ValidateSchemaParameterBindings added in v1.0.57 

func ValidateSchemaParameterBindings() error

ValidateSchemaParameterBindings is the production validation gate for the reviewed mapping ledger (exclusions + removals). Build and generator entrypoints call this before any candidate resolution.

func WriteSchemaCacheBuildResult added in v1.0.63 

func WriteSchemaCacheBuildResult(w io.Writer, result SchemaCacheBuildResult) error

WriteSchemaCacheBuildResult writes a bounded, versioned private response.

Types

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 added in v1.0.57 

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

BuildAgentExampleExecutionPlan validates every ContractFinal example against its real BoundCommand/Cobra contract. Runtime dry-run execution is opt-in and comes only from the final typed ToolSpec.

func ValidateAgentExampleDelivery added in v1.0.57 

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

ValidateAgentExampleDelivery is the final generation gate. It validates every bound tool's ContractFinal Selection.Examples against the assembled typed SchemaRegistry.

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 added in v1.0.57 

func ValidateAgentSelectionContract(bound BoundCommandRegistry) (AgentSelectionReport, error)

ValidateAgentSelectionContract is the lightweight generator-facing gate.

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 added in v1.0.52 

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

BindEffectiveCommandRegistry resolves every registry path against the live Cobra tree. Registry entries may target hidden compatibility leaves when they are explicitly reviewed, but every target must be an actual runnable leaf. Native annotations are optional implementation evidence; when present they must exactly agree with the registry identity.

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 = schemaruntime.CommandIdentity

CommandIdentity is the stable identity of a command.

type CommandMeta added in v1.0.55 

type CommandMeta = schemaruntime.CommandMeta

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

func ResolveMeta added in v1.0.55 

func ResolveMeta(cliPath string) (CommandMeta, bool)

ResolveMeta returns the complete metadata for a command identified by its CLI path (e.g. "dev app delete") or one of its compat aliases (e.g. "report list" for "report inbox list"). Returns ok=false for commands not in the Schema surface (utility commands, hidden commands, shortcuts).

A persistent hit authenticates the payload file's index and one product shard header — Meta and the registry are never read on this path. Misses and corruption use the shared authoritative repair path.

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 added in v1.0.58 

func LoadCommandPathFallbacks() ([]CommandPathFallback, error)

LoadCommandPathFallbacks decodes and validates the authored recovery table. Callers receive a clone so generation and tests cannot mutate shared data.

func LookupCommandPathFallback added in v1.0.58 

func LookupCommandPathFallback(rawPath string) (CommandPathFallback, bool)

LookupCommandPathFallback performs an exact O(1) lookup of a reviewed recovery-only path. Normalization only removes a leading dws and folds whitespace; it does not apply prefix, typo, or semantic matching.

func ReduceCommandPathFallbacks added in v1.0.58 

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

ReduceCommandPathFallbacks validates the reviewed recovery table against the live distribution-owned Cobra tree. It refuses to turn an existing command or stable alias into a hidden rewrite. The sole exception is an explicitly annotated hint-only compatibility node, which contains no business action.

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 (CommandRegistry) SourceHash added in v1.0.52 

func (registry CommandRegistry) SourceHash() string

SourceHash hashes only stable identity, navigation, and reviewed exposure. Formatting, product order, provenance labels, and omitted default source_product_id/visibility values do not affect it.

type CommandSafety added in v1.0.55 

type CommandSafety = schemaruntime.CommandSafety

func SafetyForCLIPath deprecated added in v1.0.55 

func SafetyForCLIPath(cliPath string) (CommandSafety, bool)

SafetyForCLIPath returns the safety metadata for a command identified by its CLI path (e.g. "dev app delete"). Returns ok=false when the path is absent from the Schema surface (utility commands, hidden commands, shortcuts), or when no Schema source root is registered (synthetic help trees in unit tests). With a registered factory, assembly failure panics via ResolveMeta (fail-closed).

Deprecated: use ResolveMeta(cliPath).Safety for the complete metadata view. Kept for backward compatibility with existing callers.

type CommandSelection added in v1.0.55 

type CommandSelection = schemaruntime.CommandSelection

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 added in v1.0.52 

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

BuildEffectiveCommandRegistry assembles the effective command identity registry by collecting ContractFinal.Identity from the live Cobra leaves under root. The collector is the single identity source; there is no separate reviewed identity file to merge or overlay.

Parameter mapping ledger (schema_parameter_mapping_ledger.go — mapping_exclusions / removals; active bindings retired to ParamDecl.Property) is validated at BindEffectiveCommandRegistry and catalog assembly, not here. Identity registry construction must not hard-depend on active binding rows.

func BuildEffectiveFromSpecs added in v1.0.57 

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

BuildEffectiveFromSpecs wraps the shared indexing so collected specs are normalised by the exact same rules used for effective registry assembly.

func (EffectiveCommandRegistry) SourceHash added in v1.0.52 

func (registry EffectiveCommandRegistry) SourceHash() string

SourceHash covers every effective command identity delivered to downstream consumers.

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 added in v1.0.56 

func LookupParamAlias(rawCommandPath string) (ParamAliasEntry, bool)

LookupParamAlias resolves the reduced parameter-alias entry for a command.

rawCommandPath is Cobra's CommandPath() (it still carries the "dws" prefix). It is normalized through normalizeSchemaCLIPath — the exact function the build-time generator used to key each entry — so the runtime lookup key is byte-identical to the generation key and there is zero mapping drift.

func ReduceParamAliases added in v1.0.56 

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

ReduceParamAliases resolves the reviewed concept dictionary against every runnable leaf's real flags and returns the per-command alias table. It is the single source of the reduction algorithm, shared by the generator and tests so the build-time (intersection) and generated views can never disagree.

The reduction is deliberately mechanical (no NLU): for each concept it morphs the concept members (plus any command-bound generic flag) and intersects them with the command's morphed real flags. An intersection of exactly one real flag yields aliases onto it; two or more real flags is a co-occurrence that must be an explicitly reviewed `ambiguous` entry or generation fails. Command scoped aliases override, blocks are removed and recorded, and every override path and target is validated against the live tree.

func (ParamAliasEntry) IsAmbiguous added in v1.0.56 

func (e ParamAliasEntry) IsAmbiguous(morphed string) bool

IsAmbiguous reports whether a morphed emitted name is on this command's reviewed co-occurrence whitelist: it is intentionally left unresolved so the runtime asks instead of guessing between two real flags.

func (ParamAliasEntry) IsBlocked added in v1.0.56 

func (e ParamAliasEntry) IsBlocked(morphed string) bool

IsBlocked reports whether a morphed emitted name is on this command's block list: it must never be auto-rewritten and instead routes to did-you-mean.

func (ParamAliasEntry) ResolveAlias added in v1.0.56 

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

ResolveAlias returns the canonical real flag a morphed emitted name reduces to, if this command aliases it. The caller is expected to pass an already-morphed name (cmdutil.Morph), matching how the table is keyed.

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 added in v1.0.56 

func LoadParamConcepts() (ParamConcepts, error)

LoadParamConcepts decodes and validates the embedded reviewed concept dictionary exactly once.

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 = schemaruntime.ParameterSpec

type ProductSpec added in v1.0.52 

type ProductSpec = schemaruntime.ProductSpec

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 added in v1.0.52 

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

ResolveSchemaBuild is the only assembly path from executable Cobra commands and reviewed metadata into the typed Agent contract. It resolves identity once, binds Cobra once, and assembles one SchemaRegistry from ContractFinal / contract.ProductDecl leaf declarations. Catalog gates and serialization consume the returned value directly; they never re-read overlays or merge sources.

func (ResolvedSchemaBuild) CommandCount added in v1.0.52 

func (resolved ResolvedSchemaBuild) CommandCount() int

CommandCount reports the reviewed effective command count for generator diagnostics without exposing a mutable registry view.

func (ResolvedSchemaBuild) RegistryHash added in v1.0.52 

func (resolved ResolvedSchemaBuild) RegistryHash() string

RegistryHash returns the semantic identity/navigation hash attached to this resolved build. It is an envelope value, not a second registry input.

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 added in v1.0.52 

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

RuntimeSchemaCompleteness scans the real command tree in the reverse direction: every public executable leaf must either belong to the effective reviewed CommandRegistry or have a reviewed exclusion with a non-empty reason.

type RuntimeSchemaConstraints added in v1.0.52 

type RuntimeSchemaConstraints = contract.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 added in v1.0.57 

func ReviewedRuntimeSchemaExclusions() ([]RuntimeSchemaExclusion, error)

ReviewedRuntimeSchemaExclusions returns the exact, reviewed list of public CLI leaves intentionally kept outside the stable Agent command contract. Authority is the reviewed Go registry in schema_command_exclusions.go (central groups + non-empty reason); there is no JSON completeness input.

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 = schemaruntime.RuntimeToolSpecInput

type SchemaCacheArtifacts added in v1.0.63 

type SchemaCacheArtifacts struct {
	Version            int
	SourceHash         string
	SurfaceHash        string
	Meta               []byte
	Registry           []byte
	Payload            []byte
	ProductCount       int
	MetaSHA256         [sha256.Size]byte
	RegistrySHA256     [sha256.Size]byte
	PayloadSHA256      [sha256.Size]byte
	ProductDescriptors []schemaruntime.ProductDescriptor
	// contains filtered or unexported fields
}

SchemaCacheArtifacts is the deterministic cache hand-off used by the identity generator. Payload slices are detached from assembly state.

func BuildSchemaCacheArtifacts added in v1.0.63 

func BuildSchemaCacheArtifacts(resolved ResolvedSchemaBuild) (SchemaCacheArtifacts, error)

BuildSchemaCacheArtifacts validates and snapshots one ResolvedSchemaBuild, then derives Meta and product shards from that exact typed registry.

func DeliverySchemaCacheArtifactsForTest added in v1.0.63 

func DeliverySchemaCacheArtifactsForTest() (SchemaCacheArtifacts, error)

DeliverySchemaCacheArtifactsForTest derives artifacts from an already assembled live result without invoking its source factory again.

func (SchemaCacheArtifacts) LocatorPaths added in v1.0.63 

func (a SchemaCacheArtifacts) LocatorPaths() []string

LocatorPaths returns a detached, sorted list of every authenticated path in Meta. It is primarily useful for exhaustive generation and parity gates.

func (SchemaCacheArtifacts) MetaArtifact added in v1.0.63 

func (a SchemaCacheArtifacts) MetaArtifact() schemacache.Artifact

func (SchemaCacheArtifacts) PayloadArtifact added in v1.0.63 

func (a SchemaCacheArtifacts) PayloadArtifact() schemacache.Artifact

func (SchemaCacheArtifacts) PayloadIndexPins added in v1.0.63 

func (a SchemaCacheArtifacts) PayloadIndexPins() (uint64, [sha256.Size]byte, error)

PayloadIndexPins derives the pinned payload index region identity from the artifact's self-describing prefix: the region length including the 4-byte prefix, and the region digest.

func (SchemaCacheArtifacts) RegistryArtifact added in v1.0.63 

func (a SchemaCacheArtifacts) RegistryArtifact() schemacache.Artifact

func (SchemaCacheArtifacts) RenderAll added in v1.0.63 

func (a SchemaCacheArtifacts) RenderAll() (map[string]any, error)

RenderAll returns the public full-export projection represented by these exact artifacts without rebuilding the authoritative source tree.

func (SchemaCacheArtifacts) RenderOverview added in v1.0.63 

func (a SchemaCacheArtifacts) RenderOverview() (map[string]any, error)

RenderOverview returns the public Meta-only overview projection.

func (SchemaCacheArtifacts) RenderQuery added in v1.0.63 

func (a SchemaCacheArtifacts) RenderQuery(path string) (map[string]any, error)

RenderQuery returns a product/group/leaf projection from the exact registry used to create the cache artifacts.

func (SchemaCacheArtifacts) ValidateRoundTrip added in v1.0.63 

func (a SchemaCacheArtifacts) ValidateRoundTrip() error

ValidateRoundTrip proves the release hand-off before its digests can become binary trust anchors. It is intentionally a build-time operation: a cache hit authenticates bytes and validates the selected DTO, without reconstructing the complete public Catalog.

type SchemaCacheBuildResult added in v1.0.63 

type SchemaCacheBuildResult struct {
	Artifacts SchemaCacheArtifacts
	Identity  SchemaCacheIdentity
}

SchemaCacheBuildResult is the detached result of a clean declaration-only Schema assembly. It contains no live Cobra or registry state.

func ReadSchemaCacheBuildResult added in v1.0.63 

func ReadSchemaCacheBuildResult(r io.Reader) (SchemaCacheBuildResult, error)

ReadSchemaCacheBuildResult reads and validates a private builder response.

type SchemaCacheIdentity added in v1.0.63 

type SchemaCacheIdentity = schemareader.Identity

SchemaCacheIdentity is the complete identity of one cache generation. No value is learned from an on-disk envelope. Production does not embed this at compile time; each supported machine generates it from live declarations.

func IdentityFromArtifacts added in v1.0.63 

func IdentityFromArtifacts(edition string, artifacts SchemaCacheArtifacts) (SchemaCacheIdentity, error)

IdentityFromArtifacts derives the authenticated Schema cache identity of one live declaration assembly. Production never embeds this at compile time; each machine generates it from the running binary's declarations.

func SchemaCacheFastPathIdentity added in v1.0.63 

func SchemaCacheFastPathIdentity() (SchemaCacheIdentity, bool)

SchemaCacheFastPathIdentity returns only the currently registered, eligible authority. Replacing the source factory or marking runtime uncertainty must disable early process delivery just as it disables ordinary cache loaders. This accessor never opens the cache or assembles declarations.

func SchemaCacheReadableIdentityForTest added in v1.0.63 

func SchemaCacheReadableIdentityForTest() (SchemaCacheIdentity, bool)

SchemaCacheReadableIdentityForTest returns the registered identity even when the process is uncertain and therefore prohibited from direct publication.

func TryLoadLocalSchemaCacheIdentity added in v1.0.63 

func TryLoadLocalSchemaCacheIdentity(edition string) (SchemaCacheIdentity, bool)

TryLoadLocalSchemaCacheIdentity reads the per-edition identity sidecar from the edition cache directory. Missing files are a miss, not an error. Leftover fingerprint-suffixed sidecars are ignored and never used as a lookup key. A sidecar whose binary_build_id does not match the running binary is a miss with no side effect: it is left in place for lock-holding repair/publish or explicit upgrade invalidation. A sidecar whose recorded edition does not match the requested one is also a miss: identity binds the (directory, record) edition pair, so a sidecar copied from another edition's directory must not substitute that edition's artifacts for the requested one.

type SchemaCacheIsolatedBuilder added in v1.0.63 

type SchemaCacheIsolatedBuilder func(context.Context) (SchemaCacheBuildResult, error)

SchemaCacheIsolatedBuilder assembles a cache generation outside the caller's process state. Production installs this from internal/app.

type SchemaCacheOptions added in v1.0.63 

type SchemaCacheOptions struct {
	Enabled         bool
	AllowGenerate   bool
	Edition         string
	Identity        SchemaCacheIdentity
	GOOS            string
	GOARCH          string
	LockTimeout     time.Duration
	Counters        *schemacache.Counters
	RuntimeEligible func() bool
}

SchemaCacheOptions configures production cache delivery. Enabled options are accepted for darwin/linux/windows on amd64/arm64; tests may inject GOOS/GOARCH. AllowGenerate lets an empty identity be derived from the running binary's declarations on first schema use.

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 added in v1.0.52 

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

BuildSchemaCatalogSnapshot renders a deterministic Catalog from one resolved source-to-delivery hand-off. It deliberately accepts no Cobra root: rebuilding SchemaRegistry or re-deriving identity at this boundary would allow generation gates to validate one candidate while publishing another.

type SchemaIndex added in v1.0.52 

type SchemaIndex = schemaruntime.SchemaIndex

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 added in v1.0.57 

func BuildSchemaMetaIndex(snapshot SchemaCatalogSnapshot) (SchemaMetaIndexSnapshot, error)

BuildSchemaMetaIndex extracts the ResolveMeta summary from a full Catalog snapshot. Entries are sorted by cli_path for deterministic generation.

func DecodeSchemaMetaIndex added in v1.0.57 

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

DecodeSchemaMetaIndex parses a CI/test gob meta index dump.

func DecodeSchemaMetaIndexJSON added in v1.0.57 

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

DecodeSchemaMetaIndexJSON parses a JSON meta index document. Kept for unit fixtures; runtime delivery uses gob via DecodeSchemaMetaIndex.

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 added in v1.0.52 

func RuntimeSchemaMetadataLoadCounts() SchemaMetadataLoadCounts

RuntimeSchemaMetadataLoadCounts reads the concurrency-safe lazy loader counters without triggering any loader.

type SchemaRegistry added in v1.0.52 

type SchemaRegistry = schemaruntime.SchemaRegistry

Public aliases preserve the original cli API while ownership lives in the Cobra-free runtime package.

func AssembleSchemaRegistry added in v1.0.52 

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

AssembleSchemaRegistry is a test/homology gate entry that only needs the typed registry. Catalog production must use ResolveSchemaBuild so the bound/effective views remain attached to the exact same resolution pass.

func AssembleSchemaRegistryFromBound added in v1.0.52 

func AssembleSchemaRegistryFromBound(bound BoundCommandRegistry) (SchemaRegistry, error)

AssembleSchemaRegistryFromBound resolves non-identity sources into the single typed ToolSpec model. Command discovery is intentionally impossible below this boundary: callers must first provide a fail-closed bound registry.

type SchemaSnapshotPayload added in v1.0.52 

type SchemaSnapshotPayload = schemaruntime.SchemaSnapshotPayload

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 

func NewStdinGuard() *StdinGuard

NewStdinGuard creates a fresh guard for one command invocation.

func (*StdinGuard) Claim 

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

Claim marks stdin as consumed by the named source (e.g. "--text @-"). Returns an error if stdin was already claimed.

func (*StdinGuard) Claimed 

func (g *StdinGuard) Claimed() bool

Claimed reports whether stdin has been consumed.

type ToolSpec added in v1.0.52 

type ToolSpec = schemaruntime.ToolSpec

Source Files

View all Source files

Directories

Path Synopsis
Package homology holds Schema/CLI homology and ContractFinal consistency gates that exercise the live command tree and delivered Catalog.
 Package homology holds Schema/CLI homology and ContractFinal consistency gates that exercise the live command tree and delivered Catalog.
Package schemacachepb contains the private generated Schema cache DTO.
 Package schemacachepb contains the private generated Schema cache DTO.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.