@compaction/cli 0.1.0

package/dist/core/api-client/config.js

@@ -0,0 +1,44 @@
+/**
+ * Compaction API client — configuration (PUBLIC CLI/SDK code).
+ *
+ * Reads env ONLY. Persists NOTHING. The default URL is the LOCAL-DEV server
+ * (`127.0.0.1`); there is no remote URL baked into the public package. The API key
+ * (when set) is attached as a bearer token at call time and is NEVER persisted, logged,
+ * or printed. See `docs/ops/cli-api-client-design.md` §1.
+ */
+/** Local-dev default. Deliberately NOT a remote URL — a fresh checkout talks to a LOCAL server. */
+export const DEFAULT_API_URL = "http://127.0.0.1:8787";
+/** Default per-request timeout. Override with `COMPACTION_API_TIMEOUT_MS`. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+function stripTrailingSlash(url) {
+    return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+/**
+ * Resolve API config from the environment. Pure: same env in → same config out. Never reads
+ * or writes any file and never mutates the env.
+ *
+ *  - `COMPACTION_API_URL`     → base URL (default LOCAL `127.0.0.1:8787`).
+ *  - `COMPACTION_API_KEY`     → optional bearer token (unset by default).
+ *  - `COMPACTION_API_TIMEOUT_MS` → optional positive integer timeout.
+ */
+export function resolveApiConfig(env = process.env) {
+    const rawUrl = (env.COMPACTION_API_URL ?? "").trim();
+    const url = stripTrailingSlash(rawUrl === "" ? DEFAULT_API_URL : rawUrl);
+    const rawKey = (env.COMPACTION_API_KEY ?? "").trim();
+    const apiKey = rawKey === "" ? undefined : rawKey;
+    const rawTimeout = (env.COMPACTION_API_TIMEOUT_MS ?? "").trim();
+    const parsedTimeout = Number.parseInt(rawTimeout, 10);
+    const timeoutMs = Number.isFinite(parsedTimeout) && parsedTimeout > 0 ? parsedTimeout : DEFAULT_TIMEOUT_MS;
+    return { url, apiKey, timeoutMs };
+}
+/**
+ * Build request headers. The API key (when present) is attached as a bearer token. Returns a
+ * fresh object each call; the key is never stored elsewhere.
+ */
+export function buildHeaders(config) {
+    const headers = { "content-type": "application/json" };
+    if (config.apiKey)
+        headers.authorization = `Bearer ${config.apiKey}`;
+    return headers;
+}
+//# sourceMappingURL=config.js.map

package/dist/core/api-client/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Compaction API client — public surface (PUBLIC CLI/SDK code).
+ *
+ * Reference implementation of `docs/ops/cli-api-client-design.md` (Track E). It is the typed
+ * boundary the public CLI uses to talk to the private Compaction API over the documented HTTP
+ * contract ONLY. It imports NOTHING from `src/engine`, makes NO call at import time, and never
+ * auto-uploads. It is NOT wired into any free command; an API call happens only when a caller
+ * explicitly invokes `apiStatus` / `sendRequest`.
+ */
+export { DEFAULT_API_URL, DEFAULT_TIMEOUT_MS, resolveApiConfig, buildHeaders, type ApiConfig, type EnvLike } from "./config.js";
+export { isContentBearing, ConsentError, buildOptimizeRequest, buildEvaluateRequest, buildReportsRequest, previewPayload, type OptimizeBuildOptions, type EvaluateBuildOptions, type ReportsBuildOptions, type PayloadPreview } from "./payload.js";
+export { apiStatus, sendRequest, ApiNotConfirmedError, ApiTransportError, type ApiResponse, type SendOptions } from "./client.js";
+export { CONTENT_BEARING_PAYLOAD_CLASSES, type PayloadClass, type TokenSource, type Consent, type Trace, type TokenUsage, type OptimizeRequest, type EvaluateRequest, type ReportsRequest, type ApiRequestBody, type StatusResponse, type ApiErrorBody } from "./types.js";

