@prism-d1/cli 1.0.79 → 1.0.80

package/dist/assets/infra/lib/lambda/event-schema.ts

@@ -0,0 +1,144 @@
+/**
+ * Canonical PRISM event schema — the contract between emitters and the pipeline.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The event payload is a wide union of optional sections that producers fill
+ * selectively. Nothing validated it, and every silent failure in this pipeline
+ * traced back to that gap:
+ *
+ *   - prism-dora-weekly.yml emitted `dora.lead_time_hours` while the processor
+ *     read `lead_time_seconds`. The `!= null` guard skipped it, so the
+ *     LeadTimeForChanges metric was never published and nothing errored.
+ *   - It emitted `dora.mttr_hours` against `mttr_seconds`, so the MTTR metric
+ *     was never published at all.
+ *   - `ai_dora.ai_adoption_rate` matched no key the processor consumed.
+ *   - The `pr` section was emitted by producers for months but missing from the
+ *     processor's persisted-section list, so every field was dropped at write.
+ *   - GitHub emitted `pr` while GitLab emitted `mr` for the same concept.
+ *
+ * None of those threw. They produced plausible-looking dashboards with missing
+ * data. Declaring the shape here and validating against it converts that class
+ * of failure from silent to loud.
+ */
+
+/** Sections persisted to the events table. Anything not listed is DROPPED. */
+export const PERSISTED_SECTIONS = [
+  'metric',
+  'ai_context',
+  'dora',
+  'ai_dora',
+  'eval',
+  'guardrail',
+  'mcp_tool_call',
+  'agent',
+  'security',
+  'security_agent_finding',
+  'security_remediation',
+  'pr',
+] as const;
+
+export type PersistedSection = (typeof PERSISTED_SECTIONS)[number];
+
+/**
+ * Known field names per section. Used by validateEventShape to flag fields a
+ * producer emits that no consumer reads — the `lead_time_hours` class of bug.
+ *
+ * This is intentionally a denylist-by-omission: unknown fields are WARNED about,
+ * not rejected, so adding a field is never a hard outage. The CI guard
+ * (scripts/check-metric-coverage.ts) is what fails the build.
+ */
+export const SECTION_FIELDS: Record<PersistedSection, readonly string[]> = {
+  metric: ['name', 'value', 'unit'],
+  ai_context: ['tool', 'model', 'origin', 'origin_source'],
+  dora: [
+    'deployment_frequency',
+    'lead_time_seconds',
+    'change_failure_rate',
+    'mttr_seconds',
+    'is_failure_fix',
+  ],
+  ai_dora: ['eval_gate_pass_rate'],
+  eval: ['eval_id', 'rubric', 'result', 'score', 'findings', 'high_findings', 'pr_number', 'criterion_scores'],
+  guardrail: ['guardrail_id', 'trigger_category', 'trigger_type', 'action_taken', 'agent_name'],
+  mcp_tool_call: ['session_id', 'client_id', 'tool_name', 'scopes', 'authorized', 'risk_level', 'result_status', 'duration_ms'],
+  agent: ['agent_name', 'status', 'duration_ms', 'steps_taken', 'tools_invoked', 'tokens_used', 'guardrails_triggered'],
+  security: ['alert_type', 'table_name', 'principal_arn', 'read_count'],
+  security_agent_finding: [
+    'finding_id', 'phase', 'severity', 'cvss_score', 'title', 'description',
+    'category', 'cwe_id', 'exploit_validated', 'remediation_guidance',
+    'compliance_mappings', 'ai_origin', 'commit_shas', 'pr_number',
+    'commit_sha', 'spec_ref', 'environment', 'found_at', 'remediated_at',
+  ],
+  security_remediation: [
+    'finding_id', 'severity', 'remediation_time_hours', 'remediated_by_origin',
+    'remediated_by_origin_source', 'fix_commit_shas', 'fix_pr_number', 'finding_phase',
+  ],
+  pr: [
+    'number', 'author', 'reviews_approved', 'reviews_changes_requested',
+    'total_commits', 'commit_shas',
+  ],
+};
+
+/**
+ * Units matter: these fields have caused real bugs by carrying the wrong unit
+ * under a plausible name. A producer emitting `lead_time_hours` is emitting a
+ * field this pipeline does not read — the suffix is load-bearing.
+ */
+export const UNIT_SUFFIXED_FIELDS = [
+  'lead_time_seconds',
+  'mttr_seconds',
+  'remediation_time_hours',
+  'duration_ms',
+] as const;
+
+export interface ShapeWarning {
+  section: string;
+  field?: string;
+  message: string;
+}
+
+/**
+ * Non-throwing shape validation. Returns warnings for the processor to log so
+ * field drift shows up in CloudWatch Logs Insights instead of vanishing.
+ *
+ * Deliberately does NOT reject: dropping a real event because a producer added
+ * a field would be a worse failure than logging it.
+ */
+export function validateEventShape(detail: Record<string, unknown>): ShapeWarning[] {
+  const warnings: ShapeWarning[] = [];
+  const known = new Set<string>(PERSISTED_SECTIONS);
+
+  for (const [key, value] of Object.entries(detail)) {
+    // Envelope fields live alongside sections and are handled separately.
+    if (['team_id', 'repo', 'timestamp', 'prism_level'].includes(key)) continue;
+
+    if (!known.has(key)) {
+      warnings.push({
+        section: key,
+        message: `section '${key}' is not in PERSISTED_SECTIONS and will be DROPPED at write time`,
+      });
+      continue;
+    }
+
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      const allowed = SECTION_FIELDS[key as PersistedSection];
+      for (const field of Object.keys(value as Record<string, unknown>)) {
+        if (!allowed.includes(field)) {
+          // Near-miss on a unit suffix is the highest-signal case.
+          const nearMiss = UNIT_SUFFIXED_FIELDS.find(
+            f => f.split('_').slice(0, -1).join('_') === field.split('_').slice(0, -1).join('_'),
+          );
+          warnings.push({
+            section: key,
+            field,
+            message: nearMiss
+              ? `'${key}.${field}' is not consumed — did you mean '${nearMiss}'? Unit suffixes are load-bearing.`
+              : `'${key}.${field}' is not consumed by any reader`,
+          });
+        }
+      }
+    }
+  }
+  return warnings;
+}

