# AWP FOSS / Reuse Specification Coverage Matrix

**Date:** 2026-08-20  
**Status:** **PRE-RUN COMPLETENESS AUDIT — canonical FOSS decisions mapped to implementation-facing specs**  
**Authority:** `AWP-FOSS-DECISIONS.md` remains the binding provider/dependency decision register. This matrix proves where those decisions are carried into the target specification set and when they may be realized.

## Result

The binding FOSS decisions are now represented in the canonical implementation-facing specification system. The earlier gap was not that the FOSS research had been lost; it was that several decisions and legacy-code-harvest rules were not explicit enough in the specs an implementation agent would naturally read.

The completeness chain is now:

```text
AWP-FOSS-DECISIONS
  binding provider / omit / trigger decisions

specs/architecture/platform-reuse
  implementation-facing reuse-before-build rule

AWP-OVERDECK-CAPABILITY-HARVEST-PLAN
  proven legacy capability/script/module disposition gate

AWP-PRE-RUN-VISION-DRIFT-GAP-REVIEW
  omission/vision audit

this matrix
  FOSS decision -> canonical spec / timing trace
```

A row being fully specified does **not** mean its dependency should be installed now. `I0–I9` and trigger rules remain binding.

## Reuse Decision Order

```text
project-native mechanism
  -> verified platform-modules/mod capability
  -> vetted Overdeck capability/script/module
  -> native Node/PostgreSQL/K3s/Kubernetes primitive
  -> open standard/interchange format
  -> selected narrow FOSS/library/provider
  -> custom generic mechanics only with explicit gap justification
```

## Baseline Architecture / Runtime

| Decision | Canonical spec coverage | Realization | Anti-rebuild consequence |
|---|---|---|---|
| Modular monolith | `architecture/principles`, `module-boundaries`, ADR 0002 | I0 | no premature service split |
| gateway -> control -> K3s execution | `deployment-topology`, ADR 0001, `security-and-trust` | I0 | no workstation execution authority |
| Hono | `transport-and-contracts`, ADR 0003 | I0 | no custom HTTP stack / second application framework |
| PostgreSQL + Drizzle | `persistence-and-transactions`, ADR 0004 | I0 | no second product-state store |
| DBOS durable workflows | `durable-execution`, ADR 0005 | I0 | no Hatchet/Temporal/Conductor baseline and no duplicate workflow authority |
| `@platform-modules/jobs` bounded jobs/outbox | `platform-reuse`, persistence/event specs | I0 | do not rebuild bounded jobs/outbox |
| typed AWP transition functions/tables | domain specs + `durable-execution` | I0 onward | no XState backend state authority |
| K3s/Kubernetes execution | `workspace-execution`, `cluster`, deployment topology | I0 | no normal agent work on workstation |
| native Pod/PVC/ServiceAccount/NetworkPolicy WorkspaceProvider | `workspace-execution`, ADR 0006 | I0/I1 | no custom workspace operator required at baseline |
| gVisor preferred for untrusted AgentRuns | `security-and-trust`, `workspace-execution`, Step-0 readiness | I0 compatibility gate | native runtime only explicit compatibility fallback; Kata is trigger-only |
| Dev Container spec + official CLI | `workspace-execution`, `platform-reuse`, Step-0 | I0/I1 | no proprietary AWP environment DSL |
| project-native environment definitions first | `workspace-execution`, onboarding/reuse rules | I0/I1 | do not replace `.devcontainer`, Docker/Compose, mise, Devbox, tool manifests |
| service dependencies attached separately | `workspace-execution` | I0/I1 | no mutable per-framework snowflake workspace image |

## Agent / Factory / Control Surfaces

