---
schema_version: 1
id: RAC-KTR5QS8J965S
type: roadmap
---
# RAC v0.8.0 — Explorer Foundation

## Status

Planned

## Context

The Explorer requirement defines an interactive product knowledge navigation
environment delivered as a Terminal User Interface (ADR-028).

The v0.7.x series delivered the platform Explorer depends on: a service layer
(`rac.services`), canonical artifact identity (v0.7.11), lookup and resolution
(v0.7.12), and metadata migration (v0.7.13). The `rac.explorer` package exists
as an intentionally empty consumer boundary.

Two gaps remain before an interactive surface can be built:

1. Consumers lack a single navigable representation of a RAC repository.
   Repository discovery should not be duplicated by each consumer.
2. CLI workflows are short-lived; an interactive consumer is long-lived and
   requires responsiveness, progress reporting, and repeated queries without
   blocking the interface.

This milestone closes those gaps and stands up the Explorer application shell.

## Outcomes

- RAC Core exposes a first-class repository model that any consumer can
  navigate without scanning files.
- Core operations are safe for long-lived interactive consumers.
- `rac explorer` launches a Textual-based TUI shell that consumes RAC services
  through a dedicated adapter layer and recovers gracefully from failures.

## Initiatives

### Initiative 1 — Repository Model

Introduce first-class repository objects in RAC Core:

```text
Repository
  contains Artifacts
  connected by Relationships
  described by Diagnostics
```

- A `Repository` object exposes indexed artifacts, validation, relationships,
  and portfolio analysis through the existing services.
- A common artifact representation covers all supported types (requirement,
  decision, roadmap, prompt, design).
- Relationships and diagnostics are shared model objects, reused by
  validation, relationship analysis, and portfolio health.
- Repository models contain no CLI or TUI concepts; consumers shall not
  implement their own repository scanning.

### Initiative 2 — Interactive Runtime Readiness

Prepare Core operations for long-lived consumers:

- Represent long-running work (repository scan, validation, relationship
  analysis, ingestion) through a consistent operation interface.
- Operations may expose progress callbacks and support cancellation where
  practical.
- Support refreshing repository state without a full reload where possible.
- Validate behaviour against repositories containing 1000+ artifacts.

Core shall not assume synchronous terminal execution, and this milestone does
not require an async rewrite of Core.

### Initiative 3 — Textual Application Foundation

Introduce the Explorer TUI application:

```text
RAC Core  →  Explorer Adapter  →  Textual UI
```

Launched as:

```bash
rac explorer
```

### Initiative 4 — Explorer Adapter Layer

Introduce a dedicated boundary between RAC Core and the UI. The adapter
shall:

- invoke RAC services
- translate Core models into UI state
- own no repository intelligence
- prevent widgets from depending on Core internals

### Initiative 5 — Non-Blocking Execution

Explorer shall never execute expensive Core operations directly in UI
handlers. Repository loading, validation, relationship analysis, and
portfolio calculation execute through Textual workers.

### Initiative 6 — Recoverable Errors

Core failures surface as recoverable Explorer states. Failures shall not
crash the interface.

## Constraints

- Explorer consumes Core services only; no business logic exists exclusively
  within Explorer (ADR-015).
- Explorer operates entirely within a terminal, keyboard first, with no mouse
  required (ADR-028, DESIGN-visual-system).
- Meaning never depends on colour alone; limited-colour environments and
  remote sessions are supported (DESIGN-visual-system).
- Explorer includes adapter tests, screen tests, and Core isolation tests,
  organized as service batteries (ADR-027).

## Non-Goals

- Artifact editing or authoring (ADR-024)
- New repository intelligence
- Background daemons or hosted services
- Navigation, health, or recommendation experiences (delivered by v0.8.1+)

## Implementation Contract

The following decisions are pinned for v0.8.0.

### Module Locations

- The repository model lives in `rac/services/repository.py`. It composes
  existing services (index, validation, relationships, portfolio), and the
  service layer depends on `rac.core`, never the reverse — so the model
  cannot live under `rac/core/`.
