obsidian-vault/personal/projects/archive/virfield-release-cleanup-2026-10-16/docs/ARCHITECTURE.md

Архив исходника docs/ARCHITECTURE.md

Источник: Virfield, commit a1460d3372bdfbb5cb19d633d41dd5d3fb3164e6. Снимок перед релизной очисткой. Исторические утверждения ниже относятся к моменту исходной записи; актуальное состояние — в personal/projects/virfield.

# Architecture

Virfield is one modular Go application. Clients call `/api/v1`; the controller
and runtime adapters alone perform infrastructure effects. The maintained
candidate is on `codex/retire-lume-release-hardening`; `main` is not promoted.
Broker/Runner own execution semantics.

## Modules

| Module | Current responsibility |
|---|---|
| `cmd/virfieldd` | Config, single-owner locks, runtime wiring, API and shutdown |
| `internal/control` | Lease/image admission, durable phases, reconciliation, expiry and cleanup |
| `internal/store` | SQLite schema 10, atomic lease/job/event/request/template records, snapshots and retention; pre-migration snapshots protect state from older transfer/revalidation/toolchain-unaware executors |
| `internal/provider`, `internal/fleet` | Runtime seam and local Tart + SSH-node routing |
| `internal/tart`, `internal/tartimage` | Tart inventory/lifecycle and pinned Packer image adoption |
| `internal/baremetal`, `internal/nodeimage`, `internal/wol` | SSH physical nodes, node VM overlays, securing goldens and wake packets |
| `internal/guestssh`, `internal/qualify` | Account-specific credentials, host pins and guest qualification |
| `internal/catalog`, `internal/registry` | Version metadata and allowlisted registry metadata |
| `internal/httpapi`, `internal/web` | Bearer-authenticated API and embedded local console |
| `internal/client`, `internal/mcpadapter` | API-only CLI/SDK and MCP adapters with embedded documentation |
| `internal/appleauth`, `apple-browser` | Scoped native Apple website authentication |
| `internal/orchard` | Unaccepted Orchard candidate adapter |

The Lume backend, image factory, wrapper and build/install files are removed.
Legacy profile fields are read only for journal compatibility; Tart rejects old
IPSW recipes before reserving a build. The retired host service is independent
of the candidate and tracked in [Verification](VERIFICATION.md).

## Capacity and recovery

Acceptance commits reservations before returning. Capacity includes active
observed targets and unreleased durable reservations without double-counting.
Local Tart slots and secondary node slots are separate. Primary image builds and
portable exports reserve CPU/RAM/disk before dispatch, in the same budget as
workers; stopped ready goldens are excluded from active reservations. An unreachable node
remains visible; WoL-capable nodes may retain cached image inventory for waking.
A cached image is not proof of a currently reachable guest.

Unknown/stale primary inventory blocks admission. Unknown mutation outcomes keep
reservations and require operator inspection; a dispatch is never blindly
replayed. Stop and deletion are distinct effects. Capacity is freed only after
fresh absence is confirmed. Expiry revokes access even during backend failure.

Local Tart/node VM readiness requires running state, address, per-lease credential
isolation and authentication against a pinned host key. Physical host leases add
one caller key to the configured account and reserve its workspace. They do not
reset the host or kill workloads under the shared account. A physical host has one exclusive reservation independent of its VM slots.
Shared sleep holds are reference-counted; foreign holds are retained. VM cleanup
requires confirmed container removal before deleting overlays or releasing holds.

The approved VM account policy is standard `admin/admin`, without automatic
random account-password rotation. Standard-account candidates (`0f8bc20` and
later) implement this policy. Old golden credentials remain
unchanged; a new disposable clone can convert its known old account once. Distinct SSH keys and host
pins remain required; a standard console password is not a tenant-isolation
boundary. Existing keychain items, workspaces and goldens must be preserved.

Transient unverified inventory preserves the last verified ready endpoint and
existing streams, while new tunnels pause. Confirmed `vm_drift` instead moves a
lease to `needs_attention`. Journaled `lease_revalidate`/`vm_revalidate` can recover
a verified Tart/node VM in place only after original caller proof, fresh immutable
runtime identity and native readiness checks; it does not clone, rotate keys,
change workspace or extend expiry. Legacy records without a verified baseline
and physical-host leases fail safely. Operator resolution remains cleanup-only.

Bounded typed drift, backend and separate tunnel listener/stream diagnostic events
survive cleanup/restart under normal retention. Structured resource admission
reports full-growth CPU/RAM/storage/cache arithmetic and rechecks before dispatch;
a changed budget waits with the original job/key/deadline. Verified local Tart
golden transfer copies to a new storage/name, preserves sparse allocation and
private provenance, verifies hashes and registers atomically. See
[Operations](OPERATIONS.md) and the [five follow-ups](VIRFIELD-3-PLAN.md#operator-feedback-backlog)
for contracts and [Verification](VERIFICATION.md) for exact installed live scope.

## API boundary

REST scoped principals support `lease:own` and `image:build`; ownership checks
protect lease access. HTTP MCP currently uses the operator principal. These are
not v3 tenant grants. Loopback-only API deployment uses an explicit Host allowlist;
remote use requires an authenticated TLS proxy and accepted routing.

Clients never access SQLite or runtime storage. Do not add arbitrary host shell
or generic workload execution through this API. `/api/v1`, schema versions and
recipe identifiers are protocol contracts, not product marketing versions.

## Development rules

Use bounded contexts, safe error codes, atomic persist-before-effect transitions,
strict SSH host checking and private credential files. Never hold admission locks
across network effects. Run formatting, vet, race tests and release checks; test
failure behavior and provider routing. [Operations](OPERATIONS.md) owns commands;
[the 3.0 plan](VIRFIELD-3-PLAN.md) owns future architecture.