# Platform, FOSS and Proven-Capability Reuse Specification

**Status:** Approved target-state baseline — Advisor/Search reuse decisions integrated  
**First verification/consumption:** I0  
**Harvest authority:** [`../../plans/AWP-OVERDECK-CAPABILITY-HARVEST-PLAN.md`](../../plans/AWP-OVERDECK-CAPABILITY-HARVEST-PLAN.md)  
**Binding provider decisions:** [`../../plans/AWP-FOSS-DECISIONS.md`](../../plans/AWP-FOSS-DECISIONS.md)  
**Advisor/Search supplement:** [`../../plans/AWP-ADVISOR-SEARCH-DEPENDENCY-DECISIONS.md`](../../plans/AWP-ADVISOR-SEARCH-DEPENDENCY-DECISIONS.md)  
**Purpose:** Prevent AWP from rebuilding generic mechanics already available in project-native tooling, `platform-modules/mod`, proven Overdeck capability, standards/native primitives or selected FOSS while keeping AWP-specific product semantics inside AWP.

## Target State

AWP uses a mandatory **reuse-before-build** decision order:

```text
required AWP capability
  ↓
existing project-native mechanism?
  ↓
verified platform-modules/mod capability?
  ↓
vetted proven Overdeck capability/script/module?
  ↓
native Node/PostgreSQL/K3s/Kubernetes primitive?
  ↓
open standard / interchange format?
  ↓
small mature FOSS library/tool?
  ↓
mature external subsystem behind ProviderAdapter?
  ↓
only then consider custom generic mechanics
```

The purpose is minimum **total system complexity**, not minimum dependency count and not maximum FOSS count.

AWP owns semantic control-plane behavior. Reused systems own replaceable mechanics.

## Invariants From Day 1

- no generic helper/subsystem is custom-built without the reuse/delete-test;
- no temporary local copy of a fitting Platform capability becomes permanent by accident;
- no proven Overdeck capability inside AWP scope is silently discarded/rebuilt without a harvest disposition;
- no provider-native ID/type/lifecycle becomes the sole AWP domain identity;
- one selected authority per mechanic: do not run overlapping workflow/CI/policy/telemetry/search/memory systems without demonstrated need;
- standards/native mechanics are preferred before adding another running controller/service;
- current provider/package capability is verified before first consumption; old research is not install-time proof;
- project-owned tools/configuration are preserved where they already satisfy the contract;
- trigger-only infrastructure remains uninstalled until its trigger actually exists;
- reuse never imports Overdeck/deck-ui product identity into AWP;
- a UI library such as `cmdk` never becomes search/product-state authority;
- a model/chat framework never becomes AdvisorPersona/Decision/authorization authority.

## Mandatory Pre-Build Record

For every meaningful generic subsystem/custom helper, implementation review must be able to answer:

```text
capability required
project-native check
Platform check
Overdeck harvest check
native/standard check
FOSS/provider check
selected disposition
AWP semantic ownership
provider/mechanic ownership
version/revision actually consumed
consumer/integration test
known gap / exit path
```

If none of the candidates fits and custom code is needed, record why the code is AWP-specific or the smallest safe adapter rather than an accidental replacement subsystem.

## Platform Verification Rule

Before first consumption, verify the **actual current published** package/export/revision in `platform-modules/mod`.

For every consumed Platform seam record:

```text
package / exported subpath
pinned version/revision
capability used
AWP adapter/wrapper if any
consumer/integration test
ownership boundary
known gap
```

If a generic capability is missing and belongs in Platform, upstream it there. If behavior is AWP-specific, keep it in AWP rather than polluting Platform for reuse purity.

### Platform target map

| Concern | Required action before local equivalent |
|---|---|
| DB / transaction helpers | verify/reuse fitting Platform DB seam + PostgreSQL/Drizzle; AWP owns aggregates/transaction semantics. |
| Auth / API keys | verify/adapt Platform auth primitives; AWP owns Principal mapping/final authorization. |
| Audit | reuse Platform audit mechanics when fitting; AWP owns domain meaning/required attribution. |
| Bounded jobs / outbox | use `@platform-modules/jobs` when its current contract fits; do not create a second durable-workflow authority. |
| Configuration utilities | verify Platform config utilities before generic local parser/store helpers; AWP owns hierarchy/effective-value semantics. |
| Logging/error correlation | verify Platform logger/error helpers + OTel boundary; AWP owns redaction/domain correlation. |
| Realtime client/server | verify current Platform realtime capability before writing reconnect/subscription/cache plumbing. |
| AI/model utilities | verify `@platform-modules/ai` and current Subrouter/model/account capability before custom provider/token/routing/fallback mechanics. Advisor persona/scope/grounding remain AWP-owned. |
| Search | verify/reuse `@platform-modules/search` registry/provider/group/cursor mechanics before a custom generic search layer; AWP owns entity providers, authorization, ranking policy, commands and UX. |
| Notification / health | reuse only when exact current capability fits; AWP owns product projections/meaning. |
| UI primitives/data helpers | check Platform duplication before adopting another headless data/query/table layer. Astryx remains visual authority. |

