Module contracts (//! docs)
Status: Open — Phase 1, no confirmation needed
Problem
Section titled “Problem”About 46% of source files (53 of 116) have //! orientation docs. The remaining 54% (63 files) give AI agents and contributors no orientation when they open the file — purpose, scope, and key invariants must be reverse-engineered from the code. This has barely improved since the original analysis.
Priority files (current largest / most central undocumented modules)
Section titled “Priority files (current largest / most central undocumented modules)”| File | Current LOC (May 2026) | Original LOC | Growth | Why urgent |
|---|---|---|---|---|
src/runtime/launch.rs | 7575 | ~5494 | +38% | Largest undocumented production file, jackin load critical path |
src/app/mod.rs | 2767 | ~1243 | +123% | CLI dispatch entry point — more than doubled |
src/app/context.rs | 1466 | ~1022 | +43% | Target resolution and workspace/agent context helpers |
src/instance/auth.rs | 2607 | ~2401 | +9% | Credential forwarding and auth provisioning logic |
src/isolation/materialize.rs | 2392 | ~2392 | — | Central mount-materialization flow with many invariants |
src/isolation/finalize.rs | 1819 | ~1819 | — | Foreground-session cleanup / preservation policy |
src/config/mod.rs | 1407 | ~1254 | +12% | Main config schema and auth/source policy |
src/workspace/mod.rs | 1056 | ~905 | +17% | Core workspace types and validation rules |
src/runtime/cleanup.rs | 687 | ~637 | +8% | Container/class cleanup semantics |
src/derived_image.rs | 983 | ~989 | — | Dockerfile generation, UID/GID remapping |
Notable new entries not in original list:
| File | Current LOC | Why urgent |
|---|---|---|
src/console/manager/state.rs | 2477 | Central state machine for the entire console — enums, modal definitions, workspace state. No //!. |
src/console/manager/input/save.rs | 2734 | Save flow, validation, commit planning. Grew from zero to 2734L. No //!. |
src/console/manager/input/global_mounts.rs | 1984 | Global mounts editor input handling. Grew from ~344L to 1984L. No //!. |
src/manifest/validate.rs | 1222 | Role manifest validation logic. No //!. |
- For each file, read the first 50 lines and the public item list.
- Write a
//!block at the top: purpose, scope claim, key invariants, what callers can assume. - Model on
src/env_model.rs(the 3-element exemplar: purpose + scope + history). - Do not add
///item-level docs in this pass — only//!module-level.
What a good //! block says
Section titled “What a good //! block says”- Purpose: What does this module do?
- Scope: What is it NOT responsible for? (crucial for AI agents to know where not to look)
- Key invariants: What must always be true when this module’s public functions return?
Caveats
Section titled “Caveats”Purely additive — no behavior change, no CI risk. Do before the behavioral specs since the spec presupposes the module has a stated contract.