Crate scope audit — bupha under ADR-0006
Per-crate ruling for every crate in crates/, against ADR-0006 ("bupha is CI semantics only — substrate is hypha/peregrin, distribution is tamias") and the P-002 ci-job ops contract.
Rulings:
- KEEP — CI semantics or runner/dialect/forge/status knowledge that stays in bupha.
- MIGRATE — stateful/infra machinery that becomes a hypha-side impl or dies in favor of ci-job entities. Target home noted.
- DIE — fully subsumed, no port value.
- SPLIT — crate mixes semantics + machinery; noted per half.
- DEV — survives only as the in-process dev/test harness (ADR-0006: "ports stay, impls get swapped").
The table
| Crate | Ruling | Reason | Target home |
|---|---|---|---|
bupha-core | KEEP | Canonical job spec, Queue/QueuePolicy/MAX_PENDING, is_valid_sha/is_valid_key, WatchedRepo, config types — the pure semantics P-002 pins as the plane's spec. Gains cijob transition functions. | stays |
bupha-access | KEEP | "Who may trigger" — sender authorization is ingest semantics; sender is forge-attested. | stays |
bupha-access-file | KEEP | Allowlist policy impl — CI-ingress policy, not generic infra. | stays |
bupha-access-forge | KEEP | Forge collaborator-permission check — forge knowledge is bupha's. | stays |
bupha-attest | KEEP | Run-provenance port (SLSA-style predicate) — attestation is a CI deliverable. | stays |
bupha-attest-file | KEEP | Predicate-file impl of Attest. | stays |
bupha-attest-sigstore | KEEP | cosign-signed predicate impl. | stays |
bupha-audit-file | KEEP | JSONL audit of access/run decisions — CI observability. Optional feature; the ci-job entity index may subsume it in hosted mode (open question). | stays |
bupha-cache | KEEP | Port only renders conf text the runner consumes (sccache is external) — runner-facing semantics, not a stateful cache. The worktree/build cache concern belongs to substrate, but this crate never held state. | stays |
bupha-cache-sccache | KEEP | Conf renderer for sccache-compatible backends. | stays |
bupha-cli | SPLIT/DEV | Per ADR-0006 amendment there is no user-facing bupha CLI. watch/worker/agent/run/import/doctor survive as the dev/test harness (single-box bupha-node + embedded queue); lifecycle verbs (deploy/service/destroy) are already driver/tamias surface. The binary eventually dissolves into tamias-driver-bupha worker + a dev binary. | dev binary + driver |
bupha-cloudflared | MIGRATE | Named/quick tunnel provider — generic ingress plumbing. Webhook ingress is peregrin's (P-002/T-055); tunnel lifecycle is hypha-service territory. | hypha tunnel impl (or dies if peregrin ships one) |
bupha-config | KEEP | Config port over the CI fleet/repo model — domain-shaped, not generic config machinery. | stays |
bupha-config-file | KEEP | Path resolution + syntax dispatch. | stays |
bupha-config-toml | KEEP | TOML parser impl. | stays |
bupha-config-yaml | KEEP | YAML parser impl (fleet.toml/bupha.yaml are the standard). | stays |
bupha-container | KEEP | Runner impl — unprivileged container exec is CI-runner semantics. | stays |
bupha-dagger | KEEP | Runner impl — dagger call per job. | stays |
bupha-dotenv | MIGRATE | KEY=VAL secret file — generic secret plumbing, not CI semantics. hypha already ships hypha-dotenv; under a cuora story (T-056) it dies outright. | hypha-secret impls / cuora (T-056) |
bupha-driver | KEEP+EXTEND | tamias-driver-bupha is the distribution surface and the future worker host (P-002 §4 worker verb). data.rs moves from queue.redb reads to the ci-job entity index when hosted mode lands. | stays — gains worker verb + ci-jobs view |
bupha-gha | KEEP | The workflow dialect — parse/plan/script/executor for .github/workflows/*.yml. Core CI semantics; also feeds T-050 (self-hosted GHA runner — reserved name gha-runner, T-054). | stays |
bupha-git | KEEP | Vcs impl via git CLI — worktree/sync primitives every runner needs. | stays |
bupha-github | KEEP | Trigger parse/verify (push normalization) + StatusSink commit-status posting — both halves are CI semantics (P-002 keeps normalization + worker-side status posting in bupha). | stays |
bupha-history | KEEP (dev/optional) | JSONL run records for bupha runs/log. In hosted mode the ci-job entity index is the history; keep as dev-mode/optional feature, candidate to fold later. | stays (dev) |
bupha-http | KEEP | Runner impl — remote exec via bupha agent (tar worktree + poll). Runner semantics; known auth caveats tracked as issues. | stays |
bupha-keyring | MIGRATE | OS-keyring secret impl — generic secret plumbing. hypha ships hypha-keyring; cuora is the org broker story (T-056). | hypha-keyring / cuora (T-056) |
bupha-queue | KEEP (dev only) | QueueStore/WorkQueue port + MemWorkQueue — P-002 keeps the port and in-process impl for dev/test; the distributed path is the ci-job entity plane, not this port. | stays (dev/test) |
bupha-queue-lease | DIE | Fence/TryClaim semantics are absorbed verbatim into the ci-job entity (fence counter + leaseExpiresAt + ci.claim CAS, P-002 §3). No port value once the plane lands; dev mode doesn't need it (MemWorkQueue always claims). | → bupha-plane entity state |
bupha-queue-redb | MIGRATE | Embedded durable queue — single-node state machinery. The entity plane replaces it even single-box; if hypha wants a local durable queue impl it can adopt the redb code hypha-side. Dev path uses MemWorkQueue. | hypha-side queue impl (or DIE — open question) |
bupha-queue-redis | MIGRATE | Networked queue impl (SET NX claim + INCR fence) — textbook substrate. The ci-job entity CAS + outbox is the distributed queue. | hypha-side queue impl |
bupha-runner | KEEP | Runner port — RunCtx/RunHandle/Runner is the seam every runner impl (shell/container/ssh/http/dagger/gha) plugs into. | stays |
bupha-secret | DECIDE (T-056) | Secret-resolution port. If cuora wins the secrets story the port dies (cuora refs replace named-secret lookup); if env-file/keyring survives it stays thin. Tentative: DIE under cuora. | cuora / hypha-secret (T-056) |
bupha-service | DIE | OS service-lifecycle port — generic infra now owned by tamias-provider (tamias-deploy -systemd/-windows) and hypha-service. Bupha's only consumer was its own (dead) CLI verbs. | tamias / hypha-service |
bupha-shell | KEEP | Runner impl — bash -c exec. | stays |
bupha-ssh | KEEP | Runner impl — remote exec over ssh/rsync. Runner semantics. | stays |
bupha-status | KEEP | StatusSink port — workers post forge commit statuses on ci.complete (they hold forge creds via token_env); the plane records outcome but does not post (P-002 §5). | stays |
bupha-sturn | KEEP | Trigger impl — polls refs/sturn/* WAL → normalized Pushes with SSH-verified sender attestation. Event→push normalization is CI semantics; sturn itself is a sibling repo. | stays |
bupha-systemd | MIGRATE | User-unit rendering — generic service lifecycle. tamias-deploy -systemd already owns this; the driver's deploy verb should consume tamias's surface instead. | tamias-deploy-systemd / hypha-systemd |
bupha-telemetry | KEEP | Telemetry port over CI-shaped run events (Queued/Started/Finished) — observability semantics; optional feature. | stays |
bupha-telemetry-otel | KEEP | OpenMetrics textfile impl. Note overlap with hypha-telemetry (OTLP) — different export shape, both may coexist; revisit if hypha-telemetry gains textfile. | stays |
bupha-trigger | KEEP | Source/Trigger port + Push/Verdict/PushOutcome — the normalization contract every ingress (webhook, sturn, future gitlab) drives. | stays |
bupha-tunnel | DIE | Port exists solely to expose the webhook listener publicly. Production ingress is peregrin's; dev mode can use a hypha tunnel impl or direct. No CI semantics in the trait. | → hypha (if a generic tunnel port is wanted) |
bupha-vcs | KEEP | VCS port — sync/worktree/tag ops the runner pipeline needs. | stays |
bupha-webhook | SPLIT | The Trigger-driving + signature/dedup logic's durable value is subsumed: deterministic entity ids (ci:{key}:{sha}:{attempt}) dedup replays for free (P-002 §1), so the Seen ring dies with the listener. The tiny_http accept-loop harness → dev-mode only; production ingress is a peregrin campaign listener that normalizes via bupha-trigger then POST /api/entities (T-055). | harness → dev; dedup → entity ids |
Incoming
bupha-plane(new, P-002) — KEEP. Thinhypha_http::EntityPlaneadapter holding ci-job entity state and dispatchingci.*ops; the pure transition math stays inbupha-core. First bupha→hypha dep — confirm acceptable (P-002 open question 1).
Key judgment calls
- Queue family: the semantics (
Queue, supersede/retry math,MAX_PENDING) stay inbupha-coreas the spec the plane mirrors; the port + in-process impl (bupha-queue) stay for dev/test per P-002; the distributed impls (-redb,-redis) and the lease port migrate/die — fencing becomes entity state (fence+leaseExpiresAt+ op CAS), not a separate port. - Cache:
bupha-cache/-sccacheare KEEP — they render runner conf, they don't are a cache. The substrate cache concern (worktree/build artifacts across nodes) is hypha's and was never these crates' job. - Ingress trio (
webhook/trigger/sturn): normalization (Trigger,Push,Verdict, sturn WAL→push) is KEEP — it's the "forge event → job spec" half of ADR-0006. Listener harnesses are dev-mode; production ingress is peregrin's. - Secrets trio (
secret/keyring/dotenv): judged generic infra, not CI semantics — but the ruling is gated on T-056 (cuora vs env vs keyring). hypha already shipshypha-{secret,keyring,dotenv}impls, so MIGRATE has a ready home; under cuora they all DIE. - Service/lifecycle (
service/systemd/tunnel/cloudflared): all generic host machinery — tamias (deploy/provider) + hypha (service/systemd) own it now. DIE or MIGRATE; nothing here is CI semantics. - Enterprise surfaces (
access*/attest*/audit-file/history/telemetry*): KEEP as optional bupha features — they encode CI-specific policy (who may trigger, run provenance, audit trail), not generic substrate. Onlyhistoryis a maybe-fold into the entity index later. bupha-cli: SPLIT — dev harness survives, user-facing binary dies per the ADR-0006 amendment;tamias-driver-bupha workeris the production worker host.
Open questions
- Secrets story (T-056) gates
bupha-secret/-keyring/-dotenv: cuora → all three die; env/keyring → port stays thin, impls duplicate hypha's. Pick before migrating. bupha-queue-redb: migrate the redb code hypha-side as a local durable queue impl, or let the entity plane cover single-box too (dev usesMemWorkQueue) and DIE it? Lean: DIE unless hypha wants a non-entity queue.bupha-planehome (P-002 Q1): bupha crate dep'ing onhypha-httpvs plane code insideperegrin-node. Audit assumes the bupha crate.history/audit-filevs entity index: do ci-job entities +ci.statusfully replacehistory.jsonl/audit.login hosted mode, making both dev-only? Probably yes; confirm before deleting read paths the driver still uses.bupha-telemetry-otelvshypha-telemetry: keep the OpenMetrics textfile impl in bupha, or does hypha-telemetry absorb textfile export? Different export shapes today — keep for now.- Tunnel: does hypha/peregrin want a generic tunnel port at all, or is ingress exposure always a campaign/deploy concern (named tunnel via tamias)? Determines whether
bupha-tunnel's trait migrates or just dies.
Resolution — T-077 (landed)
With T-055 (ADR-0007: ingress is peregrin-owned, bupha webhook surfaces are standalone/dev mode) and T-056 (cuora canonical, T-059 migration verified) done, the remaining MIGRATE/DIE crates were retired in three commits on main:
| Crate | Outcome |
|---|---|
bupha-secret | DIE — trait identical to hypha_secret::Secrets; consumers take the hypha git dep directly. |
bupha-keyring | DIE → hypha-keyring with service = "bupha" so pre-cuora keyring entries still resolve. |
bupha-dotenv | DIE → hypha-dotenv — ~/.config/bupha/env path/format unchanged. |
bupha-secret-cuora | KEEP — the canonical store; now implements hypha_secret::Secrets (already wrapped hypha-secret-cuora). |
bupha-service | DIE — one impl (bupha-systemd), consumers used free fns/struct, not the trait. |
bupha-systemd | DIE → hypha-systemd — unit render/control via write_unit/enable/disable/status/restart/unit_path/default_unit_dir. Bupha-shaped helpers (write_env_skeleton, service_logs, strict daemon-reload on destroy, SystemdService wrapper) folded into bupha-cli's deploy module. Unit diffs: bare name + .service suffix, quoted ExecStart argv, EnvironmentFile=-, Restart=on-failure. |
bupha-tunnel + bupha-cloudflared | FOLDED → bupha-watch::tunnel — ADR-0007 keeps them as the standalone/dev-mode ingress; no hypha tunnel impl exists or is wanted (ingress exposure is a deploy/campaign concern). |
bupha-webhook | FOLDED → bupha-watch::webhook — same reasoning; tiny_http dep moved to bupha-watch. |
Open questions 1 and 6 are thereby resolved: cuora won the secrets story (legacy keyring/dotenv legs survive only as hypha-backed fallbacks in the dev chain), and no generic tunnel port migrates — the trait lives on inside bupha-watch for standalone mode only.