@saptools/service-flow 0.1.67 → 0.1.69

package/src/db/012-binding-reference-proof.ts

@@ -0,0 +1,268 @@
+import type {
+  LexicalScopeFact,
+  ServiceBindingReference,
+} from '../types.js';
+
+export interface BindingProofCall {
+  repoId: number;
+  bindingId: number | null;
+  variableName?: string;
+  sourceFile: string;
+  startOffset: number;
+  endOffset: number;
+}
+
+export interface BindingProofTarget {
+  id: number;
+  repoId: number;
+  symbolId: number | null;
+  variableName: string;
+  sourceFile: string;
+  startOffset: number;
+  endOffset: number;
+  ownerResolution: string;
+  ownerStartOffset: number | null;
+  ownerEndOffset: number | null;
+  singleHopHelperReturn: boolean;
+}
+
+interface ResolvedBindingProof {
+  variableName: string;
+  bindingSourceFile: string;
+  bindingSiteStartOffset: number;
+  bindingSiteEndOffset: number;
+  resolutionStrategy: NonNullable<
+    ServiceBindingReference['resolutionStrategy']
+  >;
+  lexicalScopeChain: LexicalScopeFact[];
+  bindingScopeIndex: number;
+}
+
+const scopeKinds = new Set([
+  'source_file', 'module_block', 'function', 'class', 'loop',
+  'case_block', 'block', 'catch',
+]);
+const strategies = new Set([
+  'lexical_declaration',
+  'lexical_alias_declaration',
+  'deterministic_reaching_assignment',
+  'single_hop_helper_return',
+]);
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined;
+}
+
+function integer(value: unknown): value is number {
+  return Number.isInteger(value);
+}
+
+function nonEmpty(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function all(values: readonly boolean[]): boolean {
+  return values.every(Boolean);
+}
+
+export function validBindingLexicalScope(
+  value: unknown,
+): value is LexicalScopeFact {
+  const scope = record(value);
+  return Boolean(scope && scopeKinds.has(String(scope.kind))
+    && integer(scope.startOffset) && integer(scope.endOffset)
+    && Number(scope.startOffset) >= 0
+    && Number(scope.endOffset) > Number(scope.startOffset));
+}
+
+export function bindingReferenceCountsValid(
+  reference: Record<string, unknown>,
+): boolean {
+  const total = reference.scopeChainTotal;
+  const shown = reference.scopeChainShown;
+  const omitted = reference.scopeChainOmitted;
+  return integer(total) && integer(shown) && integer(omitted)
+    && total >= 0 && shown >= 0 && omitted >= 0 && shown <= 16
+    && shown + omitted === total;
+}
+
+function scopeArray(value: unknown): LexicalScopeFact[] | undefined {
+  if (!Array.isArray(value) || !value.every(validBindingLexicalScope))
+    return undefined;
+  return value;
+}
+
+function resolvedProofFields(
+  call: BindingProofCall,
+  reference: Record<string, unknown>,
+): boolean {
+  return all([
+    reference.status === 'resolved_exact',
+    nonEmpty(reference.variableName),
+    call.variableName === undefined
+      || reference.variableName === call.variableName,
+    reference.bindingSourceFile === call.sourceFile,
+    integer(reference.bindingSiteStartOffset),
+    integer(reference.bindingSiteEndOffset),
+    strategies.has(String(reference.resolutionStrategy)),
+    reference.reason === undefined,
+  ]);
+}
+
+function resolvedProof(
+  call: BindingProofCall,
+  value: unknown,
+): ResolvedBindingProof | undefined {
+  const reference = record(value);
+  if (!reference || !resolvedProofFields(call, reference)) return undefined;
+  const chain = scopeArray(reference.lexicalScopeChain);
+  const index = reference.bindingScopeIndex;
+  if (!chain || !integer(index) || !resolvedChainValid(
+    reference, chain, index,
+  )) return undefined;
+  if (!resolvedProofValuesValid(reference)) return undefined;
+  return {
+    variableName: reference.variableName,
+    bindingSourceFile: reference.bindingSourceFile,
+    bindingSiteStartOffset: reference.bindingSiteStartOffset,
+    bindingSiteEndOffset: reference.bindingSiteEndOffset,
+    resolutionStrategy: reference.resolutionStrategy,
+    lexicalScopeChain: chain,
+    bindingScopeIndex: index,
+  };
+}
+
+function resolvedProofValuesValid(
+  value: Record<string, unknown>,
+): value is Record<string, unknown> & {
+  variableName: string;
+  bindingSourceFile: string;
+  bindingSiteStartOffset: number;
+  bindingSiteEndOffset: number;
+  resolutionStrategy: ResolvedBindingProof['resolutionStrategy'];
+} {
+  return all([
+    nonEmpty(value.variableName),
+    nonEmpty(value.bindingSourceFile),
+    integer(value.bindingSiteStartOffset),
+    integer(value.bindingSiteEndOffset),
+    strategies.has(String(value.resolutionStrategy)),
+  ]);
+}
+
+function resolvedChainValid(
+  reference: Record<string, unknown>,
+  chain: readonly LexicalScopeFact[],
+  index: number,
+): boolean {
+  return all([
+    index >= 0,
+    index < chain.length,
+    chain[0]?.kind === 'source_file',
+    bindingReferenceCountsValid(reference),
+    reference.scopeChainShown === chain.length,
+    reference.scopeChainOmitted === 0,
+  ]);
+}
+
+function contains(
+  scope: LexicalScopeFact,
+  startOffset: number,
+  endOffset: number,
+): boolean {
+  return scope.startOffset <= startOffset && scope.endOffset >= endOffset;
+}
+
+function strictlyNested(scopes: readonly LexicalScopeFact[]): boolean {
+  return scopes.every((scope, index) => {
+    const child = scopes[index + 1];
+    return !child || contains(scope, child.startOffset, child.endOffset)
+      && (scope.startOffset < child.startOffset
+        || scope.endOffset > child.endOffset);
+  });
+}
+
+function deepestContainingScopeIndex(
+  chain: readonly LexicalScopeFact[],
+  startOffset: number,
+  endOffset: number,
+): number {
+  let result = -1;
+  chain.forEach((scope, index) => {
+    if (contains(scope, startOffset, endOffset)) result = index;
+  });
+  return result;
+}
+
+function scopeProofValid(
+  call: BindingProofCall,
+  reference: ResolvedBindingProof,
+): boolean {
+  const chain = reference.lexicalScopeChain;
+  const siteStart = reference.bindingSiteStartOffset;
+  const siteEnd = reference.bindingSiteEndOffset;
+  const scopeIndex = reference.bindingScopeIndex;
+  const deepest = deepestContainingScopeIndex(chain, siteStart, siteEnd);
+  const siteScopeValid = reference.resolutionStrategy
+    === 'deterministic_reaching_assignment'
+    ? deepest >= scopeIndex
+    : deepest === scopeIndex;
+  return all([
+    siteStart >= 0, siteEnd > siteStart, siteEnd <= call.startOffset,
+    strictlyNested(chain),
+    chain.every((scope) => contains(scope, call.startOffset, call.endOffset)),
+    chain.slice(0, scopeIndex + 1).every((scope) =>
+      contains(scope, siteStart, siteEnd)),
+    siteScopeValid,
+  ]);
+}
+
+function ownerCompatible(
+  call: BindingProofCall,
+  target: BindingProofTarget,
+): boolean {
+  if (target.ownerResolution === 'ownerless_file_scope')
+    return target.symbolId === null
+      && target.ownerStartOffset === null && target.ownerEndOffset === null;
+  return all([
+    target.ownerResolution === 'owned_exact',
+    target.symbolId !== null,
+    integer(target.ownerStartOffset),
+    integer(target.ownerEndOffset),
+    Number(target.ownerStartOffset) <= target.startOffset,
+    Number(target.ownerEndOffset) >= target.endOffset,
+    Number(target.ownerStartOffset) <= call.startOffset,
+    Number(target.ownerEndOffset) >= call.endOffset,
+  ]);
+}
+
+function targetMatches(
+  call: BindingProofCall,
+  reference: ResolvedBindingProof,
+  target: BindingProofTarget | undefined,
+): boolean {
+  if (!target || call.bindingId !== target.id) return false;
+  if (reference.resolutionStrategy === 'single_hop_helper_return'
+    && !target.singleHopHelperReturn) return false;
+  return all([
+    target.repoId === call.repoId,
+    target.sourceFile === call.sourceFile,
+    target.sourceFile === reference.bindingSourceFile,
+    target.variableName === reference.variableName,
+    target.startOffset === reference.bindingSiteStartOffset,
+    target.endOffset === reference.bindingSiteEndOffset,
+    ownerCompatible(call, target),
+  ]);
+}
+
+export function resolvedBindingReferenceProofValid(
+  call: BindingProofCall,
+  referenceValue: unknown,
+  target: BindingProofTarget | undefined,
+): boolean {
+  const reference = resolvedProof(call, referenceValue);
+  return Boolean(reference && scopeProofValid(call, reference)
+    && targetMatches(call, reference, target));
+}

package/src/db/013-index-publication-failure.ts

@@ -0,0 +1,91 @@
+import type { Db } from './connection.js';
+
+export type PreparedRepositoryFactKind =
+  | 'outbound_call'
+  | 'service_binding'
+  | 'symbol_call';
+
+export type PreparedSnapshotFailureCode =
+  | 'binding_lexical_proof_invalid'
+  | 'binding_owner_mismatch'
+  | 'binding_reference_mismatch'
+  | 'binding_reference_missing'
+  | 'binding_site_missing'
+  | 'duplicate_service_binding_site'
+  | 'outbound_owner_mismatch'
+  | 'package_import_provenance_missing'
+  | 'symbol_call_owner_mismatch';
+
+export interface PreparedSnapshotFailureSite {
+  factKind: PreparedRepositoryFactKind;
+  sourceFile?: string;
+  sourceLine?: number;
+  callSiteStartOffset?: number;
+  callSiteEndOffset?: number;
+}
+
+export class PreparedRepositorySnapshotError extends Error {
+  readonly failureCode: PreparedSnapshotFailureCode;
+  readonly site: PreparedSnapshotFailureSite;
+
+  constructor(
+    failureCode: PreparedSnapshotFailureCode,
+    site: PreparedSnapshotFailureSite,
+  ) {
+    super(`invalid_prepared_repository_snapshot:${failureCode}`);
+    this.name = 'PreparedRepositorySnapshotError';
+    this.failureCode = failureCode;
+    this.site = site;
+  }
+}
+
+interface PreparedCallSite {
+  sourceFile: string;
+  sourceLine: number;
+  callSiteStartOffset?: number;
+  callSiteEndOffset?: number;
+}
+
+export function preparedCallSnapshotError(
+  failureCode: PreparedSnapshotFailureCode,
+  factKind: 'outbound_call' | 'symbol_call',
+  call: PreparedCallSite,
+): PreparedRepositorySnapshotError {
+  return new PreparedRepositorySnapshotError(failureCode, {
+    factKind,
+    sourceFile: call.sourceFile,
+    sourceLine: call.sourceLine,
+    callSiteStartOffset: call.callSiteStartOffset,
+    callSiteEndOffset: call.callSiteEndOffset,
+  });
+}
+
+export function isPreparedRepositorySnapshotError(
+  error: unknown,
+): error is PreparedRepositorySnapshotError {
+  return error instanceof PreparedRepositorySnapshotError;
+}
+
+export function recordPreparedSnapshotFailure(
+  db: Db,
+  repoId: number,
+  error: PreparedRepositorySnapshotError,
+): void {
+  db.prepare(`UPDATE repositories SET index_status='failed',
+    error_count=1 WHERE id=?`).run(repoId);
+  db.prepare(`DELETE FROM diagnostics WHERE repo_id=? AND (
+    code IN ('index_failed_snapshot_preserved','source_read_failed')
+    OR code GLOB 'invalid_prepared_repository_snapshot:*'
+  )`).run(repoId);
+  db.prepare(`INSERT INTO diagnostics(
+    repo_id,severity,code,message,source_file,source_line
+  ) VALUES(?,?,?,?,?,?)`).run(
+    repoId,
+    'error',
+    error.message,
+    'Index publication failed before commit for this repository; previous facts and fingerprint were preserved. '
+      + `factKind=${error.site.factKind}`,
+    error.site.sourceFile,
+    error.site.sourceLine,
+  );
+}

package/src/db/014-binding-helper-provenance.ts

@@ -0,0 +1,17 @@
+function record(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function parsed(value: string): unknown {
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+export function hasSingleHopHelperReturn(value: unknown): boolean {
+  const chain = typeof value === 'string' ? parsed(value) : value;
+  return Array.isArray(chain) && chain.some((step) =>
+    record(step) && step.bindingOrigin === 'single_hop_helper_return');
+}

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 = 12;
+export const CURRENT_SCHEMA_VERSION = 13;
 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 '{}'" },
@@ -8,6 +8,9 @@ const columns: Record<string, Array<{ name: string; ddl: string }>> = {
   service_bindings: [
     { name: 'helper_chain_json', ddl: 'ALTER TABLE service_bindings ADD COLUMN helper_chain_json TEXT' },
     { name: 'alias_expr', ddl: 'ALTER TABLE service_bindings ADD COLUMN alias_expr TEXT' },
+    { name: 'binding_site_start_offset', ddl: 'ALTER TABLE service_bindings ADD COLUMN binding_site_start_offset INTEGER' },
+    { name: 'binding_site_end_offset', ddl: 'ALTER TABLE service_bindings ADD COLUMN binding_site_end_offset INTEGER' },
+    { name: 'owner_resolution', ddl: "ALTER TABLE service_bindings ADD COLUMN owner_resolution TEXT NOT NULL DEFAULT 'legacy_unknown' CHECK(owner_resolution IN ('owned_exact','ownerless_file_scope','legacy_unknown'))" },
   ],
   repositories: [
     { name: 'fingerprint', ddl: 'ALTER TABLE repositories ADD COLUMN fingerprint TEXT' },
@@ -16,6 +19,7 @@ const columns: Record<string, Array<{ name: string; ddl: string }>> = {
     { name: 'graph_stale_reason', ddl: 'ALTER TABLE repositories ADD COLUMN graph_stale_reason TEXT' },
     { 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' },
   ],
   graph_edges: [
     { name: 'status', ddl: "ALTER TABLE graph_edges ADD COLUMN status TEXT NOT NULL DEFAULT 'unresolved'" },
@@ -81,7 +85,8 @@ function addMissingColumns(db: Db): void {
     }
   }
 }
-function normalizeLegacyStatus(db: Db): void {
+function normalizeLegacyStatus(db: Db, priorVersion: number): void {
+  if (priorVersion >= 12) return;
   db.prepare("UPDATE graph_edges SET status=CASE WHEN edge_type='REMOTE_CALL_RESOLVES_TO_OPERATION' THEN 'resolved' WHEN edge_type IN ('HANDLER_RUNS_DB_QUERY','HANDLER_CALLS_EXTERNAL_HTTP','HANDLER_EMITS_EVENT','EVENT_CONSUMED_BY_HANDLER') THEN 'terminal' WHEN edge_type='DYNAMIC_EDGE_CANDIDATE' THEN 'dynamic' WHEN status='ambiguous' THEN 'ambiguous' ELSE status END").run();
   db.prepare("UPDATE repositories SET graph_stale_reason='schema_migration_requires_relink', graph_stale_at=COALESCE(graph_stale_at, datetime('now')) WHERE EXISTS (SELECT 1 FROM graph_edges WHERE graph_edges.workspace_id=repositories.workspace_id) AND graph_generation=0").run();
 }
@@ -92,6 +97,13 @@ function markCallSiteMigrationStale(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 markFactProvenanceMigrationStale(db: Db, priorVersion: number): void {
+  if (priorVersion >= 13) return;
+  db.prepare(`UPDATE repositories
+    SET graph_stale_reason='schema_v13_fact_provenance_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);
@@ -99,8 +111,9 @@ export function migrate(db: Db): void {
     db.exec(schemaTablesSql);
     addMissingColumns(db);
     db.exec(schemaIndexesSql);
-    normalizeLegacyStatus(db);
+    normalizeLegacyStatus(db, version);
     markCallSiteMigrationStale(db, version);
+    markFactProvenanceMigrationStale(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/repositories.ts

@@ -8,6 +8,14 @@ import type {
   ServiceBindingFact,
   ExecutableSymbolFact,
 } from '../types.js';
+import {
+  selectCallOwner,
+  type OwnerCandidate,
+} from '../parsers/004-fact-identity.js';
+import {
+  PreparedRepositorySnapshotError,
+  type PreparedSnapshotFailureCode,
+} from './013-index-publication-failure.js';
 export interface RepoRow {
   id: number;
   name: string;
@@ -28,6 +36,24 @@ export interface WorkspaceRow {
   root_path: string;
   db_path: string;
 }
+function initialPackagePublicSurface(packageName?: string): string {
+  return JSON.stringify({
+    schema: 'service-flow/package-public-surface@1',
+    status: packageName ? 'incomplete' : 'not_applicable',
+    reason: packageName ? 'package_surface_pending_index' : null,
+    recordCap: 256,
+    total: 0,
+    shown: 0,
+    omitted: 0,
+    packageName: packageName ?? null,
+    exportsPresent: false,
+    exportsAuthoritative: false,
+    main: null,
+    module: null,
+    entries: [],
+    scopes: [],
+  });
+}
 export function upsertWorkspace(
   db: Db,
   rootPath: string,
@@ -64,7 +90,15 @@ export function upsertRepository(
   },
 ): number {
   db.prepare(
-    `INSERT INTO repositories(workspace_id,name,absolute_path,relative_path,package_name,package_version,dependencies_json,kind,is_git_repo) VALUES(?,?,?,?,?,?,?,?,?) ON CONFLICT(workspace_id,absolute_path) DO UPDATE SET name=excluded.name,relative_path=excluded.relative_path,package_name=excluded.package_name,package_version=excluded.package_version,dependencies_json=excluded.dependencies_json,kind=excluded.kind`,
+    `INSERT INTO repositories(workspace_id,name,absolute_path,relative_path,
+      package_name,package_version,dependencies_json,
+      package_public_surface_json,kind,is_git_repo)
+    VALUES(?,?,?,?,?,?,?,?,?,?)
+    ON CONFLICT(workspace_id,absolute_path) DO UPDATE SET
+      name=excluded.name,relative_path=excluded.relative_path,
+      package_name=excluded.package_name,
+      package_version=excluded.package_version,
+      dependencies_json=excluded.dependencies_json,kind=excluded.kind`,
   ).run(
     workspaceId,
     r.name,
@@ -73,6 +107,7 @@ export function upsertRepository(
     r.packageName,
     r.packageVersion,
     JSON.stringify(r.dependencies ?? {}),
+    initialPackagePublicSurface(r.packageName),
     r.kind ?? 'unknown',
     r.isGitRepo ? 1 : 0,
   );
@@ -355,16 +390,14 @@ export function insertBindings(
   repoId: number,
   rows: ServiceBindingFact[],
 ): void {
+  assertUniquePreparedBindingSites(rows);
   const stmt = db.prepare(
-    'INSERT INTO service_bindings(repo_id,symbol_id,variable_name,alias,alias_expr,destination_expr,service_path_expr,is_dynamic,placeholders_json,source_file,source_line,helper_chain_json) VALUES(?,(SELECT id FROM symbols WHERE repo_id=? AND source_file=? AND start_line<=? AND end_line>=? ORDER BY (end_line-start_line),id LIMIT 1),?,?,?,?,?,?,?,?,?,?)',
+    'INSERT INTO service_bindings(repo_id,symbol_id,variable_name,alias,alias_expr,destination_expr,service_path_expr,is_dynamic,placeholders_json,source_file,source_line,binding_site_start_offset,binding_site_end_offset,owner_resolution,helper_chain_json) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)',
   );
   for (const r of rows)
     stmt.run(
       repoId,
-      repoId,
-      r.sourceFile,
-      r.sourceLine,
-      r.sourceLine,
+      bindingOwnerId(db, repoId, r),
       r.variableName,
       r.alias,
       r.aliasExpr,
@@ -374,9 +407,100 @@ export function insertBindings(
       JSON.stringify(r.placeholders),
       r.sourceFile,
       r.sourceLine,
+      r.bindingSiteStartOffset,
+      r.bindingSiteEndOffset,
+      r.ownerResolution,
       r.helperChain ? JSON.stringify(r.helperChain) : null,
     );
 }
+
+interface PersistedOwnerCandidate extends OwnerCandidate {
+  id: number;
+}
+
+function bindingSnapshotError(
+  failureCode: PreparedSnapshotFailureCode,
+  fact: ServiceBindingFact,
+): PreparedRepositorySnapshotError {
+  return new PreparedRepositorySnapshotError(failureCode, {
+    factKind: 'service_binding',
+    sourceFile: fact.sourceFile,
+    sourceLine: fact.sourceLine,
+    callSiteStartOffset: fact.bindingSiteStartOffset,
+    callSiteEndOffset: fact.bindingSiteEndOffset,
+  });
+}
+
+function persistedOwnerCandidates(
+  db: Db,
+  repoId: number,
+  fact: ServiceBindingFact,
+): PersistedOwnerCandidate[] {
+  const rows = db.prepare(`SELECT id,kind,qualified_name qualifiedName,
+    start_offset startOffset,end_offset endOffset FROM symbols
+    WHERE repo_id=? AND source_file=? AND start_offset<=? AND end_offset>=?`)
+    .all(
+      repoId, fact.sourceFile, fact.bindingSiteStartOffset,
+      fact.bindingSiteEndOffset,
+    );
+  return rows.flatMap((row) =>
+    typeof row.id === 'number' && typeof row.kind === 'string'
+      && typeof row.qualifiedName === 'string'
+      && typeof row.startOffset === 'number'
+      && typeof row.endOffset === 'number'
+      ? [{
+          id: row.id,
+          kind: row.kind,
+          qualifiedName: row.qualifiedName,
+          startOffset: row.startOffset,
+          endOffset: row.endOffset,
+        }]
+      : []);
+}
+
+function bindingOwnerId(
+  db: Db,
+  repoId: number,
+  fact: ServiceBindingFact,
+): number | null {
+  const candidates = persistedOwnerCandidates(db, repoId, fact);
+  const selected = selectCallOwner(
+    candidates,
+    fact.bindingSiteStartOffset ?? -1,
+    fact.bindingSiteEndOffset ?? -1,
+  );
+  if (fact.ownerResolution === 'ownerless_file_scope') {
+    if (selected.status !== 'none')
+      throw bindingSnapshotError('binding_owner_mismatch', fact);
+    return null;
+  }
+  if (fact.ownerResolution !== 'owned_exact'
+    || selected.status !== 'resolved'
+    || selected.owner?.qualifiedName !== fact.sourceSymbolQualifiedName)
+    throw bindingSnapshotError('binding_owner_mismatch', fact);
+  const owner = selected.owner;
+  if (!owner)
+    throw bindingSnapshotError('binding_owner_mismatch', fact);
+  return owner.id;
+}
+
+function assertUniquePreparedBindingSites(
+  rows: readonly ServiceBindingFact[],
+): void {
+  const seen = new Set<string>();
+  for (const row of rows) {
+    if (row.bindingSiteStartOffset === undefined
+      || row.bindingSiteEndOffset === undefined)
+      throw bindingSnapshotError('binding_site_missing', row);
+    const key = [
+      row.sourceFile, row.variableName,
+      row.bindingSiteStartOffset, row.bindingSiteEndOffset,
+    ].join('\u0000');
+    if (seen.has(key))
+      throw bindingSnapshotError('duplicate_service_binding_site', row);
+    seen.add(key);
+  }
+}
 export function insertExecutableSymbols(db: Db, repoId: number, rows: ExecutableSymbolFact[]): void {
   const stmt = db.prepare('INSERT INTO symbols(repo_id,file_id,kind,name,qualified_name,exported,start_line,end_line,start_offset,end_offset,source_file,exported_name,evidence_json) VALUES(?,(SELECT id FROM files WHERE repo_id=? AND relative_path=?),?,?,?,?,?,?,?,?,?,?,?)');
   for (const r of rows) stmt.run(repoId, repoId, r.sourceFile, r.kind, r.localName, r.qualifiedName, r.exported ? 1 : 0, r.startLine, r.endLine, r.startOffset, r.endOffset, r.sourceFile, r.exportedName, r.importExportEvidence ? JSON.stringify(r.importExportEvidence) : null);

package/src/db/schema.ts

@@ -1,6 +1,6 @@
 export const schemaTablesSql = `
 CREATE TABLE IF NOT EXISTS workspaces (id INTEGER PRIMARY KEY, root_path TEXT UNIQUE NOT NULL, db_path TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL);
-CREATE TABLE IF NOT EXISTS repositories (id INTEGER PRIMARY KEY, workspace_id INTEGER NOT NULL, name TEXT NOT NULL, absolute_path TEXT NOT NULL, relative_path TEXT NOT NULL, package_name TEXT, package_version TEXT, dependencies_json TEXT DEFAULT '{}', kind TEXT NOT NULL, is_git_repo INTEGER NOT NULL, last_indexed_at TEXT, index_status TEXT DEFAULT 'pending', error_count INTEGER DEFAULT 0, fingerprint TEXT, fact_generation INTEGER NOT NULL DEFAULT 0, graph_generation INTEGER NOT NULL DEFAULT 0, graph_stale_reason TEXT, graph_stale_at TEXT, fact_analyzer_version TEXT, UNIQUE(workspace_id, absolute_path), FOREIGN KEY(workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE);
+CREATE TABLE IF NOT EXISTS repositories (id INTEGER PRIMARY KEY, workspace_id INTEGER NOT NULL, name TEXT NOT NULL, absolute_path TEXT NOT NULL, relative_path TEXT NOT NULL, package_name TEXT, package_version TEXT, dependencies_json TEXT DEFAULT '{}', package_public_surface_json TEXT, kind TEXT NOT NULL, is_git_repo INTEGER NOT NULL, last_indexed_at TEXT, index_status TEXT DEFAULT 'pending', error_count INTEGER DEFAULT 0, fingerprint TEXT, fact_generation INTEGER NOT NULL DEFAULT 0, graph_generation INTEGER NOT NULL DEFAULT 0, graph_stale_reason TEXT, graph_stale_at TEXT, fact_analyzer_version TEXT, UNIQUE(workspace_id, absolute_path), FOREIGN KEY(workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE);
 CREATE TABLE IF NOT EXISTS files (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, relative_path TEXT NOT NULL, extension TEXT NOT NULL, sha256 TEXT NOT NULL, size_bytes INTEGER NOT NULL, last_indexed_at TEXT NOT NULL, UNIQUE(repo_id, relative_path), FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE);
 CREATE TABLE IF NOT EXISTS cds_requires (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, alias TEXT NOT NULL, kind TEXT, model TEXT, destination TEXT, service_path TEXT, request_timeout INTEGER, raw_json TEXT NOT NULL, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE);
 CREATE TABLE IF NOT EXISTS cds_services (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, namespace TEXT, service_name TEXT NOT NULL, qualified_name TEXT NOT NULL, service_path TEXT NOT NULL, is_extend INTEGER NOT NULL, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, extension_local_ref TEXT, extension_imported_symbol TEXT, extension_local_alias TEXT, extension_module_specifier TEXT, extension_import_kind TEXT, extension_base_service_id INTEGER, extension_base_status TEXT, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(extension_base_service_id) REFERENCES cds_services(id) ON DELETE SET NULL);
@@ -9,7 +9,7 @@ CREATE TABLE IF NOT EXISTS symbols (id INTEGER PRIMARY KEY, repo_id INTEGER NOT
 CREATE TABLE IF NOT EXISTS handler_classes (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, symbol_id INTEGER, class_name TEXT NOT NULL, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(symbol_id) REFERENCES symbols(id) ON DELETE SET NULL);
 CREATE TABLE IF NOT EXISTS handler_methods (id INTEGER PRIMARY KEY, handler_class_id INTEGER NOT NULL, method_name TEXT NOT NULL, decorator_kind TEXT NOT NULL, decorator_value TEXT, decorator_raw_expression TEXT NOT NULL, decorator_resolution_json TEXT NOT NULL DEFAULT '{}', source_file TEXT NOT NULL, source_line INTEGER NOT NULL, FOREIGN KEY(handler_class_id) REFERENCES handler_classes(id) ON DELETE CASCADE);
 CREATE TABLE IF NOT EXISTS handler_registrations (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, handler_class_id INTEGER, class_name TEXT, import_source TEXT, registration_file TEXT NOT NULL, registration_line INTEGER NOT NULL, registration_kind TEXT NOT NULL, confidence REAL NOT NULL, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(handler_class_id) REFERENCES handler_classes(id) ON DELETE SET NULL);
-CREATE TABLE IF NOT EXISTS service_bindings (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, symbol_id INTEGER, variable_name TEXT NOT NULL, alias TEXT, alias_expr TEXT, destination_expr TEXT, service_path_expr TEXT, is_dynamic INTEGER NOT NULL, placeholders_json TEXT NOT NULL, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, helper_chain_json TEXT, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(symbol_id) REFERENCES symbols(id) ON DELETE SET NULL);
+CREATE TABLE IF NOT EXISTS service_bindings (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, symbol_id INTEGER, variable_name TEXT NOT NULL, alias TEXT, alias_expr TEXT, destination_expr TEXT, service_path_expr TEXT, is_dynamic INTEGER NOT NULL, placeholders_json TEXT NOT NULL, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, binding_site_start_offset INTEGER, binding_site_end_offset INTEGER, owner_resolution TEXT NOT NULL DEFAULT 'legacy_unknown' CHECK(owner_resolution IN ('owned_exact','ownerless_file_scope','legacy_unknown')), helper_chain_json TEXT, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(symbol_id) REFERENCES symbols(id) ON DELETE SET NULL);
 CREATE TABLE IF NOT EXISTS outbound_calls (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, source_symbol_id INTEGER, call_type TEXT NOT NULL, service_binding_id INTEGER, method TEXT, operation_path_expr TEXT, query_entity TEXT, event_name_expr TEXT, payload_summary TEXT, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, call_site_start_offset INTEGER, call_site_end_offset INTEGER, confidence REAL NOT NULL, unresolved_reason TEXT, local_service_name TEXT, local_service_lookup TEXT, alias_chain_json TEXT, evidence_json TEXT, external_target_kind TEXT, external_target_id TEXT, external_target_label TEXT, external_target_dynamic INTEGER NOT NULL DEFAULT 0, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(source_symbol_id) REFERENCES symbols(id) ON DELETE SET NULL, FOREIGN KEY(service_binding_id) REFERENCES service_bindings(id) ON DELETE SET NULL);
 CREATE TABLE IF NOT EXISTS symbol_calls (id INTEGER PRIMARY KEY, repo_id INTEGER NOT NULL, caller_symbol_id INTEGER NOT NULL, callee_symbol_id INTEGER, callee_expression TEXT NOT NULL, import_source TEXT, source_file TEXT NOT NULL, source_line INTEGER NOT NULL, call_site_start_offset INTEGER, call_site_end_offset INTEGER, call_role TEXT NOT NULL DEFAULT 'legacy_unknown', status TEXT NOT NULL, confidence REAL NOT NULL, evidence_json TEXT NOT NULL, unresolved_reason TEXT, FOREIGN KEY(repo_id) REFERENCES repositories(id) ON DELETE CASCADE, FOREIGN KEY(caller_symbol_id) REFERENCES symbols(id) ON DELETE CASCADE, FOREIGN KEY(callee_symbol_id) REFERENCES symbols(id) ON DELETE SET NULL);
 CREATE TABLE IF NOT EXISTS graph_edges (id INTEGER PRIMARY KEY, workspace_id INTEGER NOT NULL, edge_type TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'unresolved', from_kind TEXT NOT NULL, from_id TEXT NOT NULL, to_kind TEXT NOT NULL, to_id TEXT NOT NULL, confidence REAL NOT NULL, evidence_json TEXT NOT NULL, is_dynamic INTEGER NOT NULL, unresolved_reason TEXT, generation INTEGER NOT NULL DEFAULT 0, FOREIGN KEY(workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE);
@@ -27,6 +27,8 @@ CREATE INDEX IF NOT EXISTS idx_calls_repo ON outbound_calls(repo_id, call_type);
 CREATE INDEX IF NOT EXISTS idx_symbol_calls_caller ON symbol_calls(repo_id, caller_symbol_id);
 CREATE INDEX IF NOT EXISTS idx_outbound_call_site ON outbound_calls(repo_id, source_file, call_site_start_offset, call_site_end_offset, call_type);
 CREATE INDEX IF NOT EXISTS idx_symbol_call_site_role ON symbol_calls(repo_id, source_file, call_site_start_offset, call_site_end_offset, call_role);
+CREATE INDEX IF NOT EXISTS idx_service_binding_site ON service_bindings(repo_id,source_file,variable_name,binding_site_start_offset,binding_site_end_offset);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_service_binding_exact_site ON service_bindings(repo_id,source_file,variable_name,binding_site_start_offset,binding_site_end_offset) WHERE binding_site_start_offset IS NOT NULL AND binding_site_end_offset IS NOT NULL;
 CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(kind, name, path, repo);
 `;
 

package/src/index.ts

@@ -35,3 +35,15 @@ export type {
 export { parseImplementationHint } from './trace/implementation-hints.js';
 export type { DynamicMode, ImplementationHint, TraceOptions } from './types.js';
 export { redactValue, redactText } from './utils/redaction.js';
+export type { Db } from './db/connection.js';
+export type {
+  CallType,
+  EdgeType,
+  ExecutableSymbolFact,
+  OutboundCallFact,
+  SymbolCallFact,
+  SymbolCallRole,
+  TraceEdge,
+  TraceResult,
+  TraceStart,
+} from './types.js';