| Decision | Canonical spec coverage | Realization | Anti-rebuild consequence |
|---|---|---|---|
| ACP preferred; native escape hatch | `adapter-contracts`, `agents`, `factory`, `platform-reuse` | I1 | no custom universal agent protocol if ACP fits |
| Fabro primary FactoryProvider | `factory`, `factory-execution`, `adapter-contracts`, `platform-reuse` | I1 | no second custom factory workflow graph engine |
| official TypeScript MCP SDK v2 | `control-surfaces`, `platform-reuse` | I0/I1 as needed | no custom MCP wire/transport implementation |
| UI/API/`aw*` CLI/MCP share commands | `control-surfaces` | I0 onward | no separate CLI/MCP lifecycle or hidden authority path |
| GitHub initial VCS | `repositories-vcs`, `adapter-contracts` | I1 | AWP owns ChangeSet/publication/merge semantics, not GitHub object identity |
| future self-hosted VCS via Gitea provider | adapter/provider seam + binding FOSS register | trigger/later | do not build a generic Git server |

## Kubernetes Scheduling / Security / Identity

| Decision | Canonical spec coverage | Realization | Anti-rebuild consequence |
|---|---|---|---|
| native kube-scheduler | `cluster`, `workspace-execution`, `platform-reuse` | I0 | no second ordinary scheduler |
| no Kueue baseline | `cluster`, `platform-reuse`, FOSS trigger register | trigger only | add only for demonstrated fair-share/quota/GPU admission need |
| PSA + VAP/CEL + RBAC + securityContext + NetworkPolicy | `security-and-trust`, `workspace-execution`, Step-0 | I0 | native controls before policy controller |
| K3s Flannel + kube-router NetworkPolicy | deployment/security specs + binding FOSS register | I0 | no Cilium baseline |
| Kubernetes ServiceAccounts | `security-and-trust`, `workspace-execution` | I0 | no SPIFFE/SPIRE for same-cluster identity by default |
| Kubernetes Secrets behind AWP SecretStore | integrations/security/workspace specs | I0 | no credentials in ordinary config/domain records |
| no secrets in Git by default, even encrypted | integrations/security + binding FOSS register | I0 | SOPS+age is opt-in project policy only |

## Data / Backup / Registry

| Decision | Canonical spec coverage | Realization | Anti-rebuild consequence |
|---|---|---|---|
| plain PostgreSQL application endpoint | persistence + provider boundaries | I0 | no application dependency on a DB operator |
| managed/external production PostgreSQL preferred | deployment/reliability boundaries | deployment choice | no bundled DB operator by default |
| CloudNativePG + Barman plugin optional self-host profile | `platform-reuse`, deployment/reliability evidence | trigger | only when self-hosted production PostgreSQL is required |
| external S3-compatible ObjectStoreProvider | adapters/reliability/platform-reuse | before production backup/artifact need | no bundled object-store service by default |
| SeaweedFS optional self-contained object store | platform-reuse + binding trigger register | trigger | no MinIO/custom object-store baseline |
| GHCR initial OCI registry | artifacts/provider specs | I1/I6 | no self-hosted registry baseline |
| zot optional self-host registry | platform-reuse + trigger register | trigger | no custom OCI registry |
| Harbor enterprise only | platform-reuse + trigger register | enterprise trigger | avoid default enterprise registry stack |
| native K3s etcd snapshots | reliability/deployment evidence | operations | do not rebuild snapshot mechanics |
| no Velero baseline | binding negative register | trigger only | add only for generic K8s/PV backup/migration not covered by existing recovery model |

## CI / Verification / Build Graph

| Decision | Canonical spec coverage | Realization | Anti-rebuild consequence |
|---|---|---|---|
| GitHub Actions initial CI provider | `ci`, `ci-and-runner-boundary`, ADR 0007 | I1/I5 | no custom CI engine |
| ARC ephemeral runners on K3s | `ci-and-runner-boundary`, ADR 0007, Step-0 | I0/I1 | no per-machine runner daemons/autoscaler |
| project-native CI workflows preserved | CI domain/reuse rules | I1/I5 | do not rewrite workflows merely to normalize |
| repo-native Nx/Turbo/Bazel/Pants graph adapters | CI/reuse specs | I5 | do not rebuild repository dependency graph when one exists |
| Dagger not baseline | binding FOSS register | only existing-project or proven CI need | no additional CI execution authority preemptively |
| existing Testcontainers preserved | workspace/reuse spec | whenever present | do not replace working test service orchestration |
| VerificationAuthority belongs to AWP | `verification`, CI workflows | I1 thin / I5 full | tools produce evidence; they do not self-certify |

