# AWP FOSS / Provider Decisions

**Date:** 2026-08-19  
**Status:** Canonical binding planning decisions  
**Authority:** This file records the current-plan FOSS/provider decisions. `AWP-FOSS-REUSE-DEEP-RESEARCH.md` and `AWP-FOSS-MINIMALISM-DECISION-PASS.md` are the evidence/rationale. Where older planning text uses weaker `candidate`, `evaluate`, `bake-off`, or exploratory wording that conflicts with this file, this file controls until an accepted ADR explicitly changes it.

## 1. Governing rule: minimum total system complexity

AWP owns product semantics and authoritative lifecycle state. External systems own narrow replaceable mechanics.

Prefer, in order:

```text
standard
  > library
  > native platform primitive
  > single binary
  > controller/operator
  > service stack
```

A larger dependency is justified only when it deletes a larger, riskier subsystem that AWP would otherwise need to build and operate.

Do not add infrastructure merely because it may be useful later.

## 2. Final baseline decisions

| Concern | Binding decision | Consequence |
|---|---|---|
| Control-plane shape | **Modular monolith** | Do not split AWP domain Modules into services until measured scale/isolation requires it. |
| Runtime topology | **Stateless edge/gateway -> authoritative control plane -> K3s execution plane from day 1** | Gateway and control plane are separate deployable targets even when initially co-located. See `AWP-DEPLOYMENT-TOPOLOGY.md`. |
| HTTP/API | **Hono** | Thin Web-Standards transport around AWP Modules. Fastify/Nest/Express are not baseline alternatives. |
| Durable control-plane workflows | **DBOS library + PostgreSQL** | `DurableWorkflowProvider` uses DBOS. No Hatchet/Temporal/DBOS Conductor baseline. Re-evaluate only on demonstrated HA/operations gap. |
| Short async jobs/outbox | **`@platform-modules/jobs`** | Bounded background jobs/outbox only; not durable workflow or lifecycle authority. |
| Backend lifecycle modeling | **AWP-owned typed transition tables/functions** | No XState in authoritative backend lifecycle state. PostgreSQL transaction remains source of truth. |
| Agent execution substrate | **K3s / Kubernetes** | Normal agent execution is isolated from the workstation. |
| Workspace architecture | **Native Kubernetes `WorkspaceProvider` using Pod/PVC/ServiceAccount/NetworkPolicy** | Kubernetes Agent Sandbox is not installed initially. AWP Workspace semantics remain independent of CRDs. |
| Untrusted AgentRun runtime | **gVisor `RuntimeClass` preferred** | Trusted control-plane workloads use native containerd/runc. Native runtime is compatibility fallback; Kata is only for explicit VM-isolation requirements. |
| Project execution environments | **Development Container specification + official CLI; project-native definitions first** | No proprietary AWP environment DSL. |
| Existing environment definitions | **Adopt-first** | Detect `.devcontainer`, Docker/Compose, mise, Devbox and native tool manifests before generating anything. |
| Service dependencies | **Separate attached services** | DB/browser/SMTP-test/etc. attach to `ExecutionProfile`; do not bake them into mutable workspace images. |
| Agent interoperability | **ACP preferred generic protocol** | Use Agent Client Protocol where supported; keep native adapters for provider-specific capabilities ACP cannot express. |
| Coding-agent factory | **Fabro primary `FactoryProvider`** | Single-binary factory mechanics; AWP keeps `FactoryRun`/`AgentRun` semantics, approvals, policy and relationships. |
| Scheduling | **native kube-scheduler** | No second ordinary placement authority. |
| Fair-share/admission | **No Kueue baseline** | Add only after real quota/fairness/GPU/resource-flavor admission requirements exist. |
| Kubernetes security | **PSA + VAP/CEL + RBAC + securityContext + NetworkPolicy** | Native security primitives first. |
| Network | **K3s Flannel + kube-router NetworkPolicy** | No Cilium/Hubble baseline. |
| Admission policy | **native Kubernetes policy mechanisms** | No Kyverno baseline. |
| Workload identity | **Kubernetes ServiceAccounts** | No SPIFFE/SPIRE baseline. |
| Secrets | **AWP `SecretStore` -> Kubernetes Secrets initially** | AWP owns references, authorization, redaction, rotation semantics and audit. |
| Secrets in Git | **Default: none, including encrypted payloads** | SOPS + age is opt-in project policy only. |
| External/dynamic secrets | **No OpenBao/ESO baseline** | ESO only when integrating an existing external secret authority; OpenBao only if a self-hosted dynamic authority is explicitly required. |
| PostgreSQL application contract | **plain PostgreSQL endpoint** | AWP does not require a Kubernetes database operator. |
| Production PostgreSQL | **external/managed PostgreSQL preferred** | Keeps AWP deployment small and cloud/VM/Kubernetes portable. |
| Self-hosted production PostgreSQL | **CloudNativePG + Barman Cloud Plugin optional deployment profile** | Use only for customers requiring production PostgreSQL inside Kubernetes. |
| Object storage | **external S3-compatible endpoint** | `ObjectStoreProvider` is required; no bundled object-store service by default. |
| Self-contained object storage | **SeaweedFS preferred optional profile** | Use its tested S3 subset; `weed mini` is appropriate for small/self-contained installs. |
| OCI registry | **GHCR initially** | No self-hosted registry baseline. |
| Self-hosted OCI registry | **zot** | Harbor only for enterprise requirements that justify its larger surface. |
| Supply-chain scanning | **Trivy** | Do not simultaneously install Syft+Grype unless a project/customer requires that alternative. |
| Signing/attestation | **Cosign** | Standard OCI signing/verification. |
| Generic OCI artifacts | **ORAS** | Reuse OCI transport. |
| Kubernetes deployment | **Helm-rendered manifests + Kubernetes Server-Side Apply** | No Flux baseline; AWP owns deployment orchestration, health and rollback state. |
| Continuous GitOps reconciliation | **Flux only on explicit project/customer requirement** | Add when desired state must reconcile independently of AWP. |
| Progressive delivery | **Flagger only on explicit need** | Not baseline infrastructure. |
| CI execution | **GitHub Actions as initial CI provider, executed by ARC-managed ephemeral runners on K3s** | AWP owns CIExecution/CIResult semantics and observes GitHub checks; project-native workflows remain intact. Direct workspace checks are preflight/ad-hoc mechanics, not a replacement CI control plane. |
| GitHub Actions self-hosted runners | **ARC on K3s from day 1** | One cluster-managed runner scale-set model replaces independently maintained runner daemons on individual machines. |
| Work-management semantics | **AWP-owned typed policy/data model** | No external Scrum/Kanban/Scrumban semantics engine. |
| Board drag/drop | **Pragmatic Drag and Drop** | Library owns mechanics; AWP owns WorkItem semantics. |
| Graph interaction | **React Flow** | Library owns graph interaction mechanics; AWP owns graph meaning/composition. |
| Operational charts | **Chart.js** | Use directly behind AWP chart components; no ECharts baseline. Critical data also has text/table representation. |
| Business events | **AWP/PostgreSQL** | Durable business events are product data, not telemetry. |
| Telemetry instrumentation | **OpenTelemetry API/SDK-compatible boundary** | No mandatory Collector. Export directly when sufficient. |
| Telemetry Collector | **optional** | Add for batching/routing/transformation/fan-out only. |
| Persistent metrics/traces/log backend | **not bundled** | Deployments may point OTel at existing infrastructure. Do not install Prometheus+Jaeger+log DB by default. |
| MCP | **Official TypeScript MCP SDK v2** | No AWP-specific MCP transport stack. |
| External event envelope | **CloudEvents** | AWP internal events remain AWP schemas; CDEvents is only an optional integration adapter. |
| Existing repo build graphs | **adapt Nx/Turbo/Bazel/Pants when present** | Do not impose a universal build graph. |
| Feature activation | **AWP typed activation/landing policy** | No OpenFeature baseline. Add adapter only for real external flag providers. |
| Generic policy engine | **no OPA baseline** | Typed AWP policy is authoritative; OPA only for a future policy class that materially benefits from it. |
| Release preparation | **project-native first** | Adapt Changesets/Release Please/semantic-release/project scripts when present; otherwise use a small AWP-owned explicit version/tag/changelog path. |
| Incident diagnosis | **existing ModelGateway/agents + deterministic Resolver framework** | No HolmesGPT baseline. |
| K3s machine install/join | **official K3s installer** | k3sup CE may remain an optional convenience adapter. |
| Raw Kubernetes admin | **Headlamp optional expert escape hatch** | Never normal product UX/source of truth. |
| Machine capability data | **Kubernetes Node API** | Add Node Feature Discovery only when advanced hardware features are actually required. |
| Node/system health | **node-problem-detector before custom deep detector** | Add only at Cluster health increment. |
| K3s upgrades | **system-upgrade-controller before custom upgrade executor** | AWP owns policy/authorization/progress. |
| Current cluster CPU/memory | **K3s metrics-server** | Add node_exporter/kube-state-metrics only for historical metrics requirements. |
| SBOM | **CycloneDX preferred; SPDX accepted** | Preserve standard evidence. |
| Build provenance | **SLSA + in-toto compatible** | No proprietary provenance prerequisite. |
| Static analysis interchange | **SARIF** | Normalize standard provider output. |
| AWP packaging | **Helm chart** | Kustomize may provide overlays; no new packaging DSL. |
| Tenant Kubernetes isolation | **namespace/RBAC/network/runtime isolation first** | No vCluster baseline. |
| Future cloud/IaC provisioning | **OpenTofu CLI first** | Do not introduce Crossplane unless continuous Kubernetes-native infrastructure reconciliation becomes an explicit product requirement. |
| Future self-hosted VCS | **Gitea provider** | GitHub remains initial VCS path. |
| Redis/BullMQ, Kafka, NATS, service mesh | **not baseline dependencies** | Add only after a demonstrated requirement survives the delete-test. |

