Crate scc_core 

System IR core types.

These types mirror docs/system-ir.schema.json exactly so that a SystemIr document serializes to the documented export format without translation.

Re-exports

pub use handles::fnv1a64_hex;

pub use handles::ContentHandle;

pub use handles::HandleError;

pub use handles::HandleKind;

pub use languages::extracted_language_ids;

pub use languages::language_by_id;

pub use languages::language_registry;

pub use languages::support_matrix_markdown;

pub use languages::LanguageCapability;

pub use languages::LanguageTier;

pub use languages::LANGUAGE_REGISTRY;

pub use lex::bm25_rank;

pub use lex::bm25_scores;

pub use lex::bm25_scores_with_stats;

pub use lex::classify_query;

pub use lex::extract_query_mentions;

pub use lex::is_exact_anchor;

pub use lex::mention_matches_doc;

pub use lex::path_matches_locus;

pub use lex::ranking_arm_ids;

pub use lex::relevance_hits;

pub use lex::relevance_hits_with_stats;

pub use lex::route_query;

pub use lex::subtokens;

pub use lex::Bm25CorpusStats;

pub use lex::LexDoc;

pub use lex::LexField;

pub use lex::QueryLocus;

pub use lex::QueryMention;

pub use lex::QueryShape;

pub use lex::RankingArm;

pub use lex::RelevanceHit;

pub use lex::RetrievalPlan;

pub use lex::BM25_B;

pub use lex::BM25_K1;

pub use lex::QUERY_MENTION_MAX_RAW;

pub use lex::WEIGHT_BODY;

pub use lex::WEIGHT_DOC;

pub use lex::WEIGHT_NAME;

pub use lex::WEIGHT_PATH;

pub use resolution::choose_representation;

pub use resolution::AnalysisQuality;

pub use resolution::CallQuality;

pub use resolution::FileQuality;

pub use resolution::RecvKind;

pub use resolution::RepresentationChoice;

pub use resolution::RepresentationKind;

pub use resolution::ResolutionClass;

pub use retrieval::mean_reciprocal_rank;

pub use retrieval::recall_at_k;

Modules

handles

Stable content handles for lazy exact-source retrieval.

identity

Stable repository identity (mission §XIV).

kinds

languages

Authoritative language-support registry.

lex

Relevance-first lexical machinery: subtoken tokenizer, BM25, query shape.

predicates

resolution

Receiver classification, resolution honesty, and representation choice.

retrieval

Retrieval metrics for ranking-arm ablations.

Structs

AtlasComponent

One architectural component in the atlas. Purpose is the highest-ranked responsibility claim; consumes/produces come from data-flow edges; upstream/downstream from dependency edges; retry/failure from extracted failure behavior.

AtlasEntrypoint

AtlasFlow

A condensed flow: steps collapsed to “Actor: operation” lines, with branch/async/failure markers preserved.

AtlasHierarchyNode

One hierarchical container (service or subsystem) with its direct member entity ids (component ids, or subsystem ids nested inside a service). Deterministic: members sorted by entity id.

AtlasInvariant

AtlasOwnershipClaim

A typed ownership claim (provenance preserved — DECLARED intent never promoted).

ContextArtifact

The deterministic startup artifact (Atlas + Surface), hash-stable per epoch so prompt caches hit.

ContextBudget

The startup/task context budget split (Wave 14 dynamic budgets).

ContextItem

A token-optimized context candidate (Aider-style hard budget search).

ContextLedger

What the agent has already seen — novelty suppression source (the general form of Aider treating chat files specially).

Contract

One first-class contract in the atlas (Wave 9): a typed, evidence-backed contract surface (http/cli/event/config/annotation) with its producer symbol and the symbols that consume it. operations carries the concrete contract strings (route GET /api/x, flag --paging, event user.created, config key DEBUG, annotation router.get).

Entity

Evidence

Flow

FlowEdge

FlowGraph

The canonical causal representation of one flow: a graph, never a flattened linear step list. Alternate execution paths are preserved as branch edges; false sequential causality is impossible by construction.

FlowNode

One operation node in the canonical flow graph. The canonical graph retains individual operations — component-level grouping (ComponentSpan) happens only at display/context time.

FlowStep

ImportanceProfile

A definition deliberately omitted by a token-budget cut — the artifact never silently implies completeness. Derived importance explanation for one surface symbol (audit item 3): topology (exact fan-in/fan-out, never truncated), architecture signals, and change impact — computed from data the pipeline ALREADY has. Badges are derived labels over those numbers, not extra scoring magic: the overall score stays rank.total.

Invariant

InvocationSurface

One invocation surface: a symbol reachable from outside the process.

Occurrence

One concrete occurrence of a concept (schema/reactive) in a source file.

