cli

type CheckCompatibilityUseCase interface {
	CheckCompatibilityForWalk(ctx context.Context, walkID string, root coordinate.ModuleCoordinate, targetSPDX string, overrides licensedomain.LicenseOverrideSet) (licensedomain.ClosureCompatibilityReport, error)
}

type Container struct {
	// Config is the resolved store configuration for this invocation.
	// Preferences have already been applied to logLevel/jsonOut by root's
	// PersistentPreRunE; this field is provided for use-case layers that need
	// access to license_policy, license_overrides, or callgraph settings.
	Config domain.Config

	// fetch
	FetchModule QueryFetchUseCase // query-only; full fetch is done by runFetch directly
	QueryFetch  QueryFetchUseCase

	// identity. Signer is the published substitution port for
	// keyed attestation; the default is the OSS no-op (no attestation).
	// Pipeline call sites are wired in a later subtask.
	Signer fetchports.Signer

	// walk
	ExecuteWalk ExecuteWalkUseCase
	QueryWalks  QueryWalksUseCase
	DiffWalks   DiffWalksUseCase

	// extract
	Extract      ExtractUseCase
	QueryExtract QueryExtractionUseCase

	// CallgraphBound is the subprocess bound this invocation adopted and what
	// decided it. It is on the container because it is resolved when the
	// extractor is built and a command that reports it must report the value the
	// run is actually using — resolving it a second time reads the host again and
	// can produce a different number from the one in force.
	CallgraphBound extextractor.CallgraphBound

	// license
	ExtractLicense     ExtractLicenseUseCase
	QueryLicense       QueryLicenseUseCase
	DiffLicense        DiffLicenseUseCase
	GenerateNotice     GenerateNoticeUseCase
	CheckCompatibility CheckCompatibilityUseCase
	LicenseOverrides   licports.LicenseOverrideStore

	// StdlibCustody is the recorded chain of custody for the standard library,
	// which carries its licence on the acquisition rather than in a licence
	// record. Every command asked about the stdlib coordinate reads it here, so
	// the answer is the one audit and the SBOM already give.
	StdlibCustody StdlibCustodyReader

	// iface
	ExtractInterface ExtractInterfaceUseCase
	QueryInterface   QueryInterfaceUseCase
	DiffInterface    DiffInterfaceUseCase

	// callgraph
	ExtractCallGraph       ExtractCallGraphUseCase
	ExtractLocalCallGraph  ExtractLocalCallGraphUseCase
	ExtractStdlibCallGraph ExtractStdlibCallGraphUseCase
	QueryCallGraph         QueryCallGraphUseCase

	// examples
	ExtractExample ExtractExampleUseCase
	QueryExamples  QueryExamplesUseCase

	// vuln
	ScanModule ScanModuleUseCase
	ScanWalk   ScanWalkUseCase
	// SetAside is where the scans state the stored generations their writes and
	// reuse reads set aside; a scanning command points it at its stderr.
	SetAside            *setAsideRelay
	RescanWalk          RescanWalkUseCase
	QueryVuln           QueryVulnUseCase
	QueryScanRuns       QueryScanRunsUseCase
	DiffScanRuns        DiffScanRunsUseCase
	VulnStore           vulnports.VulnerabilityStore
	VulnPipelineVersion string
	// NegativeSearch is the read-time call-graph search over stored negatives.
	// QueryVuln already applies it; this is for the read paths that go to the
	// vuln store directly rather than through the query use case, and for the
	// records a fresh scan prints without reading them back.
	NegativeSearch *reachability.NegativeSearcher

	// sbom
	GenerateSBOM GenerateSBOMUseCase
	QuerySBOM    QuerySBOMUseCase

	// directive
	ExtractDirectives *dirapp.ExtractDirectivesUseCase
	QueryDirectives   QueryDirectivesUseCase
	DiffDirectives    DiffDirectivesUseCase
	// DirectiveParser reads a project's replace/exclude directives without
	// recording a scan. A diagnostic needs the local-replace fact to name a
	// remedy that can work, and reading it here keeps that answer coming from
	// the directive context instead of a second go.mod parser. Nil means the
	// question cannot be asked, which is not the same as answering "no".
	DirectiveParser dirports.DirectiveParser

	// godebug
	ExtractGoDebug *gdapp.ExtractGoDebugUseCase
	QueryGoDebug   *gdapp.QueryGoDebugUseCase

	// vendor
	ExtractVendor *venapp.ExtractVendorUseCase
	QueryVendor   *venapp.QueryVendorUseCase

	// fips
	ExtractFIPS ExtractFIPSUseCase
	QueryFIPS   QueryFIPSUseCase

	// native — the third-party C/C++ library a cgo module compiles into the
	// binary from source it ships in its own zip.
	ExtractNative *nativeapp.ExtractNativeUseCase
	QueryNative   *nativeapp.QueryNativeUseCase

	// staleness. The ledger of latest-version lookups, read and written by
	// every command that reports how far behind a dependency is.
	StalenessLedger staleports.Ledger

	// Audit is the backend's assurance log; ConfigHashes is its memory of the
	// last config hash that log recorded, nil when it keeps none.
	Audit        fetchports.AuditSink
	ConfigHashes configports.ConfigHashLedger
	// contains filtered or unexported fields
}

