Skip to content

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 ​

CrateRulingReasonTarget home
bupha-coreKEEPCanonical 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-accessKEEP"Who may trigger" — sender authorization is ingest semantics; sender is forge-attested.stays
bupha-access-fileKEEPAllowlist policy impl — CI-ingress policy, not generic infra.stays
bupha-access-forgeKEEPForge collaborator-permission check — forge knowledge is bupha's.stays
bupha-attestKEEPRun-provenance port (SLSA-style predicate) — attestation is a CI deliverable.stays
bupha-attest-fileKEEPPredicate-file impl of Attest.stays
bupha-attest-sigstoreKEEPcosign-signed predicate impl.stays
bupha-audit-fileKEEPJSONL audit of access/run decisions — CI observability. Optional feature; the ci-job entity index may subsume it in hosted mode (open question).stays
bupha-cacheKEEPPort 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-sccacheKEEPConf renderer for sccache-compatible backends.stays
bupha-cliSPLIT/DEVPer 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-cloudflaredMIGRATENamed/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-configKEEPConfig port over the CI fleet/repo model — domain-shaped, not generic config machinery.stays
bupha-config-fileKEEPPath resolution + syntax dispatch.stays
bupha-config-tomlKEEPTOML parser impl.stays
bupha-config-yamlKEEPYAML parser impl (fleet.toml/bupha.yaml are the standard).stays
bupha-containerKEEPRunner impl — unprivileged container exec is CI-runner semantics.stays
bupha-daggerKEEPRunner impl — dagger call per job.stays
bupha-dotenvMIGRATEKEY=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-driverKEEP+EXTENDtamias-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-ghaKEEPThe 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-gitKEEPVcs impl via git CLI — worktree/sync primitives every runner needs.stays
bupha-githubKEEPTrigger 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-historyKEEP (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-httpKEEPRunner impl — remote exec via bupha agent (tar worktree + poll). Runner semantics; known auth caveats tracked as issues.stays
bupha-keyringMIGRATEOS-keyring secret impl — generic secret plumbing. hypha ships hypha-keyring; cuora is the org broker story (T-056).hypha-keyring / cuora (T-056)
bupha-queueKEEP (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-leaseDIEFence/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-redbMIGRATEEmbedded 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-redisMIGRATENetworked queue impl (SET NX claim + INCR fence) — textbook substrate. The ci-job entity CAS + outbox is the distributed queue.hypha-side queue impl
bupha-runnerKEEPRunner port — RunCtx/RunHandle/Runner is the seam every runner impl (shell/container/ssh/http/dagger/gha) plugs into.stays
bupha-secretDECIDE (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-serviceDIEOS 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-shellKEEPRunner impl — bash -c exec.stays
bupha-sshKEEPRunner impl — remote exec over ssh/rsync. Runner semantics.stays
bupha-statusKEEPStatusSink 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-sturnKEEPTrigger 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-systemdMIGRATEUser-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-telemetryKEEPTelemetry port over CI-shaped run events (Queued/Started/Finished) — observability semantics; optional feature.stays
bupha-telemetry-otelKEEPOpenMetrics textfile impl. Note overlap with hypha-telemetry (OTLP) — different export shape, both may coexist; revisit if hypha-telemetry gains textfile.stays
bupha-triggerKEEPSource/Trigger port + Push/Verdict/PushOutcome — the normalization contract every ingress (webhook, sturn, future gitlab) drives.stays
bupha-tunnelDIEPort 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-vcsKEEPVCS port — sync/worktree/tag ops the runner pipeline needs.stays
bupha-webhookSPLITThe 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. Thin hypha_http::EntityPlane adapter holding ci-job entity state and dispatching ci.* ops; the pure transition math stays in bupha-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 in bupha-core as 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/-sccache are 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 ships hypha-{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. Only history is 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 worker is the production worker host.

Open questions ​

  1. 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.
  2. 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 uses MemWorkQueue) and DIE it? Lean: DIE unless hypha wants a non-entity queue.
  3. bupha-plane home (P-002 Q1): bupha crate dep'ing on hypha-http vs plane code inside peregrin-node. Audit assumes the bupha crate.
  4. history/audit-file vs entity index: do ci-job entities + ci.status fully replace history.jsonl/audit.log in hosted mode, making both dev-only? Probably yes; confirm before deleting read paths the driver still uses.
  5. bupha-telemetry-otel vs hypha-telemetry: keep the OpenMetrics textfile impl in bupha, or does hypha-telemetry absorb textfile export? Different export shapes today — keep for now.
  6. 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:

CrateOutcome
bupha-secretDIE — trait identical to hypha_secret::Secrets; consumers take the hypha git dep directly.
bupha-keyringDIE → hypha-keyring with service = "bupha" so pre-cuora keyring entries still resolve.
bupha-dotenvDIE → hypha-dotenv — ~/.config/bupha/env path/format unchanged.
bupha-secret-cuoraKEEP — the canonical store; now implements hypha_secret::Secrets (already wrapped hypha-secret-cuora).
bupha-serviceDIE — one impl (bupha-systemd), consumers used free fns/struct, not the trait.
bupha-systemdDIE → 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-cloudflaredFOLDED → 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-webhookFOLDED → 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.