## Overdeck Capability Harvest Rule

Before implementing equivalent behavior, inspect proven Overdeck sources listed by [`AWP-OVERDECK-CAPABILITY-HARVEST-PLAN.md`](../../plans/AWP-OVERDECK-CAPABILITY-HARVEST-PLAN.md).

Required categories include:

```text
CLI/control tools
factory helpers
Git/workspace/publication helpers
deployment-untangling scripts
CI/CD helpers
configuration/auth/realtime/health helpers
account/model routing helpers
cleanup/recovery/checkpoint logic
reusable modules
undocumented proven special capabilities
UI/deck-ui behavior missing from Astryx
```

Allowed dispositions are `reuse-as-is`, `adapt`, `wrap`, `port-behavior`, `replace-with-platform`, `replace-with-foss`, `reference-only`, `outside-awp`, or `retire`.

Botmaster, systray and workstation-personal automation remain outside core AWP.

## Canonical Reuse / Provider Map

| Concern | Baseline disposition | AWP owns |
|---|---|---|
| HTTP transport | Hono | contracts/application/domain semantics |
| Durable application workflow | DBOS + PostgreSQL | workflow meaning, IDs, policy/events, authoritative product state |
| Backend transitions | AWP typed transition tables/functions | lifecycle semantics/guards; no second persisted XState authority |
| Workspace mechanics | native Kubernetes Pod/PVC/ServiceAccount/NetworkPolicy | Workspace/ExecutionProfile/WIP lifecycle |
| Execution environment definition | project-native declarations + Development Container specification/official CLI where fitting | resolution, provenance, security ceilings, services, immutable Attempt profile |
| Existing project tests | preserve project-native Testcontainers/fixtures where present | orchestration/evidence meaning |
| Factory | Fabro | Plan/Task/FactoryRun semantics/progression |
| Agent protocol | ACP where supported + native AgentProvider escape hatch | AgentRun/Attempt/capabilities/provenance |
| MCP | official TypeScript MCP SDK | AWP tools/resources, auth/policy/audit semantics |
| VCS / forge | GitHub initial provider | Repository/ChangeSet/publication/merge semantics |
| CI | GitHub Actions + ARC on K3s | CIExecution/VerificationAuthority/gates; ARC only runner mechanics |
| Impact graph | adapt repo-native Nx/Turbo/Bazel/Pants graph when present; conservative fallback | capability/invariant interpretation |
| Deployment | Helm render + Kubernetes Server-Side Apply | Release/Environment/Deployment/policy/rollback meaning |
| Packaging | Helm for AWP Kubernetes distribution; Kustomize selectively for overlays | product release identity/desired deployment |
| Board interaction | Pragmatic Drag and Drop | Work/Kanban meaning and accessible non-drag actions |
| Graph interaction | React Flow | Factory/Planning/CI/provenance graph meaning |
| Charts | Chart.js | metric meaning + accessible table/text equivalents |
| Command palette | `cmdk` after React/Astryx/accessibility compatibility proof | AWP visual design, command registry, authorization and search data |
| Global entity search | `@platform-modules/search` + PostgreSQL/AWP read models | searchable entity providers, Principal/project scoping, ranking boosts, snippets, full Search UX |
| Advisor model/provider mechanics | `@platform-modules/ai` + existing Account/Model/Provider/Connection seams; verify current fit | AdvisorPersona/Thread, scope, context grounding, sources, proposal/action semantics, audit |
| Advisor realtime/chat plumbing | verify `@platform-modules/realtime` + Astryx AI-chat behavior before custom generic plumbing | advisor conversation semantics, persistence, source/proposal blocks, recovery |
| UI components | React + Astryx | AWP component identity/interaction; deck-ui only behavior/source harvest when needed |
| Contract description/diff | OpenAPI + oasdiff when stable consumer boundary exists | compatibility declarations/gate policy |
| Threat modeling | OWASP methodology + Threat Dragon when useful | trigger/risk/mitigation/Decision ownership |
| Supply-chain scan | Trivy baseline | Finding/evidence/policy relationships |
| SBOM | CycloneDX preferred, SPDX accepted; Syft only if it adds value | Artifact linkage/policy |
| Provenance | SLSA predicate + in-toto Attestation Framework | Artifact/build/run relationships |
| Static analysis interchange | SARIF when provider supports it | normalized Finding meaning |
| Test/coverage interchange | JUnit-style/common coverage formats where fitting | Check/evidence semantics |
| Signing/attestation | Cosign | policy/Artifact relationships |
| OCI artifact transport | ORAS | Artifact identity/retention semantics |
| Release preparation | repository-native scripts, Changesets, Release Please, semantic-release as adapters when already/fitting | Release eligibility/identity/authorization/provenance |
| External delivery events | CloudEvents; CDEvents mapping where vocabulary fits | internal AWP business-event meaning |
| Machine install/join | official K3s installer; k3sup CE optional helper | MachineEnrollment lifecycle, policy, audit, verification |
| Machine hardware facts | Kubernetes Node basic facts; Node Feature Discovery only when deeper facts required | MachineCapability normalization/meaning |
| Node problem detection | node-problem-detector before custom detector | Incident/health interpretation/remediation policy |
| K3s upgrades | system-upgrade-controller before custom upgrade executor | MachineLifecycle/ClusterUpgrade intent/approval/progress |
| Current node CPU/memory | K3s metrics-server | semantic Cluster capacity/read model |
| Historical node metrics | node_exporter when historical OS/filesystem/load metrics are required | UI/read-model meaning |
| Historical K8s object metrics | kube-state-metrics when required | product relationship/health meaning |
| Expert raw Kubernetes UI | Headlamp optional deep-debug escape hatch | AWP Cluster product UX remains semantic |
| Secret material | `CredentialReference -> SecretStore -> Kubernetes Secrets` initially | connection/binding/policy/audit; no raw secret config |
| Object storage | external S3-compatible service first; SeaweedFS optional self-host profile | ObjectStoreProvider policy/retention/use semantics |
| Registry | GHCR initially; zot optional self-host; Harbor later enterprise trigger | ArtifactRegistryProvider/product identity |
| PostgreSQL operations | normal external/managed endpoint preferred; CloudNativePG+Barman optional self-host profile | schema/migrations/backup policy/restore authorization |
| Telemetry | OTel-compatible instrumentation/export; Collector/backend optional | business state/events/audit and semantic read models |
| Reliability | OpenSLO + Sloth/Pyrra when I9/productization requires it | ReliabilityPlan/policy consequences |
| Architecture conformance | dependency-cruiser where fitting | boundary rules/exemptions |