type DiffDirectivesUseCase interface {
	Diff(ctx context.Context, scanIDA, scanIDB string) (directivedomain.DirectiveDiff, error)
}

type DiffInterfaceUseCase interface {
	Diff(ctx context.Context, coordA, coordB coordinate.ModuleCoordinate) (ifacedomain.InterfaceDiff, error)
}

type DiffLicenseUseCase interface {
	Diff(ctx context.Context, coordA, coordB coordinate.ModuleCoordinate) (licensedomain.LicenseDiff, error)
}

type DiffScanRunsUseCase interface {
	Diff(ctx context.Context, runIDA, runIDB string) (vulndomain.ScanRunDiff, error)
}

type DiffWalksUseCase interface {
	Diff(ctx context.Context, idA, idB string) (walkapp.WalkDiff, error)
}

type ExecuteWalkUseCase interface {
	Execute(ctx context.Context, req walkapp.WalkRequest) (walkapp.ExecuteWalkResult, error)
}

type ExtractCallGraphUseCase interface {
	Execute(ctx context.Context, req cgapp.ExtractRequest) (cgapp.ExtractResult, error)
}

type ExtractExampleUseCase interface {
	Execute(ctx context.Context, req exapp.ExtractRequest) (exapp.ExtractResult, error)
}

type ExtractFIPSUseCase interface {
	Extract(ctx context.Context, goModPath string, policy configdomain.FIPSPolicy, configHash string) (fipsdomain.Record, error)
}

type ExtractInterfaceUseCase interface {
	Execute(ctx context.Context, req ifaceapp.ExtractRequest) (ifaceapp.ExtractResult, error)
}

type ExtractLicenseUseCase interface {
	Execute(ctx context.Context, req licapp.ExtractRequest) (licapp.ExtractResult, error)
	GetLicenseStore() licenseports.LicenseStore
}

type ExtractLocalCallGraphUseCase interface {
	Execute(ctx context.Context, req cgapp.LocalExtractRequest) (cgapp.ExtractResult, error)
}

type ExtractStdlibCallGraphUseCase interface {
	Execute(ctx context.Context, req cgapp.ExtractRequest) (cgapp.ExtractResult, error)
}

type ExtractUseCase interface {
	Execute(ctx context.Context, req extractapp.ExtractRequest) (extractdomain.ExtractionRun, error)
}

type FetchModuleUseCase interface {
	Execute(ctx context.Context, req fetchapp.FetchRequest) (fetchapp.FetchResult, error)
}

type GenerateNoticeUseCase interface {
	Generate(ctx context.Context, req licapp.NoticeRequest) (licapp.NoticeResult, error)
}

type GenerateSBOMUseCase interface {
	Generate(ctx context.Context, req sbomapp.SBOMRequest) (sbomdomain.SBOMRecord, error)
}

