disambiguation

README

Disambiguation entry schema

internal/disambiguation owns the public, machine-readable terminology-entry contract. Agents can inspect the pinned contract through the public binary:

fak disambiguation schema --json
fak disambiguation schema --self-test --json

Version 1 is fak-disambiguation-entry/1. Its reader rejects unknown versions, unknown fields, trailing JSON values, missing required fields, invalid enum values, and non-public source locators. identity.aliases must be present as an array but may be empty ([]). Adding, removing, renaming, or changing the type of a field requires a new schema version.

The package performs no filesystem or network writes and imports no private source. GeneratePublicIndex is the sole byte writer for the tracked public artifact; cmd/fak only routes those bytes to disk. testdata/entry-v1.json is a complete public-source fixture; RunSelfTest accepts it in equivalent typed form and independently removes and rejects every required JSON path declared by the schema descriptor.

Canonical and declared-alias query

The public read seam performs an exact, case-sensitive lookup across canonical terms and declared aliases; it never normalizes whitespace or case. Canonical input returns the canonical record directly. Alias input returns that same complete canonical record and adds matched_alias with the exact declared alias used, so canonical identity and ownership remain visible:

fak disambiguation query "agent kernel" --json
fak disambiguation query "fused agent kernel" --json
fak disambiguation query --self-test --json

Query remains the package-level canonical-only seam; Resolve is the additive alias-aware seam used by the CLI. Index construction rejects duplicate canonical terms, duplicate aliases (including repeats under one owner), and aliases that collide with any canonical term. These checks are the generation/index boundary: ambiguous identity cannot become queryable.

The response contract is fak-disambiguation-query/1 and names the public seed version separately. Its nested entry is the complete strict schema record, including meaning (definition), scope, contrasts, owner, public sources, and freshness. The reader is stdlib-only and read-only; it is not a second index writer and has no private source dependency.

Ranked search and explicit ambiguity

Use fak disambiguation search <term> --json when discovery, rather than exact resolution, is intended. The fak-disambiguation-search/1 response keeps exact canonical, exact alias, and prefix matches in separate ranked groups. Its typed verdict is exact, alias, prefix, ambiguous, or not_found; multiple owners produce ambiguous instead of silently selecting the first candidate. The human form prints the same groups, and exits 3 for ambiguity so automation cannot mistake a candidate list for a resolved identity.

fak disambiguation search "agent" --json
fak disambiguation search "kernel"

CLI terminology source

fak disambiguation cli-source --json derives command, subcommand, and long-flag terms directly from the public runtime help synopsis. Each flag retains its invocation context, so shared spellings do not lose ownership. The read-only fak-disambiguation-cli-source/1 report can compare a prior snapshot and lists removed terms under stale; --self-test captures one automatically added CLI term and one removed verb. This projection is not a second index writer.

Pairwise contrasts and forbidden conflations

Each contrast names another canonical entry, carries a non-empty explanation, and explicitly records required_pair and forbidden_conflation. A required pair must be declared in both directions and must agree on whether conflation is forbidden. Index admission rejects self-contrasts, duplicate or unknown targets, and asymmetric required pairs. Querying either a canonical term or an alias returns the canonical entry with these contrast fields unchanged; for example, fak disambiguation query "fused agent kernel" --json exposes the required, forbidden agent kernel / compute kernel distinction.

These are reader-side admission checks over the same public index. They add no writer, filesystem access, network access, or private dependency.

Fuzzing the public read seams

The normal Go test gate discovers five native fuzz targets in fuzz_test.go: FuzzParseEntryMalformed, FuzzContrastGraphCycles, FuzzDuplicateIdentities, FuzzUnicodeConfusables, and FuzzPathologicalAliasSets. Their deterministic seed corpus runs during every ordinary go test; bounded mutation can be invoked with, for example, go test ./internal/disambiguation -run '^$' -fuzz FuzzUnicodeConfusables -fuzztime 5s.

The targets import the package externally (disambiguation_test) and exercise only the exported ParseEntry, Entry.Validate, NewIndex, and Resolve seams. They add no corpus writer, generated index, filesystem/network access, or private-source dependency. Alias and graph inputs are bounded so a routine fuzz smoke cannot turn cardinality or string width into an accidental resource test.

Ownership and dispatch admission

Every entry's owner.leaf and owner.lane fields are admission data, not free-form labels. Agents discover the authoritative public contracts in these existing places:

• owner leaf registry: real public directories under internal/<leaf>/ and cmd/<leaf>/, matching the ship-stamp contract in AGENTS.md and tools/commit_stamp_doctor.py;
• dispatch lane registry: dos.toml [lanes] (concurrent, exclusive, autopick) plus [lanes.trees], the workspace manifest used by dispatch and lease tooling.

Generation calls LoadPublicManifests and NewAdmittedIndex, rejecting an entry before output when either target is absent. This reads only public repository paths—never private repositories, host configuration, or a second generated registry. Run fak disambiguation ownership --self-test --json; its report proves one accepted fixture and separate rejected leaf/lane fixtures through the public CLI seam.

The seed distinctions retain their accountable kernel or disambiguation owner leaves. Their dispatch lanes are kernel for the kernel-owned distinction and the declared public terminology lane canon for disambiguation-owned terminology distinctions.

Scoped overloaded terms

A canonical token may have multiple entries only when each entry has a distinct, required scope.kind + scope.value qualifier. Unscoped queries of an overloaded token return scope required; callers select an owner with --scope-kind and --scope-value, and JSON returns the stored scope unchanged. For example:

fak disambiguation query kernel --scope-kind package --scope-value internal/disambiguation --json

The index remains a single public-source writer. Scope does not broaden source admission or permit private repository, host, credential, or local-path material.

Deterministic generated index

fak disambiguation generate validates the declared public entries, sorts entries, aliases, contrasts, and source witnesses into canonical order, and writes docs/generated/disambiguation-index.json. The artifact records the source-set SHA-256 as source_revision; the command report records the final byte digest. Run fak disambiguation generate --check --json at a committed tip to prove regenerate-and-diff is clean. --check is read-only and exits nonzero on missing or stale output. No repository crawl, network read, private source, or second serializer participates in generation.

fak disambiguation version --json exposes the entry schema, generated-index schema, source revision, entry count, and ordered-content SHA-256 for citations. Semantic content changes move both digests; source-order-only changes move neither because versioning consumes the same canonical bytes as generation.

fak disambiguation committed-freshness --json archives HEAD into an isolated temporary checkout, runs the committed generator check there, and compares that artifact with generation from the invoking binary. It reports committed-clean, own-overlay-drift, or unavailable; a dirty peer file cannot make a committed tip look stale, and an unavailable git/toolchain probe never looks clean.

The regenerate-and-diff check is a hard gate in all canonical CI entry points: make ci, scripts/ci.ps1, the unchanged build · vet · test · claims-lint GitHub job, and fak-dev ci-preflight over its isolated committed archive. The workflow job/check name is unchanged; only a step was added. Rollback removes that step/target/preflight call together and leaves the generator artifact intact.

Strict public provenance

Every sources[] entry is immutable provenance returned unchanged by fak disambiguation query <term> --json:

• kind is one of document, go-source, test, generated-index, or github-metadata; private repositories, local files, arbitrary URLs, and other unverifiable kinds are refused.
• locator is a normalized slash-separated repository-relative path with an optional #fragment; absolute Windows/Unix paths, backslashes, and .. escapes are refused.
• revision pins the public source state, checked_at is canonical UTC RFC 3339, and probe is the stable lowercase public probe identity.

Provenance admission failures are ValidationError values with stable code and field members; use ValidationCode(err), not message parsing. Validation walks entries and sources in input order, making the first error deterministic. This adds no writer: the existing entry/index writer remains authoritative and the dependency boundary remains public fak repository/GitHub evidence only. Run fak disambiguation provenance --self-test --json for the hermetic CLI round-trip plus absolute-path, escaping-path, and private-kind rejection witness.

Public-safety admission

Entry.Validate also scans every string field before an entry can reach the index. It rejects credential-shaped text, absolute local paths, private repository names, private hostnames or RFC 1918 addresses, and terminal control bytes with stable DISAMBIGUATION_PUBLIC_SAFETY_* codes. Repository-relative public locators and ordinary public documentation remain valid. The recursive scan covers nested fields and future string fields by default, so adding a field cannot silently bypass the publication boundary.

Freshness verdict contract

Agents and JSON consumers get exactly four freshness states. Every state has one stable reason code; do not infer freshness from timestamps or probe transport success alone.

Verdict	Stable reason_code	Meaning
fresh	SOURCE_CURRENT	The public probe was available and returned valid, current evidence.
stale	SOURCE_OUTDATED	The public probe was available and returned valid evidence that is not current.
unknown	PROBE_UNAVAILABLE	The probe could not supply evidence. Unavailability never degrades to fresh.
invalid	EVIDENCE_MALFORMED	Probe metadata or returned evidence was malformed. Malformed evidence is never classified as merely stale.

EvaluateFreshness is the single read-only classifier. Its inputs are public probe observations; it performs no I/O, reads no private source, and does not write or regenerate the index. Existing schema, query, alias, contrast, scope, and ownership behavior is unchanged. A Freshness value is valid only when its verdict and reason-code pair match this table and checked_at is canonical RFC3339.

Run the package witness with go test ./internal/disambiguation and the public CLI JSON witness with:

fak disambiguation freshness --self-test --json

Public reference freshness

A source witness may add a reference object to cite a repository-visible contract inside its existing public provenance locator:

• go-symbol: an exported top-level Go declaration in the cited .go file;
• cli-verb: a literal public verb dispatched by the cited Go source;
• reason-code: a stable uppercase reason-code literal in cited Go source;
• doc-anchor: a GitHub-style Markdown heading anchor in the cited document.

ProbePublicReferences(repoRoot, entry) reads only those repository-relative public sources. A present reference is fresh/SOURCE_CURRENT; removing it is stale with PUBLIC_SYMBOL_MISSING, CLI_VERB_MISSING, REASON_CODE_MISSING, or DOCUMENT_ANCHOR_MISSING. A source that cannot be read for reasons other than absence remains unknown/PROBE_UNAVAILABLE. Invalid entry/provenance/reference evidence remains invalid/EVIDENCE_MALFORMED and outranks unavailable or stale results, preserving the four-state #6280 precedence. This is a reader/probe over #6281 provenance, not a writer, registry, or private-source integration.

Agents can capture the deterministic package/CLI transition witness with:

fak disambiguation stale-symbols-self-test --json

The JSON emits both the initial fresh result and the result after deleting the fixture declaration (stale/PUBLIC_SYMBOL_MISSING).

Coverage inventory

