@titan-design/code-graph 0.9.2 → 0.11.0

package/README.md

@@ -271,6 +271,22 @@ snapshots and buckets each violation as new, resolved, or unchanged; unchanged m
 violations are further split into worsened and improved by value. From-side ids follow the
 alias chain, as in the ratchet.
 
+`computeFootprints({ nodes, edges }, options)` gives each symbol node a footprint built from
+structural inputs only, so a moved declaration or a churn window never reads as a change. It
+has three parts, each a `hashText` over canonical JSON: `signature` (name, exported, signature,
+purpose; no span), `consumers` (sorted distinct files with a `references` edge into the symbol),
+and `coupling` (sorted co-import partners at or above `minCoImports`, default 2). `hash` combines
+the three. Consumers include test files unless `ignoreConsumer(fileId)` rejects them; a rejected
+file is dropped from coupling too. `symbolSetHash({ unitId, symbolIds }, footprints)` hashes a
+doc unit's sorted `[symbolId, footprint.hash]` pairs, so it ignores member order and changes when
+a member is added, removed or changed.
+
+`diffFootprints(store, { fromSnapshotId, toSnapshotId, ...options })` compares the footprints of
+two snapshots. From-side ids follow the alias chain first, and a symbol under a moved file follows
+its file, so a move reads as `changed` with `reasons: ["renamed"]` alone when its footprint held.
+Each other change is `added`, `removed`, or `changed` with the differing parts (`signature`,
+`consumers`, `coupling`). `files` rolls the changes up to their declaring files, never to consumers.
+
 `scripts/dag-check-self.mjs` in the repo root runs this repo's DAG check on this engine
 instead of codewatch's CLI.
 

package/dist/index.d.ts

