export interface SpecUsageEvent {
    /** The spec identifier referenced (e.g. "SPEC-042") */
    readonly specId: string;
    /** The MCP tool name that referenced the spec */
    readonly toolName: string;
    /** ISO 8601 timestamp of the access */
    readonly timestamp: string;
    /** Optional: acceptance criterion referenced (e.g. "AC-3") */
    readonly acRef?: string;
}
export interface SpecUsageMetrics {
    /** Spec identifier */
    readonly specId: string;
    /** Total number of accesses in the period */
    readonly totalAccesses: number;
    /** Distinct tools that referenced this spec */
    readonly toolsUsed: readonly string[];
    /** Map of toolName -> count */
    readonly toolMatrix: Record<string, number>;
    /** Most referenced acceptance criteria */
    readonly hotAcs: readonly {
        readonly acRef: string;
        readonly count: number;
    }[];
    /** ISO 8601 timestamp of first access */
    readonly firstAccessAt: string;
    /** ISO 8601 timestamp of most recent access */
    readonly lastAccessAt: string;
}
export interface SpecObservabilityReport {
    /** Project ID */
    readonly projectId: string;
    /** Period used to filter events */
    readonly period: 'day' | 'week' | 'month' | 'all';
    /** ISO 8601 timestamp of report generation */
    readonly generatedAt: string;
    /** Total spec access events in period */
    readonly totalEvents: number;
    /** Hot specs: most frequently accessed */
    readonly hotSpecs: readonly SpecUsageMetrics[];
    /** Cold specs: approved but never accessed in the period (specIds only) */
    readonly coldSpecs: readonly string[];
    /** Metrics per spec (all specs that had at least one event) */
    readonly specMetrics: readonly SpecUsageMetrics[];
    /** Tool-level summary: which tools generated the most spec references */
    readonly topTools: readonly {
        readonly toolName: string;
        readonly count: number;
    }[];
}
export interface SpecUsageLog {
    /** Append-only event list */
    readonly events: readonly SpecUsageEvent[];
}
export interface SpecUsageReportInput {
    readonly projectId: string;
    readonly specId?: string;
    readonly period?: 'day' | 'week' | 'month' | 'all';
}
/** Time period for filtering usage events. */
export type Period = 'day' | 'week' | 'month' | 'all';
/** Options for building an observability report. */
export interface BuildReportOptions {
    projectId: string;
    period: Period;
    events: readonly SpecUsageEvent[];
    allKnownSpecIds?: readonly string[];
    /** Filter to a single spec when specId is provided */
    filterSpecId?: string;
}
//# sourceMappingURL=spec-observability.d.ts.map