package/dist/core/api-client/index.js

@@ -0,0 +1,14 @@
+/**
+ * Compaction API client — public surface (PUBLIC CLI/SDK code).
+ *
+ * Reference implementation of `docs/ops/cli-api-client-design.md` (Track E). It is the typed
+ * boundary the public CLI uses to talk to the private Compaction API over the documented HTTP
+ * contract ONLY. It imports NOTHING from `src/engine`, makes NO call at import time, and never
+ * auto-uploads. It is NOT wired into any free command; an API call happens only when a caller
+ * explicitly invokes `apiStatus` / `sendRequest`.
+ */
+export { DEFAULT_API_URL, DEFAULT_TIMEOUT_MS, resolveApiConfig, buildHeaders } from "./config.js";
+export { isContentBearing, ConsentError, buildOptimizeRequest, buildEvaluateRequest, buildReportsRequest, previewPayload } from "./payload.js";
+export { apiStatus, sendRequest, ApiNotConfirmedError, ApiTransportError } from "./client.js";
+export { CONTENT_BEARING_PAYLOAD_CLASSES } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/core/api-client/payload.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Compaction API client — payload builders + preview (PUBLIC CLI/SDK code).
+ *
+ * Pure functions: artifact + options → a typed request body. NO network, NO engine import.
+ * Builders fail CLOSED: a content-bearing payload class requires explicit upload consent, and
+ * inline raw (non-redacted) content requires consent too — mirroring the server's
+ * `enforceConsent`. The preview shows EXACTLY what would be sent (API key redacted), so the
+ * user never sends blind. See `docs/ops/cli-api-client-design.md` §3–§5.
+ */
+import { type EvaluateRequest, type OptimizeRequest, type PayloadClass, type ReportsRequest, type Trace } from "./types.js";
+/** True when a class carries raw-or-sanitized message CONTENT (requires explicit consent). */
+export declare function isContentBearing(payloadClass: PayloadClass | undefined): boolean;
+/** Thrown by a builder when consent rules are violated. The client must fail closed. */
+export declare class ConsentError extends Error {
+    constructor(message: string);
+}
+/**
+ * Inspect a built/hand-built request body and report whether it ACTUALLY carries inline raw
+ * (non-redacted) content in ANY content-bearing field — independent of the declared
+ * `payload_class`. This is the source of truth the client uses to fail closed: the consent gate
+ * must be driven by what the body CONTAINS, not by its label. Content is considered "raw" (and
+ * therefore consent-requiring) unless it is explicitly marked redacted on its own trace.
+ *
+ * Content-bearing fields across the v0 contract:
+ *  - `trace.content`            (optimize)
+ *  - `original_trace.content`   (evaluate)
+ *  - `compacted_context.content`(evaluate — trace-derived)
+ */
+export declare function bodyContainsInlineContent(body: Record<string, unknown>): boolean;
+export interface OptimizeBuildOptions {
+    trace: Trace;
+    uploadPermitted?: boolean;
+    payloadClass?: PayloadClass;
+    tokenSource?: OptimizeRequest["token_usage"]["source"];
+    inputTokens?: number;
+    outputTokens?: number;
+    provider?: string;
+    runtime?: string;
+    labels?: {
+        project?: string;
+        session?: string;
+    };
+    optimizationMode?: OptimizeRequest["optimization_mode"];
+}
+/** Build a `POST /v0/optimize` body. Fails closed on a content-bearing class without consent. */
+export declare function buildOptimizeRequest(opts: OptimizeBuildOptions): OptimizeRequest;
+export interface EvaluateBuildOptions {
+    originalTrace: Trace;
+    compactedContext: {
+        content?: Record<string, unknown>;
+        reference?: string;
+    };
+    uploadPermitted?: boolean;
+    payloadClass?: PayloadClass;
+    evidenceRequirements?: EvaluateRequest["evidence_requirements"];
+}
+/** Build a `POST /v0/evaluate` body. Fails closed on a content-bearing class without consent. */
+export declare function buildEvaluateRequest(opts: EvaluateBuildOptions): EvaluateRequest;
+export interface ReportsBuildOptions {
+    reportBundle: ReportsRequest["report_bundle"];
+    uploadPermitted?: boolean;
+    payloadClass?: PayloadClass;
+    labels?: {
+        team?: string;
+        project?: string;
+    };
+}
+/** Build a `POST /v0/reports` body. A report bundle is metrics/structure; consent still applies if a content-bearing class is declared. */
+export declare function buildReportsRequest(opts: ReportsBuildOptions): ReportsRequest;
+export interface PayloadPreview {
+    /** The HTTP method + path that would be hit. */
+    endpoint: string;
+    /** The resolved base URL the request would go to. */
+    url: string;
+    /** The declared payload class. */
+    payloadClass: PayloadClass;
+    /** Whether the body carries message content. */
+    contentIncluded: boolean;
+    /** A short human-readable description of what is / is NOT included. */
+    summary: string;
+    /** The EXACT JSON body that would be sent, with any API key redacted. */
+    body: Record<string, unknown>;
+    /** On-wire byte size of the serialized body. */
+    byteSize: number;
+}
+/**
+ * Produce a payload preview: exactly what would be sent (the API key is NOT part of the body
+ * and never appears here), plus a plain-language summary and byte size. This is the contract
+ * the user sees before any send and is identical to the real body.
+ */
+export declare function previewPayload(method: string, path: string, url: string, body: {
+    payload_class?: PayloadClass;
+} & Record<string, unknown>): PayloadPreview;

