@pipeline-builder/pipeline-data 3.4.125 → 3.4.127

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

@@ -100,6 +100,54 @@ interface BuildFailure {
     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
@@ -110,110 +158,216 @@ export type DoraLevel = 'elite' | 'high' | 'medium' | 'low' | null;
 export interface DoraOptions {
     /** Restrict to a single pipeline (per-pipeline DORA). */
     pipelineId?: string;
-    /** Count only executions deployed to this environment (deploy-scoped). */
+    /** Restrict to a single deploy environment (else all deploy environments). */
     environment?: string;
-    /** Count only executions tagged with ANY environment (real deployments). */
-    deploysOnly?: boolean;
+    /**
+     * 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).
  *
- * A "deployment" is a TERMINAL pipeline-level event, rolled up to one row per
- * `execution_id` (FAILED wins, then SUCCEEDED, then CANCELED/STOPPED — same
- * precedence as `listPipelineExecutions`).
+ * 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.
  *
- * DISCLOSURE — these are RUN-BASED approximations of DORA. A "deployment" here
- * is any successful pipeline RUN, not a verified production deployment: the
- * event stream carries no deploy-stage/environment marker, so a CI-only
- * build/test pipeline counts the same as one that ships to prod. That makes
- * `deploymentFrequency` a pipeline-throughput signal and `changeFailureRate` a
- * pipeline-failure rate (build/test failures caught in CI count too), and MTTR
- * a pipeline-recovery time. Only `leadTime` carries an explicit `approx` flag
- * (it is additionally a run-time proxy), but ALL four share the run≠deploy
- * caveat until deploy/commit metadata is captured. See docs/dora-metrics.md.
+ * `production` is the headline environment; MTTR is measured production-only.
  */
 export interface DoraMetrics {
-    /** The [from,to] window echoed back (started_at range). */
+    /** The [from,to] window echoed back (deploy `completed_at` range). */
     window: {
         from: string;
         to: string;
     };
-    /**
-     * Whether the numbers count real deployments or pipeline runs:
-     * - `'deploy'` — scoped to executions tagged with a deploy `environment`
-     *   (via `environment`/`deploysOnly`); a genuine deployment signal.
-     * - `'run'` — default: every successful PIPELINE run counts (no deploy
-     *   marker applied). DF/CFR/MTTR then reflect pipeline activity, not deploys.
-     */
-    basis: 'deploy' | 'run';
     /** The scoping applied (echoed for the UI); `null` when unscoped. */
     filters: {
         pipelineId: string | null;
         environment: string | null;
     };
-    /** Deployment Frequency — SUCCEEDED terminal deployments in the window. */
+    /** 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: {
-        /** Count of successful deployments. */
         deployments: number;
-        /** Successful deployments per day over the window. */
         perDay: number;
-        /** Performance band, or null when there were no deployments. */
         level: DoraLevel;
     };
-    /** Change Failure Rate — failed / (succeeded + failed); CANCELED excluded. */
+    /**
+     * 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: {
-        failed: number;
-        /** succeeded + failed (the CFR denominator). */
-        total: number;
-        /** failed/total as a percentage, 0–100, 1 decimal. */
-        pct: number;
-        /** Performance band, or null when there were no deployments to judge. */
+        rate: number;
+        deployTimeFailures: number;
+        postDeployFailures: number;
+        attempts: number;
         level: DoraLevel;
     };
-    /** Mean Time To Restore — avg gap from a failure INCIDENT to its recovery.
-     *  Consecutive failed runs of a pipeline (with no green run between) collapse
-     *  into one incident; the gap is measured from the first failure's END to the
-     *  recovering run's END. The recovery is visible up to a look-ahead past `to`
-     *  so a failure near the window edge isn't spuriously counted unrestored. */
-    meanTimeToRestore: {
-        /** Failure incidents in the window (maximal runs of consecutive failures). */
-        failures: number;
-        /** Incidents that were followed by a succeeded run (recovered). */
-        restored: number;
-        /** Average restore gap in seconds; null when there were no incidents. */
-        avgSeconds: number | null;
-        /** Performance band, or null when there were no incidents. */
-        level: DoraLevel;
-    };
-    /** Lead Time — PROXY: median pipeline RUN TIME of succeeded deployments.
-     *  NOT true commit→prod lead time (executions don't capture commit time),
-     *  hence `approx: true` so the UI/docs can label it. */
+    /**
+     * 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: {
-        /** Succeeded deployments with a duration (the median sample). */
+        /** Successful deploys with a resolvable commit time (the median sample). */
         deployments: number;
-        /** Median run time in seconds; null when no successful deployments. */
         medianSeconds: number | null;
-        approx: true;
-        /** Performance band, or null when there were no successful deployments. */
         level: DoraLevel;
     };
 }