## 3. Required provider boundaries

Even when a provider is selected, AWP owns the semantic interface so the provider does not become the product model.

```text
DurableWorkflowProvider
  default: DBOS

WorkspaceProvider
  default: native Kubernetes Pod/PVC implementation

FactoryProvider
  default: Fabro

AgentProvider
  default interoperability: ACP where supported

ObjectStoreProvider
  default deployment: external S3-compatible endpoint

SecretStore
  default deployment: Kubernetes Secrets

VcsProvider
  initial: GitHub

DeploymentProvider
  baseline Kubernetes path: Helm render + Server-Side Apply

CiProvider
  initial: GitHub Actions

RunnerInfrastructure
  baseline: Actions Runner Controller (ARC) on K3s

TelemetryExporter
  OpenTelemetry-compatible
```

Provider IDs, CRD fields, workflow task IDs, tool-specific state and external JSON are never the only identity/state representation for AWP domain objects.

## 4. Intentionally absent baseline infrastructure

The following are **not unresolved research**. The current decision is to omit them from the baseline:

```text
Hatchet
Temporal
DBOS Conductor
XState for backend lifecycle
Kubernetes Agent Sandbox
Kata Containers
Kueue
Dagger
Flux
Flagger
Cilium/Hubble
Kyverno
Tetragon/Falco
Velero
OpenFeature
OPA
OpenBao
External Secrets Operator
SPIFFE/SPIRE
vCluster
Crossplane
Harbor
persistent telemetry backend stack
OpenTelemetry Collector
service mesh
Redis/BullMQ
Kafka
NATS
HolmesGPT
CDEvents core model
```

