Module surface 

System Surface Map compiler (Wave 14, Level 1): the actual callable code surface built from the TrustedGraphView — an Aider RepoMap equivalent on System IR.

Every SYMBOL entity in the trusted view becomes a SurfaceEntry carrying exact signatures (source + canonical + semantic), visibility, modifiers/annotations, component attribution, and the architectural meaning attached to the symbol (flows, contracts, state ownership, invocation surfaces, callers/callees). Deterministic and no-panic: unparseable signatures degrade to name-only SemanticSignatures.

Structs

SurfacePipelineStages

Stage toggles for the ablation matrix (build_surface_staged): the same pipeline with one stage switched off. All on = build_surface.

SurfacePolicy

Pipeline policy knobs for one surface render.

SurfaceRequest

One surface render request: the mode, the token budget, whether to explain selection scores, the pipeline policy, and the optional semantic scorer.

Enums

SurfaceMode

The surface mode: global (the historical production pipeline) or task (task PPR + novelty suppression with the same pipeline tail).

Functions

build_surface

THE one authoritative surface pipeline: compile candidates → heterogeneous PPR (global or task) → [pagerank::SystemRanker::project_to_symbols] → per-entry importance (final_importance) → required coverage → MMR diversify → token-aware quotas → soft/hard budget selection → render. Global mode is the historical select_and_render_global pipeline; Task mode adds task PPR (lexical seeds, warm global start), novelty suppression against the ledger, and the same MMR/quotas/selector/render tail. Every surface consumer (production, CLI, MCP, plugin, benchmark ablations) routes through this service — no consumer reimplements ranking. Deterministic and no-panic.

build_surface_cached

15.2-cache-seam: cache-aware sibling of build_surface (Wave 15.2, REQ-global-rank-cached-per-model-epoch). When cache holds a valid crate::startup::GlobalRankCache (loaded by crate::startup::load_global_rank_cache), the global PPR vector + symbol projection come from the cache — skipping SystemRanker::new (the heterogeneous node graph + adjacency + rarity build) and the 50 power iterations of global_vector(). The pipeline tail (required coverage, MMR, quotas, budget selection, render) runs identically, so the output is byte-identical to build_surface. On a miss (cache is None) the ranker is built once and the cache is FILLED (the caller persists it via crate::startup::store_global_rank_cache). Additive: B’s semantic field lands on SurfaceRequest/build_surface independently.

build_surface_staged

build_surface with stage toggles for the ablation matrix (benchmark ablations toggle stages here — they never reimplement ranking). lexical off skips PPR entirely and scores by lexical match; global_ppr off drops the global vector; task_ppr off seeds no task vector; mmr off skips diversification; quotas off skips per-kind caps; optimizer off renders in importance order up to the budget. Deterministic and no-panic.

compile_surface_map

Build the System Surface Map (Level 1) from the trusted view.

entry_lexical

Lexical relevance of an entry to the goal terms: name hits count double, signature hits count single (shared with the task-delta pipeline). Lexical relevance of an entry to the goal terms (engine ranking seam).

important_symbols

Top-N important symbols (audit item 3): the ranked map’s entries sorted by the mode’s score (task_ppr for Task, global-weighted total for Global), each carrying its derived scc_core::ImportanceProfile. READ-ONLY ranking view: no rescoring, no budget, no render — callers (startup sections, scc important) decide presentation. limit caps the returned entries (0 = all).

render_important

Render the IMPORTANT SYMBOLS section (audit item 3): numbered entries with badges, exact fan-in/fan-out, flow/contract counts, and the overall score — the fast “where do I pay attention first” answer before the long Surface Map detail.

render_surface_map

Deterministic, budget-capped render of a SystemSurfaceMap.

required_ids

Entries the pipeline MUST never omit: critical invocation surfaces (non-empty invocation_surfaces), invariant-enforcing APIs (contracts containing an invariant name), primary flow entrypoints (entrypoint of a triggered flow), and state owners of critical (invariant-scoped) state. Entries the pipeline MUST never omit (engine ranking seam: same set build_surface partitions on, so ranking.symbols criticality matches).

select_and_render_global

The FULL production global surface pipeline (historical entry point — kept as a thin wrapper over build_surface so the traced contract and legacy callers stay stable): global heterogeneous PPR, required coverage, MMR, quotas, budget selection, render.

select_and_render_task

The FULL production task surface pipeline (historical entry point — kept as a thin wrapper over build_surface so the traced contract and legacy callers stay stable): task PPR + novelty suppression against the ledger + the same MMR/quotas/selector/render tail.

surface_quotas

The spec’s global surface budget quotas (keys consumed by selector::enforce_quotas): 30% public/entrypoint, 25% core impl, 15% types/interfaces, 10% state owners, 10% contract APIs, 10% flow-critical.