InventoryCoverage is the deterministic orphan-term check for agents adding public terminology. Call it with the repository's canonical Index, an explicit list of PublicTerminologySurface declarations, and explicit IncidentalTerm classifications. The first supported surface kind is go_package: it inventories exported type, function, constant, and variable names from non-test Go files beneath exactly the declared package directory. It does not crawl the repository, read private inputs, use the network, or write an index.

Every exported candidate must resolve by one of these paths:

• canonical: its normalized words are a canonical term/alias, or the canonical entry's public-source provenance names the exact exported Go symbol;
• incidental: the caller supplies the exact symbol and a non-empty reason; or
• finding: JSON reports MISSING_TERM_CLASSIFICATION, the declared surface, exact symbol, and normalized candidate term.

Surfaces and findings are sorted, so identical public inputs produce identical JSON. Keep surface declarations narrow and reviewed; adding a broad repository heuristic defeats the contract by turning implementation churn into terminology noise.

Run the hermetic public CLI witness before changing coverage plumbing:

fak disambiguation coverage-self-test --json

The witness introduces NewlyExportedTerm, observes the stable missing-classification reason, classifies it as incidental, and verifies the finding clears. Package callers can use the same CoverageSelfCheck; neither path introduces a second writer.

Incidental classification contract (#6284)

TermClassification is the strict public contract for exported local implementation tokens that must count in terminology coverage but must never become canonical glossary/query rows. Build the normal index with NewClassifiedIndex(entries, classifications); this is the same Index and the same InventoryCoverage writer used for canonical entries, not a second registry or identity path.

An incidental classification has deterministic machine-readable fields:

{
  "schema_version": "fak-disambiguation-classification/1",
  "term": "LocalRetryToken",
  "classification": "incidental",
  "reason": "LOCAL_IMPLEMENTATION_TOKEN"
}

Validation is closed and deterministic: the term must be an exported Go identifier; schema, classification, and reason must be the constants above; duplicate terms and unknown values fail. Index.Query remains canonical/alias-only, while InventoryCoverage reports the classification and increments incidental. Agents can witness both sides with:

fak disambiguation coverage-self-test --json

A passing report has covered: true, absent_from_query: true, and the stable classification/reason fields. The older []IncidentalTerm coverage argument remains accepted for compatibility with #6283, but new declarations should use NewClassifiedIndex so classification belongs to the shared index.

Generated documentation pages (#6320)

fak disambiguation docs renders the human-facing canonical-term page and reverse contrast index from the same typed Entry records used by generate, query, and search. The tracked pages live under docs/generated/disambiguation/; each row links to a scoped identity and prints the exact public query command.

fak disambiguation docs
fak disambiguation docs --check
fak disambiguation docs --json

--check is the drift gate: it fails if either page differs and never rewrites it. Rendering is sorted and byte-identical, so documentation does not become a second terminology writer.

Reverse lookup from repository evidence (#6321)

Agents that start from evidence rather than a glossary term can use fak disambiguation reverse to find the canonical distinction that owns it. The lookup reads the same immutable Entry index as query and search; it does not crawl the tree, infer fuzzy matches, or maintain a second registry.

fak disambiguation reverse --kind source-path internal/disambiguation/query.go
fak disambiguation reverse --kind symbol Query
fak disambiguation reverse --kind cli-token disambiguation
fak disambiguation reverse --kind reason-code SOURCE_CURRENT
fak disambiguation reverse --self-test --json

Supported kinds are exact and closed: source-path matches a source locator (including the path portion before a document anchor), while symbol, cli-token, and reason-code match typed public references. Freshness reason codes are also indexed. A locator may return multiple evidenced owners; unknown input returns reverse locator not found with an empty matches array rather than fabricating an owner.

Session-family terminology (#6314)

The canonical index separates five related runtime concepts that must not collapse into a generic “session state” label:

Input term	Canonical identity	Mechanism
session	agent session	Durable execution identity and drive-state pointers; not the provider transcript.
resume	session resume	Re-admit a valid paused session, warm when KV can be reattached and safely cold otherwise.
recovery	session recovery	Repair or reroute state that cannot safely continue unchanged.
compaction	context compaction	Replace model-visible history so resident context falls; cumulative usage can still rise.
checkpoint	recovery checkpoint	Preserve typed continuation state for a recovery action.

The public witness resolves every input and checks required forbidden pairs in both directions:

fak disambiguation session-source-self-test --json
fak disambiguation query resume
fak disambiguation query compaction

Two conflations are explicitly forbidden: resume is not recovery, because a paused but valid session does not require repair; and compaction is not a recovery checkpoint, because rewriting model context is not the same operation as preserving control-plane continuation state. All records cite public Go symbols under internal/session; no private transcript or secondary terminology writer is involved.

Cache and prefix-reuse terminology (#6315)

“Cache” names four different objects in fak. The canonical index distinguishes them by owner, cached object, lookup identity, and invalidation boundary:

Input	Canonical identity	Owner and object	Lookup / invalidation boundary
vDSO cache	tool-result cache	internal/vdso; completed tool outputs	Tool + argument hash + principal + effect epochs; writes strand old epoch keys.
KV cache	model KV cache	internal/model; live attention K/V tensors	Sequence positions; token eviction or sequence rewrite mutates the tensors.
radix cache	radix prefix cache	internal/radixkv; reusable prefix snapshots	Namespaced token longest-prefix match; explicit token/byte budgets and eviction.
provider cache	provider prompt cache	Upstream provider; prompt-prefix reuse	Provider identity/TTL; fak observes cache-read and cache-creation token axes rather than owning entries.

Run the public four-way fixture:

fak disambiguation cache-source-self-test --json
fak disambiguation query "KV cache"
fak disambiguation query "provider cache"

The fixture requires every record to carry three explicit forbidden contrasts, a distinct owner leaf, and public Go-symbol provenance. In particular, a radix prefix lookup is not the same object as a live KV tensor, and neither is evidence that the external provider prompt cache hit.

Reason-code and verdict namespaces (#6311)

Uppercase tokens are not one global enum. The index separates four semantic roles:

Example	Canonical identity	Meaning
POLICY_BLOCK	ABI refusal reason	Closed abi.ReasonCode explaining why a tool-call adjudication refused.
DENY	policy posture verdict	Result of folding organization amendment authority.
LANDS_TREE	hook gate class	Hook-runner metadata describing a gate’s tree mutation/isolation surface.
ARBITER_REFUSE	DOS decision kind	Persistent decision-row category revalidated against live lane leases.

ValidateVocabulary makes duplicate handling explicit. Reusing the same code is accepted only when every declaration has the same kind and canonical_meaning; package and symbol may differ. Thus the public COLLISION_RISK declarations in internal/dispatchorder and internal/dispatchtick are a declared cross-package alias for unsafe-tree-region-overlap. Reusing that token as a verdict meaning “request denied” is rejected as incompatible vocabulary collision.

fak disambiguation reason-source-self-test --json
fak disambiguation query POLICY_BLOCK
fak disambiguation query ARBITER_REFUSE

The selfcheck inventories public paths and symbols, admits the declared alias, and mutates one duplicate to an incompatible kind/meaning to prove rejection. It reads the same canonical index and public source tree as other disambiguation commands; there is no private or second vocabulary writer.

Scoped runtime terminology (#6316)

runtime is intentionally overloaded and therefore cannot be queried safely without scope. The canonical index exposes five choices:

Scope	Alias	Public owner	What executes
runtime:agent-application	agent application runtime	internal/agent.Planner	Host-side model/tool task loop.
runtime:gateway-serving	gateway serving runtime	internal/gateway.Server	HTTP/MCP transport, auth, routing, and kernel mediation.
runtime:guard-enforcement	guard enforcement runtime	fak guard	Wrapped guest process under policy, capability, hook, and stop enforcement.
runtime:model-serving	model serving runtime	internal/engine.OnDeviceRuntime	Model completion implementation behind an engine driver.
runtime:worker-execution	worker execution runtime	dispatchworker	One backend worker executing a lane-scoped work packet.

An unscoped exact query returns scope required for overloaded term; search returns all five choices. Resolve one explicitly:

fak disambiguation query runtime --scope-kind runtime --scope-value gateway-serving
fak disambiguation query "guard enforcement runtime" --scope-kind runtime --scope-value guard-enforcement
fak disambiguation runtime-source-self-test --json

The selfcheck asks the ambiguous question first and then resolves both the canonical token and alias for every public scope. Runtime is execution context—not a synonym for agent kernel, durable session, model KV state, or DOS decision state.

Fleet and dispatch identities (#6317)

The dispatch control plane uses eight distinct identities:

Input	Canonical identity	Authoritative typed source
worker process	dispatch worker	dispatchaudit.Worker: issue, lane, backend, and witnessed-result fields.
seat	account seat	fleetaccounts.Seat: account capacity, session cap, leased/free slots.
lane	dispatch lane	laneadmit.Request: taxonomy partition and requested tree.
lease	lane lease	laneadmit.Lease: live holder claim over lane/tree.
fleet	compute fleet	fleet.Roster: uniquely identified controllable machines.
wave	dispatch wave	issuecohort.Wave: one concurrency-safe launch batch and lease region.
loop	dispatch loop	loopmgr.LoopSnapshot: durable recurring run state and counters.
supervisor	fleet supervisor	supervisoragent.SupervisorInput: witnessed liveness, workers, escalations, and leases.

Dispatch identity is never parsed from worker prose. ResolveDispatchIdentity reads only structured worker_id, issue, lane, and lease_id; narration has no authority. A narration-only sentence such as worker=w-7 issue=6317 lane=dispatch lease=lease-7 returns dispatch identity missing from structured fields. If structured fields are present, conflicting narration cannot overwrite them.

fak disambiguation fleet-source-self-test --json
fak disambiguation query "worker process"
fak disambiguation query lease

The selfcheck resolves all eight public concepts, rejects narration-only identity, and proves structured identity survives adversarial prose unchanged.

Policy and adjudication terminology (#6318)

The public index keeps five policy-adjacent concepts separate:

• policy declaration is reusable configuration (adjudicator.Policy), not a result for one call;
• capability floor is the minimum authority boundary (abi.Capability), not a verdict;
• adjudication verdict is the typed per-call outcome (abi.Verdict), while an ABI refusal reason explains why;
• structural preflight is the local grammar/adjudicator fold exposed by fak preflight and does not execute the tool; and
• model-mediated check depends on model interpretation and is explicitly outside that deterministic preflight fold.

Run fak disambiguation policy-source-self-test --json to resolve each term to its public source, prove the structural/model and capability/verdict boundaries, and reject an incompatible reuse of POLICY_BLOCK through the shared vocabulary validator. The fixture reads the same public index and reason-code validation seam as consumers; it introduces no second writer or private source.

Benchmark and claim terminology (#6319)

The index distinguishes the naive baseline (untuned floor), tuned baseline (credible next-best alternative), and fak measurement arm (the treatment, not another baseline). It separately names witness provenance as the closed WITNESSED / OBSERVED / MODELED / SIMULATED classification, simulated evidence as one honestly labeled provenance class, and a net-true claim as the full six-question value statement.

Run fak disambiguation claims-source-self-test --json to resolve the six terms and prove a claim fixture without baseline, provenance, or scope is rejected. The source is the public internal/claimcheck contract; benchmark numbers remain owned by the benchmark authority rather than copied into this index.

Lifecycle and rollout terminology (#6312)

Three ladders remain domain-scoped rather than sharing overloaded spellings:

• index lifecycle class is the terminology authority ladder: current, versioned, research, or archived;
• activation posture is the behavior switch: off, shadow, or on; and
• capability maturity rung is the readiness ladder: proposed, prototyped, tested, dogfooded, or default. benchmarked remains an orthogonal badge.

Run fak disambiguation lifecycle-source-self-test --json to link every accepted spelling to one canonical public definition and prove cross-ladder spellings such as lifecycle shadow, activation archived, and maturity benchmarked are rejected. The fixture reads the existing disambiguation and maturity source contracts; it introduces no second lifecycle writer.

Exported Go and capability candidates (#6310)

The go-source inventory emits two candidate classes for review rather than silently declaring either canonical:

• an exported Go symbol candidate is an exported package-level type, function, variable, or constant from ordinary source; and
• a package capability token is a literal passed to abi.RegisterCapability, representing explicit negotiation vocabulary rather than an authorization verdict.

InventoryGoSource walks an injected public filesystem deterministically and excludes _test.go, generated files carrying the standard Code generated … DO NOT EDIT. marker, methods, and unexported helpers. Run fak disambiguation go-source-self-test --json for a fixture proving stable ordering and every exclusion rule. The inventory is a read-only candidate source; the canonical index remains the only terminology writer.

Module, leaf, lane, and stamp ownership (#6313)

Four identities form one checked chain without becoming synonyms:

• module revision identity is the history-derived module@rN+gSHA version surface;
• leaf identity is the semantic package or command owner attributed by a commit;
• dispatch ownership lane is the file-tree concurrency region used for admission; and
• fak commit stamp is the validated (fak <leaf>) subject token.

Run fak disambiguation ownership-source-self-test --json to resolve a fixture path to all four fields. ResolveOwnershipFixture returns typed leaf-mismatch, lane-mismatch, and stamp-mismatch errors instead of guessing from similar names. The fixture reads the public ownership, module-version, and commit-lint contracts and does not duplicate their writers.

Freshness and coverage metrics (#6322)

fak disambiguation metrics --json derives its report directly from the public index. It groups entries by all four freshness verdicts, source-family probe, and leaf@lane owner, and reserves an uncovered-candidate-class breakdown populated from coverage findings. Freshness and owner counts each sum exactly to total; no metric is a second index writer.

The JSON schema is fak-disambiguation-metrics/1. Empty classes remain explicit where a closed vocabulary is meaningful (including zero freshness verdicts), while source, owner, and uncovered-class rows are sorted by key for deterministic output.

Typed index change impact (#6323)

fak disambiguation diff --before OLD.json --after NEW.json --json compares two generated indexes and emits deterministic change rows. The taxonomy is additive, alias move, semantic change, contrast change, owner move, stale transition, and removal; every row also carries query compatibility impact as compatible, review, or breaking.

Additions and pure owner moves preserve query compatibility. Definition, scope, contrast, and freshness transitions require review. Canonical removals and removed aliases are breaking because an existing exact query can stop resolving. The diff is read-only and accepts the generated-index schema rather than creating another index representation.

Alias and removal migration checks (#6324)

ValidateMigrations consumes the typed diff report. A canonical removal or breaking alias move is rejected as silent identity removal unless a migration record names the removed term, replacement target, deprecation version, and distinct removal version. Invalid or zero-window records fail separately as migration record invalid; an explicit breaking record remains available for deliberate cutovers.

Run fak disambiguation migration-self-test --json to witness silent-removal refusal and acceptance of a versioned alias migration with a replacement target. Migration records authorize compatibility changes; they do not mutate either index.

End-to-end agent lookup demo (#6325)

go run ./cmd/disambiguationdemo -selfcheck searches the overloaded canonical term runtime, captures the five scoped choices, selects runtime=gateway-serving, and prints the canonical contrast. -json emits the deterministic fak-disambiguation-demo/1 receipt. The captured test proves the whole path is local public-index logic: no model, API key, GPU, network, or private data is required.

Projected-scale benchmark (#6327)

scale_benchmark_test.go exercises deterministic generation plus exact, alias, and reverse queries at 4,096 valid entries. Every benchmark logs dataset size, tuned implementation baseline, OS/architecture and Go scope, and OBSERVED provenance; it reports machine-readable entry/provenance/baseline metrics as well. The dated observed run and exact reproduce command are captured in docs/benchmarks/DISAMBIGUATION-SCALE-2026-08-17.md. These are scoped observations, not unsupported cross-hardware gains.

Public-safe issue-contract suggestions (#6328)

SuggestIssue turns one uncovered coverage finding into a read-only contract containing title, problem, done condition, acceptance gate, likely files, and dedupe query. It never invokes GitHub or files an issue. Before rendering, the candidate term and source are passed through the same public-safety admission used by index entries, so credentials, local paths, private repositories or hosts, and control text are refused.

Run fak disambiguation issue-suggest-self-test --json to capture all required fields, explicit no_auto_file, and refusal of an unsafe local-path candidate. Operators may review and file an emitted contract through the normal guarded issue workflow.

Documentation

Overview

Package disambiguation defines the canonical machine-readable record shared by fak's terminology index generator and readers.

EntrySchemaVersion is the wire contract. Version 1 is intentionally pinned: readers reject unknown versions, unknown JSON fields, trailing JSON values, and incomplete required groups. Any field addition, rename, removal, or type change therefore needs a new schema version instead of being interpreted as v1. Empty aliases are represented by [] rather than by an absent or null field.

The package owns the record, parser, validation, hermetic selfchecks, coverage, and incidental local-token classification contracts. It performs no filesystem or network writes, so the generator remains the single writer of the derived disambiguation index.

Index

• Constants
• Variables
• func AdmitOwnership(entries []Entry, manifests PublicManifests) error
• func Explain(result QueryResponse) string
• func FindRepositoryRoot(start string) (string, error)
• func GenerateIndex(entries []Entry) ([]byte, error)
• func GeneratePublicIndex() ([]byte, error)
• func SelfTest() error
• func SumMetrics(counts []MetricsCount) int
• func ValidateClaimTermFixture(f ClaimTermFixture) error
• func ValidateVocabulary(terms []VocabularyTerm) error
• func ValidationCode(err error) string
• type ActivationMode
• type CLISourceReport
  • func IndexCLISource(help string, prior []CLITerm) CLISourceReport
• type CLITerm
• type CLITermKind
• type CacheSourceResolution
• type CacheSourceSelfTestReport
  • func RunCacheSourceSelfTest() (CacheSourceSelfTestReport, error)
• type ChangeKind
• type ClaimTermFixture
• type ClaimsSourceSelfTestReport
  • func RunClaimsSourceSelfTest() (ClaimsSourceSelfTestReport, error)
• type CommittedFreshnessReport
  • func EvaluateCommittedFreshness(committed, overlay []byte, probeErr error) CommittedFreshnessReport
• type CommittedFreshnessVerdict
• type CompatibilityImpact
• type Contrast
• type CoverageFinding
• type CoverageReport
  • func InventoryCoverage(root fs.FS, surfaces []PublicTerminologySurface, index *Index, ...) (CoverageReport, error)
• type CoverageSelfCheckReport
  • func CoverageSelfCheck() CoverageSelfCheckReport
• type DiffReport
  • func DiffIndexes(before, after []Entry) DiffReport
• type DispatchIdentity
  • func ResolveDispatchIdentity(input DispatchIdentityInput) (DispatchIdentity, error)
• type DispatchIdentityInput
• type DocPage
  • func RenderDocs(entries []Entry) ([]DocPage, error)
  • func RenderPublicDocs() ([]DocPage, error)
• type Entry
  • func DecodeGeneratedIndex(data []byte) ([]Entry, error)
  • func ParseEntry(data []byte) (Entry, error)
  • func ProbePublicReferences(repoRoot string, entry Entry) Entry
  • func SelfTestEntry() Entry
  • func (e Entry) Validate() error
• type FleetSourceResolution
• type FleetSourceSelfTestReport
  • func RunFleetSourceSelfTest() (FleetSourceSelfTestReport, error)
• type Freshness
  • func EvaluateFreshness(observation FreshnessProbe) Freshness
• type FreshnessProbe
• type FreshnessReasonDescriptor
• type FreshnessSelfCheckCase
• type FreshnessSelfCheckReport
  • func FreshnessSelfCheck() FreshnessSelfCheckReport
• type FreshnessVerdict
• type GeneratedIndex
• type GoCandidateKind
• type GoSourceCandidate
• type GoSourceInventory
  • func InventoryGoSource(source fs.FS, root string) (GoSourceInventory, error)
• type GoSourceSelfTestReport
  • func RunGoSourceSelfTest() (GoSourceSelfTestReport, error)
• type Identity
• type IncidentalTerm
• type Index
  • func NewAdmittedIndex(entries []Entry, manifests PublicManifests) (*Index, error)
  • func NewClassifiedIndex(entries []Entry, classifications []TermClassification) (*Index, error)
  • func NewIndex(entries []Entry) (*Index, error)
  • func (i *Index) Classifications() []TermClassification
  • func (i *Index) ReverseLookup(kind ReverseLocatorKind, value string) (ReverseLookupResponse, error)
  • func (i *Index) Search(term string) SearchResponse
• type IndexChange
• type IndexVersion
  • func CurrentIndexVersion() (IndexVersion, error)
  • func VersionIndex(entries []Entry) (IndexVersion, error)
• type IssueSuggestion
  • func SuggestIssue(finding CoverageFinding) (IssueSuggestion, error)
• type IssueSuggestionSelfTestReport
  • func RunIssueSuggestionSelfTest() (IssueSuggestionSelfTestReport, error)
• type LadderKind
• type Lifecycle
• type LifecycleClass
• type LifecycleLadderResolution
• type LifecycleSourceSelfTestReport
  • func RunLifecycleSourceSelfTest() (LifecycleSourceSelfTestReport, error)
• type MetricsCount
• type MetricsReport
  • func Metrics(entries []Entry, coverage CoverageReport) MetricsReport
  • func PublicMetrics() MetricsReport
• type MigrationRecord
• type MigrationReport
  • func ValidateMigrations(changes DiffReport, records []MigrationRecord) (MigrationReport, error)
• type MigrationSelfTestReport
  • func RunMigrationSelfTest() (MigrationSelfTestReport, error)
• type Owner
• type OwnershipBinding
  • func ResolveOwnershipFixture(f OwnershipFixture) (OwnershipBinding, error)
• type OwnershipFixture
• type OwnershipMismatchError
  • func (e *OwnershipMismatchError) Error() string
• type OwnershipMismatchKind
• type OwnershipSelfCheckReport
  • func OwnershipSelfCheck() OwnershipSelfCheckReport
• type OwnershipSourceSelfTestReport
  • func RunOwnershipSourceSelfTest() (OwnershipSourceSelfTestReport, error)
• type PolicySourceResolution
• type PolicySourceSelfTestReport
  • func RunPolicySourceSelfTest() (PolicySourceSelfTestReport, error)
• type ProvenanceSelfCheckReport
  • func ProvenanceSelfCheck() ProvenanceSelfCheckReport
• type PublicManifests
  • func LoadPublicManifests(repoRoot string) (PublicManifests, error)
• type PublicReference
• type PublicTerminologySurface
• type QueryResponse
  • func Query(canonicalTerm string) (QueryResponse, error)
  • func QueryScoped(canonicalTerm string, scope Scope) (QueryResponse, error)
  • func Resolve(term string) (QueryResponse, error)
  • func ResolveLadderSpelling(kind LadderKind, spelling string) (QueryResponse, error)
  • func ResolveScoped(term string, scope Scope) (QueryResponse, error)
• type QuerySelfTestReport
  • func RunQuerySelfTest() (QuerySelfTestReport, error)
• type ReasonSourceSelfTestReport
  • func RunReasonSourceSelfTest() (ReasonSourceSelfTestReport, error)
• type ReverseLocatorKind
• type ReverseLookupResponse
  • func ReverseLookup(kind ReverseLocatorKind, value string) (ReverseLookupResponse, error)
• type ReverseMatch
• type ReverseSelfTestCase
• type ReverseSelfTestReport
  • func RunReverseSelfTest() (ReverseSelfTestReport, error)
• type RuntimeSourceResolution
• type RuntimeSourceSelfTestReport
  • func RunRuntimeSourceSelfTest() (RuntimeSourceSelfTestReport, error)
• type SchemaDescriptor
  • func Descriptor() SchemaDescriptor
• type Scope
• type SearchGroups
• type SearchMatch
• type SearchResponse
  • func Search(term string) SearchResponse
• type SearchVerdict
• type SelfTestReport
  • func RunSelfTest() (SelfTestReport, error)
• type SessionSourceResolution
• type SessionSourceSelfTestReport
  • func RunSessionSourceSelfTest() (SessionSourceSelfTestReport, error)
• type SourceWitness
• type StaleSymbolsSelfCheckReport
  • func StaleSymbolsSelfCheck() StaleSymbolsSelfCheckReport
• type TermClassification
  • func ValidateClassifications(items []TermClassification) ([]TermClassification, error)
• type ValidationError
  • func (e *ValidationError) Error() string
• type VocabularyKind
• type VocabularyTerm
  • func PublicReasonVocabulary() []VocabularyTerm

Constants

const (
	// ClassificationIncidental marks a local exported implementation token as
	// coverage-accounted without admitting it as a canonical glossary identity.
	ClassificationIncidental = "incidental"
	// ClassificationReasonLocalImplementation is the stable reason code for an
	// exported Go identifier that is implementation vocabulary rather than a
	// public concept agents should query.
	ClassificationReasonLocalImplementation = "LOCAL_IMPLEMENTATION_TOKEN"
)

const (
	CoverageReasonMissingClassification = "MISSING_TERM_CLASSIFICATION"
	CoverageClassCanonical              = "canonical"
	CoverageClassIncidental             = "incidental"
)

const (
	FreshnessReasonSourceCurrent     = "SOURCE_CURRENT"
	FreshnessReasonSourceOutdated    = "SOURCE_OUTDATED"
	FreshnessReasonProbeUnavailable  = "PROBE_UNAVAILABLE"
	FreshnessReasonEvidenceMalformed = "EVIDENCE_MALFORMED"
)

Stable freshness reason codes. These values are part of the public JSON contract; callers should branch on them rather than human-readable text.

const (
	SourceKindDocument       = "document"
	SourceKindGoSource       = "go-source"
	SourceKindTest           = "test"
	SourceKindGeneratedIndex = "generated-index"
	SourceKindGitHubMetadata = "github-metadata"

	ErrProvenanceSourceKind       = "DISAMBIGUATION_PROVENANCE_SOURCE_KIND_UNVERIFIABLE"
	ErrProvenanceLocatorAbsolute  = "DISAMBIGUATION_PROVENANCE_LOCATOR_ABSOLUTE"
	ErrProvenanceLocatorEscape    = "DISAMBIGUATION_PROVENANCE_LOCATOR_ESCAPE"
	ErrProvenanceLocatorInvalid   = "DISAMBIGUATION_PROVENANCE_LOCATOR_INVALID"
	ErrProvenanceRevisionInvalid  = "DISAMBIGUATION_PROVENANCE_REVISION_INVALID"
	ErrProvenanceCheckedAtInvalid = "DISAMBIGUATION_PROVENANCE_CHECKED_AT_INVALID"
	ErrProvenanceProbeInvalid     = "DISAMBIGUATION_PROVENANCE_PROBE_IDENTITY_INVALID"
	ErrProvenanceReferenceInvalid = "DISAMBIGUATION_PROVENANCE_REFERENCE_INVALID"
)

Public source kinds are intentionally closed: each kind denotes material that can be independently read from the public fak repository checkout.

const (
	ErrPublicSafetyLocalPath   = "DISAMBIGUATION_PUBLIC_SAFETY_LOCAL_PATH"
	ErrPublicSafetyCredential  = "DISAMBIGUATION_PUBLIC_SAFETY_CREDENTIAL"
	ErrPublicSafetyPrivateRepo = "DISAMBIGUATION_PUBLIC_SAFETY_PRIVATE_REPOSITORY"
	ErrPublicSafetyPrivateHost = "DISAMBIGUATION_PUBLIC_SAFETY_PRIVATE_HOST"
	ErrPublicSafetyControlText = "DISAMBIGUATION_PUBLIC_SAFETY_CONTROL_TEXT"
)

const (
	ReferenceKindGoSymbol   = "go-symbol"
	ReferenceKindCLIVerb    = "cli-verb"
	ReferenceKindReasonCode = "reason-code"
	ReferenceKindDocAnchor  = "doc-anchor"

	FreshnessReasonPublicSymbolMissing = "PUBLIC_SYMBOL_MISSING"
	FreshnessReasonCLIVerbMissing      = "CLI_VERB_MISSING"
	FreshnessReasonReasonCodeMissing   = "REASON_CODE_MISSING"
	FreshnessReasonDocAnchorMissing    = "DOCUMENT_ANCHOR_MISSING"
)

Public reference kinds identify repository-visible contracts that can become stale independently of the file carrying them.

const CLISourceSchemaVersion = "fak-disambiguation-cli-source/1"

CLISourceSchemaVersion identifies terminology derived from fak's public help.

const CacheSourceSelfTestSchemaVersion = "fak-disambiguation-cache-source-self-test/1"

const ClaimsSourceSelfTestSchemaVersion = "fak-disambiguation-claims-source-self-test/1"

const ClassificationSchemaVersion = "fak-disambiguation-classification/1"

const CoverageSchemaVersion = "fak-disambiguation-coverage/1"

const DiffSchemaVersion = "fak-disambiguation-diff/1"

const EntrySchemaVersion = "fak-disambiguation-entry/1"

EntrySchemaVersion is the only entry schema this package understands.

Version 1 is fail-closed: ParseEntry rejects a different schema value instead of guessing that a future or historical record has the current meaning.

const FleetSourceSelfTestSchemaVersion = "fak-disambiguation-fleet-source-self-test/1"

const GeneratedDocsSchemaVersion = "fak-disambiguation-docs/1"

const GeneratedIndexSchemaVersion = "fak-disambiguation-index/1"

const GoSourceSelfTestSchemaVersion = "fak-disambiguation-go-source-self-test/1"

const IndexVersionSchema = "fak-disambiguation-index-version/1"

const IssueSuggestionSchemaVersion = "fak-disambiguation-issue-suggestion/1"

const LifecycleSourceSelfTestSchemaVersion = "fak-disambiguation-lifecycle-source-self-test/1"

const MetricsSchemaVersion = "fak-disambiguation-metrics/1"

const MigrationSchemaVersion = "fak-disambiguation-migration/1"

const OwnershipSourceSelfTestSchemaVersion = "fak-disambiguation-ownership-source-self-test/1"

const PolicySourceSelfTestSchemaVersion = "fak-disambiguation-policy-source-self-test/1"

const PublicIndexVersion = "public-seed/1"

PublicIndexVersion identifies the immutable public seed set used by this reader. The later generator may replace the seed while retaining this read contract.

const QuerySchemaVersion = "fak-disambiguation-query/1"

QuerySchemaVersion identifies the canonical-identity query response contract.

const ReasonSourceSelfTestSchemaVersion = "fak-disambiguation-reason-source-self-test/1"

const ReverseLookupSchemaVersion = "fak-disambiguation-reverse/1"

ReverseLookupSchemaVersion identifies the locator-to-canonical-identity contract.

const RuntimeSourceSelfTestSchemaVersion = "fak-disambiguation-runtime-source-self-test/1"

const SearchSchemaVersion = "fak-disambiguation-search/1"

SearchSchemaVersion identifies the ranked terminology-search response contract.

const SessionSourceSelfTestSchemaVersion = "fak-disambiguation-session-source-self-test/1"

Variables

var (
	ErrReverseKindInvalid = errors.New("invalid reverse locator kind")
	ErrReverseNotFound    = errors.New("reverse locator not found")
)

var ErrCanonicalTermNotFound = errors.New("canonical term not found")

ErrCanonicalTermNotFound reports that an exact canonical-term lookup missed.

var ErrClaimBaselineMissing = errors.New("claim baseline missing")

var ErrClaimProvenanceMissing = errors.New("claim provenance missing")

var ErrClaimScopeMissing = errors.New("claim scope missing")

var ErrDispatchIdentityMissing = errors.New("dispatch identity missing from structured fields")

var ErrIssueSuggestionIncomplete = errors.New("incomplete issue suggestion candidate")

var ErrIssueSuggestionUnsafe = errors.New("unsafe issue suggestion candidate")

var ErrLadderSpelling = errors.New("incompatible ladder spelling")

var ErrMigrationRecordInvalid = errors.New("migration record invalid")

var ErrScopeRequired = errors.New("scope required for overloaded term")

ErrScopeRequired reports that a token has multiple scoped owners and cannot be resolved safely without an exact scope qualifier.

var ErrSilentRemoval = errors.New("silent identity removal")

var ErrVocabularyCollision = errors.New("incompatible vocabulary collision")

Functions

func AdmitOwnership

func AdmitOwnership(entries []Entry, manifests PublicManifests) error

AdmitOwnership rejects entries that cannot be routed through both public registries. It is called by generation before any output is written.

func Explain

func Explain(result QueryResponse) string

Explain renders one resolved entry for a human while QueryResult remains the stable machine contract.

func FindRepositoryRoot

func FindRepositoryRoot(start string) (string, error)

FindRepositoryRoot finds the public repository manifests without consulting private configuration or environment-specific state.

func GenerateIndex

func GenerateIndex(entries []Entry) ([]byte, error)

func GeneratePublicIndex

func GeneratePublicIndex() ([]byte, error)

func SelfTest

func SelfTest() error

SelfTest is the compact compatibility seam used by package tests and callers. Detailed omission evidence is available from RunSelfTest.

func SumMetrics

func SumMetrics(counts []MetricsCount) int

func ValidateClaimTermFixture

func ValidateClaimTermFixture(f ClaimTermFixture) error

func ValidateVocabulary

func ValidateVocabulary(terms []VocabularyTerm) error

ValidateVocabulary rejects an overloaded code unless every declaration names the same kind and canonical meaning. Package and symbol may differ: that is a declared cross-package alias, not a semantic collision.

func ValidationCode

func ValidationCode(err error) string

ValidationCode extracts a stable code without parsing an error string.

Types

type ActivationMode

type ActivationMode string

ActivationMode is the normalized activation posture carried with an entry.

const (
	RolloutOff    ActivationMode = "off"
	RolloutShadow ActivationMode = "shadow"
	RolloutOn     ActivationMode = "on"
)

type CLISourceReport

type CLISourceReport struct {
	Schema string    `json:"schema"`
	Terms  []CLITerm `json:"terms"`
	Stale  []CLITerm `json:"stale"`
}

CLISourceReport is a read-only projection of the public help source. Stale contains prior terms no longer emitted by that source.

func IndexCLISource

func IndexCLISource(help string, prior []CLITerm) CLISourceReport

IndexCLISource derives terminology from fak usage synopsis lines and compares it with an optional prior snapshot. It never writes the canonical index.

type CLITerm

type CLITerm struct {
	Term       string      `json:"term"`
	Kind       CLITermKind `json:"kind"`
	Invocation string      `json:"invocation"`
}

CLITerm is one command, subcommand, or long flag discovered from a public usage synopsis. Invocation preserves the command context for overloaded flags.

type CLITermKind

type CLITermKind string

CLITermKind names the CLI namespace that owns a discovered term.

const (
	CLITermCommand    CLITermKind = "command"
	CLITermSubcommand CLITermKind = "subcommand"
	CLITermFlag       CLITermKind = "flag"
)

type CacheSourceResolution

type CacheSourceResolution struct {
	Input         string `json:"input"`
	CanonicalTerm string `json:"canonical_term"`
	OwnerLeaf     string `json:"owner_leaf"`
	Scope         string `json:"scope"`
	SourcePath    string `json:"source_path"`
	ContrastCount int    `json:"contrast_count"`
}

CacheSourceResolution captures the four axes that distinguish one cache.

type CacheSourceSelfTestReport

type CacheSourceSelfTestReport struct {
	Schema       string                  `json:"schema"`
	IndexVersion string                  `json:"index_version"`
	Resolutions  []CacheSourceResolution `json:"resolutions"`
	Pairwise     bool                    `json:"pairwise_contrasts_complete"`
}

CacheSourceSelfTestReport proves all four cache concepts resolve through the public index and carry complete pairwise distinctions.

func RunCacheSourceSelfTest

func RunCacheSourceSelfTest() (CacheSourceSelfTestReport, error)

RunCacheSourceSelfTest resolves four overloaded cache names and verifies each record contrasts with every sibling using public provenance.

type ChangeKind

type ChangeKind string

const (
	ChangeAdditive        ChangeKind = "additive"
	ChangeAliasMove       ChangeKind = "alias-move"
	ChangeSemantic        ChangeKind = "semantic-change"
	ChangeContrast        ChangeKind = "contrast-change"
	ChangeOwnerMove       ChangeKind = "owner-move"
	ChangeStaleTransition ChangeKind = "stale-transition"
	ChangeRemoval         ChangeKind = "removal"
)

type ClaimTermFixture

type ClaimTermFixture struct {
	Term       string `json:"term"`
	Baseline   string `json:"baseline"`
	Provenance string `json:"provenance"`
	Scope      string `json:"scope"`
}

type ClaimsSourceSelfTestReport

type ClaimsSourceSelfTestReport struct {
	Schema                    string   `json:"schema"`
	IndexVersion              string   `json:"index_version"`
	CanonicalTerms            []string `json:"canonical_terms"`
	MissingBaselineRejected   bool     `json:"missing_baseline_rejected"`
	MissingProvenanceRejected bool     `json:"missing_provenance_rejected"`
	MissingScopeRejected      bool     `json:"missing_scope_rejected"`
}

func RunClaimsSourceSelfTest

func RunClaimsSourceSelfTest() (ClaimsSourceSelfTestReport, error)

type CommittedFreshnessReport

type CommittedFreshnessReport struct {
	Schema         string                    `json:"schema"`
	Verdict        CommittedFreshnessVerdict `json:"verdict"`
	CommittedClean bool                      `json:"committed_clean"`
	OverlayDrift   bool                      `json:"overlay_drift"`
	ProbeAvailable bool                      `json:"probe_available"`
	Reason         string                    `json:"reason,omitempty"`
}

func EvaluateCommittedFreshness

func EvaluateCommittedFreshness(committed, overlay []byte, probeErr error) CommittedFreshnessReport

type CommittedFreshnessVerdict

type CommittedFreshnessVerdict string

const (
	CommittedFreshnessClean        CommittedFreshnessVerdict = "committed-clean"
	CommittedFreshnessOverlayDrift CommittedFreshnessVerdict = "own-overlay-drift"
	CommittedFreshnessUnavailable  CommittedFreshnessVerdict = "unavailable"
)

type CompatibilityImpact

type CompatibilityImpact string

const (
	ImpactCompatible CompatibilityImpact = "compatible"
	ImpactReview     CompatibilityImpact = "review"
	ImpactBreaking   CompatibilityImpact = "breaking"
)

type Contrast

type Contrast struct {
	CanonicalTerm       string `json:"canonical_term"`
	Explanation         string `json:"explanation"`
	RequiredPair        *bool  `json:"required_pair"`
	ForbiddenConflation *bool  `json:"forbidden_conflation"`
}

Contrast names one concept this entry must not be conflated with and explains the distinction. Cross-entry existence and symmetry checks belong to the index validator; this record validator guarantees the pair is expressible.

type CoverageFinding

type CoverageFinding struct {
	Surface   string `json:"surface"`
	Term      string `json:"term"`
	Candidate string `json:"candidate"`
	Reason    string `json:"reason"`
}

type CoverageReport

type CoverageReport struct {
	SchemaVersion   string                     `json:"schema_version"`
	Surfaces        []PublicTerminologySurface `json:"surfaces"`
	Findings        []CoverageFinding          `json:"findings"`
	Classifications []TermClassification       `json:"classifications"`
	Candidates      int                        `json:"candidates"`
	Canonical       int                        `json:"canonical"`
	Incidental      int                        `json:"incidental"`
	OK              bool                       `json:"ok"`
}

func InventoryCoverage

func InventoryCoverage(root fs.FS, surfaces []PublicTerminologySurface, index *Index, incidental []IncidentalTerm) (CoverageReport, error)

InventoryCoverage checks only explicitly declared public surfaces. Go packages are parsed from the supplied public repository filesystem; no network or private input is used.

type CoverageSelfCheckReport

type CoverageSelfCheckReport struct {
	SchemaVersion        string `json:"schema_version"`
	ClassificationSchema string `json:"classification_schema"`
	DetectedReason       string `json:"detected_reason"`
	Classification       string `json:"classification"`
	ClassificationReason string `json:"classification_reason"`
	Detected             bool   `json:"detected"`
	Covered              bool   `json:"covered"`
	AbsentFromQuery      bool   `json:"absent_from_query"`
	Cleared              bool   `json:"cleared"`
	Passed               bool   `json:"passed"`
}

func CoverageSelfCheck

func CoverageSelfCheck() CoverageSelfCheckReport

type DiffReport

type DiffReport struct {
	Schema  string        `json:"schema"`
	Changes []IndexChange `json:"changes"`
}

func DiffIndexes

func DiffIndexes(before, after []Entry) DiffReport

type DispatchIdentity

type DispatchIdentity struct {
	WorkerID string `json:"worker_id"`
	Issue    string `json:"issue"`
	Lane     string `json:"lane"`
	LeaseID  string `json:"lease_id"`
}

DispatchIdentity is derived exclusively from structured fields.

func ResolveDispatchIdentity

func ResolveDispatchIdentity(input DispatchIdentityInput) (DispatchIdentity, error)

ResolveDispatchIdentity refuses to mine identity from narration. Narration is retained for display/forensics by callers but carries zero identity authority.

type DispatchIdentityInput

type DispatchIdentityInput struct {
	WorkerID  string `json:"worker_id"`
	Issue     string `json:"issue"`
	Lane      string `json:"lane"`
	LeaseID   string `json:"lease_id"`
	Narration string `json:"narration"`
}

DispatchIdentityInput separates authoritative dispatch fields from worker-authored narration.

type DocPage

type DocPage struct {
	Path    string
	Content []byte
}

DocPage is one deterministic documentation artifact rendered from the canonical terminology index.

func RenderDocs

func RenderDocs(entries []Entry) ([]DocPage, error)

RenderDocs renders canonical-term pages without introducing a second source of terminology truth.

func RenderPublicDocs

func RenderPublicDocs() ([]DocPage, error)

RenderPublicDocs renders the human-readable projection of the same records used by GeneratePublicIndex and the query commands.

type Entry

type Entry struct {
	Schema     string          `json:"schema"`
	Identity   Identity        `json:"identity"`
	Definition string          `json:"definition"`
	Contrasts  []Contrast      `json:"contrasts"`
	Scope      Scope           `json:"scope"`
	Owner      Owner           `json:"owner"`
	Sources    []SourceWitness `json:"sources"`
	Freshness  Freshness       `json:"freshness"`
	Lifecycle  Lifecycle       `json:"lifecycle"`
}

Entry is one canonical distinction in fak's disambiguation index.

The groups are values rather than open maps so producers and consumers share one shape. ParseEntry is the persisted-wire admission seam; programmatically constructed entries use Validate before entering a generated index.

func DecodeGeneratedIndex

func DecodeGeneratedIndex(data []byte) ([]Entry, error)

func ParseEntry

func ParseEntry(data []byte) (Entry, error)

ParseEntry decodes exactly one v1 JSON record. It rejects unknown fields at every nesting level, trailing documents, unknown schema versions, and entries that fail Validate.

func ProbePublicReferences

func ProbePublicReferences(repoRoot string, entry Entry) Entry

ProbePublicReferences re-evaluates an entry's cited public references from a repository checkout. It only reads repository-visible files and does not write or register entries. Invalid evidence outranks unavailable probes; unavailable probes outrank missing references, preserving #6280 precedence.

func SelfTestEntry

func SelfTestEntry() Entry

SelfTestEntry returns a deterministic complete public-source record used by the package self-test and CLI witness. It is sample data, not an index writer.

func (Entry) Validate

func (e Entry) Validate() error

Validate enforces the complete v1 entry contract without consulting ambient repository, network, or clock state.

type FleetSourceResolution

type FleetSourceResolution struct {
	Input         string `json:"input"`
	CanonicalTerm string `json:"canonical_term"`
	OwnerLeaf     string `json:"owner_leaf"`
	SourcePath    string `json:"source_path"`
}

FleetSourceResolution is one public fleet/dispatch concept.

type FleetSourceSelfTestReport

type FleetSourceSelfTestReport struct {
	Schema             string                  `json:"schema"`
	IndexVersion       string                  `json:"index_version"`
	Resolutions        []FleetSourceResolution `json:"resolutions"`
	NarrationRejected  bool                    `json:"narration_identity_rejected"`
	StructuredAccepted bool                    `json:"structured_identity_accepted"`
}

FleetSourceSelfTestReport captures terminology and narration-safety proof.

func RunFleetSourceSelfTest

func RunFleetSourceSelfTest() (FleetSourceSelfTestReport, error)

RunFleetSourceSelfTest resolves all eight terms and proves a persuasive worker sentence cannot become dispatch identity without structured fields.

type Freshness

type Freshness struct {
	Verdict    FreshnessVerdict `json:"verdict"`
	ReasonCode string           `json:"reason_code"`
	CheckedAt  string           `json:"checked_at"`
	Probe      string           `json:"probe"`
}

Freshness records the last source-check outcome and the public probe that produced it. CheckedAt is RFC 3339 so JSON consumers do not have to guess a locale or timezone. ReasonCode is required for every verdict, including fresh.

func EvaluateFreshness

func EvaluateFreshness(observation FreshnessProbe) Freshness

EvaluateFreshness converts one public probe observation into the four-state wire verdict. Invalid probe metadata or malformed returned evidence outranks age; probe unavailability is unknown; only valid, available, current evidence can be fresh. It performs no I/O and is not an index writer.

type FreshnessProbe

type FreshnessProbe struct {
	Probe         string `json:"probe"`
	CheckedAt     string `json:"checked_at"`
	Available     bool   `json:"available"`
	EvidenceValid bool   `json:"evidence_valid"`
	Current       bool   `json:"current"`
}

FreshnessProbe is the public-only observation consumed by EvaluateFreshness. EvidenceValid applies only when Available is true. An unavailable probe has no evidence to validate and therefore yields unknown, never fresh.

type FreshnessReasonDescriptor

type FreshnessReasonDescriptor struct {
	Verdict    FreshnessVerdict `json:"verdict"`
	ReasonCode string           `json:"reason_code"`
}

FreshnessReasonDescriptor binds a public verdict to its stable reason code.

type FreshnessSelfCheckCase

type FreshnessSelfCheckCase struct {
	Verdict    FreshnessVerdict `json:"verdict"`
	ReasonCode string           `json:"reason_code"`
	Passed     bool             `json:"passed"`
}

FreshnessSelfCheckCase is one row of the hermetic four-state package witness.

type FreshnessSelfCheckReport

type FreshnessSelfCheckReport struct {
	Schema string                   `json:"schema"`
	Cases  []FreshnessSelfCheckCase `json:"cases"`
	Passed bool                     `json:"passed"`
}

FreshnessSelfCheckReport is the stable CLI/package JSON witness.

func FreshnessSelfCheck

func FreshnessSelfCheck() FreshnessSelfCheckReport

FreshnessSelfCheck exercises every public state without filesystem, network, private-source, or writer dependencies.

type FreshnessVerdict

type FreshnessVerdict string

FreshnessVerdict is the four-state result of checking an entry's cited public sources. Unknown means evidence could not be obtained; invalid means evidence was obtained but could not be interpreted as a valid witness.

const (
	FreshnessFresh   FreshnessVerdict = "fresh"
	FreshnessStale   FreshnessVerdict = "stale"
	FreshnessUnknown FreshnessVerdict = "unknown"
	FreshnessInvalid FreshnessVerdict = "invalid"
)

type GeneratedIndex

type GeneratedIndex struct {
	Schema         string  `json:"schema"`
	SourceRevision string  `json:"source_revision"`
	EntryCount     int     `json:"entry_count"`
	Entries        []Entry `json:"entries"`
}

type GoCandidateKind

type GoCandidateKind string

const (
	GoCandidateSymbol     GoCandidateKind = "exported-symbol"
	GoCandidateCapability GoCandidateKind = "capability-token"
)

type GoSourceCandidate

type GoSourceCandidate struct {
	Kind       GoCandidateKind `json:"kind"`
	Name       string          `json:"name"`
	Package    string          `json:"package"`
	SourcePath string          `json:"source_path"`
}

type GoSourceInventory

type GoSourceInventory struct {
	Schema             string              `json:"schema"`
	Candidates         []GoSourceCandidate `json:"candidates"`
	ExcludedTests      int                 `json:"excluded_tests"`
	ExcludedGenerated  int                 `json:"excluded_generated"`
	ExcludedUnexported int                 `json:"excluded_unexported"`
}

func InventoryGoSource

func InventoryGoSource(source fs.FS, root string) (GoSourceInventory, error)

type GoSourceSelfTestReport

type GoSourceSelfTestReport struct {
	Schema             string              `json:"schema"`
	Candidates         []GoSourceCandidate `json:"candidates"`
	Deterministic      bool                `json:"deterministic"`
	TestsExcluded      bool                `json:"tests_excluded"`
	GeneratedExcluded  bool                `json:"generated_excluded"`
	UnexportedExcluded bool                `json:"unexported_excluded"`
}

func RunGoSourceSelfTest

func RunGoSourceSelfTest() (GoSourceSelfTestReport, error)

type Identity

type Identity struct {
	CanonicalTerm string   `json:"canonical_term"`
	Aliases       []string `json:"aliases"`
}

Identity names the canonical term and every declared alias. Aliases is required on the wire even when empty so absence cannot be mistaken for a producer that forgot to classify aliases.

type IncidentalTerm

type IncidentalTerm struct {
	Term   string `json:"term"`
	Reason string `json:"reason"`
}

type Index

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

Index is an immutable read index over canonical terms and their declared aliases. A token may have multiple owners only when every owner has a distinct, required scope.

func NewAdmittedIndex

func NewAdmittedIndex(entries []Entry, manifests PublicManifests) (*Index, error)

NewAdmittedIndex is the generator/admission constructor. It refuses to build an index until every ownership target exists in the public manifests.

func NewClassifiedIndex

func NewClassifiedIndex(entries []Entry, classifications []TermClassification) (*Index, error)

NewClassifiedIndex builds the single query/coverage index with strict local term classifications. It is the classification-aware form of NewIndex.

func NewIndex

func NewIndex(entries []Entry) (*Index, error)

NewIndex constructs a read-only index. Canonical terms and aliases share one exact, case-sensitive namespace. Repeated tokens are accepted only when their scope qualifiers are distinct; callers must then use a scoped lookup.

func (*Index) Classifications

func (i *Index) Classifications() []TermClassification

Classifications returns a stable copy of the classifications used by this index. Query results remain canonical-only.

func (*Index) ReverseLookup

func (i *Index) ReverseLookup(kind ReverseLocatorKind, value string) (ReverseLookupResponse, error)

ReverseLookup finds entries carrying the exact locator. Source paths also match the path portion of a locator with a document anchor.

func (*Index) Search

func (i *Index) Search(term string) SearchResponse

Search discovers terms in this index. Exact matches outrank prefixes, but all groups remain visible so callers can explain why a result is ambiguous.

type IndexChange

type IndexChange struct {
	Kind          ChangeKind          `json:"kind"`
	CanonicalTerm string              `json:"canonical_term"`
	Detail        string              `json:"detail"`
	QueryImpact   CompatibilityImpact `json:"query_impact"`
}

type IndexVersion

type IndexVersion struct {
	Schema         string `json:"schema"`
	IndexSchema    string `json:"index_schema"`
	SourceRevision string `json:"source_revision"`
	EntryCount     int    `json:"entry_count"`
	ContentSHA256  string `json:"content_sha256"`
}

func CurrentIndexVersion

func CurrentIndexVersion() (IndexVersion, error)

func VersionIndex

func VersionIndex(entries []Entry) (IndexVersion, error)

type IssueSuggestion

type IssueSuggestion struct {
	Schema         string   `json:"schema"`
	Title          string   `json:"title"`
	Problem        string   `json:"problem"`
	DoneCondition  string   `json:"done_condition"`
	AcceptanceGate string   `json:"acceptance_gate"`
	LikelyFiles    []string `json:"likely_files"`
	DedupeQuery    string   `json:"dedupe_query"`
}

func SuggestIssue

func SuggestIssue(finding CoverageFinding) (IssueSuggestion, error)

type IssueSuggestionSelfTestReport

type IssueSuggestionSelfTestReport struct {
	Schema         string          `json:"schema"`
	Suggestion     IssueSuggestion `json:"suggestion"`
	UnsafeRejected bool            `json:"unsafe_rejected"`
	NoAutoFile     bool            `json:"no_auto_file"`
}

func RunIssueSuggestionSelfTest

func RunIssueSuggestionSelfTest() (IssueSuggestionSelfTestReport, error)

type LadderKind

type LadderKind string

const (
	LadderLifecycle  LadderKind = "lifecycle"
	LadderActivation LadderKind = "activation"
	LadderMaturity   LadderKind = "maturity"
)

type Lifecycle

type Lifecycle struct {
	Class   LifecycleClass `json:"class"`
	Rollout ActivationMode `json:"rollout"`
}

Lifecycle separates the entry's authority class from its rollout posture.

type LifecycleClass

type LifecycleClass string

LifecycleClass states whether the entry describes current authority or material retained for a narrower historical or research purpose.

const (
	LifecycleCurrent   LifecycleClass = "current"
	LifecycleVersioned LifecycleClass = "versioned"
	LifecycleResearch  LifecycleClass = "research"
	LifecycleArchived  LifecycleClass = "archived"
)

type LifecycleLadderResolution

type LifecycleLadderResolution struct {
	Ladder        LadderKind `json:"ladder"`
	CanonicalTerm string     `json:"canonical_term"`
	Spellings     []string   `json:"spellings"`
	SourcePath    string     `json:"source_path"`
}

type LifecycleSourceSelfTestReport

type LifecycleSourceSelfTestReport struct {
	Schema                        string                      `json:"schema"`
	IndexVersion                  string                      `json:"index_version"`
	Ladders                       []LifecycleLadderResolution `json:"ladders"`
	IncompatibleSpellingsRejected bool                        `json:"incompatible_spellings_rejected"`
}

func RunLifecycleSourceSelfTest

func RunLifecycleSourceSelfTest() (LifecycleSourceSelfTestReport, error)

type MetricsCount

type MetricsCount struct {
	Key   string `json:"key"`
	Count int    `json:"count"`
}

type MetricsReport

type MetricsReport struct {
	Schema                    string         `json:"schema"`
	IndexVersion              string         `json:"index_version"`
	Total                     int            `json:"total"`
	Freshness                 []MetricsCount `json:"freshness"`
	SourceFamilies            []MetricsCount `json:"source_families"`
	Owners                    []MetricsCount `json:"owners"`
	UncoveredCandidateClasses []MetricsCount `json:"uncovered_candidate_classes"`
}

func Metrics

func Metrics(entries []Entry, coverage CoverageReport) MetricsReport

func PublicMetrics

func PublicMetrics() MetricsReport

type MigrationRecord

type MigrationRecord struct {
	RemovedTerm     string `json:"removed_term"`
	ReplacementTerm string `json:"replacement_term"`
	DeprecatedIn    string `json:"deprecated_in"`
	RemovedIn       string `json:"removed_in"`
	Breaking        bool   `json:"breaking"`
}

type MigrationReport

type MigrationReport struct {
	Schema   string            `json:"schema"`
	Accepted []MigrationRecord `json:"accepted"`
}

func ValidateMigrations

func ValidateMigrations(changes DiffReport, records []MigrationRecord) (MigrationReport, error)

type MigrationSelfTestReport

type MigrationSelfTestReport struct {
	Schema                 string `json:"schema"`
	SilentRemovalRejected  bool   `json:"silent_removal_rejected"`
	VersionedAliasAccepted bool   `json:"versioned_alias_accepted"`
	ReplacementTarget      string `json:"replacement_target"`
}

func RunMigrationSelfTest

func RunMigrationSelfTest() (MigrationSelfTestReport, error)

type Owner

type Owner struct {
	Leaf string `json:"leaf"`
	Lane string `json:"lane"`
}

Owner is the accountable fak leaf and dispatch lane for repairing drift.

type OwnershipBinding

type OwnershipBinding struct {
	Path        string `json:"path"`
	ModuleAtRev string `json:"module_at_rev"`
	Leaf        string `json:"leaf"`
	Lane        string `json:"lane"`
	Stamp       string `json:"stamp"`
}

func ResolveOwnershipFixture

func ResolveOwnershipFixture(f OwnershipFixture) (OwnershipBinding, error)

type OwnershipFixture

type OwnershipFixture struct {
	Path   string
	Module string
	Rev    int
	SHA    string
	Leaf   string
	Lane   string
	Stamp  string
}

type OwnershipMismatchError

type OwnershipMismatchError struct {
	Kind   OwnershipMismatchKind
	Detail string
}

func (*OwnershipMismatchError) Error

func (e *OwnershipMismatchError) Error() string

type OwnershipMismatchKind

type OwnershipMismatchKind string

const (
	OwnershipPathUnknown   OwnershipMismatchKind = "path-unknown"
	OwnershipLeafMismatch  OwnershipMismatchKind = "leaf-mismatch"
	OwnershipLaneMismatch  OwnershipMismatchKind = "lane-mismatch"
	OwnershipStampMismatch OwnershipMismatchKind = "stamp-mismatch"
)

type OwnershipSelfCheckReport

type OwnershipSelfCheckReport struct {
	OK              bool   `json:"ok"`
	AcceptedFixture bool   `json:"accepted_fixture"`
	RejectedLeaf    bool   `json:"rejected_owner_leaf"`
	RejectedLane    bool   `json:"rejected_dispatch_lane"`
	LeafSource      string `json:"leaf_source"`
	LaneSource      string `json:"lane_source"`
}

func OwnershipSelfCheck

func OwnershipSelfCheck() OwnershipSelfCheckReport

OwnershipSelfCheck proves both admission edges using repository-shaped public fixtures. The report is JSON-safe for the CLI selfcheck seam.

type OwnershipSourceSelfTestReport

type OwnershipSourceSelfTestReport struct {
	Schema             string           `json:"schema"`
	Binding            OwnershipBinding `json:"binding"`
	LeafMismatchTyped  bool             `json:"leaf_mismatch_typed"`
	LaneMismatchTyped  bool             `json:"lane_mismatch_typed"`
	StampMismatchTyped bool             `json:"stamp_mismatch_typed"`
}

func RunOwnershipSourceSelfTest

func RunOwnershipSourceSelfTest() (OwnershipSourceSelfTestReport, error)

type PolicySourceResolution

type PolicySourceResolution struct {
	Term          string `json:"term"`
	CanonicalTerm string `json:"canonical_term"`
	SourcePath    string `json:"source_path"`
	OwnerLeaf     string `json:"owner_leaf"`
}

type PolicySourceSelfTestReport

type PolicySourceSelfTestReport struct {
	Schema                     string                   `json:"schema"`
	IndexVersion               string                   `json:"index_version"`
	Resolutions                []PolicySourceResolution `json:"resolutions"`
	StructuralBeforeModel      bool                     `json:"structural_before_model"`
	CapabilityNotVerdict       bool                     `json:"capability_not_verdict"`
	IncompatibleReasonRejected bool                     `json:"incompatible_reason_rejected"`
}

func RunPolicySourceSelfTest

func RunPolicySourceSelfTest() (PolicySourceSelfTestReport, error)

type ProvenanceSelfCheckReport

type ProvenanceSelfCheckReport struct {
	Schema             string `json:"schema"`
	OK                 bool   `json:"ok"`
	RoundTrip          bool   `json:"round_trip"`
	RejectedAbsolute   bool   `json:"rejected_absolute"`
	RejectedEscape     bool   `json:"rejected_escape"`
	RejectedSourceKind bool   `json:"rejected_source_kind"`
}

ProvenanceSelfCheckReport is the JSON witness for strict public provenance.

func ProvenanceSelfCheck

func ProvenanceSelfCheck() ProvenanceSelfCheckReport

ProvenanceSelfCheck exercises the public valid and rejection seams without I/O.

type PublicManifests

type PublicManifests struct {
	Leaves []string `json:"leaves"`
	Lanes  []string `json:"lanes"`
}

PublicManifests is the admission view derived from the repository's existing public contracts. Leaves are real internal/<name> and cmd/<name> directories; lanes are declarations in dos.toml [lanes] and [lanes.trees].

func LoadPublicManifests

func LoadPublicManifests(repoRoot string) (PublicManifests, error)

LoadPublicManifests reads the authoritative public leaf and lane registries.

type PublicReference

type PublicReference struct {
	Kind string `json:"kind"`
	Name string `json:"name"`
}

PublicReference names a contract inside a public repository source.

type PublicTerminologySurface

type PublicTerminologySurface struct {
	Locator string `json:"locator"`
	Kind    string `json:"kind"`
}

type QueryResponse

type QueryResponse struct {
	Schema       string `json:"schema"`
	IndexVersion string `json:"index_version"`
	MatchedAlias string `json:"matched_alias,omitempty"`
	Entry        Entry  `json:"entry"`
}

QueryResponse is the versioned, machine-readable result of a lookup. Entry always exposes the canonical owner. MatchedAlias is populated only when an exact declared alias selected that owner and preserves the caller's spelling.

func Query

func Query(canonicalTerm string) (QueryResponse, error)

Query performs an exact, case-sensitive lookup of a canonical term. It stays canonical-only so callers that require canonical ownership cannot silently broaden their lookup to aliases.

func QueryScoped

func QueryScoped(canonicalTerm string, scope Scope) (QueryResponse, error)

QueryScoped performs an exact canonical lookup constrained by the required scope qualifier. The entry returns the stored scope unchanged.

func Resolve

func Resolve(term string) (QueryResponse, error)

Resolve performs an exact, case-sensitive lookup across canonical terms and declared aliases. The returned entry always carries the canonical identity; MatchedAlias records the exact alias used and is empty for canonical input.

func ResolveLadderSpelling

func ResolveLadderSpelling(kind LadderKind, spelling string) (QueryResponse, error)

func ResolveScoped

func ResolveScoped(term string, scope Scope) (QueryResponse, error)

ResolveScoped performs an exact canonical-or-alias lookup constrained by the required scope qualifier. The entry returns the stored scope unchanged.

type QuerySelfTestReport

type QuerySelfTestReport struct {
	Schema            string `json:"schema"`
	IndexVersion      string `json:"index_version"`
	CanonicalTerm     string `json:"canonical_term"`
	MatchedAlias      string `json:"matched_alias"`
	EntrySchema       string `json:"entry_schema"`
	Complete          bool   `json:"complete"`
	OverloadedTerm    string `json:"overloaded_term"`
	UnscopedAmbiguous bool   `json:"unscoped_ambiguous"`
	Scope             Scope  `json:"scope"`
}

QuerySelfTestReport is the machine-readable CLI witness for canonical and declared-alias query behavior.

func RunQuerySelfTest

func RunQuerySelfTest() (QuerySelfTestReport, error)

RunQuerySelfTest reads the public seed through both strict Query and Resolve. It proves alias resolution does not alter canonical ownership.

type ReasonSourceSelfTestReport

type ReasonSourceSelfTestReport struct {
	Schema                   string           `json:"schema"`
	IndexVersion             string           `json:"index_version"`
	Terms                    []VocabularyTerm `json:"terms"`
	IncompatibleRejected     bool             `json:"incompatible_duplicate_rejected"`
	CrossPackageAliasAllowed bool             `json:"cross_package_alias_allowed"`
}

ReasonSourceSelfTestReport captures both sides of the collision contract.

func RunReasonSourceSelfTest

func RunReasonSourceSelfTest() (ReasonSourceSelfTestReport, error)

RunReasonSourceSelfTest proves the public inventory is valid, an incompatible duplicate fails, and the declared COLLISION_RISK alias remains accepted.

type ReverseLocatorKind

type ReverseLocatorKind string

ReverseLocatorKind names a repository-visible handle carried by an Entry.

const (
	ReverseSourcePath ReverseLocatorKind = "source-path"
	ReverseGoSymbol   ReverseLocatorKind = "symbol"
	ReverseCLIToken   ReverseLocatorKind = "cli-token"
	ReverseReasonCode ReverseLocatorKind = "reason-code"
)

type ReverseLookupResponse

type ReverseLookupResponse struct {
	Schema       string             `json:"schema"`
	IndexVersion string             `json:"index_version"`
	Kind         ReverseLocatorKind `json:"kind"`
	Input        string             `json:"input"`
	Matches      []ReverseMatch     `json:"matches"`
}

ReverseLookupResponse returns every exact evidenced owner. Multiple matches remain visible because a source path or reason code may intentionally support several canonical distinctions.

func ReverseLookup

func ReverseLookup(kind ReverseLocatorKind, value string) (ReverseLookupResponse, error)

ReverseLookup finds canonical identities from a public source locator.

type ReverseMatch

type ReverseMatch struct {
	Kind         ReverseLocatorKind `json:"kind"`
	Input        string             `json:"input"`
	MatchedValue string             `json:"matched_value"`
	Entry        Entry              `json:"entry"`
}

ReverseMatch preserves why an entry matched instead of presenting an inferred canonical owner without evidence.

type ReverseSelfTestCase

type ReverseSelfTestCase struct {
	Kind          ReverseLocatorKind `json:"kind"`
	Input         string             `json:"input"`
	CanonicalTerm string             `json:"canonical_term"`
	MatchCount    int                `json:"match_count"`
}

ReverseSelfTestCase records one supported locator kind proved through the immutable public index.

type ReverseSelfTestReport

type ReverseSelfTestReport struct {
	Schema          string                `json:"schema"`
	IndexVersion    string                `json:"index_version"`
	Cases           []ReverseSelfTestCase `json:"cases"`
	UnknownRejected bool                  `json:"unknown_rejected"`
}

ReverseSelfTestReport is the captured public-seam witness for reverse lookup.

func RunReverseSelfTest

func RunReverseSelfTest() (ReverseSelfTestReport, error)

RunReverseSelfTest resolves every supported locator kind and proves unknown evidence does not produce a guessed identity.

type RuntimeSourceResolution

type RuntimeSourceResolution struct {
	Scope         Scope  `json:"scope"`
	Alias         string `json:"alias"`
	CanonicalTerm string `json:"canonical_term"`
	OwnerLeaf     string `json:"owner_leaf"`
	SourcePath    string `json:"source_path"`
}

RuntimeSourceResolution is one scoped owner of the intentionally overloaded canonical token "runtime".

type RuntimeSourceSelfTestReport

type RuntimeSourceSelfTestReport struct {
	Schema            string                    `json:"schema"`
	IndexVersion      string                    `json:"index_version"`
	UnscopedAmbiguous bool                      `json:"unscoped_ambiguous"`
	Choices           []RuntimeSourceResolution `json:"choices"`
}

RuntimeSourceSelfTestReport proves unscoped ambiguity and exact scoped lookup.

func RunRuntimeSourceSelfTest

func RunRuntimeSourceSelfTest() (RuntimeSourceSelfTestReport, error)

RunRuntimeSourceSelfTest asks the ambiguous question first, then resolves all five public runtime surfaces with the required scope qualifier.

type SchemaDescriptor

type SchemaDescriptor struct {
	Schema            string                      `json:"schema"`
	Compatibility     string                      `json:"compatibility"`
	UnknownFields     string                      `json:"unknown_fields"`
	TrailingValues    string                      `json:"trailing_values"`
	Aliases           string                      `json:"aliases"`
	Required          []string                    `json:"required"`
	FreshnessVerdicts []string                    `json:"freshness_verdicts"`
	FreshnessReasons  []FreshnessReasonDescriptor `json:"freshness_reasons"`
	LifecycleClasses  []string                    `json:"lifecycle_classes"`
	Rollouts          []string                    `json:"rollouts"`
}

SchemaDescriptor is the public, machine-readable summary of the pinned wire contract. Required uses JSON paths so callers can display or audit the contract without duplicating the Go validator.

func Descriptor

func Descriptor() SchemaDescriptor

Descriptor returns the deterministic v1 contract description.

type Scope

type Scope struct {
	Kind  string `json:"kind"`
	Value string `json:"value"`
}

Scope qualifies which public surface gives the canonical term this meaning. Kind names the dimension (for example product, package, cli, runtime, protocol, or operator); Value names the member within that dimension.

type SearchGroups

type SearchGroups struct {
	Exact  []SearchMatch `json:"exact"`
	Alias  []SearchMatch `json:"alias"`
	Prefix []SearchMatch `json:"prefix"`
}

SearchGroups are ordered by authority: exact canonical matches, exact alias matches, then canonical-or-alias prefix matches.

type SearchMatch

type SearchMatch struct {
	MatchedTerm string `json:"matched_term"`
	Entry       Entry  `json:"entry"`
}

SearchMatch preserves the token and namespace that led to a canonical entry.

type SearchResponse

type SearchResponse struct {
	Schema       string        `json:"schema"`
	IndexVersion string        `json:"index_version"`
	Query        string        `json:"query"`
	Verdict      SearchVerdict `json:"verdict"`
	Groups       SearchGroups  `json:"groups"`
}

SearchResponse returns every ranked candidate and an explicit resolution verdict. Ambiguous results never select an owner on the caller's behalf.

func Search

func Search(term string) SearchResponse

Search discovers exact canonical, exact alias, and prefix matches in the public terminology index.

type SearchVerdict

type SearchVerdict string

SearchVerdict tells callers whether search found one safe owner or requires them to choose explicitly from multiple candidates.

const (
	SearchVerdictExact     SearchVerdict = "exact"
	SearchVerdictAlias     SearchVerdict = "alias"
	SearchVerdictPrefix    SearchVerdict = "prefix"
	SearchVerdictAmbiguous SearchVerdict = "ambiguous"
	SearchVerdictNotFound  SearchVerdict = "not_found"
)

type SelfTestReport

type SelfTestReport struct {
	Schema            string                   `json:"schema"`
	CompleteAccepted  bool                     `json:"complete_accepted"`
	OmissionsRejected []string                 `json:"omissions_rejected"`
	Freshness         FreshnessSelfCheckReport `json:"freshness"`
}

SelfTestReport is the stable, machine-readable result of exercising the v1 contract without filesystem, network, or private-source dependencies.

func RunSelfTest

func RunSelfTest() (SelfTestReport, error)

RunSelfTest proves through the strict JSON reader that one complete record is accepted and every path declared required by Descriptor is rejected when omitted. Identity aliases is included: its array must be present on the wire, although [] is a valid value.

type SessionSourceResolution

type SessionSourceResolution struct {
	Input         string `json:"input"`
	CanonicalTerm string `json:"canonical_term"`
	SourcePath    string `json:"source_path"`
}

SessionSourceResolution proves one public term resolves to its intended canonical identity rather than a similarly named session mechanism.

type SessionSourceSelfTestReport

type SessionSourceSelfTestReport struct {
	Schema                         string                    `json:"schema"`
	IndexVersion                   string                    `json:"index_version"`
	Resolutions                    []SessionSourceResolution `json:"resolutions"`
	ResumeRecoveryConflation       bool                      `json:"resume_recovery_conflation_rejected"`
	CompactionCheckpointConflation bool                      `json:"compaction_checkpoint_conflation_rejected"`
}

SessionSourceSelfTestReport is the public fixture witness for #6314.

func RunSessionSourceSelfTest

func RunSessionSourceSelfTest() (SessionSourceSelfTestReport, error)

RunSessionSourceSelfTest resolves every session-family alias and verifies the two required forbidden distinctions are present in both directions.

type SourceWitness

type SourceWitness struct {
	Kind      string           `json:"kind"`
	Locator   string           `json:"locator"`
	Revision  string           `json:"revision"`
	CheckedAt string           `json:"checked_at"`
	Probe     string           `json:"probe"`
	Reference *PublicReference `json:"reference,omitempty"`
}

SourceWitness is strict public provenance for one supporting source. Locator is repository-relative; Revision, CheckedAt, and Probe make verification reproducible without introducing a private-source dependency.

type StaleSymbolsSelfCheckReport

type StaleSymbolsSelfCheckReport struct {
	Schema        string    `json:"schema"`
	Fresh         Freshness `json:"fresh"`
	Stale         Freshness `json:"stale"`
	PackagePassed bool      `json:"package_passed"`
	Passed        bool      `json:"passed"`
}

StaleSymbolsSelfCheckReport is the package/CLI JSON witness for public reference probing and the required fresh-to-stale transition.

func StaleSymbolsSelfCheck

func StaleSymbolsSelfCheck() StaleSymbolsSelfCheckReport

StaleSymbolsSelfCheck creates and removes a public fixture in an isolated directory. It is deterministic apart from the irrelevant temporary path, which is never emitted.

type TermClassification

type TermClassification struct {
	SchemaVersion  string `json:"schema_version"`
	Term           string `json:"term"`
	Classification string `json:"classification"`
	Reason         string `json:"reason"`
}

TermClassification is public classification data consumed by the same Index that serves canonical queries and terminology coverage. Incidental terms are deliberately not inserted into canonical or alias query maps.

func ValidateClassifications

func ValidateClassifications(items []TermClassification) ([]TermClassification, error)

ValidateClassifications validates and returns a deterministic copy. The contract is intentionally closed: unknown schema versions, classes, reasons, malformed local Go identifiers, and duplicate identities are rejected.

type ValidationError

type ValidationError struct {
	Code    string `json:"code"`
	Field   string `json:"field"`
	Message string `json:"message"`
}

ValidationError is the stable machine-readable provenance admission error. Code and Field are contract fields; Message is deterministic human context.

func (*ValidationError) Error

func (e *ValidationError) Error() string

type VocabularyKind

type VocabularyKind string

VocabularyKind names the semantic role of a public uppercase token.

const (
	VocabularyReason    VocabularyKind = "reason"
	VocabularyVerdict   VocabularyKind = "verdict"
	VocabularyGateClass VocabularyKind = "gate-class"
	VocabularyDecision  VocabularyKind = "decision-kind"
)

type VocabularyTerm

type VocabularyTerm struct {
	Code             string         `json:"code"`
	Kind             VocabularyKind `json:"kind"`
	Package          string         `json:"package"`
	Symbol           string         `json:"symbol"`
	CanonicalMeaning string         `json:"canonical_meaning"`
	SourcePath       string         `json:"source_path"`
}

VocabularyTerm is one public code declaration. CanonicalMeaning is the stable identity that allows intentional aliases across package boundaries.

func PublicReasonVocabulary

func PublicReasonVocabulary() []VocabularyTerm

PublicReasonVocabulary returns representative public declarations spanning policy/ABI, hooks, DOS, and runtime dispatch surfaces.