@titan-design/code-graph 0.8.0 → 0.9.0

package/README.md

@@ -148,7 +148,7 @@ always recomputed over the whole assembled graph, so a heavily-reused run and a
 
 ## Store layout
 
-`openCodeGraph` opens the database with the kit's pragmas and runs three migrations.
+`openCodeGraph` opens the database with the kit's pragmas and runs four migrations.
 
 It refuses a database stamped past `SCHEMA_VERSION` with `SchemaTooNewError`: a code graph
 database belongs to one build, so a higher version means a newer build already moved the
@@ -163,7 +163,8 @@ every consumer reads directly: `node.language`, `node.role`, `snapshot.commit_ha
 Domain tables in `schema.ts`: `edge` (snapshot-scoped, keyed
 `(snapshot_id, src_id, dst_id, kind)` — the kit's own edge table is bi-temporal, which is the
 wrong time model for a population re-indexed all at once), `metric`, `id_alias`, and
-`file_fingerprint`.
+`file_fingerprint`. Migration 4 adds `finding` and `verdict`, both keyed
+`(snapshot_id, key)` on a `findingKey` and pruned with their snapshot.
 
 The symbol layer is hidden by default. `listNodes` drops `symbol` nodes and `listEdges` drops
 `references` and `calls` edges unless you ask for them (`includeReferences` covers both), so a caller reasoning about module structure sees

package/dist/index.d.ts

@@ -175,8 +175,14 @@ declare const KIT: {
  * `file_fingerprint` is the reuse basis the incremental indexer diffs against.
  */
 declare const DOMAIN_DDL = "\n  CREATE TABLE IF NOT EXISTS edge (\n    snapshot_id INTEGER NOT NULL,\n    src_id      TEXT NOT NULL,\n    dst_id      TEXT NOT NULL,\n    kind        TEXT NOT NULL,\n    attrs       TEXT,\n    PRIMARY KEY (snapshot_id, src_id, dst_id, kind)\n  );\n  CREATE INDEX IF NOT EXISTS idx_edge_dst ON edge(snapshot_id, dst_id);\n  CREATE INDEX IF NOT EXISTS idx_edge_kind ON edge(snapshot_id, kind);\n\n  CREATE TABLE IF NOT EXISTS metric (\n    snapshot_id INTEGER NOT NULL,\n    node_id     TEXT NOT NULL,\n    name        TEXT NOT NULL,\n    value       REAL,\n    unit        TEXT,\n    PRIMARY KEY (snapshot_id, node_id, name)\n  );\n  CREATE INDEX IF NOT EXISTS idx_metric_name ON metric(snapshot_id, name);\n\n  CREATE TABLE IF NOT EXISTS id_alias (\n    snapshot_id INTEGER NOT NULL,\n    old_id      TEXT NOT NULL,\n    new_id      TEXT NOT NULL,\n    reason      TEXT NOT NULL,\n    PRIMARY KEY (snapshot_id, old_id, new_id)\n  );\n\n  CREATE TABLE IF NOT EXISTS file_fingerprint (\n    snapshot_id     INTEGER NOT NULL,\n    file_id         TEXT NOT NULL,\n    content_hash    TEXT NOT NULL,\n    structural_hash TEXT,\n    PRIMARY KEY (snapshot_id, file_id)\n  );\n";
+/**
+ * Stored audit findings and model verdicts. `key` is a `findingKey`, not `Finding.id`,
+ * because an external tool's id embeds its line number and can repeat within one audit.
+ * The whole `Finding` and a verdict's citations live in `attrs`.
+ */
+declare const FINDING_DDL = "\n  CREATE TABLE IF NOT EXISTS finding (\n    snapshot_id  INTEGER NOT NULL,\n    key          TEXT NOT NULL,\n    finding_id   TEXT NOT NULL,\n    tool         TEXT NOT NULL,\n    signal       TEXT NOT NULL,\n    path         TEXT NOT NULL,\n    line_start   INTEGER,\n    line_end     INTEGER,\n    severity     TEXT NOT NULL,\n    excerpt_hash TEXT,\n    attrs        TEXT NOT NULL,\n    PRIMARY KEY (snapshot_id, key)\n  );\n  CREATE INDEX IF NOT EXISTS idx_finding_path ON finding(snapshot_id, path);\n\n  CREATE TABLE IF NOT EXISTS verdict (\n    snapshot_id  INTEGER NOT NULL,\n    key          TEXT NOT NULL,\n    verdict      TEXT NOT NULL CHECK (verdict IN ('confirmed', 'justified', 'unclear')),\n    rationale    TEXT NOT NULL,\n    excerpt_hash TEXT NOT NULL,\n    model        TEXT,\n    run_id       TEXT,\n    cost_usd     REAL,\n    provenance   TEXT,\n    control_run  TEXT,\n    carried_from INTEGER,\n    attrs        TEXT NOT NULL,\n    PRIMARY KEY (snapshot_id, key)\n  );\n";
 /** Every table keyed by `snapshot_id`. No DDL above declares a foreign key, so dropping a snapshot walks this list. */
-declare const SNAPSHOT_SCOPED_TABLES: readonly ["node", "edge", "metric", "id_alias", "file_fingerprint"];
+declare const SNAPSHOT_SCOPED_TABLES: readonly ["node", "edge", "metric", "id_alias", "file_fingerprint", "finding", "verdict"];
 declare const MIGRATIONS: Migration[];
 /** The top of this package's schema. A code graph database is never shared, so this is the top of one. */
 declare const SCHEMA_VERSION: number;
@@ -1299,6 +1305,67 @@ interface ExternalDiagnostic {
 declare function toFindings(result: CheckResult): Finding[];
 declare function externalToFinding(input: ExternalDiagnostic): Finding;
 
+type VerdictLabel = "confirmed" | "justified" | "unclear";
+interface VerdictCitation {
+    path: string;
+    lineStart: number;
+    lineEnd: number;
+    quote: string;
+}
+/** A finding as stored against a snapshot, addressed by its `findingKey`. */
+interface StoredFinding {
+    key: string;
+    finding: Finding;
+    /** Hash of the excerpt a reader would be shown for this finding; carry-forward compares it. */
+    excerptHash?: string;
+}
+/** A model's judgement of one stored finding, after its citations were verified. */
+interface StoredVerdict {
+    key: string;
+    verdict: VerdictLabel;
+    rationale: string;
+    citations: VerdictCitation[];
+    /** Hash of the excerpt the verdict judged. */
+    excerptHash: string;
+    model?: string;
+    costUsd?: number;
+    runId?: string;
+    provenance?: string;
+    controlRun?: "ok" | "provisional";
+    dropped?: string[];
+    /** The snapshot this verdict was carried from, when carry-forward copied it. */
+    carriedFrom?: number;
+}
+interface FindingKeyInput {
+    finding: Finding;
+    /** The innermost symbol node id containing the finding; the finding's path when absent. */
+    anchor?: string;
+    /** The source text of the flagged lines. */
+    flaggedText: string;
+    excerptHash?: string;
+}
+/** Whitespace-insensitive, so reindenting or reflowing the flagged lines keeps the key. */
+declare function normalizeFlaggedText(text: string): string;
+declare function hashText(text: string): string;
+/**
+ * A finding's identity across snapshots: no line number, so an inserted line above it
+ * keeps the key, and a collision ordinal separates same-rule findings on the same text.
+ */
+declare function findingKey(input: FindingKeyInput, ordinal?: number): string;
+/** Key a whole audit's findings, numbering collisions in source order so the result ignores input order. */
+declare function keyFindings(inputs: readonly FindingKeyInput[]): StoredFinding[];
+/** Insert or replace findings by key within one snapshot. */
+declare function saveFindings(store: CodeGraphStore, snapshotId: number, findings: readonly StoredFinding[]): void;
+declare function listFindings(store: CodeGraphStore, snapshotId: number): StoredFinding[];
+/** Insert or replace verdicts by key within one snapshot. */
+declare function saveVerdicts(store: CodeGraphStore, snapshotId: number, verdicts: readonly StoredVerdict[]): void;
+declare function listVerdicts(store: CodeGraphStore, snapshotId: number): StoredVerdict[];
+/**
+ * Copy each verdict of `from` onto the finding in `to` with the same key whose excerpt hash
+ * equals the one the verdict judged. A verdict `to` already holds is kept. Returns the count copied.
+ */
+declare function carryForwardVerdicts(store: CodeGraphStore, from: number, to: number): number;
+
 /** Glob when the pattern has a `*` (`**` crosses directories, `*` stays in a segment); otherwise a case-sensitive substring. */
 declare function patternToRegex(pattern: string): RegExp;
 declare function compilePatterns(patterns: readonly string[] | undefined): RegExp[];
@@ -1619,4 +1686,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, type FileFingerprint, type FindConventionsOptions, type FindSimilarOptions, type Finding, 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 SummarizeConventionsResult, type Summarizer, type SymbolConsumers, type SymbolCouplingOptions, type SymbolCouplingPair, type SymbolSpan, type TestCoverageOwnershipOptions, type TestSourceLink, type TopMetricRow, TsMorphGraphExtractor, type TsMorphGraphExtractorOptions, type UnchangedViolation, type ValidateRulesOptions, aggregateMetrics, aliasChain, annotateRoles, attributeCoverage, buildAliases, buildConventionAreas, buildEmbedText, buildFileModuleNodes, buildIndexerMetrics, buildLineage, canonicalEdgeKind, canonicalMetricName, canonicalRole, 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, getConventionMap, getEdgeWeight, groupTestsBySource, hashContent, hashEmbedText, indexPaths, invertBuckets, isGeneratedByHeuristic, isGeneratedFile, isInsideGitRepo, lineagePath, linkTestsToSources, listEdges, listEdgesTouching, listEmbeddableSymbols, listMetrics, listMetricsForNode, listNodes, loadCheckRules, loadGeneratedPatterns, loadHistoryMetrics, loadLineage, matchesAny, moduleId, openCodeGraph, packageId, parentModuleId, parseSymbolId, patternToRegex, percentileOf, planPrune, priorSnapshotForRef, pruneDanglingReferences, readSourceFiles, rebasedViolationKey, resolveAlias, resolveBarrelEdges, resolveChurnWindows, resolveGitRef, resolveSnapshot, runChecks, runPrune, 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 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 };

package/dist/index.js

@@ -62,11 +62,53 @@ var DOMAIN_DDL = `
     PRIMARY KEY (snapshot_id, file_id)
   );
 `;
-var SNAPSHOT_SCOPED_TABLES = ["node", "edge", "metric", "id_alias", "file_fingerprint"];
+var FINDING_DDL = `
+  CREATE TABLE IF NOT EXISTS finding (
+    snapshot_id  INTEGER NOT NULL,
+    key          TEXT NOT NULL,
+    finding_id   TEXT NOT NULL,
+    tool         TEXT NOT NULL,
+    signal       TEXT NOT NULL,
+    path         TEXT NOT NULL,
+    line_start   INTEGER,
+    line_end     INTEGER,
+    severity     TEXT NOT NULL,
+    excerpt_hash TEXT,
+    attrs        TEXT NOT NULL,
+    PRIMARY KEY (snapshot_id, key)
+  );
+  CREATE INDEX IF NOT EXISTS idx_finding_path ON finding(snapshot_id, path);
+
+  CREATE TABLE IF NOT EXISTS verdict (
+    snapshot_id  INTEGER NOT NULL,
+    key          TEXT NOT NULL,
+    verdict      TEXT NOT NULL CHECK (verdict IN ('confirmed', 'justified', 'unclear')),
+    rationale    TEXT NOT NULL,
+    excerpt_hash TEXT NOT NULL,
+    model        TEXT,
+    run_id       TEXT,
+    cost_usd     REAL,
+    provenance   TEXT,
+    control_run  TEXT,
+    carried_from INTEGER,
+    attrs        TEXT NOT NULL,
+    PRIMARY KEY (snapshot_id, key)
+  );
+`;
+var SNAPSHOT_SCOPED_TABLES = [
+  "node",
+  "edge",
+  "metric",
+  "id_alias",
+  "file_fingerprint",
+  "finding",
+  "verdict"
+];
 var MIGRATIONS = [
   kitMigration(1, { snapshot: KIT.snapshot, entitySnap: KIT.entitySnap, cacheBlob: KIT.cacheBlob }),
   { version: 2, name: "code graph columns", up: (db) => db.exec(KIT_EXTENSIONS) },
-  { version: 3, name: "code graph tables", up: (db) => db.exec(DOMAIN_DDL) }
+  { version: 3, name: "code graph tables", up: (db) => db.exec(DOMAIN_DDL) },
+  { version: 4, name: "findings and verdicts", up: (db) => db.exec(FINDING_DDL) }
 ];
 var SCHEMA_VERSION = Math.max(...MIGRATIONS.map((m) => m.version));
 
@@ -5605,6 +5647,127 @@ function withoutUndefined(finding) {
   return Object.fromEntries(Object.entries(finding).filter(([, v]) => v !== void 0));
 }
 
+// src/check/finding-store.ts
+import { createHash as createHash2 } from "crypto";
+function normalizeFlaggedText(text) {
+  return text.split(/\r?\n/).map((line) => line.trim().replace(/\s+/g, " ")).filter((line) => line.length > 0).join("\n");
+}
+function hashText(text) {
+  return createHash2("sha256").update(text, "utf8").digest("hex").slice(0, 16);
+}
+function findingKey(input, ordinal = 0) {
+  const { finding } = input;
+  const anchor = input.anchor ?? finding.path;
+  const textHash = hashText(normalizeFlaggedText(input.flaggedText));
+  return `${finding.tool}:${finding.signal}:${anchor}:${textHash}#${ordinal}`;
+}
+function keyFindings(inputs) {
+  const ordered = [...inputs].sort(compareBySource);
+  const seen = /* @__PURE__ */ new Map();
+  return ordered.map((input) => {
+    const base = findingKey(input);
+    const ordinal = seen.get(base) ?? 0;
+    seen.set(base, ordinal + 1);
+    const stored = { key: findingKey(input, ordinal), finding: input.finding };
+    if (input.excerptHash !== void 0) stored.excerptHash = input.excerptHash;
+    return stored;
+  });
+}
+function compareBySource(a, b) {
+  const fa = a.finding;
+  const fb = b.finding;
+  return fa.path.localeCompare(fb.path) || (fa.lineStart ?? 0) - (fb.lineStart ?? 0) || (fa.lineEnd ?? 0) - (fb.lineEnd ?? 0) || (fa.evidence ?? "").localeCompare(fb.evidence ?? "") || fa.id.localeCompare(fb.id);
+}
+function saveFindings(store, snapshotId, findings) {
+  const insert = store.db.prepare(
+    `INSERT OR REPLACE INTO finding
+       (snapshot_id, key, finding_id, tool, signal, path, line_start, line_end, severity, excerpt_hash, attrs)
+     VALUES (@snapshotId, @key, @findingId, @tool, @signal, @path, @lineStart, @lineEnd, @severity, @excerptHash, @attrs)`
+  );
+  store.db.transaction(() => {
+    for (const { key, finding, excerptHash } of findings) {
+      insert.run({
+        snapshotId,
+        key,
+        findingId: finding.id,
+        tool: finding.tool,
+        signal: finding.signal,
+        path: finding.path,
+        lineStart: finding.lineStart ?? null,
+        lineEnd: finding.lineEnd ?? null,
+        severity: finding.severity,
+        excerptHash: excerptHash ?? null,
+        attrs: JSON.stringify(finding)
+      });
+    }
+  })();
+}
+function listFindings(store, snapshotId) {
+  const rows = store.db.prepare("SELECT key, excerpt_hash, attrs FROM finding WHERE snapshot_id = ? ORDER BY key").all(snapshotId);
+  return rows.map((row) => {
+    const stored = { key: row.key, finding: JSON.parse(row.attrs) };
+    if (row.excerpt_hash !== null) stored.excerptHash = row.excerpt_hash;
+    return stored;
+  });
+}
+function saveVerdicts(store, snapshotId, verdicts) {
+  const insert = store.db.prepare(
+    `INSERT OR REPLACE INTO verdict
+       (snapshot_id, key, verdict, rationale, excerpt_hash, model, run_id, cost_usd, provenance, control_run,
+        carried_from, attrs)
+     VALUES (@snapshotId, @key, @verdict, @rationale, @excerptHash, @model, @runId, @costUsd, @provenance,
+        @controlRun, @carriedFrom, @attrs)`
+  );
+  store.db.transaction(() => {
+    for (const v of verdicts) insert.run(verdictParams(snapshotId, v));
+  })();
+}
+function verdictParams(snapshotId, v) {
+  return {
+    snapshotId,
+    key: v.key,
+    verdict: v.verdict,
+    rationale: v.rationale,
+    excerptHash: v.excerptHash,
+    model: v.model ?? null,
+    runId: v.runId ?? null,
+    costUsd: v.costUsd ?? null,
+    provenance: v.provenance ?? null,
+    controlRun: v.controlRun ?? null,
+    carriedFrom: v.carriedFrom ?? null,
+    attrs: JSON.stringify({ citations: v.citations, dropped: v.dropped ?? [] })
+  };
+}
+function listVerdicts(store, snapshotId) {
+  const rows = store.db.prepare("SELECT * FROM verdict WHERE snapshot_id = ? ORDER BY key").all(snapshotId);
+  return rows.map(rowToVerdict);
+}
+function rowToVerdict(row) {
+  const attrs = JSON.parse(row.attrs);
+  const verdict = {
+    key: row.key,
+    verdict: row.verdict,
+    rationale: row.rationale,
+    citations: attrs.citations,
+    excerptHash: row.excerpt_hash
+  };
+  if (row.model !== null) verdict.model = row.model;
+  if (row.cost_usd !== null) verdict.costUsd = row.cost_usd;
+  if (row.run_id !== null) verdict.runId = row.run_id;
+  if (row.provenance !== null) verdict.provenance = row.provenance;
+  if (row.control_run !== null) verdict.controlRun = row.control_run;
+  if (attrs.dropped.length > 0) verdict.dropped = attrs.dropped;
+  if (row.carried_from !== null) verdict.carriedFrom = row.carried_from;
+  return verdict;
+}
+function carryForwardVerdicts(store, from, to) {
+  const targets = new Map(listFindings(store, to).map((f) => [f.key, f.excerptHash]));
+  const existing = new Set(listVerdicts(store, to).map((v) => v.key));
+  const carried = listVerdicts(store, from).filter((v) => !existing.has(v.key) && targets.get(v.key) === v.excerptHash).map((v) => ({ ...v, carriedFrom: v.carriedFrom ?? from }));
+  saveVerdicts(store, to, carried);
+  return carried.length;
+}
+
 // src/check/validate.ts
 function validateRules(input, options = {}) {
   if (!input || typeof input !== "object") {
@@ -6489,6 +6652,7 @@ export {
   DEFAULT_OUTLIER_MIN_SAMPLE,
   DOMAIN_DDL,
   EXCEPTION_METRIC_NAMES,
+  FINDING_DDL,
   GROWTH_RISK_METRIC_NAMES,
   INDEX_VERSION,
   KIT,
@@ -6516,6 +6680,7 @@ export {
   canonicalEdgeKind,
   canonicalMetricName,
   canonicalRole,
+  carryForwardVerdicts,
   checkSnapshot,
   classifyRole,
   collectDeclaredNames,
@@ -6552,6 +6717,7 @@ export {
   fileId,
   findConventions,
   findSimilarCapability,
+  findingKey,
   getConventionMap,
   getEdgeWeight,
   getLanguageFromPath3 as getLanguageFromPath,
@@ -6559,25 +6725,30 @@ export {
   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,
@@ -6597,6 +6768,8 @@ export {
   resolveSnapshot,
   runChecks,
   runPrune,
+  saveFindings,
+  saveVerdicts,
   shouldIncludeFile2 as shouldIncludeFile,
   snapshotPageRank,
   snapshotReferenceEdges,