agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/state/startupAnalysis/metrics.js

@@ -0,0 +1,340 @@
+import { inc, counterDict, nowIsoSeconds, flt, pyRound, safeInt, } from "./helpers.js";
+import { boundedRuntimeStatus } from "./threshold.js";
+export const STARTUP_METRICS_ENVELOPE = "startup_state_metrics_v1";
+export const TOKEN_ESTIMATOR_VERSION = "approx_bytes_div_4_v1";
+function mergeTokenEstimates(counter, value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return;
+    for (const [label, estimate] of Object.entries(value)) {
+        if (typeof label === "string" && typeof estimate === "number" && Number.isInteger(estimate)) {
+            counter[label] = (counter[label] ?? 0) + estimate;
+        }
+    }
+}
+function sequenceCount(sequence, eventClass) {
+    const counts = sequence.counts;
+    if (counts && typeof counts === "object" && !Array.isArray(counts) && typeof counts[eventClass] === "number") {
+        return counts[eventClass];
+    }
+    const events = Array.isArray(sequence.events) ? sequence.events : [];
+    return events.filter((event) => Boolean(event && typeof event === "object" && !Array.isArray(event) && event.event_class === eventClass)).length;
+}
+function distribution(values) {
+    if (values.length === 0) {
+        return { count: 0, min: 0, max: 0, mean: 0, p50: 0, p75: 0, histogram: {} };
+    }
+    const ordered = [...values].sort((a, b) => a - b);
+    const percentile = (fraction) => {
+        const index = Math.min(ordered.length - 1, Math.ceil(ordered.length * fraction - 1));
+        return ordered[Math.max(index, 0)];
+    };
+    const histCounts = {};
+    for (const v of ordered)
+        histCounts[v] = (histCounts[v] ?? 0) + 1;
+    const histogram = {};
+    for (const key of Object.keys(histCounts).map(Number).sort((a, b) => a - b)) {
+        histogram[String(key)] = histCounts[key];
+    }
+    return {
+        count: ordered.length,
+        min: ordered[0],
+        max: ordered[ordered.length - 1],
+        mean: flt(pyRound(ordered.reduce((a, b) => a + b, 0) / ordered.length, 2)),
+        p50: percentile(0.5),
+        p75: percentile(0.75),
+        histogram,
+    };
+}
+function unionAll(map) {
+    const out = new Set();
+    for (const s of Object.values(map))
+        for (const v of s)
+            out.add(v);
+    return out;
+}
+function deriveStateThresholds(args) {
+    const capabilityCount = Object.keys(args.perCapability).length;
+    const credibleDistribution = args.totalSequences >= 3;
+    const rawDistribution = distribution(args.rawAfterCliPerSequence);
+    const redundantDistribution = distribution(args.redundantRawPerSequence);
+    const redundantArtifacts = {};
+    for (const label of Object.keys(args.redundantCounts).sort()) {
+        const count = args.redundantCounts[label];
+        if (count > 0) {
+            redundantArtifacts[label] = {
+                count,
+                capability_count: (args.redundantCapabilities[label] ?? new Set()).size,
+            };
+        }
+    }
+    const redundantSequenceCount = args.redundantRawPerSequence.filter((v) => v > 0).length;
+    const aggregateRedundantCapabilities = Object.keys(args.redundantCapabilities).length > 0 ? unionAll(args.redundantCapabilities) : new Set();
+    let redundantSequenceThreshold;
+    let thresholdReason;
+    if (credibleDistribution) {
+        redundantSequenceThreshold = Math.max(2, Math.ceil(args.totalSequences * 0.2));
+        thresholdReason =
+            "Selected from post-boundary state-gathering distribution: raw artifact " +
+                "access after CLI state must recur in at least 20% of measured sequences, " +
+                "with a floor of two sequences.";
+    }
+    else {
+        redundantSequenceThreshold = null;
+        thresholdReason = "No broad-envelope threshold: fewer than three state-gathering sequences were measured.";
+    }
+    let broadTrigger = null;
+    if (credibleDistribution) {
+        for (const [label, item] of Object.entries(redundantArtifacts)) {
+            if (safeInt(item.count) >= redundantSequenceThreshold && safeInt(item.capability_count) >= 2) {
+                broadTrigger = {
+                    event_class: "raw_artifact_access",
+                    artifact_label: label,
+                    count: item.count,
+                    capability_count: item.capability_count,
+                    threshold: redundantSequenceThreshold,
+                };
+                break;
+            }
+        }
+        if (broadTrigger === null && redundantSequenceCount >= redundantSequenceThreshold) {
+            broadTrigger = {
+                event_class: "raw_artifact_access",
+                artifact_label: "multiple",
+                count: redundantSequenceCount,
+                capability_count: aggregateRedundantCapabilities.size,
+                threshold: redundantSequenceThreshold,
+                aggregate: true,
+            };
+        }
+    }
+    let recommendation;
+    if (broadTrigger !== null) {
+        const trigger = broadTrigger.aggregate
+            ? `redundant_raw_artifact_access in ${broadTrigger.count} of ${args.totalSequences} state sequences`
+            : `raw_artifact_access_after_cli:${broadTrigger.artifact_label} repeated ` +
+                `${broadTrigger.count} times across ${broadTrigger.capability_count} capabilities`;
+        recommendation = {
+            action: "plan_cli_startup_envelope",
+            measured_trigger: trigger,
+            rationale: "Raw artifact access after CLI state exceeded the broad startup-envelope threshold.",
+        };
+    }
+    else if (Object.keys(redundantArtifacts).length > 0) {
+        recommendation = {
+            action: "targeted_capability_guidance_fixes",
+            measured_trigger: "raw_artifact_access_after_cli_hotspot",
+            rationale: "Raw artifact access follows CLI state, but evidence is narrow or below the broad-envelope gate.",
+        };
+    }
+    else {
+        recommendation = {
+            action: "close_without_implementation",
+            measured_trigger: "none",
+            rationale: "No raw artifact access after overlapping CLI state was measured.",
+        };
+    }
+    if (args.confidenceCaveats.includes("insufficient_post_2_3_state_sequences")) {
+        recommendation = {
+            action: "close_without_implementation",
+            measured_trigger: "weak_evidence",
+            rationale: "No post-boundary Agentera state-gathering sequences were available.",
+        };
+    }
+    return {
+        measured_distribution: {
+            raw_after_cli_per_sequence: rawDistribution,
+            redundant_raw_after_cli_per_sequence: redundantDistribution,
+            redundant_sequence_count: redundantSequenceCount,
+            redundant_artifacts: redundantArtifacts,
+            capability_count: capabilityCount,
+        },
+        action_thresholds: {
+            startup_envelope: {
+                credible: credibleDistribution,
+                redundant_sequence_threshold: redundantSequenceThreshold,
+                selection_reason: thresholdReason,
+            },
+            targeted_guidance: {
+                credible: Object.keys(redundantArtifacts).length > 0,
+                selection_reason: "Selected when raw artifact access after CLI state is narrow or below the broad-envelope threshold.",
+            },
+        },
+        recommendation,
+    };
+}
+export function aggregateStartupMetrics(intermediateInput) {
+    const intermediate = intermediateInput && typeof intermediateInput === "object" && !Array.isArray(intermediateInput) ? intermediateInput : {};
+    const sequences = Array.isArray(intermediate.state_gathering_sequences) ? intermediate.state_gathering_sequences : [];
+    const degradations = Array.isArray(intermediate.degradations) ? intermediate.degradations : [];
+    const perCapability = {};
+    const cliCommandCounts = {};
+    const rawAfterCliCounts = {};
+    const redundantRawCounts = {};
+    const rawAfterCliTokenEstimates = {};
+    const redundantRawTokenEstimates = {};
+    const proseCounts = {};
+    const implementationCounts = {};
+    const degradationCounts = {};
+    const redundantCapabilities = {};
+    const rawAfterCliPerSequence = [];
+    const redundantRawPerSequence = [];
+    for (const item of degradations) {
+        if (item && typeof item === "object" && !Array.isArray(item)) {
+            const reason = item.reason;
+            if (typeof reason === "string")
+                inc(degradationCounts, reason);
+        }
+    }
+    for (const sequence of sequences) {
+        if (!sequence || typeof sequence !== "object" || Array.isArray(sequence))
+            continue;
+        let capability = sequence.capability;
+        if (typeof capability !== "string" || !capability)
+            capability = "unknown";
+        if (!(capability in perCapability)) {
+            perCapability[capability] = {
+                state_sequences: 0,
+                cli_state_call: 0,
+                raw_artifact_access_after_cli: 0,
+                redundant_raw_artifact_access: 0,
+                capability_prose_read: 0,
+                implementation_boundary: 0,
+            };
+        }
+        const cc = perCapability[capability];
+        cc.state_sequences += 1;
+        const cliCount = sequenceCount(sequence, "cli_state_call");
+        const rawList = Array.isArray(sequence.raw_artifact_labels_after_cli) ? sequence.raw_artifact_labels_after_cli : [];
+        const redundantList = Array.isArray(sequence.redundant_raw_artifact_labels) ? sequence.redundant_raw_artifact_labels : [];
+        const rawCount = rawList.length;
+        const redundantCount = redundantList.length;
+        const proseCount = sequenceCount(sequence, "capability_prose_read");
+        const implCount = sequenceCount(sequence, "implementation_boundary");
+        cc.cli_state_call += cliCount;
+        cc.raw_artifact_access_after_cli += rawCount;
+        cc.redundant_raw_artifact_access += redundantCount;
+        cc.capability_prose_read += proseCount;
+        cc.implementation_boundary += implCount;
+        proseCounts[capability] = (proseCounts[capability] ?? 0) + proseCount;
+        implementationCounts[capability] = (implementationCounts[capability] ?? 0) + implCount;
+        rawAfterCliPerSequence.push(rawCount);
+        redundantRawPerSequence.push(redundantCount);
+        mergeTokenEstimates(rawAfterCliTokenEstimates, sequence.estimated_raw_after_cli_tokens_by_artifact);
+        mergeTokenEstimates(redundantRawTokenEstimates, sequence.estimated_redundant_raw_tokens_by_artifact);
+        for (const event of Array.isArray(sequence.events) ? sequence.events : []) {
+            if (!event || typeof event !== "object" || Array.isArray(event))
+                continue;
+            const stateCommand = event.state_command;
+            if (event.event_class === "cli_state_call" && typeof stateCommand === "string") {
+                inc(cliCommandCounts, stateCommand);
+            }
+            const label = event.artifact_label;
+            if (event.event_class === "raw_artifact_access" && typeof label === "string") {
+                inc(rawAfterCliCounts, label);
+                if (event.redundant_with_cli === true) {
+                    inc(redundantRawCounts, label);
+                    if (!(label in redundantCapabilities))
+                        redundantCapabilities[label] = new Set();
+                    redundantCapabilities[label].add(capability);
+                }
+            }
+        }
+        for (const reason of Array.isArray(sequence.degradation_reasons) ? sequence.degradation_reasons : []) {
+            if (typeof reason === "string")
+                inc(degradationCounts, reason);
+        }
+    }
+    const totalSequences = sequences.filter((s) => Boolean(s && typeof s === "object" && !Array.isArray(s))).length;
+    const runtimeCoverage = (Array.isArray(intermediate.runtime_coverage) ? intermediate.runtime_coverage : [])
+        .filter((s) => Boolean(s && typeof s === "object" && !Array.isArray(s)))
+        .map((s) => boundedRuntimeStatus(s));
+    const runtimeStatusCounts = {};
+    for (const status of runtimeCoverage) {
+        const st = status.status;
+        if (typeof st === "string")
+            inc(runtimeStatusCounts, st);
+    }
+    const confidenceCaveats = [];
+    if (totalSequences === 0)
+        confidenceCaveats.push("insufficient_post_2_3_state_sequences");
+    if (runtimeCoverage.some((s) => typeof s.status === "string" && ["missing", "sparse", "degraded", "skipped"].includes(s.status))) {
+        confidenceCaveats.push("runtime_coverage_incomplete_or_degraded");
+    }
+    if (Object.keys(degradationCounts).length > 0)
+        confidenceCaveats.push("some_records_or_sequences_degraded");
+    const thresholdDerivation = deriveStateThresholds({
+        totalSequences,
+        perCapability,
+        rawAfterCliPerSequence,
+        redundantRawPerSequence,
+        redundantCounts: redundantRawCounts,
+        redundantCapabilities,
+        confidenceCaveats,
+    });
+    const sequencesWithRaw = rawAfterCliPerSequence.filter((v) => v > 0).length;
+    const sequencesWithRedundant = redundantRawPerSequence.filter((v) => v > 0).length;
+    const recommendation = thresholdDerivation.recommendation && typeof thresholdDerivation.recommendation === "object" && !Array.isArray(thresholdDerivation.recommendation)
+        ? thresholdDerivation.recommendation
+        : {};
+    const sortedPerCapability = {};
+    for (const key of Object.keys(perCapability).sort())
+        sortedPerCapability[key] = perCapability[key];
+    const sumValues = (o) => Object.values(o).reduce((a, b) => a + b, 0);
+    const result = {
+        output_envelope: STARTUP_METRICS_ENVELOPE,
+        input_envelope: intermediate.output_envelope ?? null,
+        contract_version: intermediate.contract_version ?? null,
+        generated_at: nowIsoSeconds(),
+        boundary_source: intermediate.boundary_source ?? null,
+        boundary_commit: intermediate.boundary_commit ?? null,
+        boundary_committed_at: intermediate.boundary_committed_at ?? null,
+        benchmark_mode: intermediate.benchmark_mode || "full_boundary_snapshot",
+        benchmark_previous_watermark_at: intermediate.benchmark_previous_watermark_at ?? null,
+        benchmark_window_started_after: intermediate.benchmark_window_started_after ?? null,
+        benchmark_watermark_at: intermediate.benchmark_watermark_at ?? null,
+        corpus_adapter_version: intermediate.corpus_adapter_version ?? null,
+        runtime_coverage: runtimeCoverage,
+        runtime_status_counts: counterDict(runtimeStatusCounts),
+        runtime_record_counts: intermediate.runtime_record_counts || {},
+        total_records: safeInt(intermediate.total_records_read),
+        total_state_sequences: totalSequences,
+        state_sequences_with_raw_after_cli: sequencesWithRaw,
+        state_sequences_with_redundant_raw_access: sequencesWithRedundant,
+        total_cli_state_calls: sumValues(cliCommandCounts),
+        total_raw_artifact_access_after_cli: sumValues(rawAfterCliCounts),
+        total_redundant_raw_artifact_accesses: sumValues(redundantRawCounts),
+        raw_after_cli_sequence_rate: totalSequences ? flt(pyRound(sequencesWithRaw / totalSequences, 4)) : 0,
+        redundant_raw_sequence_rate: totalSequences ? flt(pyRound(sequencesWithRedundant / totalSequences, 4)) : 0,
+        per_capability_state_counts: sortedPerCapability,
+        cli_state_command_counts: counterDict(cliCommandCounts),
+        raw_artifact_access_after_cli_counts: counterDict(rawAfterCliCounts),
+        redundant_raw_artifact_access_counts: counterDict(redundantRawCounts),
+        token_estimator_version: TOKEN_ESTIMATOR_VERSION,
+        estimated_raw_after_cli_tokens: sumValues(rawAfterCliTokenEstimates),
+        estimated_redundant_raw_tokens: sumValues(redundantRawTokenEstimates),
+        estimated_raw_after_cli_tokens_by_artifact: counterDict(rawAfterCliTokenEstimates),
+        estimated_redundant_raw_tokens_by_artifact: counterDict(redundantRawTokenEstimates),
+        estimated_tokens_saved_vs_previous: null,
+        estimated_tokens_saved_vs_previous_null_reason: "previous_row_missing",
+        capability_prose_read_counts: counterDict(proseCounts),
+        implementation_boundary_counts: counterDict(implementationCounts),
+        degradation_reason_counts: counterDict(degradationCounts),
+        privacy_redaction_summary: {
+            raw_transcript_text: "not_emitted",
+            full_local_paths: "not_emitted",
+            raw_store_paths: "not_emitted",
+            session_ids: "salted_or_not_emitted",
+            artifact_labels: "canonical_only",
+        },
+        confidence_caveats: confidenceCaveats,
+        insufficient_evidence_reason: totalSequences === 0 ? "no_post_2_3_state_sequences" : null,
+        threshold_derivation: thresholdDerivation,
+        startup_recommendation: recommendation,
+        implementation_recommended: recommendation.action === "plan_cli_startup_envelope",
+        compatibility_note: "Section 22 corpus records are read-only; aggregation consumes only startup_state_analysis_v1.",
+    };
+    if (totalSequences) {
+        result.recommendation_gate_input = thresholdDerivation.measured_distribution;
+    }
+    return result;
+}