package/dist/core/api-client/payload.js

@@ -0,0 +1,180 @@
+/**
+ * Compaction API client — payload builders + preview (PUBLIC CLI/SDK code).
+ *
+ * Pure functions: artifact + options → a typed request body. NO network, NO engine import.
+ * Builders fail CLOSED: a content-bearing payload class requires explicit upload consent, and
+ * inline raw (non-redacted) content requires consent too — mirroring the server's
+ * `enforceConsent`. The preview shows EXACTLY what would be sent (API key redacted), so the
+ * user never sends blind. See `docs/ops/cli-api-client-design.md` §3–§5.
+ */
+import { CONTENT_BEARING_PAYLOAD_CLASSES } from "./types.js";
+/** True when a class carries raw-or-sanitized message CONTENT (requires explicit consent). */
+export function isContentBearing(payloadClass) {
+    return payloadClass !== undefined && CONTENT_BEARING_PAYLOAD_CLASSES.has(payloadClass);
+}
+/** Thrown by a builder when consent rules are violated. The client must fail closed. */
+export class ConsentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConsentError";
+    }
+}
+/** True when an inline-content field is present and NON-empty (i.e. actually carries content). */
+function hasInlineContent(content) {
+    return (typeof content === "object" &&
+        content !== null &&
+        !Array.isArray(content) &&
+        Object.keys(content).length > 0);
+}
+/**
+ * Inspect a built/hand-built request body and report whether it ACTUALLY carries inline raw
+ * (non-redacted) content in ANY content-bearing field — independent of the declared
+ * `payload_class`. This is the source of truth the client uses to fail closed: the consent gate
+ * must be driven by what the body CONTAINS, not by its label. Content is considered "raw" (and
+ * therefore consent-requiring) unless it is explicitly marked redacted on its own trace.
+ *
+ * Content-bearing fields across the v0 contract:
+ *  - `trace.content`            (optimize)
+ *  - `original_trace.content`   (evaluate)
+ *  - `compacted_context.content`(evaluate — trace-derived)
+ */
+export function bodyContainsInlineContent(body) {
+    const trace = body.trace;
+    if (trace && hasInlineContent(trace.content) && trace.redacted !== true)
+        return true;
+    const originalTrace = body.original_trace;
+    if (originalTrace && hasInlineContent(originalTrace.content) && originalTrace.redacted !== true) {
+        return true;
+    }
+    // Compacted context is trace-derived; it carries no independent `redacted` flag, so any inline
+    // content here counts as raw trace-derived content for consent purposes.
+    const compacted = body.compacted_context;
+    if (compacted && hasInlineContent(compacted.content))
+        return true;
+    return false;
+}
+/**
+ * Shared consent enforcement (client-side mirror of `apps/api` `enforceConsent`). Fail closed:
+ *  - a content-bearing `payload_class` requires `consent.upload_permitted === true`;
+ *  - inline raw (non-redacted) `trace.content` requires consent too.
+ * Content-free classes / redacted inline content / reference-only payloads need no consent.
+ */
+function assertConsent(consent, payloadClass, trace) {
+    const uploadPermitted = consent.upload_permitted === true;
+    if (isContentBearing(payloadClass) && !uploadPermitted) {
+        throw new ConsentError(`consent_required: payload_class "${payloadClass}" carries content and may not be ` +
+            "sent unless upload is explicitly permitted. Use a metrics_only/redacted_structure " +
+            "payload, or pass the upload-permitted flag.");
+    }
+    if (trace && trace.content !== undefined && trace.redacted !== true && !uploadPermitted) {
+        throw new ConsentError("consent_required: inline raw trace.content may not be sent unless upload is explicitly " +
+            "permitted (or the trace is redacted). Send a redacted trace or a reference instead.");
+    }
+}
+/** Build a `POST /v0/optimize` body. Fails closed on a content-bearing class without consent. */
+export function buildOptimizeRequest(opts) {
+    const payloadClass = opts.payloadClass ?? "metrics_only";
+    const consent = {
+        upload_permitted: opts.uploadPermitted === true,
+        redacted: opts.trace.redacted === true
+    };
+    // For content-free classes, NEVER attach inline content even if the caller passed it.
+    const trace = isContentBearing(payloadClass)
+        ? opts.trace
+        : { redacted: opts.trace.redacted, reference: opts.trace.reference };
+    assertConsent(consent, payloadClass, trace);
+    const req = {
+        trace,
+        consent,
+        payload_class: payloadClass,
+        token_usage: {
+            source: opts.tokenSource ?? "local-estimate",
+            ...(opts.inputTokens !== undefined ? { input_tokens: opts.inputTokens } : {}),
+            ...(opts.outputTokens !== undefined ? { output_tokens: opts.outputTokens } : {})
+        },
+        optimization_mode: opts.optimizationMode ?? "recommend"
+    };
+    if (opts.provider || opts.runtime) {
+        req.provider_metadata = {
+            ...(opts.provider ? { provider: opts.provider } : {}),
+            ...(opts.runtime ? { runtime: opts.runtime } : {})
+        };
+    }
+    if (opts.labels)
+        req.labels = opts.labels;
+    return req;
+}
+/** Build a `POST /v0/evaluate` body. Fails closed on a content-bearing class without consent. */
+export function buildEvaluateRequest(opts) {
+    const payloadClass = opts.payloadClass ?? "metrics_only";
+    const consent = {
+        upload_permitted: opts.uploadPermitted === true,
+        redacted: opts.originalTrace.redacted === true
+    };
+    const contentBearing = isContentBearing(payloadClass);
+    // For content-free classes, NEVER attach inline content from ANY source — not the original
+    // trace AND not the compacted context (which is trace-derived). A content-free class must
+    // carry zero inline content regardless of which field the caller populated. Strip everything
+    // except references, so the declared class is TRUE to the actual body.
+    const originalTrace = contentBearing
+        ? opts.originalTrace
+        : { redacted: opts.originalTrace.redacted, reference: opts.originalTrace.reference };
+    const compactedContext = contentBearing
+        ? opts.compactedContext
+        : { reference: opts.compactedContext.reference };
+    assertConsent(consent, payloadClass, originalTrace);
+    const req = {
+        original_trace: originalTrace,
+        compacted_context: compactedContext,
+        consent,
+        payload_class: payloadClass
+    };
+    if (opts.evidenceRequirements)
+        req.evidence_requirements = opts.evidenceRequirements;
+    return req;
+}
+/** Build a `POST /v0/reports` body. A report bundle is metrics/structure; consent still applies if a content-bearing class is declared. */
+export function buildReportsRequest(opts) {
+    const payloadClass = opts.payloadClass ?? "metrics_only";
+    const consent = {
+        upload_permitted: opts.uploadPermitted === true,
+        redacted: opts.reportBundle.redacted === true
+    };
+    assertConsent(consent, payloadClass, undefined);
+    const req = {
+        report_bundle: opts.reportBundle,
+        consent,
+        payload_class: payloadClass
+    };
+    if (opts.labels)
+        req.labels = opts.labels;
+    return req;
+}
+const CONTENT_SUMMARY = {
+    metrics_only: "metrics only — NO message content",
+    redacted_structure: "structure/roles/ids — message content REMOVED",
+    sanitized_snippets: "sanitized snippets — partial message CONTENT included",
+    full_trace: "FULL message content included"
+};
+/**
+ * Produce a payload preview: exactly what would be sent (the API key is NOT part of the body
+ * and never appears here), plus a plain-language summary and byte size. This is the contract
+ * the user sees before any send and is identical to the real body.
+ */
+export function previewPayload(method, path, url, body) {
+    const payloadClass = (body.payload_class ?? "metrics_only");
+    const serialized = JSON.stringify(body);
+    return {
+        endpoint: `${method} ${path}`,
+        url,
+        payloadClass,
+        // Report what the body ACTUALLY carries, not just its declared class — a
+        // mislabeled content-free body that still contains inline content must preview
+        // as content-included (and will be rejected by sendRequest before any fetch).
+        contentIncluded: isContentBearing(payloadClass) || bodyContainsInlineContent(body),
+        summary: CONTENT_SUMMARY[payloadClass],
+        body,
+        byteSize: Buffer.byteLength(serialized, "utf8")
+    };
+}
+//# sourceMappingURL=payload.js.map