Some have explicit trigger-based uses below. Omission is the default.

## 5. Trigger-based additions: decision is already made, installation waits

These do not require another architecture debate unless the stated default fails.

| Trigger | Add/use | Why |
|---|---|---|
| DBOS cannot satisfy required horizontal HA/operations cleanly | Re-open `DurableWorkflowProvider`; Hatchet/Temporal become alternatives | Do not pre-install another workflow control plane. |
| Workspace startup/warm-pool/hibernate complexity becomes material | Evaluate Kubernetes Agent Sandbox as optimized `WorkspaceProvider` | Native provider remains compatibility floor. |
| gVisor breaks a required toolchain | Per-workload native runtime fallback | Do not weaken all workloads for one incompatibility. |
| Threat model requires VM-backed workload isolation | Kata Containers | RuntimeClass preserves same AWP abstraction. |
| Native NetworkPolicy/visibility is insufficient | Cilium/Hubble | Only after a concrete network gap. |
| Native admission mechanisms become materially awkward/insufficient | Kyverno | Only for concrete policy classes. |
| Runtime detection/response becomes required | Evaluate Falco first; Tetragon if Cilium is already present and creates clear leverage | Avoid a runtime-security stack before a threat requirement. |
| Customer/project requires continuous GitOps independent of AWP | Flux | Baseline remains Server-Side Apply. |
| Project requires progressive delivery | Flagger | Add above the deployment provider. |
| Existing project already uses Dagger | Dagger adapter | Preserve project-native tooling. |
| Customer has existing external secret manager | ESO adapter | Do not introduce OpenBao merely to use ESO. |
| Customer needs self-hosted dynamic secret authority | OpenBao (+ ESO only if useful) | Explicit deployment requirement. |
| Customer needs self-hosted object storage | SeaweedFS | External S3 remains default. |
| Customer needs self-hosted OCI registry | zot | GHCR remains default. |
| Namespace-level tenant isolation proves insufficient | vCluster | Requirement-driven isolation. |
| AWP becomes responsible for cloud resource provisioning | OpenTofu | Crossplane only if persistent Kubernetes reconciliation is explicitly required. |
| OTel direct export becomes insufficient | OpenTelemetry Collector | Add only when routing/batching/transformation/fan-out is needed. |
| Project/customer requires CDEvents interoperability | CDEvents adapter -> CloudEvents transport | Do not replace internal AWP event vocabulary. |