package/dist/state/startupAnalysis/records.js

@@ -0,0 +1,198 @@
+import { hashLabel, loadContract, parseTimestamp } from "./contract.js";
+import { argumentsText, capabilityInvocation, extractText, introCapability, recordLabel, } from "./helpers.js";
+import { BOUNDARY_DEGRADATION_REASONS, STATE_EVENT_CLASSES, classifyStartupEvent, startupConversationKey, } from "./threshold.js";
+function hasTranscriptBearingField(record) {
+    if ("transcript" in record)
+        return true;
+    const data = record.data;
+    return Boolean(data && typeof data === "object" && !Array.isArray(data) && "transcript" in data);
+}
+function boundedReason(reason, contract) {
+    const reasons = Array.isArray(contract.degradation_reasons) ? contract.degradation_reasons : [];
+    const allowed = new Set([...reasons, ...BOUNDARY_DEGRADATION_REASONS]);
+    return allowed.has(reason) ? reason : "malformed_record";
+}
+function estimatedToolArgumentTokens(record) {
+    return Math.ceil(Buffer.byteLength(argumentsText(record), "utf8") / 4);
+}
+function timestampUtc(value) {
+    return parseTimestamp(value);
+}
+function newSequence(conversationKey, capability, salt) {
+    const counts = {};
+    for (const eventClass of [...STATE_EVENT_CLASSES].sort())
+        counts[eventClass] = 0;
+    return {
+        conversation: hashLabel("session", conversationKey, salt),
+        capability: capability || "unknown",
+        start_anchor: "first_cli_state_call_after_capability_invocation",
+        events: [],
+        counts,
+        cli_artifact_labels: [],
+        raw_artifact_labels_after_cli: [],
+        redundant_raw_artifact_labels: [],
+        estimated_raw_after_cli_tokens_by_artifact: {},
+        estimated_redundant_raw_tokens_by_artifact: {},
+        degradation_reasons: [],
+    };
+}
+function eventOutput(record, opts) {
+    const item = {
+        record: recordLabel(record, opts.salt),
+        event_class: STATE_EVENT_CLASSES.has(opts.eventClass) ? opts.eventClass : "non_state_context",
+        phase: opts.phase,
+    };
+    if (opts.artifactLabel)
+        item.artifact_label = opts.artifactLabel;
+    if (opts.stateCommand)
+        item.state_command = opts.stateCommand;
+    if (opts.redundantWithCli !== undefined && opts.redundantWithCli !== null) {
+        item.redundant_with_cli = opts.redundantWithCli;
+    }
+    return item;
+}
+export function classifyStartupRecords(corpus, opts) {
+    const salt = opts.salt;
+    const loaded = opts.contract ?? loadContract();
+    const boundaryInfo = loaded.boundary && typeof loaded.boundary === "object" && !Array.isArray(loaded.boundary) ? loaded.boundary : {};
+    const boundary = timestampUtc(boundaryInfo.committed_at);
+    const records = corpus && typeof corpus === "object" && !Array.isArray(corpus) ? (corpus.records ?? []) : [];
+    const degradations = [];
+    const groups = new Map();
+    for (const record of Array.isArray(records) ? records : []) {
+        if (!record || typeof record !== "object" || Array.isArray(record)) {
+            degradations.push({ reason: boundedReason("malformed_record", loaded) });
+            continue;
+        }
+        if (hasTranscriptBearingField(record)) {
+            degradations.push({ record: recordLabel(record, salt), reason: "privacy_redaction_required" });
+            continue;
+        }
+        const timestamp = timestampUtc(record.timestamp);
+        if (timestamp === null) {
+            degradations.push({ record: recordLabel(record, salt), reason: "missing_timestamp" });
+            continue;
+        }
+        if (boundary !== null && timestamp.getTime() <= boundary.getTime()) {
+            degradations.push({ record: recordLabel(record, salt), reason: "pre_boundary_record" });
+            continue;
+        }
+        const key = startupConversationKey(record);
+        if (key === null) {
+            degradations.push({ record: recordLabel(record, salt), reason: "missing_conversation_key" });
+            continue;
+        }
+        if (!groups.has(key))
+            groups.set(key, []);
+        groups.get(key).push(record);
+    }
+    const sequences = [];
+    for (const [conversationKey, items] of groups) {
+        items.sort((a, b) => {
+            const ta = String(a.timestamp ?? "");
+            const tb = String(b.timestamp ?? "");
+            return ta < tb ? -1 : ta > tb ? 1 : 0;
+        });
+        const state = {
+            active: null,
+            segmentCapability: null,
+            segmentOpen: false,
+            segmentHadStateSequence: false,
+            cliArtifactsSeen: new Set(),
+        };
+        const closeActive = () => {
+            if (state.active !== null) {
+                state.active.cli_artifact_labels = [...state.cliArtifactsSeen].sort();
+                sequences.push(state.active);
+                state.segmentHadStateSequence = true;
+                state.active = null;
+                state.cliArtifactsSeen = new Set();
+            }
+        };
+        for (const record of items) {
+            const text = extractText(record);
+            const data = record.data && typeof record.data === "object" && !Array.isArray(record.data) ? record.data : {};
+            const actor = data.actor;
+            if (actor === "user") {
+                closeActive();
+                if (state.segmentOpen && !state.segmentHadStateSequence) {
+                    degradations.push({
+                        conversation: hashLabel("session", conversationKey, salt),
+                        reason: "no_agentera_state_sequence",
+                    });
+                }
+                state.segmentCapability = capabilityInvocation(text);
+                state.segmentOpen = state.segmentCapability !== null;
+                state.segmentHadStateSequence = false;
+                continue;
+            }
+            if (!state.segmentOpen) {
+                const introCap = actor === "assistant" ? introCapability(text) : null;
+                if (introCap) {
+                    state.segmentCapability = introCap;
+                    state.segmentOpen = true;
+                }
+                else {
+                    continue;
+                }
+            }
+            const [eventClass, artifactLabel, stateCommand, cliArtifactLabels] = classifyStartupEvent(record);
+            if (eventClass === "non_state_context")
+                continue;
+            if (eventClass === "cli_state_call" && state.active === null) {
+                state.active = newSequence(conversationKey, state.segmentCapability, salt);
+            }
+            if (state.active === null)
+                continue;
+            // cast: state.active is built by newSequence with typed array/counter/estimate fields
+            const active = state.active;
+            if (eventClass === "cli_state_call") {
+                for (const label of cliArtifactLabels)
+                    state.cliArtifactsSeen.add(label);
+            }
+            const redundant = eventClass === "raw_artifact_access" && artifactLabel
+                ? state.cliArtifactsSeen.has(artifactLabel)
+                : null;
+            const phase = eventClass === "implementation_boundary" ? "implementation_boundary" : "state_gathering";
+            active.counts[eventClass] += 1;
+            active.events.push(eventOutput(record, {
+                eventClass,
+                phase,
+                salt,
+                artifactLabel,
+                stateCommand,
+                redundantWithCli: redundant,
+            }));
+            if (eventClass === "raw_artifact_access" && artifactLabel) {
+                active.raw_artifact_labels_after_cli.push(artifactLabel);
+                const estimatedTokens = estimatedToolArgumentTokens(record);
+                const rawEstimates = active.estimated_raw_after_cli_tokens_by_artifact;
+                rawEstimates[artifactLabel] = (rawEstimates[artifactLabel] ?? 0) + estimatedTokens;
+                if (redundant) {
+                    active.redundant_raw_artifact_labels.push(artifactLabel);
+                    const redundantEstimates = active.estimated_redundant_raw_tokens_by_artifact;
+                    redundantEstimates[artifactLabel] = (redundantEstimates[artifactLabel] ?? 0) + estimatedTokens;
+                }
+            }
+            if (eventClass === "implementation_boundary") {
+                closeActive();
+                state.segmentOpen = false;
+                state.segmentCapability = null;
+                state.segmentHadStateSequence = false;
+            }
+        }
+        closeActive();
+        if (state.segmentOpen && !state.segmentHadStateSequence) {
+            degradations.push({
+                conversation: hashLabel("session", conversationKey, salt),
+                reason: "no_agentera_state_sequence",
+            });
+        }
+    }
+    return {
+        contract_version: loaded.version,
+        boundary_source: boundaryInfo.source,
+        state_gathering_sequences: sequences,
+        degradations,
+    };
+}

