empeira 0.1.0.pre.alpha.1

data/docs/addons.md

@@ -0,0 +1,331 @@
+# Standalone Git addons (API 1)
+
+Empeira remains a local Puppet/OpenVox test environment. Addons expose independent
+helper programs through its CLI, for example a converter, data synchronization
+tool or Git hook installer. Core does not import their Ruby classes or know their
+functionality. There is no plugin runtime, registry, package manager, dependency
+installer or lifecycle hook. No production helper tools ship with Empeira.
+
+## Companion addons
+
+These independently maintained addons can be installed through Empeira but are
+not bundled with the core application. See each repository for installation and
+usage details.
+
+| Addon | Description |
+| --- | --- |
+| [Convert](https://github.com/c8m6/empeira-addon-convert) | Convert YAML, JSON, XML, Java Properties and Puppet hashes, and generate EPP templates with typed defaults. |
+| [Pre-Commit](https://github.com/c8m6/empeira-addon-pre-commit) | Manage Git pre-commit hooks for control and Hiera repositories using locally built Docker or Podman images. |
+| [Sync](https://github.com/c8m6/empeira-addon-sync) | Synchronize configured files and directories with host rsync, using source and destination to define direction. |
+
+## Configuration and commands
+
+Declare addons in the existing effective configuration, normally the control
+repository's `.empeira.yaml`:
+
+```yaml
+addons:
+  converter:
+    git: https://github.com/example/empeira-converter.git
+    ref: v1.2.0
+    config:
+      output_format: yaml
+      paths: [data, defaults]
+  git-hooks:
+    git: git@example.org:team/empeira-git-hooks.git
+    ref: main
+```
+
+Each entry requires `git` and `ref` and may optionally contain `config`, a mapping
+of addon-specific settings. The addon itself interprets those settings; the
+`converter` example above is illustrative, not a built-in Empeira option.
+Config keys use lowercase letters, digits and underscores, starting with a letter;
+values may be nested mappings, arrays or simple YAML scalars. Do not put secrets
+in addon config: it is visible in project configuration and the addon's environment.
+`git` and `ref` must be nonempty strings after merging. Names start with a lowercase letter and contain lowercase letters,
+digits, underscores or hyphens, up to 63 characters. Built-in defaults contain
+`addons: {}`. Mappings deep-merge and project overrides may replace just a ref.
+Normal defaults/project/user/CLI precedence and validation remain in force.
+The existing user preference file does **not** accept addon definitions. There is
+no additional user configuration file and no executable or completion settings
+in Empeira configuration.
+
+```console
+empeira addons list
+empeira addons info converter
+empeira addons sync
+empeira addons update
+empeira addon converter convert input.xml output.json
+```
+
+`addons list` inspects configured names and reports missing, installed or invalid
+local installations. `addons info NAME` shows the source, configured ref, resolved
+commit, absolute installation path and complete validated manifest. Neither
+command downloads anything. Invalid installations are reported explicitly.
+
+`addons sync` and `addons update` synchronize all configured sources and refs.
+Both use the same explicit refresh semantics as `update modules`: branches and
+moved tags follow the fetched source; a commit reference selects that commit.
+They attempt every configured addon and return failure if any cannot be installed.
+Already published versions survive failed updates. They need host Git and network
+access to the configured sources, but no container engine, server, node, network,
+proxy or infrastructure inventory.
+
+`addon NAME ...` runs exactly one executable. Everything after NAME, including
+`--help`, `--version`, `--`, empty arguments and shell metacharacters, is passed
+unchanged. Core options belong **before** `addon`, for example
+`empeira --container-engine docker addon example ...`. Manifest commands describe
+completion; they do not restrict the executable's argument parser or validate its
+arguments. Singular `addon` executes; plural `addons` manages.
+
+Direct execution automatically installs a missing ref. Subsequent executions use
+the locally installed ref without network freshness checks. `up` also installs
+missing refs, after the Puppet infrastructure is ready. An addon failure makes
+`up` return failure with a separate addon diagnostic; the successfully prepared
+Puppet infrastructure remains usable. Invalid addon manifests do not affect Core
+commands. Invalid Empeira configuration still follows normal configuration errors.
+`update images`, `update modules` and the currently unavailable `update all` retain
+their existing behavior; addon updates use `addons update`.
+
+## Git references and storage
+
+Empeira reuses the Puppetfile host Git acquisition boundary, including native
+SSH configuration, agents, HTTPS credential helpers and sanitized Git diagnostics.
+Sources support HTTP(S), SSH URLs and SSH scp syntax. Do not embed HTTP credentials,
+URL query strings or fragments; authentication belongs to host Git. Local fixture
+servers are used in tests, without external Git services.
+
+`ref` uses the Puppetfile/r10k native Git resolution, `ref^{commit}`: branch, tag,
+full or unambiguous abbreviated commit, or `HEAD`. It is not a semantic version
+constraint. Unknown refs fail. API 1 requires an explicit ref (`HEAD` is the
+explicit equivalent of Puppetfile's default). It does not support Forge versions
+or Puppetfile Ruby symbols such as `:control_branch`.
+
+Data lives under `~/.empeira/addons/`, resolved through the existing platform home
+abstraction on Linux, macOS and WSL2. Each source has a SHA-256 namespace containing
+a bare host mirror, immutable commit directories, hashed reference pointers and a
+stable lock file. Equal source strings and commits can be reused across names,
+refs and workspaces. Different URLs never collide simply because their addon names
+match. Different versions remain available in parallel. No cache eviction is
+automatic; do not remove a cache while an addon or synchronization is using it.
+
+Acquisition and publication use an exclusive per-source lock. New mirrors and
+revisions are staged privately, checked and atomically renamed. A reference is
+published only after manifest and executable validation. Interrupted staging
+directories are never considered installed. The control repository is not used as
+an installation destination and its tracked files are not modified.
+If the configured user home or a cache symlink would put the cache inside the
+control repository, installation is rejected before writing there.
+
+Snapshots are materialized by native Git with a disposable index, without a `.git`
+working directory. Local checkout ignores inherited Git configuration and disables
+hooks, so filters, submodules, addon entrypoints and install scripts are not run.
+Tracked files keep their Git content and executable bits. Addons must ship
+everything needed for execution or document prerequisites the user installs
+separately.
+
+## Manifest contract
+
+Every addon repository has exactly one root-level `empeira-addon.yaml` and one
+executable entrypoint:
+
+```text
+empeira-addon-example/
+├── empeira-addon.yaml
+├── bin/
+│   └── example
+└── README.md
+```
+
+```yaml
+schema: 1
+description: Convert configuration files
+executable: bin/example
+commands:
+  convert:
+    description: Convert a file
+    arguments:
+      - name: input
+        completion: file
+      - name: output
+        completion: file
+    options:
+      --format:
+        description: Output format
+        completion: enum
+        values: [yaml, text]
+      --input:
+        completion: file
+      --directory:
+        completion: directory
+      --verbose:
+        completion: none
+  validate:
+    description: Validate input
+    arguments:
+      - name: input
+        completion: file
+```
+
+Required root fields are `schema` (integer 1), `description`, `executable` and
+`commands` (a mapping, possibly empty). Every command requires a description;
+`arguments` (ordered array) and `options` (mapping) are optional. Arguments require
+`name` and `completion`. Option names are explicit `-x` or `--long-name` spellings,
+with optional descriptions. An option has one value when its completion is `file`,
+`directory` or `enum`; `none` declares a flag without a value. To provide short and
+long forms, declare each spelling. `enum` requires a nonempty string list `values`;
+other types must not have `values`. `none` on an argument disables its completion.
+Names and descriptions cannot contain control characters. Unknown fields, YAML
+object tags, aliases, duplicate keys and unsupported schema versions are rejected.
+
+There is no nested command framework, dynamic completion, option bundling or
+variadic argument schema. The program may implement its own richer CLI; Empeira
+offers completion only for the declared interface.
+
+The entrypoint must be a regular executable inside the addon directory. Absolute
+paths, `.`/`..` path components, and symlinks escaping that directory are rejected,
+including an escaping manifest symlink. Keep the executable bit in Git. Scripts
+need a shebang naming an installed interpreter; native binaries must be compatible
+with the host. Empeira does not invoke a shell command string or interpolate argv.
+
+## Environment API
+
+Configuration is freshly loaded and merged for every invocation. Empeira exports
+its approved fields as `EMPEIRA_CONFIG_*`, without JSON export or temporary
+configuration files. Keys become uppercase, with punctuation replaced by `_`.
+
+| Value | Export |
+| --- | --- |
+| String | Original value, including an empty string |
+| Integer/float | String representation |
+| Boolean | `true` / `false` |
+| Mapping | Recursively flattened keys |
+| Array | `_COUNT` and zero-based indexed elements |
+| Empty array | `_COUNT=0` |
+| Null | No variable |
+
+Array elements can be mappings, arrays or scalars. For example:
+
+```yaml
+proxy:
+  enabled: true
+  global: [forge.puppet.com, github.com]
+server:
+  mounts:
+    - source: /home/user/data
+      target: /mnt/data
+      readonly: true
+```
+
+produces `EMPEIRA_CONFIG_PROXY_ENABLED=true`,
+`EMPEIRA_CONFIG_PROXY_GLOBAL_COUNT=2`,
+`EMPEIRA_CONFIG_PROXY_GLOBAL_0=forge.puppet.com`,
+`EMPEIRA_CONFIG_PROXY_GLOBAL_1=github.com`,
+`EMPEIRA_CONFIG_SERVER_MOUNTS_COUNT=1`, and the variables
+`EMPEIRA_CONFIG_SERVER_MOUNTS_0_SOURCE`, `_TARGET`, `_READONLY`.
+
+### Per-addon configuration
+
+Only the selected addon's `config` mapping is additionally exported as
+`EMPEIRA_ADDON_CONFIG_*`. It uses the same flattening rules as the effective
+configuration above. For the example, `converter` receives:
+
+```text
+EMPEIRA_ADDON_CONFIG_OUTPUT_FORMAT=yaml
+EMPEIRA_ADDON_CONFIG_PATHS_COUNT=2
+EMPEIRA_ADDON_CONFIG_PATHS_0=data
+EMPEIRA_ADDON_CONFIG_PATHS_1=defaults
+```
+
+Other addons' `config` values are **not** included in the general
+`EMPEIRA_CONFIG_*` export or the selected addon's export. The optional
+`config` mapping deep-merges like other project mappings; arrays replace.
+No new addon API version, configuration file or install hook is needed.
+
+Runtime context is separate:
+
+| Variable | Meaning |
+| --- | --- |
+| `EMPEIRA_VERSION` | Installed build version, or `development` |
+| `EMPEIRA_ADDON_API_VERSION` | `1` |
+| `EMPEIRA_ADDON_NAME` | Configured logical name |
+| `EMPEIRA_ADDON_VERSION` | Configured Git ref |
+| `EMPEIRA_ADDON_PATH` | Absolute resolved commit snapshot directory |
+| `EMPEIRA_WORKSPACE` | Absolute canonical workspace project directory |
+| `EMPEIRA_CONTROL_REPO` | Absolute canonical control repository root |
+
+Workspace means the existing project identity, not a running lab. Project-bound
+CLI calls require the existing Git-root `.empeira.yaml` marker, including when
+invoked from a subdirectory. No workspace infrastructure is created for an addon.
+Context variables are omitted if a caller has no such context.
+
+The schema explicitly excludes `vm.console.root_password`, `eyaml.private_key`,
+`browser.start_url`, `server.runtime.startup.arguments`,
+`puppetdb.runtime.java_arguments`, `puppetdb.runtime.main_arguments`, and each
+additional container's `environment`, `command` and `configuration.content`.
+These include opaque content which may contain secrets under ordinary names; this
+is not a suspicious-key-name filter. Other validated configuration is exported.
+No private key files are read for export.
+
+Normal inherited user variables remain available. All inherited `EMPEIRA_*` names
+are cleared before the authoritative configuration and runtime values are set, so
+stale, forged or excluded values cannot leak through that namespace. Environment
+plus argv size is checked against the OS limit, with pointer/headroom allowance
+and a conservative 128-KiB per-string limit. Oversized data or null bytes fail
+before execution without printing values; there is no file-based fallback.
+
+## Bash completion
+
+Use the existing registration:
+
+```bash
+source <(empeira completion bash)
+```
+
+It completes `addons list/info/sync/update`, names after `addons info` and `addon`,
+then local manifest commands, options and enum values. Positional and option
+`file`/`directory` arguments use native Bash filename completion, including relative
+and absolute paths, subdirectories, spaces and shell punctuation. `--option=value`
+is supported as well as a separate value. `--` ends option parsing.
+
+Completion reads only configuration and installed manifests. It never fetches Git
+sources or calls an addon executable. A configured missing addon name is offered,
+but its commands become available only after installation. Missing or invalid
+manifests produce no addon candidates and leave Core completion usable. There is
+no additional completion executable, script to install or cached file list.
+
+## Development, trust and troubleshooting
+
+The complete [minimal fixture](../spec/fixtures/addon/README.md) can be copied into
+a separate Git repository. It prints arguments and demonstrates all completion
+types. It does not implement a production converter, data sync or Git hook tool.
+Keep runtime dependencies and platform instructions in the addon's README. An
+addon can read the environment in any language and uses the caller's current
+directory and inherited stdin/stdout/stderr. Terminal colors and interactive input
+remain available. The CLI process is replaced by the executable: exit statuses and
+signal termination remain native, without an intermediary process swallowing them.
+Start failures distinguish 126 (not executable) and 127 (entrypoint/interpreter
+not found); actual addon failure exits are returned unchanged.
+
+Addons run as the invoking user. They are trusted local programs, **not sandboxed**.
+The export filter limits what Core supplies; it cannot prevent a trusted program
+from reading files or credentials already accessible to the user. Review sources
+before execution and prefer immutable commits for reproducibility. Git source
+authentication continues to use the user's existing Git/SSH tools; credentials
+are not copied into an addon cache by Empeira. Git diagnostics use Core redaction;
+addon stdout/stderr are direct program output and remain the addon's responsibility.
+
+Supported platforms are native Linux, native macOS and Linux in WSL2. Native
+Windows is unsupported. Host Git, the normal Empeira Ruby requirements and any
+addon interpreter/binary prerequisites must be installed. No Docker or Podman is
+needed to install, manage or execute addons.
+
+For a missing addon, check the effective `addons` mapping and run `addons sync`.
+For an unknown ref, verify it with the source owner and correct `ref`. For Git
+authentication failures, use the normal host Git/SSH configuration. For a missing
+or invalid manifest, fix it upstream and update to a valid revision. For 126/127,
+check the executable bit, shebang, interpreter and host architecture. If a cache
+is incomplete, stop users of that source and remove only its affected source
+namespace before synchronizing again; never delete a live lock as recovery.
+For missing command completion, inspect `addons info NAME` and source the current
+Bash completion again after an Empeira upgrade.

data/docs/architecture.md

@@ -0,0 +1,277 @@
+# Architecture
+
+Empeira has one control-plane lifecycle and interchangeable infrastructure adapters.
+The CLI presents output and calls `Application`; the core loads without Thor.
+`Application` composes a canonical Git project, immutable effective configuration,
+workspace identity, platform locations and the central execution runner. Constructing
+it does not start infrastructure. Registries expose names without constructing providers.
+The loader validates personal SSH preferences separately from the effective project
+configuration. `Application` passes them only to the node-service login resolver;
+that resolver selects user/identity fields for interactive SSH before dispatching
+to the recorded provider. Internal VM transport retains its managed credentials.
+A shared hostname-pattern helper supplies matching semantics without coupling SSH
+preferences to proxy destination policy. Personal login values never enter context
+configuration, definitions, fingerprints or inventory.
+
+```mermaid
+flowchart TD
+    CLI[CLI and completion] --> App[Application and context]
+    App --> Config[Configuration and version gate]
+    App --> State[Inventory and mutation lock]
+    App --> Plane[Control-plane lifecycle]
+    App --> Nodes[Node lifecycle]
+    Plane --> Runtime[Docker / Podman]
+    Nodes --> Container[Container provider]
+    Nodes --> VM[VM provider]
+    Container --> Runtime
+    VM --> QEMU[QEMU: KVM / HVF]
+    VM --> Images[Immutable image cache and QCOW2 overlays]
+    VM --> Peer[Replaceable peer-network backend]
+    Peer --> Runtime
+    Runtime --> Runner[Execution runner]
+    QEMU --> Runner
+```
+
+## Software and provider boundaries
+
+| Boundary | Responsibility |
+| --- | --- |
+| Configuration | Safe YAML, deep merge, complete-path validation and permitted overrides |
+| Platform | Host capabilities, architecture, home, state/cache locations and DNS discovery |
+| Container runtime | Owned OCI containers, networks, volumes, images and runtime transport |
+| Server runtime | Validated startup, paths and semantic environment mapping |
+| Node provider | Common identity, bootstrap, enrollment and lifecycle for `container` or `vm` |
+| VM engine | QEMU process, acceleration, console and overlay lifecycle |
+| Image source | Upstream metadata, integrity verification and immutable VM base images |
+| Execution | Argument-array processes, timeouts, streaming and diagnostic redaction |
+| Addons | Declarative manifests, user Git snapshots and standalone process handoff; no infrastructure dependency |
+
+VM interface rules resolve through Configuration using the shared hostname glob
+matcher. The VM provider invokes the guest interface reconciler through its existing
+VirtIO management channel after agent installation and on start/up. Device intent
+and recovery definitions live in the locked node inventory;
+atomically assigned locally administered MAC addresses and verified aliases bind
+devices to workspace/node ownership. Guest observations establish device type,
+parent, address and routes before mutation. The VM engine,
+QEMU NIC topology, peer adapters and gateway policy remain independent of these
+guest-only devices. See [interface lifecycle](nodes.md#additional-vm-interface-lifecycle).
+
+OpenVox is the default software. `images.server`, `images.puppetdb` and
+`images.postgres` select OCI images independently. `server.runtime` and
+`puppetdb.runtime` describe compatible startup contracts without classifying image
+names. Agent selection is independent of those images. Container recipes add base
+tools. A shared agent acquisition component resolves native source metadata in an
+owned, short-lived runtime helper, validates the package and publishes it atomically
+in the user cache. Cache identity includes the native version, target and source.
+Valid hits use local integrity and configured checksum checks and work offline,
+including artifacts from authenticated sources. HTTP authentication and login occur
+only during acquisition. Both node providers upload the same host artifact and
+install it locally through native guest package managers. Bootstrap verifies cleanup
+and enrolls certificates before Puppet runs. Cloud-Init is a VM delivery mechanism only.
+VM disk preparation creates and resizes a private QCOW2 overlay, verifies its exact
+backing image and configured virtual capacity, then publishes it atomically. The
+immutable base is unchanged. First-boot readiness observes the actual mounted root
+partition and filesystem after cloud-init growth, before managed package bootstrap.
+Resume and workspace reconciliation preserve existing disk capacities.
+
+Both providers reconcile normal guest proxy intent in the existing node inventory
+after bootstrap cleanup. The shared reconciler uses the public control-plane
+proxy environment, owned APT files and a bounded DNF block; provider transports
+only execute guest operations. Managed Puppet receives explicit `env` arguments
+inside the root guest command, preserving the runtime proxy policy.
+
+Interactive tool PATH uses the same provider guest transports and node inventory.
+Its startup fragments apply only to interactive Bash, with a small owned block
+in the distribution's global initializer. Personal dotfiles and non-interactive
+process environments stay under their existing owners.
+
+VMs seed a Python 3 standard-library execution adapter through Cloud-Init, before
+project scripts and package bootstrap. The private VirtIO-Serial channel has no
+network listener or guest account authentication. A systemd service runs with
+numeric UID/GID 0, independently of root shadow, PAM, NSS login policy, sudoers and
+system SSH. Guest commands use argument arrays and owned process groups; stdout
+and stderr stream in bounded frames without truncation. Timeouts, interrupts and
+host disconnects terminate those groups. Binary uploads are SHA-256 verified,
+staged privately and atomically installed in the real guest filesystem.
+
+The QEMU monitor verifies workspace/node/instance identity before management.
+A 0700 host directory and 0600 Unix socket restrict access; recorded device/inode
+identity rejects replaced sockets. Sessions also verify the instance identity and
+operation ID. No management NIC, host port, additional privileged host helper or
+SSH credentials are needed. Existing workspace locks and VM session guards apply.
+`node puppet` uses this targeted path without server readiness or full guest
+reconciliation.
+
+The user SSH adapter connects directly to the guest's peer IP through the owned
+peer attachment and its isolated TCP client, independently of management. Personal
+user/key/port resolution
+applies only to `node ssh`; the default guest port is 22. The locked `empeira`
+system account and `/var/lib/empeira` home are seeded once for regular SSH, without
+sudo. Puppet may remove or change them. Empeira never unlocks root or restores
+Puppet-managed authentication. Unsupported VM layouts require explicit recreation;
+there is no migration, fallback transport or automatic resource deletion.
+
+Nodes share lifecycle contracts: create rejects an existing name, stop preserves
+state, start resumes it, and destroy removes owned state. Already satisfied lifecycle
+operations return `changed: false`; absent start/stop and ownership conflicts fail.
+Names are unique across both providers under the shared workspace transaction.
+The structured Empeira classification fact contains `facts.empeira.provider` and
+the fixed `facts.empeira.hierarchy: empeira` Hiera selector.
+
+## Persistent state and ownership
+
+| Location | Linux / WSL2 | macOS |
+| --- | --- | --- |
+| Cache | `$XDG_CACHE_HOME/empeira` or `~/.cache/empeira` | `~/Library/Caches/empeira` |
+| State | `$XDG_STATE_HOME/empeira` or `~/.local/state/empeira` | `~/Library/Application Support/empeira` |
+| Temporary work | Ruby `Dir.tmpdir` | Ruby `Dir.tmpdir` |
+
+Relative XDG locations are ignored. Workspace identity hashes the canonical checkout
+and user-home paths; moving a checkout changes its identity. Destroy needed resources
+before moving it, or preserve its original path for cleanup.
+
+`workspaces/ID/infrastructure.json` records the owning runtime, logical resources,
+observed backend IDs, service/volume/node inventories, peer allocation and definition
+fingerprints. Only the current schema is accepted. Atomic mode-0600 writes use
+flush/fsync and rename. Invalid or unreadable state fails closed.
+
+Resources carry `io.empeira.managed-by`, `io.empeira.workspace` and purpose labels.
+Volumes also have a random identity label. Names alone never authorize adoption or
+deletion. Mutations validate recorded IDs, labels and isolation, and persist creation
+intent before changing runtime resources. Uncertain outcomes are inspected before
+retry. Missing retained storage or database credentials never initialize replacement
+data implicitly.
+
+The runtime is authoritative for observed existence; inventory supplies ownership
+and recovery context. Runtime migration is explicit: destroy with the owning engine,
+then change configuration. `down` preserves CA and database storage; `destroy`
+removes them. Both preserve control code, modules and caches.
+
+All mutations share a nonblocking filesystem `flock` and version gate. Read-only
+status takes no exclusive lock. The lock inode stays stable; never delete its file
+as stale-lock recovery. Unsupported state has no automatic migration.
+
+## Definitions and live code
+
+Canonical SHA-256 fingerprints cover relevant managed definitions, independently
+of application versions, YAML formatting and unrelated node defaults. Component
+fingerprints allow selective service reconciliation while preserving owned storage.
+Each `up` batches service and volume observations and reuses them only within that
+locked transaction. Starts, replacements and network attachments are inspected
+again; destructive operations verify fresh ownership and recorded IDs. Later CLI
+invocations never inherit these observations. Local image inspection results are
+shared by availability, reviewed-recipe, ID and architecture checks within one
+image-preparation block. A pull or build discards the old result before the new
+image is inspected. `up` performs no remote freshness check or full image-content
+hash; native image storage and immutable IDs remain the source of metadata.
+A recorded container is inspected directly by ID; a missing ID falls back to
+name inventory to detect replacements and renamed resources. DNS discovery uses the complete service observation and
+one node snapshot, preserving unchanged generated files. Proxy allowlist changes
+reload Squid after readiness without replacing its container; unchanged policy
+and bindings do not trigger HUP. The existing inventory records a validated
+proxy ID and small-file digest only after native reload success; failed reloads
+are retried even if generated files are already current. Gateway lockdown is
+reused only while the same instance remains locked in that transaction. Policy apply clears that checkpoint
+before execution so every uncertain outcome attempts fresh lockdown. Firewall
+policy and namespace routing are still reconciled on every `up`.
+Node access verifies network ownership and isolation with one bounded native network inspection; membership counts are collected separately
+for lifecycle observations and deletion, never inferred from the access check.
+VM acquisition and restart still read the complete immutable base and verify its
+SHA-256 pin, using the existing OpenSSL implementation. Neither file timestamps
+nor cached fingerprints replace these integrity checks.
+Network changes and unsafe storage transitions require explicit lifecycle operations;
+there are no implicit database-major migrations or automatic node replacements.
+
+Managed servers disable environment caching through native Puppet configuration
+(`environment_timeout = 0` in `[server]`), applied by the startup wrapper before
+the configured image entrypoint. `up` checks the actual native setting and restarts
+only a server whose setting changed; it preserves every other configuration key
+and retained storage. The configured Puppet confdir must agree with Puppetserver
+HOCON `master-conf-dir`. Catalog
+requests reload live code without repository hashes or environment-cache checkpoints.
+See [nodes](nodes.md#environment-cache-and-live-code).
+
+Command mocks use the same node inventory, generated-file mechanism and mutation
+lock. They reconcile atomically during initial node provisioning and start/up, preserving
+unchanged files and removing only verified owned stubs.
+
+## Runtime and update planes
+
+The control plane manages the server, database, DNS, workspace gateway and optional
+proxy, browser and additional infrastructure services. Readiness probes test real
+DNS, server, SQL and PuppetDB responses. Shared naming and peer backends preserve
+container/VM connectivity and isolation. Network capabilities and isolation must
+be verifiable; there is no host-network or software-emulation fallback.
+See [networking](networking.md) for the privilege and trust boundaries.
+
+`browser` validates existing infrastructure and reconciles only Chromium and its
+fixed loopback UI relay. Additional services use ordinary ownership, DNS and
+fingerprints, with a deliberately narrow configuration schema.
+
+Exact DNS rewrites share the existing CoreDNS configuration and service-discovery
+hosts file. Reloadable rewrite policy stays outside the DNS container definition
+fingerprint, so `up` can reload it without invalidating container/VM resolver
+bindings. Target lookups remain authoritative for `empeira.internal` and never
+fall through externally. No separate DNS inventory or provider-specific state is
+introduced. DNS image/definition replacement retains its existing node protection.
+
+Transparent TCP and UDP DNS redirects reuse the same gateway policy, fingerprint
+and discovery boundary. Exact IP/protocol/port tuples are translated to observed
+internal services
+with DNAT/SNAT; unresolved targets remain denied. Reconciliation blocks stale targets
+before recreation and publishes their new addresses after service startup. Changed
+NAT revokes namespace-local connection state while DROP is active. Unchanged rules
+preserve connections and node identities. DNS and proxy policy are independent;
+there is no additional service-IP inventory or provider-specific redirect plane.
+
+Updates form a separate plane. `update modules` uses host Git acquisition and a
+disposable r10k helper; `update images` uses native registry metadata and cached
+pulls/builds. Helpers use the runtime's normal bridge, require no infrastructure
+inventory or workspace services, and are removed after each invocation. Git/SSH and
+registry credentials remain owned by their native tools. `up` acquires missing
+images only and never synchronizes modules. See [Hiera and modules](hiera-and-eyaml.md).
+
+Standalone [addons](addons.md) reuse `Application`'s configuration and project
+context without constructing runtime services. `Modules::HostGit` acquires mirrors
+with the user's native authentication; addon acquisition disables hooks and
+submodules. Native Git resolves the same `ref^{commit}` expression used by r10k,
+without its container helper. Native Git materializes local snapshots using a
+disposable index with configured filters and hooks disabled; publication is atomic
+under a per-source user-cache lock.
+They do not participate in infrastructure inventory or component fingerprints.
+The execution runner hands off directly to the entrypoint, and the existing
+completion catalog/Bash adapter reads its manifest. `up` prepares missing addons
+after infrastructure readiness and reports addon failures independently.
+
+## Diagnostic access and recovery
+
+Exec and VM PTY shells extend the existing framed VirtIO guest adapter. Eight private
+VirtIO-Serial ports have pinned socket identities and exclusive session slots; each
+bounded worker owns its process session and PTY. Idle workers block on I/O. Commands,
+uploads and interactive sessions retain one instance token and per-session identity
+without a management network or host daemon. A local raw terminal forwards bytes,
+resize and normal guest job control; cancellation kills the owned session groups.
+Container exec uses native numeric-root execution and a guest Ruby supervisor with a
+private completion receipt so native-client errors cannot impersonate guest exits.
+
+Recovery uses the same workspace lock/inventory and existing runtime, QEMU monitor
+and peer teardown adapters. It reads ownership fields without operational schema,
+version, guest, base-image or current configuration gates. Every mutation still
+checks native identity and safe paths. Resource records are removed only after confirmed
+removal; partial failures retain evidence and continue independent cleanup. Retired
+public certificate fingerprints permit later verified hostname reuse without requiring
+a live CA during node removal. The mutation-lock inode remains stable after destroy.
+
+## Execution and secrets
+
+All external processes use `Execution::Runner` with explicit arguments, environment,
+directory and timeout. Capture and streaming share owned-process cleanup on Linux,
+macOS and WSL2. Debug logs redact sensitive values; captured output is untrusted and
+failure diagnostics are filtered and bounded. Interactive shell, SSH and console
+operations suspend progress rendering.
+
+Keys and generated credentials stay in private external workspace storage or owned
+volumes. Agent repository credentials use only the two documented process variables;
+bootstrap delivers them through temporary 0600 files and verifies their removal.
+Repository/proxy credentials and private keys stay out of image layers, inventories,
+fingerprints and public release assets.