scc_context/
startup.rs

1//! Startup context (Wave 14C): the deterministic Atlas + Surface fusion
2//! handed to agents at session start, plus the task delta (Wave 14E) that
3//! renders only *new* relevant APIs against the context ledger.
4//!
5//! Prompt-cache stability: the artifact hash is a pure function of
6//! `(epoch, renderer_version, trust_policy, budget)` — no timestamps — so
7//! the same epoch + config always yields byte-identical startup text.
8
9use crate::surface::{build_surface, build_surface_cached, SurfaceMode, SurfacePolicy, SurfaceRequest};
10use crate::ContextCompiler;
11use scc_core::kinds;
12use scc_core::{estimate_tokens, ContextArtifact, ContextBudget, ContextLedger};
13use serde::{Deserialize, Serialize};
14use std::collections::{BTreeMap, BTreeSet};
15
16/// Renderer version: part of the artifact hash. Bump when the startup
17/// renderer's output format changes (invalidates prompt-cache keys).
18pub const RENDERER_VERSION: &str = env!("CARGO_PKG_VERSION");
19
20/// The startup artifact: atlas + surface + coverage + omissions, with the
21/// deterministic artifact hash. `surface_render` is the SAME render the
22/// artifact printed — ledger recording derives visible ids from it, so
23/// the surface is never computed twice per startup.
24// trace:exempt reason=internal-detail
25pub struct StartupContext {
26    pub atlas: String,
27    /// Atlas budget the DELIVERED atlas text was rendered under (normally
28    /// the loop's final `atlas_budget`, or the 256-token essentials budget
29    /// on the emergency floor). The ledger rebuilds the same pack, so
30    /// recorded atlas ids never describe undelivered text (§53 coupling).
31    pub atlas_budget_used: usize,
32    /// Deterministic physical-layout evidence (repository skeleton),
33    /// built from the indexed file inventory under its own hard budget.
34    pub skeleton: String,
35    pub surface: String,
36    /// IMPORTANT SYMBOLS section (audit item 3): the fast "where do I pay
37    /// attention first" answer, rendered before the long Surface Map
38    /// detail. Computed from the same global rank the surface used.
39    pub important: String,
40    pub surface_render: scc_core::SurfaceRenderResult,
41    pub coverage: Vec<String>,
42    pub omissions: Vec<String>,
43    pub artifact: ContextArtifact,
44}
45/// Global-rank cache (Wave 15.2, per-ModelEpoch rank caching): the
46/// expensive, epoch-stable parts of a global Surface build —
47/// `SystemRanker::new` (heterogeneous node graph + adjacency + rarity),
48/// the 50-iteration global PageRank vector, and the projection to symbol
49/// scores — serialized to the store cache so consecutive startups in the
50/// same model epoch skip the rank build entirely.
51///
52/// Scope evidence (Part F profiling, cli-service fixture, budget 7000):
53/// cold rebuild 44-242µs vs 25µs cache hit — the rebuild is sub-millisecond
54/// at fixture scale, so the seam stays STARTUP-ONLY; plain `scc surface` /
55/// MCP `surface_map` keep the uncached `build_surface` (identical output,
56/// measured cost negligible). Re-measure before extending the seam to
57/// larger corpora. Key:
58/// `rank:global:<blake3(epoch, policy, salt)[..20]>` (mirrors the
59/// `system_atlas` pack-cache pattern in `ContextCompiler::system_atlas`).
60#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
61// trace:exempt reason=internal-detail
62pub struct GlobalRankCache {
63    /// The composite cache epoch the entry was computed under.
64    pub epoch: String,
65    /// The TrustPolicy fingerprint (`trust_policy_str`) the rank used.
66    pub policy: String,
67    /// The active rank salt (`ContextSettings::rank_salt`).
68    pub salt: String,
69    /// The heterogeneous global PageRank vector (index i == `nodes()[i]`).
70    /// Retained so a future task-PPR path can warm-start from it.
71    pub global_vector: Vec<f64>,
72    /// Symbol id -> projected global score (`project_to_symbols` output) —
73    /// exactly what the surface pipeline consumes as `global_of`.
74    pub node_symbol_map: BTreeMap<String, f64>,
75    /// The epoch the candidate entry list came from (epoch-stability
76    /// marker; the cache key already pins the epoch).
77    pub candidates_epoch: String,
78    /// Epoch-stable candidate entry ids (cheap accounting — avoids a
79    /// `compile_surface_map` walk for the surface accounting line).
80    #[serde(default, skip_serializing_if = "Vec::is_empty")]
81    pub candidate_ids: Vec<String>,
82    /// How many times this entry has been reused (deterministic
83    /// cache-hit marker for tests).
84    #[serde(default)]
85    pub hits: u64,
86}
87
88/// THE one startup-budget allocator (transport parity): every transport
89/// that builds a startup artifact — CLI `context startup`, MCP
90/// `system_context`, HTTP, Hermes, the SDKs, the Claude SessionStart /
91/// PreCompact hooks, and the benchmark harness — resolves its budget
92/// through this function and never derives an Atlas:Surface split itself.
93///
94/// `target_tokens == None` does NOT bypass adaptation: it selects the
95/// configured startup ceiling (`compiler.settings.startup_tokens`), which
96/// then goes through the SAME adaptive complexity split. An explicit target
97/// scales the total; repo complexity decides the split — in both cases via
98/// [`scc_core::ContextBudget::adaptive`]. Deterministic per (target,
99/// view): same inputs, same budget.
100// trace:v1 id=impl.scc.startup.allocate-budget work=WORK-wave-15-2-heterogeneous-hierarchy-edges-semantic-scoring-explain-rank-caching satisfies=REQ-adaptive-startup-budgets
101pub fn allocate_startup_budget(
102    compiler: &ContextCompiler,
103    target_tokens: Option<usize>,
104) -> ContextBudget {
105    let total = target_tokens.unwrap_or(compiler.settings.startup_tokens);
106    let view = &compiler.view;
107    let entity_count = view.entities().count();
108    let component_count = view.components().len();
109    let flow_count = view.flows().len();
110    let surface_candidates = view.entities_of_kind(scc_core::kinds::SYMBOL).len();
111    scc_core::ContextBudget::adaptive(total, entity_count, component_count, flow_count, surface_candidates)
112}
113
114// trace:v1 id=impl.crates-scc-context-src-startup.coverage-lines work=WORK-wave-15-2-heterogeneous-hierarchy-edges-semantic-scoring-explain-rank-caching satisfies=REQ-hard-max-invariant-on-rendered-text
115fn coverage_lines(
116    compiler: &ContextCompiler,
117    render_ids: usize,
118    candidates: usize,
119    render_tokens: usize,
120    surface_budget: usize,
121) -> Vec<String> {
122    let mut coverage = Vec::new();
123    for w in compiler_warnings(compiler) {
124        coverage.push(w);
125    }
126    let mut stale: Vec<String> = compiler.stale_paths.clone();
127    stale.sort();
128    stale.dedup();
129    // Bounded: per-path lines aid small repos; a 10k-stale repo reports
130    // counts, never 10k lines (the emergency floor omits paths entirely).
131    const MAX_STALE_LINES: usize = 10;
132    for p in stale.iter().take(MAX_STALE_LINES) {
133        coverage.push(format!("stale: {p}"));
134    }
135    if stale.len() > MAX_STALE_LINES {
136        coverage.push(format!(
137            "stale: …and {} more changed file(s) not yet re-indexed",
138            stale.len() - MAX_STALE_LINES
139        ));
140    }
141    coverage.push(format!(
142        "surface map: {} of {} entries rendered, {} tokens (budget {})",
143        render_ids,
144        candidates,
145        render_tokens,
146        surface_budget
147    ));
148    coverage
149}
150
151// OMISSIONS helper (module-level so its trace marker attaches): the render
152// result's per-kind cuts + omitted-id count + the
153// atlas's dropped sections (honest: omitted ids are never silent).
154// trace:v1 id=impl.crates-scc-context-src-startup.omission-lines
155fn omission_lines(
156    render_omissions: &[scc_core::SurfaceOmission],
157    omitted_len: usize,
158    atlas_dropped: &[String],
159    atlas_hard_truncated: bool,
160    atlas_exceeded: bool,
161) -> Vec<String> {
162    let mut omissions = Vec::new();
163    for o in render_omissions {
164        omissions.push(format!("surface: {} ({})", o.kind, o.reason));
165    }
166    if omitted_len > 0 {
167        omissions.push(format!(
168            "surface: {} lower-ranked definitions omitted",
169            omitted_len
170        ));
171    }
172    for d in atlas_dropped {
173        omissions.push(format!("atlas section dropped: {d}"));
174    }
175    if atlas_hard_truncated {
176        omissions.push("atlas hard-truncated mid-section".into());
177    }
178    if atlas_exceeded {
179        omissions.push("atlas exceeded soft budget: kept complete, over budget".into());
180    }
181    if omissions.is_empty() {
182        omissions.push("none".into());
183    }
184    omissions
185}
186
187/// Build the deterministic startup artifact: the existing System Atlas
188/// content (capped at `budget.atlas`) fused with the budget-selected
189/// System Surface Map (the production `select_and_render_global` pipeline),
190/// coverage warnings, and honest omissions. The surface's omitted ids
191/// populate the OMISSIONS section; the ledger records ONLY rendered ids.
192// trace:v1 id=impl.scc.context.startup work=WORK-SCC-014 satisfies=REQ-SCC-IR
193pub fn build_startup(
194    compiler: &ContextCompiler,
195    budget: &ContextBudget,
196    renderer_version: &str,
197) -> StartupContext {
198    let epoch = compiler
199        .store
200        .cache_epoch()
201        .unwrap_or_else(|_| "no-epoch".into());
202
203    // Atlas: reuse the existing cached-atlas pipeline (system_atlas is
204    // cache-keyed by epoch + stale set; a stale atlas is never served).
205    let atlas_pack = compiler.system_atlas(Some(budget.atlas));
206    let atlas = atlas_pack.content.clone();
207
208    // Repository Skeleton: physical-layout evidence from the indexed file
209    // inventory, under its own hard budget. Pre-bounded (never rebalanced
210    // by the corrective loop below), deterministic per epoch, and counted
211    // in every fused hard-max probe.
212    let paths: Vec<String> = compiler
213        .store
214        .all_files()
215        .unwrap_or_default()
216        .into_iter()
217        .map(|(p, _, _, _, _)| p)
218        .collect();
219    let mut skeleton =
220        crate::skeleton::build_skeleton(&paths, crate::skeleton::skeleton_budget(budget.total)).text;
221
222    // Surface: the FULL production pipeline — the one authoritative
223    // [`build_surface`] service in Global mode (heterogeneous global PPR,
224    // required coverage, MMR diversity, token-aware quotas, soft/hard
225    // budget selection, render) — built EXACTLY ONCE per startup. The
226    // per-ModelEpoch global-rank cache supplies the PPR vector + symbol
227    // projection on hit (skipping SystemRanker::new + the 50 power
228    // iterations); on miss the render fills the cache, persisted below.
229    let mut rank_cache = load_global_rank_cache(compiler);
230    let cache_hit = rank_cache.is_some();
231    let render = build_surface_cached(
232        compiler,
233        SurfaceRequest {
234            mode: SurfaceMode::Global,
235            budget: budget.surface,
236            explain: false,
237            policy: SurfacePolicy::defaults(budget.surface),
238            semantic: None,
239        },
240        &mut rank_cache,
241    );
242    // Startup hard-max semantics (Part E): `budget.total` is the SOFT
243    // target; the hard maximum is target + 20% (min +500). Atlas and
244    // Surface may borrow from each other within it: if the FUSED body
245    // (atlas + coverage + omissions + surface) exceeds the hard max, the
246    // surface slice is re-selected against whatever room the atlas's
247    // ACTUAL size left — never by silently cutting the artifact.
248    let startup_hard_max = budget.total.saturating_add((budget.total / 5).max(500));
249
250    let mut render = render;
251    let mut atlas_pack = atlas_pack;
252    let mut atlas = atlas;
253    let mut atlas_budget = budget.atlas;
254    // MODEL COVERAGE: compiler warnings + stale paths + a surface accounting
255    // line, derived from the render itself (rendered ∪ omitted == every
256    // candidate) — never a second compile_surface_map walk. Recomputed
257    // after any hard-max rebalance below.
258    let mut coverage = coverage_lines(
259        compiler,
260        render.rendered_ids.len(),
261        render.rendered_ids.len() + render.omitted_ids.len(),
262        render.token_count,
263        budget.surface,
264    );
265
266    // Startup hard-max CORRECTIVE LOOP (Part 4): the invariant is on the
267    // FINAL assembled text — `estimate_tokens(assemble_body(atlas, surface,
268    // coverage, omissions)) <= startup_hard_max`. Headers, coverage lines,
269    // omission text, and the atlas's actual size can each push the fused
270    // body past the room estimated pre-assembly, so the ONE-SHOT rebalance
271    // is not sufficient. This loop reassembles and recounts after every
272    // change; first it shrinks the Surface (re-selected with hard_max = the
273    // room the current atlas/coverage/omissions actually leave), then, when
274    // the Surface is at its floor (no room left), it shrinks the Atlas
275    // budget in 25% steps — dropping lower-priority sections that are
276    // RECORDED via atlas_pack.dropped_sections and surfaced in OMISSIONS.
277    // Deterministic convergence, not a fixed round cap: each round either
278    // shrinks the Surface (re-selected with hard_max = the room the current
279    // atlas/coverage/omissions actually leave) or, once the surface is at
280    // its 64-token floor, shrinks the Atlas budget by 25% (dropping
281    // lower-priority sections that are RECORDED via dropped_sections and
282    // surfaced in OMISSIONS). Both steps are monotone, so the loop
283    // terminates at the natural floor in a bounded number of rounds (well
284    // under the 64-round safety net). The fit check counts the FULL
285    // assembled block (the "# SCC SYSTEM CONTEXT" header + artifact comment
286    // are part of the final text), so the invariant holds on artifact.text.
287    const BLOCK_HEADER_OVERHEAD: usize = 40; // header + metadata comment, chars/4
288    let mut iterations = 0;
289    loop {
290        let omissions_probe = omission_lines(
291            &render.omissions,
292            render.omitted_ids.len(),
293            &atlas_pack.dropped_sections,
294            atlas_pack.hard_truncated,
295            atlas_pack.exceeded_soft_budget,
296        );
297        let fused = assemble_body(&atlas, &skeleton, &render.text, "", &coverage, &omissions_probe);
298        if BLOCK_HEADER_OVERHEAD + estimate_tokens(&fused) <= startup_hard_max {
299            break;
300        }
301        iterations += 1;
302        if iterations > 64 {
303            // Safety net: the natural floors (surface < 64 tokens + atlas
304            // floor) always terminate well before this; if both floors are
305            // exhausted and the artifact STILL exceeds the hard max, the
306            // final assert below documents the pathological residual rather
307            // than looping forever.
308            break;
309        }
310        let overhead = estimate_tokens(&assemble_body(&atlas, &skeleton, "", "", &coverage, &omissions_probe));
311        let room = startup_hard_max.saturating_sub(overhead);
312        if room >= 64 {
313            // Surface still has room: shrink it to the room the current
314            // atlas + coverage + omissions ACTUALLY leave (headers included).
315            let policy = SurfacePolicy {
316                quotas: true,
317                mmr: true,
318                coverage: true,
319                hard_max: room,
320            };
321            render = build_surface_cached(
322                compiler,
323                SurfaceRequest {
324                    mode: SurfaceMode::Global,
325                    budget: room,
326                    explain: false,
327                    policy,
328                    semantic: None,
329                },
330                &mut rank_cache,
331            );
332            coverage = coverage_lines(
333                compiler,
334                render.rendered_ids.len(),
335                render.rendered_ids.len() + render.omitted_ids.len(),
336                render.token_count,
337                room,
338            );
339        } else {
340            // Surface at its floor: shrink the Atlas in 25% steps.
341            let smaller = atlas_budget.saturating_mul(3) / 4;
342            if smaller == atlas_budget {
343                break; // atlas floor reached — nothing more to give.
344            }
345            atlas_budget = smaller;
346            atlas_pack = compiler.system_atlas(Some(atlas_budget));
347            atlas = atlas_pack.content.clone();
348        }
349    }
350
351    // Best-effort persistence AFTER the corrective loop (the final surface
352    // render also feeds the cache): a cache failure never fails startup.
353    // The hit counter is the deterministic "reused on run 2" marker.
354    if let Some(c) = &mut rank_cache {
355        if cache_hit {
356            c.hits += 1;
357        }
358        store_global_rank_cache(compiler, c);
359    }
360    let mut surface = render.text.clone();
361    let mut atlas_budget_used = atlas_budget;
362
363    // Emergency floor (Part 4): the corrective loop guarantees fit
364    // whenever the Surface/Atlas floors leave room. When even the floors
365    // overflow (a tiny budget on a large repository), degrade
366    // structurally instead of escaping the cap: atlas essentials at a
367    // fixed 256-token budget, surface omitted (ledger ids cleared so §53
368    // coupling holds), skeleton shrunk until the fused receipt fits. The
369    // delivered text ALWAYS satisfies the hard max — there is no overflow
370    // escape hatch. `atlas_budget_used` tracks the delivered atlas so the
371    // ledger rebuilds the same pack it describes.
372    let emergency_omissions: Option<Vec<String>>;
373    {
374        let omissions_probe0 = omission_lines(
375            &render.omissions,
376            render.omitted_ids.len(),
377            &atlas_pack.dropped_sections,
378            atlas_pack.hard_truncated,
379            atlas_pack.exceeded_soft_budget,
380        );
381        if BLOCK_HEADER_OVERHEAD
382            + estimate_tokens(&assemble_body(
383                &atlas,
384                &skeleton,
385                &surface,
386                "",
387                &coverage,
388                &omissions_probe0,
389            ))
390            <= startup_hard_max
391        {
392            emergency_omissions = None;
393        } else {
394
395        atlas_budget_used = 256;
396        atlas_pack = compiler.system_atlas(Some(atlas_budget_used));
397        atlas = atlas_pack.content.clone();
398        render.rendered_ids.clear();
399        render.omitted_ids.clear();
400        render.omissions.clear();
401        render.text = String::new();
402        render.token_count = 0;
403        surface = String::new();
404        // Minimal emergency coverage: warnings + counts, never per-path
405        // lines (a 10k-stale repo must still fit a tiny budget).
406        coverage = compiler_warnings(compiler);
407        if compiler.stale_paths.is_empty() {
408            coverage.push("model: current".into());
409        } else {
410            coverage.push(format!(
411                "model stale: {} changed file(s) not yet re-indexed (paths omitted over hard max)",
412                compiler.stale_paths.len()
413            ));
414        }
415        coverage.push("surface map: omitted over hard max (0 rendered)".into());
416        let mut skel_budget = crate::skeleton::skeleton_budget(budget.total);
417        loop {
418            let probe = crate::skeleton::build_skeleton(&paths, skel_budget);
419            let omissions_probe = {
420            let mut o = omission_lines(
421                &[],
422                0,
423                &atlas_pack.dropped_sections,
424                atlas_pack.hard_truncated,
425                atlas_pack.exceeded_soft_budget,
426            );
427            o.push(
428                "startup emergency compression: atlas essentials + skeleton only (surface omitted over hard max)".into(),
429            );
430            o };
431            let fused = assemble_body(&atlas, &probe.text, "", "", &coverage, &omissions_probe);
432            if BLOCK_HEADER_OVERHEAD + estimate_tokens(&fused) <= startup_hard_max
433                || skel_budget == 0
434            {
435                skeleton = probe.text;
436                emergency_omissions = Some(omissions_probe);
437                break;
438            }
439            skel_budget /= 2;
440        }
441    }
442    }
443
444    // IMPORTANT FUNDED (audit item 3): the section joins the fused body,
445    // so it must fit the hard max like every other section. If the
446    // post-loop important text pushes the fused artifact over hard_max,
447    // shrink the surface once more by exactly that overrun and recompute
448    // the section from the new render (monotone: at most one extra pass).
449    // Section budget: ~8% of the hard max at ~40 tokens/symbol,
450    // floored to 1 symbol and capped at 15. Tiny totals list fewer
451    // symbols instead of either blowing the hard max or flooring to
452    // nothing. Receipt: 15 symbols render ~550 tokens; a 1024-total
453    // startup (hard max ~1500) funds ~120 section tokens ≈ 3 symbols.
454    let important_n = (startup_hard_max / 500).clamp(1, 15);
455    let mut important = if render.rendered_ids.is_empty() {
456        "## SYSTEM-CRITICAL SYMBOLS\n(surface omitted over hard max)\n".to_string()
457    } else {
458        let top = crate::surface::important_symbols(
459            compiler,
460            crate::surface::SurfaceMode::Global,
461            important_n,
462        );
463        crate::surface::render_important(&top, false)
464    };
465    {
466        let probe_om = omission_lines(
467            &render.omissions,
468            render.omitted_ids.len(),
469            &atlas_pack.dropped_sections,
470            atlas_pack.hard_truncated,
471            atlas_pack.exceeded_soft_budget,
472        );
473        let fused = assemble_body(&atlas, &skeleton, &render.text, &important, &coverage, &probe_om);
474        if BLOCK_HEADER_OVERHEAD + estimate_tokens(&fused) > startup_hard_max && !render.rendered_ids.is_empty() {
475            let over = BLOCK_HEADER_OVERHEAD + estimate_tokens(&fused) - startup_hard_max;
476            let room = render
477                .token_count
478                .saturating_sub(over)
479                .saturating_sub(estimate_tokens(&important));
480            if room >= 64 {
481                let policy = SurfacePolicy {
482                    quotas: true,
483                    mmr: true,
484                    coverage: true,
485                    hard_max: room,
486                };
487                render = build_surface_cached(
488                    compiler,
489                    SurfaceRequest {
490                        mode: SurfaceMode::Global,
491                        budget: room,
492                        explain: false,
493                        policy,
494                        semantic: None,
495                    },
496                    &mut rank_cache,
497                );
498                coverage = coverage_lines(
499                    compiler,
500                    render.rendered_ids.len(),
501                    render.rendered_ids.len() + render.omitted_ids.len(),
502                    render.token_count,
503                    room,
504                );
505                important = if render.rendered_ids.is_empty() {
506                    "## SYSTEM-CRITICAL SYMBOLS\n(surface omitted over hard max)\n".to_string()
507                } else {
508                    let top = crate::surface::important_symbols(
509                        compiler,
510                        crate::surface::SurfaceMode::Global,
511                        important_n,
512                    );
513                    crate::surface::render_important(&top, false)
514                };
515                // Final probe: the recomputed section + smaller surface
516                // may still exceed (tiny total, huge repo) — floor it.
517                let probe_om2 = omission_lines(
518                    &render.omissions,
519                    render.omitted_ids.len(),
520                    &atlas_pack.dropped_sections,
521                    atlas_pack.hard_truncated,
522                    atlas_pack.exceeded_soft_budget,
523                );
524                let fused2 = assemble_body(&atlas, &skeleton, &render.text, &important, &coverage, &probe_om2);
525                if BLOCK_HEADER_OVERHEAD + estimate_tokens(&fused2) > startup_hard_max {
526                    important = "## SYSTEM-CRITICAL SYMBOLS\n(omitted over hard max)\n".to_string();
527                }
528            }
529        } else {
530            // No room to fund the section: floor it to one line.
531            important = "## SYSTEM-CRITICAL SYMBOLS\n(omitted over hard max)\n".to_string();
532        }
533    }
534
535    // OMISSIONS (final render — after the corrective loop): the render
536    // result's per-kind cuts + omitted-id count + the atlas's dropped
537    // sections (honest: omitted ids are never silent).
538    let omissions = emergency_omissions.unwrap_or_else(|| {
539        omission_lines(
540            &render.omissions,
541            render.omitted_ids.len(),
542            &atlas_pack.dropped_sections,
543            atlas_pack.hard_truncated,
544            atlas_pack.exceeded_soft_budget,
545        )
546    });
547
548    let trust_policy = trust_policy_str(compiler.view.policy());
549
550    // Deterministic artifact hash: blake3 over (epoch + renderer_version +
551    // trust_policy + budget fields). The preimage never contains
552    // timestamps or volatile state, so the hash is stable per epoch.
553    let mut h = blake3::Hasher::new();
554    h.update(b"startup-artifact-v1");
555    h.update(epoch.as_bytes());
556    h.update(renderer_version.as_bytes());
557    h.update(trust_policy.as_bytes());
558    h.update(budget.total.to_string().as_bytes());
559    h.update(budget.atlas.to_string().as_bytes());
560    h.update(budget.surface.to_string().as_bytes());
561    h.update(budget.task_delta.to_string().as_bytes());
562    h.update(budget.structural_source.to_string().as_bytes());
563    let sha256 = h.finalize().to_hex().to_string();
564
565    // CONTENT hash: the same config preimage PLUS the actual rendered text
566    // (atlas + surface + coverage + omissions, without the artifact metadata
567    // comment). A content change that keeps the config identical now
568    // changes the hash — the audit's name/content mismatch fix.
569    let body = assemble_body(&atlas, &skeleton, &surface, &important, &coverage, &omissions);
570    let mut ch = blake3::Hasher::new();
571    ch.update(b"startup-content-v1");
572    ch.update(epoch.as_bytes());
573    ch.update(renderer_version.as_bytes());
574    ch.update(trust_policy.as_bytes());
575    ch.update(budget.total.to_string().as_bytes());
576    ch.update(budget.atlas.to_string().as_bytes());
577    ch.update(budget.surface.to_string().as_bytes());
578    ch.update(budget.task_delta.to_string().as_bytes());
579    ch.update(budget.structural_source.to_string().as_bytes());
580    ch.update(body.as_bytes());
581    let content_hash = ch.finalize().to_hex().to_string();
582
583    let mut artifact = ContextArtifact {
584        kind: "startup".into(),
585        epoch,
586        renderer_version: renderer_version.to_string(),
587        trust_policy,
588        budget: budget.clone(),
589        sha256,
590        content_hash,
591        text: String::new(),
592    };
593    artifact.text = assemble_block(&atlas, &skeleton, &surface, &important, &coverage, &omissions, &artifact);
594
595    StartupContext {
596        atlas,
597        atlas_budget_used,
598        skeleton,
599        surface,
600        important,
601        surface_render: render,
602        coverage,
603        omissions,
604        artifact,
605    }
606}
607/// The store-cache key for the global rank cache: `rank:global:` +
608/// blake3 over the composite cache epoch, the TrustPolicy fingerprint,
609/// and the rank salt (truncated to 20 hex chars, mirroring the
610/// `system_atlas` pack-cache key pattern). A changed epoch, policy, or
611/// salt yields a different key — a stale entry is never served.
612// trace:exempt reason=internal-detail
613fn global_rank_key(epoch: &str, policy: &str, salt: &str) -> String {
614    let mut h = blake3::Hasher::new();
615    h.update(b"rank:global:v1");
616    h.update(epoch.as_bytes());
617    h.update(b"\0");
618    h.update(policy.as_bytes());
619    h.update(b"\0");
620    h.update(salt.as_bytes());
621    format!("rank:global:{}", &h.finalize().to_hex()[..20])
622}
623
624/// Load the per-ModelEpoch global rank cache from the store cache
625/// (key `rank:global:<hash>` over epoch + policy + salt). `None` on any
626/// miss/error — never panics, never fabricates. The entry is validated
627/// against the current epoch/policy/salt (belt-and-suspenders: the key
628/// already pins them).
629// trace:v1 id=impl.scc.startup.rank-cache-load work=WORK-wave-15-2-heterogeneous-hierarchy-edges-semantic-scoring-explain-rank-caching satisfies=REQ-global-rank-cached-per-model-epoch
630pub fn load_global_rank_cache(compiler: &ContextCompiler) -> Option<GlobalRankCache> {
631    let epoch = compiler.store.cache_epoch().ok()?;
632    let policy = trust_policy_str(compiler.view.policy());
633    let salt = &compiler.settings.rank_salt;
634    let key = global_rank_key(&epoch, &policy, salt);
635    let cached = compiler.store.cache_get(&key, &epoch).ok().flatten()?;
636    let c: GlobalRankCache = serde_json::from_str(&cached).ok()?;
637    if c.epoch != epoch || c.policy != policy || c.salt != *salt {
638        return None;
639    }
640    Some(c)
641}
642
643/// Persist the per-ModelEpoch global rank cache (best-effort: cache
644/// failures never fail the caller).
645// trace:v1 id=impl.scc.startup.rank-cache-store work=WORK-wave-15-2-heterogeneous-hierarchy-edges-semantic-scoring-explain-rank-caching satisfies=REQ-global-rank-cached-per-model-epoch
646pub fn store_global_rank_cache(compiler: &ContextCompiler, cache: &GlobalRankCache) {
647    let epoch = compiler
648        .store
649        .cache_epoch()
650        .unwrap_or_else(|_| "no-epoch".into());
651    let policy = trust_policy_str(compiler.view.policy());
652    let salt = &compiler.settings.rank_salt;
653    let key = global_rank_key(&epoch, &policy, salt);
654    if let Ok(json) = serde_json::to_string(cache) {
655        let _ = compiler.store.cache_put(&key, &json, &epoch);
656    }
657}
658
659/// The logical symbol entity id of a rendered entry id: overload-sensitive
660/// entry ids carry a `#overload{N}` suffix (`{symbol}#overload{N}`) that
661/// is stripped to recover the symbol id. Non-overload entry ids ARE the
662/// symbol entity id.
663// trace:exempt reason=internal-detail
664fn symbol_id_of(entry_id: &str) -> String {
665    entry_id
666        .rsplit_once("#overload")
667        .map(|(logical, _)| logical)
668        .unwrap_or(entry_id)
669        .to_string()
670}
671
672/// The spec's startup block format. Pure function of the context struct, so
673/// `build_startup(..).artifact.text == render_startup(&startup)` always.
674// trace:exempt reason=internal-detail
675pub fn render_startup(s: &StartupContext) -> String {
676    assemble_block(&s.atlas, &s.skeleton, &s.surface, &s.important, &s.coverage, &s.omissions, &s.artifact)
677}
678
679/// The startup body (all content sections, no artifact metadata comment) —
680/// the preimage of `content_hash`.
681// trace:exempt reason=internal-detail
682fn assemble_body(atlas: &str, skeleton: &str, surface: &str, important: &str, coverage: &[String], omissions: &[String]) -> String {
683    let mut out = String::new();
684    out.push_str("## HOW TO READ THIS PACK\n");
685    out.push_str("What this is: machine-generated system context for this repo, fused from the local index. Work within it; do not re-derive what it states.\n");
686    out.push_str("Sections: SYSTEM ATLAS = architecture (purpose, components, stores, flows, invariants). REPOSITORY SKELETON = physical file layout. SYSTEM SURFACE MAP = callable API layer ranked by global importance (entry format: `name [role] -- kind: details`, grouped by component). SYSTEM-CRITICAL SYMBOLS = highest-attention symbols first. MODEL COVERAGE = index warnings (stale files, drift). OMISSIONS = what the budget cut (never silently dropped).\n");
687    out.push_str("Authority: source/runtime > this pack > checkpoint > hindsight > model assumption. Bracketed DOCUMENTATION labels are claims from docs, not verified facts. Verify before trusting: `scc verify`; re-index with `scc index` when stale.\n");
688    out.push_str("Next: task slice via `scc context task \"<goal>\"`; change blast radius via `scc impact <files>`; cross-layer edits check `scc drift` and `scc ci check`.\n");
689    out.push_str("\n## SYSTEM ATLAS\n");
690    out.push_str(atlas.trim_end());
691    out.push_str("\n\n## REPOSITORY SKELETON\n");
692    out.push_str(skeleton.trim_end());
693    out.push_str("\n\n## SYSTEM SURFACE MAP\n");
694    out.push_str(surface.trim_end());
695    out.push_str("\n\n");
696    out.push_str(important.trim_end());
697    out.push_str("\n\n## MODEL COVERAGE\n");
698    if coverage.is_empty() {
699        out.push_str("(no warnings)\n");
700    } else {
701        for c in coverage {
702            out.push_str(c);
703            out.push('\n');
704        }
705    }
706    out.push_str("\n## OMISSIONS\n");
707    for o in omissions {
708        out.push_str(o);
709        out.push('\n');
710    }
711    out
712}
713
714// trace:exempt reason=internal-detail
715fn assemble_block(
716    atlas: &str,
717    skeleton: &str,
718    surface: &str,
719    important: &str,
720    coverage: &[String],
721    omissions: &[String],
722    artifact: &ContextArtifact,
723) -> String {
724    let mut out = String::new();
725    out.push_str("# SCC SYSTEM CONTEXT\n");
726    out.push_str(&format!(
727        "<!-- artifact sha256:{} content_hash:{} epoch:{} renderer:{} -->\n\n",
728        artifact.sha256, artifact.content_hash, artifact.epoch, artifact.renderer_version
729    ));
730    out.push_str(&assemble_body(atlas, skeleton, surface, important, coverage, omissions));
731    out
732}
733
734/// Coverage warnings mirroring the compiler's pack warnings (deterministic):
735/// not-indexed, stale count, high/critical drift.
736// trace:exempt reason=internal-detail
737fn compiler_warnings(compiler: &ContextCompiler) -> Vec<String> {
738    let mut w = Vec::new();
739    if compiler.store.snapshot_status().ok().flatten().is_none() {
740        w.push("Repository is not indexed — run `scc index`.".into());
741    }
742    if !compiler.stale_paths.is_empty() {
743        w.push(format!(
744            "Model is stale: {} changed file(s) not yet re-indexed.",
745            compiler.stale_paths.len()
746        ));
747    }
748    if let Ok(findings) = compiler.store.drift_findings(true) {
749        for (_, kind, sev, msg, _) in findings {
750            if sev == "high" || sev == "critical" {
751                w.push(format!("Drift [{kind}]: {msg}"));
752            }
753        }
754    }
755    w.truncate(6);
756    w
757}
758
759// trace:exempt reason=internal-detail
760pub(crate) fn trust_policy_str(p: &scc_graph::TrustPolicy) -> String {
761    format!(
762        "extracted={} resolved={} observed={} declared={} inferred={} floor={}",
763        p.allow_extracted,
764        p.allow_resolved,
765        p.allow_observed,
766        p.allow_declared,
767        p.allow_inferred,
768        p.min_inferred_confidence
769    )
770}
771
772/// The kind-scoped id sets shown by the startup artifact (for ledger
773/// recording): `(symbols, files, components, flows)`. The surface side
774/// records ONLY the render result's `rendered_ids` — budget-omitted
775/// candidates are never marked visible (audit fix: the ledger must
776/// describe what the agent actually saw). Consumes the ALREADY-PRODUCED
777/// render (`startup.surface_render`) — the surface is built exactly once
778/// per startup; this function never rebuilds it.
779// trace:exempt reason=internal-detail
780pub fn visible_ids_from_startup(
781    compiler: &ContextCompiler,
782    startup: &StartupContext,
783) -> (BTreeSet<String>, BTreeSet<String>, BTreeSet<String>, BTreeSet<String>) {
784    let mut symbols = BTreeSet::new();
785    let mut files = BTreeSet::new();
786    let mut components = BTreeSet::new();
787    let mut flows = BTreeSet::new();
788
789    // Cache-hit in the CLI flow (build_startup already ran system_atlas
790    // at this budget). The DELIVERED budget — not the requested one — so
791    // emergency-floor artifacts record only delivered atlas ids (§53).
792    let atlas_pack = compiler.system_atlas(Some(startup.atlas_budget_used));
793
794    // Surface: rendered entries ONLY — the SAME render the artifact
795    // printed, so the ledger exactly matches the artifact text. Entry
796    // metadata (symbol id, file path, component) is derived from the
797    // trusted view per rendered id (cheap: rendered ids only, never the
798    // candidate pool) — no compile_surface_map walk.
799    let view = &compiler.view;
800    let rendered_symbols: BTreeSet<String> = startup
801        .surface_render
802        .rendered_ids
803        .iter()
804        .map(|id| symbol_id_of(id))
805        .collect();
806    // Component attribution mirrors compile_surface_map's containment
807    // walk (component CONTAINS file CONTAINS symbol; first component in
808    // name order wins) but only for the rendered symbol ids.
809    let mut comp_of: BTreeMap<String, String> = BTreeMap::new();
810    for c in view.components() {
811        for r in sorted_rels(view.out_pred(&c.id, scc_core::predicates::CONTAINS)) {
812            for sr in sorted_rels(view.out_pred(&r.object, scc_core::predicates::CONTAINS)) {
813                if rendered_symbols.contains(&sr.object) {
814                    comp_of
815                        .entry(sr.object.clone())
816                        .or_insert_with(|| c.name.clone());
817                }
818            }
819        }
820    }
821    for id in &startup.surface_render.rendered_ids {
822        let symbol_id = symbol_id_of(id);
823        symbols.insert(symbol_id.clone());
824        // The entry id is the entity id for non-overload entries; overload
825        // entries (n >= 1) resolve through the logical symbol id.
826        let ent = view.entity(id).or_else(|| view.entity(&symbol_id));
827        if let Some(e) = ent {
828            if let Some(f) = e.attributes.get("file").and_then(|v| v.as_str()) {
829                files.insert(f.to_string());
830            }
831        }
832        if let Some(c) = comp_of.get(&symbol_id) {
833            components.insert(c.clone());
834        }
835    }
836    // Classify the atlas pack's entity ids by kind (deterministic).
837    for id in &atlas_pack.entity_ids {
838        if let Some(e) = compiler.view.entity(id) {
839            match e.kind.as_str() {
840                kinds::SYMBOL => {
841                    symbols.insert(id.clone());
842                }
843                kinds::FILE => {
844                    files.insert(e.name.clone());
845                }
846                kinds::COMPONENT => {
847                    components.insert(id.clone());
848                }
849                kinds::FLOW => {
850                    flows.insert(id.clone());
851                }
852                _ => {}
853            }
854        }
855    }
856    (symbols, files, components, flows)
857}
858
859/// Deterministic relationship sort (id, subject, object) — mirrors the
860/// surface compiler's traversal order so attribution walks are stable.
861// trace:exempt reason=internal-detail
862fn sorted_rels(rels: Vec<&scc_core::Relationship>) -> Vec<&scc_core::Relationship> {
863    let mut v = rels;
864    v.sort_by(|a, b| {
865        a.id.cmp(&b.id)
866            .then_with(|| a.subject.cmp(&b.subject))
867            .then_with(|| a.object.cmp(&b.object))
868    });
869    v
870}
871
872/// `task_delta` plus the ids it rendered (for ledger recording). Routed
873/// through the one authoritative [`build_surface`] service in Task mode;
874/// never re-dumps the Atlas — the custom task/PPR selection implementation
875/// was deleted, [`build_surface`] is the only ranking pipeline. `semantic`
876/// is the caller-resolved scorer — transport parity: every transport with
877/// inference enabled passes the SAME scorer it passed to the task pack
878/// (interface choice must not change ranking quality). `None` redistributes
879/// the 10% share explicitly.
880// trace:v1 id=impl.scc.startup.task-delta-with-ids work=WORK-SCC-014 satisfies=REQ-SCC-IR
881pub fn task_delta_with_ids(
882    compiler: &ContextCompiler,
883    goal: &str,
884    visible: &ContextLedger,
885    budget_tokens: usize,
886    semantic: Option<&dyn crate::rank::SemanticScorer>,
887) -> (String, Vec<String>) {
888    let render = build_surface(
889        compiler,
890        SurfaceRequest {
891            mode: SurfaceMode::Task {
892                goal,
893                visible: Some(visible),
894            },
895            budget: budget_tokens,
896            explain: false,
897            policy: SurfacePolicy::defaults(budget_tokens),
898            semantic,
899        },
900    );
901    // TASK-CRITICAL SYMBOLS (audit item 3): top-8 task-ranked entries
902    // with badges + exact counts, ahead of the delta detail.
903    let critical = crate::surface::important_symbols(
904        compiler,
905        SurfaceMode::Task { goal, visible: Some(visible) },
906        8,
907    );
908    let mut out = String::new();
909    out.push_str("# SCC TASK DELTA\n");
910    out.push_str(&format!("TASK-FOCUS: {goal}\n"));
911    out.push_str(crate::surface::render_important(&critical, true).as_str());
912    out.push_str("Relevant APIs not already visible:\n");
913    let body = render
914        .text
915        .strip_prefix("SCC SYSTEM SURFACE MAP\n\n")
916        .unwrap_or(&render.text);
917    out.push_str(body.trim_end());
918    out.push('\n');
919    (out, render.rendered_ids)
920}
921
922/// Task-personalized surface map (full map, no novelty filter — this is a
923/// map, not a delta): entries re-ranked by task PPR + importance via the
924/// one authoritative [`build_surface`] service in Task mode.
925// trace:exempt reason=internal-detail
926pub fn task_surface(
927    compiler: &ContextCompiler,
928    goal: &str,
929    budget_tokens: usize,
930    explain: bool,
931    semantic: Option<&dyn crate::rank::SemanticScorer>,
932) -> String {
933    task_surface_with_ids(compiler, goal, budget_tokens, explain, semantic).0
934}
935
936/// `task_surface` plus the rendered entry ids (for ledger recording).
937/// `semantic` is the caller-resolved scorer — transport parity, same rule
938/// as [`task_delta_with_ids`].
939// trace:v1 id=impl.scc.startup.task-surface-with-ids work=WORK-SCC-014 satisfies=REQ-SCC-IR
940pub fn task_surface_with_ids(
941    compiler: &ContextCompiler,
942    goal: &str,
943    budget_tokens: usize,
944    explain: bool,
945    semantic: Option<&dyn crate::rank::SemanticScorer>,
946) -> (String, Vec<String>) {
947    let render = build_surface(
948        compiler,
949        SurfaceRequest {
950            mode: SurfaceMode::Task {
951                goal,
952                visible: None,
953            },
954            budget: budget_tokens,
955            explain,
956            policy: SurfacePolicy::defaults(budget_tokens),
957            semantic,
958        },
959    );
960    let mut out = String::new();
961    out.push_str(&format!("# SYSTEM SURFACE MAP (task-personalized: {goal})\n"));
962    let body = render
963        .text
964        .strip_prefix("SCC SYSTEM SURFACE MAP\n\n")
965        .unwrap_or(&render.text);
966    out.push_str(body.trim_end());
967    out.push('\n');
968    (out, render.rendered_ids)
969}
970
971#[cfg(test)]
972mod tests {
973    use super::*;
974
975// trace:exempt reason=internal-detail
976    fn fixture_compiler() -> (tempfile::TempDir, crate::ContextCompiler<'static>) {
977        let dir = tempfile::TempDir::new().unwrap();
978        let root = dir.path().join("repo");
979        std::fs::create_dir_all(&root).unwrap();
980        let store = Box::leak(Box::new(
981            scc_store::Store::open(&dir.path().join("scc.db"), &root).unwrap(),
982        ));
983        let graph = Box::leak(Box::new(scc_graph::RealityGraph::load(store).unwrap()));
984        let settings = crate::ContextSettings::default();
985        let comp = crate::ContextCompiler::new(store, graph, settings, Vec::new());
986        (dir, comp)
987    }
988
989    #[test]
990// trace:exempt reason=internal-detail
991    fn render_startup_emits_spec_headers() {
992        let sc = StartupContext {
993            atlas: "ATLAS-BODY".into(),
994            atlas_budget_used: 6000,
995            skeleton: "SKELETON-BODY".into(),
996            surface: "SURFACE-BODY".into(),
997            important: "IMPORTANT-BODY".into(),
998            surface_render: scc_core::SurfaceRenderResult {
999                text: "SURFACE-BODY".into(),
1000                rendered_ids: vec![],
1001                rendered_entries: vec![],
1002                omitted_ids: vec![],
1003                omissions: vec![],
1004                token_count: 0,
1005                critical_drops: vec![],
1006            },
1007            coverage: vec!["stale: a.py".into()],
1008            omissions: vec!["none".into()],
1009            artifact: ContextArtifact {
1010                kind: "startup".into(),
1011                epoch: "epoch:test".into(),
1012                renderer_version: "test".into(),
1013                trust_policy: "floor=0.85".into(),
1014                budget: ContextBudget::default(),
1015                sha256: "abc".into(),
1016                content_hash: "def".into(),
1017                text: String::new(),
1018            },
1019        };
1020        let out = render_startup(&sc);
1021        assert!(out.contains("# SCC SYSTEM CONTEXT"));
1022        assert!(out.contains("## SYSTEM ATLAS"));
1023        assert!(out.contains("## REPOSITORY SKELETON"));
1024        assert!(out.contains("## SYSTEM SURFACE MAP"));
1025        assert!(out.contains("ATLAS-BODY"));
1026        assert!(out.contains("SURFACE-BODY"));
1027        assert!(out.contains("SKELETON-BODY"));
1028        assert!(out.contains("## SYSTEM-CRITICAL SYMBOLS") || out.contains("IMPORTANT-BODY"));
1029        let (ia, ik, is) = (
1030            out.find("## SYSTEM ATLAS").unwrap(),
1031            out.find("## REPOSITORY SKELETON").unwrap(),
1032            out.find("## SYSTEM SURFACE MAP").unwrap(),
1033        );
1034        assert!(ia < ik && ik < is, "skeleton grounds before architecture");
1035        assert!(out.contains("stale: a.py"));
1036    }
1037
1038    #[test]
1039// trace:exempt reason=internal-detail
1040    fn artifact_text_equals_rendered_block() {
1041        let (_dir, comp) = fixture_compiler();
1042        let budget = ContextBudget::default();
1043        let sc = build_startup(&comp, &budget, "test-renderer");
1044        assert_eq!(sc.artifact.text, render_startup(&sc));
1045        assert_eq!(sc.artifact.sha256.len(), 64);
1046        assert_eq!(sc.artifact.content_hash.len(), 64);
1047        assert_ne!(sc.artifact.content_hash, sc.artifact.sha256);
1048        assert!(render_startup(&sc).contains("content_hash:"));
1049        assert_eq!(sc.artifact.epoch, comp.store.cache_epoch().unwrap_or_default());
1050    }
1051
1052    #[test]
1053// trace:exempt reason=internal-detail
1054    fn global_rank_cache_roundtrips_through_the_store() {
1055        let (_dir, comp) = fixture_compiler();
1056        // miss on a cold store
1057        assert!(load_global_rank_cache(&comp).is_none());
1058        let cache = GlobalRankCache {
1059            epoch: comp.store.cache_epoch().unwrap_or_else(|_| "no-epoch".into()),
1060            policy: trust_policy_str(comp.view.policy()),
1061            salt: comp.settings.rank_salt.clone(),
1062            global_vector: vec![0.1, 0.2, 0.3],
1063            node_symbol_map: BTreeMap::from([("repo://r/symbol/a.py/serve".into(), 0.42)]),
1064            candidates_epoch: comp.store.cache_epoch().unwrap_or_default(),
1065            candidate_ids: vec!["repo://r/symbol/a.py/serve".into()],
1066            hits: 1,
1067        };
1068        store_global_rank_cache(&comp, &cache);
1069        let loaded = load_global_rank_cache(&comp).expect("cache entry present after store");
1070        assert_eq!(loaded, cache);
1071        assert_eq!(loaded.hits, 1);
1072        assert_eq!(
1073            loaded.node_symbol_map.get("repo://r/symbol/a.py/serve"),
1074            Some(&0.42)
1075        );
1076        assert_eq!(loaded.candidates_epoch, loaded.epoch);
1077    }
1078
1079    #[test]
1080// trace:exempt reason=internal-detail
1081    fn visible_ids_consume_the_same_render_the_artifact_printed() {
1082        // The ledger-visible surface ids MUST be exactly the render's
1083        // rendered_ids (never a rebuild, never the candidate pool): every
1084        // rendered entry's logical symbol is visible. The inverse
1085        // direction (omitted candidates never visible) is asserted in the
1086        // indexed CLI fixture (surface_startup.rs) where the atlas symbol
1087        // set is controlled.
1088        let (_dir, comp) = fixture_compiler();
1089        let budget = ContextBudget::default();
1090        let sc = build_startup(&comp, &budget, "test-renderer");
1091        assert!(sc.artifact.text.contains(&sc.surface));
1092        let (syms, _files, _comps, _flows) = visible_ids_from_startup(&comp, &sc);
1093        for id in &sc.surface_render.rendered_ids {
1094            let symbol_id = symbol_id_of(id);
1095            assert!(
1096                syms.contains(&symbol_id),
1097                "rendered entry {id} must be marked visible (symbol {symbol_id})"
1098            );
1099        }
1100    }
1101}
scc_context/startup.rs

scc_context/
startup.rs
