opencode-swarm 7.158.1 → 7.159.1

package/dist/observability/catalog.d.ts

@@ -1,7 +1,7 @@
 /**
  * The event catalog (issue #2029).
  *
- * Exactly 51 entries, matching the `TelemetryEvent` union at
+ * Exactly 54 entries, matching the `TelemetryEvent` union at
  * `src/telemetry.ts:15-131`. Thirty-eight predate the #2029 contract; the 39th is
  * `agent_conflict_detected` (previously emitted through a force-cast past the
  * type system), the 40th is `close_archive_result` (issue #2030 — the
@@ -22,7 +22,9 @@
  * the bounded `trajectory_health` storage audit for the issue-#2041
  * `.swarm/trajectories/` PRM session store, and the 51st is the bounded
  * `pr_subscription_health` storage audit for the issue-#2042
- * `.swarm/pr-monitor/` PR-monitor subscription checkpoint store. These late
+ * `.swarm/pr-monitor/` subscription checkpoint store. The 52nd is
+ * `delegation_cost_correction`, the 53rd is `delegation_cost_binding`, and the
+ * 54th is `delegation_cost_join`. These late
  * additions are instances
  * of the defect class this contract exists to close: an event kind entering
  * the stream with no registration.
@@ -78,7 +80,7 @@ export interface CatalogEntry {
     /**
      * Whether an event of this kind must carry `trace.parentSpanId`.
      *
-     * `false` for all 51 entries today, and that is a truthful statement about
+     * `false` for all 54 entries today, and that is a truthful statement about
      * the current system rather than a placeholder: no producer supplies a
      * parent span, so `createObservation` never sets one. Setting this to `true`
      * for a kind whose producer cannot supply a parent would make every

package/dist/review/contracts.d.ts

@@ -1,5 +1,6 @@
 import type { OpencodeClient } from '@opencode-ai/sdk';
 import { type EphemeralAgentDispatchResult } from '../evaluation/ephemeral-agent-dispatcher.js';
+import type { PricingConfig } from '../services/cost-accounting.js';
 import type { ModelOverride } from '../utils/model-dispatch-fallback.js';
 export type ReviewDispatchRequest = {
     directory: string;
@@ -26,4 +27,4 @@ export interface ReviewModelDispatcher {
  * The returned dispatcher is instance-local and safe to inject into hooks and
  * tools; it does not read or mutate module-level client state.
  */
-export declare function createReviewModelDispatcher(client: OpencodeClient): ReviewModelDispatcher;
+export declare function createReviewModelDispatcher(client: OpencodeClient, pricing?: PricingConfig): ReviewModelDispatcher;

package/dist/review/evidence.d.ts

@@ -1,7 +1,10 @@
+import * as fs from 'node:fs';
 import { type FindingValidation, type ReviewFinding } from '../agents/agent-output-schema.js';
 import type { Plan } from '../config/plan-schema.js';
 import type { AutoReviewConfig } from '../config/schema.js';
 import { type ReviewFindingSeverity, type ReviewReceipt } from '../hooks/review-receipt.js';
+import type { CostEvidence, CostEvidenceReason, CostEvidenceStatus } from '../services/cost-accounting.js';
+import { bunWrite } from '../utils/bun-compat.js';
 import type { ReviewDiffCompleteness, ReviewDiffManifest, ReviewDiffSelector } from './diff-source.js';
 export interface AutoReviewEvidenceFinding extends ReviewFinding {
     finding_id: string;
@@ -64,6 +67,10 @@ export interface AutoReviewEvidence {
         tokens_cache: number;
         cost_usd: number | null;
         cost_source: 'reported' | 'estimated' | 'unavailable';
+        /** Bounded per-dispatch provenance; scalar totals remain compatibility projections. */
+        cost_evidence: CostEvidence[];
+        evidence_status: CostEvidenceStatus;
+        evidence_reason?: CostEvidenceReason;
     };
 }
 export declare function computeAutoReviewManifestHash(manifest: Omit<AutoReviewScopeManifest, 'hash'>): string;
