Implementation Plan: Protocol Gateway

Build thin inbound adapters (“protocol gateways”) that translate external protocols into kernel commands/queries, enforce authn/z and capability checks at the boundary, and keep shells stateless.

Protocols in scope include: HTTP API, OpenAI-compatible facade, LSP endpoints for editor integration, and CLI entrypoints.

Provenance & Traceability

Architectural Decisions (ADRs)

Product Requirements (PRDs)

Software Design Specifications (SDS)

Note: SDS-042 (Policy Gateway Service) has been superseded by SDS-047 per ADR-031.

Provenance Chain

graph TD
  ADR33[ADR-033: Kernel-Shell] --> PRD23[PRD-023: Platform Integration]
  PRD23 --> SDS48[SDS-048: Platform UI Integration]
  SDS48 --> SDS47[SDS-047: GovernedSpeed™ Runtime]
  SDS48 --> SDS50[SDS-050: Semantic Identity & Provenance]

Architecture and Design

Design Principles Applied

• Isomorphism: Protocol routes map 1:1 to declared inbound ports (commands/queries) in the semantic model.
• Invariants: Gateways remain thin: translate → validate → authorize → dispatch.
• Idempotency: External requests carry requestId/idempotency key for command dedup where required.

Dependency Justification

• No new dependencies as part of the plan writing; any runtime framework selection must be justified in the SDS (SDS-048 lists Hono/FastAPI options).

Nx Generators Used

Expected Filetree

1
2
3
4
/
├── apps/
│   └── sea-api/src/gen/**              # generated protocol surface + wiring
└── libs/sea/adapters/src/gen/**        # generated inbound adapters (http/lsp/cli)

Proposed Cycles

Task Breakdown

Wave 1 (Parallel)

• C1A: Generate OpenAI-compatible facade for LibreChat (/v1/chat/completions)
  • Implements: SDS-048 OpenAIFacadePort
  • Satisfies: PRD-023 REQ-064
  • Files: docs/specs/shared/sds/048-platform-ui-integration.md, generated apps/sea-api/src/gen/**
• C1B: Generate editor action endpoints for Zed integration
  • Implements: SDS-048 EditorActionPort
  • Satisfies: PRD-023 REQ-063
  • Files: docs/specs/shared/sds/048-platform-ui-integration.md, generated apps/sea-api/src/gen/**

Wave 2 (Depends on Wave 1)

• C2A: Enforce authn/z + policy checks at the gateway boundary
  • Implements: Policy gateway integration + identity addressing
  • Satisfies: SDS-048 POL-048-* policies and PRD-023 invariants
  • Files: docs/specs/shared/sds/047-governedspeed-governance-runtime.sds.yaml, docs/specs/shared/sds/050-semantic-identity-provenance.md, generated adapters under libs/sea/adapters/src/gen/**

Validation & Verification

Spec Validation

• Ensure SDS-048 commands/queries include idempotency specs where required (CMD-060 uses requestId).

Implementation Validation

• Gateways stay thin: generated code contains transport glue only; domain logic remains in kernel
• Requests are authorized before dispatch (policy checks enforced)
• Protocol endpoints match SDS-048 contract (paths and payload shapes)

Open Questions

1. For MVP, which runtime is authoritative for HTTP shells: Python/FastAPI (current generator stubs) or a TS framework? Python/FastAPI
2. Should LSP be implemented as a separate process (dedicated shell) or embedded into sea-api? Separate process
3. What is the canonical “capability descriptor” format returned by QRY-060 GetCapabilities? JSON schema (OpenAPI-style)

Risks & Mitigation

Rollback Strategy

1. If a gateway causes instability, disable the shell while keeping kernel intact (ADR-033).

Related Documents

Reference Documents

• SEA™ Platform Integration PRD

Linked Specifications

Superseded: SDS-042 (Policy Gateway Service) has been merged into SDS-047 per ADR-031.