## Advisor / Search Anti-Rebuild Rule

### Search

Before custom global-search infrastructure:

```text
verify current @platform-modules/search export/behavior
verify PostgreSQL/read-model search satisfies baseline relevance/scale
verify cmdk with actual React/Astryx/focus/accessibility stack
```

Then build only AWP-specific entity providers/scoping/ranking/UI.

Do not make `cmdk` hold the entire product entity corpus. Static commands/navigation can use local filtering; global entity search uses server-ranked authorized results with cmdk filtering disabled.

Do not add Elasticsearch/OpenSearch/Meilisearch/Typesense/vector DB by default. A specialized search service requires measured scale/relevance/semantic-search evidence and an explicit Decision.

### Advisor

Before generic conversation/model plumbing:

```text
verify @platform-modules/ai provider helpers
verify @platform-modules/realtime behavior
verify Astryx AI-chat behavior/primitives
reuse Account/Model/Provider + Connection boundaries
```

Do not add a generic agent framework as domain authority just to implement tool-capable chat. A future provider library may execute model/tool loops behind `AdvisorPersona`/application semantics if a spike proves useful.

Do not add a separate vector-memory database as baseline Advisor memory. AdvisorThread persists conversation in AWP/PostgreSQL; material Project knowledge belongs in canonical ProjectVision/Decision/Plan/etc. Semantic retrieval can be evaluated later through the Search/provider seam if measured need appears.

## Account / Subrouter Anti-Rebuild Rule

`Subrouter` is a **reuse candidate/direction**, not an unconditional domain dependency.

Before implementing any custom account/model mechanics for:

```text
token ownership/refresh
account health/quota observation
account selection/routing
sticky assignment
fallback/rotation
shared-account concurrency
```

inspect and test the current Platform/Subrouter capability. If it satisfies the AWP `AccountProvider` / selection contract, wrap/adapt it. If it does not, document the exact gap before custom mechanics are authorized.

Do not hard-code Subrouter-specific IDs into `Account`, `Model`, `Provider` or `Attempt`.

## Project-Native-First Rules

AWP does not normalize projects by replacing mechanisms that already work.

Examples:

```text
existing .devcontainer/Docker/Compose/mise/Devbox -> inspect/adopt
existing Testcontainers                         -> preserve
existing Nx/Turbo/Bazel/Pants graph            -> adapt
existing release/version scripts                -> preserve/adapt
existing CI workflows/checks                    -> reconcile/consume
```

AWP adds semantic ownership/explanation only where needed.

## UI Reuse Rule

Astryx is the primary component source.

If Astryx lacks a required complex behavior:

```text
inspect proven deck-ui/Overdeck source
  -> preserve useful behavior/accessibility/edge cases
  -> port/adapt as AWP-owned component
  -> remove deck-ui/Overdeck runtime identity
```

