desktop/src-tauri/crates/core/src/adapters/framework.rs

Comment 1, line 1

desktop/src-tauri/crates/core/src/adapters/framework.rs:1

//! Common adapter interface: discover, detect, scan, map and capability,

Comment 2, line 2

desktop/src-tauri/crates/core/src/adapters/framework.rs:2

//! with a runner feeding M1 commit_batch. V12: repeated reads do not duplicate usage.

Comment 3, line 3

desktop/src-tauri/crates/core/src/adapters/framework.rs:3

//!

Comment 4, line 4

desktop/src-tauri/crates/core/src/adapters/framework.rs:4

//! Rules:

Comment 5, line 5

desktop/src-tauri/crates/core/src/adapters/framework.rs:5

//! - discover: bounded candidate paths, environment overrides and manual roots; no full-disk scan;

Comment 6, line 6

desktop/src-tauri/crates/core/src/adapters/framework.rs:6

//! - detect: file signatures, record types and schema fingerprints, with per-Agent version registries;

Comment 7, line 7

desktop/src-tauri/crates/core/src/adapters/framework.rs:7

//!   unknown/missing versions try the latest built-in Agent reader with compatibility metadata (V17/V30);

Comment 8, line 8

desktop/src-tauri/crates/core/src/adapters/framework.rs:8

//!   verified incompatible versions and unknown formats remain restricted;

Comment 9, line 9

desktop/src-tauri/crates/core/src/adapters/framework.rs:9

//! - scan: incremental JSONL cursors keep file identity, generation, complete-line byte offset and parse context;

Comment 10, line 10

desktop/src-tauri/crates/core/src/adapters/framework.rs:10

//! - capability: declare the fields available from each source;

Comment 11, line 11

desktop/src-tauri/crates/core/src/adapters/framework.rs:11

//! - diagnostics keep field names, error codes and positions without copying raw content.

Comment 12, line 25

desktop/src-tauri/crates/core/src/adapters/framework.rs:25

/// Default wall-clock timeout for one source run: 30 seconds (architecture.md).

Comment 13, line 27

desktop/src-tauri/crates/core/src/adapters/framework.rs:27

/// Discovery file/directory limits.

Comment 14, line 31

desktop/src-tauri/crates/core/src/adapters/framework.rs:31

/// Transient detection I/O: short antivirus/product locks, Windows sharing violations

Comment 15, line 32

desktop/src-tauri/crates/core/src/adapters/framework.rs:32

/// mapped to PermissionDenied, timeouts or files deleted after enumeration.

Comment 16, line 33

desktop/src-tauri/crates/core/src/adapters/framework.rs:33

/// Return Pending and retry next run instead of persisting a scan failure or UnknownFormat.

Comment 17, line 45

desktop/src-tauri/crates/core/src/adapters/framework.rs:45

/// Read a detection header; Ok(None) means transiently unreadable and requires Pending.

Comment 18, line 46

desktop/src-tauri/crates/core/src/adapters/framework.rs:46

/// Propagate other errors as CoreError.

Comment 19, line 63

desktop/src-tauri/crates/core/src/adapters/framework.rs:63

/// Discovery context: an explicit environment map supports isolated tests without process-environment reads.

Comment 20, line 71

desktop/src-tauri/crates/core/src/adapters/framework.rs:71

/// How a candidate root was selected.

Comment 21, line 75

desktop/src-tauri/crates/core/src/adapters/framework.rs:75

/// Environment override; the stored string is the variable name, not its value.

Comment 22, line 77

desktop/src-tauri/crates/core/src/adapters/framework.rs:77

/// Platform default user directory.

Comment 23, line 79

desktop/src-tauri/crates/core/src/adapters/framework.rs:79

/// User-added manual root.

Comment 24, line 83

desktop/src-tauri/crates/core/src/adapters/framework.rs:83

/// Candidate root with bounded file enumeration.

Comment 25, line 91

desktop/src-tauri/crates/core/src/adapters/framework.rs:91

/// Detection results follow architecture.md compatibility rules:

Comment 26, line 92

desktop/src-tauri/crates/core/src/adapters/framework.rs:92