package/dist/core/api-client/types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Compaction API client — wire types (PUBLIC CLI/SDK code).
+ *
+ * OPEN-CORE BOUNDARY: this module is part of the PUBLIC `@compaction/cli` package and
+ * ships in the published tarball. It MUST NOT import anything from `src/engine` and MUST
+ * NOT import the private `apps/api` package. It mirrors — by hand, with no cross-package
+ * import — the request/response SHAPES defined in `apps/api/src/schemas.ts` and the contract
+ * in `docs/api/compaction-api-v0.md`. The client speaks only the documented HTTP contract.
+ *
+ * Keeping these types LOCAL (rather than importing the `apps/api` zod schemas) is deliberate:
+ * it guarantees the public package has zero build/runtime coupling to the server package or
+ * the engine. The local-stub tests assert the shapes still line up with the live contract.
+ *
+ * See `docs/ops/cli-api-client-design.md` (Track E) and `docs/ops/api-command-ux.md` (Track F).
+ */
+/** Payload classes (mirror of `apps/api` `PayloadClassSchema`). */
+export type PayloadClass = "metrics_only" | "redacted_structure" | "sanitized_snippets" | "full_trace";
+/** Classes that carry raw-or-sanitized CONTENT and therefore require explicit upload consent. */
+export declare const CONTENT_BEARING_PAYLOAD_CLASSES: ReadonlySet<PayloadClass>;
+/** Honest token-source labels (mirror of `apps/api` `TokenSourceSchema`). Never upgraded. */
+export type TokenSource = "provider-reported" | "local-estimate" | "unknown";
+export interface Consent {
+    upload_permitted: boolean;
+    redacted: boolean;
+}
+export interface Trace {
+    redacted: boolean;
+    content?: Record<string, unknown>;
+    reference?: string;
+}
+export interface TokenUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    source: TokenSource;
+}
+export interface OptimizeRequest {
+    trace: Trace;
+    consent: Consent;
+    payload_class?: PayloadClass;
+    provider_metadata?: {
+        provider?: string;
+        runtime?: string;
+    };
+    token_usage: TokenUsage;
+    evidence_labels?: Record<string, unknown>;
+    labels?: {
+        project?: string;
+        session?: string;
+    };
+    optimization_mode: "recommend" | "compact" | "apply-ready";
+}
+export interface EvaluateRequest {
+    original_trace: Trace;
+    compacted_context: {
+        content?: Record<string, unknown>;
+        reference?: string;
+    };
+    consent: Consent;
+    payload_class?: PayloadClass;
+    evidence_requirements?: {
+        require_recoverability?: boolean;
+        require_commitment_preservation?: boolean;
+        require_task_replay?: boolean;
+    };
+}
+export interface ReportsRequest {
+    report_bundle: {
+        runs?: Array<Record<string, unknown>>;
+        summary?: Record<string, unknown>;
+        redacted: boolean;
+    };
+    labels?: {
+        team?: string;
+        project?: string;
+    };
+    consent: Consent;
+    payload_class?: PayloadClass;
+}
+/** Any payload-bearing request body (carries `consent` + optional `payload_class`). */
+export type ApiRequestBody = OptimizeRequest | EvaluateRequest | ReportsRequest;
+/** `GET /v0/status` response (honest local-engine-dev shape). */
+export interface StatusResponse {
+    status: "ok";
+    service: "compaction-api";
+    version: "v0";
+    mode: string;
+    engine: string;
+    hosted: boolean;
+    uptime_seconds: number;
+}
+/** Coded error body shape returned by every endpoint on failure. */
+export interface ApiErrorBody {
+    error: string;
+    details?: unknown;
+}