`deck-ui` is never a runtime fallback library or architectural dependency.

`cmdk` is a narrow exception for command-palette interaction mechanics, not a second visual component system. Style/composition remains AWP/Astryx owned.

## Trigger-Only / Deferred Infrastructure

Do not add these because a full target spec mentions the future seam:

```text
Kubernetes Agent Sandbox
Kata
Kueue
Cilium/Hubble
Kyverno
OpenBao / External Secrets Operator
Flux / Flagger
vCluster
OpenTofu / Crossplane
SPIFFE/SPIRE
self-host telemetry backend stack
specialized search/vector service
advisor vector-memory service
generic multi-agent framework as control-plane authority
zot/Harbor/SeaweedFS unless self-host profile requires them
other operators/controllers without a demonstrated contract gap
```

Each adoption requires the trigger/Decision in the binding FOSS/reuse register and must delete more custom/operational complexity than it adds.

## Explicit Negative Register

Do not introduce by default:

```text
Redis / BullMQ
Kafka
NATS
service mesh
second API gateway
multiple workflow authorities for the same work
multiple CI engines without an actual provider need
multiple chart libraries
Gatekeeper + Kyverno together
Backstage as AWP product model
custom generic Git server
custom CI runner autoscaler
custom model-provider OAuth/token platform without Platform/Subrouter check
custom GitOps reconciliation engine
custom telemetry storage backend
custom command-palette keyboard engine
custom generic search registry before Platform search proof
browser-preloaded global AWP entity index
advisor-only mutation authority
advisor-specific credential store
advisor-only canonical project memory database
```

## Increment Realization

| Increment | Reuse work |
|---|---|
| I0 | perform I0/I1 Overdeck harvest inventory; verify/pin Platform DB/auth/audit/jobs/config/logger/realtime/model seams actually consumed; pin selected FOSS versions/capabilities; prove no-rebuild dispositions. |
| I1 | Fabro/ACP/GitHub/ARC/K8s/DevContainer/project-env integration proof; consume harvested WIP/recovery/publication knowledge. Advisor/Search remain unimplemented. |
| I2 | Planning/work/UI reuse verification before first implementation. |
| I3 | verify/pin `cmdk`, `@platform-modules/search`, Platform AI/realtime and Astryx chat behavior before Project Manager/Search implementation. |
| I4 | Factory/Agent observability harvest + AWP Advisor cross-project analytics/provider proof. |
| I5 | CI graph/check/format/provider reuse verification; R4 activates at stable consumer boundaries. |
| I6 | release tooling, supply-chain standards, deployment provider/resolver harvest and reuse verification. |
| I7 | K3s installer/upgrade/NFD/NPD/metrics/Headlamp checks before custom cluster mechanics. |
| I8 | vetted Overdeck deterministic resolver recipes before new generic resolver library. |
| I9 | OpenSLO/reliability and public adapter/plugin/provider SDK choices; enterprise-triggered providers only. |

## Current Implementation State

Target reuse/ownership/no-rebuild map is explicit, including Advisor/Search. Exact package versions, current Platform exports and Overdeck source paths are verified during the pre-build/consuming-increment harvest rather than invented from old planning text.

Current pre-run inspection has already identified `@platform-modules/search` as a reuse candidate and `cmdk` as the selected I3 interaction direction; the I3 consuming proof remains mandatory.

## Deferred Realization

A provider/library being named here does not activate its product capability earlier than the Increment Realization Matrix.

## Temporary Dogfood Behavior

CLI/manual configuration may temporarily operate a canonical provider seam before polished UI exists. Temporary behavior must not bypass the same domain state, auth/policy, audit or secret boundaries.

I1 does not ship a throwaway generic Advisor chat or client-only global Search merely because those future contracts now exist.

## Decisions / ADRs

Binding general dispositions live in [`AWP-FOSS-DECISIONS`](../../plans/AWP-FOSS-DECISIONS.md); Advisor/Search dependency decisions live in [`AWP-ADVISOR-SEARCH-DEPENDENCY-DECISIONS`](../../plans/AWP-ADVISOR-SEARCH-DEPENDENCY-DECISIONS.md). Research alternatives remain evidence in [`AWP-FOSS-REUSE-DEEP-RESEARCH`](../../plans/AWP-FOSS-REUSE-DEEP-RESEARCH.md). New material dependency/provider changes require a Decision and must update this spec/increment map.

## Acceptance

Before a generic subsystem is authored in AWP, a reviewer can trace:

```text
required product semantic
-> Platform/Overdeck/native/standard/FOSS checks
-> selected mechanic/provider
-> why custom AWP code remains
-> exact ownership boundary
-> increment first consuming it
-> integration evidence
```

If that trace cannot be produced, custom implementation is not ready.