@pipeline-builder/pipeline-data 0.0.1

package/lib/api/reporting-service.d.ts

@@ -0,0 +1,685 @@
+interface ExecutionCount {
+    id: string;
+    project: string;
+    organization: string;
+    pipelineName: string | null;
+    total: number;
+    succeeded: number;
+    failed: number;
+    canceled: number;
+    firstExecution: string | null;
+    lastExecution: string | null;
+}
+interface TimeSeriesEntry {
+    period: string;
+    succeeded: number;
+    failed: number;
+    canceled: number;
+    successPct: number;
+}
+interface DurationStats {
+    id: string;
+    project: string;
+    pipelineName: string | null;
+    avgMs: number;
+    minMs: number;
+    maxMs: number;
+    p95Ms: number;
+    executions: number;
+}
+interface PipelineExecution {
+    executionId: string;
+    /** Rolled-up terminal status: succeeded | failed | canceled | in-progress. */
+    status: string;
+    startedAt: string | null;
+    endedAt: string | null;
+    durationMs: number | null;
+    /** First failing stage/action for the execution (null when it didn't fail). */
+    failingStage: string | null;
+    failingAction: string | null;
+}
+interface StageFailure {
+    stageName: string;
+    failures: number;
+    total: number;
+    failurePct: number;
+}
+interface StageBottleneck {
+    id: string;
+    pipelineName: string | null;
+    stageName: string;
+    avgMs: number;
+    maxMs: number;
+}
+interface ActionFailure {
+    actionName: string;
+    failures: number;
+    total: number;
+    failurePct: number;
+}
+interface ErrorEntry {
+    errorPattern: string;
+    occurrences: number;
+    affectedPipelines: number;
+    lastSeen: string;
+}
+interface PluginSummary {
+    total: number;
+    active: number;
+    inactive: number;
+    /** Counts per sharing rung — one bucket per `visibility` value. */
+    public: number;
+    org: number;
+    private: number;
+    uniqueNames: number;
+}
+interface TypeComputeDistribution {
+    pluginType: string;
+    computeType: string;
+    count: number;
+}
+interface VersionCount {
+    name: string;
+    versionCount: number;
+    latestVersion: string;
+    hasDefault: boolean;
+}
+interface BuildTimeSeriesEntry {
+    period: string;
+    succeeded: number;
+    failed: number;
+    successPct: number;
+}
+interface BuildDuration {
+    pluginName: string;
+    avgMs: number;
+    maxMs: number;
+    builds: number;
+}
+interface BuildFailure {
+    pluginName: string;
+    errorMessage: string;
+    occurrences: number;
+    lastSeen: string;
+}
+/** Effective standard-event retention (days): a valid per-org override wins,
+ *  else the global env default. Shared by the sweep + the settings surface so
+ *  they can't drift. The `-1` unlimited sentinel (Phase 8) passes straight
+ *  through — the sweep reads it as "keep forever, skip this org's standard
+ *  events". A positive override clamps to [1, RETENTION_MAX_DAYS]; a `null`, a
+ *  non-integer, or any other out-of-range value (e.g. 0, -2) falls back to the
+ *  env default. */
+export declare function resolveEventRetentionDays(override?: number | null): number;
+/** Effective DORA-source retention (days): a valid per-org override wins, else
+ *  the global env default. The `-1` unlimited sentinel (Phase 8) passes straight
+ *  through — the sweep reads it as "keep forever, skip this org's DORA-source
+ *  windows". A positive override clamps to [1, RETENTION_MAX_DAYS]; a `null`, a
+ *  non-integer, or any other out-of-range value (e.g. 0, -2) falls back to the
+ *  env default. */
+export declare function resolveDoraRetentionDays(override?: number | null): number;
+/** The cutoff instant for a retention window: rows with `created_at` strictly
+ *  before this (`< cutoff`) are expired. Deterministic for a fixed `now`. */
+export declare function retentionCutoff(now: Date, days: number): Date;
+/** Per-org retention override row (Phase 7). Both nullable ⇒ global defaults. */
+export interface ReportingRetentionSettings {
+    eventRetentionDays: number | null;
+    doraRetentionDays: number | null;
+    defaultEventRetentionDays: number;
+    defaultDoraRetentionDays: number;
+}
+/** Options for the reporting retention sweep. */
+export interface ReportingRetentionOptions {
+    /** Rows deleted per statement (default 1000). */
+    batchSize?: number;
+    /** Max batches per table per org per tick (default 50); the rest defers to
+     *  the next tick so a huge backlog can't hold locks too long. */
+    maxBatchesPerTable?: number;
+    /** Fixed "now" for the whole sweep (default `new Date()`). */
+    now?: Date;
+}
+/** Per-run purge tallies (also logged). */
+export interface ReportingRetentionCounts {
+    /** Orgs swept this run. */
+    orgs: number;
+    /** Standard `pipeline_events` (environment IS NULL) rows purged. */
+    standardEvents: number;
+    /** DORA-source `pipeline_events` (environment IS NOT NULL) rows purged. */
+    doraEvents: number;
+    /** `deployment_outcomes` rows purged. */
+    deploymentOutcomes: number;
+    /** `incidents` rows purged. */
+    incidents: number;
+}
+/**
+ * DORA performance band. `null` = insufficient data to classify (no
+ * deployments/failures/lead-time sample in the window), so the UI shows a
+ * neutral state rather than mislabeling an empty window as "low".
+ */
+export type DoraLevel = 'elite' | 'high' | 'medium' | 'low' | null;
+/** Optional scoping for {@link ReportingService.getDoraMetrics}. */
+export interface DoraOptions {
+    /** Restrict to a single pipeline (per-pipeline DORA). */
+    pipelineId?: string;
+    /** Restrict to a single deploy environment (else all deploy environments). */
+    environment?: string;
+    /**
+     * Per-org incident→deploy correlation window override (hours). When set (a
+     * positive finite number), the incident correlation uses it instead of the
+     * global `DORA_INCIDENT_WINDOW_HOURS`. The route resolves this from the org's
+     * `dora_settings` row (see {@link ReportingService.getIncidentSettings}) and
+     * passes it in; unset falls back to the env default.
+     */
+    incidentWindowHours?: number;
+}
+/**
+ * Per-org reporting settings surfaced to the org-admin panel. `incidentWindowHours`
+ * (Phase 5b) is the incident→deploy correlation window; `eventRetentionDays` /
+ * `doraRetentionDays` (Phase 7) are the two retention-sweep windows. Each override
+ * is `null` when unset (the paired `default*` field shows the env fallback applied).
+ */
+export interface IncidentSettings {
+    /** The org's stored correlation-window override in hours, or `null` when unset. */
+    incidentWindowHours: number | null;
+    /** The global env default applied when no override is stored. */
+    defaultWindowHours: number;
+    /** Standard-event retention override in days, or `null` when unset (Phase 7). */
+    eventRetentionDays: number | null;
+    /** DORA-source retention override in days, or `null` when unset (Phase 7). */
+    doraRetentionDays: number | null;
+    /** Global standard-event retention default applied when unset (days). */
+    defaultEventRetentionDays: number;
+    /** Global DORA-source retention default applied when unset (days). */
+    defaultDoraRetentionDays: number;
+}
+/** A partial reporting-settings write (Phase 5b + 7). Only provided fields are
+ *  upserted; omitted fields are left unchanged (an omitted retention field keeps
+ *  its stored override / the global default). */
+export interface ReportingSettingsPatch {
+    incidentWindowHours?: number;
+    eventRetentionDays?: number;
+    doraRetentionDays?: number;
+}
+/** One row of the org-admin incidents list (recent incidents + deploy correlation). */
+export interface IncidentListItem {
+    incidentId: string;
+    environment: string;
+    severity: string;
+    openedAt: string | null;
+    resolvedAt: string | null;
+    createdAt: string | null;
+    /** True once the incident has a `resolved_at`. */
+    resolved: boolean;
+    /** The correlated deploy execution id (most recent successful deploy in-window), or null. */
+    correlatedExecutionId: string | null;
+    /** That deploy's completion instant, or null when uncorrelated. */
+    deployCompletedAt: string | null;
+}
+/** Result of the wiring-test dry-run correlation ({@link ReportingService.testIncidentCorrelation}). */
+export interface IncidentTestResult {
+    environment: string;
+    /** The synthetic incident's openedAt (now, ISO). */
+    openedAt: string;
+    /** The effective correlation window used. */
+    windowHours: number;
+    /** Whether a recent successful deploy to `environment` correlated. */
+    correlated: boolean;
+    /** The correlated deploy execution id, or null. */
+    executionId: string | null;
+    /** That deploy's completion instant, or null. */
+    deployCompletedAt: string | null;
+}
+/**
+ * DORA metrics over a [from,to] window, org-scoped (single-org or rollup subtree).
+ *
+ * DEPLOY-BASIS — every metric derives from real DEPLOY-STAGE executions, i.e.
+ * `pipeline_events` rows with `event_type='STAGE'` and a non-null `environment`
+ * (the forwarder sets `environment` only for the stages a user declared in
+ * `pb.deploys`). A CI-only build/test pipeline with no deploy stage produces NO
+ * DORA data — there is no run-based fallback. The panel is empty until deployed
+ * pipelines re-synth with the new deploy tags and start emitting deploy events.
+ *
+ * `production` is the headline environment; MTTR is measured production-only.
+ */
+export interface DoraMetrics {
+    /** The [from,to] window echoed back (deploy `completed_at` range). */
+    window: {
+        from: string;
+        to: string;
+    };
+    /** The scoping applied (echoed for the UI); `null` when unscoped. */
+    filters: {
+        pipelineId: string | null;
+        environment: string | null;
+    };
+    /** The headline environment name (`production`). */
+    headline: string;
+    /** Per-environment DF / CFR / lead time. Sorted headline-first, then A→Z. */
+    environments: DoraEnvMetrics[];
+    /**
+     * Mean Time To Restore — PRODUCTION-ONLY, from `deployment_outcomes`.
+     * `median(restored.at − deployed.completed_at)` over restored production
+     * incidents (deltas clamped ≥0). `incidents` counts production deploys marked
+     * failed; `restored` counts those that recovered; `medianSeconds` is null when
+     * no restored incident has a resolvable deploy time.
+     */
+    meanTimeToRestore: {
+        incidents: number;
+        restored: number;
+        medianSeconds: number | null;
+        level: DoraLevel;
+    };
+    /**
+     * Coverage reconciliation — registered pipelines with no observed deploy in
+     * the window. A high `withoutDeploys` count means DORA is blind to most of the
+     * fleet (pipelines that haven't re-synthed with deploy tags, or don't deploy).
+     */
+    coverage: {
+        /** Pipelines in the registry (org-scoped). */
+        registered: number;
+        /** Registered pipelines with ≥1 deploy-stage execution in the window. */
+        deploying: number;
+        /** registered − deploying (clamped ≥0). */
+        withoutDeploys: number;
+    };
+}
+/** Per-environment DORA metrics (deployment frequency, CFR, lead time). */
+export interface DoraEnvMetrics {
+    environment: string;
+    /** Deployment Frequency — successful deploy-stage executions for this env. */
+    deploymentFrequency: {
+        deployments: number;
+        perDay: number;
+        level: DoraLevel;
+    };
+    /**
+     * Change Failure Rate — two-class:
+     * `(deployTimeFailures + postDeployFailures) / attempts`.
+     * - `deployTimeFailures` — deploy stage `result=failed` (from events).
+     * - `postDeployFailures` — a successful deploy later marked failed in prod
+     *   (from `deployment_outcomes`).
+     * - `attempts` — all terminal deploy-stage attempts (succeeded + failed).
+     */
+    changeFailureRate: {
+        rate: number;
+        deployTimeFailures: number;
+        postDeployFailures: number;
+        attempts: number;
+        level: DoraLevel;
+    };
+    /**
+     * Lead Time — MEASURED: `median(deploy_completed − oldest_commit_time)` over
+     * successful deploys with a resolvable commit timestamp (deltas clamped ≥0).
+     * `medianSeconds` is `null` (= unknown) when no successful deploy in this env
+     * carried a `commit_timestamp`. The old median-run-duration proxy is removed.
+     */
+    leadTime: {
+        /** Successful deploys with a resolvable commit time (the median sample). */
+        deployments: number;
+        medianSeconds: number | null;
+        level: DoraLevel;
+    };
+}
+/** One interval bucket of the DORA trend (deploy frequency + change failure). */
+export interface DoraTrendPoint {
+    /** Bucket start (DATE_TRUNC of the deploy `completed_at`), ISO text. */
+    period: string;
+    /** Successful deploy-stage executions in the bucket. */
+    deployments: number;
+    /** Failed deploy-stage executions in the bucket. */
+    failed: number;
+    /** succeeded + failed in the bucket (deploy attempts). */
+    total: number;
+    /** failed/total as a percent (0 when total is 0). Deploy-time CFR only. */
+    changeFailurePct: number;
+}
+/** Per-stage build-health metrics (Phase 6) for one pipeline over a window. */
+export interface BuildHealthStage {
+    stage: string;
+    /** Terminal stage runs (succeeded + failed) in the window. */
+    runs: number;
+    successes: number;
+    failures: number;
+    /** successes / runs as a percent (0 when runs is 0). */
+    successRate: number;
+    /** Duration percentiles over the stage's terminal runs; null when no durations. */
+    p50Ms: number | null;
+    p90Ms: number | null;
+    p99Ms: number | null;
+}
+/**
+ * Per-pipeline build-health breakdown (Phase 6). Standard reporting (NOT
+ * `advanced_reporting`-gated) — per-stage success rate + timing percentiles, with
+ * totals summed across stages.
+ */
+export interface BuildHealth {
+    stages: BuildHealthStage[];
+    totals: {
+        runs: number;
+        failures: number;
+        failureRate: number;
+    };
+}
+/** Post-deploy incident marker (Phase 5) accepted by `ReportingService.recordIncident`. */
+export interface IncidentInput {
+    incidentId: string;
+    environment: string;
+    openedAt: string;
+    resolvedAt?: string;
+    severity: string;
+}
+/** Event payload accepted by `ReportingService.ingestEvents`. Mirrors the route's Zod shape. */
+export interface IngestEvent {
+    /** Stable pipeline id the events Lambda read from the `pb.pipeline-id`
+     *  tag (= the platform pipelineId). The registry join key. */
+    pipelineId: string;
+    eventSource: 'codepipeline' | 'codebuild' | 'plugin-build';
+    eventType: 'PIPELINE' | 'STAGE' | 'ACTION' | 'BUILD';
+    status: string;
+    executionId?: string;
+    stageName?: string;
+    actionName?: string;
+    /** Human-readable failure reason (Action events). */
+    errorMessage?: string;
+    startedAt?: string;
+    completedAt?: string;
+    durationMs?: number;
+    /** Source commit id of the change being shipped (DORA deploy attribution). */
+    commitSha?: string;
+    /** Source ref/branch (DORA deploy attribution). */
+    commitRef?: string;
+    /** Deploy target (e.g. "production"). Its presence on a STAGE/ACTION event
+     *  marks a real deployment (derived server-side — there is no `isDeploy`). */
+    environment?: string;
+    /** Oldest unshipped commit timestamp (ISO 8601) for measured lead time. */
+    commitTimestamp?: string;
+    /** Number of commits shipped in this change (≥1). */
+    commitCount?: number;
+    detail?: Record<string, unknown>;
+}
+/**
+ * Per-event metric descriptor emitted (via the {@link ReportingService.ingestEvents}
+ * `onMetric` hook) for each REGISTERED terminal deploy/stage event, so the route
+ * layer can fan them into Prometheus counters without pipeline-data importing
+ * api-server's metrics registry. `result` is the terminal outcome; `environment`
+ * is non-null only for a deploy-stage event.
+ */
+export interface IngestMetric {
+    pipelineId: string;
+    orgId: string;
+    stage: string;
+    environment: string | null;
+    result: 'succeeded' | 'failed';
+}
+/** Counts + the (possibly truncated) list of unregistered pipeline ids the caller can log. */
+export interface IngestResult {
+    inserted: number;
+    skipped: number;
+    unregisteredPipelineIds: string[];
+}
+/**
+ * Read-only reporting service for pipeline execution and plugin inventory aggregations.
+ * Does not extend CrudService — reports are aggregate queries, not entity CRUD.
+ *
+ * All queries are cached in-memory to avoid repeated expensive SQL aggregations:
+ * - Inventory queries (plugin summary/distribution/versions): 5 min TTL
+ * - Timeseries queries (execution/build metrics with date ranges): 2 min TTL
+ */
+export declare class ReportingService {
+    #private;
+    /** Invalidate all cached reports for an org (call after event ingest). */
+    invalidateOrg(orgId: string): Promise<void>;
+    /**
+     * Resolve incoming events against the pipeline registry, batch-insert the
+     * matched ones, and invalidate reporting caches for affected orgs.
+     * Events for unregistered pipeline ids are dropped (and logged at WARN
+     * with sample ids so an operator can see when EventBridge is delivering
+     * events for pipelines that haven't called POST /pipelines/registry yet).
+     *
+     * Returns counts + a sample of unregistered pipeline ids for observability.
+     */
+    ingestEvents(events: IngestEvent[], onMetric?: (m: IngestMetric) => void): Promise<IngestResult>;
+    /**
+     * Build the org-scope predicate for a report query. With `orgIds` (the
+     * org → team rollup — a parent's `[self, ...descendants]`) it becomes an
+     * `IN (...)` over the subtree; otherwise the single-org `= $org`. Returns a
+     * `multi` flag so callers can run multi-org reads under sysadmin context
+     * (the subtree spans orgs outside the request's RLS scope) and salt the
+     * cache key.
+     */
+    private orgScope;
+    /**
+     * Run a report read. Single-org reads use the per-org cache (invalidated on
+     * that org's event ingest). Rollup (multi-org) reads **bypass the cache** and
+     * run under sysadmin context: they're admin-only and lower-frequency, and a
+     * child org's event ingest can't invalidate a parent's rollup entry (reporting
+     * has no org tree), so caching them would serve stale aggregates. Always fresh.
+     */
+    private runReport;
+    /** 1.1 Execution count per pipeline with status breakdown. */
+    getExecutionCount(orgId: string, orgIds?: string[], range?: {
+        from?: string;
+        to?: string;
+    }): Promise<ExecutionCount[]>;
+    /**
+     * 1.1b Per-pipeline execution history — DISTINCT executions for one pipeline,
+     * newest first. Groups all events by `execution_id` in a single scan and
+     * rolls each execution up to one row:
+     *   - status: derived from the PIPELINE-type events. FAILED wins, then
+     *     SUCCEEDED, then CANCELED; an execution with no terminal PIPELINE event
+     *     is still `in-progress`.
+     *   - startedAt/endedAt/durationMs: from the PIPELINE lifecycle events.
+     *   - failingStage/failingAction: the first FAILED STAGE/ACTION event (cheap —
+     *     same scan, no extra query).
+     *
+     * ORG-SCOPING: identical to the sibling execution reports — joins the pipeline
+     * registry table (`pipeline`) and gates on `p.org_id ${pred}`, where `pred` is
+     * the single-org `= $org` or (with a rollup) an `IN (...)` over the org→team
+     * subtree. A pipelineId belonging to another org yields zero rows.
+     */
+    listPipelineExecutions(orgId: string, pipelineId: string, orgIds?: string[], range?: {
+        from?: string;
+        to?: string;
+    }, limit?: number): Promise<PipelineExecution[]>;
+    /** 1.2 Success rate over time for an org. */
+    getSuccessRate(orgId: string, interval: string, from: string, to: string, orgIds?: string[]): Promise<TimeSeriesEntry[]>;
+    /** 1.3 Average duration per pipeline. */
+    getAverageDuration(orgId: string, from: string, to: string, orgIds?: string[]): Promise<DurationStats[]>;
+    /** 1.5 Stage failure heatmap — which stages fail most. */
+    getStageFailures(orgId: string, from: string, to: string, orgIds?: string[]): Promise<StageFailure[]>;
+    /**
+     * Distinct deploy `environment` values observed in the window — powers the
+     * DORA environment-scope datalist. Org-scoped + rollup-aware like the sibling
+     * reports; only non-null environments (i.e. deploy-attributed executions).
+     */
+    getReportEnvironments(orgId: string, from: string, to: string, orgIds?: string[]): Promise<string[]>;
+    /** 1.6 Stage bottlenecks — slowest stages per pipeline. */
+    getStageBottlenecks(orgId: string, from: string, to: string, orgIds?: string[]): Promise<StageBottleneck[]>;
+    /** 1.7 Action failure rate — which plugin steps fail most. */
+    getActionFailures(orgId: string, from: string, to: string, orgIds?: string[]): Promise<ActionFailure[]>;
+    /**
+     * 1.8 Error categorization — group failure messages. Execution report, so
+     * rollup-aware exactly like the sibling execution reports: with `orgIds`
+     * (the org→team subtree) the org gate becomes an `IN (...)` and the read runs
+     * fresh under sysadmin via `runReport`; single-org reads keep the per-org cache.
+     */
+    getErrors(orgId: string, from: string, to: string, limit?: number, orgIds?: string[]): Promise<ErrorEntry[]>;
+    /**
+     * 1.9 DORA metrics over a [from,to] deploy-completion window, org-scoped +
+     * rollup-aware. DEPLOY-BASIS ONLY — every metric derives from real deploy-stage
+     * executions (`event_type='STAGE'` with a non-null `environment`, set by the
+     * forwarder for the stages a user declared in `pb.deploys`). No run-based
+     * fallback: a pipeline with no deploy stage produces no DORA data.
+     *
+     * Four scoped SQL scans run inside one tx (each org-gated by `p.org_id ${pred}`
+     * / `o.org_id ${pred}` so a rollup passes the org→team subtree and a foreign
+     * org's rows never enter): (1) terminal deploy rows PER (execution, env) — one
+     * "deployment" = one execution reaching an env (D1) — → DF / deploy-time CFR /
+     * measured lead time (lead time joins the execution's earliest commit, D2);
+     * the scan also reaches back `windowHours` before `from` so incidents opened
+     * near the window start can correlate to a just-prior deploy; (2) `deployment_outcomes`
+     * in-window → post-deploy CFR component; (3) production restored/failed
+     * outcomes joined to their deploy → MTTR; (4) registry vs deploying → coverage.
+     * The cross-source medians (lead time, MTTR) are computed in JS from clamped
+     * (≥0) deltas.
+     *
+     * @param opts.pipelineId    restrict to one pipeline (per-pipeline DORA)
+     * @param opts.environment   restrict to one deploy environment
+     */
+    getDoraMetrics(orgId: string, from: string, to: string, orgIds?: string[], opts?: DoraOptions): Promise<DoraMetrics>;
+    /**
+     * Shape the raw DORA scan rows into the public {@link DoraMetrics}. Buckets the
+     * terminal deploy rows by environment (DF / deploy-time CFR / measured lead),
+     * folds in the post-deploy failure counts (manual outcomes + webhook-ingested
+     * incidents, deduped by deploy execution), computes production MTTR from both
+     * sources (incident `resolved_at − opened_at` taking precedence over the manual
+     * `restored − deployed`), and reconciles coverage — all cross-source medians
+     * over deltas clamped ≥0.
+     *
+     * Phase 5 incident correlation: each incident is attributed to the most recent
+     * SUCCESSFUL deploy to its environment with `completed_at ≤ opened_at` within
+     * {@link DORA_INCIDENT_WINDOW_HOURS}. That deploy is a post-deploy failure; an
+     * uncorrelated incident (no eligible deploy) contributes nothing.
+     */
+    private shapeDora;
+    /**
+     * 1.9b DORA trend — deployment frequency + deploy-time change-failure rate
+     * bucketed by `interval` (day/week/month) for a sparkline. Deploy-basis like
+     * getDoraMetrics: buckets terminal deploy-stage executions on their
+     * `completed_at`. Shares the org/rollup + pipelineId/environment scoping. MTTR,
+     * lead time, and post-deploy CFR are intentionally omitted (too heavy to bucket).
+     */
+    getDoraTrend(orgId: string, interval: string, from: string, to: string, orgIds?: string[], opts?: DoraOptions): Promise<DoraTrendPoint[]>;
+    /**
+     * 1.10 Per-pipeline BUILD HEALTH (Phase 6) — a standard (NOT `advanced_reporting`)
+     * per-stage breakdown for one pipeline over a [from,to] window. Aggregates the
+     * existing `pipeline_events` STAGE rows: each stage is rolled up per execution
+     * to a terminal status (FAILED wins, then SUCCEEDED) + its max duration, then
+     * grouped per stage into run/success/failure counts, a success rate, and
+     * duration percentiles (p50/p90/p99). Totals sum across stages. Org-scoped via
+     * the pipeline join (`p.org_id ${pred}`) + rollup-aware like the sibling reports;
+     * a pipelineId owned by another org returns an empty breakdown.
+     */
+    getBuildHealth(orgId: string, pipelineId: string, from: string, to: string, orgIds?: string[]): Promise<BuildHealth>;
+    /** 2.1 Plugin summary — counts and breakdowns.
+     *  INTENTIONALLY SINGLE-ORG (no rollup): plugin inventory is an org-owned
+     *  asset count, not an execution/build activity report, so a parent's view is
+     *  its own plugins — teams manage their own inventory. Single `= $org` scope. */
+    getPluginSummary(orgId: string): Promise<PluginSummary>;
+    /** 2.2 Type & compute distribution.
+     *  INTENTIONALLY SINGLE-ORG (no rollup): plugin inventory is per-org (see
+     *  getPluginSummary). Single `= $org` scope. */
+    getPluginDistribution(orgId: string): Promise<TypeComputeDistribution[]>;
+    /** 2.3 Version counts per plugin name.
+     *  INTENTIONALLY SINGLE-ORG (no rollup): plugin inventory is per-org (see
+     *  getPluginSummary). Single `= $org` scope. */
+    getPluginVersions(orgId: string): Promise<VersionCount[]>;
+    /**
+     * 2.4 Build success rate over time.
+     *
+     * STATUS CASING NOTE: This query filters by `event_source = 'plugin-build'`
+     * and uses lowercase status values (`'completed'`, `'failed'`), while
+     * `getSuccessRate` (1.2) filters by `event_type = 'PIPELINE'` with
+     * uppercase AWS-style statuses (`'SUCCEEDED'`, `'FAILED'`, `'CANCELED'`).
+     * The casing drift is intentional and tracks the producer:
+     *   - `plugin-build` events come from our own build pipeline (lowercase)
+     *   - `PIPELINE` events come from AWS CodePipeline (uppercase)
+     * The ingest Zod schema at api/reporting/src/routes/event-ingest.ts
+     * SHOULD enum these per-eventSource so we catch drift at ingest rather
+     * than silently producing zero rows here. See findings N71.
+     */
+    getBuildSuccessRate(orgId: string, interval: string, from: string, to: string, orgIds?: string[]): Promise<BuildTimeSeriesEntry[]>;
+    /** 2.5 Build duration per plugin. Build activity report — rollup-aware. */
+    getBuildDuration(orgId: string, from: string, to: string, orgIds?: string[]): Promise<BuildDuration[]>;
+    /** 2.6 Build failures — top error messages. Build activity report — rollup-aware. */
+    getBuildFailures(orgId: string, from: string, to: string, limit?: number, orgIds?: string[]): Promise<BuildFailure[]>;
+    /**
+     * Record a manual post-deploy outcome marker (Phase 2): a user marks a
+     * deployment `failed` (a production incident linked to the deploy) or
+     * `restored` (recovered). Idempotent — keyed on (execution_id, outcome) so a
+     * duplicate POST refreshes `at` rather than double-counting, while a
+     * failed→restored pair stays two rows. Feeds the post-deploy CFR component and
+     * the real MTTR. Runs under the caller's org context (RLS WITH CHECK).
+     */
+    recordDeploymentOutcome(orgId: string, executionId: string, input: {
+        outcome: 'failed' | 'restored';
+        at: string;
+        environment?: string;
+    }): Promise<void>;
+    /**
+     * Ingest a production incident (Phase 5) from the org's incident tooling
+     * (PagerDuty / Datadog / Alertmanager webhook). Idempotent — keyed on
+     * (org_id, incident_id) so a later resolve re-post upserts `resolved_at`
+     * (and refreshes the other mutable fields) instead of inserting a duplicate.
+     * DORA correlates each incident to the most recent successful deploy to its
+     * `environment`, producing an automated post-deploy failure + a real MTTR.
+     * Runs under the caller's org context (RLS WITH CHECK); free-form fields are
+     * AWS-id scrubbed at this persistence boundary like the other ingest paths.
+     */
+    recordIncident(orgId: string, input: IncidentInput): Promise<void>;
+    /**
+     * Read the per-org DORA settings (Phase 5b). Returns the stored
+     * `incidentWindowHours` override (or `null` when unset) plus the global env
+     * default, so the settings UI can show both. Runs under the caller's tenant
+     * context (RLS-scoped); a single-org read.
+     */
+    getIncidentSettings(orgId: string): Promise<IncidentSettings>;
+    /**
+     * Upsert per-org reporting settings (Phase 5b incident window + Phase 7
+     * retention overrides), idempotent on `org_id`. A partial write — only the
+     * fields present in `patch` are set (so updating retention never clears the
+     * incident window, and vice-versa). Set self-serve by an org admin via
+     * `PUT /api/reports/settings/incidents`. Runs under the caller's org context
+     * (RLS WITH CHECK); a changed value affects DORA aggregates so the org's
+     * cached reports are dropped.
+     */
+    setReportingSettings(orgId: string, patch: ReportingSettingsPatch): Promise<void>;
+    /**
+     * List recent incidents for an org (Phase 5b org-admin surface), newest first,
+     * paginated. Each row carries its resolved state and its deploy correlation —
+     * the most recent SUCCESSFUL deploy to the incident's `environment` whose
+     * `completed_at` falls within the effective per-org correlation window before
+     * `opened_at` (the same rule DORA's CFR/MTTR correlation applies). Single-org
+     * (no rollup) — an org admin views their own org's incidents. RLS-scoped via
+     * the `p.org_id`/`i.org_id` predicates + the tenant context.
+     */
+    listIncidents(orgId: string, opts: {
+        limit: number;
+        offset: number;
+    }): Promise<IncidentListItem[]>;
+    /**
+     * Wiring-test dry-run (Phase 5b): would a synthetic incident opening NOW for
+     * `environment` correlate to a recent successful deploy under the org's
+     * effective window? This is a NON-persisting correlation check — it verifies
+     * the admin's environment naming + window line up with real deploy events
+     * WITHOUT writing an incident (so a "test" never pollutes CFR/MTTR). RLS-scoped.
+     */
+    testIncidentCorrelation(orgId: string, environment: string): Promise<IncidentTestResult>;
+    /**
+     * Upsert per-org ingestion health (Phase 3): the AWS events Lambda periodically
+     * reports forwarded/dropped counters + the last event timestamp so the Reports
+     * UI can show flowing / stale / dropping. One row per org (upsert on org_id).
+     */
+    recordIngestHealth(orgId: string, input: {
+        forwarded?: number;
+        dropped?: number;
+        lastEventAt?: string;
+    }): Promise<void>;
+    /**
+     * Reporting retention sweep (Phase 7). Hard-deletes rows older than their
+     * retention window, by `created_at`, across every org that has reporting data —
+     * a **split** policy so high-volume standard events expire faster than the
+     * low-volume DORA source:
+     *  - `pipeline_events WHERE environment IS NULL` → standard-event window.
+     *  - `pipeline_events WHERE environment IS NOT NULL` (deploy stages),
+     *    `deployment_outcomes`, and `incidents` → DORA-source window.
+     * Each org's windows come from its `dora_settings` override, else the global
+     * env defaults (see {@link resolveEventRetentionDays} / {@link resolveDoraRetentionDays}).
+     * `ingest_health` and `dora_settings` are never purged. One `now` for the whole
+     * tick (rows crossing the boundary mid-sweep wait for the next). Establishes a
+     * sysadmin tenant scope so the deletes span all orgs / bypass RLS — this is a
+     * cross-tenant housekeeping job. Returns (and logs) per-window purge tallies.
+     */
+    purgeExpiredReportingData(opts?: ReportingRetentionOptions): Promise<ReportingRetentionCounts>;
+}
+export declare const reportingService: ReportingService;
+export {};