Critique Rpc Vs Http Evaluation

Spike: Cloudflare Worker RPC vs. HTTP Conventions and Critique Platform Service Evaluation

Source Issue: #628
Status: uningested (Authoritative evaluation write-up targeted for /docs distill into docs/architecture/MULTI_WORKER_PLATFORM_SERVICES.md)
Candidate Distillation Targets: docs/architecture/MULTI_WORKER_PLATFORM_SERVICES.md, docs/architecture/CAPABILITY_MANAGEMENT.md

---

1. Executive Summary & Spike Objective

In SiteSwarm, horizontal capabilities deliver cross-cutting functionality—such as visual editorial feedback (@siteswarm/critique), edge cache invalidation (@siteswarm/service-cache-purge), inquiries, and content management—across a multi-tenant fleet of client web applications (apps/*).

Under Epic #581 and Epic #606, SiteSwarm successfully transformed the in-situ visual review system from a client-siloed proof of concept (POC) into a centralized platform service (services/critique) backed by dedicated Cloudflare D1 persistence (siteswarm-critique-db). In that transition, the primary caller path was structured as direct browser-to-platform-worker HTTP with dynamic CORS, eliminating the “Pass-Through Edge Proxy” anti-pattern (where client app workers waste an invocation merely proxying browser HTTP calls into RPC), achieving a verified 0-byte production client footprint and cutting total edge worker invocations by 50%.

Simultaneously, however, services/critique/src/index.ts exposes a class CritiqueService extends WorkerEntrypoint<Env> implementing Cloudflare Worker RPC methods (list, create, update, updateStatus, resolveAddressed) alongside the standard HTTP fetch export.

This architectural spike accomplishes three mandatory objectives:

1. Empirical Evaluation of Worker RPC vs. HTTP: Investigates the real Cloudflare workerd runtime mechanics of Worker RPC (WorkerEntrypoint over Service Bindings) versus Direct HTTP (fetch()) across developer experience (DX), end-to-end type safety, execution latency, network/edge isolation, and browser compatibility.
2. Comprehensive Audit of services/critique: Identifies critical implementation discrepancies where existing RPC methods bypass HTTP validation schemas (createCritiqueSchema), deduplication engines (getCritiqueDeduplicationKey), and origin security controls, while diagnosing deployment routing contradictions in services/critique/wrangler.jsonc (workers_dev: false vs. hardcoded workers.dev URLs).
3. Formalization of the SiteSwarm 3-Tier Platform Service Taxonomy: Codifies an authoritative standard defining when SiteSwarm platform services should be Tier A (Edge API / HTTP-First), Tier B (Internal Edge / RPC-First), or Tier C (Hybrid Platform Services), establishing mandatory architectural guardrails to prevent interface divergence.

flowchart TD
    subgraph IngressCallers["Ingress Caller Topologies"]
        Browser["1. Browser Client (<CritiqueOverlay />)\n- Outside Cloudflare Edge Network\n- Speaks HTTP/HTTPS Only"]
        WorkerA["2. Client App Edge Server (Worker A)\n- Inside Cloudflare Edge Network\n- Can Use Service Bindings (RPC or fetch)"]
        CLI["3. Governance CLI / AI Agent (pnpm swarm)\n- Outside Cloudflare Edge (Node.js)\n- Speaks HTTP/HTTPS Only"]
    end

    subgraph CritiqueServiceWorker["services/critique (Platform Worker)"]
        subgraph HttpIngress["Tier A HTTP Ingress"]
            CORS["Dynamic CORS Middleware\n(isAllowedOrigin regex)"]
            Router["HTTP Router (router.ts)\n- validateOrigin\n- createCritiqueSchema (Zod)\n- getCritiqueDeduplicationKey"]
        end

        subgraph RpcIngress["Tier B RPC Ingress"]
            RPC["CritiqueService extends WorkerEntrypoint\n- list, create, update\n- ⚠️ BYPASSES Zod validation\n- ⚠️ BYPASSES deduplication"]
        end

        Repo["CritiqueRepository (repository.ts)\n(Direct D1 SQL Prepared Statements)"]
        D1[("D1 SQLite Database\nsiteswarm-critique-db")]
    end

    Browser -->|"Direct HTTPS + CORS"| CORS
    CLI -->|"Direct HTTPS + Spoofed Origin"| CORS
    CORS --> Router
    WorkerA -.->|"Hypothetical Service Binding"| RPC
    Router --> Repo
    RPC -->|"Direct DAO Call"| Repo
    Repo --> D1

---

2. Empirical Comparison: Cloudflare Worker RPC vs. Direct HTTP Conventions

Cloudflare Workers provides two distinct mechanisms for inter-worker and external communication: Direct HTTP (fetch) and native Worker RPC (WorkerEntrypoint). Evaluating these paradigms requires understanding the underlying V8 isolate runtime architecture in workerd.

2.1 The Underlying Runtime Realities (workerd, V8 Isolates & Cap’n Proto)

• Worker RPC (WorkerEntrypoint): Introduced natively in workerd (2024), Worker RPC uses Cap’n Proto zero-copy serialization across V8 isolate boundaries. When Worker A binds Worker B via an internal Service Binding (env.SERVICE_BINDING.method()), both workers execute within Cloudflare’s edge compute infrastructure. If colocated on the same physical host machine or edge point of presence (PoP), the call bypasses the operating system’s network stack, TLS termination, HTTP parsing, and JSON serialization entirely. Arguments are transferred via structured clone semantics, and promises/stubs can be pipelined across isolates.
• Direct HTTP (fetch): Operates over the standard web networking model. Whether routed internally via serviceBinding.fetch(request) or externally across public DNS (fetch("https://service.domain/...")), requests require constructing a standard Request object, serializing headers, stringifying JSON bodies, parsing URLs, handling HTTP status codes, and managing content negotiation.

2.2 Deep Comparative Matrix across 6 Dimensions

The following matrix evaluates Worker RPC against Direct HTTP across critical architectural dimensions under real Cloudflare runtime constraints:

Evaluation Dimension	Cloudflare Worker RPC (WorkerEntrypoint)	Direct HTTP (fetch())	Architectural Impact for SiteSwarm
1. Developer Experience (DX)	Superior: Native JavaScript method calls (await env.SRV.get(id)). No manual URL construction, query string escaping, or status code parsing.	Verbose Boilerplate: Caller must construct URL, set headers, JSON.stringify(body), await res.json(), and handle non-2xx statuses manually.	RPC eliminates 15–30 lines of client fetch glue per endpoint.
2. Type Safety & Contracts	End-to-End Compile-Time Proof: Method parameters and return types are governed by shared TypeScript interfaces (implements ServiceRpc). Breaking changes fail tsc builds monorepo-wide.	Implicit / Deserialized: Untyped network boundary (Response). Requires manual Zod schema parsing on the receiver and duplicated TypeScript client types on the caller.	RPC prevents payload schema drift between caller and callee across workspace packages.
3. Latency & CPU Overhead	Ultra-Low (< 0.1ms compute overhead): Direct isolate memory transfer via Cap’n Proto structured clone. Zero JSON serialization or HTTP header parsing.	Higher (~0.5ms – 2.0ms local, 15ms–80ms internet): Incurs JSON stringify/parse CPU time, header processing, and network/TLS roundtrips if public.	For high-throughput worker-to-worker operations (e.g. cache purges), RPC saves measurable CPU budget (50ms limit).
4. Edge Isolation & Security	Air-Gapped Private Perimeter: Service Bindings are private internal runtime pointers. Zero public IP, zero DNS record, zero exposure to internet scrapers, and unforgeable caller identity.	Public Exposure Surface: Requires public URLs, dynamic CORS allowlists, origin verification, and rate limiting to defend against public internet abuse.	Internal services (Tier B) gain absolute perimeter security via Service Bindings.
5. Browser Client Compatibility	Zero (Incompatible): Browser JavaScript cannot invoke Cloudflare Service Binding RPCs directly. Browsers reside outside Cloudflare’s network.	Universal (100% Compatible): Native window.fetch() works in every modern browser, mobile WebView, and headless environment.	Critical Negative Constraint: Browser-facing capabilities (like <CritiqueOverlay />) cannot use RPC without a gateway.
6. Local Dev & Miniflare Rigor	High in Modern Miniflare (v3.2024+): Miniflare supports Worker RPC natively via workerd. However, multi-worker dev (pnpm run dev with multiple wrangler dev processes) requires multi-port coordination.	Standard / Decoupled: Each service runs an HTTP server on a discrete localhost port (e.g. :8787). Can be tested with curl, Postman, or unit tests without binding mocks.	HTTP is slightly simpler for decoupled local CLI and script testing.

2.3 The Browser Egress Invariant & The Pass-Through Proxy Anti-Pattern

[!CAUTION] Negative Constraint & Anti-Mocking Rule:
Under no circumstance may it be claimed or designed that browser JavaScript can invoke Cloudflare Service Binding RPCs directly.

Cloudflare Service Bindings and Worker RPC are strictly runtime-internal primitives. They exist exclusively within the address space and configuration of the Cloudflare workerd daemon running on Cloudflare’s global edge network.

Because a user’s web browser (e.g. mobile Safari on an iPhone previewing a client site) runs in an external client environment:

1. The browser cannot resolve or invoke env.CRITIQUE_SERVICE.
2. The browser only understands standard web network protocols: HTTPS, WebSockets, and WebTransport.

This physical boundary introduces two competing architectural topologies for browser-to-platform communication:

flowchart TD
    subgraph TopologyA["Topology A: Pass-Through Edge Proxy (Client Worker as Proxy)"]
        BrowserA["Browser Client (<CritiqueOverlay />)"] -->|"1. HTTP POST /api/critique\n(Network hop across Internet)"| ClientWorker["Client App Worker (apps/*)\n- Edge route /api/critique\n- Parses HTTP JSON body\n- Invokes env.CRITIQUE_SERVICE"]
        ClientWorker -->|"2. Worker RPC (Cap'n Proto)\n(Internal Service Binding)"| PlatformWorkerA["Platform Service (services/critique)\n- WorkerEntrypoint\n- Writes to D1 Database"]
    end

    subgraph TopologyB["Topology B: Direct Edge Service Ingress (Decoupled Platform Service)"]
        BrowserB["Browser Client (<CritiqueOverlay />)"] -->|"1. Direct HTTPS POST + CORS\n(Single Network Hop to Platform Edge)"| PlatformWorkerB["Platform Service (services/critique)\n- Custom Domain critique.siteswarm.tech\n- Dynamic CORS + Zod Validation\n- Writes to D1 Database"]
    end

    style TopologyA fill:#fff1f2,stroke:#e11d48,stroke-width:1px
    style TopologyB fill:#f0fdf4,stroke:#16a34a,stroke-width:1px

2.3.1 The “RPC Eliminates HTTP” Fallacy

A common misconception in multi-worker architectures is that adopting Cloudflare Worker RPC on a platform service eliminates HTTP complexity from client interactions.

This is an illusion. Because browser JavaScript cannot execute Cloudflare RPC directly, adopting Worker RPC for browser-originated interactions does not eliminate HTTP—it simply forces the HTTP boundary into the client application worker:

• The client worker must expose a dedicated HTTP endpoint (e.g. POST /api/critique).
• The client worker must parse the incoming HTTP request, extract JSON headers and payload, and construct an RPC invocation (await env.CRITIQUE_SERVICE.create(payload)).
• The client worker must then await the RPC response and serialize it back into an HTTP Response(JSON.stringify(result)).

Rather than eliminating HTTP, Topology A introduces an un-value-added pass-through proxy inside every client application worker.

2.3.2 Deep Comparative Analysis: Pass-Through Proxy vs. Direct HTTP Ingress

Evaluating Topology A (Client HTTP-to-RPC Proxy) against Topology B (Direct HTTP Ingress) reveals five critical architectural advantages for Direct HTTP:

Evaluation Vector	Topology A: Pass-Through Edge Proxy (Browser -> HTTP -> Client Worker -> RPC -> Platform)	Topology B: Direct Edge Service Ingress (Browser -> HTTP -> Platform Service)	Architectural Verdict
1. Billable Invocations & Resource Amplification	2 Worker Invocations per Action: Every critique creation or vote triggers two distinct billable invocations (Client Worker + Platform Service Worker), doubling Cloudflare Worker invocation counts and edge CPU budgets.	1 Worker Invocation per Action: Request terminates directly at the platform service. Exactly one worker executes.	Topology B cuts Cloudflare invocations and compute load by 50%.
2. Client Worker Maintenance & Configuration Footprint	Heavy Multi-Repo Burden: Every client application (apps/*) must: 1. Declare services = [{ binding = "CRITIQUE_SERVICE", service = "..." }] in wrangler.jsonc. 2. Bundle server-side proxy route files (/api/critique.ts). 3. Handle RPC-to-HTTP error status code translations. 4. Redeploy whenever platform endpoints change.	Zero Client Infrastructure: Client apps have 0 service bindings, 0 server-side routes, and 0 proxy files. Client applications only embed the lightweight client UI component (<CritiqueOverlay />), which targets the platform URL.	Topology B preserves absolute zero-maintenance client isolation.
3. Hosting Model & Runtime Agnosticism	Tightly Coupled to Cloudflare Workers: The client application must be an active Cloudflare Worker deployed in the exact same Cloudflare account to bind env.CRITIQUE_SERVICE. Cannot work with static hosting, external preview environments, or third-party hosts.	Universally Host-Agnostic: Works identically whether the client site is a static SPA on Cloudflare Pages, a static site on Workers Assets, a hybrid SSR Astro app, a local Vite preview server (localhost:4321), or deployed externally.	Topology B works across any hosting runtime without requiring SSR or edge compute.
4. Latency & Serial Processing Hops	Compound Latency: Browser-to-client-worker HTTP + client-worker execution + RPC hop + platform execution + return serialization across isolates.	Single-Hop Direct Ingress: Browser connects directly to Cloudflare edge closest to user, where the platform worker immediately terminates TLS, validates, and processes in one execution context.	Topology B reduces end-to-end user perceived latency.
5. Blast Radius & Fault Domain Isolation	Bifurcated Failure Modes: If the client application worker suffers an out-of-memory crash, SSR template error, or misconfigured middleware, the platform capability breaks. Reviewers cannot even use the Critique overlay to report the broken site.	Independent Fault Containment: The platform service is completely isolated from client worker runtime failures. Even if the client app’s SSR backend is crashing, static assets and the Critique overlay remain fully operational.	Topology B protects platform capabilities from client runtime outages.

2.3.3 The Core Architectural Litmus Test: Browser-Originated vs. Worker-Originated Operations

Why does SiteSwarm maintain Worker RPC for @siteswarm/service-cache-purge while advocating Direct HTTP for @siteswarm/service-critique?

The governing architectural rule is The Origin of Invocation:

1. Browser-Originated Interactions (Tier A: Direct HTTP-First):

   • Examples: In-situ critique and visual reviews (@siteswarm/critique), client-side analytics telemetry, end-user contact form submissions, frontend crash reporting.
   • Transport: Direct HTTP (fetch()) with Dynamic CORS.
   • Rationale: Because the interaction originates in the browser DOM outside Cloudflare’s network, an HTTP hop is physically mandatory. Bypassing the client worker eliminates the pass-through proxy anti-pattern, halves worker invocations, removes client wrangler.jsonc bindings, and allows static client sites to remain pure static assets without forcing SSR.

2. Worker-Originated Platform Operations (Tier B: Internal Edge RPC-First):

   • Examples: Edge cache invalidation (@siteswarm/service-cache-purge), server-side CMS data fetching during SSR page generation, asynchronous queue consumers, inter-service event fanout.
   • Transport: Cloudflare Worker RPC (WorkerEntrypoint) via Service Bindings.
   • Rationale: The caller is already an edge worker isolate running inside Cloudflare’s global network. There is no browser in the loop. Worker RPC genuinely eliminates HTTP, JSON serialization, and DNS roundtrips, delivering sub-millisecond, compile-time typed execution behind an air-gapped private perimeter (workers_dev: false).

---

3. Architectural Audit of services/critique Baseline Implementation

An inspection of services/critique/src/index.ts, services/critique/src/router.ts, packages/capabilities/critique/src/handler.ts, and packages/governance/src/cli/critique.ts reveals severe architectural divergence between the RPC interface and the HTTP interface.

3.1 The Current Dual Seam

In services/critique/src/index.ts, the worker class is defined as:

// services/critique/src/index.ts (Lines 15-55)
export default class CritiqueService extends WorkerEntrypoint<Env> {
  override async fetch(request: Request): Promise<Response> {
    return handleRequest(request, this.env);
  }

  // Service Binding RPC Interface
  async list(
    tenantId: string,
    options?: { environment?: string; status?: string | string[] }
  ): Promise<Critique[]> {
    const repository = new CritiqueRepository(this.env.CRITIQUE_DB);
    return repository.list(tenantId, options);
  }

  async create(critique: Critique): Promise<Critique> {
    const repository = new CritiqueRepository(this.env.CRITIQUE_DB);
    return repository.create(critique);
  }

  async update(id: string, input: UpdateCritiqueInput): Promise<Critique | null> {
    const repository = new CritiqueRepository(this.env.CRITIQUE_DB);
    return repository.update(id, input);
  }

  async updateStatus(
    id: string,
    status: Critique["status"] | "dismissed",
    options?: { comment?: string; commitSha?: string }
  ): Promise<Critique | null> {
    const repository = new CritiqueRepository(this.env.CRITIQUE_DB);
    return repository.updateStatus(id, status, options);
  }

  async resolveAddressed(
    tenantId: string,
    options?: { commitSha?: string }
  ): Promise<number> {
    const repository = new CritiqueRepository(this.env.CRITIQUE_DB);
    return repository.resolveAddressed(tenantId, options);
  }
}

Meanwhile, handleRequest in services/critique/src/router.ts handles all HTTP traffic:

// services/critique/src/router.ts (HTTP POST /critiques Handler excerpt)
const parseResult = createCritiqueSchema.safeParse(body);
if (!parseResult.success) {
  return applyCors(jsonResponse({ success: false, error: "Validation failed", issues: parseResult.error.issues }, 422), origin);
}

// Explicit ID Deduplication
if (validated.id) {
  const byId = existingList.find((c) => c.id === validated.id);
  if (byId) return applyCors(jsonResponse({ success: true, data: byId, deduplicated: true }, 200), origin);
}

// Content-based Deduplication Key
const targetKey = getCritiqueDeduplicationKey(validated);
const existingDuplicate = existingList.find(
  (c) => c.status !== "resolved" && getCritiqueDeduplicationKey(c) === targetKey
);
if (existingDuplicate) return applyCors(jsonResponse({ success: true, data: existingDuplicate, deduplicated: true }, 200), origin);

// Version and Timestamp Enrichment
const now = new Date().toISOString();
const detectedAtVersion = validated.detectedAtVersion || {
  commitSha: request.headers.get("X-SiteSwarm-Commit-Sha") || undefined,
  buildTime: request.headers.get("X-SiteSwarm-Build-Time") || undefined,
  environmentObserved: targetEnv,
};

const critique: Critique = {
  id: validated.id || crypto.randomUUID(),
  // ...
  createdAt: now,
  updatedAt: now,
};

const created = await repository.create(critique);

3.2 Concrete Discrepancy Analysis: Where RPC Bypasses Domain Logic

Comparing router.ts and CritiqueService in index.ts exposes four critical divergence vectors:

flowchart LR
    subgraph HTTP_Flow["HTTP Ingress Path (router.ts)"]
        H1["HTTP POST /critiques"] --> H2["validateOrigin()"]
        H2 --> H3["createCritiqueSchema.safeParse() (Zod)"]
        H3 --> H4["ID & Content Hash Deduplication\n(getCritiqueDeduplicationKey)"]
        H4 --> H5["Metadata & Version Injection\n(crypto.randomUUID, timestamps)"]
        H5 --> H6["CritiqueRepository.create()"]
    end

    subgraph RPC_Flow["RPC Ingress Path (index.ts)"]
        R1["RPC critiqueService.create(critique)"] --> R6["CritiqueRepository.create()"]
    end

    style R6 fill:#f87171,stroke:#b91c1c,color:#fff
    style H6 fill:#34d399,stroke:#059669,color:#fff

Discrepancy 1: Zod Schema Validation Bypass

• HTTP Path: Strict runtime verification via createCritiqueSchema.safeParse(body) and updateCritiqueSchema.safeParse(body). Invalid enum values, empty selectors, or malformed URLs are rejected with HTTP 422 Unprocessable Entity.
• RPC Path: Accepts a raw TypeScript Critique object without runtime schema validation. If an RPC caller passes an invalid object (e.g. empty string selector, invalid status string, missing tenant ID), it is passed directly into SQLite SQL parameters, potentially triggering unhandled database constraints or corrupted records.

Discrepancy 2: Deduplication Engine Bypass

• HTTP Path: Enforces both:
  1. Client ID deduplication (existingList.find(c => c.id === validated.id)).
  2. Content-based deduplication (getCritiqueDeduplicationKey(validated)), preventing duplicate open feedback for identical selectors, comments, and tags.
• RPC Path: Completely bypasses deduplication! Calls repository.create(critique) directly, creating duplicate database records in D1.

Discrepancy 3: Metadata & Version Enrichment Bypass

• HTTP Path: Automatically assigns a fallback id (crypto.randomUUID()), injects createdAt and updatedAt ISO timestamps, and synthesizes detectedAtVersion from headers.
• RPC Path: Expects a fully-formed Critique object. If optional properties or timestamps are omitted, the record is inserted with missing or null values.

Discrepancy 4: Root Cause of the Architectural Drift

The root cause is an architectural layering defect:

The business domain logic (validation, deduplication, metadata enrichment) was implemented directly inside the HTTP router (router.ts), treating the database repository (repository.ts) as a dumb DAO.
When the WorkerEntrypoint RPC methods were added to index.ts, they called CritiqueRepository directly, inadvertently bypassing the domain logic trapped inside router.ts.

3.3 Consumer Seam Analysis: Who is Actually Calling What?

A full workspace audit of all consumers of @siteswarm/critique and services/critique reveals surprising reality:

1. Browser Client (<CritiqueOverlay /> in overlay.ts):
   • Uses window.fetch() directly to apiEndpoint (https://critique.siteswarm.workers.dev).
   • Uses HTTP GET, POST, and PATCH.
   • Does NOT use RPC.
2. Capability Handler (createCritiqueHandler in handler.ts):
   • Inspects options.serviceBinding.
   • When provided, lines 17–29 execute:

     if (serviceBinding && typeof serviceBinding.fetch === "function") {
       return await serviceBinding.fetch(request.url, { ... });
     }

   • It invokes serviceBinding.fetch(...) as an HTTP forwarder.
   • Does NOT invoke any RPC method (.list(), .create(), etc.)!
3. Governance CLI & Agent Tooling (packages/governance/src/cli/critique.ts):
   • Uses Node.js fetch() directly to https://critique.siteswarm.workers.dev.
   • Spoofs Origin: https://critique.siteswarm.workers.dev to pass router.ts’s validateOrigin() check!
   • Does NOT use RPC (Node.js cannot speak Service Binding RPC).
4. Summary Finding:

   The WorkerEntrypoint RPC interface in services/critique/src/index.ts is currently an unused ghost seam.
   100% of production, preview, CLI, and capability traffic flows through HTTP fetch. Maintaining the unmaintained RPC methods in their current state is an active liability because they lack validation and deduplication parity.

3.4 Deployment Routing Discrepancy in wrangler.jsonc

An inspection of services/critique/wrangler.jsonc reveals an operational contradiction:

// services/critique/wrangler.jsonc (Lines 3-7)
{
  "name": "siteswarm-critique",
  "main": "src/index.ts",
  "compatibility_date": "2026-09-29",
  "compatibility_flags": ["nodejs_compat"],
  "workers_dev": false,
  // ...
}

Notice line 7: "workers_dev": false!

Meanwhile, across the codebase:

• packages/capabilities/critique/src/client/overlay.ts (line 77): apiEndpoint: options.apiEndpoint || "https://critique.siteswarm.workers.dev"
• packages/governance/src/cli/critique.ts (line 110): "https://critique.siteswarm.workers.dev"
• services/critique/src/router.ts (line 24): ALLOWED_ORIGIN_PATTERNS = [ /^https:\/\/[a-z0-9-]+\.workers\.dev$/ ]

Operational Consequence:

1. When "workers_dev": false is set without specifying custom routes (routes: [...]) or custom domains (custom_domain: true), Cloudflare disables the default *.workers.dev subdomain routing for that worker.
2. Furthermore, in Cloudflare’s naming convention, a worker named siteswarm-critique on workers.dev is routed to https://siteswarm-critique.<account-subdomain>.workers.dev, never https://critique.siteswarm.workers.dev.
3. In a deployed production environment, if workers_dev: false remains without custom domains, services/critique is completely unreachable via HTTP from the public internet.
4. Why this happened: The configuration was cloned from services/cache-purge/wrangler.jsonc. In cache-purge, "workers_dev": false is correct because it is a pure internal Tier B service bound exclusively via Service Bindings. For critique, which requires public browser HTTP egress, disabling workers_dev without custom domains creates a deployment failure mode.

---

4. The SiteSwarm 3-Tier Platform Service Taxonomy

To eliminate ad-hoc transport decisions across existing and future capabilities (such as @siteswarm/inquiries, @siteswarm/cms, and telemetry), SiteSwarm establishes a formal 3-Tier Platform Service Taxonomy.

flowchart TD
    Start["New Platform Service or Capability"] --> Q1{"Who are the primary callers?"}

    Q1 -->|"Browsers, External CLIs, Third-Party Webhooks"| TierA["Tier A: Edge API / HTTP-First\n(services/critique public path)"]
    Q1 -->|"Exclusively Internal Workers (apps/* SSR, Background Queues)"| TierB["Tier B: Internal Edge / RPC-First\n(services/cache-purge)"]
    Q1 -->|"Both External Browsers/CLI AND High-Speed Worker SSR"| TierC["Tier C: Hybrid Platform Service\n(Mandates Shared Domain Service)"]

    subgraph TierARequirements["Tier A Invariants"]
        A1["Public Domain / Custom Route\n(api.<service>.siteswarm.tech)"]
        A2["Dynamic CORS Middleware\n(isAllowedOrigin)"]
        A3["Zod Runtime Schema Validation\n(422 Error Responses)"]
        A4["Origin / Ingress Auth Verification"]
    end

    subgraph TierBRequirements["Tier B Invariants"]
        B1["workers_dev: false\n(Zero Public DNS Routes)"]
        B2["WorkerEntrypoint<Env> implements ServiceRpc\n(Formal TypeScript Interface)"]
        B3["Structured Clone Data Transfer\n(No JSON Boilerplate)"]
        B4["Native Isolate Perimeter Security"]
    end

    subgraph TierCRequirements["Tier C Invariants"]
        C1["Shared Domain Service Layer (ServiceCore)\n- Validation, Dedup, Metadata"]
        C2["HTTP Router calls Domain Service"]
        C3["WorkerEntrypoint RPC calls Domain Service"]
        C4["Zero Divergence Guarantee"]
    end

    TierA --- TierARequirements
    TierB --- TierBRequirements
    TierC --- TierCRequirements

4.1 Taxonomy Overview

Service Tier	Transport Mechanism	Caller Topology	Public Routing Profile	Validation & Security Model	Reference SiteSwarm Services
Tier A (Edge API / HTTP-First)	Direct HTTPS (fetch()) with dynamic CORS	Browsers, mobile WebViews, Node.js CLI tools, external webhooks	Custom domain or workers.dev public route	Zod schema validation on ingress; CORS allowlists or HMAC-SHA256 tokens	@siteswarm/service-critique (browser path), @siteswarm/inquiries
Tier B (Internal Edge / RPC-First)	Cloudflare Service Binding (WorkerEntrypoint)	Edge workers only (apps/* SSR actions, background worker pipelines)	workers_dev: false (Zero public routes)	Compile-time TypeScript interface contracts (implements ServiceRpc); unforgeable isolate security	@siteswarm/service-cache-purge, internal auth token verifier
Tier C (Hybrid Platform Services)	Dual Interface: WorkerEntrypoint RPC + HTTP fetch	Mixed: Browser clients AND internal worker-to-worker pipelines	Public custom domain for HTTP; Service Binding for RPC	Mandatory Shared Domain Service Layer (DomainService) invoked by both HTTP router and RPC methods	@siteswarm/service-critique (target architecture), future CMS API

---

4.2 Tier A: Edge API / HTTP-First Services

Tier A services are built for clients that execute outside Cloudflare’s edge network.

Architectural Invariants:

1. Runtime Input Validation: Every mutation endpoint (POST, PUT, PATCH, DELETE) must validate incoming payloads using Zod schemas (safeParse). Invalid requests must return HTTP 422 with structured issue details ({ success: false, error: "Validation failed", issues: [...] }).
2. Dynamic CORS Middleware: Services must implement dynamic origin verification (isAllowedOrigin(origin)), matching approved development (localhost), pull request preview (*-preview-pr-*), and staging (*-staging.*) patterns. Responses must attach Access-Control-Max-Age: 86400 to cache preflight requests.
3. Public Route Provisioning: Must configure explicit public custom domains in wrangler.jsonc (e.g. critique.siteswarm.tech) or enable workers_dev: true.
4. Ingress Threat Defenses: Must validate Origin/Referer headers or verify signed ephemeral tokens (per write-up #585) to defend against unauthenticated public abuse.
5. Zero Pass-Through Proxy Invariant: Capabilities that originate from the client browser DOM must NOT require client application workers to act as intermediate HTTP-to-RPC proxies. Client applications must be able to embed the capability via direct HTTP egress without adding Service Bindings or server-side proxy routes to their codebase.

---

4.3 Tier B: Internal Edge / RPC-First Services

Tier B services are built for private, high-speed worker-to-worker platform coordination.

Reference Architecture: services/cache-purge

In services/cache-purge/src/index.ts, the service is defined as:

services/cache-purge/src/index.ts

export interface CachePurgeRpc {
  purgeTags(tenantId: string, tags: string[]): Promise<PurgeResult>;
  getPurgeStatus(jobId: string): Promise<PurgeJobRecord | null>;
  getCooldown(tenantId: string): Promise<{ inCooldown: boolean; remainingSeconds?: number } | null>;
}

export default class CachePurgeService extends WorkerEntrypoint<Env> implements CachePurgeRpc {
  async purgeTags(tenantId: string, tags: string[]): Promise<PurgeResult> {
    return purgeTags(tenantId, tags, { ... });
  }
  // ...
}

Architectural Invariants:

1. Zero Public Route Invariant (workers_dev: false): The worker configuration in wrangler.jsonc must set "workers_dev": false and define zero public routes or custom domains. The service must be completely invisible to public internet traffic.
2. Formal TypeScript Interface Contract: The service must export a dedicated TypeScript interface (e.g. export interface CachePurgeRpc). The entrypoint class must explicitly implement this interface (implements CachePurgeRpc).
3. Zero JSON Serialization Overhead: RPC methods must accept and return native JavaScript objects, typed arrays, or primitives. Callers must not stringify or parse JSON.
4. Unforgeable Edge Isolation: Because Service Bindings operate inside Cloudflare’s secure control plane, callers cannot forge their identity if this.ctx or binding parameters are used. No CORS or public ingress auth middleware is required.

---

4.4 Tier C: Hybrid Platform Services

When a platform service must support external callers (e.g. browser overlays, developer CLIs) and internal workers (e.g. SSR route actions, background queues), it operates as a Tier C Hybrid Service.

The Shared Domain Service Layer Mandate:

To prevent the exact architectural drift discovered in services/critique (where RPC bypassed Zod validation and deduplication), Tier C services must encapsulate all business rules in a pure domain service:

services/critique/src/domain.ts

export class CritiqueDomainService {
  constructor(private readonly repository: CritiqueRepository) {}

  async listCritiques(tenantId: string, options?: ListOptions): Promise<Critique[]> {
    if (!tenantId) throw new DomainValidationError("Missing tenantId");
    return this.repository.list(tenantId, options);
  }

  async createCritique(input: unknown, context: IngressContext): Promise<CreateCritiqueResult> {
    // 1. Zod Validation (Applies to BOTH RPC and HTTP)
    const parseResult = createCritiqueSchema.safeParse(input);
    if (!parseResult.success) {
      throw new DomainValidationError("Validation failed", parseResult.error.issues);
    }
    const validated = parseResult.data;

    // 2. Tenant Scoping
    const targetTenant = validated.tenantId || context.tenantId;
    if (!targetTenant) throw new DomainValidationError("Missing required tenantId");

    // 3. Deduplication Check (Applies to BOTH RPC and HTTP)
    const existingList = await this.repository.list(targetTenant);
    if (validated.id) {
      const byId = existingList.find((c) => c.id === validated.id);
      if (byId) return { critique: byId, deduplicated: true };
    }

    const targetKey = getCritiqueDeduplicationKey(validated);
    const existingDuplicate = existingList.find(
      (c) => c.status !== "resolved" && getCritiqueDeduplicationKey(c) === targetKey
    );
    if (existingDuplicate) return { critique: existingDuplicate, deduplicated: true };

    // 4. Entity Construction & Persistence
    const critique: Critique = {
      id: validated.id || crypto.randomUUID(),
      tenantId: targetTenant,
      environment: validated.environment || context.environment || "development",
      url: validated.url,
      componentName: validated.componentName,
      selector: validated.selector,
      textSnippet: validated.textSnippet,
      tags: validated.tags || [],
      comment: validated.comment,
      authorName: validated.authorName,
      status: "open",
      detectedAtVersion: validated.detectedAtVersion || context.version,
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
    };

    const created = await this.repository.create(critique);
    return { critique: created, deduplicated: false };
  }
}

Dual Ingress Wiring:

Both the HTTP router and the WorkerEntrypoint RPC class delegate directly to CritiqueDomainService:

// In services/critique/src/index.ts (RPC Entrypoint)
export default class CritiqueService extends WorkerEntrypoint<Env> implements CritiqueRpc {
  private get domain() {
    return new CritiqueDomainService(new CritiqueRepository(this.env.CRITIQUE_DB));
  }

  async create(input: unknown): Promise<Critique> {
    const res = await this.domain.createCritique(input, { tenantId: "", environment: "" });
    return res.critique;
  }
  // ...
}

// In services/critique/src/router.ts (HTTP Router)
export async function handleRequest(request: Request, env: Env): Promise<Response> {
  const domain = new CritiqueDomainService(new CritiqueRepository(env.CRITIQUE_DB));
  // In POST /critiques:
  try {
    const body = await request.json();
    const res = await domain.createCritique(body, {
      tenantId: request.headers.get("X-SiteSwarm-Tenant-Id") || undefined,
      environment: request.headers.get("X-SiteSwarm-Environment") || undefined,
      // ...
    });
    return applyCors(jsonResponse({ success: true, data: res.critique, deduplicated: res.deduplicated }, res.deduplicated ? 200 : 201), origin);
  } catch (err: any) {
    if (err instanceof DomainValidationError) {
      return applyCors(jsonResponse({ success: false, error: err.message, issues: err.issues }, 422), origin);
    }
    // ...
  }
}

---

4.5 Generalized Platform Capability Decision Matrix (Beyond Critique)

The 3-Tier Taxonomy and the Invocation Origin Litmus Test apply systematically across SiteSwarm’s current and planned platform capabilities:

Platform Capability	Primary Callers	Ingress Tier	Primary Transport Pattern	Rationale & Invariant Enforcement	SiteSwarm Reference Seams
In-Situ Visual Critique (@siteswarm/critique)	Browser overlay (<CritiqueOverlay />), PR preview reviewers, CLI drain	Tier C (Hybrid) (HTTP-First)	Direct HTTPS + Dynamic CORS for browser/CLI; Worker RPC for internal worker automation	Browser DOM origin mandates direct HTTP; client apps avoid pass-through proxy overhead. Shared domain service prevents deduplication bypass.	services/critique, packages/capabilities/critique
Inquiries Intake & Ingestion (@siteswarm/inquiries)	Public website visitors, contact forms, appointment booking widgets	Tier A (Edge API / HTTP-First)	Direct HTTPS POST + CORS with Rate Limiting	User form inputs originate in browser DOM. Direct HTTP to inquiries.siteswarm.tech ensures submissions succeed even if client app backend is static or down. Zero client worker proxying.	services/inquiries, @siteswarm/inquiries
Headless CMS & Content Queries (@siteswarm/cms)	Client Astro/Next.js SSR pages, build-time SSG generators, live admin editors	Tier C (Hybrid)	Worker RPC for SSR page rendering; Direct HTTPS for live in-browser preview editing	Server-side SSR page fetches originate inside edge worker isolates (Worker RPC saves CPU and eliminates network serialization). Live in-browser visual editing originates in browser (Direct HTTP).	services/cms (planned), @siteswarm/client-cms
Edge Cache Invalidation (@siteswarm/service-cache-purge)	CI/CD deploy hooks, CMS publish webhooks, internal cron maintenance	Tier B (Internal Edge / RPC-First)	Cloudflare Service Binding RPC (WorkerEntrypoint)	100% internal worker-to-worker invocation. Zero browser access needed. "workers_dev": false enforces air-gapped private perimeter. Zero JSON serialization overhead.	services/cache-purge
Real-User Monitoring & Telemetry (services/telemetry)	Browser performance metrics (web-vitals), error trackers, worker logs	Tier A (Edge API / HTTP-First)	Direct HTTP (navigator.sendBeacon / POST) with public endpoint	High-frequency telemetry events from browser DOM must not double-invoke client application workers. Uses fire-and-forget direct beaconing.	services/telemetry (planned)
Authentication & Session Tokens (services/auth)	User login forms, OAuth redirects, internal edge middleware token checks	Tier C (Hybrid)	Direct HTTPS for login/OAuth; Worker RPC for SSR session verification	Browser handles public login and cookie exchange via HTTPS. Internal client workers verify session JWTs/tokens on incoming requests via sub-millisecond Worker RPC.	services/auth (planned)

---

5. Eliminating HTTP Boilerplate: Ergonomics, Type Safety & The Type-Safe Client Factory

A primary driver for developers choosing Cloudflare Worker RPC is developer experience: native JavaScript method calls (await env.SRV.get(id)), automatic TypeScript return type inference, and the absence of boilerplate fetch(), JSON.stringify(), and manual header configuration.

However, adopting Worker RPC solely for syntactic convenience introduces the severe architectural baggage documented in §2.3 (double billable invocations, client pass-through proxy routes, and tight coupling).

To achieve the best of both worlds, SiteSwarm codifies four architectural pillars to completely eliminate HTTP boilerplate, delivering an RPC-like developer experience over direct HTTP.

5.1 Pillar 1: Zero-Overhead Type-Safe Client Factory (createPlatformClient<TRouter>)

Inspired by modern edge RPC-over-HTTP patterns (such as Hono RPC and tRPC), SiteSwarm eliminates manual fetch() calls on the client through a lightweight, zero-overhead TypeScript Proxy client factory.

Architectural Mechanics:

1. Zero Runtime Bundle Footprint: The client imports only TypeScript types from the platform service (import type { CritiqueApiRouter }). No server-side runtime code or dependencies are bundled into the client browser build.
2. Proxy-Driven Method Invocations: A ~35-line generic Proxy traps nested property calls (e.g. client.critiques.create({ json: ... })) and translates them into standard HTTP fetch() requests automatically.
3. End-to-End Type Safety & Autocomplete: Request bodies, URL path params, and query strings are statically validated against the server schema at compile time, and the return type is automatically inferred.

packages/capabilities/critique/src/client/api-client.ts

import type { CritiqueApiRouter } from "@siteswarm/service-critique";

// Zero-runtime type import guarantees 0 bytes added to client bundle!
export function createCritiqueClient(baseUrl: string) {
  return createPlatformClient<CritiqueApiRouter>(baseUrl);
}

// Consumer DX (inside <CritiqueOverlay /> or client apps):
const client = createCritiqueClient("https://critique.siteswarm.tech");

// 100% typed parameters, auto-completion, and inferred return type!
// Zero manual fetch(), zero JSON.stringify(), zero status code parsing!
const { data, error } = await client.critiques.post({
  json: {
    tenantId: "bakery",
    url: window.location.href,
    selector: "#hero-title",
    comment: "Update header font size on mobile viewports",
    authorName: "Designer",
    environment: "preview"
  }
});

if (error) {
  console.error(`Critique creation failed (${error.status}):`, error.message);
  return;
}

console.log("Critique created:", data.id); // 'data' is strictly typed as Critique!

Generic Client Factory Implementation (packages/edge-core/src/client.ts):

export interface ApiResponse<T> {
  data: T | null;
  error: { status: number; message: string; issues?: unknown[] } | null;
}

export function createPlatformClient<TRouter>(baseUrl: string): TRouter {
  return new Proxy({} as any, {
    get(_, route: string) {
      return {
        async post(options: { json?: unknown; headers?: Record<string, string> }): Promise<ApiResponse<any>> {
          try {
            const res = await fetch(`${baseUrl.replace(/\/$/, "")}/${route}`, {
              method: "POST",
              headers: {
                "Content-Type": "application/json",
                ...options.headers,
              },
              body: options.json ? JSON.stringify(options.json) : undefined,
            });
            const body = await res.json();
            if (!res.ok) {
              return { data: null, error: { status: res.status, message: body.error || "Request failed", issues: body.issues } };
            }
            return { data: body.data ?? body, error: null };
          } catch (err: any) {
            return { data: null, error: { status: 0, message: err.message || "Network error" } };
          }
        },
        async get(options?: { query?: Record<string, string>; headers?: Record<string, string> }): Promise<ApiResponse<any>> {
          try {
            const queryParams = options?.query ? `?${new URLSearchParams(options.query).toString()}` : "";
            const res = await fetch(`${baseUrl.replace(/\/$/, "")}/${route}${queryParams}`, {
              method: "GET",
              headers: options?.headers,
            });
            const body = await res.json();
            if (!res.ok) {
              return { data: null, error: { status: res.status, message: body.error || "Request failed" } };
            }
            return { data: body.data ?? body, error: null };
          } catch (err: any) {
            return { data: null, error: { status: 0, message: err.message || "Network error" } };
          }
        }
      };
    },
  });
}

---

5.2 Pillar 2: Declarative Edge HTTP Middleware & Router Primitives

On the server side, writing standard Cloudflare Workers HTTP routers typically generates repetitive boilerplate: extracting CORS headers, parsing JSON bodies, wrapping Zod validations, and formatting error responses.

SiteSwarm abstracts this into composable declarative edge middleware:

// services/critique/src/router.ts (Declarative Refactor)
import { createEdgeRouter, validateJson, withDynamicCors } from "@siteswarm/edge-core";
import { createCritiqueSchema, updateCritiqueSchema } from "./schemas";

const router = createEdgeRouter<Env>();

// 1. Automatic Dynamic CORS Middleware with 24-hour preflight caching
router.use(withDynamicCors({
  allowedOrigins: ALLOWED_ORIGIN_PATTERNS,
  maxAge: 86400, // Access-Control-Max-Age: 86400 caches OPTIONS for 24h
}));

// 2. Declarative Route Definition (Eliminates 35+ lines of boilerplate per route)
router.post(
  "/critiques",
  validateJson(createCritiqueSchema), // Automatically validates and emits 422 on failure
  async (req, ctx) => {
    const domain = new CritiqueDomainService(new CritiqueRepository(ctx.env.CRITIQUE_DB));
    const result = await domain.createCritique(req.validJson, ctx.ingress);
    return ctx.json(result.critique, result.deduplicated ? 200 : 201);
  }
);

Boilerplate Eliminated:

• CORS Handling: Automated handling of OPTIONS preflights and Access-Control-Allow-Origin injection across all routes.
• Request Body Parsing: Safe JSON parsing without manual try/catch and await req.json().
• Validation: Schema failures automatically return structured HTTP 422 with Zod issues ({ success: false, error: "Validation failed", issues: [...] }).
• Response Headers: ctx.json(data, status) automatically formats JSON headers and applies CORS credentials.

---

5.3 Pillar 3: Isomorphic Contracts Colocated in the Capability Package (packages/capabilities/<name>)

A natural architectural question is: Should contract schemas and TypeScript types live in a dedicated standalone package (e.g. packages/contracts-<service>) or be colocated directly inside the existing capability package (packages/capabilities/<name>)?

SiteSwarm strongly mandates colocating contracts directly inside the existing capability package (e.g. packages/capabilities/critique/src/schemas.ts and src/types.ts).

Why Colocation in the Capability Package is Superior:

1. Minimal Viable Abstraction (MVA) & Zero Package Bloat: Creating separate contracts-* packages creates monorepo churn: extra package.json manifests, duplicated tsconfig.json files, additional build/typecheck steps in CI, and package proliferation. Colocation keeps the monorepo lean and cohesive.
2. Natural Capability Boundary: In SiteSwarm, a capability package (like @siteswarm/critique or @siteswarm/inquiries) is the canonical SDK for that feature. It packages the frontend UI components (<CritiqueOverlay />), client factory (createCritiqueClient), and contract schemas (createCritiqueSchema) together.
3. Clean Acyclic Monorepo Dependency Graph:
   • packages/capabilities/<name> is a pure leaf package with zero internal monorepo dependencies.
   • Client applications (apps/*) depend on packages/capabilities/<name> to render the UI.
   • The platform service (services/<name>) depends on packages/capabilities/<name> strictly for validation schemas and types.
   • The dependency graph is a strictly unidirectional DAG with zero circular references:

   flowchart TD
       App["Client App (apps/app-bakery)"] -->|"Imports UI & Client"| Cap["Capability Package (@siteswarm/critique)\n(src/schemas.ts, src/types.ts, src/client/)"]
       Service["Platform Service (services/critique)"] -->|"Imports Zod Schemas"| Cap
       Service -.->|"No Dependency"| App

4. Tree-Shaking & Zero Client/Server Leakage:
   • When the edge platform service (services/critique) imports { createCritiqueSchema } from @siteswarm/critique, bundlers tree-shake out all client-side UI and browser code.
   • Conversely, when client apps import TypeScript types (import type { Critique }), type-only imports are stripped at compile time with 0 runtime bytes added to the browser bundle.
5. Instant Frontend Validation with Exact Server Parity:
   • The client UI component runs createCritiqueSchema.safeParse(input) in the browser DOM before firing the network request, giving users instant form validation feedback without network roundtrips.
   • The edge platform service runs the exact same schema upon request receipt, guaranteeing 100% contract parity.

---

5.4 Pillar 4: Built-in Edge Resilience (Timeouts, CORS Caching & Optimistic Sync)

HTTP client boilerplate often stems from defensive programming: setting up timeouts, caching CORS preflights, and handling intermittent network disconnects.

SiteSwarm encapsulates these resilience patterns into standard client utilities:

1. Preflight Optimization: Edge servers return Access-Control-Max-Age: 86400, ensuring the browser only issues an OPTIONS network hop once per 24 hours per origin.
2. Strict Timeouts: All client HTTP requests wrap an AbortSignal.timeout(5000) to prevent hanging promises on mobile viewports.
3. Optimistic Local Storage & Offline Queuing: In <CritiqueOverlay />, user actions are immediately committed to localStorage (providing 0ms instant UI feedback), queued, and synchronized with the platform service in the background. If the reviewer is offline, submissions are preserved and re-attempted automatically upon reconnection.

---

6. Exhaustive Failure-Mode & Edge Constraint Analysis

Architectural evaluations must reflect real production failure modes rather than idealized abstractions.

6.1 Cloudflare Worker RPC Failure Modes

flowchart TD
    subgraph RPC_Failures["Worker RPC Failure Modes"]
        F1["1. Isolate Crash / OOM\n- Callee worker exceeds memory (128MB) or crashes\n- Caller receives generic RpcError\n- Mitigation: Try/Catch + Circuit Breaker"]
        F2["2. Cross-Deployment Schema Drift\n- Caller deploys new method signature before callee deploys\n- Method mismatch throws unhandled exception\n- Mitigation: Additive non-breaking method signatures"]
        F3["3. Structured Clone Serialization Limits\n- Caller passes cyclic object, complex class, or Symbol\n- Structured clone throws DataCloneError at isolate boundary\n- Mitigation: Plain Data Transfer Objects (DTOs)"]
        F4["4. Concurrency & Write Lock Contention\n- Multiple worker isolates invoke RPC concurrently\n- D1 primary SQLite instance emits SQLITE_BUSY\n- Mitigation: Jittered exponential backoff retry in DAO"]
    end

1. Isolate Crashes & Memory Exhaustion (RpcError):
   • If the callee worker isolate crashes due to an out-of-memory (OOM) error (standard workers have 128 MB RAM) or an unhandled top-level exception, Cloudflare’s runtime terminates the isolate and raises an RpcError in the caller worker.
   • Mitigation: Internal callers must wrap RPC invocations in try/catch blocks and provide graceful degradation (e.g. falling back to offline memory queues or logging warnings).
2. Cross-Deployment Schema Drift:
   • In a multi-worker monorepo, workers are deployed via independent CI pipelines. If apps/clk-construction is deployed with a new method call (env.CRITIQUE_SERVICE.batchResolve(...)) before services/critique finishes deploying, the call fails with TypeError: env.CRITIQUE_SERVICE.batchResolve is not a function.
   • Mitigation: Platform RPC interfaces must evolve additively. New capabilities must be deployed to the platform service worker before downstream client workers consume them.
3. Structured Clone Serialization Traps:
   • Worker RPC allows structured cloning, but passing complex custom class instances, cyclic object graphs, functions, or DOM-like elements will throw DataCloneError.
   • Mitigation: Service RPC interfaces must use pure TypeScript data transfer objects (DTOs), primitives, and plain objects.

6.2 HTTP Ingress Failure Modes

flowchart TD
    subgraph HTTP_Failures["HTTP Ingress Failure Modes"]
        H1["1. CORS Preflight Latency & Blockade\n- Browser emits OPTIONS before mutation\n- Network hop adds 20-100ms latency on mobile\n- Disallowed origin yields HTTP 403\n- Mitigation: Access-Control-Max-Age: 86400"]
        H2["2. Mobile Network Timeouts & Dropped Packets\n- Mobile reviewer on flaky 4G/5G loses connection\n- Critique submission hangs or fails\n- Mitigation: AbortSignal.timeout(5000) + Client Retry"]
        H3["3. Unauthenticated Public Ingress Abuse\n- Public URL exposed to internet scrapers and bots\n- Forged Origin headers pass regex allowlists\n- Mitigation: Ephemeral HMAC-SHA256 tokens (#585)"]
        H4["4. JSON Serialization CPU Overhead\n- Stringifying large DOM text snippets & JSON parsing\n- Consumes Worker CPU budget (50ms limit)\n- Mitigation: String truncation (150 chars max) in client"]
    end

1. CORS Preflight Latency & Blocker:
   • Any cross-origin request carrying custom headers (X-SiteSwarm-Tenant-Id, Content-Type: application/json) forces web browsers to issue a synchronous OPTIONS preflight request before sending the payload. On high-latency mobile networks, this doubles perceived mutation latency.
   • Mitigation: The service returns Access-Control-Max-Age: 86400, instructing the browser to cache preflight permission for 24 hours.
2. Mobile Network Timeouts & Flakiness:
   • Reviewers testing mobile viewports in real-world settings experience dropped TCP connections and packet loss.
   • Mitigation: The client overlay in overlay.ts writes immediately to localStorage first (optimistic UI), queues unsynced items, and retries in the background during syncWithServer().
3. Unauthenticated Public Ingress Abuse & Origin Forgery:
   • Because validateOrigin only inspects the Origin header (which non-browser tools like curl can forge), public HTTP endpoints can be probed by external actors.
   • Mitigation: Layering ephemeral HMAC-SHA256 signed tokens (evaluated in write-up #585) ensures cryptographic verification of tenant identity and preview commit SHA.

---

7. Recommended Production Routing & DNS Topology

To resolve the discrepancy in services/critique/wrangler.jsonc (workers_dev: false vs default workers.dev URLs), SiteSwarm establishes a production DNS and routing standard.

7.1 Analysis of Current Subdomain Hardcoding

Currently, packages/capabilities/critique and packages/governance hardcode: https://critique.siteswarm.workers.dev

This presents three operational flaws:

1. workers.dev subdomains require an account prefix: https://siteswarm-critique.<account>.workers.dev.
2. Setting "workers_dev": false disables this URL entirely.
3. Third-party cookies and cross-origin security policies treat *.workers.dev as a public suffix, preventing certain secure cookie and partition optimizations.

7.2 Recommended Domain Conventions

SiteSwarm adopts the following DNS standard for platform services:

Environment	DNS Routing Convention	Cloudflare Zone	Configuration in wrangler.jsonc
Local Development	http://localhost:8787	Local Miniflare / workerd	Default wrangler dev port binding
Staging / PR Previews	https://critique-staging.siteswarm.tech	siteswarm.tech	Custom Domain route on staging environment
Production	https://critique.siteswarm.tech	siteswarm.tech	Custom Domain route on production environment

Production wrangler.jsonc Configuration:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "siteswarm-critique",
  "main": "src/index.ts",
  "compatibility_date": "2026-09-29",
  "compatibility_flags": ["nodejs_compat"],
  "workers_dev": false, // Retained false because public access is mapped to dedicated custom domains!
  "observability": { "enabled": true },
  "env": {
    "staging": {
      "name": "siteswarm-critique-staging",
      "routes": [
        { "pattern": "critique-staging.siteswarm.tech", "custom_domain": true }
      ]
    },
    "production": {
      "name": "siteswarm-critique",
      "routes": [
        { "pattern": "critique.siteswarm.tech", "custom_domain": true }
      ]
    }
  }
}

By configuring { "pattern": "critique.siteswarm.tech", "custom_domain": true }, "workers_dev": false remains safely active (preventing unauthorized execution on default Cloudflare subdomains), while routing production browser traffic through enterprise DNS with Cloudflare WAF, DDoS protection, and SSL certificates.

---

8. Traceability & Acceptance Criteria Verification

8.1 Acceptance Criteria Traceability Matrix

Requirement from Issue #628	Implementation in Evaluation Write-Up	Verification Status
YAML Frontmatter Contract	Valid status: "uningested", source_issue: "#628", candidate_targets	✅ Complete
Empirical RPC vs HTTP Comparison	Comprehensive analysis of workerd isolates, Cap’n Proto, latency, type safety, DX	✅ Complete (§2)
Browser Direct Egress Evaluation	Proof that browsers cannot invoke Service Binding RPCs directly; pass-through proxy anti-pattern	✅ Complete (§2.3)
Audit of services/critique Seams	Identified RPC bypasses of Zod validation, deduplication key, and metadata injection	✅ Complete (§3.1, §3.2)
Consumer Seam Audit	Identified that RPC interface is currently an unused ghost seam (100% traffic is HTTP)	✅ Complete (§3.3)
3-Tier Platform Service Taxonomy	Formally defined Tier A (HTTP-First), Tier B (RPC-First), and Tier C (Hybrid)	✅ Complete (§4)
Generalized Capability Decision Matrix	Codified decision matrix across Inquiries, CMS, Cache Purge, Telemetry, and Auth	✅ Complete (§4.5)
HTTP Boilerplate Elimination	Type-safe client factory (createPlatformClient), declarative middleware, contract schemas	✅ Complete (§5)
Shared Domain Service Layer Mandate	Defined CritiqueDomainService architecture to eliminate validation/dedup drift	✅ Complete (§4.4)
Deployment Routing Discrepancy	Diagnosed workers_dev: false contradiction and defined custom domain standard	✅ Complete (§3.4, §7)
Exhaustive Failure-Mode Analysis	Documented isolate crashes, schema drift, CORS preflight, and network flakiness	✅ Complete (§6)
Shovel-Ready Deferred Tickets	Synthesized 3 follow-up tickets adhering to 4-part Anti-False-Victory schema	✅ Complete (§9)

---

9. Decisions Intentionally Deferred & Shovel-Ready Implementation Tickets

In strict accordance with the Negative Constraints of this architectural spike:

• No codebase modifications have been made to services/critique or canonical architecture specs (docs/architecture/).
• All concrete implementation actions are formulated as shovel-ready follow-up tickets below.

<!-- TICKET_PAYLOAD_START: 1 -->
### Ticket 1: refactor(critique): extract shared domain service layer to harmonize RPC and HTTP validation/deduplication

- **Type**: `refactor`
- **Scope**: `critique-service`
- **Estimated Complexity**: `Medium`
- **Parent Epic**: `#581`
- **Prerequisites**: `#628`

#### Objective
Extract a shared `CritiqueDomainService` within `services/critique/src/domain.ts` that encapsulates Zod validation (`createCritiqueSchema`, `updateCritiqueSchema`), deduplication (`getCritiqueDeduplicationKey`), and metadata enrichment, ensuring that both `handleRequest` (HTTP) and `CritiqueService extends WorkerEntrypoint` (RPC) execute identical business logic without drift.

#### Target Components, Clients & Seams
- `services/critique/src/domain.ts`: New domain service encapsulating validation and deduplication.
- `services/critique/src/index.ts`: Update `CritiqueService` RPC methods to delegate to `CritiqueDomainService`.
- `services/critique/src/router.ts`: Update `handleRequest` HTTP handlers to delegate to `CritiqueDomainService`.
- `services/critique/src/types.ts`: Define formal `CritiqueRpc` interface.

#### Acceptance Criteria

##### 1. Functional Deliverables
- [ ] Implement `CritiqueDomainService` in `services/critique/src/domain.ts` exposing `list`, `create`, `update`, `updateStatus`, and `resolveAddressed`.
- [ ] Move Zod schema validation and content-hash deduplication from `router.ts` into `CritiqueDomainService`.
- [ ] Refactor `CritiqueService extends WorkerEntrypoint<Env>` in `index.ts` to implement `CritiqueRpc` and delegate all method calls to `CritiqueDomainService`.
- [ ] Refactor `handleRequest` in `router.ts` to delegate HTTP request parsing and responses to `CritiqueDomainService`.
- [ ] Ensure invoking `critiqueService.create()` via RPC enforces Zod validation and deduplication identically to HTTP `POST /critiques`.

##### 2. Tier 1 (Machine Gate) Verification
- [ ] `pnpm run check` passes with 0 errors across workspace packages.
- [ ] `pnpm run lint:arch` passes with 0 errors.
- [ ] `pnpm run test:tooling` passes with 0 errors.
- [ ] Unit tests in `services/critique/tests/domain.test.ts` pass verifying domain service validation and deduplication.

##### 3. Tier 2 (Behavioral Runtime Proof) Verification
- [ ] Execute `pnpm --filter @siteswarm/service-critique test` with Miniflare D1 asserting:
  - RPC `create()` with invalid schema throws `DomainValidationError`.
  - RPC `create()` with duplicate content key returns existing critique with `deduplicated: true`.
  - Existing HTTP test suite passes with 100% green assertions and zero regressions.

##### 4. Anti-Mocking & Failure-Mode Guardrails (Definition of NOT Done)
- [ ] **No Mock-Only Proof**: Tests must verify deduplication against a real Miniflare D1 SQLite database.
- [ ] RPC and HTTP methods must not maintain separate, divergent copies of validation or deduplication logic.
- [ ] Failure-Mode Check: Malformed inputs to RPC methods must reject cleanly with structured validation errors rather than unhandled database exceptions.
<!-- TICKET_PAYLOAD_END: 1 -->

<!-- TICKET_PAYLOAD_START: 2 -->
### Ticket 2: fix(critique): configure production custom domain routes and reconcile workers_dev in wrangler.jsonc

- **Type**: `fix`
- **Scope**: `critique-service`
- **Estimated Complexity**: `Low`
- **Parent Epic**: `#581`
- **Prerequisites**: `#628`

#### Objective
Reconcile the deployment routing conflict in `services/critique/wrangler.jsonc` by configuring canonical custom domain routes (`critique.siteswarm.tech` and `critique-staging.siteswarm.tech`) for public HTTP ingress, and update default client URLs in `@siteswarm/critique` and governance tooling.

#### Target Components, Clients & Seams
- `services/critique/wrangler.jsonc`: Add custom domain route patterns for staging and production.
- `packages/capabilities/critique/src/client/overlay.ts`: Update default API endpoint fallback.
- `packages/governance/src/cli/critique.ts`: Update default CLI service URL fallback.

#### Acceptance Criteria

##### 1. Functional Deliverables
- [ ] In `services/critique/wrangler.jsonc`, configure staging custom domain `critique-staging.siteswarm.tech` and production custom domain `critique.siteswarm.tech`.
- [ ] Maintain `"workers_dev": false` to prevent unrouted execution on default account subdomains.
- [ ] Update default `apiEndpoint` in `packages/capabilities/critique/src/client/overlay.ts` to `https://critique.siteswarm.tech`.
- [ ] Update `getCritiqueServiceUrl()` in `packages/governance/src/cli/critique.ts` to default to `https://critique.siteswarm.tech`.

##### 2. Tier 1 (Machine Gate) Verification
- [ ] `pnpm run check` passes with 0 errors across workspace packages.
- [ ] `pnpm run lint:arch` passes with 0 errors.
- [ ] `pnpm run test:tooling` passes with 0 errors.

##### 3. Tier 2 (Behavioral Runtime Proof) Verification
- [ ] Run `npx wrangler deploy --dry-run` or configuration validation script confirming valid wrangler JSONC schema and routes.
- [ ] Verify unit tests in `@siteswarm/critique` and `@siteswarm/governance` pass with updated defaults.

##### 4. Anti-Mocking & Failure-Mode Guardrails (Definition of NOT Done)
- [ ] Do not remove `"workers_dev": false` without adding explicit custom domain routes.
- [ ] Default URLs must not point to fictitious non-existent worker subdomains.
<!-- TICKET_PAYLOAD_END: 2 -->

<!-- TICKET_PAYLOAD_START: 3 -->
### Ticket 3: docs(architecture): distill 3-tier platform service taxonomy and HTTP boilerplate reduction into MULTI_WORKER_PLATFORM_SERVICES.md

- **Type**: `documentation`
- **Scope**: `docs`
- **Estimated Complexity**: `Low`
- **Parent Epic**: `#581`
- **Prerequisites**: `#628`

#### Objective
Distill the SiteSwarm 3-Tier Platform Service Taxonomy, Generalized Capability Decision Matrix, and HTTP Boilerplate Reduction architecture ratified in `#628` into canonical living architecture documentation (`docs/architecture/MULTI_WORKER_PLATFORM_SERVICES.md` and `docs/architecture/CAPABILITY_MANAGEMENT.md`).

#### Target Components, Clients & Seams
- `docs/architecture/MULTI_WORKER_PLATFORM_SERVICES.md`: Add section codifying Tier A, Tier B, and Tier C service models, the Generalized Capability Decision Matrix, and the Type-Safe Client Factory pattern.
- `docs/architecture/CAPABILITY_MANAGEMENT.md`: Cross-reference platform service taxonomy.
- `docs/write-ups/critique-rpc-vs-http-evaluation.md`: Update frontmatter status to `distilled`.

#### Acceptance Criteria

##### 1. Functional Deliverables
- [ ] Integrate Tier A (Edge API / HTTP-First), Tier B (Internal Edge / RPC-First), and Tier C (Hybrid) into `MULTI_WORKER_PLATFORM_SERVICES.md`.
- [ ] Incorporate the Generalized Platform Capability Decision Matrix (Critique, Inquiries, CMS, Cache Purge, Telemetry, Auth).
- [ ] Codify the 4 Pillars of HTTP Boilerplate Elimination (`createPlatformClient<TRouter>`, declarative middleware, isomorphic schemas, edge resilience).
- [ ] Document the Shared Domain Service Layer mandate for Tier C services.
- [ ] Update `docs.ts audit` frontmatter status of `#628` write-up to `distilled`.

##### 2. Tier 1 (Machine Gate) Verification
- [ ] `pnpm run check` passes with 0 errors.
- [ ] `pnpm run lint:arch` passes with 0 errors.
- [ ] `pnpm run test:tooling` passes with 0 errors.

##### 3. Tier 2 (Behavioral Runtime Proof) Verification
- [ ] Execute `npx tsx .agents/skills/docs/scripts/docs.ts audit` confirming 0 lint errors and accurate categorization.

##### 4. Anti-Mocking & Failure-Mode Guardrails (Definition of NOT Done)
- [ ] Canonical documentation must not claim that browser JavaScript can invoke Service Binding RPCs directly.
<!-- TICKET_PAYLOAD_END: 3 -->