@unbrained/pm-cli 2026.8.6 → 2026.8.7

package/dist/sdk/history-analytics.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @module sdk/history-analytics
+ *
+ * Derives bounded provenance coverage and fleet outcome analytics from the
+ * immutable history event index without introducing telemetry-owned state.
+ */
+import { type HarnessSignalDescriptor } from "../core/shared/author.js";
+import type { HistoryEntry, ItemMetadata } from "../types/index.js";
+import { type AgentProvenanceDescriptorCoverage, type AgentProvenanceDimensionCoverage } from "./provenance.js";
+/** Bounded immutable-history window controls shared by analytics surfaces. */
+export interface HistoryAnalyticsWindowOptions {
+    /** Inclusive ISO timestamp or negative day/hour duration such as -30d. */
+    since?: string;
+    /** Maximum indexed events consumed across all pages. */
+    eventLimit?: number;
+    /** Minimum denominator required before a rate is reported. */
+    minimumSample?: number;
+}
+/** Read receipt proving how much immutable history contributed. */
+export interface HistoryAnalyticsWindowReceipt {
+    /** Inclusive lower bound used for the scan. */
+    since: string;
+    /** Number of indexed immutable events inspected. */
+    events: number;
+    /** Whether the configured event ceiling omitted matching rows. */
+    truncated: boolean;
+    /** Cursor that resumes after the last inspected event when truncated. */
+    next_cursor?: string;
+    /** Derived read source. */
+    source: "history_event_index";
+}
+/** Live declared-versus-observed provenance report. */
+export interface ProvenanceCoverageAnalytics {
+    /** Descriptor coverage for every declared dimension. */
+    descriptors: AgentProvenanceDescriptorCoverage[];
+    /** Per-harness availability over the bounded event window. */
+    observations: AgentProvenanceDimensionCoverage[];
+    /** Declared dimensions with enough explicit samples but no observations. */
+    inert: Array<{
+        harness: string;
+        dimension: string;
+        explicit_samples: number;
+    }>;
+    /** Dimensions no configured harness declares. */
+    undeclared: string[];
+    /** Stable warning codes suitable for health/gate adapters. */
+    warnings: string[];
+    /** Bounded source receipt. */
+    window: HistoryAnalyticsWindowReceipt;
+}
+/** One bounded attribution bucket with honest denominator states. */
+export interface FleetAttributionRow {
+    /** Recorded grouping value. */
+    value: string;
+    /** Immutable events attributed to the bucket. */
+    events: number;
+    /** State-changing events attributed to the bucket. */
+    state_events: number;
+    /** Annotation/evidence events attributed to the bucket. */
+    annotation_events: number;
+    /** Terminal transitions attributed to the bucket. */
+    closes: number;
+    /** Active transitions after a terminal transition in the observed window. */
+    reopens: number;
+    /** Issue items linked discovered_from to work closed by this bucket. */
+    defect_escapes: number;
+    /** Terminal transitions per observed day, or null for insufficient samples. */
+    throughput_per_day: number | null;
+    /** Reopens divided by closes, or null for insufficient samples. */
+    rework_rate: number | null;
+    /** Defect escapes divided by closes, or null for insufficient samples. */
+    defect_escape_rate: number | null;
+    /** Denominator state preventing tiny samples from masquerading as rates. */
+    sample_status: "available" | "insufficient";
+}
+/** One supported fleet grouping dimension. */
+export interface FleetAttributionDimension {
+    /** Stable dimension name. */
+    dimension: "harness" | "model" | "author_source";
+    /** Whether at least one event supplied this dimension. */
+    status: "available" | "unavailable";
+    /** Deterministically sorted bounded aggregate rows. */
+    rows: FleetAttributionRow[];
+}
+/** Observational fleet analytics derived only from immutable history. */
+export interface FleetAttributionAnalytics {
+    /** Grouped analytics for every supported provenance dimension. */
+    dimensions: FleetAttributionDimension[];
+    /** Minimum close denominator required for rates. */
+    minimum_sample: number;
+    /** Safety statement retained in every transport. */
+    policy: "observational_only_not_for_authorization_or_routing";
+    /** Bounded source receipt. */
+    window: HistoryAnalyticsWindowReceipt;
+}
+/** One immutable history entry paired with its owning tracked item. */
+export interface HistoryAnalyticsEvent {
+    /** Tracked item owning the immutable event. */
+    item_id: string;
+    /** Immutable history entry consumed by analytics. */
+    entry: HistoryEntry;
+}
+/** Reusable bounded history read shared across multiple analytics projections. */
+export interface HistoryAnalyticsWindow {
+    /** Immutable events retained by the configured bound. */
+    events: HistoryAnalyticsEvent[];
+    /** Receipt describing the bounded source read. */
+    receipt: HistoryAnalyticsWindowReceipt;
+}
+declare function parseHistoryAnalyticsLimit(value: number | undefined): number;
+declare function parseMinimumSample(value: number | undefined): number;
+declare function resolveHistoryAnalyticsSince(value: string | undefined): string;
+/** Read one reusable bounded immutable-history window. */
+export declare function readHistoryAnalyticsWindow(pmRoot: string, options: HistoryAnalyticsWindowOptions): Promise<HistoryAnalyticsWindow>;
+declare function provenanceValue(entry: HistoryEntry, dimension: FleetAttributionDimension["dimension"]): string | undefined;
+declare function statusFromEntry(entry: HistoryEntry): string | undefined;
+declare function annotationOperation(op: string): boolean;
+declare function buildFleetDimension(dimension: FleetAttributionDimension["dimension"], events: readonly HistoryAnalyticsEvent[], items: readonly Pick<ItemMetadata, "id" | "type" | "dependencies">[], terminalStatuses: ReadonlySet<string>, minimumSample: number, windowDays: number): FleetAttributionDimension;
+declare function resolveHistoryWindowDays(events: readonly HistoryAnalyticsEvent[], since: string): number;
+/** Evaluate a negative-control-friendly declared-versus-observed coverage gate. */
+export declare function evaluateProvenanceCoverage(entries: readonly HistoryEntry[], descriptors: readonly HarnessSignalDescriptor[], minimumSample: number): Omit<ProvenanceCoverageAnalytics, "window">;
+/** Read live, bounded provenance coverage from authoritative history. */
+export declare function runProvenanceCoverageAnalytics(pmRoot: string, descriptors?: readonly HarnessSignalDescriptor[], options?: HistoryAnalyticsWindowOptions): Promise<ProvenanceCoverageAnalytics>;
+/** Project provenance coverage from an already-read immutable-history window. */
+export declare function projectProvenanceCoverageAnalytics(window: HistoryAnalyticsWindow, descriptors?: readonly HarnessSignalDescriptor[], options?: Pick<HistoryAnalyticsWindowOptions, "minimumSample">): ProvenanceCoverageAnalytics;
+/** Derive bounded fleet rates grouped by harness, model, and author source. */
+export declare function runFleetAttributionAnalytics(pmRoot: string, items: readonly Pick<ItemMetadata, "id" | "type" | "dependencies">[], terminalStatuses: ReadonlySet<string>, options?: HistoryAnalyticsWindowOptions): Promise<FleetAttributionAnalytics>;
+/** Project fleet attribution from an already-read immutable-history window. */
+export declare function projectFleetAttributionAnalytics(window: HistoryAnalyticsWindow, items: readonly Pick<ItemMetadata, "id" | "type" | "dependencies">[], terminalStatuses: ReadonlySet<string>, options?: Pick<HistoryAnalyticsWindowOptions, "minimumSample">): FleetAttributionAnalytics;
+/** Pure seams for deterministic analytics and negative-control tests. */
+export declare const _testOnlyHistoryAnalytics: {
+    annotationOperation: typeof annotationOperation;
+    buildFleetDimension: typeof buildFleetDimension;
+    parseHistoryAnalyticsLimit: typeof parseHistoryAnalyticsLimit;
+    parseMinimumSample: typeof parseMinimumSample;
+    provenanceValue: typeof provenanceValue;
+    resolveHistoryAnalyticsSince: typeof resolveHistoryAnalyticsSince;
+    resolveHistoryWindowDays: typeof resolveHistoryWindowDays;
+    statusFromEntry: typeof statusFromEntry;
+};
+export {};