@@ -307,8 +307,12 @@ declare class TsMorphGraphExtractor implements Extractor<GraphFragment> {
     private readonly repoRoot;
     private readonly tsConfigPath?;
     private project?;
+    private readonly ownsProject;
+    private readonly retired;
     constructor(options: TsMorphGraphExtractorOptions);
     extract(file: ParsedFile): GraphFragment[];
+    private retire;
+    private extractFrom;
     private ensureProject;
     private loadSourceFile;
     private buildFileAndModuleNodes;
@@ -1423,6 +1427,27 @@ interface GraphDiffSummary {
     removedEdges: number;
     metricChanges: number;
 }
+/** Why a symbol present in both snapshots changed; `renamed` alone means its footprint held. */
+type FootprintChangeReason = "signature" | "consumers" | "coupling" | "renamed";
+interface FootprintChange {
+    /** The to-snapshot id; a removed symbol keeps its from-snapshot id. */
+    symbolId: string;
+    /** The from-snapshot id, set only when it differs from `symbolId`. */
+    previousId?: string;
+    status: "added" | "removed" | "changed";
+    /** Empty for an added or removed symbol. */
+    reasons: FootprintChangeReason[];
+    /** The declaring file, in the to-snapshot's id space where it still exists there. */
+    fileId: string;
+}
+interface FootprintDiff {
+    fromSnapshotId: number;
+    toSnapshotId: number;
+    /** Sorted by `symbolId`; an unchanged symbol is absent. */
+    changes: FootprintChange[];
+    /** Sorted distinct declaring files of `changes`; consumer files never appear here. */
+    files: string[];
+}
 interface GraphDiff {
     summary: GraphDiffSummary;
     addedNodes: GraphNode[];
@@ -1470,6 +1495,97 @@ interface DiffCheckResultsOptions {
  */
 declare function diffCheckResults(store: CodeGraphStore, options: DiffCheckResultsOptions): CheckDiff;
 
+/**
+ * A symbol's documentable footprint (C-75): structural inputs only, so a moved declaration,
+ * a churn window or a centrality shift never reads as a change.
+ */
+interface FootprintParts {
+    /** Hash of `{name, exported, signature, purpose}`; no span. */
+    signature: string;
+    /** Hash of the sorted distinct file ids that reference the symbol. */
+    consumers: string;
+    /** Hash of the sorted co-import partner symbol ids at or above `minCoImports`. */
+    coupling: string;
+}
+interface SymbolFootprint {
+    symbolId: string;
+    parts: FootprintParts;
+    /** Hash of the three part hashes. */
+    hash: string;
+}
+interface FootprintGraph {
+    nodes: readonly GraphNode[];
+    edges: readonly GraphEdge[];
+}
+interface FootprintOptions {
+    /** Drop a referencing file from consumers and co-import coupling, e.g. test files. Default keeps all. */
+    ignoreConsumer?: (fileId: string) => boolean;
+    /** Co-import threshold for a coupling partner. Default 2. */
+    minCoImports?: number;
+}
+/** A doc target: the default unit is one file holding its symbols. */
+interface FootprintUnit {
+    unitId: string;
+    symbolIds: readonly string[];
+}
+/** Footprint of every symbol node in the graph, keyed by symbol id. */
+declare function computeFootprints(graph: FootprintGraph, options?: FootprintOptions): Map<string, SymbolFootprint>;
+/**
+ * Order-independent hash of a unit's `[symbolId, footprint.hash]` pairs. A member with no
+ * footprint hashes as null, so a symbol that disappears still changes the set.
+ */
+declare function symbolSetHash(unit: FootprintUnit, footprints: ReadonlyMap<string, SymbolFootprint>): string;
+
+interface DiffFootprintsOptions extends FootprintOptions {
+    fromSnapshotId: number;
+    toSnapshotId: number;
+}
+/**
+ * Symbols whose documentable footprint differs between two snapshots. From-snapshot ids
+ * follow the alias chain first, so a moved file reads as `renamed`, not a remove plus an add.
+ */
+declare function diffFootprints(store: CodeGraphStore, options: DiffFootprintsOptions): FootprintDiff;
+
+/**
+ * What a consumer generated a unit's doc from. Provenance lives with the consumer, not the
+ * store, so it survives snapshot prune.
+ */
+interface UnitProvenance {
+    unitId: string;
+    /** The to-snapshot's commit hash; null for a working-tree snapshot. */
+    commit: string | null;
+    symbolSetHash: string;
+    /** The generator the consumer used; the gate records it but never calls one. */
+    model: string | null;
+}
+interface UnitProvenanceInput {
+    unit: FootprintUnit;
+    footprints: ReadonlyMap<string, SymbolFootprint>;
+    snapshot: Pick<SnapshotRow, "commitHash">;
+    model?: string | null;
+}
+type RegenerateReason = "new" | "changed";
+interface UnitRegeneration {
+    unitId: string;
+    reason: RegenerateReason;
+}
+interface GateUnitsInput {
+    prior: readonly UnitProvenance[];
+    units: readonly FootprintUnit[];
+    footprints: ReadonlyMap<string, SymbolFootprint>;
+}
+/** An empty `regenerate` means the caller makes no LLM call. */
+interface GateResult {
+    regenerate: UnitRegeneration[];
+    skip: string[];
+    /** Prior units that no longer exist. */
+    orphaned: string[];
+}
+/** A fresh provenance record for one unit at the given snapshot. */
+declare function unitProvenance(input: UnitProvenanceInput): UnitProvenance;
+/** Splits units into those whose symbol-set hash moved since the prior record and those that did not. */
+declare function gateUnits(input: GateUnitsInput): GateResult;
+
 interface EmbeddableSymbol {
     id: string;
     name: string;
@@ -1686,4 +1802,4 @@ declare function getConventionMap(store: CodeGraphStore, snapshotId: number, mod
  */
 declare function findConventions(store: CodeGraphStore, snapshotId: number, query: string, embedder: Embedder, model: string, opts?: FindConventionsOptions): Promise<ConventionQueryResult>;
 
-export { ALIAS_BASE_ATTR, ALL_ROLES, type AliasChain, type AliasChainInput, type AliasChainOptions, type AliasLoader, type AliasResolution, COMMUNITY_SUMMARY_NAMESPACE, COVERAGE_METRIC_NAME, type CachedEmbedResult, type CheckDiff, type CheckResult, type CheckRule, type CheckRulesFile, type CheckSnapshotOptions, type CheckSnapshotResult, type CheckViolation, CodeGraphStore, type ConventionArea, type ConventionCorpus, type ConventionCoverage, type ConventionMap, type ConventionMatch, type ConventionOptions, type ConventionQueryResult, type ConventionSymbol, DEAD_CODE_METRIC_NAMES, DEFAULT_CHURN_WINDOWS, DEFAULT_OUTLIER_MIN_SAMPLE, DOMAIN_DDL, type DeepAst, type DeepAstInput, type DiffCheckResultsOptions, type DiffSnapshotsOptions, EXCEPTION_METRIC_NAMES, type EdgeKind, type EmbedAttempt, type EmbedCoverage, type EmbedSnapshotResult, type EmbeddableSymbol, type ExternalDiagnostic, FINDING_DDL, type FileFingerprint, type FindConventionsOptions, type FindSimilarOptions, type Finding, type FindingKeyInput, type ForbidImportRule, GROWTH_RISK_METRIC_NAMES, type GraphDiff, type GraphDiffSummary, type GraphEdge, type GraphFragment, type GraphMetric, type GraphNode, type HistoryMetricsOptions, INDEX_VERSION, type IdAlias, type IdAliasReason, type IndexOptions, type IndexResult, type IstanbulCoverage, KIT, LanguageExtractor, type LanguageExtractorOptions, type LayeredDepsRule, type LineSpan, type Lineage, type LineageSnapshot, type LineageStep, type LinkMethod, type LinkTestsOptions, type LoadedHistory, METRIC_CATALOGUE, MIGRATIONS, type MemberInfo, type MetricAbsence, type MetricAggregate, type MetricDelta, type MetricDescriptor, type MetricDirection, type MetricMaxRule, type MetricMinRule, type MetricOutlierRule, type MetricProductMaxRule, type MetricRollup, type MetricSource, type MetricUnit, type NoInternalOnlyBarrelsRule, type NodeKind, type NodeRename, type NodeRole, type PackageFlag, type PackageLayer, type PackageStats, type PageRankOptions, type PageRankResult, type PageRankRow, type PairCoupling, type PairFlag, type ParamInfo, type PartitionQualityInput, type PartitionQualityResult, type PriorSnapshotOptions, type PruneOptions, type PrunePlan, type PruneResult, PythonGraphExtractor, type ReadFile, type ReferenceEdgeLite, type RelevanceOptions, type ResolveAliasOptions, type ReuseBasis, type RuleStore, type RunChecksOptions, SCHEMA_VERSION, SNAPSHOT_SCOPED_TABLES, SOURCE_METRIC_NAMES, SYMBOL_EMBEDDING_NAMESPACE, SYMBOL_ID_SEP, SYMBOL_METRIC_NAMES, type Severity, type SimilarCandidate, type SimilarResult, type SnapshotInsert, type SnapshotRow, type SnapshotSpec, type SourceLanguage, type StoredFinding, type StoredVerdict, type SummarizeConventionsResult, type Summarizer, type SymbolConsumers, type SymbolCouplingOptions, type SymbolCouplingPair, type SymbolSpan, type TestCoverageOwnershipOptions, type TestSourceLink, type TopMetricRow, TsMorphGraphExtractor, type TsMorphGraphExtractorOptions, type UnchangedViolation, type ValidateRulesOptions, type VerdictCitation, type VerdictLabel, aggregateMetrics, aliasChain, annotateRoles, attributeCoverage, buildAliases, buildConventionAreas, buildEmbedText, buildFileModuleNodes, buildIndexerMetrics, buildLineage, canonicalEdgeKind, canonicalMetricName, canonicalRole, carryForwardVerdicts, checkSnapshot, classifyRole, collectDeclaredNames, collectDeclaredSpans, compilePatterns, computeDeadCodeMetrics, computeDeepAst, computeGrowthRiskMetrics, computeMetrics, computePageRank, computePartitionQuality, computeRecencyWindows, computeRelevance, computeRoleHints, computeSourceMetrics, computeSymbolConsumers, computeSymbolCoupling, computeTestCoverageOwnership, createAliasChain, defaultTargetCount, describeMetric, describeMetrics, detectCommunities, detectGitHead, detectGitToplevel, detectRenames, diffCheckResults, diffSnapshots, edgeWeight, embedSnapshot, embedTextsCached, externalId, externalToFinding, fileId, findConventions, findSimilarCapability, findingKey, getConventionMap, getEdgeWeight, groupTestsBySource, hashContent, hashEmbedText, hashText, indexPaths, invertBuckets, isGeneratedByHeuristic, isGeneratedFile, isInsideGitRepo, keyFindings, lineagePath, linkTestsToSources, listEdges, listEdgesTouching, listEmbeddableSymbols, listFindings, listMetrics, listMetricsForNode, listNodes, listVerdicts, loadCheckRules, loadGeneratedPatterns, loadHistoryMetrics, loadLineage, matchesAny, moduleId, normalizeFlaggedText, openCodeGraph, packageId, parentModuleId, parseSymbolId, patternToRegex, percentileOf, planPrune, priorSnapshotForRef, pruneDanglingReferences, readSourceFiles, rebasedViolationKey, resolveAlias, resolveBarrelEdges, resolveChurnWindows, resolveGitRef, resolveSnapshot, runChecks, runPrune, saveFindings, saveVerdicts, snapshotPageRank, snapshotReferenceEdges, snapshotRelevance, snapshotSymbolConsumers, snapshotSymbolCoupling, snapshotViolations, structuralSignature, summarizeConventions, symbolId, testCoverageCountMetrics, toFindings, tryEmbedSnapshot, validateRules, violationKey, walkSourceFiles, windowSuffix };
+export { ALIAS_BASE_ATTR, ALL_ROLES, type AliasChain, type AliasChainInput, type AliasChainOptions, type AliasLoader, type AliasResolution, COMMUNITY_SUMMARY_NAMESPACE, COVERAGE_METRIC_NAME, type CachedEmbedResult, type CheckDiff, type CheckResult, type CheckRule, type CheckRulesFile, type CheckSnapshotOptions, type CheckSnapshotResult, type CheckViolation, CodeGraphStore, type ConventionArea, type ConventionCorpus, type ConventionCoverage, type ConventionMap, type ConventionMatch, type ConventionOptions, type ConventionQueryResult, type ConventionSymbol, DEAD_CODE_METRIC_NAMES, DEFAULT_CHURN_WINDOWS, DEFAULT_OUTLIER_MIN_SAMPLE, DOMAIN_DDL, type DeepAst, type DeepAstInput, type DiffCheckResultsOptions, type DiffFootprintsOptions, type DiffSnapshotsOptions, EXCEPTION_METRIC_NAMES, type EdgeKind, type EmbedAttempt, type EmbedCoverage, type EmbedSnapshotResult, type EmbeddableSymbol, type ExternalDiagnostic, FINDING_DDL, type FileFingerprint, type FindConventionsOptions, type FindSimilarOptions, type Finding, type FindingKeyInput, type FootprintChange, type FootprintChangeReason, type FootprintDiff, type FootprintGraph, type FootprintOptions, type FootprintParts, type FootprintUnit, type ForbidImportRule, GROWTH_RISK_METRIC_NAMES, type GateResult, type GateUnitsInput, type GraphDiff, type GraphDiffSummary, type GraphEdge, type GraphFragment, type GraphMetric, type GraphNode, type HistoryMetricsOptions, INDEX_VERSION, type IdAlias, type IdAliasReason, type IndexOptions, type IndexResult, type IstanbulCoverage, KIT, LanguageExtractor, type LanguageExtractorOptions, type LayeredDepsRule, type LineSpan, type Lineage, type LineageSnapshot, type LineageStep, type LinkMethod, type LinkTestsOptions, type LoadedHistory, METRIC_CATALOGUE, MIGRATIONS, type MemberInfo, type MetricAbsence, type MetricAggregate, type MetricDelta, type MetricDescriptor, type MetricDirection, type MetricMaxRule, type MetricMinRule, type MetricOutlierRule, type MetricProductMaxRule, type MetricRollup, type MetricSource, type MetricUnit, type NoInternalOnlyBarrelsRule, type NodeKind, type NodeRename, type NodeRole, type PackageFlag, type PackageLayer, type PackageStats, type PageRankOptions, type PageRankResult, type PageRankRow, type PairCoupling, type PairFlag, type ParamInfo, type PartitionQualityInput, type PartitionQualityResult, type PriorSnapshotOptions, type PruneOptions, type PrunePlan, type PruneResult, PythonGraphExtractor, type ReadFile, type ReferenceEdgeLite, type RegenerateReason, type RelevanceOptions, type ResolveAliasOptions, type ReuseBasis, type RuleStore, type RunChecksOptions, SCHEMA_VERSION, SNAPSHOT_SCOPED_TABLES, SOURCE_METRIC_NAMES, SYMBOL_EMBEDDING_NAMESPACE, SYMBOL_ID_SEP, SYMBOL_METRIC_NAMES, type Severity, type SimilarCandidate, type SimilarResult, type SnapshotInsert, type SnapshotRow, type SnapshotSpec, type SourceLanguage, type StoredFinding, type StoredVerdict, type SummarizeConventionsResult, type Summarizer, type SymbolConsumers, type SymbolCouplingOptions, type SymbolCouplingPair, type SymbolFootprint, type SymbolSpan, type TestCoverageOwnershipOptions, type TestSourceLink, type TopMetricRow, TsMorphGraphExtractor, type TsMorphGraphExtractorOptions, type UnchangedViolation, type UnitProvenance, type UnitProvenanceInput, type UnitRegeneration, type ValidateRulesOptions, type VerdictCitation, type VerdictLabel, aggregateMetrics, aliasChain, annotateRoles, attributeCoverage, buildAliases, buildConventionAreas, buildEmbedText, buildFileModuleNodes, buildIndexerMetrics, buildLineage, canonicalEdgeKind, canonicalMetricName, canonicalRole, carryForwardVerdicts, checkSnapshot, classifyRole, collectDeclaredNames, collectDeclaredSpans, compilePatterns, computeDeadCodeMetrics, computeDeepAst, computeFootprints, computeGrowthRiskMetrics, computeMetrics, computePageRank, computePartitionQuality, computeRecencyWindows, computeRelevance, computeRoleHints, computeSourceMetrics, computeSymbolConsumers, computeSymbolCoupling, computeTestCoverageOwnership, createAliasChain, defaultTargetCount, describeMetric, describeMetrics, detectCommunities, detectGitHead, detectGitToplevel, detectRenames, diffCheckResults, diffFootprints, diffSnapshots, edgeWeight, embedSnapshot, embedTextsCached, externalId, externalToFinding, fileId, findConventions, findSimilarCapability, findingKey, gateUnits, getConventionMap, getEdgeWeight, groupTestsBySource, hashContent, hashEmbedText, hashText, indexPaths, invertBuckets, isGeneratedByHeuristic, isGeneratedFile, isInsideGitRepo, keyFindings, lineagePath, linkTestsToSources, listEdges, listEdgesTouching, listEmbeddableSymbols, listFindings, listMetrics, listMetricsForNode, listNodes, listVerdicts, loadCheckRules, loadGeneratedPatterns, loadHistoryMetrics, loadLineage, matchesAny, moduleId, normalizeFlaggedText, openCodeGraph, packageId, parentModuleId, parseSymbolId, patternToRegex, percentileOf, planPrune, priorSnapshotForRef, pruneDanglingReferences, readSourceFiles, rebasedViolationKey, resolveAlias, resolveBarrelEdges, resolveChurnWindows, resolveGitRef, resolveSnapshot, runChecks, runPrune, saveFindings, saveVerdicts, snapshotPageRank, snapshotReferenceEdges, snapshotRelevance, snapshotSymbolConsumers, snapshotSymbolCoupling, snapshotViolations, structuralSignature, summarizeConventions, symbolId, symbolSetHash, testCoverageCountMetrics, toFindings, tryEmbedSnapshot, unitProvenance, validateRules, violationKey, walkSourceFiles, windowSuffix };

package/dist/index.js

@@ -1223,20 +1223,36 @@ function literalText(arg) {
 }
 
 // src/extractors/ts-morph-extractor.ts
+var RETIRE_BATCH = 100;
 var TsMorphGraphExtractor = class {
   name = "ts-morph-graph";
   repoRoot;
   tsConfigPath;
   project;
+  ownsProject;
+  retired = [];
   constructor(options) {
     this.repoRoot = options.repoRoot;
     this.tsConfigPath = options.tsConfigPath;
     this.project = options.project;
+    this.ownsProject = options.project === void 0;
   }
   extract(file) {
     if (!isTypeScriptFile(file)) return [];
     const project = this.ensureProject();
     const sourceFile = this.loadSourceFile(project, file);
+    try {
+      return this.extractFrom(sourceFile, file);
+    } finally {
+      if (this.ownsProject) this.retire(project, sourceFile);
+    }
+  }
+  retire(project, sourceFile) {
+    this.retired.push(sourceFile);
+    if (this.retired.length < RETIRE_BATCH) return;
+    for (const sf of this.retired.splice(0)) project.removeSourceFile(sf);
+  }
+  extractFrom(sourceFile, file) {
     const nodes = this.buildFileAndModuleNodes(sourceFile);
     const symbolNodes2 = buildSymbolNodes(this.repoRoot, sourceFile, file);
     const { edges, externalNodes } = this.collectEdges(sourceFile);
@@ -3461,16 +3477,16 @@ function targetFileId(edge) {
 }
 function computeDeltaAffected(basis, currentFileIds) {
   const affected = /* @__PURE__ */ new Set();
-  const removed = /* @__PURE__ */ new Set();
+  const removed2 = /* @__PURE__ */ new Set();
   for (const id of basis.fingerprints.keys()) {
-    if (!currentFileIds.has(id)) removed.add(id);
+    if (!currentFileIds.has(id)) removed2.add(id);
   }
-  const added = currentFileIds.size !== basis.fingerprints.size || removed.size > 0;
+  const added = currentFileIds.size !== basis.fingerprints.size || removed2.size > 0;
   if (!added) return affected;
   for (const [srcId, edges] of basis.edgesBySrc) {
     if (!currentFileIds.has(srcId)) continue;
     for (const edge of edges) {
-      if (isEdgeAffected(edge, srcId, removed, currentFileIds)) {
+      if (isEdgeAffected(edge, srcId, removed2, currentFileIds)) {
         affected.add(srcId);
         break;
       }
@@ -3478,8 +3494,8 @@ function computeDeltaAffected(basis, currentFileIds) {
   }
   return affected;
 }
-function isEdgeAffected(edge, srcId, removed, currentFileIds) {
-  if (removed.has(targetFileId(edge))) return true;
+function isEdgeAffected(edge, srcId, removed2, currentFileIds) {
+  if (removed2.has(targetFileId(edge))) return true;
   const specifier = edge.attrs?.specifier;
   if (!specifier || !isRelative(specifier)) return false;
   return resolveRelativeId(srcId, specifier, currentFileIds) !== targetFileId(edge);
@@ -6071,13 +6087,13 @@ function indexEdges(edges) {
 function diffNodes(fromNodes, toNodes, aliases) {
   const toIndex = new Map(toNodes.map((n) => [n.id, n]));
   const matchedToIds = /* @__PURE__ */ new Set();
-  const removed = [];
+  const removed2 = [];
   const renamed = [];
   for (const fromNode of fromNodes) {
     const newId = resolveId(fromNode.id, aliases);
     const toNode = toIndex.get(newId);
     if (!toNode) {
-      removed.push(fromNode);
+      removed2.push(fromNode);
       continue;
     }
     matchedToIds.add(newId);
@@ -6086,7 +6102,7 @@ function diffNodes(fromNodes, toNodes, aliases) {
     }
   }
   const added = toNodes.filter((toNode) => !matchedToIds.has(toNode.id));
-  return { added, removed, renamed, commonNewIds: matchedToIds };
+  return { added, removed: removed2, renamed, commonNewIds: matchedToIds };
 }
 function diffEdges(fromEdges, toEdges, aliases) {
   const remappedKey = (e) => edgeKey2(resolveId(e.srcId, aliases), resolveId(e.dstId, aliases), e.kind);
@@ -6096,8 +6112,8 @@ function diffEdges(fromEdges, toEdges, aliases) {
   for (const [k, e] of toIndex) {
     if (!fromKeys.has(k)) added.push(e);
   }
-  const removed = fromEdges.filter((e) => !toIndex.has(remappedKey(e)));
-  return { added, removed };
+  const removed2 = fromEdges.filter((e) => !toIndex.has(remappedKey(e)));
+  return { added, removed: removed2 };
 }
 function indexFromMetrics(metrics, aliases) {
   const fromIndex = /* @__PURE__ */ new Map();
@@ -6207,6 +6223,176 @@ function computeDelta(from, to) {
   return to.value - from.value;
 }
 
+// src/diff/footprint.ts
+var DEFAULT_MIN_CO_IMPORTS2 = 2;
+function computeFootprints(graph, options = {}) {
+  const edges = referenceEdges(graph.edges, options.ignoreConsumer);
+  const consumers = consumersBySymbol(edges);
+  const partners = partnersBySymbol(edges, options.minCoImports ?? DEFAULT_MIN_CO_IMPORTS2);
+  const out = /* @__PURE__ */ new Map();
+  for (const node of graph.nodes) {
+    if (node.kind !== "symbol") continue;
+    const parts = {
+      signature: hashJson(signatureOf2(node)),
+      consumers: hashJson(consumers.get(node.id) ?? []),
+      coupling: hashJson(partners.get(node.id) ?? [])
+    };
+    const hash = hashJson([parts.signature, parts.consumers, parts.coupling]);
+    out.set(node.id, { symbolId: node.id, parts, hash });
+  }
+  return out;
+}
+function symbolSetHash(unit, footprints) {
+  const pairs = [...new Set(unit.symbolIds)].sort().map((id) => [id, footprints.get(id)?.hash ?? null]);
+  return hashJson(pairs);
+}
+function hashJson(value) {
+  return hashText(JSON.stringify(value));
+}
+function signatureOf2(node) {
+  const attrs = node.attrs ?? {};
+  return {
+    name: node.name,
+    exported: attrs.exported === true,
+    signature: typeof attrs.signature === "string" ? attrs.signature : null,
+    purpose: typeof attrs.purpose === "string" ? attrs.purpose : null
+  };
+}
+function referenceEdges(edges, ignoreConsumer) {
+  return edges.filter(
+    (e) => canonicalEdgeKind(e.kind) === "references" && !ignoreConsumer?.(e.srcId)
+  );
+}
+function consumersBySymbol(edges) {
+  return new Map(computeSymbolConsumers(edges).map((c) => [c.symbolId, c.consumers]));
+}
+function partnersBySymbol(edges, minCoImports) {
+  const partners = /* @__PURE__ */ new Map();
+  const add = (from, to) => {
+    const set = partners.get(from) ?? /* @__PURE__ */ new Set();
+    set.add(to);
+    partners.set(from, set);
+  };
+  for (const pair of computeSymbolCoupling(edges, { minCoImports })) {
+    add(pair.aId, pair.bId);
+    add(pair.bId, pair.aId);
+  }
+  return new Map([...partners].map(([id, set]) => [id, [...set].sort()]));
+}
+
+// src/diff/footprint-diff.ts
+var PART_REASONS = ["signature", "consumers", "coupling"];
+function diffFootprints(store, options) {
+  const { fromSnapshotId, toSnapshotId } = options;
+  const resolve4 = symbolAwareResolver(aliasChain(store, fromSnapshotId, toSnapshotId));
+  const fromGraph = loadSymbolLayer(store, fromSnapshotId);
+  const toGraph = loadSymbolLayer(store, toSnapshotId);
+  const { previousIds, mergedAway } = mergeSources(fromGraph.nodes, resolve4);
+  const before = computeFootprints(remapGraph(fromGraph, resolve4, new Set(mergedAway)), options);
+  const after = computeFootprints(toGraph, options);
+  const changes = [
+    ...changedOrAdded(after, before, previousIds),
+    ...removed(before, after, previousIds, resolve4),
+    ...mergedAway.map((id) => ({ symbolId: id, status: "removed", reasons: [], fileId: resolve4(declaringFile(id)) }))
+  ].sort((a, b) => compare2(a.symbolId, b.symbolId));
+  const files = [...new Set(changes.map((c) => c.fileId))].sort(compare2);
+  return { fromSnapshotId, toSnapshotId, changes, files };
+}
+function loadSymbolLayer(store, snapshotId) {
+  return {
+    nodes: store.listNodes(snapshotId, { includeSymbols: true }).filter((n) => n.kind === "symbol"),
+    edges: store.listEdges(snapshotId, { includeReferences: true })
+  };
+}
+function symbolAwareResolver(aliases) {
+  return (id) => {
+    const direct = aliases.resolve(id);
+    if (direct !== id) return direct;
+    const parsed = parseSymbolId(id);
+    return parsed ? symbolId(aliases.resolve(parsed.fileId), parsed.name) : id;
+  };
+}
+function remapGraph(graph, resolve4, losers) {
+  return {
+    nodes: graph.nodes.filter((n) => !losers.has(n.id)).map((n) => ({ ...n, id: resolve4(n.id) })),
+    edges: graph.edges.filter((e) => !losers.has(e.srcId) && !losers.has(e.dstId)).map((e) => ({ ...e, srcId: resolve4(e.srcId), dstId: resolve4(e.dstId) }))
+  };
+}
+function mergeSources(nodes, resolve4) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    const id = resolve4(node.id);
+    groups.set(id, [...groups.get(id) ?? [], node.id]);
+  }
+  const previousIds = /* @__PURE__ */ new Map();
+  const mergedAway = [];
+  for (const [id, sources] of groups) {
+    const keeper = sources.includes(id) ? id : [...sources].sort(compare2)[0];
+    if (keeper !== id) previousIds.set(id, keeper);
+    mergedAway.push(...sources.filter((source) => source !== keeper));
+  }
+  return { previousIds, mergedAway };
+}
+function changedOrAdded(after, before, previousIds) {
+  const out = [];
+  for (const [id, footprint] of after) {
+    const prior = before.get(id);
+    const previousId = previousIds.get(id);
+    if (!prior) {
+      out.push({ symbolId: id, status: "added", reasons: [], fileId: declaringFile(id) });
+      continue;
+    }
+    const reasons = reasonsFor(prior, footprint, previousId !== void 0);
+    if (reasons.length === 0) continue;
+    out.push({ symbolId: id, ...previousId ? { previousId } : {}, status: "changed", reasons, fileId: declaringFile(id) });
+  }
+  return out;
+}
+function reasonsFor(prior, current, renamed) {
+  const reasons = PART_REASONS.filter((part) => prior.parts[part] !== current.parts[part]);
+  if (renamed) reasons.push("renamed");
+  return reasons;
+}
+function removed(before, after, previousIds, resolve4) {
+  const out = [];
+  for (const id of before.keys()) {
+    if (after.has(id)) continue;
+    const fromId = previousIds.get(id) ?? id;
+    out.push({ symbolId: fromId, status: "removed", reasons: [], fileId: resolve4(declaringFile(fromId)) });
+  }
+  return out;
+}
+function declaringFile(id) {
+  return parseSymbolId(id)?.fileId ?? id;
+}
+function compare2(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+// src/diff/gate.ts
+function unitProvenance(input) {
+  return {
+    unitId: input.unit.unitId,
+    commit: input.snapshot.commitHash,
+    symbolSetHash: symbolSetHash(input.unit, input.footprints),
+    model: input.model ?? null
+  };
+}
+function gateUnits(input) {
+  const priorHash = new Map(input.prior.map((p) => [p.unitId, p.symbolSetHash]));
+  const current = new Set(input.units.map((u) => u.unitId));
+  const regenerate = [];
+  const skip = [];
+  for (const unit of input.units) {
+    const before = priorHash.get(unit.unitId);
+    if (before === void 0) regenerate.push({ unitId: unit.unitId, reason: "new" });
+    else if (before !== symbolSetHash(unit, input.footprints)) regenerate.push({ unitId: unit.unitId, reason: "changed" });
+    else skip.push(unit.unitId);
+  }
+  const orphaned = [...priorHash.keys()].filter((id) => !current.has(id));
+  return { regenerate, skip, orphaned };
+}
+
 // src/embeddings/corpus.ts
 import { contentHashOf } from "@titan-design/store-sqlite";
 function buildEmbedText(signature, purpose) {
@@ -6705,6 +6891,7 @@ export {
   compilePatterns,
   computeDeadCodeMetrics,
   computeDeepAst,
+  computeFootprints,
   computeGrowthRiskMetrics,
   computeMetrics,
   computePageRank,
@@ -6725,6 +6912,7 @@ export {
   detectGitToplevel,
   detectRenames,
   diffCheckResults,
+  diffFootprints,
   diffSnapshots,
   edgeWeight,
   embedSnapshot,
@@ -6735,6 +6923,7 @@ export {
   findConventions,
   findSimilarCapability,
   findingKey,
+  gateUnits,
   getConventionMap,
   getEdgeWeight,
   getLanguageFromPath3 as getLanguageFromPath,
@@ -6797,9 +6986,11 @@ export {
   structuralSignature,
   summarizeConventions,
   symbolId,
+  symbolSetHash,
   testCoverageCountMetrics,
   toFindings,
   tryEmbedSnapshot,
+  unitProvenance,
   validateRules,
   violationKey,
   walkSourceFiles,