## Deployment / Release

| Decision | Canonical spec coverage | Realization | Anti-rebuild consequence |
|---|---|---|---|
| Helm-rendered manifests + Kubernetes Server-Side Apply | deployment boundary, ADR 0008 | I6; foundation contract I0 | no custom GitOps/reconciliation engine |
| Flux only explicit GitOps requirement | deployment boundary/platform reuse trigger | trigger | no Flux baseline |
| Flagger only progressive-delivery need | deployment trigger policy | trigger | no canary controller unless release strategy needs it |
| project-native release preparation first | releases/platform reuse | I6 | reuse Changesets/Release Please/semantic-release/scripts where fitting |
| Helm chart for AWP packaging | deployment/platform reuse | distribution | no custom package/install DSL |
| Kustomize selective overlays | deployment/platform reuse | as needed | no custom overlay engine |

## Supply Chain / Interchange Standards

| Decision | Canonical spec coverage | Realization | Anti-rebuild consequence |
|---|---|---|---|
| Trivy | artifact/provenance + platform reuse | before enforcement | no custom vulnerability scanner; no scanner pile by default |
| Cosign | artifact/provenance + platform reuse | before signing gate | no custom signature format |
| ORAS | artifact/provenance + platform reuse | artifact transport | no custom generic OCI artifact transport |
| CycloneDX preferred; SPDX accepted | artifacts/provenance + platform reuse | I5/I6 | no proprietary SBOM schema |
| SLSA + in-toto | artifacts/provenance + platform reuse | I6 | no proprietary build provenance schema |
| SARIF | CI/artifact evidence + platform reuse | I5 | no custom static-analysis interchange when SARIF exists |
| JUnit/common coverage formats | CI/verification + platform reuse | I5 | avoid parser-per-runner bespoke contracts where standards fit |
| CloudEvents external envelope | event/adapters + platform reuse | integration boundary | internal AWP events remain AWP semantics |
| CDEvents optional adapter | platform reuse/FOSS trigger | interoperability only | no CDEvents core-domain dependency |
| OpenAPI + oasdiff | transport/engineering practices | stable consumer boundaries | no bespoke compatibility diff mechanism |

## UI / Product Mechanics

| Decision | Canonical spec coverage | Realization | Anti-rebuild consequence |
|---|---|---|---|
| React + Astryx | UI IA + platform reuse | I1 onward | Astryx first; AWP owns product visuals |
| deck-ui only source/reference if Astryx lacks behavior | platform reuse + Overdeck harvest plan | consuming UI slice | port behavior as AWP-owned component; never runtime fallback identity |
| Pragmatic Drag and Drop | plan/work UI + platform reuse | relevant UI increment | no custom drag engine; non-drag accessible action required |
| React Flow | Planning/Factory/CI graph UI + platform reuse | relevant UI increment | no custom pan/zoom/node/edge interaction engine |
| Chart.js | Agents/CI/Cluster analytics + platform reuse | I4+ | one chart substrate; accessible text/table equivalent |
| Platform UI primitives/data helpers checked first | platform reuse | every UI slice | do not duplicate DataTable/virtual/loading behavior without gap proof |

## Operations / Cluster

