# Archiva v2 Rust Architecture

Status: current implementation record, updated 2026-07-02.

Archiva v2 is a std-only Rust implementation. The repository no longer carries
the old TypeScript implementation, TypeScript tests, or TypeScript migration
harnesses. npm/pnpm support is limited to native-package selection and install
glue; Homebrew support builds the Rust crate directly.

## Product Shape

- One native CLI binary named `archiva`.
- No runtime service, daemon, database, hosted API, or account.
- npm and pnpm are distribution wrappers only; after installation, `archiva`
  runs as a native binary.
- Homebrew builds from source through the formula in
  `packaging/homebrew/Formula/archiva.rb`.
- Decision storage remains repository-local in `.decisions/`.
- MCP is served over stdio with manually implemented JSON-RPC.

## Crate And Module Layout

- `src/main.rs`: process entrypoint and panic/error boundary.
- `src/cli.rs`: command parsing, help text, positional option compatibility,
  and command dispatch.
- `src/mcp.rs`: newline-delimited JSON-RPC MCP server and tool dispatch.
- `src/core/anchor.rs`: TypeScript/JavaScript, Rust, and C/C++ source anchor
  extraction, complexity, ranges, and parser diagnostics.
- `src/core/decision.rs`: write-decision input validation, supersession,
  history, and decision record construction.
- `src/core/dlog.rs`: schema-1 `.dlog` parsing and writing.
- `src/core/dmap.rs`: `.dmap` parsing and writing.
- `src/core/storage.rs`: transactional dlog/dmap writes, locking, stale lock
  recovery, and derivative map regeneration.
- `src/core/project.rs`: project-level workflows for init, why, history, lint,
  status, ghost check, and post-tool-use.
- `src/core/git.rs`: native Git object reader for `HEAD:<path>` content across
  SHA-1 and SHA-256 repositories.
- `src/core/json.rs`: manual JSON parsing/writing for CLI, MCP, and settings.
- `src/core/yaml.rs`: manual YAML subset used by Archiva decision logs.
- `src/core/diff.rs`: line-range shifting and reanchor support.
- `src/core/fingerprint.rs`: deterministic code normalization and
  fingerprinting.
- `src/core/paths.rs`: portable project-relative path validation and
  normalization.
- `src/core/fs.rs`: filesystem primitives, atomic write helpers, locks, and
  traversal.
- `src/core/settings.rs`: Claude settings merge support.

## Runtime Flow

Commands enter through `cli.rs` or `mcp.rs` and delegate to `core::project`
operations. Project operations resolve repository-relative paths, load `.dlog`
and `.dmap` files, extract anchors from source files, update decision records,
and write `.dlog` as the source of truth. `.dmap` files are compact derivatives
and may be regenerated from `.dlog`.

Write paths use a decision-base lock before mutating `.dlog` or `.dmap`.
Readers repair missing or corrupt derivative `.dmap` files from valid `.dlog`
data where that recovery is intentionally documented as hardening behavior.

The native Git reader is request scoped. A single `GitObjectReadContext` caches
pack-index validations and sorted offsets during one `HEAD:<path>` read, then
is discarded so repository changes between commands are not hidden by global
state.

## Source Language Strategy

Archiva is implemented in Rust, but it can attach decisions to multiple source
languages:

- TypeScript and JavaScript source anchors.
- Rust source anchors.
- C and C++ source anchors.

TypeScript/JavaScript are supported input languages, not implementation
dependencies. Adding a new source language means extending the file-extension
dispatch in `src/core/project.rs` and the extractor in `src/core/anchor.rs`.

## Packaging Strategy

npm/pnpm packaging uses small `.mjs` lifecycle helpers because npm install
scripts and platform package selection run in Node. Those helpers stage the
root meta package, validate native package metadata, select the host native
package at install time, and smoke test the installed binary. They are not the
Archiva runtime.

Homebrew packaging uses a Ruby formula that builds the Rust crate with
Homebrew's Cargo helper and tests the installed binary by running init,
write-decision, why, status, and lint.

## Testing And Validation Strategy

Local and CI validation layers:

- Rust unit and integration tests.
- Rust property soak for serialization and diff behavior.
- Panic-fuzz soak over parsers and extractors.
- Native package smoke for direct, meta, root-tarball, and published package
  paths.
- Cross-platform GitHub Actions builds/tests and native package smokes for
  Linux, macOS, Windows, glibc, musl, x64, and arm64 where runners are
  configured.
- v2 audit checks that the repository remains Rust-native, package scripts stay
  minimal, workflows avoid removed migration harnesses, and Homebrew packaging
  remains present.

## Release Gates

Publishing native packages requires:

- version consistency between `package.json`, `Cargo.toml`, and release tag;
- `npm run check`;
- package build and package smoke;
- Rust property soak;
- Rust panic-fuzz soak;
- per-target native build and deep package smoke;
- root meta package publish after native packages are available;
- post-publish install smoke across supported glibc, musl, macOS, and Windows
  targets.

## Future Extension Points

- Add source-language extractors behind explicit file-extension dispatch in
  `src/core/anchor.rs` and `src/core/project.rs`.
- Add MCP tools by extending the manual `tools/list` schema and `tools/call`
  dispatcher in `src/mcp.rs`.
- Add package targets through `tools/native-targets.mjs`, then let metadata
  validation enforce package, workflow, and lockfile drift.
- Add richer release evidence as Rust tests or Rust examples, not by reviving
  the removed TypeScript migration harness.

## Remaining Architecture Gaps

No architecture gap remains for the Rust-native cleanup objective.