agentera 3.0.0-dev.6 → 3.0.0-dev.69

package/dist/analytics/profileSignals.js

@@ -0,0 +1,211 @@
+import path from "node:path";
+import { PROFILE_SIGNAL_TYPES, profileSufficiency, } from "../registries/evidenceTierContract.js";
+import { readCurrentPointer, readSignalTier, resolveEvidenceAnchor, } from "./extractCorpus/evidenceTiers.js";
+import { assessTiers, recoveryForState, resolveTiersDir, } from "./extractCorpus/tierReader.js";
+const PROFILE_TYPES_SET = new Set(PROFILE_SIGNAL_TYPES);
+/** Resolve the absolute signal tier file path from the current generation. */
+function signalTierPath(tiersDir) {
+    const pointer = readCurrentPointer(tiersDir);
+    if (!pointer)
+        return null;
+    return path.join(tiersDir, "generations", pointer.generation, "signal.json");
+}
+/** Resolve the co-located corpus path for legacy compatibility assessment. */
+function corpusPathFromTiersDir(tiersDir) {
+    const idx = tiersDir.lastIndexOf(path.sep + "tiers");
+    if (idx === -1)
+        return undefined;
+    return path.join(tiersDir.slice(0, idx), "corpus.json");
+}
+/**
+ * Assess whether the retained profile-relevant signal distribution is
+ * sufficient against the contract threshold. The prior intended distribution
+ * is reconstructed from the signal tier's selection report (total per
+ * family); the retained distribution from the published signal records.
+ * No separate full-corpus read is needed — the selection report carries both.
+ *
+ * When the tier is uncapped, retained == total, so the bounded and intended
+ * distributions are identical and sufficiency is trivially met. When capped,
+ * the selection report's per-family total/retained is the authoritative prior
+ * distribution; the profile-relevant intended count is scaled from the
+ * retained profile-relevant count by the family's overall retention ratio.
+ */
+export function assessProfileSufficiency(selection, signals, contractPath) {
+    const suff = profileSufficiency(contractPath);
+    const threshold = suff.minimumFamilyRetention;
+    const profileRetainedPerFamily = new Map();
+    for (const sig of signals) {
+        const family = sig.source_product || "unknown";
+        profileRetainedPerFamily.set(family, (profileRetainedPerFamily.get(family) ?? 0) + 1);
+    }
+    const profileIntendedPerFamily = new Map();
+    if (!selection.capped) {
+        // Uncapped: retained == intended, so the retained counts ARE the intended.
+        for (const [family, retained] of profileRetainedPerFamily) {
+            profileIntendedPerFamily.set(family, retained);
+        }
+    }
+    else {
+        // Capped: the selection report's per_family is the authoritative source
+        // of which families had records. For families with profile-relevant
+        // retained signals, scale the intended count by the family's overall
+        // retention ratio. For families where all records were capped
+        // (retained=0, total>0), flag them as insufficient — no data survived
+        // to contribute to the profile.
+        for (const sel of selection.per_family) {
+            if (sel.total === 0)
+                continue;
+            const profileRetained = profileRetainedPerFamily.get(sel.family) ?? 0;
+            if (sel.retained > 0 && profileRetained > 0) {
+                profileIntendedPerFamily.set(sel.family, Math.round(profileRetained * (sel.total / sel.retained)));
+            }
+            else if (sel.retained === 0 && sel.total > 0) {
+                // All records for this family were capped — insufficient by definition.
+                profileIntendedPerFamily.set(sel.family, sel.total);
+            }
+            // If sel.retained > 0 but profileRetained == 0, the family's retained
+            // records were simply non-profile-relevant; leave it as sufficient.
+        }
+        // Also include any family that appears in retained signals but not in the
+        // selection report (should not normally happen, but handle gracefully).
+        for (const [family, retained] of profileRetainedPerFamily) {
+            if (!profileIntendedPerFamily.has(family)) {
+                profileIntendedPerFamily.set(family, retained);
+            }
+        }
+    }
+    const perFamily = [];
+    const allFamilies = new Set([...profileIntendedPerFamily.keys(), ...profileRetainedPerFamily.keys()]);
+    for (const family of [...allFamilies].sort()) {
+        const intended = profileIntendedPerFamily.get(family) ?? 0;
+        const retained = profileRetainedPerFamily.get(family) ?? 0;
+        const retention = intended > 0 ? retained / intended : 1;
+        const sufficient = intended === 0 || retention >= threshold;
+        perFamily.push({ family, intended, retained, retention, sufficient });
+    }
+    const insufficientFamilies = perFamily.filter((f) => !f.sufficient);
+    const sufficient = !selection.capped || insufficientFamilies.length === 0;
+    const reason = sufficient
+        ? selection.capped
+            ? "signal tier capped but per-family retention meets threshold"
+            : "signal tier uncapped; bounded and intended distributions identical"
+        : `insufficient retention for families: ${insufficientFamilies.map((f) => `${f.family} (${f.retained}/${f.intended}, ${(f.retention * 100).toFixed(0)}%)`).join(", ")}`;
+    return { sufficient, reason, threshold, capped: selection.capped, per_family: perFamily };
+}
+/**
+ * Read the bounded signal tier and return profile-relevant signals with a
+ * sufficiency assessment. This is the bounded profile-synthesis input: it
+ * loads only the signal tier (bounded by construction), never the full-
+ * evidence shards. Each signal's `evidence_anchor` resolves to retained full
+ * evidence via resolveProfileEvidence.
+ */
+export function readProfileSignals(tiersDir, corpusPath, contractPath) {
+    const assessment = assessTiers(tiersDir, corpusPath);
+    const recovery = recoveryForState(assessment.state);
+    const threshold = profileSufficiency(contractPath).minimumFamilyRetention;
+    if (!assessment.analyzable) {
+        return {
+            state: assessment.state,
+            tiers_dir: tiersDir,
+            signal_path: null,
+            signals: [],
+            profile_signal_count: 0,
+            sufficiency: {
+                sufficient: false,
+                reason: assessment.state === "missing"
+                    ? "no evidence tiers published"
+                    : assessment.state === "legacy"
+                        ? "legacy monolithic state; refresh required"
+                        : `tier state ${assessment.state}; ${recovery ?? "recovery unavailable"}`,
+                threshold,
+                capped: false,
+                per_family: [],
+            },
+            recovery,
+        };
+    }
+    const tier = readSignalTier(tiersDir);
+    if (!tier) {
+        return {
+            state: "corrupt",
+            tiers_dir: tiersDir,
+            signal_path: null,
+            signals: [],
+            profile_signal_count: 0,
+            sufficiency: {
+                sufficient: false,
+                reason: "signal tier unreadable or not found",
+                threshold,
+                capped: false,
+                per_family: [],
+            },
+            recovery,
+        };
+    }
+    const profileSignals = tier.records.filter((s) => PROFILE_TYPES_SET.has(s.signal_type));
+    const sufficiency = assessProfileSufficiency(tier.manifest.signal.selection, profileSignals, contractPath);
+    return {
+        state: assessment.state,
+        tiers_dir: tiersDir,
+        signal_path: signalTierPath(tiersDir),
+        signals: profileSignals,
+        profile_signal_count: profileSignals.length,
+        sufficiency,
+        recovery,
+    };
+}
+/**
+ * Resolve a synthesized claim's evidence anchor to its retained full-evidence
+ * record. Loads only the owning shard, never the whole tier. Returns null
+ * when the anchor does not resolve (the claim cannot be checked).
+ */
+export function resolveProfileEvidence(anchor, tiersDir) {
+    return resolveEvidenceAnchor(anchor, tiersDir);
+}
+/**
+ * Lightweight status for profile_context — assesses the tiers, reads the
+ * signal tier, and computes sufficiency. The signal records are counted but
+ * not returned in the status payload (the synthesis step reads them via
+ * readProfileSignals or the signal_path). This status tells the agent
+ * whether synthesis can proceed and where to read.
+ */
+export function profileSignalsStatus(env = process.env, platform = process.platform, contractPath) {
+    const tiersDir = resolveTiersDir(env, platform);
+    const corpusPath = corpusPathFromTiersDir(tiersDir);
+    const assessment = assessTiers(tiersDir, corpusPath);
+    const recovery = recoveryForState(assessment.state);
+    if (!assessment.analyzable) {
+        return {
+            state: assessment.state,
+            tiers_dir: tiersDir,
+            signal_path: null,
+            signal_count: 0,
+            profile_signal_count: 0,
+            sufficiency: null,
+            recovery,
+        };
+    }
+    const tier = readSignalTier(tiersDir);
+    if (!tier) {
+        return {
+            state: "corrupt",
+            tiers_dir: tiersDir,
+            signal_path: null,
+            signal_count: 0,
+            profile_signal_count: 0,
+            sufficiency: null,
+            recovery,
+        };
+    }
+    const profileSignals = tier.records.filter((s) => PROFILE_TYPES_SET.has(s.signal_type));
+    const sufficiency = assessProfileSufficiency(tier.manifest.signal.selection, profileSignals, contractPath);
+    return {
+        state: assessment.state,
+        tiers_dir: tiersDir,
+        signal_path: signalTierPath(tiersDir),
+        signal_count: tier.records.length,
+        profile_signal_count: profileSignals.length,
+        sufficiency,
+        recovery,
+    };
+}