@@ -72,6 +79,11 @@ export interface PersistAutoReviewEvidenceOptions {
     /** Rebuild the exact reviewed scope immediately before the atomic rename. */
     verifyCurrent?: () => Promise<boolean>;
 }
+/** Dependency seam for failure-path tests; production defaults stay unchanged. */
+export declare const _internals: {
+    bunWrite: typeof bunWrite;
+    renameSync: typeof fs.renameSync;
+};
 export declare function persistAutoReviewEvidence(directory: string, evidence: AutoReviewEvidence, options?: PersistAutoReviewEvidenceOptions): Promise<string>;
 export declare function readAutoReviewEvidenceForPhase(directory: string, phase: number): AutoReviewEvidence | null;
 export declare function isAutoReviewEvidence(value: unknown): value is AutoReviewEvidence;

package/dist/services/cost-accounting.d.ts

@@ -1,4 +1,33 @@
 export type CostSource = 'reported' | 'estimated' | 'unavailable';
+export type CostEvidenceKind = 'provider_reported' | 'normalized_estimate';
+export type CostEvidenceStatus = 'complete' | 'inconclusive';
+export type CostCurrency = 'USD' | 'unknown' | (string & {});
+export type CostEvidenceReason = 'authoritative' | 'missing_cost' | 'invalid_number' | 'pricing_missing' | 'unsupported_currency' | 'conflict' | 'unbilled' | 'join_miss' | 'legacy' | 'unreadable' | 'partial';
+/** Fixed, non-provider-controlled paths accepted by the evidence adapter. */
+export type CostEvidenceSourcePath = 'assistant.cost' | 'step-finish.cost' | 'response.info.cost' | 'response.cost' | 'legacy.cost' | 'pricing.model';
+export type CostEvidence = {
+    kind: CostEvidenceKind;
+    amount_usd: number | null;
+    currency: CostCurrency;
+    source_path: CostEvidenceSourcePath;
+    reason: CostEvidenceReason;
+    usage: TokenUsage;
+    model?: string;
+    pricing_version?: string;
+    pricing_effective_at?: string;
+    billing_basis?: string;
+    /** A bounded canonical digest is useful to correction producers. */
+    digest?: string;
+};
+export type CostCandidate = {
+    kind: CostEvidenceKind;
+    amount: number | null;
+    currency: CostCurrency;
+    source_path: CostEvidenceSourcePath;
+    usage: TokenUsage;
+    model?: string;
+    reason?: CostEvidenceReason;
+};
 export type ModelPricing = {
     input_per_million: number;
     output_per_million: number;
@@ -7,6 +36,14 @@ export type ModelPricing = {
 };
 export type PricingConfig = {
     models?: Record<string, ModelPricing>;
+    /** Currency of normalized table rows. Defaults to USD for compatibility. */
+    currency?: string;
+    version?: string;
+    effective_at?: string;
+    billing_basis?: string;
+    /** Explicit provider declarations; reported currency is never inferred. */
+    reported_cost_currency?: Record<string, string>;
+    subscription_unbilled?: boolean;
 };
 export type TokenUsage = {
     tokens_input: number;
@@ -17,6 +54,15 @@ export type TokenUsage = {
 export type DelegationCostFields = TokenUsage & {
     cost_usd: number | null;
     cost_source: CostSource;
+    cost_evidence?: CostEvidence[];
+    evidence_status?: CostEvidenceStatus;
+    evidence_reason?: CostEvidenceReason;
+    record_id?: string;
+    identity_fingerprint?: string;
+    child_session_digest?: string;
+    parent_session_digest?: string;
+    version?: number;
+    currency?: CostCurrency;
     model?: string;
     gate?: string;
     retry_index?: number;
@@ -27,6 +73,7 @@ export type DelegationCostInput = {
     gate?: string;
     retry_index?: number;
     pricing?: PricingConfig;
+    reported_cost_currency?: string;
 };
 export type CostSummary = {
     total_cost_usd: number;
@@ -46,6 +93,16 @@ export type CostSummary = {
         delegations: number;
         cost_usd: number;
     }>;
+    total_legacy_usd: number;
+    conflict_count: number;
+    legacy_count: number;
+    join_miss_count: number;
+    telemetry_error_count: number;
+    accepted_corrections: number;
+    rejected_corrections: number;
+    duplicate_corrections: number;
+    evidence_status: CostEvidenceStatus;
+    currencies: string[];
 };
 export type CostSummaryRow = {
     name: string;
@@ -59,7 +116,50 @@ export type CostSummaryRow = {
 };
 export declare const BUNDLED_MODEL_PRICING: Record<string, ModelPricing>;
 export declare function buildDelegationCostFields(input?: DelegationCostInput): DelegationCostFields;
+/**
+ * Extract only the pinned SDK shapes. The old generic traversal was
+ * intentionally removed: a wrapper's default cost must not shadow a child
+ * AssistantMessage/StepFinishPart report.
+ */
+export declare function extractCostEvidence(raw: unknown, input?: Pick<DelegationCostInput, 'model' | 'pricing' | 'reported_cost_currency'>): CostEvidence[];
+export type CostProjection = {
+    cost_usd: number | null;
+    cost_source: CostSource;
+    evidence_status: CostEvidenceStatus;
+    reason: CostEvidenceReason;
+    currency: CostCurrency;
+};
+/** Project additive evidence to the legacy scalar fields. Unknown is never zero. */
+export declare function projectCostEvidence(evidence: readonly CostEvidence[]): CostProjection;
+export declare function isCostEvidenceComplete(evidence: readonly CostEvidence[] | undefined): boolean;
 export declare function summarizeTelemetryCosts(directory: string): CostSummary;
+export type CostFoldStats = {
+    conflict_count: number;
+    join_miss_count: number;
+    telemetry_error_count: number;
+    accepted_corrections: number;
+    rejected_corrections: number;
+    duplicate_corrections: number;
+};
+export type FoldedCostTelemetry = {
+    events: Record<string, unknown>[];
+    stats: CostFoldStats;
+    versions: Record<string, number>;
+};
+/**
+ * Fold append-only cost corrections into one effective delegation snapshot.
+ * Corrections are buffered and replayed in version order so telemetry arrival
+ * order cannot permanently discard a valid correction. Invalid/orphan
+ * corrections remain diagnostics and can never create a row.
+ */
+export declare function foldTelemetryEvents(events: readonly Record<string, unknown>[]): FoldedCostTelemetry;
+export declare function isCostUpgrade(current: readonly CostEvidence[], next: readonly CostEvidence[]): boolean;
 export declare function readTelemetryEvents(directory: string): Record<string, unknown>[];
+/**
+ * Bounded asynchronous telemetry reader for live recovery paths. The status
+ * service and offline summaries retain the atomic synchronous snapshot above;
+ * recovery must not block event delivery on a full-file synchronous read.
+ */
+export declare function readTelemetryEventsAsync(directory: string): Promise<Record<string, unknown>[]>;
 export declare function estimateCostUsd(usage: TokenUsage, model?: string, pricing?: PricingConfig): number | null;
 export declare function roundUsd(value: number): number;

package/dist/services/status-service.d.ts

@@ -4,6 +4,7 @@ import { loadFullAutoRunState } from '../full-auto/state';
 import { type RecentEscalation } from '../hooks/knowledge-escalator';
 import { getActiveFullAutoSessionID, hasActiveFullAuto, hasActiveLeanTurbo } from '../state';
 import { loadLeanTurboRunState } from '../turbo/lean/state';
+import { summarizeTelemetryCosts } from './cost-accounting.js';
 /**
  * Dependency-injection seam for status-service.
  * Allows tests to intercept Lean Turbo state queries without mock.module leakage.
@@ -14,6 +15,7 @@ export declare const _internals: {
     hasActiveFullAuto: typeof hasActiveFullAuto;
     getActiveFullAutoSessionID: typeof getActiveFullAutoSessionID;
     loadFullAutoRunState: typeof loadFullAutoRunState;
+    summarizeTelemetryCosts: typeof summarizeTelemetryCosts;
 };
 /**
  * Structured status data returned by the status service.
@@ -175,6 +177,16 @@ export interface StatusData {
      * stores surface as typed uncertainty, never partially-trusted counts.
      */
     backgroundWork?: BackgroundWorkStatus;
+    /** Issue #2043: compatibility total plus provenance completeness. */
+    costs?: {
+        totalCostUsd: number;
+        delegations: number;
+        unavailableDelegations: number;
+        evidenceStatus: 'complete' | 'inconclusive';
+        conflictCount: number;
+        joinMissCount: number;
+        telemetryErrorCount: number;
+    };
 }
 /** Issue #2104: opt-in background-work status snapshot for /swarm status. */
 export interface BackgroundWorkStatus {

package/dist/telemetry.d.ts

@@ -1,6 +1,6 @@
 import { createObservation, toLegacyTelemetryLine } from './observability/index.js';
 import type { DelegationCostFields } from './services/cost-accounting.js';
-export type TelemetryEvent = 'session_started' | 'session_ended' | 'agent_activated' | 'delegation_begin' | 'delegation_end' | 'task_state_changed' | 'gate_passed' | 'gate_failed' | 'gate_parse_error' | 'reviewer_gate_decision' | 'phase_changed' | 'budget_updated' | 'context_pruned' | 'model_fallback'
+export type TelemetryEvent = 'session_started' | 'session_ended' | 'agent_activated' | 'delegation_begin' | 'delegation_end' | 'delegation_cost_correction' | 'delegation_cost_binding' | 'delegation_cost_join' | 'task_state_changed' | 'gate_passed' | 'gate_failed' | 'gate_parse_error' | 'reviewer_gate_decision' | 'phase_changed' | 'budget_updated' | 'context_pruned' | 'model_fallback'
 /**
  * Issue #2271 bug 4 — a configured agent model id was POSITIVELY confirmed
  * unresolvable against the live provider catalog (distinct from a runtime

package/dist/tools/repo-graph/query.d.ts

@@ -52,6 +52,7 @@ export declare function getLocalizationContext(graph: RepoGraph, filePath: strin
     maxDeps?: number;
     maxDepth?: number;
 }): LocalizationBlock;
+export declare function extractSignatureText(lines: string[], startLine: number): string;
 export declare function getContextPack(graph: RepoGraph, file: string, symbol: string, options?: {
     maxDepth?: number;
     maxTokens?: number;

package/dist/tools/repo-graph/symbol-query.d.ts

@@ -0,0 +1,47 @@
+/**
+ * KG-14 expanded graph query functions (issue #1535).
+ *
+ * Symbol-level, impact, diff, and explainability queries over the persisted
+ * repo graph. Every function is stateless and read-only: inputs are validated
+ * by the `repo_map` tool layer (`src/tools/repo-map.ts`); this module assumes
+ * well-formed arguments and focuses on bounded, workspace-relative,
+ * provenance-bearing output.
+ *
+ * Bounding contract: every list-shaped output is capped (default caps below
+ * or the caller's `topN`), every result carries a `budget {returned, dropped}`
+ * envelope, and paths in results are workspace-relative with forward slashes.
+ */
+import type { DiffContextResult, GraphExplainResult, GraphSymbolKind, GraphSymbolVisibility, ImpactConeResult, RepoGraph, SymbolContextResult, SymbolSearchResult } from './types';
+export declare function searchSymbols(graph: RepoGraph, options: {
+    query: string;
+    kind?: GraphSymbolKind;
+    language?: string;
+    file?: string;
+    visibility?: GraphSymbolVisibility;
+    topN?: number;
+}): SymbolSearchResult;
+export declare function getSymbolContext(graph: RepoGraph, options: {
+    file?: string;
+    symbol?: string;
+    symbolId?: string;
+    includeSource?: boolean;
+    topN?: number;
+}): SymbolContextResult;
+export declare function getImpactCone(graph: RepoGraph, options: {
+    file: string;
+    symbol?: string;
+    maxDepth?: number;
+    topN?: number;
+}): ImpactConeResult;
+export declare function getDiffContext(graph: RepoGraph, options: {
+    files?: string[];
+    diff?: string;
+    maxDepth?: number;
+    topN?: number;
+}): DiffContextResult;
+export declare function explainGraphEntry(graph: RepoGraph, options: {
+    file: string;
+    symbol?: string;
+    line?: number;
+    topN?: number;
+}): GraphExplainResult;

package/dist/tools/repo-graph/types.d.ts

@@ -47,8 +47,15 @@ export declare const REPO_GRAPH_FILENAME = "repo-graph.json";
  * 1.5.0 adds an optional graph-level `repoRootId` plus additive SymbolEdge v2
  * identity, kind, confidence, resolution, and evidence fields. Legacy 1.2.0
  * four-coordinate symbol edges remain readable and are normalized in memory.
+ *
+ * 1.6.0 adds the optional per-node `exportKinds` map (declaration kind per
+ * symbol, keyed exactly like `exportRanges`), powering the KG-14 declaration-
+ * kind query axis (`symbol_search` kind filter, `symbol_context` identity).
+ * The field is optional, so 1.0.0–1.5.0 graphs still load; queries surface
+ * `kind: null` hits and a `kindSupported: false` degradation note instead of
+ * failing (issue #1535).
  */
-export declare const GRAPH_SCHEMA_VERSION = "1.5.0";
+export declare const GRAPH_SCHEMA_VERSION = "1.6.0";
 /**
  * Default per-file source-size ceiling shared by graph construction and
  * query-time source reads. The builder treats this as the default value of
@@ -160,6 +167,17 @@ export interface GraphNode {
         startLine: number;
         endLine: number;
     }>;
+    /**
+     * Declaration kind per symbol, keyed by symbol name (schema >= 1.6.0;
+     * optional, so older graphs load unchanged). Keys are assigned in the same
+     * builder loop and under the same widening + duplicate-name policies as
+     * `exportRanges`, but ONLY at real declaration sites — re-export bindings
+     * add an `exportRanges` entry without a kind (the symbol is declared
+     * elsewhere), so `exportKinds` is a subset of `exportRanges` keys.
+     * Absent entries read as `kind: null` (old graph, regex-fallback scan, or
+     * re-exported binding).
+     */
+    exportKinds?: Record<string, GraphSymbolKind>;
     /** Imported module specifiers */
     imports: string[];
     /** Language/extension of the file */
@@ -246,6 +264,26 @@ export type SymbolEdgeKind = (typeof SYMBOL_EDGE_KIND_VALUES)[number];
 export declare const SYMBOL_EDGE_RESOLUTION_VALUES: readonly ["exact", "import_binding", "same_file_scope", "unique_name", "type_resolved", "lsp", "scip", "heuristic", "unresolved"];
 export type SymbolEdgeResolution = (typeof SYMBOL_EDGE_RESOLUTION_VALUES)[number];
 export type SymbolIdentityKind = 'symbol' | 'module';
+/**
+ * Declaration kind of a symbol — WHAT the symbol is (function, class, …).
+ * Mirrors `FileSymbolFacts['defs'][number]['kind']` from
+ * `src/lang/symbol-graph.ts` and is persisted per node via
+ * `GraphNode.exportKinds` (schema >= 1.6.0).
+ *
+ * This is the DECLARATION axis and is deliberately distinct from
+ * {@link SymbolEdgeKind}, the RELATIONSHIP axis (CALLS/REFERENCES/…) that
+ * describes how two symbols connect. A symbol never referenced cross-file has
+ * no symbol edge but still has a declaration kind.
+ */
+export declare const GRAPH_SYMBOL_KIND_VALUES: readonly ["function", "class", "const", "type", "interface", "enum", "method"];
+export type GraphSymbolKind = (typeof GRAPH_SYMBOL_KIND_VALUES)[number];
+/**
+ * Visibility tier derived at query time from persisted fields: a symbol in
+ * `GraphNode.exports` is `exported` (public module surface); a symbol that
+ * only exists in `exportRanges` (widened-grammar member defs) is
+ * `module-local`.
+ */
+export type GraphSymbolVisibility = 'exported' | 'module-local';
 export interface SymbolEdgeEvidence {
     /** Workspace-relative source path; source text itself is never persisted. */
     file: string;
@@ -443,6 +481,202 @@ export interface DeadExportsResult {
     /** Human-readable note describing scope and limitations of the result. */
     note: string;
 }
+/** One symbol hit from `symbol_search`, with declaration metadata. */
+export interface SymbolHit {
+    /** Workspace-relative file path. */
+    file: string;
+    symbol: string;
+    /** Declaration kind; `null` on graphs predating schema 1.6.0 (no exportKinds). */
+    kind: GraphSymbolKind | null;
+    visibility: GraphSymbolVisibility;
+    language: string;
+    /** 1-based definition line; 0 when no line is known. */
+    line: number;
+    exported: boolean;
+    /** Which match tier produced this hit (results are tier-ordered). */
+    match: 'exact' | 'prefix' | 'substring' | 'subsequence';
+}
+export interface SymbolSearchResult {
+    query: string;
+    hits: SymbolHit[];
+    count: number;
+    budget: {
+        returned: number;
+        dropped: number;
+    };
+    /** False when the graph predates schema 1.6.0, so `kind` filters/hits degrade. */
+    kindSupported: boolean;
+    /** Present (non-empty) only when a filter or scan could not be fully applied. */
+    warnings: string[];
+}
+/**
+ * One symbol-level edge inside an impact cone. `relationshipKind`,
+ * `confidence`, and `resolution` come from the underlying `SymbolEdge` and
+ * are `null` for legacy (pre-1.5.0) edges.
+ */
+export interface ConeEntry {
+    /** Workspace-relative file path. */
+    file: string;
+    symbol: string;
+    direction: 'caller' | 'callee';
+    /** 1 = direct neighbor of the target. */
+    depth: number;
+    relationshipKind: SymbolEdgeKind | null;
+    confidence: number | null;
+    resolution: SymbolEdgeResolution | null;
+}
+/** Focused definition-first context for one symbol. */
+export interface SymbolContextResult {
+    found: boolean;
+    identity: {
+        file: string;
+        symbol: string;
+        symbolId: string | null;
+        kind: GraphSymbolKind | null;
+        visibility: GraphSymbolVisibility;
+        language: string;
+        startLine: number;
+        endLine: number | null;
+    } | null;
+    signature?: string;
+    source?: {
+        text: string;
+        mode: 'full' | 'signature' | 'summary';
+        hash: string;
+        startLine: number;
+        endLine: number;
+    };
+    callers: ConeEntry[];
+    callees: ConeEntry[];
+    /** Present only when resolution scanned stable IDs to match `symbolId`. */
+    symbolIdScan?: {
+        computed: number;
+        capped: boolean;
+    };
+    budget: {
+        callersReturned: number;
+        calleesReturned: number;
+        dropped: number;
+    };
+    warnings: string[];
+    note?: string;
+}
+/** Structured impact cone for a file or file+symbol target. */
+export interface ImpactConeResult {
+    target: {
+        file: string;
+        symbol: string | null;
+    };
+    /** Symbol-level entries (empty when no symbol was given or the graph has no symbolEdges). */
+    entries: ConeEntry[];
+    /** File-level blast radius for the same target and depth — risk semantics identical to `blast_radius`. */
+    fileImpact: BlastRadiusResult;
+    risk: BlastRadiusResult['riskLevel'];
+    /** Fixed-vocabulary notes with counts (transitive spread, hubs, low-confidence edges, tests, boundaries). */
+    riskNotes: string[];
+    /** Cone files carrying the `test_file` role. */
+    tests: string[];
+    routes: Array<{
+        file: string;
+        fact: RouteFact;
+    }>;
+    dataFacts: Array<{
+        file: string;
+        fact: DataOperationFact;
+    }>;
+    securityFacts: Array<{
+        file: string;
+        fact: SecurityFact;
+    }>;
+    boundaries: Array<{
+        name: string;
+        files: string[];
+    }>;
+    budget: {
+        entriesReturned: number;
+        dropped: number;
+    };
+    truncated: boolean;
+    warnings: string[];
+}
+/** One changed symbol mapped from a diff hunk (or listed file-level). */
+export interface DiffSymbolChange {
+    symbol: string;
+    kind: GraphSymbolKind | null;
+    startLine: number;
+    endLine: number;
+    /** Hunk-mode: changed graph lines that intersect the symbol span (bounded). */
+    changedLines: number[];
+}
+export interface DiffFileSummary {
+    /** Workspace-relative file path. */
+    file: string;
+    /** False when the changed file is not present in the graph (e.g. deleted or unscanned). */
+    known: boolean;
+    symbols: DiffSymbolChange[];
+    note?: string;
+}
+export interface DiffContextResult {
+    /** `hunk` when a diff text was parsed with line ranges; `file` when only file names were given. */
+    granularity: 'hunk' | 'file';
+    files: DiffFileSummary[];
+    impact: {
+        files: string[];
+        tests: string[];
+        risk: BlastRadiusResult['riskLevel'];
+        notes: string[];
+    };
+    budget: {
+        returned: number;
+        dropped: number;
+    };
+    truncated: boolean;
+    warnings: string[];
+}
+/**
+ * One reason a file/symbol/span is graph-relevant: its definition, the
+ * symbol edges that connect it, or file-level import relationships.
+ */
+export interface ExplainReason {
+    type: 'definition' | 'referenced_by' | 'references' | 'imported_by' | 'imports';
+    /** Workspace-relative file path of the OTHER side of the relationship (or the definition file). */
+    file: string;
+    symbol?: string;
+    kind: GraphSymbolKind | null;
+    relationshipKind?: SymbolEdgeKind;
+    /** Undefined for definition/import reasons; `null`-able inside evidence-bearing edges is avoided by omitting. */
+    confidence?: number;
+    resolution?: SymbolEdgeResolution;
+    evidence?: SymbolEdgeEvidence[];
+}
+export interface GraphExplainResult {
+    target: {
+        file: string;
+        symbol: string | null;
+        line: number | null;
+    };
+    fileKnown: boolean;
+    /** When `line` was given: the symbol whose span contains it (smallest span wins). */
+    resolvedSpan?: {
+        symbol: string;
+        startLine: number;
+        endLine: number;
+    };
+    definition?: {
+        file: string;
+        symbol: string;
+        kind: GraphSymbolKind | null;
+        visibility: GraphSymbolVisibility;
+        startLine: number;
+        endLine: number | null;
+    };
+    reasons: ExplainReason[];
+    budget: {
+        returned: number;
+        dropped: number;
+    };
+    warnings: string[];
+}
 export interface GraphExtractionFailure {
     file: string;
     language: string;
@@ -509,6 +743,38 @@ export interface GraphHealthResult {
     walkTruncationReason: 'budget' | 'cap' | null;
     incrementalFallbacks: number;
     notes: string[];
+    /**
+     * KG-14 additive summaries (issue #1535). Optional on the interface so
+     * external constructors stay source-compatible; `getGraphHealth` always
+     * populates them (zero-valued when the underlying data is absent).
+     */
+    /** Symbol-edge population summary (legacy edges counted under `withV2Fields: false`). */
+    symbolEdgeSummary?: {
+        total: number;
+        withV2Fields: number;
+        lowConfidence: number;
+        unresolved: number;
+    };
+    /** Resolution-attribution histogram over symbol edges (includes `unrecorded`). */
+    resolutionBreakdown?: Record<string, number>;
+    /**
+     * Stale composition from the freshness probe; `null` when no probe was
+     * supplied. `probeTruncated` is `FreshnessProbe.truncated` — the freshness
+     * WALK hitting its budget — and is deliberately a different signal from
+     * build-time `walkTruncated` above (the graph BUILD walk).
+     */
+    staleSummary?: {
+        changed: number;
+        removed: number;
+        probeTruncated: boolean;
+    } | null;
+    /** Extraction-failure histogram keyed by failure reason. */
+    extractionFailureSummary?: Record<string, number>;
+    /** How many nodes carry schema 1.6.0 `exportKinds` data. */
+    kindCoverage?: {
+        nodesWithKinds: number;
+        nodesTotal: number;
+    };
 }
 /** Authoritative states returned by the bounded repository freshness probe. */
 export type FreshnessProbeState = 'clean' | 'drifted' | 'no-fingerprint' | 'inconclusive';

package/dist/tools/repo-graph.d.ts

@@ -11,6 +11,7 @@
  *   storage.ts     — safe load and save to .swarm/repo-graph.json
  *   builder.ts     — workspace scanning and full-graph construction
  *   incremental.ts — incremental updates for changed files
+ *   symbol-query.ts — KG-14 symbol/impact/diff/explain queries (issue #1535)
  *
  * All existing imports of this module continue to work unchanged.
  */
@@ -26,6 +27,7 @@ export { extractFileOntology } from './repo-graph/ontology';
 export type { DeadExportsOptions } from './repo-graph/query';
 export { buildOntologyPreflightPacket, getBlastRadius, getCallers, getContextPack, getDeadExports, getDependencies, getFileOntology, getGraphHealth, getGraphNode, getImporters, getKeyFiles, getLocalizationContext, getPackageBoundaries, getSymbolConsumers, isGraphFresh, resetQueryCache, } from './repo-graph/query';
 export { getGraphPath, loadGraph, loadGraphSync, loadOrCreateGraph, saveGraph, saveIfDirty, } from './repo-graph/storage';
-export type { AskHit, AskOptions, AskResult, BlastRadiusResult, BuildWorkspaceGraphOptions, CallerReference, ContextPackCoverage, ContextPackResult, ContextPackSnippet, ContextPackSourceMode, ContextPackSpan, ConventionFact, DataOperationFact, DeadExportCandidate, DeadExportsResult, FileOntology, FileReference, FileRole, FreshnessProbeState, GraphEdge, GraphExtractionFailure, GraphExtractorInputWitness, GraphHealthResult, GraphNode, GraphUnresolvedImport, LocalizationBlock, OntologyFinding, PackageBoundarySummary, RepoGraph, RepoGraphDiagnostics, RouteFact, RouteMethod, SecurityFact, SymbolEdge, SymbolEdgeEvidence, SymbolEdgeKind, SymbolEdgeResolution, SymbolIdentityKind, SymbolReference, } from './repo-graph/types';
+export { explainGraphEntry, getDiffContext, getImpactCone, getSymbolContext, searchSymbols, } from './repo-graph/symbol-query';
+export type { AskHit, AskOptions, AskResult, BlastRadiusResult, BuildWorkspaceGraphOptions, CallerReference, ConeEntry, ContextPackCoverage, ContextPackResult, ContextPackSnippet, ContextPackSourceMode, ContextPackSpan, ConventionFact, DataOperationFact, DeadExportCandidate, DeadExportsResult, DiffContextResult, DiffFileSummary, DiffSymbolChange, ExplainReason, FileOntology, FileReference, FileRole, FreshnessProbeState, GraphEdge, GraphExplainResult, GraphExtractionFailure, GraphExtractorInputWitness, GraphHealthResult, GraphNode, GraphSymbolKind, GraphSymbolVisibility, GraphUnresolvedImport, ImpactConeResult, LocalizationBlock, OntologyFinding, PackageBoundarySummary, RepoGraph, RepoGraphDiagnostics, RouteFact, RouteMethod, SecurityFact, SymbolContextResult, SymbolEdge, SymbolEdgeEvidence, SymbolEdgeKind, SymbolEdgeResolution, SymbolHit, SymbolIdentityKind, SymbolReference, SymbolSearchResult, } from './repo-graph/types';
 export { createEmptyGraph, DEFAULT_MAX_SOURCE_BYTES, GRAPH_SCHEMA_VERSION, inferPackageBoundary, isSchemaVersionAtLeast, normalizeGraphPath, REPO_GRAPH_FILENAME, updateGraphMetadata, } from './repo-graph/types';
 export { validateGraphEdge, validateGraphNode, validateWorkspace, } from './repo-graph/validation';