@compaction/cli 0.1.0

package/dist/core/session-aggregate.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Session + multi-session LOCAL aggregate (Strong-MVP Track E).
+ *
+ * Rolls up the per-run artifacts a developer already produced —
+ * `.compaction/runs/<run>/report.json` and (when present) `strong-eval.json` plus an
+ * optional local `run-labels.json` — into:
+ *   - a PER-SESSION summary (a session may contain multiple runs), and
+ *   - a CROSS-SESSION aggregate (totals across every session/run).
+ *
+ * This is the future admin/buyer value WITHOUT a hosted dashboard: everything is LOCAL,
+ * file-based, read-only over existing artifacts. NO network, NO upload, NO telemetry,
+ * NO database, NO auth, NO server.
+ *
+ * EVIDENCE HONESTY (mvp-capability-matrix rows 2/3/10/13/21, README evidence ladder):
+ *   - Token figures carry their per-figure source: provider-reported ONLY when the run's
+ *     token accounting was `measured` (provider usage metadata present); otherwise
+ *     local-estimate (chars/4). The aggregate states how many runs are in each tier and
+ *     NEVER labels an estimate as provider-reported.
+ *   - Cost / savings are ESTIMATED (price-table over the token figures). NEVER
+ *     billing-confirmed, NEVER realized, NEVER extrapolated to a time period.
+ *   - Output tokens are carried only where a run actually recorded them (from
+ *     strong-eval token_accounting); runs without strong-eval contribute `unknown`
+ *     output tokens and are counted separately, never inferred.
+ *   - Verification outcome counts (ready/conditional/not_ready, recoverability /
+ *     commitment / task-check pass/fail) are copied from strong-eval; runs without a
+ *     strong-eval are counted as `not_evaluated`, never as a pass.
+ *
+ * The builders are PURE (no IO) so the rollup math, label tagging, and the content-free
+ * share bundle are unit-testable; the reader (`collectRunRecords`) does the only IO and
+ * touches nothing but local files.
+ */
+import { type RunLabels } from "./run-labels.js";
+import type { CompactionReport } from "./types.js";
+export declare const AGGREGATE_ARTIFACT_DIRECTORY = ".compaction/aggregates";
+/** Evidence tier of a run's TOKEN figures (kept distinct from operator-asserted provider labels). */
+export type RunTokenEvidence = "provider_reported" | "local_estimate" | "unknown";
+/** Verification outcome of a run, copied from strong-eval (or not_evaluated when absent). */
+export type VerificationReadiness = "ready" | "conditional" | "not_ready" | "not_evaluated";
+export type CheckOutcome = "pass" | "fail" | "unsupported" | "not_evaluated";
+/**
+ * One normalized run record assembled from a run directory's local artifacts. The ONLY
+ * fields carried are bounded numbers / enums / short label strings — never trace content.
+ */
+export interface RunRecord {
+    run_id: string;
+    run_directory: string;
+    report_path: string;
+    model: string;
+    /** Token evidence tier for this run (drives the provider-reported vs local-estimate split). */
+    token_evidence: RunTokenEvidence;
+    input_tokens_before: number;
+    input_tokens_after: number;
+    input_tokens_saved: number;
+    /** Output tokens where the run recorded them (strong-eval token_accounting); else unknown. */
+    output_tokens_before: number | "unknown";
+    output_tokens_after: number | "unknown";
+    estimated_cost_before_usd: number;
+    estimated_cost_after_usd: number;
+    estimated_saving_usd: number;
+    /** Verification outcomes (not_evaluated when no strong-eval.json was present). */
+    readiness: VerificationReadiness;
+    recoverability: CheckOutcome;
+    commitment_preservation: CheckOutcome;
+    task_check: CheckOutcome;
+    /** Whether a strong-eval.json was present for this run. */
+    strong_eval_present: boolean;
+    /** Local-only labels (project/workflow/provider/user_label/session). */
+    labels: RunLabels;
+    /** Notes about partial/missing artifacts for this run (honest provenance). */
+    notes: string[];
+}
+export interface SkippedRunDirectory {
+    run_directory: string;
+    reason: string;
+}
+/** Aggregated token/cost/savings totals over a set of runs, with the evidence split. */
+export interface AggregateTotals {
+    run_count: number;
+    /** Token-evidence split: how many runs contributed provider-reported vs local-estimate figures. */
+    runs_provider_reported: number;
+    runs_local_estimate: number;
+    runs_unknown_token_evidence: number;
+    total_input_tokens_before: number;
+    total_input_tokens_after: number;
+    total_input_tokens_saved: number;
+    /** Output tokens summed ONLY over runs that recorded them; unknown for the rest. */
+    total_output_tokens_before: number;
+    total_output_tokens_after: number;
+    runs_with_output_tokens: number;
+    runs_without_output_tokens: number;
+    /** Estimated spend/savings (price-table; NOT billing-confirmed, NOT realized, NOT extrapolated). */
+    total_estimated_cost_before_usd: number;
+    total_estimated_cost_after_usd: number;
+    total_estimated_savings_usd: number;
+    /** Number of compactions = number of recorded runs rolled up (each run is one compaction). */
+    compactions: number;
+}
+export interface VerificationCounts {
+    /** Readiness verdict counts. */
+    ready: number;
+    conditional: number;
+    not_ready: number;
+    not_evaluated: number;
+    /** Per-axis recoverability check counts. */
+    recoverability_pass: number;
+    recoverability_fail: number;
+    recoverability_not_evaluated: number;
+    /** Per-axis commitment-preservation check counts. */
+    commitment_pass: number;
+    commitment_fail: number;
+    commitment_not_evaluated: number;
+    /** Per-axis fixture task-check counts. */
+    task_check_pass: number;
+    task_check_fail: number;
+    task_check_unsupported: number;
+    task_check_not_evaluated: number;
+}
+export interface BreakdownBucket {
+    key: string;
+    totals: AggregateTotals;
+    verification: VerificationCounts;
+}
+export interface SessionSummary {
+    session_id: string;
+    /** True when the session id came from an explicit local `session` label (vs run-id fallback). */
+    explicit_session_label: boolean;
+    run_ids: string[];
+    /** Distinct local labels observed across the session's runs. */
+    labels: {
+        projects: string[];
+        workflows: string[];
+        providers: string[];
+        user_labels: string[];
+    };
+    totals: AggregateTotals;
+    verification: VerificationCounts;
+}
+export interface AggregateReport {
+    aggregate_id: string;
+    generated_at: string;
+    source_glob: string;
+    /** Local-only label filters applied to this rollup (empty when none). */
+    applied_filters: RunLabels;
+    /** Operator-supplied provenance labels for THIS rollup (who/what produced it). Local only. */
+    rollup_labels: RunLabels;
+    session_count: number;
+    totals: AggregateTotals;
+    verification: VerificationCounts;
+    sessions: SessionSummary[];
+    /** Provider/runtime breakdown (operator-asserted provider label; unlabeled when absent). */
+    by_provider: BreakdownBucket[];
+    /** Project breakdown (local label). */
+    by_project: BreakdownBucket[];
+    /** Workflow breakdown (local label). */
+    by_workflow: BreakdownBucket[];
+    skipped_run_directories: SkippedRunDirectory[];
+    evidence_labels: AggregateEvidenceLabels;
+    limitations: string[];
+}
+/** The explicit per-field evidence labels, surfaced in the artifact so no figure is unlabeled. */
+export interface AggregateEvidenceLabels {
+    input_tokens: string;
+    output_tokens: string;
+    estimated_cost: string;
+    estimated_savings: string;
+    compactions: string;
+    verification: string;
+    provider_runtime: string;
+}
+export declare const AGGREGATE_EVIDENCE_LABELS: AggregateEvidenceLabels;
+/** True when a run passes every supplied local-label filter (case-sensitive exact match). */
+export declare function runMatchesFilters(run: RunRecord, filters: RunLabels): boolean;
+export interface BuildAggregateOptions {
+    generatedAt?: string;
+    sourceGlob?: string;
+    /** Local-only label filters: only runs matching ALL supplied fields are rolled up. */
+    filters?: RunLabels;
+    /** Operator provenance labels for this rollup (who/what produced it). Local only. */
+    rollupLabels?: RunLabels;
+    skippedRunDirectories?: SkippedRunDirectory[];
+}
+/**
+ * PURE rollup: fold a set of normalized run records into the per-session + cross-session
+ * aggregate report. No IO. Applies the supplied local-label filters first.
+ */
+export declare function buildAggregateReport(runs: RunRecord[], options?: BuildAggregateOptions): AggregateReport;
+/**
+ * Assemble a normalized RunRecord from a run directory's local artifacts. report.json is
+ * REQUIRED (skipped otherwise). strong-eval.json and run-labels.json are OPTIONAL: absence
+ * is recorded honestly (not_evaluated verification, unknown output tokens), never inferred.
+ */
+export declare function assembleRunRecord(input: {
+    runId: string;
+    runDirectory: string;
+    reportPath: string;
+    report: CompactionReport;
+    strongEval: unknown;
+    labels: RunLabels;
+}): RunRecord;
+/**
+ * Read every run directory under `runsDirectory`, assembling one RunRecord per directory that
+ * carries a valid report.json. The ONLY IO path. Reads exclusively local files; makes NO
+ * network call. Directories without a valid report.json are recorded as skipped, never dropped
+ * silently.
+ */
+export declare function collectRunRecords(runsDirectory?: string): Promise<{
+    runs: RunRecord[];
+    skipped: SkippedRunDirectory[];
+}>;
+/** Read records + build the report in one call (local IO + pure rollup). */
+export declare function createAggregateReport(runsDirectory?: string, options?: Omit<BuildAggregateOptions, "skippedRunDirectories">): Promise<AggregateReport>;