/// - Supported: verified Agent identity/input type; known versions dispatch through the registry.

Comment 27, line 93

desktop/src-tauri/crates/core/src/adapters/framework.rs:93

///   Unknown/missing versions select LatestFallback and retain compatibility metadata.

Comment 28, line 94

desktop/src-tauri/crates/core/src/adapters/framework.rs:94

/// - UnsupportedVersion: verified incompatibility, such as a different source format; no fallback.

Comment 29, line 95

desktop/src-tauri/crates/core/src/adapters/framework.rs:95

/// - UnknownFormat: unverified Agent/format stays restricted instead of reporting successful zero records (V17).

Comment 30, line 100

desktop/src-tauri/crates/core/src/adapters/framework.rs:100

/// Native version, or None when absent; LatestFallback remains possible.

Comment 31, line 112

desktop/src-tauri/crates/core/src/adapters/framework.rs:112

/// No classifiable content yet, such as an empty new file; retry next run.

Comment 32, line 116

desktop/src-tauri/crates/core/src/adapters/framework.rs:116

/// Availability of one capability.

Comment 33, line 125

desktop/src-tauri/crates/core/src/adapters/framework.rs:125

/// Structured discovery, detection, mapping, incremental, deduplication, coverage, maintenance and scheduling capabilities.

Comment 34, line 134

desktop/src-tauri/crates/core/src/adapters/framework.rs:134

/// Token/cache/call/model/time/cost/latency field availability.

Comment 35, line 145

desktop/src-tauri/crates/core/src/adapters/framework.rs:145

/// One file to scan.

Comment 36, line 149

desktop/src-tauri/crates/core/src/adapters/framework.rs:149

/// Normalized local file path; store locally and exclude from external output.

Comment 37, line 151

desktop/src-tauri/crates/core/src/adapters/framework.rs:151

/// source_files.file_id, based on the normalized path.

Comment 38, line 153

desktop/src-tauri/crates/core/src/adapters/framework.rs:153

/// source_files.file_identity/checkpoint scope_key, stable across supported renames.

Comment 39, line 155

desktop/src-tauri/crates/core/src/adapters/framework.rs:155

/// Current observed file state.

Comment 40, line 157

desktop/src-tauri/crates/core/src/adapters/framework.rs:157

/// Generation selected by file-continuity rules; a rescan already uses the new value.

Comment 41, line 159

desktop/src-tauri/crates/core/src/adapters/framework.rs:159

/// Whether replacement, truncation or rebuilding requires a scan from the beginning.

Comment 42, line 163

desktop/src-tauri/crates/core/src/adapters/framework.rs:163

/// Stored cursor and parse context.

Comment 43, line 170

desktop/src-tauri/crates/core/src/adapters/framework.rs:170

/// Scan limits.

Comment 44, line 176

desktop/src-tauri/crates/core/src/adapters/framework.rs:176

/// File scan status.

Comment 45, line 179

desktop/src-tauri/crates/core/src/adapters/framework.rs:179

/// Reached the current end of file.

Comment 46, line 181

desktop/src-tauri/crates/core/src/adapters/framework.rs:181

/// Read/time limit reached; preserve a complete-line cursor and continue next run.

Comment 47, line 183

desktop/src-tauri/crates/core/src/adapters/framework.rs:183

/// Oversized line: restrict reading at its start and permit a controlled retry.

Comment 48, line 185

desktop/src-tauri/crates/core/src/adapters/framework.rs:185

/// Empty file awaiting content.

Comment 49, line 200

desktop/src-tauri/crates/core/src/adapters/framework.rs:200

/// Snapshot reconciliation with selected numeric fields, without message content.

Comment 50, line 203

desktop/src-tauri/crates/core/src/adapters/framework.rs:203

/// Series label, such as session_cumulative_snapshot, without IDs/paths.

Comment 51, line 205

desktop/src-tauri/crates/core/src/adapters/framework.rs:205

/// Sum of detailed total_tokens values.

Comment 52, line 207

desktop/src-tauri/crates/core/src/adapters/framework.rs:207

/// Final cumulative snapshot value.

Comment 53, line 209

