Architecture

repository-harness has one Rust binary, harness, plus thin Bash and PowerShell bootstraps.

Product Boundary

consumer repository truth
  <- installed repository protocol
  <- safely maintained by harness

Harness installs navigation, working-memory structure, and decision boundaries. It does not own the consumer's product, runtime, orchestration, credentials, logs, fixtures, or validation commands.

Rust Dependency Direction

domain <- application <- infrastructure
                    <- interface

main.rs composes interface and infrastructure

• Domain types represent paths, hashes, provenance, merge outcomes, and reports without filesystem, process, serialization, or CLI dependencies.
• Application use cases depend on ports and own install, update, status, doctor, self-update, version, conflict, and recovery policy.
• Infrastructure implements embedded release content, hashing, locks, filesystem transactions, Git three-way merge, candidate download, checksum, and executable replacement.
• Interface parses commands and renders reports.
• main.rs is the composition root.

Architecture tests reject outward dependencies from inner layers.

Installation State

Consumer provenance lives under .harness-core/:

.harness-core/
├── manifest.json
├── base/
├── transaction.json          # only while an apply is pending
├── update/                   # only while conflict resolution is pending
└── update-candidate/         # retained verified candidate when required

The manifest and base contain only Harness-managed core state. They are not a task database or product-memory store.

Update Transaction

load installed base and candidate
  -> validate every managed path
  -> freeze current workspace inputs
  -> plan three-way changes
  -> stop and stage overlapping conflicts
  -> otherwise write journal and backups
  -> activate workspace files
  -> commit provenance last
  -> replace repository-local executable last

A later mutating command rolls back an interrupted apply before starting new work. Symlinks in managed paths, candidate paths, and executable replacement paths are rejected.

Conflict Ownership

Harness preserves BASE, LOCAL, UPSTREAM, and RESOLVED but does not choose policy. An agent may explain the difference; a human supplies direction when a material product choice remains. Continuation rejects conflict markers, candidate tampering, malformed sessions, and drift in any frozen managed file.

Trust Boundary

Updates resolve the exact harness-v* release pointer, download the matching platform binary and SHA-256 sidecar, require the binary-reported version to equal the pointer, and reject downgrades.

SHA-256 verifies bytes relative to the GitHub release. It is not an independent publisher-compromise trust root.

Consumer Application Guidance

Harness does not prescribe a generic application architecture. A consumer should document only its actual stack, domains, inputs, run commands, readiness, state ownership, logs, validation, and cleanup behavior.

Use docs/templates/application-runbook.md when a real application operation needs durable guidance. Do not invent commands, credentials, policies, or cleanup ownership to complete the template.