| Decision | Canonical spec coverage | Realization | Anti-rebuild consequence |
|---|---|---|---|
| official K3s installer; k3sup optional helper | cluster/machine-enrollment/platform reuse | I0/I7 | no custom K3s installer protocol |
| Kubernetes Node API for base capabilities | cluster/platform reuse | I0/I7 | no custom hardware daemon for basic facts |
| Node Feature Discovery only on deeper capability need | platform reuse trigger | I7 trigger | do not write hardware probe daemon |
| node-problem-detector before custom deep detector | incidents/cluster/platform reuse | I7 | do not rewrite kernel/runtime problem detector |
| system-upgrade-controller before custom K3s upgrader | cluster/platform reuse | I7 | no custom binary-upgrade scheduler |
| metrics-server current CPU/memory | cluster/platform reuse | I0/I7 | no custom current-resource collector |
| node_exporter historical machine metrics only when required | cluster/platform reuse | I7 trigger | no historical stack without product need |
| kube-state-metrics historical object metrics only when required | cluster/platform reuse | I7 trigger | same |
| Headlamp optional expert escape hatch | cluster UI/platform reuse | optional | do not rebuild Kubernetes Dashboard/CRD browser into AWP |

## Telemetry / Reliability

| Decision | Canonical spec coverage | Realization | Anti-rebuild consequence |
|---|---|---|---|
| AWP/PostgreSQL business events | event/audit specs | I0 | telemetry never becomes product truth |
| OTel API/SDK-compatible instrumentation | event/audit/realtime + platform reuse | I0 interface | no proprietary telemetry protocol |
| Collector optional | platform reuse/reliability | trigger | do not operate Collector until routing/batching/fan-out is needed |
| persistent metric/trace/log backend not bundled | reliability/platform reuse | deployment choice | use existing deployment telemetry backend |
| OpenSLO + Sloth/Pyrra only later reliability productization | reliability boundary/platform reuse | I9 | no SLO stack in early dogfood |

## Explicit Non-Baseline / Trigger Decisions

These decisions are not gaps. The canonical decision is **do not install/build them now**:

| Technology / family | Current disposition | Trigger / replacement boundary |
|---|---|---|
| Hatchet / Temporal / DBOS Conductor | absent | reopen durable workflow provider only if DBOS proves hard HA/operations gap |
| XState backend lifecycle authority | absent | typed AWP transitions remain canonical |
| Kubernetes Agent Sandbox | absent | evaluate only if warm-pool/hibernate/startup complexity justifies it |
| Kata | absent | explicit VM-backed isolation requirement |
| Kueue | absent | fair-share/quota/GPU/resource-flavor admission requirement |
| Cilium/Hubble | absent | native network policy/visibility demonstrably insufficient |
| Kyverno | absent | PSA/VAP/CEL materially insufficient for a required policy class |
| Falco / Tetragon | absent | runtime detection/response threat requirement; Tetragon only if Cilium creates leverage |
| OpenBao / ESO | absent | external secret authority or self-hosted dynamic secret authority requirement |
| SPIFFE/SPIRE | absent | portable cross-cluster/non-K8s workload identity requirement |
| vCluster | absent | namespace/runtime isolation insufficient for tenant boundary |
| Crossplane | absent | continuous Kubernetes-native infrastructure reconciliation explicitly required |
| OpenTofu | trigger-only | AWP becomes responsible for cloud/IaC provisioning |
| OpenFeature | absent | only real external flag-provider interoperability requirement; AWP activation policy stays typed/core |
| OPA | absent | only concrete policy class materially benefits from external policy engine |
| HolmesGPT | absent | deterministic Resolver + existing model/agent diagnostics first |
| Velero | absent | generic K8s object/PV backup/migration need |
| Dagger | absent baseline | adapt if project already owns it or later proof shows it deletes enough CI mechanics |
| persistent Prometheus/Jaeger/log stack | absent baseline | deployment lacks suitable backend and retention requires one |
| Redis/BullMQ, Kafka, NATS | absent | demonstrated queue/event requirement surviving PostgreSQL/DBOS/jobs delete-test |
| service mesh | absent | measured cross-service networking need after modular-monolith baseline changes |

## Feature / Policy / Incident No-Rebuild Decisions