desktop/src-tauri/crates/core/src/adapters/framework.rs:209

/// Sum of boundary records excluded by verified rules, such as compaction-carried usage.

Comment 54, line 211

desktop/src-tauri/crates/core/src/adapters/framework.rs:211

/// Difference: detail_sum - (snapshot_final + carried_sum).

Comment 55, line 213

desktop/src-tauri/crates/core/src/adapters/framework.rs:213

/// Reconciliation verdict: matched, mismatch or no_snapshot.

Comment 56, line 217

desktop/src-tauri/crates/core/src/adapters/framework.rs:217

/// One scan result.

Comment 57, line 229

desktop/src-tauri/crates/core/src/adapters/framework.rs:229

/// Source-file health: active or degraded.

Comment 58, line 233

desktop/src-tauri/crates/core/src/adapters/framework.rs:233

/// Common adapter interface.

Comment 59, line 236

desktop/src-tauri/crates/core/src/adapters/framework.rs:236

/// Agent name used by statistics and event.agent.

Comment 60, line 238

desktop/src-tauri/crates/core/src/adapters/framework.rs:238

/// Bounded discovery through candidate paths, environment overrides and manual roots.

Comment 61, line 240

desktop/src-tauri/crates/core/src/adapters/framework.rs:240

/// Opt in only when files can be visited independently of discovery order.

Comment 62, line 244

desktop/src-tauri/crates/core/src/adapters/framework.rs:244

/// Stable local instance ID for a candidate root.

Comment 63, line 246

desktop/src-tauri/crates/core/src/adapters/framework.rs:246

/// Detect file signature/record type/schema; use the per-Agent registry for version selection.

Comment 64, line 248

desktop/src-tauri/crates/core/src/adapters/framework.rs:248

/// Incrementally scan one supported file.

Comment 65, line 256

desktop/src-tauri/crates/core/src/adapters/framework.rs:256

/// Recheck consumed, unchanged files while preserving monotonic revisions in cursor context.

Comment 66, line 257

desktop/src-tauri/crates/core/src/adapters/framework.rs:257

/// Skip by default; snapshot adapters can opt in for a one-time statistics/health rule correction.

Comment 67, line 261

desktop/src-tauri/crates/core/src/adapters/framework.rs:261

/// Update file compatibility from per-record checks, committing it with events and cursors.

Comment 68, line 265

desktop/src-tauri/crates/core/src/adapters/framework.rs:265

/// Structured capability declaration.

Comment 69, line 268

desktop/src-tauri/crates/core/src/adapters/framework.rs:268

/// Complete prior hashes for explicitly verified parser corrections only.

Comment 70, line 269

desktop/src-tauri/crates/core/src/adapters/framework.rs:269

/// Require the same source revision; unrelated field changes still conflict.

Comment 71, line 277

desktop/src-tauri/crates/core/src/adapters/framework.rs:277

/// A verified archive may replace file scanning for this root.

Comment 72, line 278

desktop/src-tauri/crates/core/src/adapters/framework.rs:278

/// Keep errors visible without silently adding counts from a second data format.

Comment 73, line 289

desktop/src-tauri/crates/core/src/adapters/framework.rs:289

/// Normalize separators and remove the Windows verbatim prefix for local identity.

Comment 74, line 296

desktop/src-tauri/crates/core/src/adapters/framework.rs:296

/// Enumerate bounded depth/file/directory counts without following symlinks.

Comment 75, line 343

desktop/src-tauri/crates/core/src/adapters/framework.rs:343

/// Rotate bounded file windows using persisted visits; unvisited files go first.

Comment 76, line 344

desktop/src-tauri/crates/core/src/adapters/framework.rs:344

/// Equal visits retain the adapter's discovery order. Only committed file rows

Comment 77, line 345

desktop/src-tauri/crates/core/src/adapters/framework.rs:345

/// count as visits, so a rolled-back read keeps its place for the next run.

Comment 78, line 373

desktop/src-tauri/crates/core/src/adapters/framework.rs:373

/// source_instances registration input; preserve user settings such as enabled during conflict updates.

Comment 79, line 374

desktop/src-tauri/crates/core/src/adapters/framework.rs:374

