Pylibp2p Spec Guard

py-libp2p Specification Compliance Guard & Deviation Interceptor

A strict architectural governance skill ensuring that all code modifications, protocol implementations, and wire-level behaviors in py-libp2p adhere 100% to the official libp2p specifications.

🎯 Core Operating Principle

Default Stance: Every protocol ID, wire frame, state machine transition, timeout, cryptographic exchange, and multiplexing rule in py-libp2p MUST strictly conform to the canonical libp2p specifications.

The Golden Rule of Interoperability: A libp2p node that deviates from the spec will fail to communicate with go-libp2p, rust-libp2p, and js-libp2p, causing network partitions or silent connection drops.

The Deviation Interceptor: If the user or a task proposes changes that differ from the official spec, the agent MUST NOT implement them silently. The agent MUST display an explicit warning and proceed ONLY IF the user gives explicit, unambiguous permission.

Trigger Phrases

📚 Official libp2p Specification Mapping

Always verify requirements against the official specification documents:

🛡️ The 4-Step Verification & Interception Workflow

[User Request / Code Edit]
           │
           ▼
[Step 1: Check against libp2p Specs]
           │
     Is it compliant?
     ├── YES ──► Proceed with implementation (Step 4A)
     │
     └── NO / DEVIATION DETECTED
           │
           ▼
[Step 2: HALT & Render Warning Interceptor]
           │
[Step 3: Await Explicit User Permission]
     ├── User Confirms Deviation ──► Proceed with marked custom code (Step 4B)
     └── User Wants Spec Compliance ──► Implement strictly per spec (Step 4A)

Step 1: Pre-Implementation Spec Audit

Before modifying any code in py-libp2p:

1. Identify which libp2p subsystem is affected.
2. Check the canonical spec requirements for:
   • Protocol ID string (e.g. /ipfs/ping/1.0.0).
   • Frame layout, byte ordering (endianness), and length prefixing.
   • Expected error conditions, reset flags, and close handshakes.
   • Message Protobuf schemas and field tags.
3. Compare the proposed change with the spec:
   • Does this change alter wire bytes?
   • Does this change skip required validation (e.g. signature check in GossipSub)?
   • Does this change add a non-standard header or custom protocol ID?
   • Would a go-libp2p or rust-libp2p peer fail to communicate with this?

Step 2: The Warning Interceptor (When Deviation is Detected)

If a change is non-compliant, STOP IMMEDIATELY. Render this exact warning modal:

> [!WARNING]
> ### ⚠️ libp2p Specification Deviation Detected
>
> You have requested a change that deviates from the official **libp2p specification**.
>
> - **Subsystem / Module:** `<e.g., Stream Muxer (Yamux) / Identify / multistream-select>`
> - **Official libp2p Spec:** [`<Spec Title>`](<https://github.com/libp2p/specs/...>)
> - **What the Spec Mandates:**
>   `<Concise explanation of what the official standard requires, e.g.: "The Yamux spec requires a 12-byte header with big-endian length and 0x0004 for FIN.">`
> - **Proposed Deviation:**
>   `<What is being changed that differs, e.g.: "Omitting FIN frames on stream teardown and using custom 8-byte headers.">`
> - **Interoperability & Network Risk:**
>   `<Concrete consequence, e.g.: "This will cause immediate connection desynchronization and StreamReset errors when communicating with go-libp2p, rust-libp2p, or Kubo nodes.">`
>
> ---
>
> 🛑 **Explicit Permission Required:**
> Default policy requires all changes to be 100% spec-compliant. 
> Do you explicitly approve deviating from the official libp2p specification for this change?
>
> - **Option 1 (Recommended):** Keep it 100% compliant with the official libp2p spec.
> - **Option 2:** Proceed with the custom deviation (I accept breaking interop).

Step 3: Await User Instruction

• NEVER assume permission.
• NEVER start editing files until the user replies.
• If the user selects Option 1 (or asks to stick to the spec): Implement the standard spec behavior.
• If the user selects Option 2 (explicitly confirms the deviation): Proceed, but execute Step 4B.

Step 4B: Documenting Approved Deviations

When an out-of-spec change is explicitly authorized by the user:

1. Clearly mark the deviating code with a standard deviation comment:

   # ⚠️ SPEC-DEVIATION [AUTHORIZED BY USER]:
   # Official libp2p spec mandates: <standard requirement>
   # Custom deviation: <why this custom behavior was implemented>
   

2. Note the deviation in the PR newsfragment under breaking.rst or internal.rst.

📋 Non-Negotiable Compliance Invariants

1. Protocol Strings are Sacred: Never invent custom protocol IDs for standard protocols (e.g. do not rename /ipfs/ping/1.0.0 to /libp2p/ping/2.0).
2. Framing Must Match Wire Bytes: Never change big-endian to little-endian or replace unsigned varints with fixed ints unless specified in a new versioned spec.
3. Protobuf Backward Compatibility: Never change existing field numbers in .proto files; only add new optional fields.
4. Silence is Failure: If a peer violates the spec on the wire, handle it with an explicit protocol error or stream reset — never silently adapt or corrupt local state.