[Proposal] Cognitive Firewall Control Plane - FastAPI Service, /validate Contract & Audit Layer

[Saisharathchandranandnetha]

⚠️ Updated Revised to align with Phase-1 Architecture

Changes from original:

• ❌ Removed: FastAPI / HTTP transport
• ❌ Removed: SQLite / PostgreSQL audit log
• ✅ Replaced with: UDS binary framing (aligned with Issue [Design] Multi-Layered Sidecar Architecture for Agentic Cognitive Firewall #1)
• ✅ Replaced with: OpenTelemetry span emission (aligned with
  Phase-1 audit decisions)

---

Overview

Hi @tharindupr and the ACF-SDK team 👋

Following the design work in Issues #1, #2, and #3, I am proposing
a Cognitive Firewall Control Plane a stable input/output
contract layer that gives the pipeline a consistent, inspectable
interface, built on the UDS transport and OTel audit plane already
established in Phase 1.

To be clear upfront: I am not proposing to re-architect the sidecar
kernel or the transport layer. The goal is a thin schema contract
layer with OTel-native observability, built incrementally with
maintainer sign-off at each step.

---

Why This Layer?

The sidecar kernel currently has no stable input/output contract
that all pipeline layers conform to. This means:

• Each layer (heuristics, semantic, provenance) may emit signals
  in different shapes
• There is no single observable control point for policy decisions
• External agents have no agreed interface for submitting inputs
  for validation

This proposal defines that contract not as an HTTP service, but
as a UDS-native schema that all layers write to and read from.

---

The /validate Contract (UDS-aligned)

The most important step before any code is agreeing on the
data schema. Here is my proposed starting point — fully open
to refinement by maintainers.

Request (sent over UDS as binary-framed payload):

@dataclass
class ValidateRequest:
    input: str
    agent_id: str
    trace_id: str              # UUID for OTel span correlation
    policy_version: str        # semver
    timestamp_utc: str         # ISO-8601
    memory_snapshot: list[str]
    tool_results: list[dict]   # {tool_name, output, source_signature}
    conversation_history: list[str]

Response (returned over UDS):

@dataclass
class ValidateResponse:
    decision: str              # "PASS" | "SANITIZE" | "BLOCK"
    risk_score: float          # 0.0–1.0
    reasons: list[str]
    sanitized_input: str | None
    trace_id: str              # echoed for OTel correlation
    layer_signals: dict        # per-layer outputs → OTel span attributes
    # layer_signals shape:
    # {
    #   "normalisation": {"obfuscation_severity": 0.0, "fast_fail": false},
    #   "lexical":       {"matched_patterns": []},
    #   "semantic":      {"cosine_score": 0.0},
    #   "provenance":    {"signature_valid": true}
    # }

This schema is intentionally compatible with the v1.1 Telemetry
Contract referenced in PR #4 it is a structured projection
of the same data model.

---

Phased Delivery (Maintainer-Gated)

Each phase is a standalone Draft PR. Nothing merges without
review and explicit sign-off.

Phase	Deliverable	Stack
1	UDS listener skeleton + Pydantic schemas	Python, UDS, zero HTTP
2	Route to pipeline modules as they land	Wires normalisation, lexical, semantic outputs
3	OTel span emission per decision	opentelemetry-sdk, trace_id correlation
4	Operations Dashboard (OTel-native, optional)	Next.js or Streamlit → Jaeger
5	Docker + docker-compose	One-command deployment
6	MCP adapter	Agent-agnostic interface per GSoC spec

Phase 4 note: The observability dashboard is scoped as
optional and experimental. It will only be pursued if Phases 1–3
are stable and maintainers confirm it as a priority.

---

Relationship to Existing Work

SDK Interceptor (PR #4)
    │
    ├── [UDS binary] ──► Sidecar Kernel (Issues #1, #3)
    │                         │
    │                    [OTel spans] ──► Jaeger / Prometheus
    │                                          │
    │                                   Operations Dashboard
    │                                   (Phase 4 optional)
    │
    └── ValidateRequest / ValidateResponse schema
        (this proposal sits across all layers as the contract)

This adds a schema contract, not a new transport path.
Contributors on individual pipeline layers can conform to this
schema without changing their module interfaces.

---

Why I Can Build This

At the India AI Impact Buildathon 2026 (top 850 / 38,000+
participants), I built Scam Shield an offensive AI honeypot
that processes adversarial scammer messages across 8 Indian
languages using a 6-layer detection pipeline with confidence
scoring, a multi-LLM cascade, and a FastAPI backend deployed
on Render.

The schema design problem here defining a stable contract
that multiple detection layers write to is identical to the
problem I solved in Scam Shield. I have direct production
experience with exactly this architecture pattern.

Live system: https://scam-shield-5hnk.onrender.com

---

Questions for Maintainers

1. Does the ValidateRequest / ValidateResponse schema align
   with the v1.1 Telemetry Contract in PR feat(core): Phase 1 Integration Scaffold & v1.1 Telemetry Contract #4, or should I adjust
   the field names or shape?
2. Should the UDS listener use length-prefixed framing or a
   different binary protocol?
3. Is Phase 4 (dashboard) in scope for GSoC 2026, or is it
   purely post-GSoC?
4. Is there an existing contract I should conform to that I
   may have missed?

Ready to open a Draft PR with just the Pydantic dataclasses
and a UDS skeleton zero logic immediately for early review
and correction.

---

cc: @tharindupr @charithccmc @eddymontana

[AdityaCJaiswal]

Welcome to the team, @Saisharathchandranandnetha! It is great to see this level of detail and initiative, and an observability dashboard is definitely something we need for the Operations Plane.

However, to provide some immediate context: just a few hours ago, the core team and mentors explicitly froze the Phase-1 Architecture Contracts to prevent parallel design drift.

To ensure your proposal aligns with the <10ms latency constraints and the established architecture, we need to make a few critical adjustments to your plan:

1. Transport: No HTTP/FastAPI for Phase 1

We are strictly enforcing a <10ms total round-trip latency budget for the PEP-PDP communication. FastAPI and HTTP introduce significant HTTP header parsing, routing, and TCP loopback overhead that can consume 3-5ms before any security evaluation even begins.

• The Decision: The UDS (Unix Domain Socket) with binary framing is our only transport layer for Phase 1. We cannot maintain a dual-transport (HTTP + UDS) ingestion layer right now. (For non-Unix hosts like Windows, we will implement Named Pipes natively under the same binary protocol, not HTTP).

2. Audit: OpenTelemetry (OTel), not SQLite/PostgreSQL

We have officially standardized the audit plane on W3C-compliant OpenTelemetry (OTel). The PDP will emit asynchronous OTel spans containing the trace_id and enforcement decisions.

• The Decision: We will not be rolling a custom SQLite or PostgreSQL schema for audit logging. The sidecar will emit standard OTel exhaust, which can be ingested by any standard collector (Jaeger, Prometheus, Datadog).

Your Pivot: The "OTel-Native" Operations Dashboard

While the FastAPI/SQLite backend conflicts with the current architecture, your idea for Phase 4 (Observability Dashboard) is highly relevant.

Since the core pipeline (Streams A, B, and C) is already being handled, would you be willing to pivot this proposal to focus purely on the Operations Plane UI?

• Instead of building an API/DB, you could build a Streamlit or Next.js dashboard that connects directly to an OTel Collector (like Jaeger) to visualize the firewall's blocked events, risk scores, and trace latency.
• This gives you a massive, highly visible feature to own that directly complements the UDS/OTel architecture we locked in today.

Let me know if you are open to reshaping the proposal around an OTel-native dashboard! We'd love to have you driving the observability UI.

[Saisharathchandranandnetha]

Thanks for the context, @AdityaCJaiswal the points around UDS transport and OTel standardisation make sense from a latency and architecture perspective.

I’ve revised the proposal to align with this direction (removing HTTP and custom DB usage, and shifting toward UDS + OTel).

Before finalising the scope, I’d like to confirm alignment with the maintainers:

@tharindupr @charithccmc could you please clarify:

1. Does the revised /validate schema (now UDS-aligned) fit the v1.1 Telemetry Contract, or should I adjust the structure?

2. Are there still open components in the core pipeline available for contribution, or is the observability/dashboard layer the recommended focus at this stage?

I’m flexible on scope and happy to contribute where it’s most useful.

Thanks!

[eddymontana]

Thanks for the tag, @Saisharathchandranandnetha. The revised ValidateRequest schema looks like a solid starting point for a unified contract.

@AdityaCJaiswal, the decision to strictly enforce UDS/Named Pipes for Phase 1 makes total sense for the <10ms budget. I've already initialized my environment to support this 'Sidecar Kernel' approach—ensuring the Python SDK can talk to a high-performance Go-based listener over these low-latency channels.

Happy to collaborate on ensuring the schema @Saisharathchandranandnetha is proposing fits perfectly into the binary framing we're targeting for the transport layer.