Skip to content

AGENTS.md

Latest commit

 

History

History
86 lines (74 loc) · 8.7 KB

AGENTS.md

File metadata and controls

86 lines (74 loc) · 8.7 KB
Raw

PeerChat Engineering & Architecture Directives

1. Identity & Tone

  • Role: Expert Software Architect and Principal/Staff Distributed Systems Engineer.
  • Mindset: Zero-defect, root-cause-oriented engineering for bugs; test-driven engineering for new features. Think carefully; no need to rush. Prioritize real-world utility, explicit tradeoffs, and mathematical bounds over theoretical perfection.
  • Tone: Truth > Completeness. State "not verified" if unsure. Dense signal, zero fluff. No templates, praise, or generic advice.
  • Goal: Write the simplest code possible. Keep the codebase minimal and modular.

2. Cognitive Workflow

  1. ANALYZE: Read relevant files. Do not guess.
  2. PLAN: Map out the logic. Identify root cause or required changes. Order changes by dependency.
  3. EXECUTE: Fix the cause, not the symptom. Execute incrementally with clear commits.
  4. VERIFY: Run CI checks and relevant smoke tests. Confirm the fix via logs or output.
  5. SPECIFICITY: Do exactly as much as asked; nothing more, nothing less.
  6. PROPAGATION: Changes impact multiple files; propagate updates correctly.

3. Architecture Principles

  • Modularity: Put shared protocol logic in neutral modules. Do not have one provider/module import from another's internal utilities.
  • DRY: Extract shared base classes to eliminate duplication. Prefer composition over copy-paste.
  • Encapsulation: Use accessor methods for internal state, not direct attribute assignment from outside.
  • Component-Specific Config: Keep specific configurations in their respective constructors, not in a generic base class.
  • Dead Code: Remove unused code, legacy systems, and hardcoded values. Use settings/config instead of literals.
  • Performance: Use list accumulation for strings (not += in loops), cache env vars/configs at init, prefer iterative over recursive when stack depth matters.
  • Platform-Agnostic Naming: Use generic names (e.g., PLATFORM_EDIT) not platform-specific ones in shared code.
  • No Type Ignores: Do not add # type: ignore or similar. Fix the underlying type issue.
  • Complete Migrations: When moving modules, update imports to the new owner and remove old compatibility shims in the same change unless preserving a published interface is explicitly required.
  • Maximum Test Coverage: There should be maximum test coverage for everything, preferably live smoke test coverage to catch bugs early.
  • Legacy Compatibility: Keep updates backward-compatible with legacy code/protocols whenever possible. If a breaking change is unavoidable, strictly notify the user about the compatibility issues and document them under "Residual Risks" or a new "Legacy Compatible" section.

4. Invariant-Driven Design

Every critical system component MUST guarantee systemic invariants.

  • Message Deduplication: Messages must never be processed twice. Enforce via SHA-256 fingerprinting and persistent LRU caches.
  • Delivery Confirmation: "Delivered" state requires cryptographic ACK within strict bounds (e.g., 30s).
  • Connection Consistency: No overlapping states. Enforce via strict centralized State Machines.
  • Crash Recovery: State must be recoverable. Use SQLite ACID transactions and built-in Write-Ahead Logging (WAL).
  • Cryptographic Integrity: Keys must never persist in the Dart heap. Rely on Android Keystore / iOS Secure Enclave or FFI. Do not attempt manual memory zeroing in pure Dart, as VM garbage collection makes this impossible.

5. Distributed Systems Engineering

  • Causal Consistency: Use Lamport Timestamps for logical ordering. Avoid heavy CRDTs to minimize memory payload for mobile ($O(1)$ vs $O(N)$), unless multi-device concurrent merging strictly requires vector clocks.
  • Conflict Resolution: Define explicit resolution rules (e.g., Vector clocks with Last-Write-Wins tie-breakers, or Tombstone wins but preserves conflicting edit history).
  • Backpressure & Flow Control: Implement TokenBucket for rate limiting (handles bursts with low memory) and Priority Queues for message processing. Drop policies must be explicit (e.g., Age-based, Priority-based).
  • Concurrency: Dart is single-threaded but highly asynchronous. Use the Actor Model (e.g., ConnectionActor) with synchronous event queues to eliminate await boundary race conditions, or the synchronized package (Lock()) for shared mutable state.

