@saptools/service-flow 0.1.69 → 0.1.72

package/src/db/{000-call-fact-repository.ts → call-fact-repository.ts}

@@ -3,25 +3,25 @@ import {
   selectCallOwner,
   type OwnerCandidate,
   type OwnerSelection,
-} from '../parsers/004-fact-identity.js';
+} from '../parsers/fact-identity.js';
 import type { Db, Statement } from './connection.js';
 import {
   resolveRelativeSymbolCall,
-} from './006-relative-symbol-resolution.js';
+} from './relative-symbol-resolution.js';
 import {
   parsePackageImportReference,
-} from '../parsers/012-package-fact-contract.js';
+} from '../parsers/package-fact-contract.js';
 import {
   resolvedBindingReferenceProofValid,
   type BindingProofCall,
   type BindingProofTarget,
-} from './012-binding-reference-proof.js';
+} from './binding-reference-proof.js';
 import {
   preparedCallSnapshotError,
-} from './013-index-publication-failure.js';
+} from './index-publication-failure.js';
 import {
   hasSingleHopHelperReturn,
-} from './014-binding-helper-provenance.js';
+} from './binding-helper-provenance.js';
 
 export function insertSymbolCalls(db: Db, repoId: number, rows: SymbolCallFact[]): void {
   const insertStmt = db.prepare('INSERT INTO symbol_calls(repo_id,caller_symbol_id,callee_symbol_id,callee_expression,import_source,source_file,source_line,call_site_start_offset,call_site_end_offset,call_role,status,confidence,evidence_json,unresolved_reason) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?)');
@@ -400,11 +400,12 @@ export function insertCalls(
 function outboundCallInsertStatement(db: Db): Statement {
   return db.prepare(`INSERT INTO outbound_calls(
     repo_id,source_symbol_id,call_type,method,operation_path_expr,query_entity,
-    event_name_expr,payload_summary,source_file,source_line,call_site_start_offset,
+    event_name_expr,event_skeleton_signature,event_skeleton_json,
+    payload_summary,source_file,source_line,call_site_start_offset,
     call_site_end_offset,confidence,unresolved_reason,local_service_name,
     local_service_lookup,alias_chain_json,evidence_json,external_target_kind,
     external_target_id,external_target_label,external_target_dynamic,service_binding_id
-  ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`);
+  ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`);
 }
 
 function insertOutboundCall(
@@ -424,7 +425,9 @@ function insertOutboundCall(
   stmt.run(
     repoId, sourceSymbolId,
     call.callType, call.method, call.operationPathExpr, call.queryEntity,
-    call.eventNameExpr, call.payloadSummary, call.sourceFile, call.sourceLine,
+    call.eventNameExpr, call.eventSkeleton?.signature ?? null,
+    call.eventSkeleton ? JSON.stringify(call.eventSkeleton) : null,
+    call.payloadSummary, call.sourceFile, call.sourceLine,
     call.callSiteStartOffset, call.callSiteEndOffset, call.confidence,
     call.unresolvedReason,
     call.localServiceName, call.localServiceLookup,

package/src/db/{003-current-fact-semantics.ts → current-fact-semantics.ts}

@@ -3,16 +3,15 @@ import type { CallType, RepoKind } from '../types.js';
 import { ANALYZER_VERSION } from '../version.js';
 import {
   invalidPackageFactCategories,
-} from './007-package-fact-semantics.js';
+} from './package-fact-semantics.js';
 import {
   invalidRelativeFactCategories,
-} from './008-relative-fact-semantics.js';
+} from './relative-fact-semantics.js';
 import {
   invalidBindingFactCategories,
-} from './009-binding-fact-semantics.js';
-import {
-  invalidSymbolFactCategories,
-} from './011-symbol-call-semantics.js';
+} from './binding-fact-semantics.js';
+import { invalidSymbolFactCategories } from './symbol-call-semantics.js';
+import { invalidEventFactCategories } from './event-fact-semantics.js';
 
 export type PackageFactPhase = 'pre_package' | 'terminal';
 
@@ -262,7 +261,7 @@ function eventNameCategories(
   db: Db,
   workspaceId?: number,
 ): FactSemanticCategoryCount[] {
-  const invalid = count(db, `SELECT COUNT(*) count
+  const invalidName = count(db, `SELECT COUNT(*) count
     FROM outbound_calls fact JOIN repositories r ON r.id=fact.repo_id
     WHERE ${currentRepositoryPredicate()}
       AND fact.call_type IN ('async_emit','async_subscribe')
@@ -278,7 +277,7 @@ function eventNameCategories(
       fact.call_site_end_offset HAVING COUNT(*)<>1
   )`, workspaceId);
   return [
-    ...category('event_name_invalid', invalid),
+    ...category('event_name_invalid', invalidName),
     ...category('async_subscription_site_duplicate', duplicate),
   ];
 }
@@ -686,6 +685,7 @@ export function invalidFactSemanticCategories(
     ...callSpanCategories(db, workspaceId),
     ...duplicateSymbolCallCategories(db, workspaceId),
     ...eventNameCategories(db, workspaceId),
+    ...invalidEventFactCategories(db, workspaceId, phase),
     ...ownerCategories(db, workspaceId),
     ...bindingCategories(db, workspaceId),
     ...invalidBindingFactCategories(db, workspaceId),

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

@@ -0,0 +1,347 @@
+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 {
+  EventEnvironmentReference,
+} from '../parsers/event-environment-reference.js';
+import { parseEventSkeletonFact } from '../utils/event-skeleton.js';
+import { parsePackageImportReference } from
+  '../parsers/package-fact-contract.js';
+import {
+  expectedPackageEventConstantResolution,
+  type PackageEventConstantResolution,
+} from '../linker/package-event-constant-resolver.js';
+
+export interface EventFactSemanticCategoryCount {
+  category: string;
+  count: number;
+}
+
+interface EventFactRow extends Record<string, unknown> {
+  workspaceId?: number;
+  eventName?: string;
+  skeletonSignature?: string | null;
+  skeletonJson?: string | null;
+  unresolvedReason?: string | null;
+  evidenceJson?: string;
+}
+
+const receiverReasons = new Set([
+  'event_receiver_unproven_binding',
+  'event_receiver_unproven_propagation',
+  'event_receiver_not_cap_client',
+]);
+const constantReasons = new Set([
+  'event_name_constant_container_ambiguous',
+  'event_name_constant_member_not_string',
+  'event_name_constant_container_mutable',
+  'event_name_constant_container_not_exported',
+  'event_name_constant_resolution_pending',
+]);
+const environmentKeys = new Set<string>(EVENT_ENVIRONMENT_KEY_ALLOWLIST);
+
+function category(
+  name: string,
+  count: number,
+): EventFactSemanticCategoryCount[] {
+  return count > 0 ? [{ category: name, count }] : [];
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown> : undefined;
+}
+
+function jsonRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== 'string') return undefined;
+  try {
+    return record(JSON.parse(value) as unknown);
+  } catch {
+    return undefined;
+  }
+}
+
+function currentEventRows(
+  db: Db,
+  workspaceId?: number,
+): EventFactRow[] {
+  return db.prepare(`SELECT 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
+    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')`).all(
+    ANALYZER_VERSION, workspaceId, workspaceId,
+  ) as EventFactRow[];
+}
+
+function integerField(
+  value: Record<string, unknown>,
+  key: string,
+): number | undefined {
+  const item = value[key];
+  return Number.isInteger(item) && Number(item) >= 0
+    ? Number(item) : undefined;
+}
+
+function packagePendingValid(
+  row: EventFactRow,
+  evidence: Record<string, unknown>,
+): boolean {
+  const source = evidence.eventNameConstantSourceExpression;
+  return evidence.eventNameUnresolvedReason
+      === 'event_name_constant_resolution_pending'
+    && evidence.eventNamePackageConstantResolution === undefined
+    && typeof source === 'string' && source.length > 0
+    && row.eventName === source;
+}
+
+function resolutionFieldsValid(
+  value: Record<string, unknown>,
+  expected: PackageEventConstantResolution,
+): boolean {
+  return value.status === expected.status
+    && value.reason === expected.reason
+    && integerField(value, 'candidateCount') === expected.candidateCount
+    && integerField(value, 'eligibleCandidateCount')
+      === expected.eligibleCandidateCount
+    && integerField(value, 'selectedCandidateCount')
+      === (expected.status === 'resolved' ? 1 : 0)
+    && value.candidateSetComplete === expected.complete
+    && value.resolvedModulePath === expected.modulePath
+    && value.targetRepositoryId === expected.targetRepoId;
+}
+
+function packageTerminalValid(
+  db: Db,
+  row: EventFactRow,
+  evidence: Record<string, unknown>,
+): boolean {
+  const binding = parsePackageImportReference(
+    evidence.eventNameConstantImportBinding,
+  );
+  const workspaceId = row.workspaceId;
+  const resolution = record(evidence.eventNamePackageConstantResolution);
+  if (!binding || typeof workspaceId !== 'number' || !resolution)
+    return false;
+  const expected = expectedPackageEventConstantResolution(
+    db, workspaceId, binding,
+  );
+  const source = evidence.eventNameConstantSourceExpression;
+  const expectedName = expected.value ?? source;
+  const expectedReason = expected.status === 'resolved'
+    ? undefined : expected.reason;
+  if (row.eventName !== expectedName
+    || evidence.eventNameUnresolvedReason !== expectedReason
+    || !resolutionFieldsValid(resolution, expected)) return false;
+  if (expected.status !== 'resolved') return true;
+  const constant = record(evidence.eventNameConstant);
+  return constant?.sourceKind === 'package_static_string'
+    && constant.sourceFile === expected.sourceFile
+    && constant.sourceLine === expected.sourceLine;
+}
+
+function packageConstantValid(
+  db: Db,
+  row: EventFactRow,
+  evidence: Record<string, unknown>,
+  phase: 'pre_package' | 'terminal',
+): boolean {
+  if (evidence.eventNameConstantImportBinding === undefined) return true;
+  const binding = parsePackageImportReference(
+    evidence.eventNameConstantImportBinding,
+  );
+  const source = evidence.eventNameConstantSourceExpression;
+  if (!binding || typeof source !== 'string' || source.length === 0)
+    return false;
+  if (packagePendingValid(row, evidence))
+    return phase === 'pre_package';
+  return packageTerminalValid(db, row, evidence);
+}
+
+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 (classification === 'name_fallback')
+    return proof === 'compatibility_name_fallback';
+  if (classification !== 'unproven') return true;
+  return typeof row.unresolvedReason === 'string'
+    && receiverReasons.has(row.unresolvedReason);
+}
+
+function environmentBindingValid(
+  binding: EventEnvironmentReference,
+  sourceKeys: readonly 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;
+  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
+    && Number.isInteger(binding.startOffset)
+    && Number(binding.startOffset) >= 0
+    && Number.isInteger(binding.endOffset)
+    && Number(binding.endOffset) > Number(binding.startOffset);
+}
+
+function skeletonValid(
+  row: EventFactRow,
+  evidence: Record<string, unknown>,
+): boolean {
+  const reason = evidence.eventNameUnresolvedReason;
+  if (reason !== 'dynamic_event_name_identifier')
+    return row.skeletonSignature == null && row.skeletonJson == null;
+  const skeleton = parseEventSkeletonFact(row.skeletonJson);
+  if (!skeleton || skeleton.status !== 'complete'
+    || row.skeletonSignature !== skeleton.signature
+    || !skeleton.environmentBindings.every((binding) =>
+      environmentBindingValid(binding, skeleton.sourceKeys))) return false;
+  const keys = evidence.eventNamePlaceholderKeys;
+  return Array.isArray(keys)
+    && JSON.stringify(keys) === JSON.stringify(skeleton.sourceKeys);
+}
+
+function eventReasonValid(
+  row: EventFactRow,
+  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'
+    || constantReasons.has(String(eventReason)))
+    return row.unresolvedReason === eventReason;
+  return false;
+}
+
+function invalidEventRows(
+  db: Db,
+  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;
+}
+
+function invalidEnvironmentRepositories(
+  db: Db,
+  workspaceId?: number,
+): number {
+  const rows = db.prepare(`SELECT environment_declarations_json value
+    FROM repositories WHERE fact_analyzer_version=?
+      AND (? IS NULL OR workspace_id=?)`).all(
+    ANALYZER_VERSION, workspaceId, workspaceId,
+  );
+  return rows.filter((row) =>
+    !parseEnvironmentDeclarationsFact(row.value)).length;
+}
+
+function generatedConstantInvalid(row: Record<string, unknown>): boolean {
+  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}`;
+  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;
+}
+
+function validConstantOffsets(row: Record<string, unknown>): boolean {
+  const start = row.declarationStartOffset;
+  const end = row.declarationEndOffset;
+  const valueStart = row.valueStartOffset;
+  const valueEnd = row.valueEndOffset;
+  return Number.isInteger(start) && Number(start) >= 0
+    && Number.isInteger(end) && Number(end) > Number(start)
+    && Number.isInteger(valueStart) && Number(valueStart) >= Number(start)
+    && Number.isInteger(valueEnd) && Number(valueEnd) > Number(valueStart)
+    && Number(valueEnd) <= Number(end);
+}
+
+function invalidGeneratedConstants(
+  db: Db,
+  workspaceId?: number,
+): number {
+  const rows = db.prepare(`SELECT 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,
+    fact.resolution_status resolutionStatus,
+    fact.unresolved_reason unresolvedReason,
+    fact.declaration_start_offset declarationStartOffset,
+    fact.declaration_end_offset declarationEndOffset,
+    fact.value_start_offset valueStartOffset,
+    fact.value_end_offset valueEndOffset
+    FROM generated_constants fact
+    JOIN repositories r ON r.id=fact.repo_id
+    WHERE r.fact_analyzer_version=?
+      AND (? IS NULL OR r.workspace_id=?)`).all(
+    ANALYZER_VERSION, workspaceId, workspaceId,
+  );
+  return rows.filter(generatedConstantInvalid).length;
+}
+
+export function invalidEventFactCategories(
+  db: Db,
+  workspaceId?: number,
+  phase: 'pre_package' | 'terminal' = 'pre_package',
+): EventFactSemanticCategoryCount[] {
+  return [
+    ...category('event_fact_semantics_invalid',
+      invalidEventRows(db, workspaceId, phase)),
+    ...category('repository_environment_declarations_invalid',
+      invalidEnvironmentRepositories(db, workspaceId)),
+    ...category('generated_constant_fact_invalid',
+      invalidGeneratedConstants(db, workspaceId)),
+  ];
+}

package/src/db/event-surface-invalidation.ts

@@ -0,0 +1,38 @@
+import type { Db } from './connection.js';
+import type { OutboundCallFact } from '../types.js';
+
+function priorEventFactCount(db: Db, repoId: number): number {
+  const row = db.prepare(`SELECT COUNT(*) count FROM outbound_calls
+    WHERE repo_id=? AND call_type IN ('async_emit','async_subscribe')`).get(
+    repoId,
+  );
+  return Number(row?.count ?? 0);
+}
+
+function repositoryEnvironment(
+  db: Db,
+  repoId: number,
+): string | null {
+  const row = db.prepare(`SELECT environment_declarations_json value
+    FROM repositories WHERE id=?`).get(repoId);
+  return typeof row?.value === 'string' ? row.value : null;
+}
+
+export function invalidateEventSurfaceFacts(
+  db: Db,
+  repoId: number,
+  calls: readonly OutboundCallFact[],
+  nextEnvironmentJson: string,
+): void {
+  const hasNewEvents = calls.some((call) =>
+    call.callType === 'async_emit' || call.callType === 'async_subscribe');
+  const environmentChanged = repositoryEnvironment(db, repoId)
+    !== nextEnvironmentJson;
+  if (!hasNewEvents && priorEventFactCount(db, repoId) === 0
+    && !environmentChanged) return;
+  db.prepare(`UPDATE repositories SET
+    graph_stale_reason='event_surface_facts_changed',
+    graph_stale_at=datetime('now')
+    WHERE workspace_id=(SELECT workspace_id FROM repositories WHERE id=?)`)
+    .run(repoId);
+}

package/src/db/{002-fact-json-inventory.ts → fact-json-inventory.ts}

@@ -36,6 +36,14 @@ export const LINK_FACT_JSON_INVENTORY: readonly FactJsonInventoryItem[] = [
     consumers: ['package-import-symbol-resolver'],
     repositoryJoin: '',
   },
+  {
+    table: 'repositories',
+    column: 'environment_declarations_json',
+    nullable: false,
+    shape: 'object',
+    consumers: ['event-environment-resolver'],
+    repositoryJoin: '',
+  },
   {
     table: 'handler_methods',
     column: 'decorator_resolution_json',
@@ -77,6 +85,14 @@ export const LINK_FACT_JSON_INVENTORY: readonly FactJsonInventoryItem[] = [
     consumers: ['cross-repository-linker', 'trace-engine'],
     repositoryJoin: directRepositoryJoin,
   },
+  {
+    table: 'outbound_calls',
+    column: 'event_skeleton_json',
+    nullable: true,
+    shape: 'object',
+    consumers: ['event-shape-linker', 'event-runtime-resolver'],
+    repositoryJoin: directRepositoryJoin,
+  },
   {
     table: 'service_bindings',
     column: 'placeholders_json',

package/src/db/{001-fact-lifecycle.ts → fact-lifecycle.ts}

@@ -3,16 +3,16 @@ import { CURRENT_SCHEMA_VERSION, schemaVersion } from './migrations.js';
 import {
   invalidFactJsonCategories,
   type FactJsonCategoryCount,
-} from './002-fact-json-inventory.js';
+} from './fact-json-inventory.js';
 import {
   invalidFactSemanticCategories,
   type FactSemanticCategoryCount,
   type PackageFactPhase,
-} from './003-current-fact-semantics.js';
+} from './current-fact-semantics.js';
 import {
   invalidSchemaStructureCategories,
   type SchemaStructureCategoryCount,
-} from './005-schema-structure.js';
+} from './schema-structure.js';
 import { ANALYZER_VERSION } from '../version.js';
 
 export type FactLifecycleCode =

package/src/db/migrations.ts

@@ -1,6 +1,6 @@
 import type { Db } from './connection.js';
 import { schemaIndexesSql, schemaTablesSql } from './schema.js';
-export const CURRENT_SCHEMA_VERSION = 13;
+export const CURRENT_SCHEMA_VERSION = 14;
 const columns: Record<string, Array<{ name: string; ddl: string }>> = {
   handler_methods: [
     { name: 'decorator_resolution_json', ddl: "ALTER TABLE handler_methods ADD COLUMN decorator_resolution_json TEXT NOT NULL DEFAULT '{}'" },
@@ -20,6 +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' },
   ],
   graph_edges: [
     { name: 'status', ddl: "ALTER TABLE graph_edges ADD COLUMN status TEXT NOT NULL DEFAULT 'unresolved'" },
@@ -60,6 +61,8 @@ const columns: Record<string, Array<{ name: string; ddl: string }>> = {
     { name: 'external_target_dynamic', ddl: 'ALTER TABLE outbound_calls ADD COLUMN external_target_dynamic INTEGER NOT NULL DEFAULT 0' },
     { name: 'call_site_start_offset', ddl: 'ALTER TABLE outbound_calls ADD COLUMN call_site_start_offset INTEGER' },
     { name: 'call_site_end_offset', ddl: 'ALTER TABLE outbound_calls ADD COLUMN call_site_end_offset INTEGER' },
+    { name: 'event_skeleton_signature', ddl: 'ALTER TABLE outbound_calls ADD COLUMN event_skeleton_signature TEXT' },
+    { name: 'event_skeleton_json', ddl: 'ALTER TABLE outbound_calls ADD COLUMN event_skeleton_json TEXT' },
   ],
   symbol_calls: [
     { name: 'call_site_start_offset', ddl: 'ALTER TABLE symbol_calls ADD COLUMN call_site_start_offset INTEGER' },
@@ -104,6 +107,13 @@ function markFactProvenanceMigrationStale(db: Db, priorVersion: number): void {
       graph_stale_at=COALESCE(graph_stale_at,datetime('now'))
     WHERE index_status='indexed' OR last_indexed_at IS NOT NULL`).run();
 }