package/dist/sdk/history-analytics.js

@@ -0,0 +1,283 @@
+/**
+ * @module sdk/history-analytics
+ *
+ * Derives bounded provenance coverage and fleet outcome analytics from the
+ * immutable history event index without introducing telemetry-owned state.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f0e89b0b-ccd1-5dbb-afad-119d5a98590a")}catch(e){}}();
+import { AGENT_PROVENANCE_DIMENSIONS, BUILTIN_HARNESS_SIGNAL_DESCRIPTORS, } from "../core/shared/author.js";
+import { EXIT_CODE } from "../core/shared/constants.js";
+import { PmCliError } from "../core/shared/errors.js";
+import { listMutationEvents } from "./mutation-events.js";
+import { analyzeAgentProvenanceDescriptorCoverage, summarizeAgentProvenance, } from "./provenance.js";
+const DEFAULT_HISTORY_ANALYTICS_LIMIT = 10_000;
+const MAX_HISTORY_ANALYTICS_LIMIT = 100_000;
+const HISTORY_EVENT_PAGE_LIMIT = 1_000;
+const DEFAULT_HISTORY_WINDOW_DAYS = 30;
+const ANNOTATION_OPERATION_PREFIXES = [
+    "append",
+    "comment",
+    "docs",
+    "file",
+    "learning",
+    "note",
+    "test_run",
+];
+function parseHistoryAnalyticsLimit(value) {
+    const limit = value ?? DEFAULT_HISTORY_ANALYTICS_LIMIT;
+    if (!Number.isSafeInteger(limit) ||
+        limit < 1 ||
+        limit > MAX_HISTORY_ANALYTICS_LIMIT) {
+        throw new PmCliError(`History analytics event limit must be an integer from 1 to ${MAX_HISTORY_ANALYTICS_LIMIT}.`, EXIT_CODE.USAGE, { code: "invalid_history_analytics_limit" });
+    }
+    return limit;
+}
+function parseMinimumSample(value) {
+    const minimum = value ?? 5;
+    if (!Number.isSafeInteger(minimum) || minimum < 1 || minimum > 10_000) {
+        throw new PmCliError("History analytics minimum sample must be an integer from 1 to 10000.", EXIT_CODE.USAGE, { code: "invalid_history_analytics_minimum_sample" });
+    }
+    return minimum;
+}
+function resolveHistoryAnalyticsSince(value) {
+    const raw = value?.trim();
+    if (!raw) {
+        return new Date(Date.now() - DEFAULT_HISTORY_WINDOW_DAYS * 86_400_000).toISOString();
+    }
+    const relative = /^-(\d+)([dh])$/u.exec(raw);
+    if (relative) {
+        const amount = Number(relative[1]);
+        const multiplier = relative[2] === "d" ? 86_400_000 : 3_600_000;
+        if (!Number.isSafeInteger(amount) || amount < 1) {
+            throw new PmCliError("History analytics --since duration must be positive.", EXIT_CODE.USAGE, {
+                code: "invalid_history_analytics_since",
+            });
+        }
+        return new Date(Date.now() - amount * multiplier).toISOString();
+    }
+    const milliseconds = Date.parse(raw);
+    if (!Number.isFinite(milliseconds)) {
+        throw new PmCliError("History analytics --since must be an ISO timestamp or negative duration such as -30d.", EXIT_CODE.USAGE, { code: "invalid_history_analytics_since" });
+    }
+    return new Date(milliseconds).toISOString();
+}
+/** Read one reusable bounded immutable-history window. */
+export async function readHistoryAnalyticsWindow(pmRoot, options) {
+    const eventLimit = parseHistoryAnalyticsLimit(options.eventLimit);
+    const since = resolveHistoryAnalyticsSince(options.since);
+    const events = [];
+    let cursor = since;
+    let hasMore = false;
+    while (events.length < eventLimit) {
+        const page = await listMutationEvents({
+            pmRoot,
+            since: cursor,
+            limit: Math.min(HISTORY_EVENT_PAGE_LIMIT, eventLimit - events.length),
+            full: true,
+        });
+        const pageEvents = page.events.map((event) => ({
+            item_id: event.item_id,
+            entry: event.entry,
+        }));
+        events.push(...pageEvents);
+        hasMore = page.has_more;
+        cursor = page.next_cursor;
+        if (!page.has_more)
+            break;
+    }
+    return {
+        events,
+        receipt: {
+            since,
+            events: events.length,
+            truncated: hasMore,
+            ...(hasMore ? { next_cursor: cursor } : {}),
+            source: "history_event_index",
+        },
+    };
+}
+function provenanceValue(entry, dimension) {
+    if (dimension === "harness")
+        return entry.agent_harness;
+    if (dimension === "author_source")
+        return entry.author_source;
+    return entry.agent_model ?? entry.agent_provenance?.model?.value;
+}
+function statusFromEntry(entry) {
+    for (let index = entry.patch.length - 1; index >= 0; index -= 1) {
+        const operation = entry.patch[index];
+        if (operation.path === "/metadata/status" &&
+            "value" in operation &&
+            typeof operation.value === "string") {
+            return operation.value;
+        }
+    }
+    return undefined;
+}
+function annotationOperation(op) {
+    return ANNOTATION_OPERATION_PREFIXES.some((prefix) => op.startsWith(prefix));
+}
+function bucketFor(buckets, value) {
+    const existing = buckets.get(value);
+    if (existing)
+        return existing;
+    const created = {
+        events: 0,
+        stateEvents: 0,
+        annotationEvents: 0,
+        closes: 0,
+        reopens: 0,
+        defectEscapes: 0,
+    };
+    buckets.set(value, created);
+    return created;
+}
+function accumulateFleetEvents(dimension, events, terminalStatuses) {
+    const buckets = new Map();
+    const streamTerminal = new Map();
+    const lastCloseValue = new Map();
+    for (const event of events) {
+        const value = provenanceValue(event.entry, dimension);
+        const status = statusFromEntry(event.entry);
+        const wasTerminal = streamTerminal.get(event.item_id) === true;
+        const isTerminal = status === undefined ? wasTerminal : terminalStatuses.has(status);
+        if (status !== undefined)
+            streamTerminal.set(event.item_id, isTerminal);
+        if (!value)
+            continue;
+        const bucket = bucketFor(buckets, value);
+        bucket.events += 1;
+        if (annotationOperation(event.entry.op))
+            bucket.annotationEvents += 1;
+        else
+            bucket.stateEvents += 1;
+        if (status !== undefined && !wasTerminal && isTerminal) {
+            bucket.closes += 1;
+            lastCloseValue.set(event.item_id, value);
+        }
+        else if (status !== undefined && wasTerminal && !isTerminal) {
+            bucket.reopens += 1;
+        }
+    }
+    return { buckets, lastCloseValue };
+}
+function attributeDefectEscapes(buckets, lastCloseValue, items) {
+    for (const item of items) {
+        if (item.type !== "Issue")
+            continue;
+        const sources = new Set((item.dependencies ?? [])
+            .filter((dependency) => dependency.kind === "discovered_from")
+            .map((dependency) => dependency.id));
+        for (const source of sources) {
+            const value = lastCloseValue.get(source);
+            if (value)
+                bucketFor(buckets, value).defectEscapes += 1;
+        }
+    }
+}
+function fleetRow(value, bucket, minimumSample, windowDays) {
+    const sampleStatus = bucket.closes >= minimumSample ? "available" : "insufficient";
+    return {
+        value,
+        events: bucket.events,
+        state_events: bucket.stateEvents,
+        annotation_events: bucket.annotationEvents,
+        closes: bucket.closes,
+        reopens: bucket.reopens,
+        defect_escapes: bucket.defectEscapes,
+        throughput_per_day: sampleStatus === "available" ? bucket.closes / windowDays : null,
+        rework_rate: sampleStatus === "available" ? bucket.reopens / bucket.closes : null,
+        defect_escape_rate: sampleStatus === "available"
+            ? bucket.defectEscapes / bucket.closes
+            : null,
+        sample_status: sampleStatus,
+    };
+}
+function buildFleetDimension(dimension, events, items, terminalStatuses, minimumSample, windowDays) {
+    const { buckets, lastCloseValue } = accumulateFleetEvents(dimension, events, terminalStatuses);
+    attributeDefectEscapes(buckets, lastCloseValue, items);
+    return {
+        dimension,
+        status: buckets.size === 0 ? "unavailable" : "available",
+        rows: [...buckets]
+            .map(([value, bucket]) => fleetRow(value, bucket, minimumSample, windowDays))
+            .sort((left, right) => right.events - left.events || left.value.localeCompare(right.value)),
+    };
+}
+function resolveHistoryWindowDays(events, since) {
+    const firstTimestamp = events[0]?.entry.ts ?? since;
+    const lastTimestamp = events[events.length - 1]?.entry.ts ?? firstTimestamp;
+    const firstMilliseconds = Date.parse(firstTimestamp);
+    const lastMilliseconds = Date.parse(lastTimestamp);
+    if (!Number.isFinite(firstMilliseconds) ||
+        !Number.isFinite(lastMilliseconds)) {
+        return 1;
+    }
+    return Math.max(1, (lastMilliseconds - firstMilliseconds) / 86_400_000);
+}
+/** Evaluate a negative-control-friendly declared-versus-observed coverage gate. */
+export function evaluateProvenanceCoverage(entries, descriptors, minimumSample) {
+    const descriptorCoverage = analyzeAgentProvenanceDescriptorCoverage(descriptors);
+    const observations = summarizeAgentProvenance(entries, AGENT_PROVENANCE_DIMENSIONS, minimumSample);
+    const inert = observations
+        .filter((row) => row.inert)
+        .map((row) => ({
+        harness: row.harness,
+        dimension: row.dimension,
+        explicit_samples: row.observed + row.unavailable,
+    }));
+    const undeclared = descriptorCoverage
+        .filter((row) => !row.covered)
+        .map((row) => row.dimension);
+    return {
+        descriptors: descriptorCoverage,
+        observations,
+        inert,
+        undeclared,
+        warnings: [
+            ...inert.map((row) => `provenance_dimension_inert:${row.harness}:${row.dimension}:${String(row.explicit_samples)}`),
+            ...undeclared.map((dimension) => `provenance_dimension_undeclared:${dimension}`),
+        ],
+    };
+}
+/** Read live, bounded provenance coverage from authoritative history. */
+export async function runProvenanceCoverageAnalytics(pmRoot, descriptors = BUILTIN_HARNESS_SIGNAL_DESCRIPTORS, options = {}) {
+    return projectProvenanceCoverageAnalytics(await readHistoryAnalyticsWindow(pmRoot, options), descriptors, options);
+}
+/** Project provenance coverage from an already-read immutable-history window. */
+export function projectProvenanceCoverageAnalytics(window, descriptors = BUILTIN_HARNESS_SIGNAL_DESCRIPTORS, options = {}) {
+    const minimumSample = parseMinimumSample(options.minimumSample);
+    return {
+        ...evaluateProvenanceCoverage(window.events.map((event) => event.entry), descriptors, minimumSample),
+        window: window.receipt,
+    };
+}
+/** Derive bounded fleet rates grouped by harness, model, and author source. */
+export async function runFleetAttributionAnalytics(pmRoot, items, terminalStatuses, options = {}) {
+    return projectFleetAttributionAnalytics(await readHistoryAnalyticsWindow(pmRoot, options), items, terminalStatuses, options);
+}
+/** Project fleet attribution from an already-read immutable-history window. */
+export function projectFleetAttributionAnalytics(window, items, terminalStatuses, options = {}) {
+    const minimumSample = parseMinimumSample(options.minimumSample);
+    const windowDays = resolveHistoryWindowDays(window.events, window.receipt.since);
+    return {
+        dimensions: ["harness", "model", "author_source"].map((dimension) => buildFleetDimension(dimension, window.events, items, terminalStatuses, minimumSample, windowDays)),
+        minimum_sample: minimumSample,
+        policy: "observational_only_not_for_authorization_or_routing",
+        window: window.receipt,
+    };
+}
+/** Pure seams for deterministic analytics and negative-control tests. */
+export const _testOnlyHistoryAnalytics = {
+    annotationOperation,
+    buildFleetDimension,
+    parseHistoryAnalyticsLimit,
+    parseMinimumSample,
+    provenanceValue,
+    resolveHistoryAnalyticsSince,
+    resolveHistoryWindowDays,
+    statusFromEntry,
+};
+//# sourceMappingURL=history-analytics.js.map
+//# debugId=f0e89b0b-ccd1-5dbb-afad-119d5a98590a

