@saptools/service-flow 0.1.70 → 0.1.72

package/src/trace/event-runtime-resolution.ts

@@ -14,6 +14,12 @@ import type {
   TraversalScopeState,
 } from './traversal-scope.js';
 import type { TraceGraphRow } from './evidence.js';
+import {
+  eventMissingVariableNames,
+  eventTemplateVariables,
+  parseEventSkeletonFact,
+  type EventSkeletonFact,
+} from '../utils/event-skeleton.js';
 
 export interface EventRuntimeResolution {
   row: TraceGraphRow;
@@ -37,6 +43,12 @@ function eventTemplate(evidence: Record<string, unknown>): string | undefined {
     ? resolution.original : undefined;
 }
 
+function eventSkeleton(
+  evidence: Record<string, unknown>,
+): EventSkeletonFact | undefined {
+  return parseEventSkeletonFact(evidence.eventSkeleton);
+}
+
 function missingReason(substitution: RuntimeSubstitution): string {
   return `Dynamic target requires runtime variable overrides: ${
     substitution.missing.join(', ')}`;
@@ -88,6 +100,10 @@ function eventEvidence(
     unresolvedReason,
     edgeType: row.edge_type,
   };
+  const skeleton = eventSkeleton(evidence);
+  const missing = eventMissingVariableNames(
+    skeleton, substitution.missing,
+  );
   return {
     ...evidence,
     runtimeSubstitutions: { eventName: substitution },
@@ -96,8 +112,10 @@ function eventEvidence(
     ),
     ...(substitution.supplied.length > 0
       ? { runtimeVariablesApplied: true } : {}),
-    ...(substitution.missing.length > 0
-      ? { missingRuntimeVariables: substitution.missing } : {}),
+    ...(missing.length > 0 ? {
+      missingRuntimeVariables: missing,
+      missingVariableCount: missing.length,
+    } : {}),
     effectiveResolution,
     linker: {
       status: effectiveResolution.status,
@@ -137,7 +155,10 @@ export function runtimeEventResolution(
   const template = eventTemplate(evidence);
   if (!template || row.to_kind === 'event' && variables === undefined)
     return undefined;
-  const substitution = substituteVariables(template, variables ?? {});
+  const skeleton = eventSkeleton(evidence);
+  const substitution = substituteVariables(
+    template, eventTemplateVariables(skeleton, variables ?? {}),
+  );
   const effectiveRow = runtimeEventRow(
     row, evidence, substitution, template,
   );

package/src/trace/event-shape-candidate-trace.ts

@@ -0,0 +1,172 @@
+import type { Db } from '../db/connection.js';
+import type { TraceOptions } from '../types.js';
+import {
+  operationNode,
+  symbolNode,
+  type TraceGraphEdgeRow,
+} from './trace-graph-lookups.js';
+import type { TraceGraphRow } from './evidence.js';
+import {
+  eventMissingVariableNames,
+  eventTemplateVariables,
+  parseEventSkeletonFact,
+} from '../utils/event-skeleton.js';
+
+const defaultEventShapeCandidateCap = 5;
+const maximumEventShapeCandidateCap = 50;
+
+function candidateCap(options: TraceOptions): number {
+  const value = options.maxDynamicCandidates
+    ?? defaultEventShapeCandidateCap;
+  if (!Number.isSafeInteger(value) || value < 1)
+    return defaultEventShapeCandidateCap;
+  return Math.min(value, maximumEventShapeCandidateCap);
+}
+
+function withCandidateCounts(
+  row: TraceGraphEdgeRow,
+  total: number,
+  shown: number,
+): TraceGraphEdgeRow {
+  let evidence: Record<string, unknown> = {};
+  try {
+    const parsed: unknown = JSON.parse(row.evidence_json);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+      evidence = parsed as Record<string, unknown>;
+  } catch {
+    evidence = {};
+  }
+  return {
+    ...row,
+    evidence_json: JSON.stringify({
+      ...evidence,
+      eventShapeCandidateCount: total,
+      shownEventShapeCandidateCount: shown,
+      omittedEventShapeCandidateCount: Math.max(0, total - shown),
+    }),
+  };
+}
+
+export function visibleEventShapeRows(
+  rows: readonly TraceGraphEdgeRow[],
+  options: TraceOptions,
+): TraceGraphEdgeRow[] {
+  const regular = rows.filter((row) =>
+    row.edge_type !== 'EVENT_SHAPE_CANDIDATE_SUBSCRIBER');
+  if ((options.dynamicMode ?? 'strict') !== 'candidates') return regular;
+  const candidates = rows.filter((row) =>
+    row.edge_type === 'EVENT_SHAPE_CANDIDATE_SUBSCRIBER');
+  const shown = candidates.slice(0, candidateCap(options));
+  return [
+    ...regular,
+    ...shown.map((row) =>
+      withCandidateCounts(row, candidates.length, shown.length)),
+  ];
+}
+
+export function outboundTraceEdgeType(
+  call: { call_type: string },
+  row: { edge_type: string; to_kind: string },
+): string {
+  if (row.edge_type === 'EVENT_SHAPE_CANDIDATE_SUBSCRIBER')
+    return 'event_shape_candidate_subscriber';
+  if (row.to_kind === 'operation'
+    && row.edge_type === 'REMOTE_CALL_RESOLVES_TO_OPERATION')
+    return 'remote_action';
+  if (row.to_kind === 'operation'
+    && row.edge_type === 'LOCAL_CALL_RESOLVES_TO_OPERATION')
+    return 'local_service_call';
+  return call.call_type;
+}
+
+export function outboundTraceTargetNode(
+  db: Db,
+  id: string,
+  row: TraceGraphRow,
+): Record<string, unknown> {
+  const operation = row.to_kind === 'operation'
+    ? operationNode(db, row.to_id) : undefined;
+  const candidate = row.edge_type === 'EVENT_SHAPE_CANDIDATE_SUBSCRIBER'
+    ? symbolNode(db, Number(row.to_id)) : undefined;
+  return operation ?? candidate ?? {
+    id,
+    kind: row.to_kind,
+    label: row.to_kind === 'db_entity'
+      ? `Entity: ${row.to_id || 'unknown'}` : row.to_id,
+  };
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === 'string') : [];
+}
+
+function subscriberSkeletons(
+  db: Db,
+  workspaceId: number,
+  publishCallId: number,
+): unknown[] {
+  return db.prepare(`SELECT subscription.event_skeleton_json skeleton
+    FROM outbound_calls publication
+    JOIN repositories publication_repo ON publication_repo.id=publication.repo_id
+    JOIN outbound_calls subscription
+      ON subscription.call_type='async_subscribe'
+      AND subscription.event_skeleton_signature
+        =publication.event_skeleton_signature
+    JOIN repositories subscription_repo
+      ON subscription_repo.id=subscription.repo_id
+      AND subscription_repo.workspace_id=publication_repo.workspace_id
+    WHERE publication.id=? AND publication_repo.workspace_id=?
+      AND publication.event_skeleton_signature IS NOT NULL
+    ORDER BY subscription_repo.name COLLATE BINARY,
+      subscription.repo_id,subscription.source_file COLLATE BINARY,
+      subscription.call_site_start_offset,subscription.id`).all(
+    publishCallId, workspaceId,
+  ).map((row) => row.skeleton);
+}
+
+export function eventShapeMissingVariableEvidence(
+  db: Db,
+  workspaceId: number,
+  publishCallId: number,
+  evidence: Record<string, unknown>,
+  variables: Record<string, string> | undefined,
+): Record<string, unknown> {
+  const current = stringArray(evidence.missingRuntimeVariables);
+  if (current.length === 0) return evidence;
+  const names = new Set(current);
+  let matchingSubscriptions = 0;
+  for (const value of subscriberSkeletons(db, workspaceId, publishCallId)) {
+    const skeleton = parseEventSkeletonFact(value);
+    if (!skeleton?.candidateEligible) continue;
+    matchingSubscriptions += 1;
+    const expanded = eventTemplateVariables(skeleton, variables ?? {});
+    const missing = skeleton.sourceKeys.filter((key) =>
+      !Object.hasOwn(expanded, key));
+    for (const name of eventMissingVariableNames(skeleton, missing))
+      names.add(name);
+  }
+  const missing = [...names].sort((left, right) =>
+    left < right ? -1 : left > right ? 1 : 0);
+  return {
+    ...evidence,
+    missingRuntimeVariables: missing,
+    missingVariableCount: missing.length,
+    eventShapeMatchingSubscriptionCount: matchingSubscriptions,
+  };
+}
+
+export function eventShapeRuntimeEvidence(
+  db: Db,
+  workspaceId: number,
+  callId: number,
+  callType: string,
+  evidence: Record<string, unknown>,
+  variables: Record<string, string> | undefined,
+): Record<string, unknown> {
+  return callType === 'async_emit'
+    ? eventShapeMissingVariableEvidence(
+        db, workspaceId, callId, evidence, variables,
+      )
+    : evidence;
+}

package/src/trace/event-subscriber-traversal.ts

@@ -8,6 +8,10 @@ import {
   type TraversalScopeScheduler,
   type TraversalScopeState,
 } from './traversal-scope.js';
+import {
+  eventTemplateVariables,
+  parseEventSkeletonFact,
+} from '../utils/event-skeleton.js';
 
 export type EventSubscriberTransitionStatus =
   | 'resolved'
@@ -96,7 +100,8 @@ export function planEventSubscriberTransitions(
 ): PlannedEventSubscriberTransition[] {
   return loadEventSubscriberTransitions(db, query).map((transition) => {
     const handler = transition.handler;
-    if (!handler) return plannedTransition(transition, 'not_resolved');
+    if (transition.status !== 'resolved' || !handler)
+      return plannedTransition(transition, 'not_resolved');
     if (depth >= maxDepth)
       return plannedTransition(transition, 'depth_limited');
     const state = scheduler.schedule({
@@ -245,13 +250,15 @@ function eventRowForQuery(
   row: Record<string, unknown>,
   query: EventSubscriberTransitionQuery,
 ): Record<string, unknown> | undefined {
+  const exact = exactPersistedEventRow(row, query);
+  if (exact) return exact;
   const variables = query.vars;
-  if (variables === undefined) return exactPersistedEventRow(row, query);
+  if (variables === undefined) return undefined;
   const evidence = parseEvidence(row.evidenceJson);
   const resolution = isRecord(evidence.eventTemplateResolution)
     ? evidence.eventTemplateResolution : {};
   if (typeof resolution.original !== 'string')
-    return exactPersistedEventRow(row, query);
+    return undefined;
   return runtimeMatchedEventRow(
     row, query, evidence, resolution.original, variables,
   );
@@ -272,7 +279,10 @@ function runtimeMatchedEventRow(
   template: string,
   variables: Record<string, string>,
 ): Record<string, unknown> | undefined {
-  const substitution = substituteVariables(template, variables);
+  const skeleton = parseEventSkeletonFact(evidence.eventSkeleton);
+  const substitution = substituteVariables(
+    template, eventTemplateVariables(skeleton, variables),
+  );
   if (substitution.missing.length > 0
     || substitution.effective !== query.eventName) return undefined;
   const resolvedAssociation = evidence.associationStatus === 'resolved';
@@ -295,8 +305,7 @@ export function eventSubscriberMissingVariables(
   db: Db,
   query: EventSubscriberTransitionQuery,
 ): string[] {
-  if (query.vars === undefined) return [];
-  const variables = query.vars;
+  const variables = query.vars ?? {};
   const rows = db.prepare(`SELECT ge.from_id eventName,
     ge.evidence_json evidenceJson FROM graph_edges ge
     WHERE ge.workspace_id=? AND ge.generation=?
@@ -311,7 +320,10 @@ export function eventSubscriberMissingVariables(
     const template = typeof resolution.original === 'string'
       ? resolution.original : undefined;
     if (!template) return [];
-    const substitution = substituteVariables(template, variables);
+    const skeleton = parseEventSkeletonFact(evidence.eventSkeleton);
+    const substitution = substituteVariables(
+      template, eventTemplateVariables(skeleton, variables),
+    );
     if (substitution.missing.length === 0
       || matchRuntimeTemplate(
         substitution.effective, query.eventName,

package/src/trace/evidence.ts

@@ -262,6 +262,8 @@ function runtimeDiagnosticTotals(
     const effective = parseObject(edge.evidence.effectiveResolution);
     if (!['dynamic', 'unresolved', 'ambiguous'].includes(String(effective.status ?? '')))
       continue;
+    for (const key of stringArray(edge.evidence.missingRuntimeVariables))
+      missing.add(key);
     const substitutions = edge.evidence.runtimeSubstitutions;
     if (!substitutions || typeof substitutions !== 'object' || Array.isArray(substitutions)) continue;
     for (const value of Object.values(substitutions as Record<string, RuntimeSubstitution>))
@@ -648,6 +650,11 @@ function stringValue(value: unknown): string | undefined {
   return typeof value === 'string' ? value : undefined;
 }
 
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === 'string') : [];
+}
+
 function numeric(value: unknown): number {
   return typeof value === 'number' && Number.isFinite(value) ? value : 0;
 }

package/src/trace/trace-scope-execution.ts

@@ -20,7 +20,6 @@ import {
 import type { PlannedEventSubscriberTransition } from './event-subscriber-traversal.js';
 import {
   graphForCalls,
-  operationNode,
   symbolNode,
   type TraceGraphEdgeRow,
 } from './trace-graph-lookups.js';
@@ -51,6 +50,12 @@ import type { ImplementationHintOptions } from './trace-implementation-scope.js'
 import { processOperationTarget } from './trace-operation-execution.js';
 import { runtimeEventResolution, runtimeEventSubscriberPlans } from './event-runtime-resolution.js';
 import { planLocalCallExpansion } from './local-call-expansion.js';
+import {
+  eventShapeRuntimeEvidence,
+  outboundTraceEdgeType,
+  outboundTraceTargetNode,
+  visibleEventShapeRows,
+} from './event-shape-candidate-trace.js';
 
 export interface CallRow extends Record<string, unknown> {
   id: number;
@@ -90,16 +95,6 @@ export interface TraceExecutionRuntime {
   recorder: TraceEdgeRecorder;
 }
 
-function traceEdgeType(call: CallRow, row: TraceGraphRow): string {
-  if (row.to_kind === 'operation'
-    && row.edge_type === 'REMOTE_CALL_RESOLVES_TO_OPERATION')
-    return 'remote_action';
-  if (row.to_kind === 'operation'
-    && row.edge_type === 'LOCAL_CALL_RESOLVES_TO_OPERATION')
-    return 'local_service_call';
-  return String(call.call_type);
-}
-
 function includeCall(type: string, options: TraceOptions): boolean {
   if (!options.includeDb && type === 'local_db_query') return false;
   if (!options.includeExternal && type === 'external_http') return false;
@@ -339,7 +334,9 @@ function processOutboundCall(
   const contextual = contextualRuntimeResolution(
     runtime.db, call, bindings.get(receiver), call.workspaceId, persistedRows,
   );
-  const rows = contextual.row ? [contextual.row] : persistedRows;
+  const rows = contextual.row
+    ? [contextual.row]
+    : visibleEventShapeRows(persistedRows, runtime.options);
   for (const row of rows)
     processOutboundRow(runtime, current, call, { ...row }, contextual);
 }
@@ -385,16 +382,23 @@ function recordEffectiveOutbound(
 ): EffectiveOutbound {
   const persisted = parseTraceEvidence(row.evidence_json);
   const raw = baseTraceEvidence(row, call, persisted, contextual.evidence);
-  const effective = runtimeEventResolution(row, raw, runtime.options.vars)
+  const resolved = runtimeEventResolution(row, raw, runtime.options.vars)
     ?? runtimeResolution(runtime.db, row, raw, {
       vars: runtime.options.vars,
       dynamicMode: runtime.options.dynamicMode ?? 'strict',
       maxDynamicCandidates: runtime.options.maxDynamicCandidates,
     }, call.workspaceId, contextual.state);
+  const effective = {
+    ...resolved,
+    evidence: eventShapeRuntimeEvidence(
+      runtime.db, call.workspaceId, call.id, call.call_type,
+      resolved.evidence, runtime.options.vars,
+    ),
+  };
   const target = `${effective.row.to_kind}:${effective.row.to_id}`;
-  const operation = effective.row.to_kind === 'operation'
-    ? operationNode(runtime.db, effective.row.to_id) : undefined;
-  runtime.nodes.set(target, operation ?? targetNode(target, effective.row));
+  runtime.nodes.set(
+    target, outboundTraceTargetNode(runtime.db, target, effective.row),
+  );
   const to = edgeTarget(effective.row, effective.evidence);
   const edge = outboundTraceEdge(
     current.depth, call, effective.row, to,
@@ -418,18 +422,6 @@ function recordEffectiveOutbound(
   };
 }
 
-function targetNode(
-  id: string,
-  row: TraceGraphRow,
-): Record<string, unknown> {
-  return {
-    id,
-    kind: row.to_kind,
-    label: row.to_kind === 'db_entity'
-      ? `Entity: ${row.to_id || 'unknown'}` : row.to_id,
-  };
-}
-
 function outboundTraceEdge(
   depth: number,
   call: CallRow,
@@ -440,7 +432,7 @@ function outboundTraceEdge(
 ): TraceEdge {
   return {
     step: depth,
-    type: traceEdgeType(call, row),
+    type: outboundTraceEdgeType(call, row),
     from: `${call.repoName}:${call.source_file}:${call.source_line}`,
     to,
     evidence,

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { EventSkeletonFact } from './utils/event-skeleton.js';
+
 export type RepoKind =
   | 'cap-service'
   | 'cap-db-model'
@@ -36,6 +38,7 @@ export type EdgeType =
   | 'HANDLER_EMITS_EVENT'
   | 'EVENT_CONSUMED_BY_HANDLER'
   | 'EVENT_SUBSCRIPTION_HANDLED_BY'
+  | 'EVENT_SHAPE_CANDIDATE_SUBSCRIBER'
   | 'REPO_IMPORTS_HELPER_PACKAGE'
   | 'HELPER_PACKAGE_PROVIDES_HANDLER'
   | 'DYNAMIC_EDGE_CANDIDATE'
@@ -229,6 +232,7 @@ export interface OutboundCallFact {
   operationPathExpr?: string;
   queryEntity?: string;
   eventNameExpr?: string;
+  eventSkeleton?: EventSkeletonFact;
   payloadSummary?: string;
   sourceFile: string;
   sourceLine: number;
@@ -272,9 +276,21 @@ export interface SymbolCallFact {
 }
 export interface GeneratedConstantFact {
   name: string;
-  value: string;
+  value?: string;
   sourceFile: string;
   sourceLine: number;
+  containerName?: string;
+  memberName?: string;
+  constantKind: 'const_identifier' | 'enum_member' | 'const_object_property';
+  exported: boolean;
+  stable: boolean;
+  resolutionStatus: 'resolved' | 'refused';
+  unresolvedReason?: 'event_name_constant_member_not_string'
+    | 'event_name_constant_container_mutable';
+  declarationStartOffset: number;
+  declarationEndOffset: number;
+  valueStartOffset: number;
+  valueEndOffset: number;
 }
 export interface TraceStart {
   repo?: string;

package/src/utils/event-skeleton.ts

@@ -0,0 +1,207 @@
+import { sha256Text } from './hashing.js';
+import { scanPlaceholderStructure } from './placeholders.js';
+import type {
+  EventEnvironmentReference,
+} from '../parsers/event-environment-reference.js';
+
+export const EVENT_SKELETON_SCHEMA = 'service-flow/event-skeleton@1';
+export const EVENT_SKELETON_LITERAL_THRESHOLD = 8;
+export const EVENT_SKELETON_TEXT_LIMIT = 512;
+
+export interface EventSkeletonFact {
+  schema: typeof EVENT_SKELETON_SCHEMA;
+  status: 'complete' | 'malformed' | 'too_large';
+  signature: string | null;
+  literalSpans: string[];
+  holeCount: number;
+  sourceKeys: string[];
+  canonicalKeys: string[];
+  candidateEligible: boolean;
+  environmentBindings: EventEnvironmentReference[];
+  reason?: string;
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown> : undefined;
+}
+
+function parseJson(value: unknown): unknown {
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+function stringArray(value: unknown): string[] | undefined {
+  return Array.isArray(value) && value.every((item) =>
+    typeof item === 'string')
+    ? value as string[] : undefined;
+}
+
+function canonicalKey(signature: string, index: number): string {
+  return `event.${signature.slice(0, 16)}.hole${index + 1}`;
+}
+
+function skeletonSignature(
+  literalSpans: readonly string[],
+  holeCount: number,
+): string {
+  return sha256Text(JSON.stringify({ literalSpans, holeCount }));
+}
+
+function completeSkeleton(
+  template: string,
+): EventSkeletonFact {
+  const scan = scanPlaceholderStructure(template);
+  if (scan.status === 'malformed') return {
+    schema: EVENT_SKELETON_SCHEMA,
+    status: 'malformed',
+    signature: null,
+    literalSpans: [],
+    holeCount: 0,
+    sourceKeys: [],
+    canonicalKeys: [],
+    candidateEligible: false,
+    environmentBindings: [],
+    reason: scan.reason,
+  };
+  const literals: string[] = [];
+  let cursor = 0;
+  for (const span of scan.spans) {
+    literals.push(template.slice(cursor, span.start));
+    cursor = span.end;
+  }
+  literals.push(template.slice(cursor));
+  const signature = skeletonSignature(literals, scan.spans.length);
+  return {
+    schema: EVENT_SKELETON_SCHEMA,
+    status: 'complete',
+    signature,
+    literalSpans: literals,
+    holeCount: scan.spans.length,
+    sourceKeys: scan.spans.map((span) => span.key.trim()),
+    canonicalKeys: scan.spans.map((_, index) =>
+      canonicalKey(signature, index)),
+    candidateEligible: scan.spans.length > 0
+      && literals.some((literal) =>
+        literal.length >= EVENT_SKELETON_LITERAL_THRESHOLD),
+    environmentBindings: [],
+  };
+}
+
+function validCompleteSkeleton(
+  item: Record<string, unknown>,
+  literals: string[],
+  sourceKeys: string[],
+  canonicalKeys: string[],
+): boolean {
+  const holes = item.holeCount;
+  const signature = item.signature;
+  if (!Number.isInteger(holes) || Number(holes) < 1
+    || typeof signature !== 'string'
+    || !/^[a-f0-9]{64}$/.test(signature)) return false;
+  const count = Number(holes);
+  return literals.length === count + 1
+    && sourceKeys.length === count
+    && canonicalKeys.length === count
+    && sourceKeys.every((key) => key.length > 0 && key === key.trim())
+    && canonicalKeys.every((key, index) =>
+      key === canonicalKey(signature, index))
+    && new Set(canonicalKeys).size === canonicalKeys.length
+    && signature === skeletonSignature(literals, count)
+    && item.candidateEligible === literals.some((literal) =>
+      literal.length >= EVENT_SKELETON_LITERAL_THRESHOLD)
+    && item.reason === undefined;
+}
+
+function validClosedSkeleton(
+  item: Record<string, unknown>,
+  literals: string[],
+  sourceKeys: string[],
+  canonicalKeys: string[],
+): boolean {
+  const reason = item.reason;
+  if (item.signature !== null || item.holeCount !== 0
+    || item.candidateEligible !== false
+    || literals.length > 0 || sourceKeys.length > 0
+    || canonicalKeys.length > 0
+    || !Array.isArray(item.environmentBindings)
+    || item.environmentBindings.length > 0) return false;
+  if (item.status === 'too_large')
+    return reason === 'event_skeleton_text_limit_exceeded';
+  return item.status === 'malformed'
+    && typeof reason === 'string' && reason.length > 0;
+}
+
+export function parseEventSkeletonFact(
+  value: unknown,
+): EventSkeletonFact | undefined {
+  const item = record(parseJson(value));
+  if (!item || item.schema !== EVENT_SKELETON_SCHEMA
+    || !['complete', 'malformed', 'too_large'].includes(String(item.status))
+    || !Array.isArray(item.environmentBindings)) return undefined;
+  const literals = stringArray(item.literalSpans);
+  const sourceKeys = stringArray(item.sourceKeys);
+  const canonicalKeys = stringArray(item.canonicalKeys);
+  if (!literals || !sourceKeys || !canonicalKeys) return undefined;
+  const valid = item.status === 'complete'
+    ? validCompleteSkeleton(item, literals, sourceKeys, canonicalKeys)
+    : validClosedSkeleton(item, literals, sourceKeys, canonicalKeys);
+  return valid ? item as unknown as EventSkeletonFact : undefined;
+}
+
+export function deriveEventSkeleton(
+  template: string | undefined,
+): EventSkeletonFact | undefined {
+  if (!template || !template.includes('${')) return undefined;
+  if (template.length <= EVENT_SKELETON_TEXT_LIMIT)
+    return completeSkeleton(template);
+  return {
+    schema: EVENT_SKELETON_SCHEMA,
+    status: 'too_large',
+    signature: null,
+    literalSpans: [],
+    holeCount: 0,
+    sourceKeys: [],
+    canonicalKeys: [],
+    candidateEligible: false,
+    environmentBindings: [],
+    reason: 'event_skeleton_text_limit_exceeded',
+  };
+}
+
+export function eventTemplateVariables(
+  skeleton: EventSkeletonFact | undefined,
+  variables: Record<string, string>,
+): Record<string, string> {
+  if (!skeleton || skeleton.status !== 'complete') return variables;
+  const expanded = { ...variables };
+  for (let index = 0; index < skeleton.sourceKeys.length; index += 1) {
+    const sourceKey = skeleton.sourceKeys[index];
+    const canonicalKeyValue = skeleton.canonicalKeys[index];
+    if (!sourceKey || !canonicalKeyValue
+      || Object.hasOwn(expanded, sourceKey)
+      || !Object.hasOwn(expanded, canonicalKeyValue)) continue;
+    expanded[sourceKey] = expanded[canonicalKeyValue] ?? '';
+  }
+  return expanded;
+}
+
+export function eventMissingVariableNames(
+  skeleton: EventSkeletonFact | undefined,
+  missingSourceKeys: readonly string[],
+): string[] {
+  const names = new Set(missingSourceKeys);
+  if (skeleton?.status === 'complete')
+    for (let index = 0; index < skeleton.sourceKeys.length; index += 1) {
+      const sourceKey = skeleton.sourceKeys[index];
+      const canonical = skeleton.canonicalKeys[index];
+      if (sourceKey && canonical && names.has(sourceKey))
+        names.add(canonical);
+    }
+  return [...names].sort((left, right) =>
+    left < right ? -1 : left > right ? 1 : 0);
+}

package/src/version.ts

@@ -1,4 +1,4 @@
 import packageJson from '../package.json' with { type: 'json' };
 
 export const VERSION = packageJson.version;
-export const ANALYZER_VERSION = '0.1.69-facts.1';
+export const ANALYZER_VERSION = '0.1.71-facts.1';