tegwick
0b44cf12f5
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a06d83-1cbc-71f2-b0dc-e0f48cedae43
59 lines
2.2 KiB
Markdown
59 lines
2.2 KiB
Markdown
---
|
|
id: STATE-ADR-002
|
|
type: architecture-decision-record
|
|
title: "Use Forge commits, never another machine's checkout, as the cluster repository boundary"
|
|
status: accepted
|
|
owner: state-hub
|
|
date: "2026-09-04"
|
|
deciders:
|
|
- operator
|
|
- state-hub
|
|
related:
|
|
- STATE-WP-0081
|
|
- STATE-WP-0083
|
|
- STATE-WP-0084
|
|
- STATE-WP-0086
|
|
---
|
|
|
|
# Use Forge commits as the cluster repository boundary
|
|
|
|
## Context
|
|
|
|
The former consistency sweep mounted an operator home directory into the
|
|
production State Hub pod. The cluster therefore saw stale checkouts, wrote
|
|
root-owned files into human workspaces, inherited a personal SSH identity, and
|
|
could not distinguish an absent work record from an out-of-date disk.
|
|
|
|
Repository files remain authoritative, but a local checkout is only one
|
|
machine's observation of those files. It is not a cross-machine transport.
|
|
|
|
## Decision
|
|
|
|
Workstation agents commit and push repository authority to Forgejo. Cluster
|
|
infrastructure reads a named, verified Forge commit into ephemeral storage.
|
|
Neither side reads or writes the other side's checkout.
|
|
|
|
`local_path` and `host_paths` remain compatibility/observation fields for tools
|
|
running on the named host. They must not select central reconciliation input.
|
|
Central reconciliation records both the expected and derived commit and refuses
|
|
the projection if they differ.
|
|
|
|
Cluster Forge access uses a workload service identity whose credential is
|
|
obtained through Kubernetes authentication to OpenBao. Personal SSH directories
|
|
and home-directory hostPaths are prohibited.
|
|
|
|
## Consequences
|
|
|
|
- A workstation change is invisible centrally until it is committed and pushed.
|
|
- A cluster result is attributable to an exact Forge commit.
|
|
- Temporary clones and credentials may be discarded after reconciliation.
|
|
- Offline writes use the explicit edge outbox; shared disks are not a fallback.
|
|
- Scripts needing repository contents locally resolve the current host's
|
|
`host_paths` entry and must fail clearly when no checkout is present.
|
|
|
|
## Verification
|
|
|
|
- The live State Hub pod has no operator-home or SSH hostPath.
|
|
- `rmgr sync --push` verifies `primary/railliance01` and exact commit equality.
|
|
- `docs/evidence/repository-registry-audit-20260904.json` records no active
|
|
repository without a remote and no stale Gitea remote.
|