type QueryCallGraphUseCase interface {
	GetCallGraphRecord(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string) (callgraphdomain.CallGraphRecord, bool, error)
	GetCallGraphRecordFrom(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string, req callgraphdomain.ComposeRequest) (callgraphdomain.CallGraphRecord, bool, error)
	CallGraphHistory(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string) ([]callgraphdomain.CallGraphRecord, error)
	ListCallGraphRecords(ctx context.Context, filter cgports.CallGraphFilter) ([]cgports.CallGraphSummary, error)
	// ListCallGraphCoordinates answers "which modules has the store analysed, and
	// at what versions" from the ledger's keys. It is what the resolution helpers
	// ask, and it is separate from ListCallGraphRecords because that one answers
	// the different question "what does the served generation say" — and pays a
	// composition per multi-generation coordinate to do it.
	ListCallGraphCoordinates(ctx context.Context, filter cgports.CallGraphFilter) ([]cgports.CallGraphCoordinate, error)
	// ForeignModulesBuilt names the modules OTHER than the analysed one whose
	// packages the served record for a coordinate built with bodies. It is read
	// from the store's own column, never from a composed record: an edge query is
	// answered out of the edge table without decoding anything, and qualifying
	// that answer must not turn it into a query that does.
	//
	// found is false when the store holds no served generation. That is not an
	// empty set and is never rendered as one.
	ForeignModulesBuilt(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string, toolchain gotoolchain.Version) ([]callgraphdomain.ForeignModule, bool, error)
	FindCallers(ctx context.Context, symbolID, pipelineVersion string, scope coordinate.ModuleSet, opts cgports.EdgeQueryOptions) ([]cgports.CallEdgeRef, error)
	FindCallees(ctx context.Context, symbolID, pipelineVersion string, scope coordinate.ModuleSet, opts cgports.EdgeQueryOptions) ([]cgports.CallEdgeRef, error)
	// TraverseCallers and TraverseCallees walk the graph transitively. The
	// result carries whether the walk stopped at its depth bound holding
	// symbols it had not expanded — the CLI states that and must not re-derive
	// it, because the only thing outside this layer that could stand in for the
	// unexpanded frontier is a comparison against a second, unbounded run.
	TraverseCallers(ctx context.Context, req cgapp.TraversalRequest) (cgapp.TraversalResult, error)
	TraverseCallees(ctx context.Context, req cgapp.TraversalRequest) (cgapp.TraversalResult, error)
	// NotSearchedByCallers, NotSearchedByCallees and UnservedCoordinates name
	// the coordinates an edge query could not read because they hold no
	// generation at the served pipeline.
	NotSearchedByCallers(ctx context.Context, symbolIDs []string, pipelineVersion string, scope coordinate.ModuleSet, opts cgports.EdgeQueryOptions) ([]cgports.UnservedCoordinate, error)
	NotSearchedByCallees(ctx context.Context, symbolIDs []string, pipelineVersion string, scope coordinate.ModuleSet, opts cgports.EdgeQueryOptions) ([]cgports.UnservedCoordinate, error)
	UnservedCoordinates(ctx context.Context, coords []coordinate.ModuleCoordinate, pipelineVersion string) ([]cgports.UnservedCoordinate, error)
}

type QueryDirectivesUseCase interface {
	GetScan(ctx context.Context, scanID string) (directivedomain.Record, bool, error)
	ListScans(ctx context.Context, projectModulePath string, limit, offset int) ([]directivedomain.Record, error)
	// CountScans sizes the whole store, which ListScans cannot: it is keyed on
	// a project, so an empty page can only speak for that project's history.
	CountScans(ctx context.Context) (int, error)
	// ListScanProjects names each project the store holds scans of; ok is
	// false when the store cannot enumerate them.
	ListScanProjects(ctx context.Context) (projects []string, ok bool, err error)
}

type QueryExamplesUseCase interface {
	GetExampleRecord(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string) (exampledomain.ExampleRecord, bool, error)
	ExampleHistory(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string) ([]exampledomain.ExampleRecord, error)
	PipelinesHeld(ctx context.Context, coord coordinate.ModuleCoordinate) ([]string, error)
	ListExampleRecords(ctx context.Context, filter exampleports.ExampleFilter) ([]exampleports.ExampleSummary, error)
	FindBySymbol(ctx context.Context, symbol, pipelineVersion string, scope coordinate.ModuleSet) ([]exampleports.ExampleRef, error)
	FindBySymbolInModule(ctx context.Context, coord coordinate.ModuleCoordinate, symbol, pipelineVersion string) ([]exampleports.ExampleRef, error)
}

type QueryExtractionUseCase interface {
	GetExtractionRun(ctx context.Context, id string) (extractdomain.ExtractionRun, error)
	ListExtractionRuns(ctx context.Context, filter extractports.ExtractionRunFilter) ([]extractports.ExtractionRunSummary, error)
}

type QueryFIPSUseCase interface {
	Get(ctx context.Context, projectModulePath string) (fipsdomain.Record, bool, error)
}

type QueryFetchUseCase interface {
	GetFetchRecord(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string) (fetchdomain.CompositeRecord, bool, error)
	ComposeFetchRecord(ctx context.Context, coord coordinate.ModuleCoordinate) (fetchdomain.CompositeRecord, bool, error)
}