```text
Feature activation
  AWP typed activation / landing policy
  OpenFeature is NOT baseline

Authorization/progression policy
  AWP typed Policy domain
  OPA is NOT baseline

Incident diagnosis
  deterministic ResolutionRecipe first
  existing model/agent diagnostics second
  HolmesGPT is NOT baseline
```

## Overdeck / Existing-Code Harvest Coverage

FOSS reuse alone does not prevent rebuilding **existing owner code**. The binding harvest plan covers that failure mode.

Every relevant Overdeck candidate receives one of:

```text
reuse-as-is
adapt
wrap
port-behavior
replace-with-platform
replace-with-foss
reference-only
outside-awp
retire
```

Required categories before their consuming increment:

```text
Git/workspace/publication helpers
factory/Fabro integration knowledge
account/model/provider routing helpers
configuration/auth/audit/realtime/health helpers
CI runner/check helpers
deployment-untangling and deterministic recovery scripts
cleanup/retry/checkpoint/WIP preservation helpers
machine enrollment/health/upgrade helpers
UI/deck-ui behavior absent from Astryx
CLI/control tools
undocumented special capabilities proven in code/scripts
```

No exact Overdeck source path is invented here. The current connected GitHub installation does not expose that private repository; exact paths/commits/dispositions remain a mandatory I0/I1 source preflight through an authorized source/workstation context.

## Platform Modules Already Verified From Current Main

A current connected-source inspection of `platform-modules/mod` confirms reusable package families exist for the planned seam. Package presence does not prove exact AWP semantic fit; it proves **do not implement the generic equivalent before testing these seams**.

| Package | Current package version seen | Useful exported seams |
|---|---:|---|
| `@platform-modules/db` | `0.3.0` | root, health, locking, PostgreSQL adapters, PGlite |
| `@platform-modules/auth` | `0.4.2` | root, API keys, OAuth provider, custom/Better Auth engines, OTP email |
| `@platform-modules/audit` | `0.0.3` | audit root |
| `@platform-modules/jobs` | `0.0.3` | root, CF queues, DB poll, outbox, DO runner |
| `@platform-modules/util` | `0.3.0` | config, logger, error reporter, idempotency, health, crypto/tokens and other utilities |
| `@platform-modules/realtime` | `0.0.1` | root, client, server |
| `@platform-modules/ai` | `0.0.1` | OpenAI-compatible, Anthropic, Google, mock, pricing, redaction |
| `@platform-modules/notifications` | `0.1.3` | email, webpush, inbox |
| `@platform-modules/search` | `0.0.5` | search root |
| `@platform-modules/ui-primitives` | `0.5.0` | DashboardShell, DataTable, QueryBoundary, virtual and common accessible primitives |
| `@platform-modules/ui-tokens` | `0.2.0` | tokens, theme engine, base/theme CSS |

The inspected `mod` main revision and exact export evidence are recorded by the I0/I1 reuse preflight. `mod` also contains an AWP-specific smoke that imports approved realtime/config/logger/error-reporter/idempotency seams by package subpath, providing stronger evidence than package-name presence alone.

## Remaining Verification, Not Design Gaps

```text
exact Overdeck source paths/commits and disposition inventory
exact current Platform package revisions consumed by AWP
consumer tests proving each selected Platform seam fits
Subrouter current account/token/routing capability test
exact FOSS versions and compatibility for I0/I1
Dev Container representative-project proof
Fabro/ACP/ARC/K3s integration proof
gVisor toolchain compatibility
DBOS crash/recovery proof
```

If a test reveals that a selected mechanic cannot satisfy the target contract, create a `Finding`/`Decision` and amend the provider choice. It does not authorize silent custom replacement.

## Conclusion

The canonical FOSS/provider decision register is now traceable into the implementation-facing specs and explicit no-rebuild/harvest gates. The remaining work before code is **evidence collection and exact source/provider verification**, not rediscovery of the architecture.