package/dist/core/api-client/types.js

@@ -0,0 +1,21 @@
+/**
+ * Compaction API client — wire types (PUBLIC CLI/SDK code).
+ *
+ * OPEN-CORE BOUNDARY: this module is part of the PUBLIC `@compaction/cli` package and
+ * ships in the published tarball. It MUST NOT import anything from `src/engine` and MUST
+ * NOT import the private `apps/api` package. It mirrors — by hand, with no cross-package
+ * import — the request/response SHAPES defined in `apps/api/src/schemas.ts` and the contract
+ * in `docs/api/compaction-api-v0.md`. The client speaks only the documented HTTP contract.
+ *
+ * Keeping these types LOCAL (rather than importing the `apps/api` zod schemas) is deliberate:
+ * it guarantees the public package has zero build/runtime coupling to the server package or
+ * the engine. The local-stub tests assert the shapes still line up with the live contract.
+ *
+ * See `docs/ops/cli-api-client-design.md` (Track E) and `docs/ops/api-command-ux.md` (Track F).
+ */
+/** Classes that carry raw-or-sanitized CONTENT and therefore require explicit upload consent. */
+export const CONTENT_BEARING_PAYLOAD_CLASSES = new Set([
+    "sanitized_snippets",
+    "full_trace"
+]);
+//# sourceMappingURL=types.js.map