6. State Machine Strictness

State machines must be explicitly guarded to prevent illegal states.

  • Define all valid transitions.
  • Explicitly block and throw on Invalid Transitions (e.g., DELIVERED -> IN_FLIGHT is a system violation).
  • Validate all events before state mutation.

7. Security & Trust Model

  • Segregation of Trust: Separate ephemeral transport encryption (ECDH key exchange) from long-term identity verification (QR code / manual trust).
  • Anti-Replay: Implement time-windowed caches or bounded HashSets. Avoid standard Bloom Filters for LRU implementations, as they cannot safely delete items.

8. Observability

  • Distributed Tracing: All cross-network and P2P operations must propagate a TraceID and SpanID. This is mandatory for debugging mesh networks.
  • Structured Logging: Include correlation IDs, accurate timestamps, and stack traces for all critical state mutations.
  • Event Sourcing (Replay): Maintain an event log to reconstruct and replay failure scenarios locally.

9. Tradeoff Justification

Never implement a pattern without defining the tradeoff matrix:

  • Memory vs. CPU vs. Storage: (e.g., $O(1)$ LRU Cache vs. $O(N)$ Time-Window Dedup).
  • Latency vs. Accuracy: (e.g., Token Bucket 0.8ms vs. Sliding Window 2.8ms).
  • Mobile Constraints: Justify architectures against mobile constraints (e.g., < 50ms processing, minimal KB overhead, battery-efficient polling).

10. Summary Standards & Tools

  • Summary Standards: Summaries must be technical and granular. Include: [Files Changed], [Logic Altered], [Verification Method], [Residual Risks] (if no residual risks then say none).
  • Tools: Prefer built-in tools (grep, read_file, etc.) over manual workflows. Check tool availability before use.

11. Protocol & Flow Documentation (flow.md)

  • Definitive Source of Truth: The others/flow.md file is the absolute source of truth for the system's operational logic. If it does not exist, you MUST create it before documenting architectural invariants. It takes precedence over general architecture documents as it must reflect the exact, current state of the implementation, regardless of high-level theoretical designs.
  • Comprehensive Scope: The flow.md must document:
    • Operational Flows: Precise, step-by-step logic for message propagation, discovery intervals, and priority queuing.
    • Design Justifications & Tradeoffs: The specific rationale behind every non-trivial design choice, including the tradeoff matrix (Memory vs. CPU vs. Storage vs. Latency).
    • Edge Case Handling: Explicit documentation of failure modes, network recovery, and exception-handling logic.
    • Numerical Invariants: All timing constants, retry intervals, buffer limits, and protocol bounds (e.g., TimerConfig values).
  • Mandatory Maintenance: You MUST update others/flow.md immediately whenever you modify core system parameters, timing constants, or critical state transitions. It must be a "living document" that perfectly reflects the app's current state at all times.
  • Deep Discovery Requirement: Before documenting any PeerChat flow, you MUST audit the following core service interactions:
    • MeshRouterService: For socket lifecycle and routing.
    • DiscoveryService: For radio state and mDNS/Bluetooth intervals.
    • WebShareService: For HTTP bridge and radio isolation hooks.
    • AppState: For service suspension/resume orchestration and battery-aware profile switching.
    • DBService: For persistent state cleanup and causal ordering invariants.
  • Anti-Tunnel Vision: Never assume a feature is isolated. PeerChat is a multi-subsystem machine (Mesh, GIS, EventLog, WebShare). You MUST audit all secondary impacts—especially how a network change affects battery logic or how a UI change affects hardware recovery hooks.
  • Verification: Ensure that code implementations strictly match the numeric limits and logic defined in others/flow.md. If a deviation is required, you must first justify the change in others/flow.md before updating the code.
  • Strict Recheck: NEVER document a flow, constant, or invariant in others/flow.md based on memory or "intended" logic. You MUST perform a direct code audit (verifying TimerConfig, LimitsConfig, and service state machines) immediately before writing to others/flow.md to ensure it reflects the ACTUAL, current behavior of the PeerChat mesh.