## 6. Small baseline dependency picture

```text
AWP CONTROL PLANE
  Node / TypeScript / ESM
  Hono
  PostgreSQL + Drizzle
  DBOS library
  Platform modules

AWP UI
  React + Astryx
  Pragmatic Drag and Drop
  React Flow
  Chart.js

EXECUTION PLANE
  K3s / Kubernetes
  native Pod/PVC WorkspaceProvider
  gVisor RuntimeClass for untrusted AgentRuns
  Dev Container standard/CLI
  Fabro
  ACP

CI / DELIVERY
  GitHub Actions workflows
  ARC runner scale sets on K3s
  ephemeral runner pods
  project-native preflight checks in AWP workspaces where useful
  Helm + Server-Side Apply
  Trivy + Cosign + ORAS
  CloudEvents only at external boundaries

EXTERNALIZED STATEFUL SERVICES
  PostgreSQL endpoint
  S3-compatible object store
  GHCR

OBSERVABILITY
  AWP business events/audit in PostgreSQL
  structured logs
  OpenTelemetry-compatible export
```

## 7. Remaining decisions

There are **no remaining foundation FOSS architecture choices from the previous open-decision register**. They have been converted to either a selected baseline or a trigger-based optional addition.

The remaining choices are deployment/customer facts that cannot usefully be chosen globally now:

```text
which managed/external PostgreSQL vendor a deployment uses
which external S3-compatible provider a deployment uses
which OTel-compatible telemetry backend a deployment already has or wants
whether a specific customer permits SOPS-encrypted secrets in Git (default: no)
which project-native release tool a repository already uses
whether a customer requires GitOps, self-hosted registry/storage,
external secret authority, tenant virtual clusters, or cloud provisioning
```

Those are configuration/deployment selections, not unresolved AWP architecture.

## 8. Evidence documents

- `AWP-FOSS-REUSE-DEEP-RESEARCH.md` — broad second-pass FOSS evidence and alternatives.
- `AWP-FOSS-MINIMALISM-DECISION-PASS.md` — focused re-evaluation using the small/no-bloat/native-first rule.
- `STEP-0-PREPARATION-DEPENDENCIES.md` — implementation readiness gates that consume these decisions.