-/** One interval bucket of the DORA trend (deployment frequency + change failure). */
+/** One interval bucket of the DORA trend (deploy frequency + change failure). */
 export interface DoraTrendPoint {
-    /** Bucket start (DATE_TRUNC of started_at), ISO text. */
+    /** Bucket start (DATE_TRUNC of the deploy `completed_at`), ISO text. */
     period: string;
-    /** Successful deployments in the bucket. */
+    /** Successful deploy-stage executions in the bucket. */
     deployments: number;
-    /** Failed deployments in the bucket. */
+    /** Failed deploy-stage executions in the bucket. */
     failed: number;
-    /** succeeded + failed in the bucket. */
+    /** succeeded + failed in the bucket (deploy attempts). */
     total: number;
-    /** failed/total as a percent (0 when total is 0). */
+    /** 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 `PIPELINE_EVENT_ID`
+    /** 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';
@@ -231,10 +385,29 @@ export interface IngestEvent {
     commitSha?: string;
     /** Source ref/branch (DORA deploy attribution). */
     commitRef?: string;
-    /** Deploy target (e.g. "production"). Its presence marks a real deployment. */
+    /** 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;
@@ -250,6 +423,7 @@ export interface IngestResult {
  * - 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>;
     /**
@@ -261,7 +435,7 @@ export declare class ReportingService {
      *
      * Returns counts + a sample of unregistered pipeline ids for observability.
      */
-    ingestEvents(events: IngestEvent[]): Promise<IngestResult>;
+    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
@@ -328,43 +502,62 @@ export declare class ReportingService {
      */
     getErrors(orgId: string, from: string, to: string, limit?: number, orgIds?: string[]): Promise<ErrorEntry[]>;
     /**
-     * 1.9 DORA metrics over [from,to] (started_at range), org-scoped + rollup-aware.
-     *
-     * All four metrics derive from a per-execution roll-up of TERMINAL PIPELINE
-     * events (one row per execution_id+pipeline_id; FAILED wins, then SUCCEEDED,
-     * then CANCELED/STOPPED — mirroring `listPipelineExecutions`). The scan is
-     * gated by the `p.org_id ${pred}` join exactly like the sibling reports, so a
-     * rollup passes the org→team subtree and a foreign org's executions never
-     * enter the aggregate.
-     *
-     * DF/CFR/lead-time count only CORE-window executions ([from,to]). MTTR is
-     * per-INCIDENT: consecutive failures collapse into one incident and the
-     * recovery lookup may see the next success up to MTTR_RESTORE_LOOKAHEAD past
-     * `to`, so a failure near the edge isn't right-censored into "never restored".
-     * The scan bound is therefore `[from, to + look-ahead]`; the started_at range
-     * still rides the same index as the sibling reports.
+     * 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.
      *
-     * DISCLOSURE: by default DF/CFR/MTTR are RUN-based (any successful PIPELINE
-     * run = a "deployment"), and Lead Time is additionally a run-time PROXY
-     * flagged `approx: true`. Pass `environment` or `deploysOnly` to scope to
-     * executions tagged with a real deploy target — the response `basis` reports
-     * which was used. See the DoraMetrics doc + docs/dora-metrics.md.
+     * 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   count only executions deployed to this target
-     * @param opts.deploysOnly   count only executions tagged with ANY environment
+     * @param opts.environment   restrict to one deploy environment
      */
     getDoraMetrics(orgId: string, from: string, to: string, orgIds?: string[], opts?: DoraOptions): Promise<DoraMetrics>;
-    /** Shape a single DORA aggregate row into the public {@link 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 + change-failure rate bucketed by
-     * `interval` (day/week/month) for a sparkline. Per-execution rollup (one row
-     * per execution, FAILED wins) bucketed on the execution's started_at. Shares
-     * the `getDoraMetrics` scoping (org/rollup, pipelineId, deploy-scoping); MTTR
-     * and lead time are intentionally omitted (too heavy to bucket meaningfully).
+     * 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
@@ -397,6 +590,94 @@ export declare class ReportingService {
     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 {};