@remnic/core 9.3.729 → 9.3.731

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { PluginEntryResolverOptions, resolvePluginEntry } from './plugin-entry-resolver.js';
 export { isOpenaiApiKeyDisabled, parseConfig, resolveEnvVars } from './config.js';
 export { MigrationOptions, MigrationResult, RollbackResult, migrateFromEngram, rollbackFromEngramMigration } from './migrate/from-engram.js';
-import { S as SpeakerRegistry, W as WearablesService } from './orchestrator-BR0sGsME.js';
-export { D as DEFAULT_SELF_NAME, O as Orchestrator, R as ResolvedSpeaker, a as SpeakerOverride, b as WEARABLE_SOURCE_PREFIX, c as WearableDayTranscriptView, d as WearableMemoryGenDeps, e as WearableMemoryGenResult, f as WearableMemorySearchResult, g as WearableMemoryWriter, h as WearableSearchBackend, i as WearableStorageIo, j as WearableSyncDeps, k as WearableSyncOptions, l as WearableTranscriptSearchResult, m as WearablesServiceDeps, n as buildExtractionTurns, o as dateInTimezone, p as defaultTimezone, q as defaultWorkspaceDir, r as distinctSpeakerLabels, s as emptySpeakerRegistry, t as generateWearableMemories, u as importNativeMemories, v as loadSpeakerRegistry, w as locateTranscriptPath, x as memoryStatusForMode, y as resolveSpeaker, z as resolveSyncDates, A as sanitizeSessionKeyForFilename, B as saveSpeakerRegistry, C as speakerRegistryKey, E as speakersFilePath, F as syncWearableSource, H as wearableDayTag, J as wearableSourceLabel, K as writeDailyDigestMemory } from './orchestrator-BR0sGsME.js';
+import { S as SpeakerRegistry, W as WearablesService } from './orchestrator-B4KjaOtY.js';
+export { D as DEFAULT_SELF_NAME, O as Orchestrator, R as ResolvedSpeaker, a as SpeakerOverride, b as WEARABLE_SOURCE_PREFIX, c as WearableDayTranscriptView, d as WearableMemoryGenDeps, e as WearableMemoryGenResult, f as WearableMemorySearchResult, g as WearableMemoryWriter, h as WearableSearchBackend, i as WearableStorageIo, j as WearableSyncDeps, k as WearableSyncOptions, l as WearableTranscriptSearchResult, m as WearablesServiceDeps, n as buildExtractionTurns, o as dateInTimezone, p as defaultTimezone, q as defaultWorkspaceDir, r as distinctSpeakerLabels, s as emptySpeakerRegistry, t as generateWearableMemories, u as importNativeMemories, v as loadSpeakerRegistry, w as locateTranscriptPath, x as memoryStatusForMode, y as resolveSpeaker, z as resolveSyncDates, A as sanitizeSessionKeyForFilename, B as saveSpeakerRegistry, C as speakerRegistryKey, E as speakersFilePath, F as syncWearableSource, H as wearableDayTag, J as wearableSourceLabel, K as writeDailyDigestMemory } from './orchestrator-B4KjaOtY.js';
 export { normalizeProjectionPreview, normalizeProjectionTags } from './memory-projection-format.js';
 export { ModelCapabilities, ModelRegistry } from './model-registry.js';
 export { ACTIVE_STATUSES, ContradictionFilter, ContradictionJudgeBatchResult, ContradictionJudgeInput, ContradictionJudgeResult, ContradictionListResult, ContradictionVerdict, ResolutionResult, ResolutionVerb, ScanDependencies, ScanResult, computePairId, executeResolution, isCoolingDown, isValidResolutionVerb, judgeContradictionPairs, listPairs, readPair, resolvePair, runContradictionScan, writePair, writePairs } from './contradiction/index.js';