- Operation primitives (progress, cancellation) live in
  `rac/core/operations.py`. They are pure primitives with no CLI or TUI
  concepts, usable by core traversal and services alike.
- Explorer layout: `rac/explorer/launch.py` (entry point and lazy import
  seam), `adapter.py` (service boundary), `state.py` (frozen UI-state
  dataclasses), `app.py` (Textual application), `screens/`, `widgets/`.
  Only `app.py`, `screens/`, and `widgets/` may import Textual.

### Public APIs

- `rac.services.repository`: `Repository`, `Artifact`, `Diagnostic`,
  `load_repository(directory, *, recursive=True, on_progress=None,
  cancel=None)`.
- `rac.services.relationships`: `Relationship`,
  `relationships_from_corpus(entries)`.
- `rac.core.operations`: `Progress`, `ProgressCallback`, `CancelToken`
  (protocol), `CancellationToken`, `OperationCancelled`, `checkpoint`.
- `rac.core.corpus`: `collect_corpus(directory, *, recursive=True,
  on_progress=None, cancel=None)` — the single-walk snapshot that
  `load_repository` and future incremental refresh build on.
- `rac.explorer.launch`: `run_explorer`, `ExplorerUnavailable`.
- `rac.explorer.adapter`: `ExplorerAdapter`.

### Dependencies

- Textual ships as the optional extra `explorer` (`textual>=1.0`); base
  dependencies are unchanged.
- The dev extra gains `textual` and `pytest-asyncio` so explorer batteries
  run in CI on all supported Python versions.

### CLI and Exit Codes

`rac explorer [directory]` defaults to the current directory, matching
`rac index`, `rac resolve`, and `rac find`.

| Outcome | Exit code |
| --- | --- |
| User quits the Explorer session | `0` |
| Usage error (not a directory, explorer extra not installed) | `2` |

- A missing extra prints an install hint
  (`pip install 'requirements-as-code[explorer]'`) on stderr.
- Core failures during a session surface as recoverable Explorer states,
  never exit codes.
- No new JSON contract: the repository model types carry no `to_dict`,
  and no existing CLI or JSON output changes (ADR-007).

### v0.8.0 Shell Contents

The shell renders exactly three states — loading with live progress, a
repository summary (artifact counts by type, relationship totals, broken
references, diagnostics counts, health score), and a recoverable error
panel — with `q` (quit) and `r` (reload) bindings. Navigation, health
detail, and recommendations remain v0.8.1+ scope.

### Deferrals

- Refresh re-runs the single-walk load off the UI thread; incremental
  refresh is deferred, with the corpus snapshot as its enabler.
- Core stays synchronous; Explorer uses Textual thread workers.
- No golden tests cover Explorer output (terminal-size dependent).

### Testing

- New CI batteries `repository` and `explorer`; every new test file joins
  exactly one battery (ADR-027).
- Explorer screens are tested headlessly through Textual's `App.run_test`
  pilot; the missing-extra path is tested through a module-level import
  seam in `launch.py`.
- An AST-based isolation battery asserts `rac.core` and `rac.services`
  never import `textual` or `rac.explorer`, and widgets never import core
  internals.
- The 1000+ artifact target is validated against a generated corpus
  fixture, asserting correctness, monotonic progress, and early
  cancellation.

## Success Measures

- `rac explorer` opens a repository and renders an application shell without
  blocking on Core operations.
- Explorer navigation in later milestones can be implemented entirely against
  the repository model APIs.
- Explorer remains responsive on repositories of at least 1000 artifacts.
- All existing CLI behaviour and JSON contracts remain unchanged (ADR-007).

## Related Decisions

- ADR-015
- ADR-028
- ADR-008
- ADR-027

## Related Designs

- explorer-visual-system

## Related Requirements

- rac-product-knowledge-navigator-explorer

## Dependencies

- v0.7.x service layer and repository index
- v0.7.11 hybrid metadata and system-assigned identity
- v0.7.12 artifact lookup and resolution
- v0.7.13 metadata migration