type QueryInterfaceUseCase interface {
	GetInterfaceRecord(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string) (ifacedomain.InterfaceRecord, bool, error)
	InterfaceHistory(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string) ([]ifacedomain.InterfaceRecord, error)
	ListInterfaceRecords(ctx context.Context, filter ifaceports.InterfaceFilter) ([]ifaceports.InterfaceSummary, error)
	ListInterfaceGenerations(ctx context.Context) ([]ifaceports.InterfaceGeneration, error)
	FindSymbol(ctx context.Context, symbolName, pipelineVersion string, scope coordinate.ModuleSet) ([]ifaceports.SymbolRef, error)
}

type QueryLicenseUseCase interface {
	GetLicenseRecord(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string) (licensedomain.LicenseRecord, bool, error)
	ListLicenseRecords(ctx context.Context, filter licenseports.LicenseFilter) ([]licenseports.LicenseSummary, error)
	LicenseHistory(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string) ([]licensedomain.LicenseRecord, error)
	PipelinesHeld(ctx context.Context, coord coordinate.ModuleCoordinate) ([]string, error)
	ResolveForWalk(ctx context.Context, walkID string, target coordinate.ModuleCoordinate, extractFn func(context.Context, coordinate.ModuleCoordinate) (licensedomain.LicenseRecord, error)) ([]licapp.DepLicenseResult, error)
}

type QuerySBOMUseCase interface {
	GetSBOMRecord(ctx context.Context, id string) (sbomdomain.SBOMRecord, error)
	ListSBOMRecords(ctx context.Context, walkID string) ([]sbomdomain.SBOMRecord, error)
}

type QueryScanRunsUseCase interface {
	GetRun(ctx context.Context, id string) (vulndomain.WalkScanRun, bool, error)
	ListRunsForWalk(ctx context.Context, walkID string) ([]vulndomain.WalkScanRun, error)
	ListAllRuns(ctx context.Context) ([]vulndomain.WalkScanRun, error)
	// UnresolvedWalks names the walks among runs that the store no longer holds,
	// so a listing can say that those runs' inputs cannot be resolved instead of
	// printing a walk id that looks like a live reference.
	UnresolvedWalks(ctx context.Context, runs []vulndomain.WalkScanRun) (map[string]bool, error)
	// WalkPresent answers the same question for a walk a caller named directly,
	// where there may be no run to derive the id from.
	WalkPresent(ctx context.Context, walkID string) (bool, error)
	ListSnapshots(ctx context.Context) ([]vulndomain.DatabaseSnapshot, error)
	GetLatestSnapshot(ctx context.Context) (vulndomain.DatabaseSnapshot, bool, error)
}

type QueryVulnUseCase interface {
	// ListRecordsForModuleInWalk returns a walk's candidate records for a
	// coordinate, unranked. Every caller ranks them within a named frame — see
	// recordInWalkFrame — because a walk's candidates span every frame the
	// coordinate was measured in, including other projects' builds.
	ListRecordsForModuleInWalk(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string, walkID string) ([]vulndomain.VulnerabilityRecord, error)
	ListRecordsForModule(ctx context.Context, coord coordinate.ModuleCoordinate, pipelineVersion string) ([]vulndomain.VulnerabilityRecord, error)
	// ListRecordsForModuleAllGenerations is the same listing with the generation
	// lifted out of the key: every record the store holds for the coordinate,
	// whatever pipeline version wrote it. It serves the history listing, which
	// asks what has ever been recorded rather than what this build would answer,
	// and it is the only read here a superseded record may reach a reader
	// through — marked as superseded where it does.
	ListRecordsForModuleAllGenerations(ctx context.Context, coord coordinate.ModuleCoordinate) ([]vulndomain.VulnerabilityRecord, error)
	ListRecordsByFindingID(ctx context.Context, findingID, walkID string) ([]vulndomain.VulnerabilityRecord, error)
	ListRecordsForRun(ctx context.Context, runID string) ([]vulndomain.VulnerabilityRecord, error)
	// ListRecordGenerationsForModule is the census behind every empty answer:
	// which pipeline versions the store holds this coordinate at, whatever
	// version this build serves. The reads above all key on the version, so an
	// empty result from them cannot tell "never scanned" from "scanned under
	// logic this build has superseded". Nothing is answered from it.
	ListRecordGenerationsForModule(ctx context.Context, coord coordinate.ModuleCoordinate) ([]vulnports.VulnerabilityRecordGeneration, error)
	// FindingTimelines is vuln-by-id --timeline's answer, unreadable rows
	// returned beside it as the listings above return theirs.
	FindingTimelines(ctx context.Context, findingID, walkID string) ([]vulndomain.FindingTimeline, error)
}