package/dist/analytics/usageStats.js

@@ -1,10 +1,13 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { resolveProfileDirOverride, resolveXdgDataHome } from "../core/envPaths.js";
+import { expanduser } from "../core/paths.js";
+import { tiersDirForCorpusPath, assessTiers, iterBoundedRecords, readTierCorpusMetadata } from "./extractCorpus/index.js";
 export const EXIT_STATUSES = new Set(["complete", "flagged", "stuck", "waiting"]);
 export const TRIGGER_SLASH = "slash";
 export const TRIGGER_NATURAL = "natural";
-const MARKER_RE = /─{2,}\s+(\S)\s+([a-z]+era)\s+·\s+([a-z]+(?:\s+\d+)?)\s+─{2,}/g;
+const MARKER_RE = /─{2,}\s+(\S)\s+(status|vision|discuss|research|plan|build|optimize|audit|document|profile|design|orchestrate)\s+·\s+([a-z]+(?:\s+\d+)?)\s+─{2,}/g;
 function newInvocation(init) {
     return {
         skill: init.skill,
@@ -18,6 +21,9 @@ function newInvocation(init) {
         exit_timestamp: init.exit_timestamp ?? null,
         trigger: init.trigger ?? TRIGGER_NATURAL,
         project_id: init.project_id ?? "",
+        source_class: init.source_class ?? "active_runtime",
+        source_product: init.source_product ?? "unknown",
+        active_runtime: init.active_runtime ?? true,
     };
 }
 export function findMarkers(text) {
@@ -101,7 +107,7 @@ export function pairInvocations(turns) {
     for (const turn of turns) {
         const sid = String(turn.source_id ?? "");
         const ts = String(turn.timestamp ?? "");
-        const text = (isMapping(turn.data) ? turn.data.content : "") || "";
+        const text = ((isMapping(turn.data) ? turn.data.content : "") || ""); // cast: corpus record content from JSON.parse IO boundary
         for (const marker of findMarkers(text)) {
             if (marker.kind === "intro") {
                 if (!pending.has(marker.skill))
@@ -113,6 +119,9 @@ export function pairInvocations(turns) {
                     intro_source_id: sid,
                     intro_timestamp: ts,
                     completed: false,
+                    source_class: String(turn.source_class ?? "active_runtime"),
+                    source_product: String(turn.source_product ?? turn.runtime ?? "unknown"),
+                    active_runtime: turn.active_runtime !== false && turn.source_class !== "historical_import",
                 }));
             }
             else {
@@ -150,12 +159,13 @@ function stableSort(items, key) {
     })
         .map(([item]) => item);
 }
-const CLAUDE_CODE_XML_RE = /<command-name>\s*\/[A-Za-z0-9._:-]+\s*<\/command-name>/;
+// Retained only to classify command markup in consent-gated historical imports.
+const HISTORICAL_COMMAND_XML_RE = /<command-name>\s*\/[A-Za-z0-9._:-]+\s*<\/command-name>/;
 const BARE_SLASH_RE = /^\s*\/[A-Za-z0-9._:-]+(?:\s|$)/m;
 export function classifyTrigger(userTurnText) {
     if (!userTurnText)
         return TRIGGER_NATURAL;
-    if (CLAUDE_CODE_XML_RE.test(userTurnText))
+    if (HISTORICAL_COMMAND_XML_RE.test(userTurnText))
         return TRIGGER_SLASH;
     if (BARE_SLASH_RE.test(userTurnText))
         return TRIGGER_SLASH;
@@ -226,13 +236,70 @@ function accumulate(bucket, inv) {
     bucket[inv.completed ? "completed" : "incomplete"] += 1;
     bucket[inv.trigger === TRIGGER_SLASH ? "trigger_slash" : "trigger_natural"] += 1;
 }
-export function analyzeCorpus(corpus, projectFilter = null) {
-    const rawRecords = isMapping(corpus) ? (corpus.records ?? []) : [];
-    const records = filterRecordsByProject(rawRecords, projectFilter);
-    const userTurnsByConv = userTurnsByConversation(records);
-    const grouped = groupByConversation(records);
+function activeAnalyticsRecord(record) {
+    if (record.active_runtime === false || record.source_class === "historical_import")
+        return false;
+    return record.runtime !== "claude" && record.runtime !== "claude-code";
+}
+export function analyzeCorpus(corpus, projectFilter = null, sourceView = "active") {
+    const rawRecords = (isMapping(corpus) ? (corpus.records ?? []) : []); // cast: corpus records from JSON.parse IO boundary
+    return analyzeRecords(rawRecords, projectFilter, sourceView);
+}
+/**
+ * Single-pass analysis over a record iterable. Bounded consumers feed the
+ * tiered shard iterator here so non-conversation records (instruction documents,
+ * project config signals, tool calls) are counted for provenance and discarded
+ * rather than materialized; only conversation turns are retained as the analysis
+ * working set. Mirrors `analyzeCorpus` exactly when given the full record array.
+ */
+export function analyzeRecords(records, projectFilter = null, sourceView = "active") {
+    const provenanceCounts = new Map();
+    const userTurnsByConv = new Map();
+    const assistantByConv = new Map();
+    for (const record of records) {
+        if (!isMapping(record))
+            continue;
+        const isActive = activeAnalyticsRecord(record);
+        if (sourceView === "active" && !isActive)
+            continue;
+        if (projectFilter !== null) {
+            const pid = record.project_id ?? "";
+            if (!(typeof pid === "string" && projectMatch(pid, projectFilter)))
+                continue;
+        }
+        const sourceClass = String(record.source_class ?? (isActive ? "active_runtime" : "historical_import"));
+        const sourceProduct = String(record.source_product ?? record.runtime ?? "unknown");
+        const activeRuntime = isActive;
+        const key = `${sourceClass}\0${sourceProduct}\0${activeRuntime}`;
+        const current = provenanceCounts.get(key) ?? { source_class: sourceClass, source_product: sourceProduct, active_runtime: activeRuntime, records: 0 };
+        current.records += 1;
+        provenanceCounts.set(key, current);
+        if (record.source_kind !== "conversation_turn")
+            continue;
+        const data = record.data;
+        if (!isMapping(data))
+            continue;
+        const ckey = conversationKey(record);
+        if (ckey === null)
+            continue;
+        const actor = data.actor;
+        if (actor === "user") {
+            if (!userTurnsByConv.has(ckey))
+                userTurnsByConv.set(ckey, []);
+            userTurnsByConv.get(ckey).push(record);
+        }
+        else if (actor === "assistant") {
+            if (!assistantByConv.has(ckey))
+                assistantByConv.set(ckey, []);
+            assistantByConv.get(ckey).push(record);
+        }
+    }
+    for (const items of userTurnsByConv.values())
+        stableSortByTimestamp(items);
+    for (const items of assistantByConv.values())
+        stableSortByTimestamp(items);
     const invocations = [];
-    for (const [sid, turns] of grouped) {
+    for (const [sid, turns] of assistantByConv) {
         const tsToProject = new Map();
         for (const t of turns) {
             tsToProject.set(String(t.timestamp ?? ""), String(t.project_id ?? ""));
@@ -243,7 +310,7 @@ export function analyzeCorpus(corpus, projectFilter = null) {
             let precedingText = "";
             if (preceding !== null) {
                 const data = isMapping(preceding.data) ? preceding.data : {};
-                precedingText = data.content || "";
+                precedingText = (data.content || ""); // cast: corpus record content from JSON.parse IO boundary
             }
             inv.trigger = classifyTrigger(precedingText);
             invocations.push(inv);
@@ -264,34 +331,40 @@ export function analyzeCorpus(corpus, projectFilter = null) {
             accumulate(perProject[inv.project_id][inv.skill], inv);
         }
     }
-    return { invocations: sorted, skills, project_filter: projectFilter, per_project: perProject };
+    return {
+        invocations: sorted,
+        skills,
+        project_filter: projectFilter,
+        per_project: perProject,
+        source_view: sourceView,
+        source_provenance: [...provenanceCounts.values()].sort((a, b) => `${a.source_class}:${a.source_product}`.localeCompare(`${b.source_class}:${b.source_product}`)),
+    };
 }
 // --- Paths -----------------------------------------------------------------
-export const CORPUS_GUIDANCE = "Provide --corpus <path> to an existing corpus.json.";
+export const CORPUS_GUIDANCE = "Publish bounded tiers with `agentera stats refresh --consent local-history`; `--corpus PATH` points at a legacy corpus.json whose sibling `tiers/` is preferred when published.";
 function homeDir(env) {
     return env.HOME ?? os.homedir();
 }
 export function defaultUsageDir(env = process.env, platform = process.platform) {
     const override = env.AGENTERA_USAGE_DIR;
     if (override)
-        return override;
-    const profileraOverride = env.PROFILERA_PROFILE_DIR;
-    if (profileraOverride)
-        return profileraOverride;
+        return expanduser(override);
+    const profileOverride = resolveProfileDirOverride(env);
+    if (profileOverride)
+        return expanduser(profileOverride);
     const home = homeDir(env);
     if (platform === "darwin")
         return path.join(home, "Library", "Application Support", "agentera");
     if (platform === "win32") {
         const appdata = env.APPDATA ?? path.join(home, "AppData", "Roaming");
-        return path.join(appdata, "agentera");
+        return path.join(expanduser(appdata), "agentera");
     }
-    const xdg = env.XDG_DATA_HOME ?? path.join(home, ".local", "share");
-    return path.join(xdg, "agentera");
+    return path.join(resolveXdgDataHome(env, home), "agentera");
 }
 export function defaultCorpusPath(env = process.env, platform = process.platform) {
-    const profileraOverride = env.PROFILERA_PROFILE_DIR;
-    if (profileraOverride)
-        return path.join(profileraOverride, "intermediate", "corpus.json");
+    const profileOverride = resolveProfileDirOverride(env);
+    if (profileOverride)
+        return path.join(expanduser(profileOverride), "intermediate", "corpus.json");
     const home = homeDir(env);
     let base;
     if (platform === "darwin") {
@@ -299,11 +372,10 @@ export function defaultCorpusPath(env = process.env, platform = process.platform
     }
     else if (platform === "win32") {
         const appdata = env.APPDATA ?? path.join(home, "AppData", "Roaming");
-        base = path.join(appdata, "agentera");
+        base = path.join(expanduser(appdata), "agentera");
     }
     else {
-        const xdg = env.XDG_DATA_HOME ?? path.join(home, ".local", "share");
-        base = path.join(xdg, "agentera");
+        base = path.join(resolveXdgDataHome(env, home), "agentera");
     }
     return path.join(base, "intermediate", "corpus.json");
 }
@@ -319,7 +391,7 @@ export function corpusTooLargeReason(corpusPath) {
         const size = fs.statSync(corpusPath).size;
         if (size <= MAX_CORPUS_READ_BYTES)
             return null;
-        return `corpus is too large to load (${size} bytes; max ${MAX_CORPUS_READ_BYTES}). Rebuild with agentera stats refresh --consent local-history or pass --corpus PATH to a smaller extract.`;
+        return `corpus is too large to load (${size} bytes; max ${MAX_CORPUS_READ_BYTES}). Refresh bounded tiers with agentera stats refresh --consent local-history, or pass --corpus PATH to a smaller legacy extract (its sibling tiers/ is preferred when published).`;
     }
     catch {
         return null;
@@ -340,18 +412,20 @@ export function loadCorpusOrRaise(corpusPath) {
     catch (exc) {
         throw new CorpusUnavailable(`corpus is not readable JSON: ${exc.message}`);
     }
-    const records = isMapping(corpus) ? (corpus.records ?? []) : [];
+    const records = (isMapping(corpus) ? (corpus.records ?? []) : []); // cast: corpus records from JSON.parse IO boundary
     const hasTurn = Array.isArray(records) && records.some((r) => isMapping(r) && r.source_kind === "conversation_turn");
     if (!hasTurn) {
         throw new CorpusUnavailable(`corpus at ${corpusPath} contains no conversation_turn records. ${CORPUS_GUIDANCE}`);
     }
-    return corpus;
+    return corpus; // cast: corpus from JSON.parse IO boundary
 }
 export function buildJsonPayload(analysis, opts) {
     return {
         generated_at: opts.generatedAt,
         extracted_at: opts.extractedAt,
         project_filter: analysis.project_filter,
+        source_view: analysis.source_view,
+        source_provenance: analysis.source_provenance,
         skills: analysis.skills,
         per_project: analysis.per_project,
         invocations: analysis.invocations.map((inv) => ({ ...inv })),
@@ -381,7 +455,10 @@ export function renderMarkdown(analysis, opts) {
     const scope = analysis.project_filter || "all projects";
     const extractedLine = opts.extractedAt || "unknown (corpus omitted extracted_at)";
     const lines = [];
-    lines.push("# Suite Usage", "", `- Generated: ${opts.generatedAt}`, `- Corpus extracted: ${extractedLine}`, `- Scope: ${scope}`, "");
+    lines.push("# Suite Usage", "", `- Generated: ${opts.generatedAt}`, `- Corpus extracted: ${extractedLine}`, `- Scope: ${scope}`, `- Sources: ${analysis.source_view}`, "");
+    if (analysis.source_view === "all") {
+        lines.push("## Source provenance", "", "| Source class | Source product | Active runtime | Records |", "| --- | --- | --- | --- |", ...analysis.source_provenance.map((item) => `| ${item.source_class} | ${item.source_product} | ${item.active_runtime ? "yes" : "no"} | ${item.records} |`), "");
+    }
     if (Object.keys(analysis.skills).length === 0) {
         lines.push("No skill invocations found in the corpus for this scope.", "");
         return lines.join("\n");
@@ -468,6 +545,7 @@ export function usageMain(argv, io = {}) {
     let corpus = null;
     let project = null;
     let emitJson = false;
+    let sourceView = "active";
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--corpus")
@@ -480,23 +558,61 @@ export function usageMain(argv, io = {}) {
             project = a.slice("--project=".length);
         else if (a === "--json")
             emitJson = true;
+        else if (a === "--sources" || a.startsWith("--sources=")) {
+            const value = a === "--sources" ? argv[++i] : a.slice("--sources=".length);
+            if (value !== "active" && value !== "all") {
+                err(`usage_stats: unsupported --sources '${value}'; choose active or all`);
+                return 2;
+            }
+            sourceView = value;
+        }
     }
     const corpusPath = corpus ?? defaultCorpusPath(env, platform);
-    let corpusData;
-    try {
-        corpusData = loadCorpusOrRaise(corpusPath);
-    }
-    catch (e) {
-        if (e instanceof CorpusUnavailable) {
-            err(String(e.message));
+    // Bounded tier path: analyze real-scale evidence by streaming one bounded
+    // shard at a time instead of materializing the monolithic corpus envelope.
+    // Falls back to the legacy corpus.json read only when no tiers were published
+    // (legacy state) so existing small-envelope consumers keep working.
+    const tiersDir = tiersDirForCorpusPath(corpusPath);
+    const assessment = assessTiers(tiersDir, corpusPath);
+    let analysis;
+    let extractedAt = null;
+    if (assessment.analyzable) {
+        const records = iterBoundedRecords(tiersDir);
+        if (records === null) {
+            err(tierUnavailableMessage(assessment, corpusPath));
             return 2;
         }
-        throw e;
+        analysis = analyzeRecords(records, project, sourceView);
+        const metadata = readTierCorpusMetadata(tiersDir);
+        extractedAt = metadata?.extracted_at ?? null;
+    }
+    else if (assessment.state === "corrupt" || assessment.state === "oversized") {
+        // Tier-level failure: the published tier is unreadable or a shard exceeds the
+        // reader cap. Project actionable recovery from the authority contract rather
+        // than silently falling back to the corpus envelope.
+        err(tierUnavailableMessage(assessment, corpusPath));
+        return 2;
+    }
+    else {
+        // Legacy or missing: delegate to the corpus-envelope reader, which preserves
+        // the existing too-large / not-found degradation and message contract.
+        let corpusData;
+        try {
+            corpusData = loadCorpusOrRaise(corpusPath);
+        }
+        catch (e) {
+            if (e instanceof CorpusUnavailable) {
+                err(String(e.message));
+                return 2;
+            }
+            throw e;
+        }
+        analysis = analyzeCorpus(corpusData, project, sourceView);
+        const md = corpusData.metadata;
+        extractedAt =
+            md && typeof md === "object" && !Array.isArray(md) ? (md.extracted_at ?? null) : null;
     }
-    const analysis = analyzeCorpus(corpusData, project);
     const generatedAt = nowIso();
-    const md = corpusData.metadata;
-    const extractedAt = md && typeof md === "object" && !Array.isArray(md) ? (md.extracted_at ?? null) : null;
     if (emitJson) {
         out(renderJson(analysis, { generatedAt, extractedAt }));
         return 0;
@@ -506,4 +622,15 @@ export function usageMain(argv, io = {}) {
     out(renderStdoutSummary(analysis, { generatedAt, extractedAt, reportPath: outPath }));
     return 0;
 }
-//# sourceMappingURL=usageStats.js.map
+/** Compose the degrade message for a non-analyzable tier state. */
+function tierUnavailableMessage(assessment, corpusPath) {
+    const recovery = assessment.recovery;
+    const where = `tiers at ${assessment.tiersDir}${corpusPath ? ` (corpus=${corpusPath})` : ""}`;
+    if (assessment.state === "oversized") {
+        return `evidence tier is oversized at ${assessment.artifact ?? where}. ${recovery ?? ""}`.trim();
+    }
+    if (assessment.state === "corrupt") {
+        return `evidence tier is unreadable at ${where}. ${recovery ?? ""}`.trim();
+    }
+    return `evidence tier is ${assessment.state} at ${where}. ${recovery ?? ""}`.trim();
+}