package/dist/sdk/improvement-ledger-validation.d.ts

@@ -0,0 +1,3 @@
+import type { ImprovementLedgerDocument } from "./improvement-ledger.js";
+/** Parse and validate a serialized improvement-ledger singleton. */
+export declare function parseImprovementLedgerDocument(raw: string | null): ImprovementLedgerDocument;

package/dist/sdk/improvement-ledger-validation.js

@@ -0,0 +1,63 @@
+/**
+ * @module sdk/improvement-ledger-validation
+ *
+ * Validates the persisted improvement-ledger envelope and observations at the
+ * storage boundary so malformed workspace state never reaches analytics.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="939d5f93-d287-5c1c-bc78-d013f76735f2")}catch(e){}}();
+import { EXIT_CODE } from "../core/shared/constants.js";
+import { PmCliError } from "../core/shared/errors.js";
+const IMPROVEMENT_LEDGER_FORMAT_VERSION = 1;
+function isValidLedgerObservation(observation) {
+    if (typeof observation !== "object" || observation === null)
+        return false;
+    const candidate = observation;
+    const hasRequiredFields = typeof candidate.id === "string" &&
+        typeof candidate.metric === "string" &&
+        typeof candidate.value === "number" &&
+        Number.isFinite(candidate.value) &&
+        ["higher", "lower", "target"].includes(String(candidate.direction)) &&
+        typeof candidate.observed_at === "string" &&
+        typeof candidate.revision === "string" &&
+        ["caller", "git", "unversioned"].includes(String(candidate.revision_source)) &&
+        typeof candidate.author === "string";
+    if (!hasRequiredFields)
+        return false;
+    return (candidate.direction !== "target" ||
+        (typeof candidate.threshold === "number" &&
+            Number.isFinite(candidate.threshold)));
+}
+/** Parse and validate a serialized improvement-ledger singleton. */
+export function parseImprovementLedgerDocument(raw) {
+    if (raw === null) {
+        return {
+            format_version: IMPROVEMENT_LEDGER_FORMAT_VERSION,
+            observations: [],
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new PmCliError("Improvement ledger contains invalid JSON.", EXIT_CODE.GENERIC_FAILURE, { code: "invalid_improvement_ledger" });
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        Array.isArray(parsed) ||
+        parsed.format_version !==
+            IMPROVEMENT_LEDGER_FORMAT_VERSION ||
+        !Array.isArray(parsed.observations)) {
+        throw new PmCliError("Improvement ledger has an unsupported shape or format version.", EXIT_CODE.GENERIC_FAILURE, { code: "invalid_improvement_ledger" });
+    }
+    const observations = parsed.observations;
+    for (const observation of observations) {
+        if (!isValidLedgerObservation(observation)) {
+            throw new PmCliError("Improvement ledger contains an invalid observation.", EXIT_CODE.GENERIC_FAILURE, { code: "invalid_improvement_ledger" });
+        }
+    }
+    return parsed;
+}
+//# sourceMappingURL=improvement-ledger-validation.js.map
+//# debugId=939d5f93-d287-5c1c-bc78-d013f76735f2

package/dist/sdk/improvement-ledger.d.ts

@@ -0,0 +1,139 @@
+import { parseImprovementLedgerDocument as parseLedger } from "./improvement-ledger-validation.js";
+/** Direction in which a metric represents improvement. */
+export type ImprovementDirection = "higher" | "lower" | "target";
+/** One immutable quantitative observation retained by the workspace ledger. */
+export interface ImprovementObservation {
+    /** Content-derived observation identity. */
+    id: string;
+    /** Stable, agent-readable metric name. */
+    metric: string;
+    /** Finite observed numeric value. */
+    value: number;
+    /** Direction in which later values improve. */
+    direction: ImprovementDirection;
+    /** Optional domain unit such as count, ms, bytes, or percent. */
+    unit?: string;
+    /** Required target when direction is target; optional gate threshold otherwise. */
+    threshold?: number;
+    /** ISO timestamp at which the value was observed. */
+    observed_at: string;
+    /** Git commit, caller revision, or explicit unversioned marker. */
+    revision: string;
+    /** How the revision value was obtained. */
+    revision_source: "caller" | "git" | "unversioned";
+    /** Attributed actor that recorded the observation. */
+    author: string;
+    /** Optional tracked item owning the measurement. */
+    item_id?: string;
+    /** Optional producing instrument or gate name. */
+    source?: string;
+    /** Stable retry key when supplied or derivable from a revision. */
+    idempotency_key?: string;
+}
+/** Versioned workspace singleton containing every retained observation. */
+export interface ImprovementLedgerDocument {
+    /** Storage contract revision. */
+    format_version: 1;
+    /** Append-only observations in deterministic chronological order. */
+    observations: ImprovementObservation[];
+}
+/** Mutation controls accepted by {@link recordImprovementObservation}. */
+export interface RecordImprovementObservationOptions {
+    /** Stable metric name. */
+    metric: string;
+    /** Finite observed numeric value. */
+    value: number;
+    /** Direction in which later values improve. */
+    direction?: ImprovementDirection;
+    /** Optional domain unit. */
+    unit?: string;
+    /** Target or gate threshold associated with this observation. */
+    threshold?: number;
+    /** Optional producing instrument or gate name. */
+    source?: string;
+    /** Optional tracked item owning the observation. */
+    itemId?: string;
+    /** Explicit source revision; otherwise git HEAD is resolved when available. */
+    revision?: string;
+    /** Explicit observation time, primarily for reproducible importers. */
+    observedAt?: string;
+    /** Explicit retry identity. */
+    idempotencyKey?: string;
+    /** Intentional author override. */
+    author?: string;
+    /** Human-readable audit rationale. */
+    message?: string;
+}
+/** Receipt returned after recording or replaying one observation. */
+export interface RecordImprovementObservationResult {
+    /** Whether a new observation was appended. */
+    changed: boolean;
+    /** Recorded or idempotently replayed observation. */
+    observation: ImprovementObservation;
+    /** Workspace-relative singleton path. */
+    ledger_path: "improvement-ledger.json";
+}
+/** Bounded read controls for {@link readImprovementLedger}. */
+export interface ReadImprovementLedgerOptions {
+    /** Explicit tracker root, equivalent to global --pm-path. */
+    pmRoot?: string;
+    /** Working directory used for implicit tracker discovery. */
+    cwd?: string;
+    /** Optional exact metric filter. */
+    metric?: string;
+    /** Optional tracked owner filter. */
+    itemId?: string;
+    /** Inclusive ISO timestamp lower bound. */
+    since?: string;
+    /** Maximum newest observations returned. */
+    limit?: number;
+}
+/** One baseline-to-latest trend computed without rewriting observations. */
+export interface ImprovementTrend {
+    /** Stable metric name. */
+    metric: string;
+    /** Direction used to interpret the delta. */
+    direction: ImprovementDirection;
+    /** Oldest matching observation. */
+    baseline: ImprovementObservation;
+    /** Newest matching observation. */
+    latest: ImprovementObservation;
+    /** Latest value minus baseline value. */
+    delta: number;
+    /** Whether the latest value improved over the baseline. */
+    improved: boolean;
+    /** Number of observations contributing to the trend. */
+    sample_count: number;
+}
+/** Bounded ledger page plus complete aggregate trend metadata. */
+export interface ImprovementLedgerResult {
+    /** Newest-first observation page. */
+    observations: ImprovementObservation[];
+    /** Matching observation count before the page limit. */
+    total: number;
+    /** Whether older matching rows were omitted. */
+    truncated: boolean;
+    /** Trends for every matching metric, sorted by metric name. */
+    trends: ImprovementTrend[];
+    /** Read provenance for deterministic consumers. */
+    source: "audited_workspace_singleton";
+}
+declare function normalizeMetricName(value: string): string;
+declare function normalizeDirection(value: ImprovementDirection | undefined): ImprovementDirection;
+declare function parseObservationLimit(value: number | undefined): number;
+declare function trendForMetric(observations: ImprovementObservation[]): ImprovementTrend;
+/** Record one audited observation, returning an idempotent receipt on retry. */
+export declare function recordImprovementObservation(options: RecordImprovementObservationOptions, global?: {
+    path?: string;
+}): Promise<RecordImprovementObservationResult>;
+/** Read a bounded newest-first observation page and derive complete trends. */
+export declare function readImprovementLedger(options?: ReadImprovementLedgerOptions): Promise<ImprovementLedgerResult>;
+/** Pure helpers exposed for storage and trend contract tests. */
+export declare const _testOnlyImprovementLedger: {
+    normalizeMetricName: typeof normalizeMetricName;
+    normalizeDirection: typeof normalizeDirection;
+    parseLedger: typeof parseLedger;
+    parseObservationLimit: typeof parseObservationLimit;
+    trendForMetric: typeof trendForMetric;
+};
+export {};