RankNode

One node in the heterogeneous ranking universe (Wave 14B): any rankable entity — symbol, component, subsystem, service, flow, contract, state, reactive, route, topic, queue, store, schema, or file. The ranker walks edges whose endpoints are rankable entities, so architectural importance (flows, contracts, state) participates in PageRank directly.

ReferenceEdge

A normalized reference between two symbols (Wave 14): the graph the ranker walks. Many SCC relationships already express these concepts; this layer normalizes them for ranking.

Relationship

Repository

SemanticParameter

One function/method parameter in structured form.

SemanticSignature

The structured machine form of a signature — the semantic layer over the exact source text. Benchmark matching uses this, never string comparisons of source signatures alone.

Snapshot

SourceRange

A source range: file path + 1-based inclusive line span.

StructuralSourceUnit

One structural-source unit: semantic skeleton of an implementation slice (Level 2), with provenance back to the exact source.

SurfaceEntry

One ranked definition on the system surface — a callable/typeable reality of the architecture, with exact signatures and architectural meaning attached.

SurfaceOmission

SurfaceRank

Why a surface entry earned its rank (explainability; scc surface --explain renders this).

SurfaceRenderResult

The production surface render: the budget-selected subset plus honest omission accounting (Wave 14F). rendered_ids are exactly the entries the agent sees (ledger recording MUST use only these — omitted candidates are never marked visible); omitted_ids are every candidate the pipeline cut. omissions summarizes the cuts by kind.

SystemAtlas

The full System Atlas: structured architecture before rendering. This is the machine model handed to agents at session start (docs/SYSTEM_DESIGN.md §8, Wave 2).

SystemIr

SystemSurfaceMap

The System Surface Map: the ranked actual-API layer of a repository, built from System IR (Level 1 of the context stack).

TaskSeed

One task-seed resolution: task language -> SCC entities.

Enums

Archetype

Repository archetype, detected deterministically from graph evidence (routes, exports, cli/framework signals, deployment/workspace shape) by scc_graph::archetype::detect_archetype. Unknown is the honest fallback when no signal fires.

ContractSubclass

First-class contract subclass (Contract ontology): the semantic contract family, derived by the extractors from general evidence (public fn signatures, builder/factory structure, event producer/consumer pairs, serializer/deserializer pairs, interface+implementations, route/flag/ topic/config facts) and rendered by the atlas as per-subclass groups. The legacy kind string stays for back-compat; subclass is the typed family (http/cli/event/config/public-api/extension/ serialization/…).

EvidenceType

Evidence source type.

FlowEdgeKind

Edge kind in the canonical causal graph (P1, docs/SYSTEM_DESIGN.md §9).

FlowKind

Flow view kinds (System Atlas), per docs/SYSTEM_IR_SCHEMA.md §7.

InvocationSurfaceKind

How a symbol can be invoked from outside the process (Wave 9): the invocation surfaces the flow compiler seeds entrypoints from.

Provenance

Evidence class of a fact, per docs/SYSTEM_IR_SCHEMA.md §5.

ReferenceKind

Severity

SurfaceKind

The kind of code surface a definition exposes.

Visibility

Symbol visibility as declared in source.

Constants

SCHEMA_VERSION

Functions

decode_component

Inverse of encode_component: percent-decodes %XX sequences back to bytes. Used by benchmark/impact tooling to map entity ids back to names.

encode_component

Percent-encode a path/name component for use inside an entity id while preserving case and common separators (/, ., _, -). Collision-free where sanitize_key would risk merging distinct names.

entity_id

repo://{repo}/{kind}/{key} stable identifier.

estimate_tokens

Rough token estimate: 4 characters per token (byte-based for ASCII, but we operate on char count which is a close approximation across scripts).

evidence_id

Evidence id namespace: evidence:{n} — stable within a snapshot, assigned by the store.

flow_kind_str

now_rfc3339

occurrence_id

Occurrence entity id: collision-free per (concept key, path, owner, line) — the identity occurrences carry so shared concepts never lose per-file provenance. Unlike entity_id, the concept/path/owner components are percent-encoded (@-separated), so case and separator distinctions (a_b vs a-b) never merge distinct occurrences.

ontology_registries

Authoritative kind and predicate ids. Rankers, exporters, and tests must derive from these slices rather than a second hand-maintained list.

relationship_id

Relationship id: rel:{n} — stable within a snapshot, assigned by store.

sanitize_key

Sanitize a free-form name into a stable URI key.

symbol_id

Stable symbol id: repo://{repo}/symbol/{encoded-file}/{encoded-name}.

truncate_to_budget

Hard-truncate text to at most budget tokens, preferring a clean cut at a line boundary.