package/dist/core/artifact-writer.d.ts

@@ -0,0 +1,2 @@
+export declare function writeJsonArtifact(outputDirectory: string, fileName: string, value: unknown): Promise<string>;
+export declare function writeTextArtifact(outputDirectory: string, fileName: string, value: string): Promise<string>;

package/dist/core/artifact-writer.js

@@ -0,0 +1,14 @@
+import { mkdir, writeFile } from "node:fs/promises";
+async function writeArtifact(outputDirectory, fileName, value) {
+    await mkdir(outputDirectory, { recursive: true });
+    const artifactPath = `${outputDirectory}/${fileName}`;
+    await writeFile(artifactPath, value, "utf8");
+    return artifactPath;
+}
+export async function writeJsonArtifact(outputDirectory, fileName, value) {
+    return writeArtifact(outputDirectory, fileName, `${JSON.stringify(value, null, 2)}\n`);
+}
+export async function writeTextArtifact(outputDirectory, fileName, value) {
+    return writeArtifact(outputDirectory, fileName, value.endsWith("\n") ? value : `${value}\n`);
+}
+//# sourceMappingURL=artifact-writer.js.map

package/dist/core/audit-report.d.ts

@@ -0,0 +1,91 @@
+import type { RunSummaryBucket, SkippedReportFile, TopSavingsRun } from "./run-aggregator.js";
+import type { RecommendationMode } from "../engine/recommendation.js";
+import type { SafetyRiskLevel, SafetyStatus } from "./safety-report.js";
+import type { ApplySafetyStatus } from "../engine/apply-mode.js";
+export declare const AUDIT_ARTIFACT_DIRECTORY = ".compaction/audits";
+export declare const AUDIT_ARTIFACT_NAMES: readonly ["audit-report.json", "audit-report.md"];
+export interface AuditInputDirectories {
+    runs: string;
+    recommendations: string;
+    apply: string;
+    audits: string;
+}
+export interface AuditSourceSummary {
+    source_directory: string;
+    artifact_name: string;
+    total_artifacts: number;
+    skipped_files: SkippedReportFile[];
+    missing: boolean;
+    note: string | null;
+}
+export interface PolicyAuditSummary extends RunSummaryBucket {
+    policy_name: string;
+}
+export interface WastePatternAuditSummary extends RunSummaryBucket {
+    waste_pattern: string;
+}
+export interface SafetyAuditSummary {
+    source: AuditSourceSummary;
+    total_reports: number;
+    status_counts: Record<SafetyStatus, number>;
+    risk_level_counts: Record<SafetyRiskLevel, number>;
+    total_tokens_saved_with_safety_reports: number;
+    warnings: string[];
+    failures: string[];
+    note: string | null;
+}
+export interface RecommendationAuditSummary {
+    source: AuditSourceSummary;
+    total_recommendations: number;
+    mode_counts: Record<RecommendationMode, number>;
+    total_tokens_saved: number;
+    recommended_next_steps: string[];
+    note: string | null;
+}
+export interface ApplyAuditSummary {
+    source: AuditSourceSummary;
+    total_apply_reports: number;
+    applied_count: number;
+    refused_count: number;
+    safety_status_counts: Record<ApplySafetyStatus, number>;
+    total_tokens_saved_from_applied_reports: number;
+    total_saving_per_run_from_applied_reports: number;
+    refusal_reasons: string[];
+    note: string | null;
+}
+export interface AuditReport {
+    audit_id: string;
+    generated_at: string;
+    total_runs: number;
+    total_original_input_tokens: number;
+    total_compacted_input_tokens: number;
+    total_tokens_saved: number;
+    average_percent_reduction: number;
+    total_cost_before_per_run: number;
+    total_cost_after_per_run: number;
+    total_saving_per_run: number;
+    policies_detected: PolicyAuditSummary[];
+    top_waste_patterns: WastePatternAuditSummary[];
+    safety_summary: SafetyAuditSummary;
+    recommendation_summary: RecommendationAuditSummary;
+    apply_summary?: ApplyAuditSummary;
+    top_savings_runs: TopSavingsRun[];
+    suggested_next_steps: string[];
+    limitations: string[];
+    sources: {
+        runs: AuditSourceSummary;
+        recommendations: AuditSourceSummary;
+        apply: AuditSourceSummary;
+    };
+}
+export interface AuditArtifactResult {
+    audit: AuditReport;
+    markdown: string;
+    paths: {
+        auditJsonPath: string;
+        auditMarkdownPath: string;
+    };
+}
+export declare function createAuditReport(directories?: Partial<AuditInputDirectories>, generatedAt?: string): Promise<AuditReport>;
+export declare function formatAuditMarkdown(report: AuditReport): string;
+export declare function writeAuditArtifacts(directories?: Partial<AuditInputDirectories>, generatedAt?: string): Promise<AuditArtifactResult>;