+function markEventSurfaceMigrationStale(db: Db, priorVersion: number): void {
+  if (priorVersion >= 14) return;
+  db.prepare(`UPDATE repositories
+    SET graph_stale_reason='schema_v14_event_surface_requires_reindex',
+      graph_stale_at=COALESCE(graph_stale_at,datetime('now'))
+    WHERE index_status='indexed' OR last_indexed_at IS NOT NULL`).run();
+}
 export function migrate(db: Db): void {
   db.transaction(() => {
     const version = userVersion(db);
@@ -114,6 +124,7 @@ export function migrate(db: Db): void {
     normalizeLegacyStatus(db, version);
     markCallSiteMigrationStale(db, version);
     markFactProvenanceMigrationStale(db, version);
+    markEventSurfaceMigrationStale(db, version);
     const violations = db.pragma('foreign_key_check');
     if (violations.length > 0) throw new Error('SQLite foreign_key_check failed during migration');
     db.pragma(`user_version = ${CURRENT_SCHEMA_VERSION}`);

package/src/db/{007-package-fact-semantics.ts → package-fact-semantics.ts}

@@ -4,21 +4,21 @@ import type {
   PackagePublicScope,
   PackagePublicSurfaceFact,
   PublicSurfaceTarget,
-} from '../parsers/003-package-public-surface.js';
+} from '../parsers/package-public-surface.js';
 import {
   parsePackageImportReference,
   parsePackagePublicSurfaceFact,
-} from '../parsers/012-package-fact-contract.js';
+} from '../parsers/package-fact-contract.js';
 import type { SymbolImportReference } from
-  '../parsers/002-symbol-import-bindings.js';
-import type { PackageFactPhase } from './003-current-fact-semantics.js';
+  '../parsers/symbol-import-bindings.js';
+import type { PackageFactPhase } from './current-fact-semantics.js';
 import {
   expectedPackageImportResolutions,
   type PackageCallResolution,
-} from '../linker/003-package-import-symbol-resolver.js';
+} from '../linker/package-import-symbol-resolver.js';
 import {
   invalidPackageSymbolSurfaceCount,
-} from './010-package-symbol-surface-semantics.js';
+} from './package-symbol-surface-semantics.js';
 
 export interface PackageFactCategoryCount {
   category: string;

package/src/db/{010-package-symbol-surface-semantics.ts → package-symbol-surface-semantics.ts}

@@ -6,10 +6,10 @@ import {
   type PackagePublicScope,
   type PackagePublicSurfaceFact,
   type PublicSurfaceTarget,
-} from '../parsers/003-package-public-surface.js';
+} from '../parsers/package-public-surface.js';
 import {
   parsePackagePublicSurfaceFact,
-} from '../parsers/012-package-fact-contract.js';
+} from '../parsers/package-fact-contract.js';
 import type { Db } from './connection.js';
 
 interface Exposure {