type QueryWalksUseCase interface {
	GetWalk(ctx context.Context, id string) (walkdomain.WalkRecord, error)
	ListWalks(ctx context.Context, filter walkports.WalkFilter) ([]walkports.WalkSummary, error)
}

type RegisteredCommand struct {
	// Path is the command as a caller types it after "kanonarion": ["store",
	// "info"] for `kanonarion store info`. Its last element is the name.
	Path []string
	// Aliases are the spellings accepted in place of Path's last element —
	// "licence" for "license".
	Aliases []string
	// Runnable reports whether the path executes on its own. A grouping
	// command such as "store" does not, so naming it alone is a broken
	// instruction rather than a command.
	Runnable bool
	// Children names the subcommands registered under this path.
	Children []string
	// Flags are the long flag names accepted here, without their dashes,
	// including the persistent flags inherited from parent commands: a caller
	// can write --json on any command, and --help on all of them.
	Flags []string
	// HiddenFlags are the members of Flags the command registers but does not
	// offer: a flag is hidden here when it is registered to be EXPLAINED rather
	// than accepted, so that a caller who types it is told why instead of being
	// shown cobra's "unknown flag".
	//
	// It is reported separately because Flags cannot carry the distinction and a
	// guard needs it: a command's flag set answers "yes" for a flag the command
	// refuses at runtime, so documentation advertising that flag passes any check
	// that only asks what the tree accepts.
	HiddenFlags []string
	// StoreIntent is what the command declared about the store root: "create"
	// if running it may bring that directory into existence, "read" if it must
	// not, "none" if it opens no store at all, and "" if it declared nothing.
	//
	// The empty string is reported rather than folded into "read" so a guard
	// can tell a command that decided from one that never did. At runtime both
	// refuse — the default is the safe one — but only one of them is a bug.
	StoreIntent string
}

type RescanWalkUseCase interface {
	Rescan(ctx context.Context, req vulnapp.RescanRequest) (vulndomain.WalkScanRun, error)
}

type ScanModuleUseCase interface {
	Scan(ctx context.Context, params vulnapp.ScanModuleParams) (vulndomain.VulnerabilityRecord, error)
}

type ScanWalkUseCase interface {
	Scan(ctx context.Context, params vulnapp.ScanWalkParams) (vulndomain.WalkScanRun, error)

	// ReusableRun reports a completed stored run that already answers what a new
	// Scan of this walk against the current snapshot would ask. The caller
	// decides whether to serve it; Scan itself always measures.
	//
	// projectDir is the working tree this invocation would scan, exactly as it
	// is passed to Scan — empty when the caller names none, in which case the
	// walk's own record of where it was taken from is used. It is an input to
	// the decision, not to the answer: a stored run may only be served while
	// that directory still requires the module versions the walk resolved, so
	// the caller must hand over the same directory it would have scanned.
	ReusableRun(ctx context.Context, walkID, projectDir string) (vulndomain.WalkScanRun, bool, error)

	// ServeReusableRun witnesses in the assurance log that a stored run was
	// handed back instead of measured. It is separate from ReusableRun because
	// asking whether a run could serve is not serving it: some callers ask only
	// to narrate, and some ask and then discard the answer.
	ServeReusableRun(run vulndomain.WalkScanRun, surface string) error

	// RefreshSnapshot brings the advisory database up to date for the named walk,
	// downloading the body only when something that walk is judged on has
	// changed, and reports what it established.
	RefreshSnapshot(ctx context.Context, walkID string) (vulnapp.SnapshotRefresh, error)

	// JudgeToolchain derives whether the stored snapshot's toolchain key covers
	// the toolchain version a walk was built under. It reads the stored snapshot
	// and records nothing.
	JudgeToolchain(ctx context.Context, snapshot vulndomain.DatabaseSnapshot, toolchainVersion string) (vulndomain.ToolchainJudgment, error)
}

type StdlibCustodyLister interface {
	ListFactsFor(ctx context.Context, goVersion string) ([]stdlibdomain.Facts, error)
}

type StdlibCustodyReader interface {
	// Get returns the composed measurement for a canonical Go version
	// ("go1.26.5"). The bool is false when the ledger holds none.
	Get(ctx context.Context, goVersion string) (stdlibdomain.Facts, bool, error)
}