Chronos — Execution Intelligence for Coding Agents
Chronos is an agent-first runtime for observing, querying and verifying what a program actually did. The long-term goal is not to reproduce a human debugger UI: it is to give coding agents trustworthy execution evidence, causal context, runtime properties and adaptive instrumentation.
Estado operativo (2026-09-22, post-v0.8.0 release tag): REC-C0..REC-C7 constan cerrados documentalmente; M9 + M10 + M11 + OPS chapters CLOSED (4 chapters, see
docs/milestones/{M9,OPS,M11,M10}-CLOSE.md+M10-CLOSE-FINAL.md). Baselinemainenv0.8.0(peel9e3b928b) con 519/519 tests PASS (chronos-services) + 182/182 (chronos-domain) + 9/9 integration tests + clippy 0. OPS chapter cert-4 local-stdio + cert-3 linux-privileged. Honest limitations (per ADR-0004 §2.2 No Silent Lies): remote/multi-tenant OPS profile NOT IMPLEMENTED in this release; sandbox test 1M eventos deferred per env; GPG-signed tags not available in this env (annotated tags used as honest workaround). Consultar el puntero vivo y los tests del SHA actual antes de continuar.
Única entrada al trabajo nuevo: docs/ROADMAP.md → STATE.md → CERTIFICATION.md → UAT_CATALOG.md → JOURNAL.md.
Los roadmaps/backlogs obsoletos se preservan en docs/historico/, con punteros en sus antiguas rutas. El ledger de contratos y los ADR/UAT normativos permanecen activos. El resto de esta guía contiene contexto histórico del producto; el estado actual y la secuencia de trabajo se consultan en docs/ROADMAP.md y STATE.md.
Product principle
No Silent Lies. Agent-visible evidence must distinguish known, unknown, unsupported, incomplete, dropped/gapped, estimated and heuristic results. An empty/default success must never hide missing evidence.
What exists today
Evidence and replay foundations
chronos-log: append-only ExecutionLog foundation with monotonicEventSeq, segmented persistence, durable independent consumer cursors, explicit gaps and compaction.- invocation identity foundation with
SymbolId/InvocationIdand parent relationships. - query/index/store layers for historical execution analysis.
- runtime property, state-transition / Mutation-Lens and conservative causal-slice foundations.
Capture/adapters
- native C/C++/Rust tracing through ptrace-based components;
- eBPF components through aya;
- Python, Java, Go and browser adapters at varying capability depth;
- Go currently includes Delve-based debugging support.
Capability depth is not uniform across languages. The reconstruction roadmap requires a verified capability matrix and real UAT before a backend is presented as feature-equivalent to another.
Agent API
- MCP server with legacy tools plus newer v2 dispatcher/services;
chronos-servicescontains extracted application use cases;- canonical v2 API convergence and legacy deletion remain active reconstruction work.
Current architectural convergence
The active REC-C* sequence is:
- REC-C0 — restore the truth baseline, CI and machine compliance gates.
- REC-C1 — make ExecutionLog authoritative and make
events_readcursor/gap/completeness semantics truthful. - REC-C2 — delete legacy EventBus/query/tripwire delivery paths and dual truth.
- REC-C3 — close hexagonal dependency boundaries.
- REC-C4 — reduce SOLID/connascence debt and split broad adapter interfaces by capabilities.
- REC-C5 — converge on the small canonical Agent API and delete compatibility shims.
- REC-C6 — finish promised M1–M4 residuals, especially Go/Rust adaptive instrumentation.
- REC-C7 — strict reconstruction close gate; only then unblock official M6.
See the convergence plan for detailed deletion criteria and UAT.
Target architecture
Driving adapters
MCP / CLI / tests / future HTTP
|
v
Application services
Session / Probe / Observe / Property / Query / Diff
|
v
Domain + ports
Evidence identities, properties, capability contracts
^
|
Driven adapters
ExecutionLog/storage / native / eBPF / browser / OTLP / notifications
ExecutionLog is the target authoritative evidence stream. Query engines and other indexes are projections, not sources of truth.
Build
Prerequisites:
- Rust stable (see workspace toolchain/Cargo configuration);
- Linux capabilities/permissions as required by ptrace/eBPF tests;
- runtime-specific tools only for the adapter being exercised (for example Delve for Go integration paths).
cargo build -p chronos-mcp --release
Run MCP server:
./target/release/chronos-mcp --stdio
Verification
Default workspace verification:
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace -- --test-threads=1
Reconstruction architecture/spec gate:
python3 scripts/check_architecture_contracts.py
The active convergence CI additionally compiles all features:
cargo check --workspace --all-targets --all-features
REC-C7 strict close will require:
python3 scripts/check_architecture_contracts.py --strict-no-gaps
plus all mandatory sandbox UATs.
Roadmap after convergence
Once REC-C7 closes, the official reconstruction sequence resumes with:
- M6 — OpenTelemetry ingestion/correlation/export;
- M7 — semantic differential execution;
- M8 — counterexample shrinking/test intelligence completion;
- M9 — happens-before concurrency intelligence;
- M10 — Execution Explorer;
- M11 — additional language depth.
Development rule
New features must not bypass the canonical evidence path, add new legacy architecture, or claim a capability without executable UAT evidence. Architecture decisions that change semantics must update ADR/spec, reconstruction-contracts.toml and acceptance tests in the same cycle.
License
MIT