Coverage Tracking System

Relevant source files

The following files were used as context for generating this wiki page:

• src/db/coverage-store.ts
• src/status.ts
• src/indexer.ts
• src/types.ts
• AGENTS.md
• README.md
• skill-packages/cxs/references/json-schema.md

The Coverage Tracking System in cxs is a critical mechanism designed to manage the synchronization state between local Codex session JSONL files and the SQLite search index. It ensures that retrieval operations are performed against a complete and fresh dataset without requiring a full re-sync for every query. The system tracks coverage based on "Selectors"—structured definitions of file subsets—and provides a "Recommended Action" (either query or sync) to the user or agent based on the "Freshness" of the index.

Sources: AGENTS.md:12-18, README.md:104-106

Architecture and Core Concepts

The system operates by comparing a "Source Snapshot" (the current state of the filesystem) against persisted "Coverage Records" in the database.

Selectors

A Selector defines a specific scope of session files. It is the fundamental unit used to request status, perform a sync, or constrain a search.

Selector Kind	Description
all	Every session file under a specific root directory.
cwd	Sessions associated with a specific Working Directory (cwd) under a root.
date_range	Sessions within a specific start/end date range.
cwd_date_range	A combination of a specific project directory and a timeframe.

Sources: src/types.ts:44-49, README.md:85-90

Coverage Freshness

The system categorizes the state of a requested scope into one of three freshness levels:

1. Fresh: The indexed data perfectly matches the source files (matching file count, fingerprint, and index version).
2. Stale: A coverage record exists for the scope, but the source files have changed (different fingerprint or count) or the index version is deprecated.
3. Missing: No coverage record exists that covers the requested scope.

Sources: src/status.ts:58-65, src/types.ts:75-78

Selector Implication Logic

The system uses "implication rules" to optimize sync operations. A broader selector can "cover" a narrower one. For example, a fresh all selector record for a root directory implies that any cwd or date_range request within that same root is also fresh.

Sources: src/status.ts:83-85, AGENTS.md:17-18

Data Model: The Coverage Table

Coverage state is persisted in a specialized SQLite table. This table stores the metadata required to validate the index against the filesystem.

The selector_key acts as a unique identifier for the scope, allowing the system to update records using an ON CONFLICT strategy during sync operations.

Sources: src/db/coverage-store.ts:10-44, skill-packages/cxs/references/json-schema.md:139-147

The Status Collection Workflow

The collectStatus function is the primary entry point for evaluating the state of the system. It aggregates filesystem metadata (Source Inventory) and database records.

This workflow provides the StatusSummary, which contains the requestedCoverage object if a selector was provided. This object is what tools and agents use to decide whether a sync command must be issued.

Sources: src/status.ts:10-33, src/status.ts:77-101

Index Synchronization and Coverage Updates

The sync command is the only operation that modifies coverage records. It follows a strict "provenance" model where coverage is only recorded if the sync is completed successfully.

1. Source Snapshot: Before syncing, the system takes a snapshot of the files matching the selector.
2. Transaction: If the sync is not in --best-effort mode, it wraps the index update and the coverage record update in a single database transaction.
3. Fingerprint Recording: The system records a source_fingerprint (based on file paths, sizes, and mtimes) to detect future "staleness".
4. Reconciliation: During a strict sync, the system removes indexed sessions that are no longer present in the source snapshot for that selector scope.

Sources: src/indexer.ts:44-110, README.md:112-118

Sync Result Schema

The SyncSummary includes a coverage field indicating if the record was written:

Field	Type	Description
written	boolean	True if the coverage record was successfully persisted.
reason	string	Explanation if not written (e.g., best_effort, not_written, source_unavailable).
sourceFingerprint	string	The fingerprint of the files at the time of sync.

Sources: src/types.ts:168-178, src/indexer.ts:252-263

Integration with the CLI and Agents

The system enforces a "coverage-first" workflow for agents and automated tools to ensure data reliability.

1. Check: Run cxs status --selector <JSON> --json.
2. Verify: Inspect requestedCoverage.recommendedAction.
3. Action: If "sync", run cxs sync --selector <JSON>. If "query", proceed to find or list.

Sources: AGENTS.md:6-10, skill-packages/cxs/references/cli-surface.md:10-18

Summary

The Coverage Tracking System provides cxs with a robust way to handle incremental and selective indexing. By decoupling the filesystem scanning (Source Inventory) from the data retrieval (Index Querying) and using persistent metadata to bridge the two, it minimizes unnecessary I/O while guaranteeing that search results are derived from an accurate representation of the local Codex session history.