package/dist/assets/infra/lib/lambda/metrics-processor.ts

@@ -1,3 +1,4 @@
+import { PERSISTED_SECTIONS, validateEventShape } from './event-schema';
 import {
   DynamoDBClient,
   PutItemCommand,
@@ -22,6 +23,28 @@ interface DoraMetrics {
   lead_time_seconds: number | null;
   change_failure_rate: number | null;
   mttr_seconds: number | null;
+  /**
+   * Per-PR failure-fix label (title matched revert|hotfix|rollback). This is the
+   * change-failure-rate NUMERATOR as a fact; the rate and MTTR are computed at
+   * query time by the dashboard widgets over the selected window. Emitting a
+   * pre-computed rate per PR was meaningless (0% or 100%) and a pre-computed
+   * weekly rate hardcoded a 7-day window the dashboard could not override.
+   */
+  is_failure_fix?: boolean;
+}
+
+/**
+ * Per-PR facts from prism-ai-metrics.yml. Persisted so the dashboard can
+ * aggregate at query time and resolve AI origin by joining commit_shas against
+ * the attribution store.
+ */
+interface PrDetail {
+  number: number;
+  author: string;
+  reviews_approved: number;
+  reviews_changes_requested: number;
+  total_commits?: number;
+  commit_shas?: string[];
 }
 
 interface AiDoraMetrics {
@@ -95,7 +118,19 @@ interface SecurityAgentFinding {
   cwe_id: string | null;
   exploit_validated: boolean;
   compliance_mappings: string[];
-  ai_origin: string;
+  /**
+   * Trailer-derived origin. Legacy — emitters now send `commit_shas` instead
+   * and dashboards resolve origin at render time against the attribution
+   * store. Retained so events emitted before the cutover still parse.
+   */
+  ai_origin?: string;
+  /**
+   * Commit SHAs the finding's PR introduced. Immutable facts — the deferred
+   * join reads these at query time, which is correct even when the PR merged
+   * before `codeburn sync --attribution` had run for those commits.
+   */
+  commit_shas?: string[];
+  pr_number?: number;
   spec_ref: string | null;
   found_at: string;
   remediated_at: string | null;
@@ -105,7 +140,17 @@ interface SecurityRemediationDetail {
   finding_id: string;
   severity: string;
   remediation_time_hours: number;
+  /**
+   * Trailer-derived verdict for who fixed the finding. Legacy — reads 'human'
+   * for everything once git hooks are removed. Dashboards prefer
+   * `fix_commit_shas` and only fall back to this. See the deferred-join note
+   * on SecurityAgentFinding.commit_shas.
+   */
   remediated_by_origin: string;
+  remediated_by_origin_source?: string;
+  /** Fix PR's commit SHAs — joined against the attribution store at render time. */
+  fix_commit_shas?: string[];
+  fix_pr_number?: number | null;
   finding_phase: string;
 }
 
@@ -134,6 +179,7 @@ interface MetricDetail {
   security?: SecurityDetail;
   security_agent_finding?: SecurityAgentFinding;
   security_remediation?: SecurityRemediationDetail;
+  pr?: PrDetail;
 }
 
 interface EventBridgeEvent {
@@ -155,13 +201,10 @@ const METRIC_NAMESPACE = process.env.METRIC_NAMESPACE ?? 'PRISM/D1/Velocity';
 // ---- Handler ----
 
 export async function handler(event: EventBridgeEvent): Promise<void> {
-  console.log('[metrics-processor] Received event:', JSON.stringify(event, null, 2));
-
   const detailType = event['detail-type'];
   const detail = event.detail;
 
   console.log(`[metrics-processor] detail-type=${detailType} team_id=${detail?.team_id} repo=${detail?.repo} timestamp=${detail?.timestamp}`);
-  console.log(`[metrics-processor] dora=${JSON.stringify(detail?.dora)} ai_dora=${JSON.stringify(detail?.ai_dora)} metric=${JSON.stringify(detail?.metric)}`);
 
   if (!detail.team_id) {
     console.log('[metrics-processor] No team_id provided, defaulting to "no_team"');
@@ -179,21 +222,27 @@ export async function handler(event: EventBridgeEvent): Promise<void> {
     publishCloudWatchMetrics(detailType, detail),
   ]);
 
+  const labels = ['writeEventToDynamo', 'writeMetadataToDynamo', 'publishCloudWatchMetrics'];
   results.forEach((result, idx) => {
-    const labels = ['writeEventToDynamo', 'writeMetadataToDynamo', 'publishCloudWatchMetrics'];
-    if (result.status === 'fulfilled') {
-      console.log(`[metrics-processor] ${labels[idx]} succeeded`);
-    } else {
+    if (result.status === 'rejected') {
       console.error(`[metrics-processor] ${labels[idx]} FAILED:`, result.reason);
     }
   });
 
-  const failures = results.filter((r) => r.status === 'rejected');
-  if (failures.length > 0) {
-    throw new Error(`${failures.length} operation(s) failed — check logs above`);
+  // Only DynamoDB write failures are retryable — the events table is the
+  // source of truth and DDB writes are idempotent (same pk/sk overwrites).
+  // CloudWatch metric publishing is best-effort: retrying a whole invocation
+  // because PutMetricData throttled creates a self-amplifying retry storm
+  // (more retries -> more PutMetricData calls -> more throttling). This
+  // exact loop ran at ~108M invocations/day in July 2026 and wrote 445 GB
+  // of logs before stopping. Metrics lost to throttling are an acceptable
+  // gap; events lost from DDB are not.
+  const ddbFailures = results.slice(0, 2).filter((r) => r.status === 'rejected');
+  if (ddbFailures.length > 0) {
+    throw new Error(`${ddbFailures.length} DynamoDB write(s) failed — retrying event`);
   }
 
-  console.log(`[metrics-processor] Successfully processed ${detailType} for ${detail.team_id}/${detail.repo}`);
+  console.log(`[metrics-processor] Processed ${detailType} for ${detail.team_id}/${detail.repo}`);
 }
 
 // ---- DynamoDB events ----
@@ -211,22 +260,42 @@ async function writeEventToDynamo(
     prism_level: detail.prism_level ?? '1',
   };
 
-  if (detail.metric) {
-    data.metric = detail.metric;
-  }
-  if (detail.ai_context) {
-    data.ai_context = detail.ai_context;
+  // Persist every payload section — the events table is the source of truth
+  // for DDB-backed dashboard panels and replay. (Previously only the first
+  // four were stored, silently dropping eval/guardrail/mcp/agent/security
+  // payloads from the durable record.)
+  // Shape validation: logs field drift instead of letting it vanish. See
+  // event-schema.ts for the failures that motivated this.
+  for (const w of validateEventShape(detail as unknown as Record<string, unknown>)) {
+    console.warn(`[schema] ${w.message}`);
   }
-  if (detail.dora) {
-    data.dora = detail.dora;
-  }
-  if (detail.ai_dora) {
-    data.ai_dora = detail.ai_dora;
+
+  const sections = PERSISTED_SECTIONS;
+  for (const key of sections) {
+    if ((detail as Record<string, unknown>)[key]) {
+      data[key] = (detail as Record<string, unknown>)[key];
+    }
   }
 
+  // Sort key. Events that fan out PER FINDING (security findings, and one
+  // remediation per finding resolved by a merged PR) all carry the SAME
+  // timestamp — the scan time or the PR merge time. With sk = timestamp alone
+  // they collide on (pk, sk) and silently overwrite each other: a PR fixing
+  // three findings stored exactly one remediation event. Appending the
+  // finding id disambiguates them while preserving the timestamp prefix, so
+  // `sk BETWEEN :from AND :to` range queries and lexicographic time ordering
+  // still work. Follows the existing `SPAN#${ts}#${spanId}` convention in
+  // otel-receiver.ts. Pre-existing items keep bare-timestamp sks; readers
+  // split on '#', which is a no-op for those.
+  const findingDiscriminator =
+    detail.security_agent_finding?.finding_id ?? detail.security_remediation?.finding_id;
+  const sortKey = findingDiscriminator
+    ? `${detail.timestamp}#${findingDiscriminator}`
+    : detail.timestamp;
+
   const item: Record<string, { S?: string; N?: string }> = {
     pk: { S: `${detail.team_id}#${detail.repo}` },
-    sk: { S: detail.timestamp },
+    sk: { S: sortKey },
     detail_type: { S: detailType },
     data: { S: JSON.stringify(data) },
     ttl: { N: ttl.toString() },
@@ -328,9 +397,6 @@ async function publishCloudWatchMetrics(
   detailType: string,
   detail: MetricDetail,
 ): Promise<void> {
-  console.log(`[publishCloudWatchMetrics] Starting for ${detailType}, namespace=${METRIC_NAMESPACE}`);
-  console.log(`[publishCloudWatchMetrics] dora fields: deployment_frequency=${detail.dora?.deployment_frequency} lead_time_seconds=${detail.dora?.lead_time_seconds} change_failure_rate=${detail.dora?.change_failure_rate} mttr_seconds=${detail.dora?.mttr_seconds}`);
-  console.log(`[publishCloudWatchMetrics] ai_dora fields: ai_acceptance_rate=${detail.ai_dora?.ai_acceptance_rate} ai_to_merge_ratio=${detail.ai_dora?.ai_to_merge_ratio} eval_gate_pass_rate=${detail.ai_dora?.eval_gate_pass_rate}`);
 
   const sharedDimensions = [
     { Name: 'TeamId', Value: detail.team_id },
@@ -430,17 +496,37 @@ async function publishCloudWatchMetrics(
         Timestamp: metricTimestamp,
       });
     }
+    // Change-failure NUMERATOR as a counter. The CFR alarm divides this by
+    // DeploymentFrequency via metric math, so the ratio is evaluated over the
+    // alarm's own window instead of a window baked in at emit time. Emitted on
+    // every merged PR (0 or 1) so the alarm sees a real zero during healthy
+    // periods rather than sitting in INSUFFICIENT_DATA.
+    if (detail.dora.is_failure_fix != null) {
+      metricData.push({
+        MetricName: 'ChangeFailureCount',
+        Value: detail.dora.is_failure_fix ? 1 : 0,
+        Unit: StandardUnit.Count,
+        Dimensions: sharedDimensions,
+        Timestamp: metricTimestamp,
+      });
+    }
   }
 
   // AI-DORA metrics — scale 0–1 ratios to 0–100 for CloudWatch Percent unit
   if (detail.ai_dora) {
+    // AIAcceptanceRate and AIToMergeRatio were removed: neither had any
+    // consumer. No widget read them, and the dashboards' AI-vs-human graphs are
+    // driven by attribution metrics (AICommits / MergedAICommits / ...) via
+    // metric math instead. AIAcceptanceRate was additionally unsalvageable —
+    // gated on a trailer-derived ai_ratio, and defaulting to 100% whenever a PR
+    // had no reviews, which rewarded skipping review.
     const aiDoraMap: Array<[string, number | null, StandardUnit, boolean]> = [
-      ['AIAcceptanceRate', detail.ai_dora.ai_acceptance_rate, StandardUnit.Percent, true],
-      ['AIToMergeRatio', detail.ai_dora.ai_to_merge_ratio, StandardUnit.Percent, true],
-      ['SpecToCodeHours', detail.ai_dora.spec_to_code_hours, StandardUnit.Count, false],
-      ['PostMergeDefectRate', detail.ai_dora.post_merge_defect_rate, StandardUnit.Percent, true],
+      // EvalGatePassRate is the only survivor: it has a live producer
+      // (prism-agent-eval.yml) and a live consumer (the eval-gate alarm).
+      // SpecToCodeHours and PostMergeDefectRate were emitted by the
+      // spec-to-code-calculator and defect-correlator Lambdas, both now deleted
+      // as permanent no-ops. AITestCoverageDelta never had a producer at all.
       ['EvalGatePassRate', detail.ai_dora.eval_gate_pass_rate, StandardUnit.Percent, true],
-      ['AITestCoverageDelta', detail.ai_dora.ai_test_coverage_delta, StandardUnit.Percent, true],
     ];
 
     // Token & cost metrics come from git-trailer PR sums by default. When the
@@ -691,6 +777,13 @@ async function publishCloudWatchMetrics(
   // Security remediation metrics
   if (detail.security_remediation) {
     const remediation = detail.security_remediation;
+    // NOTE: the AIOrigin dimension here is trailer-derived and therefore
+    // legacy — dashboards resolve "who fixed it" from fix_commit_shas via the
+    // deferred attribution join instead. It is kept, and kept UNCONDITIONAL,
+    // on purpose: emitting this metric sometimes with AIOrigin and sometimes
+    // without would create a partial dimension set, which is exactly the
+    // failure that left three CISO widgets permanently empty. Full set or
+    // nothing. The dimensionless copy below is what the SLA panels read.
     metricData.push({
       MetricName: 'SecurityRemediationTimeHours',
       Value: remediation.remediation_time_hours,
@@ -721,15 +814,11 @@ async function publishCloudWatchMetrics(
   }
 
   console.log(`[publishCloudWatchMetrics] Publishing ${metricData.length} metric data points`);
-  metricData.forEach((m, i) => {
-    console.log(`[publishCloudWatchMetrics]   [${i}] ${m.MetricName}=${m.Value} unit=${m.Unit} dims=${JSON.stringify(m.Dimensions)}`);
-  });
 
   // CloudWatch accepts max 1000 metric data points per call; batch in chunks of 25
   const batchSize = 25;
   for (let i = 0; i < metricData.length; i += batchSize) {
     const batch = metricData.slice(i, i + batchSize);
-    console.log(`[publishCloudWatchMetrics] Sending batch ${Math.floor(i / batchSize) + 1} with ${batch.length} metrics`);
     try {
       await cloudwatchClient.send(
         new PutMetricDataCommand({
@@ -737,7 +826,6 @@ async function publishCloudWatchMetrics(
           MetricData: batch,
         }),
       );
-      console.log(`[publishCloudWatchMetrics] Batch ${Math.floor(i / batchSize) + 1} sent successfully`);
     } catch (err) {
       console.error(`[publishCloudWatchMetrics] Batch ${Math.floor(i / batchSize) + 1} FAILED:`, err);
       throw err;