@saptools/service-flow 0.1.72 → 0.1.73

package/src/db/event-fact-semantics.ts

@@ -1,7 +1,6 @@
 import type { Db } from './connection.js';
 import { ANALYZER_VERSION } from '../version.js';
 import {
-  EVENT_ENVIRONMENT_KEY_ALLOWLIST,
   parseEnvironmentDeclarationsFact,
 } from '../parsers/environment-declarations.js';
 import type {
@@ -21,12 +20,28 @@ export interface EventFactSemanticCategoryCount {
 }
 
 interface EventFactRow extends Record<string, unknown> {
+  id?: number;
+  repoId?: number;
+  repositoryName?: string;
   workspaceId?: number;
+  sourceFile?: string;
+  sourceLine?: number;
   eventName?: string;
   skeletonSignature?: string | null;
   skeletonJson?: string | null;
   unresolvedReason?: string | null;
   evidenceJson?: string;
+  environmentJson?: string | null;
+}
+
+export interface InvalidEventFactExample {
+  category: string;
+  repositoryId: number;
+  repositoryName: string;
+  sourceFile?: string;
+  sourceLine?: number;
+  factId?: number;
+  failingPredicate: string;
 }
 
 const receiverReasons = new Set([
@@ -38,11 +53,12 @@ const constantReasons = new Set([
   'event_name_constant_container_ambiguous',
   'event_name_constant_member_not_string',
   'event_name_constant_container_mutable',
+  'event_name_constant_container_unsafe_reference',
+  'event_name_constant_container_unsupported_shape',
   'event_name_constant_container_not_exported',
   'event_name_constant_resolution_pending',
+  'event_name_constant_value_empty',
 ]);
-const environmentKeys = new Set<string>(EVENT_ENVIRONMENT_KEY_ALLOWLIST);
-
 function category(
   name: string,
   count: number,
@@ -68,12 +84,15 @@ function currentEventRows(
   db: Db,
   workspaceId?: number,
 ): EventFactRow[] {
-  return db.prepare(`SELECT fact.event_name_expr eventName,
+  return db.prepare(`SELECT fact.id,fact.repo_id repoId,r.name repositoryName,
+    fact.source_file sourceFile,fact.source_line sourceLine,
+    fact.event_name_expr eventName,
     r.workspace_id workspaceId,
     fact.event_skeleton_signature skeletonSignature,
     fact.event_skeleton_json skeletonJson,
     fact.unresolved_reason unresolvedReason,
-    fact.evidence_json evidenceJson
+    fact.evidence_json evidenceJson,
+    r.environment_declarations_json environmentJson
     FROM outbound_calls fact JOIN repositories r ON r.id=fact.repo_id
     WHERE r.fact_analyzer_version=?
       AND (? IS NULL OR r.workspace_id=?)
@@ -82,6 +101,25 @@ function currentEventRows(
   ) as EventFactRow[];
 }
 
+function eventInvalidPredicate(
+  db: Db,
+  row: EventFactRow,
+  phase: 'pre_package' | 'terminal',
+): string | undefined {
+  if (typeof row.eventName !== 'string' || row.eventName.length === 0)
+    return 'event_name_non_empty';
+  const evidence = jsonRecord(row.evidenceJson);
+  if (!evidence) return 'event_evidence_valid_json_object';
+  if (!receiverEvidenceValid(evidence))
+    return 'event_receiver_evidence_consistent';
+  if (!eventReasonValid(row, evidence))
+    return 'event_name_reason_axis_consistent';
+  if (!packageConstantValid(db, row, evidence, phase))
+    return 'event_package_constant_resolution_consistent';
+  return skeletonValid(row, evidence)
+    ? undefined : 'event_skeleton_complete_and_signed';
+}
+
 function integerField(
   value: Record<string, unknown>,
   key: string,
@@ -167,37 +205,70 @@ function packageConstantValid(
 }
 
 function receiverEvidenceValid(
-  row: EventFactRow,
   evidence: Record<string, unknown>,
 ): boolean {
   const classification = evidence.receiverClassification;
   const proof = evidence.receiverProof;
-  if (!['cap_evidence', 'name_fallback', 'unproven'].includes(
-    String(classification),
-  ) || typeof proof !== 'string' || proof.length === 0
-    || !Array.isArray(evidence.consideredBindingSites)
-    || evidence.consideredBindingSites.length > 8) return false;
+  if (!receiverEvidenceShapeValid(classification, proof, evidence))
+    return false;
   if (classification === 'name_fallback')
-    return proof === 'compatibility_name_fallback';
-  if (classification !== 'unproven') return true;
-  return typeof row.unresolvedReason === 'string'
-    && receiverReasons.has(row.unresolvedReason);
+    return fallbackReceiverEvidenceValid(proof, evidence);
+  if (classification !== 'unproven')
+    return evidence.receiverUnresolvedReason === undefined
+      && evidence.receiverFallbackRefusedReason === undefined;
+  return evidence.receiverFallbackRefusedReason === undefined
+    && typeof evidence.receiverUnresolvedReason === 'string'
+    && receiverReasons.has(evidence.receiverUnresolvedReason);
+}
+
+function receiverEvidenceShapeValid(
+  classification: unknown,
+  proof: unknown,
+  evidence: Record<string, unknown>,
+): boolean {
+  const sites = evidence.consideredBindingSites;
+  return ['cap_evidence', 'name_fallback', 'unproven'].includes(
+    String(classification),
+  ) && typeof proof === 'string' && proof.length > 0
+    && Array.isArray(sites) && sites.length <= 8;
+}
+
+function fallbackReceiverEvidenceValid(
+  proof: unknown,
+  evidence: Record<string, unknown>,
+): boolean {
+  const reason = evidence.receiverFallbackRefusedReason;
+  return proof === 'compatibility_name_fallback'
+    && evidence.receiverUnresolvedReason === undefined
+    && typeof reason === 'string' && reason.length > 0;
 }
 
 function environmentBindingValid(
   binding: EventEnvironmentReference,
   sourceKeys: readonly string[],
+  allowedKeys: ReadonlySet<string>,
 ): boolean {
   if (!['resolved', 'refused'].includes(binding.status)
     || !sourceKeys.includes(binding.sourceKey)
-    || !Array.isArray(binding.transforms)
-    || !binding.transforms.every((item) =>
-      item === 'toUpperCase' || item === 'toLowerCase')) return false;
+    || !environmentTransformsValid(binding.transforms)) return false;
   if (binding.status === 'refused')
     return typeof binding.reason === 'string' && binding.reason.length > 0;
-  return typeof binding.environmentKey === 'string'
-    && environmentKeys.has(binding.environmentKey)
-    && typeof binding.sourceFile === 'string' && binding.sourceFile.length > 0
+  return resolvedEnvironmentBindingValid(binding, allowedKeys);
+}
+
+function environmentTransformsValid(value: unknown): boolean {
+  return Array.isArray(value) && value.every((item) =>
+    item === 'toUpperCase' || item === 'toLowerCase');
+}
+
+function resolvedEnvironmentBindingValid(
+  binding: EventEnvironmentReference,
+  allowedKeys: ReadonlySet<string>,
+): boolean {
+  const key = binding.environmentKey;
+  const file = binding.sourceFile;
+  return typeof key === 'string' && allowedKeys.has(key)
+    && typeof file === 'string' && file.length > 0
     && Number.isInteger(binding.startOffset)
     && Number(binding.startOffset) >= 0
     && Number.isInteger(binding.endOffset)
@@ -212,10 +283,14 @@ function skeletonValid(
   if (reason !== 'dynamic_event_name_identifier')
     return row.skeletonSignature == null && row.skeletonJson == null;
   const skeleton = parseEventSkeletonFact(row.skeletonJson);
+  const environment = parseEnvironmentDeclarationsFact(row.environmentJson);
   if (!skeleton || skeleton.status !== 'complete'
+    || !environment
     || row.skeletonSignature !== skeleton.signature
     || !skeleton.environmentBindings.every((binding) =>
-      environmentBindingValid(binding, skeleton.sourceKeys))) return false;
+      environmentBindingValid(
+        binding, skeleton.sourceKeys, new Set(environment.allowedKeys),
+      ))) return false;
   const keys = evidence.eventNamePlaceholderKeys;
   return Array.isArray(keys)
     && JSON.stringify(keys) === JSON.stringify(skeleton.sourceKeys);
@@ -226,11 +301,6 @@ function eventReasonValid(
   evidence: Record<string, unknown>,
 ): boolean {
   const eventReason = evidence.eventNameUnresolvedReason;
-  if (receiverReasons.has(String(row.unresolvedReason)))
-    return eventReason === undefined
-      || eventReason === 'dynamic_event_name_identifier'
-      || eventReason === 'dynamic_event_name_unsupported_expression'
-      || constantReasons.has(String(eventReason));
   if (eventReason === undefined) return row.unresolvedReason == null;
   if (eventReason === 'dynamic_event_name_identifier'
     || eventReason === 'dynamic_event_name_unsupported_expression'
@@ -244,16 +314,8 @@ function invalidEventRows(
   workspaceId?: number,
   phase: 'pre_package' | 'terminal' = 'pre_package',
 ): number {
-  return currentEventRows(db, workspaceId).filter((row) => {
-    if (typeof row.eventName !== 'string' || row.eventName.length === 0)
-      return false;
-    const evidence = jsonRecord(row.evidenceJson);
-    return !evidence
-      || !receiverEvidenceValid(row, evidence)
-      || !eventReasonValid(row, evidence)
-      || !packageConstantValid(db, row, evidence, phase)
-      || !skeletonValid(row, evidence);
-  }).length;
+  return currentEventRows(db, workspaceId).filter((row) =>
+    eventInvalidPredicate(db, row, phase) !== undefined).length;
 }
 
 function invalidEnvironmentRepositories(
@@ -269,31 +331,59 @@ function invalidEnvironmentRepositories(
     !parseEnvironmentDeclarationsFact(row.value)).length;
 }
 
-function generatedConstantInvalid(row: Record<string, unknown>): boolean {
+function generatedConstantInvalidPredicate(
+  row: Record<string, unknown>,
+): string | undefined {
   const kind = String(row.constantKind);
-  const container = row.containerName;
-  const member = row.memberName;
-  const name = row.name;
-  const memberShape = kind === 'const_identifier'
-    ? container == null && member == null
-    : typeof container === 'string' && container.length > 0
-      && typeof member === 'string' && member.length > 0
-      && name === `${container}.${member}`;
+  if (!['const_identifier', 'enum_member', 'const_object_property']
+    .includes(kind)) return 'generated_constant_kind_known';
+  if (typeof row.name !== 'string' || row.name.length === 0)
+    return 'generated_constant_name_non_empty';
+  const status = generatedConstantStatusInvalid(row);
+  if (status) return status;
+  const source = generatedConstantSourceInvalid(row);
+  if (source) return source;
+  if (!validConstantOffsets(row)) return 'generated_constant_offsets_valid';
+  return generatedConstantMemberShapeValid(row, kind)
+    ? undefined : 'generated_constant_member_shape_valid';
+}
+
+function generatedConstantStatusInvalid(
+  row: Record<string, unknown>,
+): string | undefined {
   const resolved = row.resolutionStatus === 'resolved';
   const refused = row.resolutionStatus === 'refused';
-  return !['const_identifier', 'enum_member', 'const_object_property']
-    .includes(kind)
-    || typeof name !== 'string' || name.length === 0
-    || (!resolved && !refused)
-    || (resolved && (typeof row.value !== 'string'
-      || row.value.length === 0 || row.unresolvedReason != null))
-    || (refused && (row.value != null
-      || !constantReasons.has(String(row.unresolvedReason))))
-    || typeof row.sourceFile !== 'string' || row.sourceFile.length === 0
-    || !Number.isInteger(row.sourceLine) || Number(row.sourceLine) < 1
-    || ![0, 1].includes(Number(row.exported))
-    || ![0, 1].includes(Number(row.stable))
-    || !validConstantOffsets(row) || !memberShape;
+  if (!resolved && !refused) return 'generated_constant_status_known';
+  if (resolved && (typeof row.value !== 'string'
+    || row.unresolvedReason != null))
+    return 'generated_constant_resolved_value_consistent';
+  return refused && (row.value != null
+    || !constantReasons.has(String(row.unresolvedReason)))
+    ? 'generated_constant_refusal_consistent' : undefined;
+}
+
+function generatedConstantSourceInvalid(
+  row: Record<string, unknown>,
+): string | undefined {
+  if (typeof row.sourceFile !== 'string' || row.sourceFile.length === 0
+    || !Number.isInteger(row.sourceLine) || Number(row.sourceLine) < 1)
+    return 'generated_constant_source_location_valid';
+  return [0, 1].includes(Number(row.exported))
+    && [0, 1].includes(Number(row.stable))
+    ? undefined : 'generated_constant_flags_boolean';
+}
+
+function generatedConstantMemberShapeValid(
+  row: Record<string, unknown>,
+  kind: string,
+): boolean {
+  if (kind === 'const_identifier')
+    return row.containerName == null && row.memberName == null;
+  const container = row.containerName;
+  const member = row.memberName;
+  return typeof container === 'string' && container.length > 0
+    && typeof member === 'string' && member.length > 0
+    && row.name === `${container}.${member}`;
 }
 
 function validConstantOffsets(row: Record<string, unknown>): boolean {
@@ -312,7 +402,17 @@ function invalidGeneratedConstants(
   db: Db,
   workspaceId?: number,
 ): number {
-  const rows = db.prepare(`SELECT fact.source_file sourceFile,
+  const rows = generatedConstantRows(db, workspaceId);
+  return rows.filter((row) =>
+    generatedConstantInvalidPredicate(row) !== undefined).length;
+}
+
+function generatedConstantRows(
+  db: Db,
+  workspaceId?: number,
+): Array<Record<string, unknown>> {
+  return db.prepare(`SELECT fact.id,fact.repo_id repoId,
+    r.name repositoryName,fact.source_file sourceFile,
     fact.source_line sourceLine,fact.name,fact.container_name containerName,
     fact.member_name memberName,fact.value,
     fact.constant_kind constantKind,fact.exported,fact.stable,
@@ -328,7 +428,106 @@ function invalidGeneratedConstants(
       AND (? IS NULL OR r.workspace_id=?)`).all(
     ANALYZER_VERSION, workspaceId, workspaceId,
   );
-  return rows.filter(generatedConstantInvalid).length;
+}
+
+function eventFactExamples(
+  db: Db,
+  workspaceId: number | undefined,
+  phase: 'pre_package' | 'terminal',
+): InvalidEventFactExample[] {
+  return currentEventRows(db, workspaceId).flatMap((row) => {
+    const predicate = eventInvalidPredicate(db, row, phase);
+    return predicate && typeof row.repoId === 'number'
+      && typeof row.repositoryName === 'string'
+      ? [{
+          category: 'event_fact_semantics_invalid',
+          repositoryId: row.repoId,
+          repositoryName: row.repositoryName,
+          sourceFile: row.sourceFile,
+          sourceLine: row.sourceLine,
+          factId: row.id,
+          failingPredicate: predicate,
+        }] : [];
+  });
+}
+
+function generatedConstantExamples(
+  db: Db,
+  workspaceId?: number,
+): InvalidEventFactExample[] {
+  return generatedConstantRows(db, workspaceId).flatMap((row) => {
+    const predicate = generatedConstantInvalidPredicate(row);
+    return predicate && typeof row.repoId === 'number'
+      && typeof row.repositoryName === 'string'
+      ? [{
+          category: 'generated_constant_fact_invalid',
+          repositoryId: row.repoId,
+          repositoryName: row.repositoryName,
+          sourceFile: typeof row.sourceFile === 'string'
+            ? row.sourceFile : undefined,
+          sourceLine: typeof row.sourceLine === 'number'
+            ? row.sourceLine : undefined,
+          factId: typeof row.id === 'number' ? row.id : undefined,
+          failingPredicate: predicate,
+        }] : [];
+  });
+}
+
+function environmentExamples(
+  db: Db,
+  workspaceId?: number,
+): InvalidEventFactExample[] {
+  const rows = db.prepare(`SELECT id repositoryId,name repositoryName,
+    environment_declarations_json value FROM repositories
+    WHERE fact_analyzer_version=?
+      AND (? IS NULL OR workspace_id=?)
+    ORDER BY name COLLATE BINARY,id`).all(
+    ANALYZER_VERSION, workspaceId, workspaceId,
+  );
+  return rows.flatMap((row) =>
+    !parseEnvironmentDeclarationsFact(row.value)
+      && typeof row.repositoryId === 'number'
+      && typeof row.repositoryName === 'string'
+      ? [{
+          category: 'repository_environment_declarations_invalid',
+          repositoryId: row.repositoryId,
+          repositoryName: row.repositoryName,
+          failingPredicate: 'environment_declarations_fact_valid',
+        }] : []);
+}
+
+function compareExample(
+  left: InvalidEventFactExample,
+  right: InvalidEventFactExample,
+): number {
+  const leftKey = `${left.repositoryName}\0${left.sourceFile ?? ''}\0${
+    left.sourceLine ?? 0}\0${left.category}\0${left.factId ?? 0}`;
+  const rightKey = `${right.repositoryName}\0${right.sourceFile ?? ''}\0${
+    right.sourceLine ?? 0}\0${right.category}\0${right.factId ?? 0}`;
+  return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+}
+
+export function invalidEventFactExamples(
+  db: Db,
+  workspaceId?: number,
+  phase: 'pre_package' | 'terminal' = 'pre_package',
+  limit = 5,
+): {
+  total: number;
+  affectedRepositoryCount: number;
+  examples: InvalidEventFactExample[];
+} {
+  const all = [
+    ...eventFactExamples(db, workspaceId, phase),
+    ...generatedConstantExamples(db, workspaceId),
+    ...environmentExamples(db, workspaceId),
+  ].sort(compareExample);
+  return {
+    total: all.length,
+    affectedRepositoryCount:
+      new Set(all.map((item) => item.repositoryId)).size,
+    examples: all.slice(0, Math.max(0, limit)),
+  };
 }
 
 export function invalidEventFactCategories(

package/src/db/event-site-semantics.ts

@@ -0,0 +1,62 @@
+import type { Db } from './connection.js';
+import { ANALYZER_VERSION } from '../version.js';
+
+export interface EventSiteCategoryCount {
+  category: string;
+  count: number;
+}
+
+function count(
+  db: Db,
+  sql: string,
+  workspaceId?: number,
+): number {
+  const row = db.prepare(sql).get(
+    ANALYZER_VERSION, workspaceId, workspaceId,
+  );
+  return Number(row?.count ?? 0);
+}
+
+function category(
+  name: string,
+  value: number,
+): EventSiteCategoryCount[] {
+  return value > 0 ? [{ category: name, count: value }] : [];
+}
+
+function duplicateSiteCount(
+  db: Db,
+  workspaceId: number | undefined,
+  callType: 'async_emit' | 'async_subscribe',
+): number {
+  return count(db, `SELECT COUNT(*) count FROM (
+    SELECT fact.repo_id,fact.source_file,fact.call_site_start_offset,
+      fact.call_site_end_offset,COUNT(*) duplicate_count
+    FROM outbound_calls fact JOIN repositories r ON r.id=fact.repo_id
+    WHERE r.fact_analyzer_version=?
+      AND (? IS NULL OR r.workspace_id=?)
+      AND fact.call_type='${callType}'
+    GROUP BY fact.repo_id,fact.source_file,fact.call_site_start_offset,
+      fact.call_site_end_offset HAVING COUNT(*)<>1
+  )`, workspaceId);
+}
+
+export function eventSiteCategories(
+  db: Db,
+  workspaceId?: number,
+): EventSiteCategoryCount[] {
+  const invalidName = count(db, `SELECT COUNT(*) count
+    FROM outbound_calls fact JOIN repositories r ON r.id=fact.repo_id
+    WHERE r.fact_analyzer_version=?
+      AND (? IS NULL OR r.workspace_id=?)
+      AND fact.call_type IN ('async_emit','async_subscribe')
+      AND (typeof(fact.event_name_expr)<>'text'
+        OR length(fact.event_name_expr)=0)`, workspaceId);
+  return [
+    ...category('event_name_invalid', invalidName),
+    ...category('async_subscription_site_duplicate',
+      duplicateSiteCount(db, workspaceId, 'async_subscribe')),
+    ...category('async_emit_site_duplicate',
+      duplicateSiteCount(db, workspaceId, 'async_emit')),
+  ];
+}

package/src/db/fact-lifecycle.ts

@@ -14,6 +14,7 @@ import {
   type SchemaStructureCategoryCount,
 } from './schema-structure.js';
 import { ANALYZER_VERSION } from '../version.js';
+import { invalidEventFactExamples } from './event-fact-semantics.js';
 
 export type FactLifecycleCode =
   | 'schema_upgrade_required'
@@ -27,11 +28,8 @@ export interface FactLifecycleDiagnostic extends Record<string, unknown> {
   remediation: string;
 }
 
-const remediation = [
-  'service-flow index --workspace /workspace --force',
-  'service-flow link --workspace /workspace --force',
-].join('\n');
 const CATEGORY_LIMIT = 24;
+const EXAMPLE_LIMIT = 5;
 
 function count(db: Db, sql: string, ...params: unknown[]): number {
   const row = db.prepare(sql).get(...params);
@@ -51,12 +49,13 @@ export function factLifecycleDiagnostic(
   workspaceId?: number,
   phase: PackageFactPhase = 'pre_package',
 ): FactLifecycleDiagnostic | undefined {
-  return schemaLifecycleDiagnostic(db)
+  return schemaLifecycleDiagnostic(db, workspaceId)
     ?? currentFactLifecycleDiagnostic(db, workspaceId, phase);
 }
 
 export function schemaLifecycleDiagnostic(
   db: Db,
+  workspaceId?: number,
 ): FactLifecycleDiagnostic | undefined {
   const currentSchema = schemaVersion(db);
   if (currentSchema > CURRENT_SCHEMA_VERSION) return {
@@ -71,13 +70,15 @@ export function schemaLifecycleDiagnostic(
     severity: 'error',
     code: 'schema_upgrade_required',
     message: `Database schema ${currentSchema} must be upgraded to ${CURRENT_SCHEMA_VERSION} before this command can read current call-site facts.`,
-    remediation,
+    remediation: staleRemediation(db, workspaceId),
     currentSchemaVersion: currentSchema,
     requiredSchemaVersion: CURRENT_SCHEMA_VERSION,
   };
   const structureCategories = invalidSchemaStructureCategories(db);
   if (structureCategories.length > 0)
-    return reindexDiagnostic(0, structureCategories);
+    return reindexDiagnostic(
+      db, workspaceId, 0, structureCategories, 'pre_package', false,
+    );
   return undefined;
 }
 
@@ -88,15 +89,17 @@ export function currentFactLifecycleDiagnostic(
 ): FactLifecycleDiagnostic | undefined {
   const staleRepositories = oldAnalyzerCount(db, workspaceId);
   if (staleRepositories > 0)
-    return reindexDiagnostic(staleRepositories, []);
+    return reindexDiagnostic(
+      db, workspaceId, staleRepositories, [], phase,
+    );
   const jsonCategories = invalidFactJsonCategories(db, workspaceId);
   if (jsonCategories.length > 0)
-    return reindexDiagnostic(0, jsonCategories);
+    return reindexDiagnostic(db, workspaceId, 0, jsonCategories, phase);
   const semanticCategories = invalidFactSemanticCategories(
     db, workspaceId, phase,
   );
   if (semanticCategories.length === 0) return undefined;
-  return reindexDiagnostic(0, semanticCategories);
+  return reindexDiagnostic(db, workspaceId, 0, semanticCategories, phase);
 }
 
 type InvalidFactCategory =
@@ -105,26 +108,81 @@ type InvalidFactCategory =
   | SchemaStructureCategoryCount;
 
 function reindexDiagnostic(
+  db: Db,
+  workspaceId: number | undefined,
   staleRepositories: number,
   categories: InvalidFactCategory[],
+  phase: PackageFactPhase,
+  examplesAllowed = true,
 ): FactLifecycleDiagnostic {
   const invalidFacts = categories.reduce((sum, item) => sum + item.count, 0);
   const shown = categories.slice(0, CATEGORY_LIMIT);
+  const eventExamples = examplesAllowed
+    ? invalidEventFactExamples(db, workspaceId, phase, EXAMPLE_LIMIT)
+    : { total: 0, affectedRepositoryCount: 0, examples: [] };
+  const examples = invalidFacts > 0 ? eventExamples.examples : [];
   return {
     severity: 'error',
     code: 'reindex_required',
-    message: 'Current facts are stale or fail bounded semantic integrity checks; force index and link before tracing or rebuilding graph edges.',
-    remediation,
+    message: invalidFacts > 0
+      ? 'Current facts fail bounded semantic integrity checks; inspect the offending rows before rebuilding graph edges.'
+      : 'Current facts are stale; force index and link before tracing or rebuilding graph edges.',
+    remediation: invalidFacts > 0
+      ? invalidFactRemediation(db, workspaceId)
+      : staleRemediation(db, workspaceId),
     staleRepositoryCount: staleRepositories,
     invalidCallFactCount: invalidFacts,
     invalidFactCategories: shown,
     invalidFactCategoryCount: categories.length,
     shownInvalidFactCategoryCount: shown.length,
     omittedInvalidFactCategoryCount: categories.length - shown.length,
+    affectedRepositoryCount: eventExamples.affectedRepositoryCount,
+    workspaceRepositoryCount: repositoryCount(db, workspaceId),
+    invalidFactExamples: examples,
+    invalidFactExampleCount: eventExamples.total,
+    shownInvalidFactExampleCount: examples.length,
+    omittedInvalidFactExampleCount:
+      Math.max(0, eventExamples.total - examples.length),
     requiredAnalyzerVersion: ANALYZER_VERSION,
   };
 }
 
+function workspacePath(db: Db, workspaceId?: number): string | undefined {
+  if (workspaceId === undefined) return undefined;
+  const row = db.prepare(
+    'SELECT root_path rootPath FROM workspaces WHERE id=?',
+  ).get(workspaceId);
+  return typeof row?.rootPath === 'string' ? row.rootPath : undefined;
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function workspaceArgument(db: Db, workspaceId?: number): string {
+  const root = workspacePath(db, workspaceId);
+  return root ? ` --workspace ${shellQuote(root)}` : '';
+}
+
+function staleRemediation(db: Db, workspaceId?: number): string {
+  const workspace = workspaceArgument(db, workspaceId);
+  return [
+    `service-flow index${workspace} --force`,
+    `service-flow link${workspace} --force`,
+  ].join('\n');
+}
+
+function invalidFactRemediation(db: Db, workspaceId?: number): string {
+  return `service-flow doctor${workspaceArgument(
+    db, workspaceId,
+  )} --strict --detail`;
+}
+
+function repositoryCount(db: Db, workspaceId?: number): number {
+  return count(db, `SELECT COUNT(*) count FROM repositories
+    WHERE (? IS NULL OR workspace_id=?)`, workspaceId, workspaceId);
+}
+
 export function assertWorkspaceLinkable(
   db: Db,
   workspaceId: number,

package/src/db/migrations.ts

@@ -20,7 +20,7 @@ const columns: Record<string, Array<{ name: string; ddl: string }>> = {
     { name: 'graph_stale_at', ddl: 'ALTER TABLE repositories ADD COLUMN graph_stale_at TEXT' },
     { name: 'fact_analyzer_version', ddl: "ALTER TABLE repositories ADD COLUMN fact_analyzer_version TEXT DEFAULT 'legacy'" },
     { name: 'package_public_surface_json', ddl: 'ALTER TABLE repositories ADD COLUMN package_public_surface_json TEXT' },
-    { name: 'environment_declarations_json', ddl: 'ALTER TABLE repositories ADD COLUMN environment_declarations_json TEXT' },
+    { name: 'environment_declarations_json', ddl: `ALTER TABLE repositories ADD COLUMN environment_declarations_json TEXT DEFAULT '{"schema":"service-flow/environment-declarations@1","allowedKeys":["SHARD_CODE"],"status":"not_applicable","reason":null,"recordCap":32,"total":0,"shown":0,"omitted":0,"declarations":[]}'` },
   ],
   graph_edges: [
     { name: 'status', ddl: "ALTER TABLE graph_edges ADD COLUMN status TEXT NOT NULL DEFAULT 'unresolved'" },
@@ -109,6 +109,9 @@ function markFactProvenanceMigrationStale(db: Db, priorVersion: number): void {
 }
 function markEventSurfaceMigrationStale(db: Db, priorVersion: number): void {
   if (priorVersion >= 14) return;
+  db.prepare(
+    'UPDATE repositories SET environment_declarations_json=NULL',
+  ).run();
   db.prepare(`UPDATE repositories
     SET graph_stale_reason='schema_v14_event_surface_requires_reindex',
       graph_stale_at=COALESCE(graph_stale_at,datetime('now'))