/// Verified local collection supplies origin_host_id; None denotes legacy_unknown ownership.

Comment 80, line 375

desktop/src-tauri/crates/core/src/adapters/framework.rs:375

/// Preserve sources owned by another host; verified local collection may claim legacy_unknown sources

Comment 81, line 376

desktop/src-tauri/crates/core/src/adapters/framework.rs:376

/// when file locality and ownership mapping are verified (data-contract.md#provenance).

Comment 82, line 390

desktop/src-tauri/crates/core/src/adapters/framework.rs:390

/// Source host ownership (M1a); None uses the legacy_unknown namespace.

Comment 83, line 394

desktop/src-tauri/crates/core/src/adapters/framework.rs:394

/// Historical namespace for databases before v4 host ownership.

Comment 84, line 473

desktop/src-tauri/crates/core/src/adapters/framework.rs:473

/// source_files row used for registration, rename and replacement detection.

Comment 85, line 486

desktop/src-tauri/crates/core/src/adapters/framework.rs:486

/// Detection JSON: native version, selected format/parser, selection basis and compatibility (v3 column).

Comment 86, line 553

desktop/src-tauri/crates/core/src/adapters/framework.rs:553

/// Find by file identity: a supported rename preserves the content stream while changing its path.

Comment 87, line 616

desktop/src-tauri/crates/core/src/adapters/framework.rs:616

/// Load cursor and parse context from the checkpoint.

Comment 88, line 640

desktop/src-tauri/crates/core/src/adapters/framework.rs:640

/// Build StoredFileState from source_files for file-continuity checks.

Comment 89, line 653

desktop/src-tauri/crates/core/src/adapters/framework.rs:653

/// Configuration for one collection run.

Comment 90, line 660

desktop/src-tauri/crates/core/src/adapters/framework.rs:660

/// Run/batch ID prefix, with the instance sequence appended.

Comment 91, line 662

desktop/src-tauri/crates/core/src/adapters/framework.rs:662

/// Local source-host ID (M1a); None denotes legacy_unknown ownership.

Comment 92, line 663

desktop/src-tauri/crates/core/src/adapters/framework.rs:663

/// The application obtains it through Storage::ensure_local_host.

Comment 93, line 667

desktop/src-tauri/crates/core/src/adapters/framework.rs:667

/// Per-file run report.

Comment 94, line 679

desktop/src-tauri/crates/core/src/adapters/framework.rs:679

/// Per-instance run report.

Comment 95, line 692

desktop/src-tauri/crates/core/src/adapters/framework.rs:692

/// Discover and detect/scan each file, then commit the instance in one transaction (V12).

Comment 96, line 693

desktop/src-tauri/crates/core/src/adapters/framework.rs:693

/// Return instance reports; isolate file failures and mark an unsuccessful instance commit failed.

Comment 97, line 703

desktop/src-tauri/crates/core/src/adapters/framework.rs:703

/// Instance filters support source schedules: custom-scheduled sources use their own triggers,

Comment 98, line 704

desktop/src-tauri/crates/core/src/adapters/framework.rs:704

/// global refresh excludes them, and due-source refresh includes only due instances.

Comment 99, line 707

desktop/src-tauri/crates/core/src/adapters/framework.rs:707

/// Include these instances only; None imposes no inclusion filter.

Comment 100, line 709

desktop/src-tauri/crates/core/src/adapters/framework.rs:709

/// Skip these instances; None imposes no exclusion filter.

Comment 101, line 729

desktop/src-tauri/crates/core/src/adapters/framework.rs:729

/// Filtered run_adapter_scan for source scheduling.

Comment 102, line 730

desktop/src-tauri/crates/core/src/adapters/framework.rs:730

/// Check source_instances.enabled before reading from any trigger:

Comment 103, line 731

desktop/src-tauri/crates/core/src/adapters/framework.rs:731

/// Interval, Startup, Manual or FixedTime. Read only enabled local sources,

Comment 104, line 732

desktop/src-tauri/crates/core/src/adapters/framework.rs:732

/// preserving set_source_enabled behavior after an instance is disabled.

Comment 105, line 733

