snipara-companion 3.5.9 → 3.6.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 Release notes for `snipara-companion`, newest first.
 
+## New In 3.6.0
+
+- Upgrades the local code overlay to v2 with TypeScript Compiler API symbols,
+  stable identities, and `CALLS`, `REFERENCES`, `IMPORTS`, and `CONTAINS` edges.
+- Adds bounded transitive callers, neighbors, shortest paths, and impact with
+  depth/direction/edge filters, cycle and node budgets, chains, and explainable
+  local risk scoring.
+- Reuses unchanged per-file extraction slices during sync and `source watch`.
+- Adds `--source hybrid` and `--fallback-hosted`: configured dirty/ahead
+  checkouts preserve the hosted canonical base plus the local delta, with
+  explicit degraded provenance when hosted enrichment fails.
+- Sends impact depth, direction, and edge-kind controls to hosted MCP.
+
+## New In 3.5.10
+
+- Reports hosted `decision_capture.created` drafts as pending Why Capture
+  decisions in phase/final receipts and final reports, instead of incorrectly
+  showing zero captured candidates when the memory write was deduplicated.
+
 ## New In 3.5.9
 
 - Routes explicit `workflow phase-commit` and `final-commit` rationale through

package/README.md

@@ -93,7 +93,7 @@ These commands are useful without hosted Snipara:
 | Command                                                                               | What it gives you locally                                                    |
 | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
 | `source init` / `source sync` / `source status`                                       | Local source snapshot, document preview, and code overlay                    |
-| `impact` / `code impact`                                                              | File-level blast-radius from the local code overlay                          |
+| `impact` / `code impact`                                                              | Bounded transitive blast radius, chains, and explainable local risk          |
 | `reality-check`                                                                       | Intent Ledger, Unknown Registry, auto-linked context, and inspectable proof  |
 | `code callers` / `imports` / `neighbors` / `shortest-path`                            | Structural repo questions from local files                                   |
 | `workflow start` / `phase-start` / `phase-commit` / `resume`                          | Agent continuity that survives compaction                                    |
@@ -394,6 +394,14 @@ This writes `.snipara/source/latest.json`, builds a local document sync preview,
 and refreshes `.snipara/code-overlay/latest.json`. The hosted code graph remains
 the canonical shared graph after provider sync.
 
+Overlay v2 uses the TypeScript Compiler API to extract stable symbols plus
+`CALLS`, `REFERENCES`, `IMPORTS`, and `CONTAINS` edges. Python and Go retain an
+import-level fallback. Use `--depth`, `--direction`, `--edge-kinds`, and
+`--max-nodes` to bound traversal. `source watch` refreshes the overlay with
+per-file incremental reuse. With hosted configuration, `--source auto` uses the
+hosted graph for a clean checkout and a provenance-preserving hybrid for dirty
+or ahead work; `--source local` remains completely offline.
+
 ## Install
 
 Use `npx` for one-off checks:

package/dist/index.d.ts