@@ -13,18 +13,18 @@ export { FocusedListRecallOptions, buildFocusedListRecallSection, shouldRecallFo
 export { ResponseGuidanceRecallOptions, buildResponseGuidanceRecallSection, shouldRecallResponseGuidance } from './response-guidance-recall.js';
 export { EventOrderRecallOptions, buildEventOrderRecallSection, shouldRecallEventOrderEvidence } from './event-order-recall.js';
 import { StorageManager } from './storage.js';
-export { parseEntityFile, serializeEntityFile } from './storage.js';
+export { MemoryWriteResult, parseEntityFile, serializeEntityFile } from './storage.js';
 export { HostEmbeddingInputType, HostEmbeddingProvider, getHostEmbeddingProvider, normalizeHostEmbeddingVector, registerHostEmbeddingProvider } from './host-embedding-provider.js';
 export { ExtractionEngine } from './extraction.js';
 export { CodexCliFallbackConfig, CodexCliFallbackMessage, CodexCliFallbackOptions, CodexCliFallbackRequest, CodexCliFallbackResult, CodexCliFallbackRunner, setCodexCliFallbackRunnerForProcess } from './cli-fallback.js';
 export { BufferSurpriseProbe, SmartBuffer, TriggerDecision } from './buffer.js';
 export { ComputeSurpriseOptions, DEFAULT_SURPRISE_K, RecentMemoryLike, computeSurprise } from './buffer-surprise.js';
 export { BufferSurpriseDistribution, BufferSurpriseReader, BufferSurpriseReportOptions, reportBufferSurpriseDistribution } from './buffer-surprise-report.js';
-import { aH as CodingContext, aS as CodingModeConfig, P as PluginConfig, M as MemoryCategory, aT as WearableCleanupSettings, ay as WearableSourceSettings, aC as WearablesConfig, aB as WearableSourceConnector, ax as WearableConversation, aG as WearableCorrectionRule, aU as WearableDayTranscriptMeta, aF as WearableDayTranscript } from './types-ChQb9D6s.js';
-export { J as AgentAccessAuthToken, r as BriefingActiveThread, aV as BriefingConfig, p as BriefingFocus, o as BriefingFollowup, aW as BriefingOpenCommitment, t as BriefingRecentEntity, s as BriefingResult, n as BriefingSections, aX as BriefingWindow, z as BufferSurpriseEvent, q as CalendarEvent, C as CalendarSource, aY as CodexCompatConfig, aK as ConsolidationObservation, a6 as ContinuityImprovementLoop, aZ as DEFAULT_RECALL_DISCLOSURE, E as EntityFile, $ as EntityStructuredSection, a_ as ExtractedFact, G as GatewayConfig, ac as MemoryActionEligibilityContext, a$ as MemoryActionEligibilitySource, U as MemoryActionType, g as MemoryFile, k as MemoryFrontmatter, b0 as MemoryObservation, b1 as MemoryScope, b2 as RECALL_DISCLOSURE_LEVELS, i as RecallDisclosure, D as SecretRef, b3 as WearableAuthCheck, b4 as WearableFetchOptions, b5 as WearableFetchPage, aA as WearableMemoryMode, az as WearableNativeMemory, b6 as WearableNativeMemoryPage, aE as WearableSourceStatus, aD as WearableSyncSummary, b7 as WearableTranscriptSegment, b8 as isRecallDisclosure } from './types-ChQb9D6s.js';
+import { aH as CodingContext, aS as CodingModeConfig, P as PluginConfig, aT as CodingKnowledgeConfig, M as MemoryCategory, aU as WearableCleanupSettings, ay as WearableSourceSettings, aC as WearablesConfig, aB as WearableSourceConnector, ax as WearableConversation, aG as WearableCorrectionRule, aV as WearableDayTranscriptMeta, aF as WearableDayTranscript } from './types-VkxElCHR.js';
+export { J as AgentAccessAuthToken, r as BriefingActiveThread, aW as BriefingConfig, p as BriefingFocus, o as BriefingFollowup, aX as BriefingOpenCommitment, t as BriefingRecentEntity, s as BriefingResult, n as BriefingSections, aY as BriefingWindow, z as BufferSurpriseEvent, q as CalendarEvent, C as CalendarSource, aZ as CodexCompatConfig, aK as ConsolidationObservation, a6 as ContinuityImprovementLoop, a_ as DEFAULT_RECALL_DISCLOSURE, E as EntityFile, $ as EntityStructuredSection, a$ as ExtractedFact, G as GatewayConfig, ac as MemoryActionEligibilityContext, b0 as MemoryActionEligibilitySource, U as MemoryActionType, g as MemoryFile, k as MemoryFrontmatter, b1 as MemoryObservation, b2 as MemoryScope, b3 as RECALL_DISCLOSURE_LEVELS, i as RecallDisclosure, D as SecretRef, b4 as WearableAuthCheck, b5 as WearableFetchOptions, b6 as WearableFetchPage, aA as WearableMemoryMode, az as WearableNativeMemory, b7 as WearableNativeMemoryPage, aE as WearableSourceStatus, aD as WearableSyncSummary, b8 as WearableTranscriptSegment, b9 as isRecallDisclosure } from './types-VkxElCHR.js';
 export { JudgeBatchResult, JudgeCandidate, JudgeVerdict, JudgeVerdictKind, clearVerdictCache, createVerdictCache, getVerdictKind, isDurableVerdict, isValidCachedVerdict, judgeFactDurability, normalizeCachedVerdict, verdictCacheSize } from './extraction-judge.js';
 export { hasBroadGraphIntent, inferIntentFromText, intentCompatibilityScore, isTaskInitiationIntent, planRecallMode } from './intent.js';
-export { i as EngramAccessInputError, g as EngramAccessService, P as ProcedureStatsConfigSnapshot, j as ProcedureStatsRecent, k as ProcedureStatsReport, l as ProcedureStatusCounts, m as computeProcedureStats, n as formatProcedureStatsText } from './access-service-BXMJqkTA.js';
+export { i as EngramAccessInputError, g as EngramAccessService, P as ProcedureStatsConfigSnapshot, j as ProcedureStatsRecent, k as ProcedureStatsReport, l as ProcedureStatusCounts, m as computeProcedureStats, n as formatProcedureStatsText } from './access-service-Byoe3HsT.js';
 export { FILTER_LABELS as DIRECT_ANSWER_FILTER_LABELS, DirectAnswerCandidate, DirectAnswerConfig, DirectAnswerInput, DirectAnswerReason, DirectAnswerResult, isDirectAnswerEligible } from './direct-answer.js';
 export { MemoryTier, TierRoutingPolicy, TierTransitionDecision, computeTierValueScore, decideTierTransition } from './tier-routing.js';
 export { ApplyReasoningTraceBoostOptions, BoostableResult, DEFAULT_REASONING_TRACE_BOOST, applyReasoningTraceBoost, isReasoningTracePath, looksLikeProblemSolvingQuery } from './reasoning-trace-recall.js';
@@ -38,7 +38,7 @@ export { OramaBackend } from './search/orama-backend.js';
 export { MeilisearchBackend } from './search/meilisearch-backend.js';
 export { buildEntityRecallSection } from './entity-retrieval.js';
 export { resolvePrincipal } from './namespaces/principal.js';
-export { N as NamespaceCatalog, c as NamespaceCatalogFilter, d as NamespaceCatalogRebuildResult, e as NamespaceCatalogSkippedRoot, f as NamespaceDiscoverySource, a as NamespaceKind, b as NamespaceRecord, g as NamespaceTouchMetadata } from './catalog-bMczlO2G.js';
+export { N as NamespaceCatalog, c as NamespaceCatalogFilter, d as NamespaceCatalogRebuildResult, e as NamespaceCatalogSkippedRoot, f as NamespaceDiscoverySource, a as NamespaceKind, b as NamespaceRecord, g as NamespaceTouchMetadata } from './catalog-DM1nk7cM.js';
 export { SESSION_CHANNEL_TYPE, SessionIdentity, SessionStoragePaths, legacyParserReadbackDir, parseSessionIdentity, sessionStoragePaths } from './session-identity.js';
 export { storagePathHash } from './storage-paths.js';
 export { TrustZoneName, TrustZoneRecord, TrustZoneRecordKind, TrustZoneSourceClass, isTrustZoneName } from './trust-zones.js';
@@ -62,8 +62,8 @@ export { CitationBlock, CitationEntry, CitationMetadata, buildCitationGuidance,
 export { initLogger, log } from './logger.js';
 export { b as SemanticDedupDecision, S as SemanticDedupHit, a as SemanticDedupLookup, c as SemanticDedupOptions, d as decideSemanticDedup } from './semantic-SLAa_prH.js';
 export { OFFLINE_SYNC_APPLY_MAX_BODY_BYTES, OFFLINE_SYNC_CHANGESET_FORMAT, OFFLINE_SYNC_FILE_CONTENT_MAX_CHUNK_BYTES, OFFLINE_SYNC_FILE_CONTENT_TRANSFER_CHUNK_BYTES, OFFLINE_SYNC_SNAPSHOT_BASE_MAX_BODY_BYTES, OFFLINE_SYNC_SNAPSHOT_FORMAT, OFFLINE_SYNC_STATE_VERSION, OfflineSyncApplyChangesetResult, OfflineSyncApplyFileContentChunkResult, OfflineSyncApplySnapshotResult, OfflineSyncChange, OfflineSyncChangeset, OfflineSyncConflict, OfflineSyncFileContentChunk, OfflineSyncFileDigest, OfflineSyncFileRecord, OfflineSyncFileState, OfflineSyncFileTarget, OfflineSyncFileWriteTarget, OfflineSyncSnapshot, OfflineSyncState, applyOfflineSyncChangeset, applyOfflineSyncFileContentChunk, applyOfflineSyncSnapshot, buildOfflineSyncChangeset, buildOfflineSyncChangesetFromSnapshot, buildOfflineSyncSnapshot, buildOfflineSyncSnapshotForPaths, buildOfflineSyncSnapshotFromBase, defaultOfflineSyncStatePath, fileStatesFromSnapshot, iterateOfflineSyncSnapshotFileRecords, normalizeOfflineSyncChangeset, normalizeOfflineSyncSnapshot, offlineSyncStateFromSnapshot, readOfflineSyncFileContentChunk, readOfflineSyncState, shouldPreferIncomingOfflineRuntimeFile, summarizeOfflineSyncChangeset, summarizeOfflineSyncPendingChanges, summarizeOfflineSyncPendingFiles, writeOfflineSyncState } from './offline-sync.js';
-import { D as DiscoveredExtension } from './semantic-consolidation-Cl15ksZy.js';
-export { E as ExtensionSchema, R as REMNIC_EXTENSIONS_TOTAL_TOKEN_LIMIT, b as buildExtensionsBlockForConsolidation, d as discoverMemoryExtensions, r as resolveExtensionsRoot } from './semantic-consolidation-Cl15ksZy.js';
+import { D as DiscoveredExtension } from './semantic-consolidation-CstTvHPo.js';
+export { E as ExtensionSchema, R as REMNIC_EXTENSIONS_TOTAL_TOKEN_LIMIT, b as buildExtensionsBlockForConsolidation, d as discoverMemoryExtensions, r as resolveExtensionsRoot } from './semantic-consolidation-CstTvHPo.js';
 export { ConnectorCapability, ConnectorInstance, ConnectorManifest, ConnectorRegistry, DoctorCheck, DoctorResult, InstallOptions, InstallResult, MARKETPLACE_MANIFEST_FILENAME, MARKETPLACE_SCHEMA_VERSION, MarketplaceConfig, MarketplaceEntry, MarketplaceInstallResult, MarketplaceInstallType, MarketplaceLogger, MarketplaceManifest, MarketplaceValidation, RemoveResult, checkMarketplaceManifest, coerceInstallExtension, doctorConnector, generateMarketplaceManifest, getConnectorToken, installConnector, installFromMarketplace, listConnectors, loadRegistry, removeConnector, saveRegistry, validateMarketplaceManifest, writeMarketplaceManifest } from './connectors/index.js';
 import { L as LiveConnector, S as SyncIncrementalResult } from './framework-CNDn2164.js';
 export { c as CONNECTOR_ID_PATTERN, C as ConnectorConfig, b as ConnectorCursor, a as ConnectorDocument, d as ConnectorDocumentSource, e as SyncIncrementalArgs, i as isValidConnectorId, p as persistableConnectorConfig, r as redactConnectorConfigSecrets } from './framework-CNDn2164.js';
@@ -79,7 +79,7 @@ export { EnrichmentAuditEntry, EnrichmentCandidate, EnrichmentCostTier, Enrichme
 export { d as BulkImportError, B as BulkImportOptions, b as BulkImportResult, a as BulkImportSource, e as BulkImportSourceAdapter, f as ImportSourceRole, I as ImportTurn, g as ImportTurnValidationIssue, i as isImportRole, p as parseIsoTimestamp, v as validateImportTurn } from './types-gb_SNtjR.js';
 export { clearBulkImportSources, getBulkImportSource, listBulkImportSources, registerBulkImportSource } from './bulk-import/index.js';
 export { a as ProcessBatchContext, P as ProcessBatchFn, b as ProcessBatchResult, f as formatBatchTranscript, r as resolveBulkImportContext, c as runBulkImportPipeline, v as validateBatchSize } from './pipeline-DmqtvION.js';
-export { B as BulkImportCliCommandOptions, p as parseStrictCliDate, r as runBulkImportCliCommand } from './cli-DmAiDd8A.js';
+export { B as BulkImportCliCommandOptions, p as parseStrictCliDate, r as runBulkImportCliCommand } from './cli-Dt-tuiYH.js';
 export { DEFAULT_IMPORT_BATCH_SIZE, ImportProgress, ImportedMemory, ImporterAdapter, ImporterParseOptions, ImporterTransformOptions, ImporterWriteResult, ImporterWriteTarget, RunImportOptions, RunImporterResult, defaultWriteMemoriesToOrchestrator, importedMemoryToTurn, runImporter, validateImportBatchSize, validateImportRateLimit } from './importers/index.js';
 export { FallbackLlmClient, FallbackLlmOptions, FallbackLlmResponse, FallbackLlmRuntimeContext } from './fallback-llm.js';
 export { ComputeMemoryWorthInput, MemoryWorthResult, computeMemoryWorth } from './memory-worth.js';
@@ -117,6 +117,7 @@ import 'better-sqlite3';
 import './structured-attributes.js';
 import './utility-runtime.js';
 import './lifecycle.js';
+import './orchestration/compression-guideline-coordinator.js';
 import './relevance.js';
 import './negative.js';
 import './session-observer-state.js';
@@ -420,6 +421,200 @@ interface ResolveGitContextOptions {
  */
 declare function resolveGitContext(cwd: string, options?: ResolveGitContextOptions): Promise<GitContext | null>;
 
+/**
+ * Structural-context provider port (issue #1548 Track A PR 5).
+ *
+ * The architectural boundary between Track A (durable coding-memory
+ * features) and Track B (the native @remnic/coding-graph engine). A
+ * structural-context provider expands a unified diff into the SYMBOLS it
+ * touches (and optionally yields architecture hints), so review-intent
+ * recall can boost memories that mention those symbols — not just the
+ * bare file paths that `review-context.ts` already boosts on.
+ *
+ * Three providers satisfy this port, selected by
+ * `codingKnowledge.structuralProvider`:
+ *
+ *   - `"none"`      — no provider consulted (default; review-context stays
+ *                     file-path-only, byte-identical to pre-feature — rule 39).
+ *   - `"subprocess"` — an external binary shelled out via `execFile` with an
+ *                     argv ARRAY (never a shell string — rule 10). The
+ *                     built-in adapter lives in `structural-subprocess-provider.ts`;
+ *                     codebase-memory-mcp's CLI mode is the canonical target,
+ *                     but the provider is command-agnostic.
+ *   - `"native"`    — the in-family @remnic/coding-graph engine, adapted to
+ *                     this port by a future PR (#1551/#1554). Only the enum
+ *                     value and this doc note land in this PR — no engine
+ *                     code. codebase-memory-mcp remains a supported
+ *                     subprocess provider through this same port regardless.
+ *
+ * Every result is a tagged outcome shaped like #1536's `SearchDegradation`
+ * (CLAUDE.md rule 34 — a degraded/absent provider must NEVER masquerade as
+ * "no structural matches"):
+ *   - `{ ok: true,  symbols }` on success
+ *   - `{ ok: false, code }`    on every failure (distinct codes per mode)
+ *
+ * No module-level mutable state (rule 11): the registry is keyed per
+ * orchestrator/service instance via a `Symbol.for(...)` slot on
+ * `globalThis`, mirroring `host-embedding-provider.ts`.
+ */
+
+/**
+ * Distinct failure codes for the structural-context port. Every code is
+ * load-bearing: callers (review-context, `remnic doctor`, xray) switch on
+ * `code` to distinguish "binary not installed" from "timed out" from
+ * "protocol violation" so a silent provider failure can never look like an
+ * empty-but-healthy result.
+ */
+type StructuralContextErrorCode = 
+/** Probe failed: binary missing / not executable, or native package absent. */
+"provider_unavailable"
+/** The provider exceeded its deadline. */
+ | "provider_timeout"
+/** Output was present but not a valid JSON object/array (rule 18). */
+ | "provider_malformed"
+/** Provider ran but returned an explicit error or threw. */
+ | "provider_error";
+/**
+ * A single symbol touched by a diff. The `symbol` name is the load-bearing
+ * field — it is what review-context adds to its match set. `path`/`kind`
+ * are informational and surface in xray when present.
+ */
+interface StructuralSymbol {
+    /** Qualified or bare symbol name, e.g. `"AuthService.login"` or `"login"`. */
+    readonly symbol: string;
+    /** Source file the symbol lives in (forward-slashed, repo-relative when possible). */
+    readonly path?: string;
+    /** Coarse kind if the provider knows it (`function`/`method`/`class`/...). */
+    readonly kind?: string;
+}
+interface SymbolsForDiffOk {
+    readonly ok: true;
+    readonly symbols: StructuralSymbol[];
+    /** Provider-reported latency in ms, when available. */
+    readonly latencyMs?: number;
+}
+interface SymbolsForDiffErr {
+    readonly ok: false;
+    readonly code: StructuralContextErrorCode;
+    readonly detail?: string;
+}
+type SymbolsForDiffResult = SymbolsForDiffOk | SymbolsForDiffErr;
+interface ArchitectureHintsOk {
+    readonly ok: true;
+    readonly hints: string[];
+}
+interface ArchitectureHintsErr {
+    readonly ok: false;
+    readonly code: StructuralContextErrorCode;
+    readonly detail?: string;
+}
+type ArchitectureHintsResult = ArchitectureHintsOk | ArchitectureHintsErr;
+/**
+ * The port contract. Both the built-in subprocess adapter
+ * (`structural-subprocess-provider.ts`) and the future native engine
+ * adapter (#1551) implement this. Registry callers retrieve an instance by
+ * scope; never construct one inline at a call site.
+ */
+interface StructuralContextProvider {
+    /** Stable identifier for registry logging / `remnic doctor`. */
+    readonly id: string;
+    /**
+     * Probe availability. Resolves to a tagged result so a missing binary
+     * (subprocess) or absent package (native) is surfaced, never thrown
+     * (rule 34). Implementations SHOULD cache the outcome per instance
+     * (rule 11).
+     */
+    probe(): Promise<{
+        available: boolean;
+        detail?: string;
+    }>;
+    /**
+     * Expand a unified diff to the symbols it touches. NEVER throws — every
+     * failure path returns a tagged `{ ok: false, code }`. The optional
+     * `signal` lets the caller cancel an in-flight subprocess (rule 40).
+     */
+    symbolsForDiff(diff: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<SymbolsForDiffResult>;
+    /**
+     * Optional architecture hints for a repo root. Used by the architecture
+     * card composition (#1548 Track A PR 3 + #1554). Implementations MAY omit
+     * this; callers MUST handle its absence.
+     */
+    architectureHints?(root: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ArchitectureHintsResult>;
+    /** Release any resources the provider holds (subprocess handles, etc.). */
+    close?(): Promise<void> | void;
+}
+/**
+ * Backend tag is a literal so consumers can switch on it programmatically
+ * alongside `SearchDegradation` (`backend: "qmd"`). `detail` is optional
+ * and never load-bearing — `code` is the signal.
+ */
+interface StructuralContextDegradation {
+    readonly backend: "structural-context";
+    readonly code: StructuralContextErrorCode;
+    readonly detail?: string;
+}
+/**
+ * Coerce a {@link SymbolsForDiffErr} into the degradation record consumers
+ * attach to recall snapshots / xray. Centralised so the `{ backend: ... }`
+ * tag is set in one place (rule 22 spirit).
+ */
+declare function toStructuralContextDegradation(err: SymbolsForDiffErr): StructuralContextDegradation;
+/**
+ * Register a provider for a scope (typically an orchestrator `serviceId`).
+ * Overwriting a previous registration closes the old provider. Returns an
+ * unregister function — callers SHOULD invoke it on service teardown so a
+ * hot-reloaded host does not leak subprocess handles.
+ */
+declare function registerStructuralContextProvider(scope: string, provider: StructuralContextProvider): () => void;
+/** Look up the provider registered for a scope, if any. */
+declare function getStructuralContextProvider(scope: string): StructuralContextProvider | undefined;
+/** Test-only: clear every registered provider. */
+declare function clearStructuralContextProvidersForTest(): void;
+/**
+ * The single gate every review-context consumer consults before consulting a
+ * provider. Returns `true` iff the master `codingKnowledge.enabled` switch is
+ * on AND `structuralProvider` is not `"none"`. When this returns `false`,
+ * review-context runs its pure file-path-only ranker — byte-identical to
+ * pre-feature behaviour on every path.
+ */
+declare function structuralProviderActive(config: PluginConfig): boolean;
+/**
+ * Config-only structural provider status. `remnic doctor` and xray render
+ * this; an async sibling in `structural-subprocess-provider.ts` augments it
+ * with a live `probed` field.
+ */
+interface StructuralProviderStatus {
+    readonly active: boolean;
+    readonly mode: CodingKnowledgeConfig["structuralProvider"];
+    /** Command path when mode is `"subprocess"` and a command is configured. */
+    readonly command?: string;
+    /** Provider id when one is registered for the scope. */
+    readonly providerId?: string;
+    /** Live probe outcome — set only by the async doctor probe. */
+    probed?: {
+        available: boolean;
+        detail?: string;
+    };
+}
+/**
+ * Summarise the structural provider status from config ALONE (no probe, no
+ * I/O). Pure — safe to call from any context, including the recall hot path
+ * for xray labels.
+ */
+declare function describeStructuralProviderStatus(config: PluginConfig, scope?: string): StructuralProviderStatus;
+/**
+ * Render a single human-readable line for `remnic doctor`. Pure.
+ *
+ *   `structural-context provider: none (inactive — review-context stays file-path-only)`
+ *   `structural-context provider: subprocess, command=/usr/local/bin/cbm, probed=available`
+ *   `structural-context provider: subprocess, command=/usr/local/bin/cbm, probed=unavailable (binary not found)`
+ */
+declare function renderStructuralProviderStatusLine(status: StructuralProviderStatus): string;
+
 /**
  * Diff-aware review-context packer (issue #569 PR 4).
  *
@@ -441,6 +636,7 @@ declare function resolveGitContext(cwd: string, options?: ResolveGitContextOptio
  * code in `orchestrator.ts` (the tier itself can be wired later; the pure
  * surface is what PRs 5/6/7 will call).
  */
+
 /**
  * A memory candidate as fed into review-context ranking. The shape is a
  * deliberate subset of the core `MemorySummary` / recall result — only the
@@ -479,6 +675,15 @@ interface ReviewContext {
     rankedRecall: Array<ReviewCandidate & {
         boost: number;
     }>;
+    /**
+     * Structural-context provider degradation observed while expanding the
+     * diff to touched symbols (issue #1548 Track A PR 5, #1536 pattern).
+     * Present only when a provider was consulted AND it failed — a silent
+     * provider failure must never look like "no structural matches"
+     * (CLAUDE.md rule 34). Undefined when no provider was consulted (the
+     * pure {@link packReviewContext} path) or when the provider succeeded.
+     */
+    structuralDegradation?: StructuralContextDegradation;
 }
 /**
  * `true` when the prompt looks like a review / diff-explanation request.
@@ -524,6 +729,86 @@ interface PackReviewContextInput {
  * the recall result.
  */
 declare function packReviewContext(input: PackReviewContextInput): ReviewContext;
+/**
+ * Input for the structural-context-aware review-context packer. The pure
+ * {@link packReviewContext} stays unchanged (gate-off parity); this async
+ * variant consults a {@link StructuralContextProvider} to expand the diff's
+ * touched FILE paths into touched SYMBOL names, widening the match set so
+ * memories that mention a changed symbol — not just the file path — float
+ * up. The gate (`structuralProvider !== "none"`) is checked ONCE by the
+ * caller, never inside this function (rule 39).
+ */
+interface PackReviewContextStructuralInput extends PackReviewContextInput {
+    /** A probed structural-context provider. Never undefined here. */
+    provider: StructuralContextProvider;
+    /** Cancellation forwarded to the provider subprocess (rule 40). */
+    signal?: AbortSignal;
+}
+/**
+ * Structural-context-aware packer.
+ *
+ * Contract (issue #1548 Track A PR 5, prove-fail-before characterization):
+ *   - Provider returns symbols (`ok: true`) → symbol names are ADDED to the
+ *     match set alongside touched files; memories mentioning a symbol get the
+ *     same bounded additive boost as a file-path match.
+ *   - Provider fails (`ok: false`, any code) → ranking falls back to
+ *     FILE-PATH-ONLY boosting, BYTE-IDENTICAL to {@link packReviewContext}
+ *     (the match set is exactly the touched files), AND `structuralDegradation`
+ *     is populated so xray/doctor can surface the failure (rule 34).
+ *
+ * The underlying ranker ({@link rankReviewCandidates}) is reused unchanged,
+ * so the deterministic ordering, boost cap, and tie-break are identical to
+ * the pure path.
+ */
+declare function packReviewContextStructural(input: PackReviewContextStructuralInput): Promise<ReviewContext>;
+
+/** Injectable spawn shape so tests substitute a stub (rule 33). */
+type StructuralSpawnFn = (command: string, argv: readonly string[], options: {
+    timeout: number;
+    signal?: AbortSignal;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+interface SubprocessProviderOptions {
+    /** Absolute path to the binary (rule 24 — statSync at probe time). */
+    readonly command: string;
+    /**
+     * Extra argv appended after the symbols-for-diff subcommand
+     * (rule 10 — array, never a shell string).
+     */
+    readonly args?: readonly string[];
+    /** Per-call deadline in ms. Default 5000. */
+    readonly timeoutMs?: number;
+    /**
+     * Subcommand the provider invokes for symbol expansion.
+     * Default `"symbols-for-diff"`.
+     */
+    readonly symbolsSubcommand?: string;
+    /** Test seam — defaults to promisified `execFile`. */
+    readonly spawn?: StructuralSpawnFn;
+}
+/**
+ * Construct a structural-context provider backed by an external subprocess.
+ * The instance is self-contained: callers register it via
+ * `registerStructuralContextProvider(scope, provider)` and dispose via the
+ * returned unregister handle.
+ */
+declare function createSubprocessStructuralProvider(options: SubprocessProviderOptions): StructuralContextProvider;
+/**
+ * Augment the pure {@link describeStructuralProviderStatus} with a LIVE probe
+ * so `remnic doctor` can render "configured / probed / last error code".
+ *
+ *   - `"none"`     → inactive (no probe).
+ *   - `"subprocess"` → builds a throwaway provider from
+ *                    `structuralProviderCommand`, probes it, disposes it.
+ *   - `"native"`   → asks `isCodingGraphInstalled()` whether the optional
+ *                    @remnic/coding-graph peer is present (the adapter that
+ *                    turns the engine into a provider lands in #1551).
+ *
+ * Never throws — a probe failure populates `probed.available = false`.
+ */
+declare function probeStructuralProviderForDoctor(config: PluginConfig): Promise<StructuralProviderStatus>;
 
 /**
  * Binary file lifecycle management types.
@@ -2590,4 +2875,4 @@ declare function forkCapsule(opts: ForkCapsuleOptions): Promise<ForkCapsuleResul
  */
 declare function readForkLineage(targetRoot: string, forkId: string): Promise<ForkLineage | null>;
 
-export { type AuditEntry, type BinaryAssetRecord, type BinaryAssetStatus, type BinaryLifecycleConfig, type BinaryLifecycleManifest, type BinaryStorageBackend, type BinaryStorageBackendConfig, ClaudeCodeMemoryExtensionPublisher, type CleanupResult, CodexMemoryExtensionPublisher, type CodingNamespaceOverlay, type CodingScopeDescription, type CollectLocalSessionSummariesOptions, type CompiledCorrectionRule, type CompiledRedactionRule, type ConflictEntry, type ContradictionOptions, type ContradictionPair, type ContradictionResult$1 as CurateContradictionResult, type DuplicateResult as CurateDuplicateResult, type CurateOptions, type CurateResult, type CuratedStatement, DEFAULT_GRACE_PERIOD_DAYS, DEFAULT_MAX_BINARY_SIZE_BYTES, DEFAULT_REDACTION_RULES, DEFAULT_SCAN_PATTERNS, DEFAULT_TAXONOMY, type DedupOptions, type DedupResult, DiscoveredExtension, type DocFile, type DriveChange, type DriveChangesPage, type DriveFileMetadata, type DuplicatePair, type FileChange, FilesystemBackend, type ForkCapsuleOptions, type ForkCapsuleResult, type ForkLineage, GOOGLE_DRIVE_CONNECTOR_ID, GOOGLE_DRIVE_CURSOR_KIND, DEFAULT_POLL_INTERVAL_MS as GOOGLE_DRIVE_DEFAULT_POLL_INTERVAL_MS, type GenerateOptions, type GenerateResult, type GitContext, type GitInvoker, type GoogleDriveClient, type GoogleDriveClientFactory, type GoogleDriveConnectorConfig, type GoogleDriveSyncResult, HermesMemoryExtensionPublisher, type IngestionPlan, KNOWN_WEARABLE_SOURCE_IDS, type LanguageInfo, LiveConnector, LiveConnectorRegistry, LiveConnectorRegistryError, type LocalSessionAdapterInput, type LocalSessionAdapterOptions, type LocalSessionParseWarning, type LocalSessionParsedFile, type LocalSessionRole, type LocalSessionSourceAdapter, type LocalSessionSummaryCliOptions, type LocalSessionSummaryReport, type LocalSessionTurn, MemoryCategory, type MemoryEntry, type MemoryExtensionPublisher, type MergeResult, NOTION_CONNECTOR_ID, NOTION_CURSOR_KIND, NOTION_DEFAULT_POLL_INTERVAL_MS, NoneBackend, type NotionConnectorConfig, type OnboardOptions, type OnboardResult, PUBLISHERS, type PipelineResult, PluginConfig, type ProjectShape, type ProvenanceEntry, type PublishContext, type PublishResult, type PublisherCapabilities, REDACTION_PLACEHOLDER, REMNIC_CITATION_FORMAT, REMNIC_MCP_TOOL_INVENTORY, REMNIC_RECALL_DECISION_RULES, REMNIC_SEMANTIC_OVERVIEW, type RedactionConfig, type RedactionReport, type RedactionRuleConfig, ResolverDecision, type ReviewAction, type ReviewCandidate, type ReviewContext, type ReviewItem, type ReviewListResult, type ReviewOptions, type ReviewResult, type SessionSummaryDraft, type SessionSummaryExcerpt, type Space, type SpaceKind, type SpaceManifest, type SpacePromoteResult, type SpacePullResult, type SpacePushResult, type SpaceShareResult, type SpaceSwitchResult, SpeakerRegistry, type StatementProvenance, StorageManager, SyncIncrementalResult, type SyncOptions, type SyncResult, type SyncState, Taxonomy, TokenEntry, type TrainingExportAdapter, type TrainingExportOptions, type TrainingExportRecord, type TreeNode, WEARABLES_DIR_NAME, WearableCleanupSettings, type WearableConnectorFactory, type WearableConnectorFactoryOptions, type WearableConnectorRegistration, WearableConversation, WearableCorrectionRule, WearableDayTranscript, WearableDayTranscriptMeta, WearableSourceConnector, WearableSourceSettings, type WearableSourceSyncState, type WearableSyncStateFile, type WearablesCliIo, WearablesConfig, WearablesInputError, WearablesService, applyCorrections, applyOffTheRecord, branchNamespaceName, buildProcedureMarkdownBody, buildProcedureRecallSection, cleanConversation, clearTrainingExportAdapters, clearWearableConnectors, collapseImmediateRepeats, collectLocalSessionSummaries, compileCorrectionRule, compileCorrectionRules, compileRedactionPatterns, compileRedactionRules, composeDayTranscriptBody, composeDayTranscriptMeta, convertMemoriesToRecords, correctionsFilePath, createBackend, createGoogleDriveConnector, createNotionConnector, createSpace, curate, defaultGoogleDriveClientFactory, defaultWearableCleanupSettings, defaultWearableSourceSettings, defaultWearablesConfig, deleteSpace, describeCodingScope, describeErrorForOperator, emptyManifest, emptySyncState, ensureBuiltInWearableConnectors, findContradictions, findDuplicates, forkCapsule, generateContextTree, generateResolverDocument, getActiveSpace, getAuditLog, getLocalSessionSourceAdapter, getManifestPath, getSpacesDir, getTaxonomyDir, getTaxonomyFilePath, getTrainingExportAdapter, getWearableConnector, hashTranscriptBody, hostIdForConnector, isLowQualitySegment, isReviewPrompt, isValidTranscriptDate, listLocalSessionSourceAdapters, listReviewItems, listSpaces, listTrainingExportAdapters, listWearableConnectors, loadCorrectionsFile, loadManifest, loadSyncState, loadTaxonomy, manifestDir, manifestPath, matchesPatterns, mergeSpaces, normalizeOriginUrl, onboard, packReviewContext, parseDayTranscript, parseFlexibleIsoTimestamp, parseIsoOffsetTimestamp, parseIsoUtcTimestamp, parseProcedureStepsFromBody, parseTouchedFiles, parseWearablesConfig, performReview, projectNamespaceName, promoteSpace, publisherFor, publisherForConnector, pullFromSpace, pushToSpace, rankReviewCandidates, readForkLineage, readManifest, redactSessionSummaryText, redactText, registerLocalSessionSourceAdapter, registerPublisher, registerTrainingExportAdapter, registerWearableConnector, renderExtensionsBlock, renderExtensionsFooter, resolveCategory, resolveCodingNamespaceOverlay, resolveGitContext, runBinaryLifecyclePipeline, runLocalSessionSummaryCliCommand, runWearablesCliCommand, saveCorrectionsFile, saveManifest, saveSyncState, saveTaxonomy, scanForBinaries, serializeDayTranscript, shareSpace, stableHash, stripFillerTokens, switchSpace, syncChanges, syncStateFilePath, updateSourceSyncState, validateGoogleDriveConfig, validateNotionConfig, validateSlug, validateTaxonomy, watchForChanges, writeManifest };
+export { type ArchitectureHintsResult, type AuditEntry, type BinaryAssetRecord, type BinaryAssetStatus, type BinaryLifecycleConfig, type BinaryLifecycleManifest, type BinaryStorageBackend, type BinaryStorageBackendConfig, ClaudeCodeMemoryExtensionPublisher, type CleanupResult, CodexMemoryExtensionPublisher, type CodingNamespaceOverlay, type CodingScopeDescription, type CollectLocalSessionSummariesOptions, type CompiledCorrectionRule, type CompiledRedactionRule, type ConflictEntry, type ContradictionOptions, type ContradictionPair, type ContradictionResult$1 as CurateContradictionResult, type DuplicateResult as CurateDuplicateResult, type CurateOptions, type CurateResult, type CuratedStatement, DEFAULT_GRACE_PERIOD_DAYS, DEFAULT_MAX_BINARY_SIZE_BYTES, DEFAULT_REDACTION_RULES, DEFAULT_SCAN_PATTERNS, DEFAULT_TAXONOMY, type DedupOptions, type DedupResult, DiscoveredExtension, type DocFile, type DriveChange, type DriveChangesPage, type DriveFileMetadata, type DuplicatePair, type FileChange, FilesystemBackend, type ForkCapsuleOptions, type ForkCapsuleResult, type ForkLineage, GOOGLE_DRIVE_CONNECTOR_ID, GOOGLE_DRIVE_CURSOR_KIND, DEFAULT_POLL_INTERVAL_MS as GOOGLE_DRIVE_DEFAULT_POLL_INTERVAL_MS, type GenerateOptions, type GenerateResult, type GitContext, type GitInvoker, type GoogleDriveClient, type GoogleDriveClientFactory, type GoogleDriveConnectorConfig, type GoogleDriveSyncResult, HermesMemoryExtensionPublisher, type IngestionPlan, KNOWN_WEARABLE_SOURCE_IDS, type LanguageInfo, LiveConnector, LiveConnectorRegistry, LiveConnectorRegistryError, type LocalSessionAdapterInput, type LocalSessionAdapterOptions, type LocalSessionParseWarning, type LocalSessionParsedFile, type LocalSessionRole, type LocalSessionSourceAdapter, type LocalSessionSummaryCliOptions, type LocalSessionSummaryReport, type LocalSessionTurn, MemoryCategory, type MemoryEntry, type MemoryExtensionPublisher, type MergeResult, NOTION_CONNECTOR_ID, NOTION_CURSOR_KIND, NOTION_DEFAULT_POLL_INTERVAL_MS, NoneBackend, type NotionConnectorConfig, type OnboardOptions, type OnboardResult, PUBLISHERS, type PackReviewContextStructuralInput, type PipelineResult, PluginConfig, type ProjectShape, type ProvenanceEntry, type PublishContext, type PublishResult, type PublisherCapabilities, REDACTION_PLACEHOLDER, REMNIC_CITATION_FORMAT, REMNIC_MCP_TOOL_INVENTORY, REMNIC_RECALL_DECISION_RULES, REMNIC_SEMANTIC_OVERVIEW, type RedactionConfig, type RedactionReport, type RedactionRuleConfig, ResolverDecision, type ReviewAction, type ReviewCandidate, type ReviewContext, type ReviewItem, type ReviewListResult, type ReviewOptions, type ReviewResult, type SessionSummaryDraft, type SessionSummaryExcerpt, type Space, type SpaceKind, type SpaceManifest, type SpacePromoteResult, type SpacePullResult, type SpacePushResult, type SpaceShareResult, type SpaceSwitchResult, SpeakerRegistry, type StatementProvenance, StorageManager, type StructuralContextDegradation, type StructuralContextErrorCode, type StructuralContextProvider, type StructuralProviderStatus, type StructuralSpawnFn, type StructuralSymbol, type SubprocessProviderOptions, type SymbolsForDiffErr, type SymbolsForDiffOk, type SymbolsForDiffResult, SyncIncrementalResult, type SyncOptions, type SyncResult, type SyncState, Taxonomy, TokenEntry, type TrainingExportAdapter, type TrainingExportOptions, type TrainingExportRecord, type TreeNode, WEARABLES_DIR_NAME, WearableCleanupSettings, type WearableConnectorFactory, type WearableConnectorFactoryOptions, type WearableConnectorRegistration, WearableConversation, WearableCorrectionRule, WearableDayTranscript, WearableDayTranscriptMeta, WearableSourceConnector, WearableSourceSettings, type WearableSourceSyncState, type WearableSyncStateFile, type WearablesCliIo, WearablesConfig, WearablesInputError, WearablesService, applyCorrections, applyOffTheRecord, branchNamespaceName, buildProcedureMarkdownBody, buildProcedureRecallSection, cleanConversation, clearStructuralContextProvidersForTest, clearTrainingExportAdapters, clearWearableConnectors, collapseImmediateRepeats, collectLocalSessionSummaries, compileCorrectionRule, compileCorrectionRules, compileRedactionPatterns, compileRedactionRules, composeDayTranscriptBody, composeDayTranscriptMeta, convertMemoriesToRecords, correctionsFilePath, createBackend, createGoogleDriveConnector, createNotionConnector, createSpace, createSubprocessStructuralProvider, curate, defaultGoogleDriveClientFactory, defaultWearableCleanupSettings, defaultWearableSourceSettings, defaultWearablesConfig, deleteSpace, describeCodingScope, describeErrorForOperator, describeStructuralProviderStatus, emptyManifest, emptySyncState, ensureBuiltInWearableConnectors, findContradictions, findDuplicates, forkCapsule, generateContextTree, generateResolverDocument, getActiveSpace, getAuditLog, getLocalSessionSourceAdapter, getManifestPath, getSpacesDir, getStructuralContextProvider, getTaxonomyDir, getTaxonomyFilePath, getTrainingExportAdapter, getWearableConnector, hashTranscriptBody, hostIdForConnector, isLowQualitySegment, isReviewPrompt, isValidTranscriptDate, listLocalSessionSourceAdapters, listReviewItems, listSpaces, listTrainingExportAdapters, listWearableConnectors, loadCorrectionsFile, loadManifest, loadSyncState, loadTaxonomy, manifestDir, manifestPath, matchesPatterns, mergeSpaces, normalizeOriginUrl, onboard, packReviewContext, packReviewContextStructural, parseDayTranscript, parseFlexibleIsoTimestamp, parseIsoOffsetTimestamp, parseIsoUtcTimestamp, parseProcedureStepsFromBody, parseTouchedFiles, parseWearablesConfig, performReview, probeStructuralProviderForDoctor, projectNamespaceName, promoteSpace, publisherFor, publisherForConnector, pullFromSpace, pushToSpace, rankReviewCandidates, readForkLineage, readManifest, redactSessionSummaryText, redactText, registerLocalSessionSourceAdapter, registerPublisher, registerStructuralContextProvider, registerTrainingExportAdapter, registerWearableConnector, renderExtensionsBlock, renderExtensionsFooter, renderStructuralProviderStatusLine, resolveCategory, resolveCodingNamespaceOverlay, resolveGitContext, runBinaryLifecyclePipeline, runLocalSessionSummaryCliCommand, runWearablesCliCommand, saveCorrectionsFile, saveManifest, saveSyncState, saveTaxonomy, scanForBinaries, serializeDayTranscript, shareSpace, stableHash, stripFillerTokens, structuralProviderActive, switchSpace, syncChanges, syncStateFilePath, toStructuralContextDegradation, updateSourceSyncState, validateGoogleDriveConfig, validateNotionConfig, validateSlug, validateTaxonomy, watchForChanges, writeManifest };