Edge services consumed only through a seam with a local equivalent runner

decisionactive owner: philip · updated 2026-11-14

Cloudflare Pages + Access + Workers is the chosen platform for publishing the KB to colleagues ($0 tier, git-native deploys, edge auth, AI-update endpoint).
The platform must never be used directly from product code or agent workflows; every interaction goes through an abstraction seam.
The factory already follows this pattern: core.Store with memstore/dynamostore adapters, outbox mock senders, fakedynamo tests — production adapters are env-selected, never hard-coded.
Philip's testing standard requires unit tests at the base, an API-contract-identical mock layer, functional tests on top, and automatic CI.

All Cloudflare interactions (Pages deploys, Access-protected endpoints, Workers API) are consumed only through a seam module in the KB toolchain, never via direct wrangler/dashboard/API calls from workflows.
The seam ships with a local equivalent runner: wrangler dev (Miniflare) for Workers — local KV/D1/R2 emulation and .dev.vars secrets — and a local static server (mkdocs serve or python3 -m http.server) for Pages content.
The seam's interface is the contract: local and production differ only in base URL and credentials (env-selected), mirroring the store-adapter pattern.
The AI-update write path is: agent → seam client → Worker endpoint (secret-gated) → GitHub commit → Pages rebuild. The compile gate (compile.py --check) runs in CI on every push; the Worker never runs the compiler.
Content audit trail is git history; Workers Logs (7-day retention) are operational visibility only. Long-term logs export via Logpush to R2 if ever needed.

Development and tests run fully offline against the local runner; Cloudflare credentials are needed only for production deploys.
The seam is a small TypeScript module plus thin Python/shell clients; it must stay thinner than the platform APIs it wraps.
Switching edge providers later means swapping the seam adapter, not rewriting consumers — same property the factory store adapters provide.
Miniflare emulation is not byte-identical to production Workers (isolate limits, bindings behavior); contract tests must target the seam interface, not Miniflare internals.
The KB repo must be on GitHub before Pages can auto-deploy from pushes (Direct Upload is the pre-GitHub fallback).