desktop/src-tauri/crates/core/src/adapters/framework.rs:733

/// If disabled-instance loading fails, stop this adapter before reading sources.

Comment 106, line 787

desktop/src-tauri/crates/core/src/adapters/framework.rs:787

/// Keep source parsing outside the writer lock; metadata and commits use it.

Comment 107, line 859

desktop/src-tauri/crates/core/src/adapters/framework.rs:859

/// Two source-instance slots, one existing writer; results retain request/root order.

Comment 108, line 954

desktop/src-tauri/crates/core/src/adapters/framework.rs:954

// A worker panic may leave a running job; normal Storage recovery handles it.

Comment 109, line 1007

desktop/src-tauri/crates/core/src/adapters/framework.rs:1007

/// Metadata and commits share the existing writer; source parsing holds no writer lock.

Comment 110, line 1029

desktop/src-tauri/crates/core/src/adapters/framework.rs:1029

// Deduplicate environment/default/manual roots; normalize Windows case aliases first.

Comment 111, line 1058

desktop/src-tauri/crates/core/src/adapters/framework.rs:1058

// Archive adapters use an empty file list and perform their own detection.

Comment 112, line 1137

desktop/src-tauri/crates/core/src/adapters/framework.rs:1137

// A merged request performed no scan here; do not report it as completed.

Comment 113, line 1187

desktop/src-tauri/crates/core/src/adapters/framework.rs:1187

// Preparation failures and cancellation finish the run just

Comment 114, line 1188

desktop/src-tauri/crates/core/src/adapters/framework.rs:1188

// like archive failures, without leaving a running job behind.

Comment 115, line 1372

desktop/src-tauri/crates/core/src/adapters/framework.rs:1372

// Skip commits when no file changed; unchanged scans do not advance the data revision.

Comment 116, line 1390

desktop/src-tauri/crates/core/src/adapters/framework.rs:1390

// Commit native aggregates with events and cursors; any failure permits a complete replay.

Comment 117, line 1467

desktop/src-tauri/crates/core/src/adapters/framework.rs:1467

/// Register one file, check continuity, detect when needed, scan and collect batch results.

Comment 118, line 1468

desktop/src-tauri/crates/core/src/adapters/framework.rs:1468

/// Return the file report and whether an actual read occurred.

Comment 119, line 1509

desktop/src-tauri/crates/core/src/adapters/framework.rs:1509

// After a path miss, check file identity; renaming the same stream does not create a new file.

Comment 120, line 1544

desktop/src-tauri/crates/core/src/adapters/framework.rs:1544

// Skip unchanged files whose bytes are fully consumed and continuity is intact.

Comment 121, line 1566

desktop/src-tauri/crates/core/src/adapters/framework.rs:1566

// Detect again on first scan/rescan; restrict verified incompatible versions and unknown formats (V17).

Comment 122, line 1567

desktop/src-tauri/crates/core/src/adapters/framework.rs:1567

// Unknown/missing versions use the latest registered Agent reader and retain compatibility metadata.

Comment 123, line 1705

desktop/src-tauri/crates/core/src/adapters/framework.rs:1705

// File error isolation must not classify cancellation or another control stop as invalid data.

Comment 124, line 1733

desktop/src-tauri/crates/core/src/adapters/framework.rs:1733

// V30 fallback with structural diagnostics and no events/valid exclusive aggregate is incompatible.

Comment 125, line 1734

desktop/src-tauri/crates/core/src/adapters/framework.rs:1734

// Duplicate/OverlapUnknown reconciliation snapshots do not establish valid usage, such as old Codex without calls.

Comment 126, line 1735

desktop/src-tauri/crates/core/src/adapters/framework.rs:1735

// Keep prior results without new cursors/aggregates; retry after a parser update or explicit rescan.

Comment 127, line 1832

desktop/src-tauri/crates/core/src/adapters/framework.rs:1832

/// Detection JSON in source_files.format_status (v3): selected metadata fields, without message content.

Comment 128, line 1859

desktop/src-tauri/crates/core/src/adapters/framework.rs:1859

/// File-stream identity: creation time and sampled prefix fingerprint/length, independent of path.