@@ -1307,6 +1307,9 @@ declare class RLMClient {
         filePath?: string;
         changedFiles?: string[];
         diffSummary?: string;
+        depth?: number;
+        direction?: "in" | "out" | "both";
+        edgeKinds?: string[];
         limit?: number;
     }): Promise<Record<string, unknown>>;
     /**
@@ -1794,18 +1797,49 @@ interface LocalCodeOverlayFile {
     sha256: string;
     symbolCount: number;
     importCount: number;
+    referenceCount: number;
+    edgeCount: number;
 }
 interface LocalCodeOverlaySymbol {
     name: string;
     kind: "function" | "class" | "interface" | "type" | "variable" | "method";
     filePath: string;
     line: number;
+    endLine?: number;
+    qualifiedName: string;
     localKey: string;
 }
+interface LocalCodeOverlayImportBinding {
+    localName: string;
+    importedName: string;
+    kind: "named" | "default" | "namespace";
+}
 interface LocalCodeOverlayImport {
     filePath: string;
     specifier: string;
     line: number;
+    bindings?: LocalCodeOverlayImportBinding[];
+}
+interface LocalCodeOverlayReference {
+    filePath: string;
+    from: string;
+    name: string;
+    kind: "CALLS" | "REFERENCES";
+    line: number;
+    confidence: number;
+}
+interface LocalCodeOverlayEdge {
+    from: string;
+    to: string;
+    kind: "IMPORTS" | "CALLS" | "REFERENCES" | "CONTAINS";
+    filePath: string;
+    line: number;
+    confidence: number;
+    source: "typescript-compiler-api" | "language-parser" | "import-resolver";
+    evidence: {
+        filePath: string;
+        line: number;
+    };
 }
 interface LocalCodeOverlayWarning {
     code: string;
@@ -1819,7 +1853,8 @@ interface LocalCodeOverlayExcludedFile {
     line?: number;
 }
 interface LocalCodeOverlayManifest {
-    version: "snipara.local_code_overlay.v1";
+    version: "snipara.local_code_overlay.v2";
+    extractorVersion: 2;
     generatedAt: string;
     indexedAt: string;
     repoRoot: string;
@@ -1837,6 +1872,13 @@ interface LocalCodeOverlayManifest {
     files: LocalCodeOverlayFile[];
     symbols: LocalCodeOverlaySymbol[];
     imports: LocalCodeOverlayImport[];
+    references: LocalCodeOverlayReference[];
+    edges: LocalCodeOverlayEdge[];
+    incremental: {
+        reusedFiles: number;
+        parsedFiles: number;
+        deletedFiles: number;
+    };
     excluded: {
         total: number;
         byReason: Record<LocalCodeOverlayExcludedFile["reason"], number>;
@@ -1873,9 +1915,15 @@ interface LocalCodeQueryCommandOptions extends CodeStatusCommandOptions {
     from?: string;
     to?: string;
     maxHops?: number;
-}
-type CodeGraphSource = "auto" | "hosted" | "local";
-type ResolvedCodeGraphSource = "hosted_graph" | "local_overlay";
+    depth?: number;
+    direction?: "in" | "out" | "both";
+    edgeKinds?: string[];
+    maxNodes?: number;
+    transitive?: boolean;
+}
+type CodeGraphSource = "auto" | "hosted" | "local" | "hybrid";
+type ResolvedCodeGraphSource = "hosted_graph" | "local_overlay" | "hybrid_graph";
+type CodeGraphVerb = "callers" | "imports" | "neighbors" | "shortest-path" | "impact";
 interface CodeGraphSourceSelection {
     requested: CodeGraphSource;
     selected: ResolvedCodeGraphSource;
@@ -1896,12 +1944,14 @@ interface CodeGraphSourceSelection {
         fileCount: number;
         symbolCount: number;
         importCount: number;
+        edgeCount: number;
         warnings: LocalCodeOverlayManifest["warnings"];
     };
     hosted?: {
         configured: boolean;
         indexFreshness?: unknown;
         contextScope?: unknown;
+        error?: string;
     };
     limitations: string[];
 }
@@ -1958,8 +2008,11 @@ interface LocalCodeOverlaySummary {
         files: number;
         symbols: number;
         imports: number;
+        references: number;
+        edges: number;
         excluded: number;
     };
+    incremental: LocalCodeOverlayManifest["incremental"];
     excludedByReason: Record<LocalCodeOverlayExcludedFile["reason"], number>;
     fileSamples: string[];
     warnings: LocalCodeOverlayManifest["warnings"];
@@ -1997,6 +2050,17 @@ declare function writeLocalCodeOverlayCache(manifest: LocalCodeOverlayManifest):
 declare function readLocalCodeOverlayCache(cwd?: string): LocalCodeOverlayManifest | null;
 declare function writeLocalCodePromotionState(state: LocalCodePromotionState): string;
 declare function readLocalCodePromotionState(cwd?: string): LocalCodePromotionState | null;
+declare function resolveCodeGraphMode(args: {
+    requested: CodeGraphSource;
+    dirtyFiles: string[];
+    aheadCount: number | null;
+    hostedConfigured: boolean;
+    fallbackHosted: boolean;
+}): {
+    selected: ResolvedCodeGraphSource;
+    reason: string;
+};
+declare function mergeHybridCodeResults(verb: CodeGraphVerb, localResult: unknown, hostedResult: unknown, hostedError?: string): Record<string, unknown>;
 declare function buildCodeStatusResult(options: CodeStatusCommandOptions): Record<string, unknown>;
 declare function buildCodeSyncResult(options: CodeSyncCommandOptions): Record<string, unknown>;
 declare function buildHostedCodeOverlayUploadPayload(options?: CodeUploadCommandOptions): HostedCodeOverlayUploadPayload;
@@ -5011,4 +5075,4 @@ declare function installAutomationBundle(args: {
 }): Promise<AutomationInstallResult>;
 declare function getAutomationStatus(projectDir?: string): AutomationStatusResult;
 
-export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, CODING_INTELLIGENCE_LEDGER_VERSION, COLLABORATION_STATE_RELATIVE_PATH, ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES, ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES, ENGINEERING_LEAD_POSTURES, ENGINEERING_LEAD_PROOF_VERIFICATION_SOURCES, ENGINEERING_LEAD_PROOF_VERIFICATION_STATUSES, ENGINEERING_LEAD_ROUTING_MODES, ENGINEERING_LEAD_STATUSES, ENGINEERING_LEAD_SUPERVISION_STATUSES, ENGINEERING_LEAD_WORKER_ROLES, ENGINEERING_LEAD_WORK_PACKAGE_STATUSES, FINAL_COMMIT_REPORT_RELATIVE_PATH, FINAL_COMMIT_REPORT_VERSION, MEMORY_GUARD_CONTEXT_TIMEOUT_MS, MEMORY_GUARD_RECALL_TIMEOUT_MS, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, POLICY_LEDGER_SYNC_REPORT_VERSION, PRODUCER_LOOP_ARTIFACT_VERSION, PRODUCER_LOOP_RELATIVE_DIR, PRODUCER_LOOP_REPORT_VERSION, TEAM_SYNC_STATE_RELATIVE_PATH, WHY_OUTCOME_CAPTURE_VERSION, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, addLocalWorker, agentReadinessAuditCommand, appendActivityEvent, applyLocalContextMutationPlan, archiveInactiveTeamSyncWork, attachLocalContextPackReceipts, autoArchiveTeamSyncState, buildAdaptiveWorkRoutingRecommendation, buildAgentReadinessAuditReport, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCodingIntelligenceLedger, buildCollaborationActor, buildCollaborationGuardActionCards, buildCollaborationHooksInstallPlan, buildCommitResultMetadata, buildCompanionEngineeringLeadPlanReport, buildContextPackStats, buildEvalCaseArtifact, buildFinalCommitReport, buildGeneratedWorkflowPlanDocument, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalContextMutationPlan, buildLocalContextPackReceipt, buildLocalContextPackReceipts, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalProjectContextValidationReport, buildLocalProjectDriftReport, buildLocalProjectRealityCheck, buildLocalProjectRealityCheckWithAutoContext, buildLocalShortestPathResult, buildLocalSourceSnapshot, buildLocalSourceStatus, buildLocalSourceSyncResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildPolicyLedgerSyncReport, buildProducerLoopReport, buildProjectIntelligenceBrief, buildProjectIntelligenceRun, buildProjectJudgmentCard, buildSessionBootstrapBrief, buildSessionBootstrapQuality, buildSessionSnapshot, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWhyOutcomeCaptureReport, buildWorkerTrustCandidates, buildWorkflowImpactGate, buildWorkflowPhaseCommitReceipt, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, cleanContextPacks, codingLedgerExportCommand, collaborationIdeStatusCommand, collectAgentReadinessLocalSignals, collectPolicyLedgerSyncArtifacts, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, compareLocalSourceSnapshots, completeTeamSyncStateFromEvidence, completeTeamSyncWorkFromEvidence, contextControlApplyCommand, contextControlDriftCommand, contextControlHostedApplyCommand, contextControlHostedDiffCommand, contextControlPlanCommand, contextControlValidateCommand, contextPackCleanCommand, contextPackPackCommand, contextPackRetrieveCommand, contextPackStatsCommand, controlledWorkerExecuteCommand, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, evaluateProjectPolicyGates, extractCommandFromToolInput, extractFilesFromToolInput, formatAgentReadinessAuditReport, formatCompanionEngineeringLeadPlanReport, formatFinalCommitReport, formatOrchestratorRecommendationReason, formatPolicyGateDecision, formatProjectJudgmentCard, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getContextPackStoragePaths, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getLocalSourceSnapshotPath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, hashWorkerProfile, ingestReferences, installAutomationBundle, leadPlanCommand, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, memoryReviewsCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, outcomeCapturePreviewCommand, packContext, parseCollaborationResources, projectIntelligenceBriefCommand, projectIntelligenceRunCommand, readActivityTimeline, readLocalCodeOverlayCache, readLocalCodePromotionState, readLocalSourceSnapshot, readLocalWorkersConfig, readSessionSnapshot, readWorkerTrustEvent, realityCheckCommand, referencesIngestCommand, referencesScanCommand, resolveAutoWorkflowMode, resolveContextPackRecord, resolveFullWorkflowTokenBudget, resolveLocalWorkerRoutingDefaults, resolveQueryFromToolInput, retrieveContextPack, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldFailCollaborationGuard, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, validatePlanResult, verifyCommand, workerTrustCandidateCommand, workerTrustReviewCommand, workerTrustStatusCommand, workersLocalAddCommand, workersLocalListCommand, workersLocalProbePrintCommand, workersLocalRemoveCommand, workersLocalStatusCommand, workflowSyncPolicyLedgerCommand, writeFinalCommitReport, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeLocalSourceSnapshot, writeOrchestratorHandoff, writeProducerLoopArtifact, writeSessionSnapshot };
+export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, CODING_INTELLIGENCE_LEDGER_VERSION, COLLABORATION_STATE_RELATIVE_PATH, ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES, ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES, ENGINEERING_LEAD_POSTURES, ENGINEERING_LEAD_PROOF_VERIFICATION_SOURCES, ENGINEERING_LEAD_PROOF_VERIFICATION_STATUSES, ENGINEERING_LEAD_ROUTING_MODES, ENGINEERING_LEAD_STATUSES, ENGINEERING_LEAD_SUPERVISION_STATUSES, ENGINEERING_LEAD_WORKER_ROLES, ENGINEERING_LEAD_WORK_PACKAGE_STATUSES, FINAL_COMMIT_REPORT_RELATIVE_PATH, FINAL_COMMIT_REPORT_VERSION, MEMORY_GUARD_CONTEXT_TIMEOUT_MS, MEMORY_GUARD_RECALL_TIMEOUT_MS, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, POLICY_LEDGER_SYNC_REPORT_VERSION, PRODUCER_LOOP_ARTIFACT_VERSION, PRODUCER_LOOP_RELATIVE_DIR, PRODUCER_LOOP_REPORT_VERSION, TEAM_SYNC_STATE_RELATIVE_PATH, WHY_OUTCOME_CAPTURE_VERSION, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, addLocalWorker, agentReadinessAuditCommand, appendActivityEvent, applyLocalContextMutationPlan, archiveInactiveTeamSyncWork, attachLocalContextPackReceipts, autoArchiveTeamSyncState, buildAdaptiveWorkRoutingRecommendation, buildAgentReadinessAuditReport, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCodingIntelligenceLedger, buildCollaborationActor, buildCollaborationGuardActionCards, buildCollaborationHooksInstallPlan, buildCommitResultMetadata, buildCompanionEngineeringLeadPlanReport, buildContextPackStats, buildEvalCaseArtifact, buildFinalCommitReport, buildGeneratedWorkflowPlanDocument, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalContextMutationPlan, buildLocalContextPackReceipt, buildLocalContextPackReceipts, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalProjectContextValidationReport, buildLocalProjectDriftReport, buildLocalProjectRealityCheck, buildLocalProjectRealityCheckWithAutoContext, buildLocalShortestPathResult, buildLocalSourceSnapshot, buildLocalSourceStatus, buildLocalSourceSyncResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildPolicyLedgerSyncReport, buildProducerLoopReport, buildProjectIntelligenceBrief, buildProjectIntelligenceRun, buildProjectJudgmentCard, buildSessionBootstrapBrief, buildSessionBootstrapQuality, buildSessionSnapshot, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWhyOutcomeCaptureReport, buildWorkerTrustCandidates, buildWorkflowImpactGate, buildWorkflowPhaseCommitReceipt, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, cleanContextPacks, codingLedgerExportCommand, collaborationIdeStatusCommand, collectAgentReadinessLocalSignals, collectPolicyLedgerSyncArtifacts, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, compareLocalSourceSnapshots, completeTeamSyncStateFromEvidence, completeTeamSyncWorkFromEvidence, contextControlApplyCommand, contextControlDriftCommand, contextControlHostedApplyCommand, contextControlHostedDiffCommand, contextControlPlanCommand, contextControlValidateCommand, contextPackCleanCommand, contextPackPackCommand, contextPackRetrieveCommand, contextPackStatsCommand, controlledWorkerExecuteCommand, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, evaluateProjectPolicyGates, extractCommandFromToolInput, extractFilesFromToolInput, formatAgentReadinessAuditReport, formatCompanionEngineeringLeadPlanReport, formatFinalCommitReport, formatOrchestratorRecommendationReason, formatPolicyGateDecision, formatProjectJudgmentCard, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getContextPackStoragePaths, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getLocalSourceSnapshotPath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, hashWorkerProfile, ingestReferences, installAutomationBundle, leadPlanCommand, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, memoryReviewsCommand, mergeHybridCodeResults, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, outcomeCapturePreviewCommand, packContext, parseCollaborationResources, projectIntelligenceBriefCommand, projectIntelligenceRunCommand, readActivityTimeline, readLocalCodeOverlayCache, readLocalCodePromotionState, readLocalSourceSnapshot, readLocalWorkersConfig, readSessionSnapshot, readWorkerTrustEvent, realityCheckCommand, referencesIngestCommand, referencesScanCommand, resolveAutoWorkflowMode, resolveCodeGraphMode, resolveContextPackRecord, resolveFullWorkflowTokenBudget, resolveLocalWorkerRoutingDefaults, resolveQueryFromToolInput, retrieveContextPack, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldFailCollaborationGuard, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, validatePlanResult, verifyCommand, workerTrustCandidateCommand, workerTrustReviewCommand, workerTrustStatusCommand, workersLocalAddCommand, workersLocalListCommand, workersLocalProbePrintCommand, workersLocalRemoveCommand, workersLocalStatusCommand, workflowSyncPolicyLedgerCommand, writeFinalCommitReport, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeLocalSourceSnapshot, writeOrchestratorHandoff, writeProducerLoopArtifact, writeSessionSnapshot };