suaveplan/openspec/changes/complete-network-plugins/specs/network-plugin-qos/spec.md

Capability Spec Delta: network-plugin-qos (complete-network-plugins)

Package: @suaveplan/network-plugin-qos Status: PROPOSED

Every requirement below carries a **Verified by:** line at authoring time. First canonical spec for this package.

ADDED Requirements

Requirement: MessagePriorityClassifier classifies messages into a fixed QoS lattice

The package SHALL export MessagePriorityClassifier, MessagePriorityClassifierConfig, ClassificationRule, and a QoSClass union "URGENT" | "CONTROL" | "DATA" | "BULK". The classifier SHALL evaluate registered rules in priority order and SHALL return a deterministic QoSClass for every input.

Scenario: first matching rule wins

• WHEN two rules match an input and the first is registered with higher priority
• THEN the classifier returns the class assigned by the first rule

Verified by: src/classifier/classifier.spec-conformance.test.ts::"first matching rule wins"

---

Requirement: BandwidthQuotaEnforcer applies per-class quota with typed overflow

The package SHALL export BandwidthQuotaEnforcer and BandwidthQuotaEnforcerConfig. The enforcer SHALL maintain a token-bucket per QoSClass and SHALL throw QosError(QUOTA_EXCEEDED) when a send attempt would exhaust the bucket for the message's class.

Scenario: quota exhausted

• WHEN the bucket for "BULK" is empty and a "BULK" message of size > 0 is offered
• THEN the call throws QosError with code === "NET_QOS.QUOTA_EXCEEDED" and context.class === "BULK"

Verified by: src/enforcer/enforcer.spec-conformance.test.ts::"throws QUOTA_EXCEEDED when bucket is empty"

---

Requirement: CongestionMonitor reports a binary congestion state to listeners

The package SHALL export CongestionMonitor, CongestionMonitorConfig, and a CongestionListener type. The monitor SHALL emit "congested" when sustained backpressure crosses the configured threshold and "recovered" when it falls back.

Scenario: threshold transition

• WHEN measured backlog rises above the threshold for the dwell time
• THEN every registered listener receives "congested"

Verified by: src/monitor/congestion-monitor.spec-conformance.test.ts::"emits congested on sustained backpressure"

---

Requirement: QoSRouter decides per-message action under load

The package SHALL export QoSRouter, QoSRouterConfig, a QoSAction union "bypass" | "send" | "queue" | "drop" | "defer", and a QoSDecision record. The router SHALL combine the classifier's QoSClass with the enforcer's quota state and the monitor's congestion state to produce a deterministic QoSDecision per message.

Scenario: congested + over-quota bulk message is dropped

• WHEN the monitor reports "congested" and the bulk bucket is empty
• THEN router.decide(msg) returns { action: "drop", class: "BULK", reason }

Verified by: src/router/qos-router.spec-conformance.test.ts::"drops bulk message when congested and over quota"

---

Requirement: Error-code registry is frozen and namespaced NET_QOS

QOS_CODES SHALL be frozen under the NET_QOS namespace and SHALL include at minimum QUOTA_EXCEEDED. Every code SHALL be reachable from a production throw site.

Scenario: registry membership

• WHEN QOS_CODES is inspected
• THEN every key maps to a value of the form "NET_QOS.<KEY>"

Verified by: src/error-codes.spec-conformance.test.ts::"QOS_CODES is frozen and prefixed NET_QOS"

---

Requirement: No bare-Error throws in production code

src/ SHALL contain zero bare throw new (Error|TypeError|RangeError|SyntaxError)\( sites outside test files.

Scenario: source grep returns zero hits

• WHEN the grep is run
• THEN the output is empty

Verified by: tests/no-bare-throws.test.ts::"network-plugin-qos src/ has no bare Error throws"

---

Requirement: README is auto-docs idempotent

The package README.md SHALL contain exactly one balanced auto-docs block; the generator SHALL produce a byte-identical file on a second run.

Scenario: marker count is exactly one

• WHEN grep -c "begin:auto-docs" packages/network/network-plugin-qos/README.md
• THEN output is 1

Verified by: scripts/generate-package-module-tree.test.ts::"README regen is idempotent for network-plugin-qos"