package/dist/state/startupAnalysis/report.js

@@ -0,0 +1,111 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pyJsonIndentSorted } from "../../core/pyjson.js";
+import { Flt, formatFloat, pyFmt, pyJsonDumps } from "./helpers.js";
+export const STARTUP_REPORT_MARKDOWN = "startup-overhead-report.md";
+export const STARTUP_REPORT_JSON = "startup-overhead-report.json";
+function startupJsonScalar(value) {
+    if (value instanceof Flt)
+        return formatFloat(value.v);
+    return undefined;
+}
+function pyJsonIndent(value, level = 0, indent = "  ") {
+    return pyJsonIndentSorted(value, indent.length || 2, level, startupJsonScalar);
+}
+function markdownTable(headers, rows) {
+    const lines = [
+        "| " + headers.join(" | ") + " |",
+        "| " + headers.map(() => "---").join(" | ") + " |",
+    ];
+    if (rows.length === 0) {
+        return [...lines, "| " + headers.map(() => "none").join(" | ") + " |"];
+    }
+    return [...lines, ...rows.map((row) => "| " + row.map((v) => pyFmt(v)).join(" | ") + " |")];
+}
+export function renderStartupReport(metrics) {
+    const thresholdDerivation = metrics.threshold_derivation && typeof metrics.threshold_derivation === "object" && !Array.isArray(metrics.threshold_derivation)
+        ? metrics.threshold_derivation
+        : {};
+    const threshold = thresholdDerivation.action_thresholds && typeof thresholdDerivation.action_thresholds === "object" && !Array.isArray(thresholdDerivation.action_thresholds)
+        ? thresholdDerivation.action_thresholds
+        : {};
+    const envelopeThreshold = threshold.startup_envelope && typeof threshold.startup_envelope === "object" && !Array.isArray(threshold.startup_envelope) ? threshold.startup_envelope : {};
+    const guidanceThreshold = threshold.targeted_guidance && typeof threshold.targeted_guidance === "object" && !Array.isArray(threshold.targeted_guidance) ? threshold.targeted_guidance : {};
+    const recommendation = metrics.startup_recommendation && typeof metrics.startup_recommendation === "object" && !Array.isArray(metrics.startup_recommendation)
+        ? metrics.startup_recommendation
+        : {};
+    const measuredDistribution = thresholdDerivation.measured_distribution && typeof thresholdDerivation.measured_distribution === "object" && !Array.isArray(thresholdDerivation.measured_distribution)
+        ? thresholdDerivation.measured_distribution
+        : {};
+    const runtimeCoverage = Array.isArray(metrics.runtime_coverage) ? metrics.runtime_coverage : [];
+    const capabilityCounts = metrics.per_capability_state_counts && typeof metrics.per_capability_state_counts === "object" && !Array.isArray(metrics.per_capability_state_counts)
+        ? metrics.per_capability_state_counts
+        : {};
+    const lines = [
+        "# Agentera Startup State-Access Analysis",
+        "",
+        "This report is local-only and privacy-preserving. It measures raw Agentera artifact access after CLI state calls during capability startup/state gathering.",
+        "",
+        "## Boundary Source",
+        "",
+        `- Contract version: \`${pyFmt(metrics.contract_version)}\``,
+        `- Boundary source: \`${pyFmt(metrics.boundary_source)}\``,
+        `- Boundary commit: \`${pyFmt(metrics.boundary_commit)}\``,
+        `- Boundary timestamp: \`${pyFmt(metrics.boundary_committed_at)}\``,
+        `- Corpus adapter version: \`${pyFmt(metrics.corpus_adapter_version)}\``,
+        "",
+        "## Benchmark Window",
+        "",
+        `- Mode: \`${pyFmt(metrics.benchmark_mode)}\``,
+        `- Previous watermark: \`${pyFmt(metrics.benchmark_previous_watermark_at)}\``,
+        `- Window started after: \`${pyFmt(metrics.benchmark_window_started_after)}\``,
+        `- Watermark: \`${pyFmt(metrics.benchmark_watermark_at)}\``,
+        "",
+        "## Runtime Coverage",
+        "",
+    ];
+    const runtimeRows = [];
+    for (const status of runtimeCoverage) {
+        if (status && typeof status === "object" && !Array.isArray(status)) {
+            runtimeRows.push([
+                status.runtime ?? "unknown",
+                status.status ?? "unknown",
+                status.reason ?? "unknown",
+                status.record_count ?? 0,
+                status.file_count ?? 0,
+                status.error_count ?? 0,
+            ]);
+        }
+    }
+    lines.push(...markdownTable(["Runtime", "Status", "Reason", "Records", "Files", "Errors"], runtimeRows));
+    lines.push("", "## Metrics", "", `- Total state-gathering sequences: \`${pyFmt(metrics.total_state_sequences)}\``, `- Sequences with raw artifact access after CLI: \`${pyFmt(metrics.state_sequences_with_raw_after_cli)}\``, `- Sequences with redundant raw artifact access: \`${pyFmt(metrics.state_sequences_with_redundant_raw_access)}\``, `- Raw-after-CLI sequence rate: \`${pyFmt(metrics.raw_after_cli_sequence_rate)}\``, `- Redundant raw sequence rate: \`${pyFmt(metrics.redundant_raw_sequence_rate)}\``, `- CLI state command counts: \`${pyJsonDumps(metrics.cli_state_command_counts ?? {})}\``, `- Raw artifact access after CLI counts: \`${pyJsonDumps(metrics.raw_artifact_access_after_cli_counts ?? {})}\``, `- Redundant raw artifact access counts: \`${pyJsonDumps(metrics.redundant_raw_artifact_access_counts ?? {})}\``, "", "## Estimated Token Impact", "", `- Token estimator version: \`${pyFmt(metrics.token_estimator_version)}\``, `- Estimated raw-after-CLI tokens: \`${pyFmt(metrics.estimated_raw_after_cli_tokens)}\``, `- Estimated redundant raw tokens: \`${pyFmt(metrics.estimated_redundant_raw_tokens)}\``, `- Estimated raw-after-CLI tokens by artifact: \`${pyJsonDumps(metrics.estimated_raw_after_cli_tokens_by_artifact ?? {})}\``, `- Estimated redundant raw tokens by artifact: \`${pyJsonDumps(metrics.estimated_redundant_raw_tokens_by_artifact ?? {})}\``, `- Estimated tokens saved vs previous: \`${pyFmt(metrics.estimated_tokens_saved_vs_previous)}\``, `- Estimated tokens saved null reason: \`${pyFmt(metrics.estimated_tokens_saved_vs_previous_null_reason)}\``, "");
+    const capabilityRows = [];
+    for (const capability of Object.keys(capabilityCounts).sort()) {
+        const counts = capabilityCounts[capability];
+        if (counts && typeof counts === "object" && !Array.isArray(counts)) {
+            capabilityRows.push([
+                capability,
+                counts.state_sequences ?? 0,
+                counts.cli_state_call ?? 0,
+                counts.raw_artifact_access_after_cli ?? 0,
+                counts.redundant_raw_artifact_access ?? 0,
+                counts.capability_prose_read ?? 0,
+            ]);
+        }
+    }
+    lines.push(...markdownTable(["Capability", "Sequences", "CLI Calls", "Raw After CLI", "Redundant Raw", "Prose Reads"], capabilityRows));
+    lines.push("", "## Threshold Rationale", "", `- Startup envelope threshold credible: \`${pyFmt(envelopeThreshold.credible)}\``, `- Redundant-sequence threshold: \`${pyFmt(envelopeThreshold.redundant_sequence_threshold)}\``, `- Startup envelope selection reason: ${pyFmt(envelopeThreshold.selection_reason)}`, `- Targeted-guidance selection reason: ${pyFmt(guidanceThreshold.selection_reason)}`, `- Measured distribution: \`${pyJsonDumps(measuredDistribution)}\``, "", "## Recommendation", "", `- Action: \`${pyFmt(recommendation.action)}\``, `- Measured trigger: \`${pyFmt(recommendation.measured_trigger)}\``, `- Rationale: ${pyFmt(recommendation.rationale)}`, `- Implementation recommended: \`${pyFmt(metrics.implementation_recommended)}\``, "", "## Privacy Caveats", "", "- Raw transcript text is not emitted.", "- Full local paths and raw store paths are not emitted.", "- Session identifiers are salted or omitted.", "- Raw artifact accesses use canonical artifact_id labels such as `plan`, not filesystem paths.", "- Runtime coverage may be incomplete or degraded; inspect `confidence_caveats` before selecting follow-up work.", "");
+    return lines.join("\n");
+}
+export function writeStartupReports(metrics, outputDir) {
+    fs.mkdirSync(outputDir, { recursive: true });
+    const jsonPath = path.join(outputDir, STARTUP_REPORT_JSON);
+    const markdownPath = path.join(outputDir, STARTUP_REPORT_MARKDOWN);
+    fs.writeFileSync(jsonPath, pyJsonIndent(metrics) + "\n");
+    fs.writeFileSync(markdownPath, renderStartupReport(metrics));
+    return { structured: jsonPath, human_readable: markdownPath };
+}
+// ===========================================================================
+// Slice 6: benchmark persistence + intermediate building + corpus-file extraction
+// (extract_*_from_runtime_stores depends on extract_corpus and lands in Phase 10)
+// ===========================================================================