70f935bc · samitouri/QOSAMI-X402Tunnel-1

@@ -1,32 +1,33 @@

1 # AGENTS.md

2

3 Keep this file short and behavioral.

4 -Architecture, product behavior, and design rationale belong in `docs/architecture.md` and `docs/adr/README.md`.

4 +Architecture, product behavior, and design rationale belong in `docs/architecture.md`.

5

6 ## Principles

7

8 +These are mandates, not suggestions.

9 +

10 - Minimize concepts, duplication, and ceremony.

11 - One real owner per contract. No mirroring, no wrappers unless they remove real coupling.

12 - Local simplicity over speculative abstraction. Add indirection only when it removes real coupling or protects a real boundary.

13 - When caller and callee are both local with no real boundary, change both directly.

14 - Remove dead code, fields, config, and stale state while touching nearby code.

13 -

14 -## Go Mandates

15 -

16 -- Validate on construction. `NewX` functions reject invalid state; callers never receive a half-built value.

17 -- Fail fast with clear errors. Wrap with context; surface the root cause.

15 +- Reject invalid state at construction. `NewX` functions never return a half-built value; callers never check after the fact.

16 +- Fail fast. Wrap errors with context; surface the root cause.

17 - Zero external dependencies unless the alternative is re-implementing a non-trivial, correctness-critical algorithm. Justify in the commit message.

18 - Interfaces express behavior, not taxonomy. One or two methods. If an interface has no consumer, delete it.

19

20 +## Implicit Contracts

21 +

22 +Expensive to rediscover. Do not violate without understanding why these exist.

23 +

24 +- **HTTP/1.1 is non-negotiable on the control plane.** `/sdk/connect` relies on HTTP/1.1 hijacking to upgrade reverse sessions. HTTP/2 silently breaks this path.

25 +- **Reverse session marker bytes are protocol state.** `0x00` (idle keepalive), `0x01` (raw TCP activation), `0x02` (TLS passthrough activation). These encode session lifecycle transitions, not transport metadata. Misinterpretation causes silent connection staleness.

26 +- **Admin policy is global and immediate.** Banning, approval mode, IP filters, and rate limits apply to all leases in real-time. There are no per-lease overrides. Do not introduce per-lease policy without rethinking the `policy.Runtime` ownership model.

27 +- **Frontend-backend contracts have no codegen.** SSR data shape, API paths, API envelope, and HTML placeholders are manually synced across Go and TypeScript. See `frontend/CLAUDE.md` for the full contract inventory.

28 +

29 ## Testing

30

31 - A test exists to catch real bugs. If deleting the test would not let a bug reach production, delete the test.

32 - Test contracts and boundaries: protocol compliance, error semantics, security invariants, integration across real I/O.

33 - Do not test configuration shapes, constructor output fields, or struct assembly — the type system and constructors already guarantee those.

26 -- Do not test that a function returns exactly what you passed in.

27 -

28 -## Verification

29 -

30 -- CI commands: `make vet`, `make lint`, `make test`, `make vuln`.

31 -- `make tidy` is local maintenance, not a CI requirement.

32 -- Run targeted tests after contract-touching or risky edits. Ask before running the full suite.

chore: philosophy-first principles