diff --git a/docs/architecture/TRD.md b/docs/architecture/TRD.md new file mode 100644 index 00000000..18cf8bda --- /dev/null +++ b/docs/architecture/TRD.md @@ -0,0 +1,149 @@ +# Wardnet Technical Requirements Document + +Status: canonical technical requirements for protected-main Wardnet development. This document describes required architecture and acceptance boundaries; it does not promote unmerged branches or foreign-owner mutable heads to released dependencies. + +## Technical authority + +Wardnet is a Rust-first gateway, WAF/IDS-adjacent SOC control plane, and Agent Artifact Admission authority. The root crate owns HTTP/control-plane application behavior and `crates/waf-ids-core` owns pure domain logic. Proven external security engines and CWL sibling systems remain integration dependencies rather than code to duplicate inside Wardnet. + +Source-of-truth order for a conflict is: protected code and executable tests; accepted ADRs; `docs/architecture.md` and security/operations/release documentation; this TRD; product requirements. A requirement that is not yet implemented must stay visibly future/acceptance work rather than being described as protected-main capability. + +## Bounded contexts + +Wardnet owns the following bounded contexts: + +- Gateway Routing and Enforcement: route selection, monitor/block decisions, request limits, and gateway event production. +- SOC Evidence and Operations: security events, KPIs, threat-feed freshness, support evidence, and operator-facing control state. +- Agent Artifact Admission: artifact/evidence binding, policy evaluation, admission decision, reason, and auditable receipt. +- Security Policy and Evidence: Wardnet-owned policy semantics and the evidence needed to justify Wardnet decisions. +- Runtime Configuration: non-secret process-edge configuration captured once as an immutable `RuntimeConfiguration` snapshot when that branch reaches protected main. +- Credential Bootstrap: secret-bearing bootstrap material owned by `CredentialRegistry`. + +Persistence, PostgreSQL authority, advanced SIEM/SOAR behavior, optional integrations, and other active-stack work are not considered protected-main truth until their exact changes reach protected main. + +## Runtime and implementation requirements + +### Language and dependency policy + +Gateway, DNSBL, admission, and high-throughput control-plane hot paths are Rust-first. New equivalent security engines must not be invented when a proven engine or standard adapter is available. Dependencies must be pinned/locked according to the repository build contract and security scanned on the exact candidate head. + +Cross-repository integration uses **released contracts only**. Wardnet must not copy sibling source, query sibling databases with cross-service SQL, or bind production behavior to a mutable PR/default-branch implementation. Versioned HTTP/event/evidence contracts are preferred at service boundaries. + +### Runtime configuration and secrets + +Secret-bearing configuration is bootstrapped into `CredentialRegistry`. Environment variables or secret files are bootstrap transport, not handler-time secret authority. Administrator secrets must satisfy the repository's strict admission rules before they can authorize management writes. + +Non-secret runtime settings are converging on an immutable `RuntimeConfiguration` snapshot. When that architecture reaches protected main, `run_from_env` must obtain one validated snapshot at the process edge and pass values inward without later direct environment reads. `WAF_IDS_CREDENTIALS_PATH`, `ADMIN_TOKEN`, and `ADMIN_TOKENS` remain outside `RuntimeConfiguration` because they are credential-bootstrap concerns. + +A non-loopback bind must fail closed before listener readiness if no write-capable, header-presentable administrator principal exists. Read-only principals, TLS, or an upstream identity layer do not substitute for Wardnet's own write-auth bootstrap prerequisite. Loopback development mode remains explicitly distinguishable in health/readiness evidence. + +### API and domain alignment + +HTTP/API types, domain invariants, persistence representation, fixtures, and tests must evolve together. Management mutations are authenticated/authorized upserts where the current domain defines upsert identity. DNSBL values must preserve the `127.0.0.0/8` response-code invariant and RFC 5782-compatible export behavior. + +Untrusted request bodies must be bounded before expensive parsing or processing. Rate-limit semantics, event retention, persistence failure behavior, shutdown/flush behavior, and authorization distinctions are testable contracts, not incidental implementation details. + +No API response may claim stronger release, security, freshness, or provenance status than the underlying evidence proves. + +## Agent Artifact Admission requirements + +Wardnet's admission input must be capable of representing an immutable artifact identity, normally a cryptographic digest, plus required evidence references. Policy evaluation produces a deterministic Wardnet decision record with at least artifact identity, policy identity/version, evaluated evidence identities, decision, reason, timestamp, and Wardnet runtime/release identity where available. + +Missing mandatory evidence fails according to policy and may not be treated as success because an external owner is unavailable. External execution/sandbox, egress, orchestration, and guardrail details stay outside the admission implementation unless represented by a released contract/evidence receipt. + +Canonical foreign owners are: + +- `quarantine-sandbox-runtime`: hostile workload isolation, ephemeral execution workspace, resource/syscall/filesystem controls, cleanup/recovery, and artifact-analysis execution profiles. +- `EgressWeave`: outbound destination and transport authorization/control semantics. +- `contextual-orchestrator`: LLM/model/tool orchestration and its released API. +- `appguardrail`: application/agent guardrail implementation and its released evidence contracts. + +Wardnet validates and evaluates foreign receipts but does not reimplement these owners. + +## LLM boundary + +All production LLM use goes through a released `contextual-orchestrator` API. Wardnet owns the security question, evidence supplied, deterministic policy surrounding the call, and treatment of the response. `contextual-orchestrator` owns model selection, provider routing, workflow/reasoning/tool policy, and model-runtime execution. + +LLM output is advisory unless a Wardnet policy explicitly defines a bounded use that is independently supported by deterministic evidence. Malformed, unsupported, stale, or unavailable orchestration responses fail closed for any security-critical decision path. + +GitHub Actions model workflows must use organization-owned exact-SHA reusable workflows and the approved gateway-token path. Wardnet must not add a local clone of central OpenCode, Strix, Noema, CodeQL, SAST, or security-review logic. + +## Performance requirements + +The realistic asynchronous Wardnet-owned buyer path has a target of **p95 <= 20 ms** for processing attributable to Wardnet. Benchmarks/load tests must identify the endpoint/path, concurrency, payload shape, warmup, sample size, hardware/runner class, and whether external network calls are excluded or separately reported. + +External LLM, threat-intelligence, sandbox, egress, or other service latency must not be hidden inside a local-processing claim. A performance regression must be reproduced with a bounded load/E2E case before optimization; throughput work must not weaken authorization, evidence binding, or fail-closed behavior. + +## Persistence and transaction requirements + +Protected main currently supports in-memory or JSON-file state and uses write-to-temporary-sibling plus atomic rename for file persistence. Documentation must not state that PostgreSQL is shipped until that stack reaches protected main. + +For future database-backed work, application code must not hold explicit database locks or long-lived transactions while performing LLM calls, external I/O, sandbox execution, or long-running computation. Read necessary state, end the database transaction, perform external/expensive work, then open a bounded write transaction that revalidates the required optimistic/concurrency predicate before commit. Cross-service SQL remains forbidden. + +## Security requirements + +Authentication, authorization, evidence integrity, and network/external-owner trust boundaries are independent controls. A stronger control in one layer does not erase a required control in another. + +Security-sensitive comparisons and credential parsing must preserve the protected fail-closed semantics and tests. Security findings are repaired at their causal owner. Central `.github` workflow/runner/verdict defects are handed to the central owner with exact repository/base/head/run/job evidence; Wardnet source is not churned merely to obtain another dispatch. + +Threat-feed and adapter acquisition must validate destination/transport expectations without absorbing `EgressWeave` policy ownership. Hostile-workload execution is requested through the sandbox owner's released boundary rather than implemented inside Wardnet. + +## UI and accessibility requirements + +Material operator UI work must retain reusable design/token/component evidence plus Figma/Storybook evidence and automated buyer-flow acceptance for normal, loading, empty, error, permission, responsive, keyboard, and accessibility states. The console must remain usable at mobile, intermediate, and desktop widths without clipping or undersized critical targets. + +Text layout must tolerate KO/EN/JA/ZH/VI/ES/DE/FR content characteristics. A locale robustness test is not a claim that all translations are shipped. Security/performance/readiness copy must be evidence-backed. + +## Test and coverage requirements + +At minimum, exact-head repository acceptance retains: + +- `cargo fmt --check`; +- `cargo test --locked --workspace`; +- `cargo clippy --locked --workspace --all-targets -- -D warnings`; +- fuzz/property mirrors for untrusted-input surfaces; +- hostile tests for security boundaries and failure paths; +- repository-owned production Rust statement/branch/edge coverage and public rustdoc coverage at the live required threshold, with the commercial-development target of 100%; +- realistic async k6/E2E coverage for buyer-critical paths when performance or deployment behavior is material. + +A predecessor SHA, synthetic merge ref when source-head proof is required, queued/cancelled/skipped job, or model-only review is not exact-head GREEN evidence. + +## Release and supply-chain requirements + +A release-ready protected head requires aligned version metadata and CHANGELOG, deterministic package construction, an SBOM, provenance/attestation, reproducibility evidence, rollback procedure/evidence, a protected exact source head, immutable tag, and immutable GitHub release/package publication. No immutable release may be claimed while the release inventory is empty. + +`SBOM` and `provenance` are release artifacts, not prose checkboxes. Their identities must bind to the same artifact/source candidate being promoted. Security/CodeQL/review gates required by live protection remain fail-closed; ordinary failed or queued checks are not emergency-bypass conditions. + +## Documentation and architecture synchronization + +Changes that alter product behavior, bounded-context ownership, API/evidence contracts, security boundaries, persistence, deployment, operator workflows, or release semantics must update the relevant PRD/TRD/UML/ADR/architecture/security/ops/test/release documentation in the same causal lane or an explicitly owned dependent lane. + +`docs/product-technical-gap-baseline.md` has a dedicated writer lane and must not be concurrently edited by this documentation-contract PR. Accepted ADR consolidation remains owned by its existing lane. Context Fabric owns writes to `context-graph-contracts` and `enterprise-architecture-core`; Wardnet inventories those repositories read-only and consumes only immutable releases/contracts when available. + +## Standards traceability + +The following authoritative references apply together with narrower references already recorded in `docs/security/`, `docs/doctoring/`, ADRs, and feature-specific design records. Research rationale is not implementation or release evidence. + +### Academic requirement mapping + +| Requirement | Research or decision record | Technical boundary supported | +| --- | --- | --- | +| bot-risk detection, **bot-risk evidence calibration and ownership boundary** | [`docs/adr/2026-09-05-anti-bot-acquisition-boundary.md`](../adr/2026-09-05-anti-bot-acquisition-boundary.md) | Applies only to inbound bot-risk/security evidence, calibration/provenance, and responsibility separation. It explicitly does not authorize browser challenge handling, outbound anti-bot acquisition, a particular detection algorithm, or mutable foreign-owner coupling. | +| load balancing | Eisenbud et al. (2016), *Maglev: A Fast and Reliable Software Network Load Balancer* — https://www.usenix.org/conference/nsdi16/technical-sessions/presentation/eisenbud | Supports software load-balancer architecture that spreads traffic across endpoints, retains connection-consistent mapping, and handles backend/reconfiguration churn. Wardnet does not claim Maglev's exact algorithm or Google-scale performance. | +| rate limiting | Parekh and Gallager (1993), *A generalized processor sharing approach to flow control in integrated services networks: The single-node case* — https://doi.org/10.1109/90.234856 | Supports explicit rate-based admission/fairness and bounded delay/rate reasoning. The concrete Wardnet limiter remains defined by API/domain tests and must not claim GPS/PGPS semantics unless implemented and measured. | +| high-throughput control plane | Curtis et al. (2011), *DevoFlow: Scaling Flow Management for High-Performance Networks* — https://doi.org/10.1145/2043164.2018466 | Supports minimizing avoidable controller interactions and keeping common-case processing near the fast path while retaining sufficient operational visibility. It does not make Wardnet an OpenFlow/DevoFlow implementation or override Wardnet's security evidence requirements. | + +Research rationale is not implementation or release evidence. These sources constrain design choices; exact source, hostile tests, k6/E2E measurements, protected-base compatibility, required security/review gates, and immutable release artifacts remain the acceptance authority. + +### References + +- Curtis, A. R., Mogul, J. C., Tourrilhes, J., Yalagandula, P., Sharma, P., & Banerjee, S. (2011). DevoFlow: Scaling flow management for high-performance networks. *ACM SIGCOMM Computer Communication Review, 41*(4), 254–265. https://doi.org/10.1145/2043164.2018466 +- Eisenbud, D. E., Yi, C., Contavalli, C., Smith, C., Kononov, R., Mann-Hielscher, E., Cilingiroglu, A., Cheyney, B., Shang, W., & Hosein, J. D. (2016). Maglev: A fast and reliable software network load balancer. In *13th USENIX Symposium on Networked Systems Design and Implementation (NSDI 16)* (pp. 523–535). USENIX Association. https://www.usenix.org/conference/nsdi16/technical-sessions/presentation/eisenbud +- Levine, J., & Vixie, P. (2010). *DNS blacklists and whitelists* (RFC 5782). Internet Engineering Task Force. https://doi.org/10.17487/RFC5782 +- National Institute of Standards and Technology. (2020). *Zero trust architecture* (NIST SP 800-207). https://doi.org/10.6028/NIST.SP.800-207 +- National Institute of Standards and Technology. (2022). *Secure software development framework (SSDF) version 1.1: Recommendations for mitigating the risk of software vulnerabilities* (NIST SP 800-218). https://doi.org/10.6028/NIST.SP.800-218 +- OWASP Foundation. (2025). *OWASP Application Security Verification Standard 5.0.0*. https://owasp.org/www-project-application-security-verification-standard/ +- Parekh, A. K., & Gallager, R. G. (1993). A generalized processor sharing approach to flow control in integrated services networks: The single-node case. *IEEE/ACM Transactions on Networking, 1*(3), 344–357. https://doi.org/10.1109/90.234856 +- World Wide Web Consortium. (2023). *Web Content Accessibility Guidelines (WCAG) 2.2*. https://www.w3.org/TR/WCAG22/ + +No new third-party paper PDF is committed by this documentation lane because repository redistribution permission for the cited versions has not been independently established. Where redistribution is not established, this TRD retains the citation, stable locator, and scoped summary instead. If implementation evidence conflicts with prose, fix the prose or implementation causally; do not preserve an outdated requirement merely because it is written here. \ No newline at end of file diff --git a/docs/architecture/wardnet-control-plane.puml b/docs/architecture/wardnet-control-plane.puml new file mode 100644 index 00000000..6e3da850 --- /dev/null +++ b/docs/architecture/wardnet-control-plane.puml @@ -0,0 +1,92 @@ +@startuml +!theme plain +skinparam componentStyle rectangle +skinparam shadowing false +skinparam defaultTextAlignment left + +title Wardnet gateway, SOC, admission, and external-owner boundaries + +actor "Security operator" as operator +actor "Gateway client" as client + +rectangle "Wardnet" as wardnet { + component "Admin / operations console" as admin + component "Gateway and SOC Control Plane" as gateway + component "Agent Artifact Admission" as admission + component "security evidence and policy" as evidence + component "CredentialRegistry\n(secret bootstrap authority)" as credentials + component "RuntimeConfiguration\n(non-secret immutable snapshot target)" as runtime + database "Wardnet state\nprotected main: memory / JSON" as state +} + +cloud "quarantine-sandbox-runtime\ncanonical hostile-workload runtime owner" as sandbox +cloud "EgressWeave\ncanonical egress authorization owner" as egress +cloud "contextual-orchestrator\ncanonical LLM orchestration owner" as orchestrator +cloud "appguardrail\ncanonical guardrail implementation owner" as appguardrail + +rectangle "Context Fabric authorities\nread-only inventory from Wardnet" as context_fabric { + component "context-graph-contracts" as cgc + component "enterprise-architecture-core" as ea +} + +operator --> admin : operate / inspect +client --> gateway : gateway request +admin --> gateway : management API +admin --> evidence : events / KPI / readiness / support evidence + +gateway --> credentials : authenticate / authorize writes +gateway --> runtime : consume validated settings +gateway --> state : route / indicator / DNSBL / event state +admission --> evidence : bind evidence + policy decision +admission --> state : decision / audit state + +evidence ..> sandbox : consume released evidence receipt only +admission ..> sandbox : request released isolation / analysis contract + +gateway ..> egress : consume released outbound policy / receipt only +admission ..> egress : evaluate released egress evidence when policy requires + +evidence ..> appguardrail : consume released guardrail evidence only +admission ..> appguardrail : evaluate released guardrail receipt + +gateway ..> orchestrator : released API only for LLM-assisted SOC work +evidence ..> orchestrator : advisory model result + provenance + +wardnet ..> cgc : released contract only; no mutable-head dependency +wardnet ..> ea : released projection only; no mutable-head dependency + +note right of sandbox +Wardnet does not copy sandbox runtime logic. +Execution isolation, resource/syscall/filesystem +controls, ephemeral workspace, cleanup/recovery, +and artifact-analysis execution profiles stay here. +end note + +note right of egress +Wardnet does not implement EgressWeave policy. +No cross-service SQL or source copy. +end note + +note right of orchestrator +All LLM model/provider/tool/workflow selection +stays in contextual-orchestrator. +Wardnet owns the security question and treatment +of returned evidence, not model routing. +end note + +note bottom of context_fabric +At the protected baseline for this diagram, +CGC and EA have no immutable GitHub release. +Wardnet therefore inventories them read-only +and does not bind protected behavior to their +mutable develop branches. +end note + +legend left + Solid arrows: Wardnet-owned runtime/data relationships. + Dotted arrows: external released-contract/evidence relationships. + This diagram is an ownership/dependency view, not a claim that every + optional integration is shipped in protected main. +endlegend + +@enduml diff --git a/docs/product/PRD.md b/docs/product/PRD.md new file mode 100644 index 00000000..1d73bfd5 --- /dev/null +++ b/docs/product/PRD.md @@ -0,0 +1,112 @@ +# Wardnet Product Requirements Document + +Status: canonical product scope for protected-main behavior and bounded commercial development. + +This document describes Wardnet as it is intended to be bought, operated, evaluated, and released without promoting unmerged feature branches to shipped truth. Implementation detail remains subordinate to `docs/architecture.md`, accepted ADRs, the threat model, runbooks, tests, and protected code. + +## Product authority + +Wardnet owns three related product responsibilities: + +1. **Gateway and SOC Control Plane** — route management, request security decisions, operational event/KPI visibility, DNSBL publication, management APIs, and the operator-facing control surface around those capabilities. +2. **Agent Artifact Admission** — Wardnet owns the admission decision, security evidence envelope, policy evaluation, decision/audit record, and the buyer-visible reason that an agent artifact is accepted, denied, or held. +3. **Security evidence and policy** — Wardnet owns the evidence and policy required to justify its gateway, SOC, and admission decisions, including provenance of the decision inputs that Wardnet itself is authoritative for. + +Wardnet is not the canonical implementation owner for every security mechanism it consumes. Product boundaries below are mandatory so that a buyer receives one coherent control plane without duplicated enforcement engines. + +## Buyer problems + +A buyer must be able to operate a security gateway and SOC-facing control plane without guessing which repository owns a decision, which evidence justified it, or whether an automated decision silently bypassed a missing dependency. The product therefore prioritizes fail-closed security boundaries, explicit ownership, deterministic evidence, and deployable operational recovery over feature breadth. + +The primary buyer outcomes are: + +- a gateway request is routed, monitored, or blocked under an inspectable Wardnet policy decision; +- security operators can inspect events, threat-feed freshness, KPIs, readiness, and support evidence without requiring repository knowledge; +- management writes require a usable write-capable administrator credential whenever the service is bound beyond numeric loopback; +- agent artifacts are admitted only through Wardnet's policy/evidence boundary, while execution isolation and other foreign-owner controls remain external dependencies; +- security and commercial evidence is bound to the evaluated artifact, runtime, configuration, and release rather than inferred from stale predecessor results; +- operational failure is diagnosable and recoverable without disabling a security gate. + +## Product requirements + +### Gateway and SOC operations + +The protected product must keep route, indicator, DNSBL, event, KPI, readiness, and support-evidence surfaces coherent with the same underlying security state. Block/monitor behavior remains route-scoped. DNSBL publication follows the repository's RFC 5782-compatible contract. Threat-intelligence freshness is buyer-visible and stale feeds cannot be represented as fresh evidence. + +Wardnet integrates proven security engines and formats where they are authoritative rather than inventing substitutes. OWASP CRS/Coraza, Suricata, STIX/TAXII, MISP, and OpenCTI are integration directions or adapters; their existence in documentation does not by itself mean every engine is embedded in protected main. + +### Management security + +Numeric loopback operation may run in development mode without a write credential. Any other listener must fail closed before readiness unless Wardnet has a write-capable administrator principal whose secret can actually be represented in the HTTP authentication header contract. Read-only credentials do not satisfy this prerequisite. + +Authentication and authorization are distinct product states. Missing/invalid authentication and authenticated-but-insufficient authority must remain distinguishable without leaking expected credentials. Secrets are bootstrap inputs to `CredentialRegistry`; runtime handlers do not treat raw process environment as the credential authority. + +### Agent Artifact Admission + +Wardnet owns admission, not hostile workload execution. An admission record must be able to bind the artifact identity/hash, policy version or identity, relevant evidence references, decision, reason, time, and the Wardnet release/configuration that produced the decision. A missing required evidence class fails closed according to policy; it is not converted into a positive decision merely because an external service is unavailable. + +The following implementation authorities remain external: + +- `quarantine-sandbox-runtime` owns hostile-workload isolation and execution profiles, including application-service isolation and artifact-analysis runtime controls. +- `EgressWeave` owns outbound destination/transport authorization and egress control semantics. +- `contextual-orchestrator` owns LLM orchestration, model/tool policy, reasoning/workflow selection, and the released API Wardnet may call for LLM-assisted SOC work. +- `appguardrail` owns its guardrail implementation surface. Wardnet consumes released evidence/contracts where a Wardnet policy requires them; it does not copy that logic into the gateway. + +Wardnet may display, validate, bind, and evaluate released evidence from those owners. It must not source-copy their implementation, perform cross-service SQL, or depend on mutable sibling PR heads. + +### Evidence and explainability + +A buyer-visible security decision must identify enough evidence to reproduce why the decision was made. Evidence must distinguish observed fact, policy evaluation, external-owner receipt, and advisory model output. LLM output is never the sole authority for a security decision that requires deterministic evidence. + +All LLM use is through a released `contextual-orchestrator` API contract. Repository or GitHub Actions automation must not introduce a second model-routing implementation in Wardnet. + +### Operator UI + +The `/admin` surface is an operations console, not a marketing landing page. Material UI work must use reusable design/tokens/components and retain Figma/Storybook evidence for the implemented design system and buyer-critical surfaces. Buyer-critical flows must cover normal, loading, empty, error, permission-denied, responsive, and keyboard/accessibility states. + +Text-bearing material UI must remain robust for KO/EN/JA/ZH/VI/ES/DE/FR content expansion and wrapping even when a locale is not yet shipped as a complete translation. UI claims about security, performance, readiness, or release state must come from product evidence, not decorative copy. + +## Quality and acceptance + +A change is not product-complete because its happy path works. Depending on the affected bounded context, acceptance includes hostile-input tests, permission/authentication cases, deterministic failure-path tests, exact-head CI/security evidence, API/schema alignment, operational recovery, and documentation updates. + +Rust remains the preferred implementation language for gateway, DNSBL, high-throughput control-plane, and admission hot paths. Owned production Rust must maintain complete rustdoc/test/edge coverage according to the repository's live coverage contract. The realistic asynchronous buyer path has a performance objective of p95 no greater than 20 ms for Wardnet-owned processing; external network/service latency must be measured and reported separately rather than hidden inside that claim. + +## Release and commercial truth + +Protected `main` is source truth, but it is not by itself an immutable commercial release. A release-ready candidate requires a version and CHANGELOG entry aligned with the source, reproducible package construction, SBOM, provenance/attestation, rollback evidence, a protected exact head, an immutable tag/release, and all then-live required gates terminal-valid. Stale, predecessor, queued, skipped, cancelled, or synthetic evidence is non-passing. + +As of the protected baseline used to create this document (`main@f8260f1e03836039ff9463dd99fa982e4e270c4b`), the GitHub Releases inventory is empty. Product documentation must therefore not describe an immutable Wardnet release as already shipped. + +## Architecture and contract boundaries + +Wardnet consumes foreign capabilities only through released contracts. `context-graph-contracts` and `enterprise-architecture-core` are architecture/context authorities owned by the Context Fabric workstream; Wardnet inventories them read-only while that writer owns them. With no immutable release available from either repository at this baseline, Wardnet does not bind protected product behavior to their mutable default branches. + +The technical requirements are canonicalized in `docs/architecture/TRD.md`; the component/dependency view is `docs/architecture/wardnet-control-plane.puml`. Accepted decisions remain in `docs/adr/`, and `docs/product-technical-gap-baseline.md` remains the separate technical-gap ledger when its owner lane lands. + +## Standards and research traceability + +These references constrain the product requirements together with the repository's more specific doctoring/security citations. Research rationale is not implementation or release evidence. + +### Academic requirement mapping + +| Requirement | Research or decision record | Scope of use | +| --- | --- | --- | +| bot-risk detection, **bot-risk evidence calibration and ownership boundary** | [`docs/adr/2026-09-05-anti-bot-acquisition-boundary.md`](../adr/2026-09-05-anti-bot-acquisition-boundary.md) | Narrows Wardnet to inbound bot-risk/security evidence and its calibration/provenance/ownership boundary. It does not justify browser challenge handling, outbound anti-bot acquisition, a specific detection algorithm, or shipped runtime behavior. | +| load balancing | Eisenbud et al. (2016), *Maglev: A Fast and Reliable Software Network Load Balancer* — https://www.usenix.org/conference/nsdi16/technical-sessions/presentation/eisenbud | Supports the product rationale for a software load balancer that distributes traffic across service endpoints, maintains connection-consistent mapping, and treats failure/reconfiguration as explicit operating concerns. It does not prescribe Wardnet's implementation. | +| rate limiting | Parekh and Gallager (1993), *A generalized processor sharing approach to flow control in integrated services networks: The single-node case* — https://doi.org/10.1109/90.234856 | Grounds bounded rate-based admission/fairness and explicit delay/rate guarantees. Wardnet's concrete limiter and buyer limits remain executable product contracts, not a claim that GPS/PGPS is implemented. | +| high-throughput control plane | Curtis et al. (2011), *DevoFlow: Scaling Flow Management for High-Performance Networks* — https://doi.org/10.1145/2043164.2018466 | Supports keeping common-case processing on a bounded fast path and avoiding unnecessary control-plane interactions while retaining sufficient security/operational visibility. It does not make Wardnet an OpenFlow/DevoFlow implementation. | + +Research rationale is not implementation or release evidence. Each requirement still needs the repository's exact code, hostile/acceptance tests, performance evidence, protected integration, and immutable release evidence before it can be described as shipped. + +### References + +- Curtis, A. R., Mogul, J. C., Tourrilhes, J., Yalagandula, P., Sharma, P., & Banerjee, S. (2011). DevoFlow: Scaling flow management for high-performance networks. *ACM SIGCOMM Computer Communication Review, 41*(4), 254–265. https://doi.org/10.1145/2043164.2018466 +- Eisenbud, D. E., Yi, C., Contavalli, C., Smith, C., Kononov, R., Mann-Hielscher, E., Cilingiroglu, A., Cheyney, B., Shang, W., & Hosein, J. D. (2016). Maglev: A fast and reliable software network load balancer. In *13th USENIX Symposium on Networked Systems Design and Implementation (NSDI 16)* (pp. 523–535). USENIX Association. https://www.usenix.org/conference/nsdi16/technical-sessions/presentation/eisenbud +- Levine, J., & Vixie, P. (2010). *DNS blacklists and whitelists* (RFC 5782). Internet Engineering Task Force. https://doi.org/10.17487/RFC5782 +- National Institute of Standards and Technology. (2022). *Secure software development framework (SSDF) version 1.1: Recommendations for mitigating the risk of software vulnerabilities* (NIST SP 800-218). https://doi.org/10.6028/NIST.SP.800-218 +- OWASP Foundation. (2025). *OWASP Application Security Verification Standard 5.0.0*. https://owasp.org/www-project-application-security-verification-standard/ +- Parekh, A. K., & Gallager, R. G. (1993). A generalized processor sharing approach to flow control in integrated services networks: The single-node case. *IEEE/ACM Transactions on Networking, 1*(3), 344–357. https://doi.org/10.1109/90.234856 +- World Wide Web Consortium. (2023). *Web Content Accessibility Guidelines (WCAG) 2.2*. https://www.w3.org/TR/WCAG22/ + +No new third-party paper PDF is committed by this documentation lane because repository redistribution permission for the cited versions has not been independently established. Where a publication cannot legally be redistributed in this repository, retain citation and stable locator rather than copying the PDF. Standards or papers committed as artifacts must have a redistribution basis recorded in the owning documentation/PR. \ No newline at end of file diff --git a/tests/documentation_contract.rs b/tests/documentation_contract.rs new file mode 100644 index 00000000..9d6d8ac0 --- /dev/null +++ b/tests/documentation_contract.rs @@ -0,0 +1,126 @@ +use std::path::Path; + +const PRD: &str = include_str!("../docs/product/PRD.md"); +const TRD: &str = include_str!("../docs/architecture/TRD.md"); +const UML: &str = include_str!("../docs/architecture/wardnet-control-plane.puml"); + +fn assert_markers(name: &str, document: &str, markers: &[&str]) { + for marker in markers { + assert!( + document.contains(marker), + "{name} must retain the code-current marker {marker:?}" + ); + } +} + +#[test] +fn canonical_commercial_architecture_documents_are_present_and_owner_bounded() { + assert!(Path::new("docs/product/PRD.md").is_relative()); + assert!(Path::new("docs/architecture/TRD.md").is_relative()); + assert!(Path::new("docs/architecture/wardnet-control-plane.puml").is_relative()); + + assert_markers( + "PRD", + PRD, + &[ + "Gateway and SOC Control Plane", + "Agent Artifact Admission", + "Security evidence and policy", + "quarantine-sandbox-runtime", + "EgressWeave", + "contextual-orchestrator", + "appguardrail", + ], + ); + assert_markers( + "TRD", + TRD, + &[ + "Rust-first", + "released contracts only", + "p95 <= 20 ms", + "CredentialRegistry", + "RuntimeConfiguration", + "SBOM", + "provenance", + ], + ); + assert_markers( + "UML", + UML, + &[ + "@startuml", + "Wardnet", + "Agent Artifact Admission", + "quarantine-sandbox-runtime", + "EgressWeave", + "contextual-orchestrator", + "appguardrail", + "@enduml", + ], + ); +} + +#[test] +fn material_ui_and_slow_work_boundaries_remain_explicit() { + assert_markers( + "PRD", + PRD, + &[ + "Figma/Storybook evidence", + "normal, loading, empty, error, permission-denied, responsive, and keyboard/accessibility states", + "KO/EN/JA/ZH/VI/ES/DE/FR", + ], + ); + assert_markers( + "TRD", + TRD, + &[ + "Figma/Storybook evidence", + "KO/EN/JA/ZH/VI/ES/DE/FR", + "must not hold explicit database locks or long-lived transactions while performing LLM calls, external I/O, sandbox execution, or long-running computation", + ], + ); +} + +#[test] +fn substantive_requirements_remain_academically_grounded_without_overclaiming() { + let anti_bot_adr = "docs/adr/2026-09-05-anti-bot-acquisition-boundary.md"; + let maglev = + "https://www.usenix.org/conference/nsdi16/technical-sessions/presentation/eisenbud"; + let rate_control = "https://doi.org/10.1109/90.234856"; + let devoflow = "https://doi.org/10.1145/2043164.2018466"; + + assert_markers( + "PRD", + PRD, + &[ + "Academic requirement mapping", + anti_bot_adr, + "bot-risk evidence calibration and ownership boundary", + "load balancing", + "rate limiting", + "high-throughput control plane", + maglev, + rate_control, + devoflow, + "Research rationale is not implementation or release evidence", + ], + ); + assert_markers( + "TRD", + TRD, + &[ + "Academic requirement mapping", + anti_bot_adr, + "bot-risk evidence calibration and ownership boundary", + "load balancing", + "rate limiting", + "high-throughput control plane", + maglev, + rate_control, + devoflow, + "Research rationale is not implementation or release evidence", + ], + ); +}