engsys 1.0.0

package/stacks/cloud/azure/skills/cloud-architecture-azure/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: cloud-architecture-azure
+description: Azure service-level architecture knowledge — compute (Container Apps/AKS/Functions), data (PostgreSQL Flexible Server/Cosmos DB), messaging (Service Bus/Event Grid/Event Hubs), edge (Front Door/API Management), identity (Entra), storage + secrets (Blob/Key Vault/ACR), and Azure OpenAI. Cost models, service limits, failure modes, and cold-start gotchas. Activate when the active cloud is Azure and the work involves designing, scaling, costing, or diagnosing Azure architecture (Container Apps cold starts, PostgreSQL connection limits, Service Bus quotas, Front Door, NAT egress).
+---
+
+# Azure Architecture Knowledge
+
+Service-level detail for an Azure-backed project. Pairs with Melvin's cloud-agnostic
+diagnostic checklist (traffic pattern, state location, SLAs, blast radius, cost
+explosion, coordination, limits, observability) — this pack supplies the Azure-specific
+answers. For concrete topology, cost tiers, and stack context, read the architecture
+docs named in `CLAUDE.md`. For deep service docs use the `microsoft-docs` skill
+(Microsoft Learn MCP).
+
+## Compute
+
+### Azure Container Apps (ACA)
+
+- Serverless containers on managed Kubernetes (KEDA-based autoscaling). **Scale to
+  zero** is the cost win — and the latency trap: a scaled-to-zero app pays a **cold
+  start** (image pull + container start, seconds) on the next request. For latency-
+  sensitive services set **`minReplicas >= 1`** (a warm replica) — the ACA analogue of
+  provisioned concurrency.
+- **Revisions:** each config/image change creates a revision; traffic-split between
+  them for blue/green and canary. The phantom "revision nobody recognizes" is usually a
+  stale active revision still taking traffic — check the revision list and traffic split.
+- **Scaling:** KEDA scale rules on HTTP concurrency, CPU/memory, or queue length
+  (Service Bus, etc.). Per-app and per-environment replica ceilings apply — know them
+  before you bet a spike on autoscale.
+- **Good for:** microservices, HTTP APIs, queue/event workers. Prefer it over AKS unless
+  you genuinely need Kubernetes primitives.
+
+### AKS
+
+- Full Kubernetes — reach for it only when you need operators, complex scheduling,
+  service mesh, or a multi-tenant platform. Otherwise it's operational overhead you'll
+  regret; Container Apps or Functions usually suffice.
+
+### Azure Functions
+
+- Event-driven serverless. **Consumption** plan scales to zero (cold starts) and bills
+  per execution+GB-s; **Premium** keeps pre-warmed instances (no cold start, VNet
+  integration); **Dedicated/App Service** for predictable steady load. Durable Functions
+  for orchestration/fan-out-fan-in workflows.
+
+## Data
+
+### PostgreSQL Flexible Server
+
+- **Connection limits** scale with tier/size and are the classic bottleneck —
+  serverless/many-replica apps exhaust them. Use **PgBouncer** (built-in pooler) — but
+  it is **not available on the Burstable tier**; only GeneralPurpose+ supports it (see
+  the IaC lessons). On Burstable, pool in-app or upsize.
+- **Tiers:** Burstable (`B`-series — dev/cheap, throttled baseline CPU, no PgBouncer) →
+  GeneralPurpose (`D`-series) → MemoryOptimized (`E`-series). HA = zone-redundant standby
+  (failover drops connections — apps must reconnect/retry). Read replicas scale reads.
+- **The metric is `active_connections`**, not `connection_percent` (that's Azure SQL) —
+  matters for alerts (see IaC lessons).
+- IOPS and storage scale together up to a point; provisioned IOPS available on higher
+  tiers. Watch IOPS on write-heavy workloads.
+
+### Cosmos DB
+
+- Globally-distributed multi-model. **Partition key design is everything** — a hot
+  partition throttles (429) regardless of total RU/s; each physical partition caps
+  ~10,000 RU/s. Pick a high-cardinality, evenly-accessed key.
+- **Throughput:** provisioned RU/s (manual or autoscale) vs **serverless** (pay-per-
+  request, good for spiky/dev). Five tunable consistency levels (Strong → Eventual) —
+  stronger costs more RU and latency; Session is the usual default.
+- Cost is RU-driven: large items, cross-partition queries, and indexing-everything
+  inflate it. Tune the indexing policy.
+
+## Messaging & Orchestration
+
+### Service Bus
+
+- Enterprise broker: **queues** (point-to-point) and **topics/subscriptions** (pub/sub
+  with SQL/correlation filters). **Sessions** for ordered/grouped processing, **DLQ**
+  built-in (configure max delivery count), scheduled + deferred messages, duplicate
+  detection.
+- **Tiers:** Basic (queues only) / Standard (topics, pay-per-op) / **Premium**
+  (dedicated capacity, predictable latency, VNet, larger messages, required for serious
+  throughput). Standard has per-namespace throughput limits — Premium for high volume.
+- Lock duration must exceed processing time or you get redelivery — idempotent consumers
+  required.
+
+### Event Grid / Event Hubs
+
+- **Event Grid:** lightweight reactive pub/sub for discrete events (resource changes,
+  custom topics) with filtering — fan-out, low latency, cheap.
+- **Event Hubs:** high-throughput streaming/ingestion (Kafka-compatible), partitioned,
+  consumer groups — telemetry, log/event firehose. Use Event Hubs for *streams*, Event
+  Grid for *discrete events*, Service Bus for *transactional work queues*.
+
+### Durable Functions / Logic Apps
+
+- Durable Functions for code-first orchestration; Logic Apps for low-code connector-
+  driven integration workflows.
+
+## Edge & Networking
+
+### Front Door
+
+- Global L7 load balancer + CDN + WAF at the edge. Anycast routing, TLS termination,
+  caching, path/host routing to origins. Use it for global entry, edge caching, and WAF;
+  cache key + rules drive hit ratio.
+
+### API Management (APIM)
+
+- Full API gateway: policies (rate limiting, transformation, auth), product/subscription
+  keys, developer portal. Heavier (and pricier — Consumption tier for serverless-style
+  billing, Developer/Standard/Premium otherwise) than Front Door routing; use when you
+  need real API-management features.
+
+### VNet / Networking — cost landmines
+
+- **NAT Gateway** + outbound data processing, and **cross-zone / cross-region data
+  transfer** are the egress budget-eaters (same shape as every cloud). Use **Private
+  Endpoints / Private Link** to keep traffic off the public path and **Service
+  Endpoints** where applicable. Default to private; public only where required.
+
+## Identity
+
+### Microsoft Entra
+
+- **Entra ID** (workforce) and **Entra External ID** (customers/CIAM — the successor to
+  Azure AD B2C) for app auth: OIDC/OAuth2, social + federated IdPs, MFA, conditional
+  access. **Managed identities** (system- or user-assigned) are the right way for
+  Azure resources to authenticate to each other — no secrets in code. Prefer managed
+  identity + Key Vault references over connection strings everywhere.
+
+## Storage, Secrets & Registry
+
+### Blob Storage
+
+- Tiers: Hot → Cool → Cold → Archive (retrieval latency/cost). Lifecycle policies to
+  age data down. Encryption at rest by default. Cost = storage + transactions + egress.
+
+### Key Vault
+
+- Secrets, keys, certs. Reference from Container Apps / App Service as secret refs and
+  from Bicep via `getSecret()` — keep secrets out of templates and env files. **Name is
+  globally unique** and **soft-deleted on delete** (purge protection can block name
+  reuse) — see IaC lessons. RBAC or access-policy authorization model; managed identity
+  for access.
+
+### Azure Container Registry (ACR)
+
+- Private image registry. **SKU restrictions bite** (see IaC lessons): Basic may be
+  unavailable on some subscriptions; `retentionPolicy` requires **Premium** (remove it
+  from Standard dev/staging). Use managed identity / ACR tokens for pulls.
+
+## Azure OpenAI / AI
+
+- Managed OpenAI + Azure-hosted models via deployments. **Capacity is in TPM (tokens-
+  per-minute) quota per deployment per region** — the throughput ceiling; a naive high-
+  volume pipeline hits 429s, so request quota early and add backoff. **Provisioned
+  Throughput Units (PTUs)** reserve guaranteed capacity/latency (committed spend) vs
+  pay-as-you-go. Model availability varies by region. Pair with **Azure AI Search** for
+  managed RAG. Cost is token-driven — right-size the model per task.
+
+## Cost realism (where Azure bills explode)
+
+1. **NAT Gateway / outbound data processing** — per-GB egress. Use Private Endpoints.
+2. **Cross-zone / cross-region data transfer** — per-GB.
+3. **Container Apps / Functions over-provisioning** — vCPU-s on idle min-replicas.
+4. **PostgreSQL IOPS + over-sized tier**; Cosmos RU/s over-provisioning.
+5. **Service Bus Premium** dedicated capacity; APIM tier.
+6. **Azure OpenAI tokens / PTUs**.
+7. **Front Door + Blob egress**.
+
+Levers: Reservations / Savings Plans (steady baseline), Spot VMs (fault-tolerant batch),
+right-sizing from Azure Monitor, Private Endpoints, Blob lifecycle tiering, Cost
+Management budgets + alerts.
+
+## Service limits (check before betting on them)
+
+Container Apps replicas per app/environment, Functions scale limits, Service Bus per-
+namespace throughput (Standard) + entity counts, PostgreSQL `max_connections` per tier,
+Cosmos RU/s per partition, Front Door routes, APIM throughput per tier, Azure OpenAI
+TPM/PTU per region, Key Vault transactions/sec, subscription-level vCPU quotas per
+region/family. Raise soft quotas via support with lead time.
+
+## Observability
+
+Azure Monitor (metrics + alerts), **Log Analytics workspace** (the store the
+`AppRequests`/`ContainerAppConsoleLogs` tables live in — KQL queries scope to the
+*workspace*, not App Insights), Application Insights (APM/distributed tracing). Alarm on
+Container Apps replica count + restarts, Service Bus DLQ depth + active message count,
+PostgreSQL `active_connections` + CPU, Cosmos 429 rate + RU consumption, Front Door
+backend health.
+
+## Hard-won lessons
+
+### Container Apps VNet integration cannot be retrofitted
+**Symptom:** You need Private Endpoints (e.g. a private DB path) but the Container
+Apps environment was created without VNet integration; there's no in-place toggle.
+**Cause:** A VNet-integrated ACA environment routes egress through the VNet — that's
+a creation-time property of the *environment*, not a setting you can flip later.
+**Fix:** Create the environment **VNet-integrated from the start** whenever Private
+Endpoints/Link are on the roadmap (do it while the resource group is still empty).
+Retrofitting means tearing down and recreating the environment.
+
+### Deploy by immutable digest + unique revision; verify the active revision
+**Symptom:** A "green" deploy reports success but the running app is still the old
+build — the new code never actually took traffic.
+**Cause:** A mutable image tag (`:latest`) can resolve to a stale layer, or a config
+change that produces no new revision leaves the prior revision active.
+**Fix:** Deploy by **immutable image digest** with a **unique revision suffix**, then
+**verify the active revision** after deploy (revision list + traffic split). Treat
+the post-deploy revision check as part of the deploy, not an afterthought.

package/stacks/cloud/cloudflare/claude.fragment.md

@@ -0,0 +1,21 @@
+## Cloud stack
+
+- **Active cloud: Cloudflare.** Architecture and deploys target Cloudflare's edge
+  (Workers/Pages + R2/D1/KV/Durable Objects/Queues); agents load the
+  `cloud-architecture-cloudflare` and `cloudflare-deployment-preflight` skill packs.
+- **Tool preference order** (when investigating or validating cloud state):
+  1. **Wrangler CLI, read-only** — `wrangler whoami`, `wrangler deploy --dry-run`,
+     `wrangler d1 list` / `wrangler d1 info`, `wrangler kv namespace list`,
+     `wrangler r2 bucket list`, `wrangler queues list`, `wrangler versions list`,
+     `wrangler secret list`, `wrangler tail` and similar inspection commands. Never
+     mutate state to answer a question.
+  2. **Docs source** — official Cloudflare documentation (developers.cloudflare.com) for
+     service limits, plan tiers, pricing, and binding/API behavior. Limits are plan-tier
+     dependent and change — verify against docs rather than from memory.
+- Mutating actions (`wrangler deploy`, `secret put`, `d1 execute`, `d1 migrations apply`,
+  `r2 object delete`, `delete`) go through the `cloudflare-deployment-preflight` gate and
+  a staged `versions upload` + gradual rollout, never an ad-hoc bare deploy.
+
+<!-- naturalize: confirm the Cloudflare account, the plan tier (Free/Paid/Enterprise —
+limits depend on it), the state primitives in use (KV/D1/DO/R2), and the path to the
+architecture/cost docs Melvin and Aaron should read for concrete topology. -->

package/stacks/cloud/cloudflare/settings.fragment.json

@@ -0,0 +1,31 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(wrangler whoami:*)",
+      "Bash(wrangler deploy --dry-run:*)",
+      "Bash(wrangler pages functions build:*)",
+      "Bash(wrangler d1 list:*)",
+      "Bash(wrangler d1 info:*)",
+      "Bash(wrangler d1 migrations list:*)",
+      "Bash(wrangler kv:key list:*)",
+      "Bash(wrangler kv:namespace list:*)",
+      "Bash(wrangler kv namespace list:*)",
+      "Bash(wrangler r2 bucket list:*)",
+      "Bash(wrangler queues list:*)",
+      "Bash(wrangler versions list:*)",
+      "Bash(wrangler versions view:*)",
+      "Bash(wrangler secret list:*)",
+      "Bash(wrangler tail:*)"
+    ],
+    "deny": [
+      "Bash(wrangler delete:*)",
+      "Bash(wrangler d1 execute:*)",
+      "Bash(wrangler d1 migrations apply:*)",
+      "Bash(wrangler secret put:*)",
+      "Bash(wrangler secret delete:*)",
+      "Bash(wrangler r2 object delete:*)",
+      "Bash(wrangler kv:key delete:*)"
+    ]
+  },
+  "mcpServers": {}
+}

package/stacks/cloud/cloudflare/skills/cloud-architecture-cloudflare/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: cloud-architecture-cloudflare
+description: Cloudflare edge/serverless architecture knowledge — compute (Workers isolates/Containers, smart placement), Pages, storage (R2/D1/KV/Durable Objects/Vectorize), messaging (Queues), AI (Workers AI/AI Gateway), and origin pooling (Hyperdrive/Cache API). CPU-time and subrequest limits, consistency tradeoffs, failure modes, and request+CPU pricing gotchas (no R2 egress). Activate when the active cloud is Cloudflare and the work involves designing, scaling, costing, or diagnosing Cloudflare architecture (Workers CPU limits, D1 write limits, KV eventual consistency, Durable Object single-threading, R2 egress savings, subrequest caps).
+---
+
+# Cloudflare Architecture Knowledge
+
+Service-level detail for a Cloudflare-backed project. Pairs with Melvin's cloud-agnostic
+diagnostic checklist (traffic pattern, state location, SLAs, blast radius, cost
+explosion, coordination, limits, observability) — this pack supplies the Cloudflare-specific
+answers for each. Cloudflare's model is fundamentally different from AWS/Azure: there are
+no regions you provision into and no VMs — code runs in **V8 isolates** at the edge POP
+nearest the user, and state lives in purpose-built edge primitives. For concrete project
+topology, cost tiers, and stack context, read the architecture docs named in `CLAUDE.md`.
+
+## Compute
+
+### Workers (isolates)
+
+- **No cold starts.** Workers run as **V8 isolates**, not containers/VMs — a new isolate
+  spins up in <5ms (often "zero" perceived) because there's no OS/runtime boot. This is
+  the headline architectural difference from Lambda/Cloud Functions/Container Apps: the
+  "scale to zero costs you a cold start" tradeoff that dominates AWS/Azure design simply
+  doesn't exist here. Design for it — short-lived, stateless request handlers are ideal.
+- **CPU-time limit, not wall-clock.** The cap is **CPU time**, default **30s** on paid,
+  configurable up to **5 minutes** (`limits.cpu_ms` in `wrangler.toml`, max 300000).
+  Free plan is **10ms** CPU/request. Crucially, **time spent awaiting I/O (fetch, KV, D1)
+  does not count** against CPU time — a Worker can wait minutes on a slow subrequest and
+  burn near-zero CPU. The killer is *compute* (crypto, JSON parsing huge payloads, image
+  work, regex backtracking), not waiting. The historical "50ms CPU" number was the old
+  default; the platform now allows far more, but **a CPU-bound hot path is still where you
+  get `Exceeded CPU` (Error 1102) errors** — profile and offload heavy compute.
+- **Subrequest limit** is the other hard ceiling: **50 subrequests/request on Free, 1000
+  on paid** (`fetch` + binding calls to KV/D1/R2/service bindings each count). A Worker
+  that fans out per-item to an API or DB will hit this — batch, cache, or move the fan-out
+  into a Durable Object / Queue consumer. Simultaneous open connections cap at ~6.
+- **Memory** is **128MB per isolate** — hard limit, `Exceeded Memory` (1102) on overflow.
+  No tuning knob like Lambda's memory→CPU slider. Stream large bodies; never buffer a big
+  R2 object fully into memory.
+- **Bundle size:** 3MB (Free) / 10MB compressed (paid) per Worker script. Heavy npm deps
+  (especially Node built-ins needing `nodejs_compat`) bloat this — tree-shake.
+- **Good for:** edge APIs, auth/routing/transform middleware, request shaping, glue.
+  **Bad for:** CPU-heavy batch, anything needing >128MB RAM, long-running stateful compute
+  (use Containers or push to a real backend via Hyperdrive).
+
+### Workers Containers
+
+- For workloads that don't fit the isolate model (full Linux, large memory, arbitrary
+  runtimes, heavy CPU, existing Docker images), **Workers Containers** run actual
+  containers, *orchestrated by a Durable Object* and programmatically started/stopped from
+  a Worker. Unlike isolates, containers **do have cold starts** (image pull + boot) and
+  bill for the time they're running — the AWS Fargate tradeoff reappears here. Use them as
+  the escape hatch, not the default; keep the hot path on isolates.
+
+### Smart Placement
+
+- By default a Worker runs at the POP nearest the *user*. If the Worker makes several
+  round trips to a **centralized origin** (a DB in one region, a slow upstream API), edge
+  placement means each subrequest pays the full user→origin latency. **Smart Placement**
+  (`placement = { mode = "smart" }`) lets Cloudflare instead run the Worker near the
+  *origin*, collapsing N origin round-trips into one user round-trip. Win when the Worker
+  is back-end-chatty; no benefit (or slightly worse) for a Worker that mostly serves edge
+  data (KV/cache/static). Pair origin-DB Workers with Smart Placement + Hyperdrive.
+
+### Pages
+
+- Git-integrated hosting for static sites + SPA/SSR frameworks, with **Pages Functions**
+  (Workers under the hood, file-based routing in `functions/`). Automatic preview
+  deployments per branch/PR. Increasingly converging with Workers (Workers now also serves
+  static assets via the `assets` binding) — for new projects prefer **Workers + static
+  assets** unless you specifically want Pages' Git/CI ergonomics. Same isolate runtime,
+  same limits apply to the Functions.
+
+## Storage & Data
+
+The hardest part of Cloudflare design is **picking the right state primitive** — each has
+a sharp consistency/latency/cost profile and they are *not* interchangeable.
+
+### R2 (object storage)
+
+- S3-compatible object storage with the headline feature: **zero egress fees.** You pay
+  storage + per-operation (Class A writes/lists ~$4.50/M, Class B reads ~$0.36/M) but
+  **never** for data transferred out. This inverts the AWS cost calculus — for
+  egress-heavy workloads (media, model weights, large downloads, multi-cloud data sharing)
+  R2 can be dramatically cheaper than S3. The cost trap moves to **operation counts**: a
+  workload doing millions of tiny PUTs/LISTs pays on Class A ops even though bytes are
+  cheap.
+- Strongly read-after-write consistent for new objects. Supports multipart upload,
+  presigned URLs, lifecycle rules, event notifications (→ Queues), and bucket-level
+  jurisdiction (EU). Access from a Worker via an R2 binding (no egress, no auth round
+  trip) or via the S3 API. **Stream** objects through the Worker — don't buffer (128MB
+  isolate cap).
+- **Failure mode:** R2 ops still count as subrequests from a Worker and are subject to the
+  per-request subrequest cap.
+
+### D1 (SQLite at the edge)
+
+- Managed **SQLite**, exposed to Workers via a binding. Real SQL, transactions, and now
+  **read replicas** (Sessions API routes reads to a nearby replica and guarantees
+  read-your-writes for that session). The primary is single-region; replicas are eventually
+  consistent — writes always go to the primary, so **write latency from a far POP includes
+  the round trip to the primary region.**
+- **Limits that bite:** **10GB max per database** (it's SQLite, not a sharded cluster —
+  this is a hard product ceiling, plan sharding/partitioning early), max **~50 databases**
+  worth of bindings per Worker, **100MB max** per query result / row size limits,
+  parameter limits per statement. Billing is by **rows read + rows written** (not queries)
+  — an unindexed query that scans the table bills every row scanned. **Index aggressively**;
+  watch `rows_read` in the query metadata.
+- **Good for:** per-tenant/per-app relational data, config, low-to-moderate write volume.
+  **Bad for:** a single large multi-tenant OLTP database (10GB ceiling, single-writer),
+  high-write-fan-in. For those, use Hyperdrive → a real Postgres, or many D1s sharded by
+  tenant.
+
+### KV (key-value)
+
+- Global, **eventually consistent** key-value store optimized for **high-read, low-write,
+  read-from-everywhere** (config, feature flags, routing tables, cached tokens, session
+  lookups). Reads are fast at the edge (cached at the POP after first read); writes
+  propagate globally with **eventual consistency — up to ~60s** to be visible everywhere.
+- **Do not use KV where you need read-after-write or coordination.** Last-write-wins, no
+  transactions, no conditional writes across the global view. A counter or a "did I already
+  process this" flag in KV will lose updates and read stale — that's a Durable Object job.
+- **Limits:** value max 25MB, key max 512 bytes, and a soft guidance of **~1 write/sec per
+  key** (writes to the *same* key are rate-limited and the slow-propagation makes
+  write-heavy patterns wrong). Billing per read/write/delete/list op + storage.
+
+### Durable Objects (single-threaded coordination)
+
+- The coordination primitive — a **single-threaded, globally-unique, addressable** object
+  instance (one per ID, with **transactional, strongly-consistent storage** colocated with
+  the compute). Because exactly one instance handles all requests for a given ID,
+  **serially**, it's the right tool for anything KV/D1 can't do safely: counters,
+  rate limiters, locks, leader election, real-time **WebSocket** rooms/hubs, collaborative
+  state, per-entity state machines.
+- **Single-threaded = the throughput ceiling.** All requests to one DO ID queue and run one
+  at a time. A "hot object" (one room/tenant taking all the traffic) becomes a bottleneck
+  no horizontal scaling fixes — **shard the keyspace** so load spreads across many DO IDs.
+  This is the DO analogue of DynamoDB's hot partition.
+- **WebSockets:** DOs are *the* way to do stateful WebSockets at the edge. Use the
+  **Hibernation API** — a DO with idle WebSockets can be evicted from memory (you stop
+  paying for active duration) while keeping connections open, rehydrating on the next
+  message. Without hibernation, thousands of idle long-lived sockets pin the DO in memory
+  and bill continuously.
+- **Alarms:** a DO can schedule itself to wake later (`storage.setAlarm`) — the primitive
+  for per-object timers, retries, scheduled flushes, debouncing, and reliable background
+  work without a cron. Survives eviction.
+- **Placement:** a DO lives in one location (near first access, or pinned by jurisdiction).
+  Cross-region access to a DO pays that latency — colocate the DO with its primary traffic.
+- **Cost:** billed on **active duration (GB-s) + requests**; SQLite-backed DOs add
+  rows-read/written billing. Hibernation is the key lever to avoid paying for idle.
+
+### Vectorize
+
+- Managed **vector database** for embeddings — semantic search and RAG over Workers AI /
+  external embeddings. Create indexes with a fixed dimension + distance metric (cosine/
+  euclidean/dot). Supports metadata filtering and namespaces. **Limits** on vectors per
+  index, dimensions, and metadata size — check before betting a large corpus on it; for
+  very large/complex vector workloads a dedicated vector DB via Hyperdrive may fit better.
+  Pairs naturally with Workers AI (embed) + an LLM (generate) for an all-edge RAG stack.
+
+### Cache API
+
+- Programmatic access to Cloudflare's **CDN cache** from inside a Worker
+  (`caches.default.match/put`). Distinct from KV: it's **per-POP** (not global — a cache
+  put in one POP isn't visible in another), tied to the CDN, and ideal for caching
+  subrequest/compute results at the edge with normal HTTP cache semantics. Use it to
+  collapse repeated origin/compute work per-POP and stay under the subrequest cap. Respect
+  `Cache-Control`; a bad cache key (unique query param) tanks hit ratio just like CloudFront.
+
+## Messaging
+
+### Queues
+
+- Managed **message queue** with Worker producers and consumers, **at-least-once** delivery
+  (idempotent consumers mandatory), **batching** (consumer gets a batch — tune
+  `max_batch_size` / `max_batch_timeout`), **retries** with configurable `max_retries`, and
+  a **dead-letter queue** for poison messages (always configure one, exactly as with SQS).
+- The right tool to **decouple** work from the request path and to **get under the
+  subrequest limit**: instead of fanning out 500 API calls inside one Worker, enqueue 500
+  messages and let the consumer process them in batches across many invocations. Also
+  smooths spikes and isolates a slow downstream from user latency.
+- Throughput/message-size limits apply (message ≤128KB, throughput quotas per queue) —
+  check before betting a very high-volume pipeline on it.
+
+## AI
+
+### Workers AI
+
+- Run inference (LLMs, embeddings, image, speech, classification) on Cloudflare's **GPU
+  edge network** via a binding — no infra, no GPU to provision. Billed on **Neurons** (a
+  normalized compute unit) with a daily free allocation. **Quotas/rate limits per model**
+  will throttle a naive high-volume pipeline — back off and batch. Model availability and
+  context limits vary by model; pick the smallest model that does the job (don't run a
+  large LLM for a classification). Pairs with Vectorize for edge RAG.
+
+### AI Gateway
+
+- A **proxy/control-plane in front of *any* model provider** (Workers AI, OpenAI,
+  Anthropic, etc.) that adds **caching** (dedup identical prompts → big cost saver),
+  **rate limiting**, **retries/fallbacks** across providers, request logging, and analytics
+  — without changing your application code beyond the endpoint. Use it as the single
+  chokepoint for all LLM traffic to control cost, observe spend, and add resilience. The
+  caching layer alone often pays for itself on repetitive prompts.
+
+## Origin connectivity
+
+### Hyperdrive
+
+- **Connection pooling + query caching in front of an external origin database**
+  (Postgres/MySQL — e.g. RDS, Cloud SQL, Neon, Supabase). Solves the exact problem that
+  bites serverless + Postgres everywhere: each Worker invocation would otherwise open a new
+  DB connection and exhaust `max_connections` (the Lambda+RDS mismatch). Hyperdrive
+  **pools** connections at the edge so thousands of Workers share a small pool, and
+  **caches** read queries to cut round trips. It also keeps a warm connection to the
+  origin, hiding connection-setup latency.
+- Use it whenever Workers talk to a traditional regional SQL database. Pair with **Smart
+  Placement** so the Worker runs near the origin. This is the Cloudflare answer to RDS
+  Proxy / PgBouncer — without it, a busy Worker fleet will knock over the origin DB on
+  connection count alone.
+
+## Consistency model cheat-sheet (pick the right primitive)
+
+| Need | Use | Consistency |
+| --- | --- | --- |
+| High-read config / flags / global lookups | **KV** | Eventual (~60s) |
+| Relational data, real SQL, transactions | **D1** | Strong on primary; replicas eventual |
+| Coordination / counters / locks / WebSockets / per-entity state | **Durable Objects** | Strong, serialized, single-writer |
+| Large blobs / media / egress-heavy | **R2** | Read-after-write (new objects) |
+| Per-POP HTTP/compute caching | **Cache API** | Per-POP, TTL-based |
+| Pool/cache to an external SQL DB | **Hyperdrive** | Inherits origin |
+| Vector/embedding search | **Vectorize** | Index-level |
+
+The classic mistake: reaching for KV because it's simple, then needing read-after-write or
+a counter — that's always a Durable Object. And reaching for D1 for a single big
+multi-tenant DB — that's the 10GB ceiling and single-writer, so shard D1 or use Hyperdrive.
+
+## Failure modes (what breaks and how it shows up)
+
+- **`Exceeded CPU` / `Exceeded Memory` (Error 1102)** — CPU-bound or >128MB hot path.
+  Profile, offload heavy compute, stream large bodies, raise `limits.cpu_ms` if it's
+  legitimately compute-heavy and on paid.
+- **Subrequest limit exceeded** — per-item fan-out inside one Worker. Batch, cache (Cache
+  API), or move fan-out to Queues / a Durable Object.
+- **KV stale reads / lost writes** — using KV where read-after-write or coordination was
+  needed. Move to a Durable Object.
+- **D1 `rows_read` blowup / slow queries** — unindexed scans (bills every row) or hitting
+  the 10GB / single-writer ceiling. Index, shard, or move to Hyperdrive+Postgres.
+- **Durable Object hot-object bottleneck** — all traffic to one DO ID serializes. Shard
+  the keyspace across many IDs.
+- **DB connections exhausted** — Workers opening direct connections to a regional Postgres.
+  Put **Hyperdrive** in front.
+- **Idle WebSocket memory/billing** — DOs pinned by idle sockets. Use the Hibernation API.
+
+## Cost realism (where Cloudflare bills behave differently)
+
+1. **No R2 egress** — the headline saving; egress-heavy workloads are far cheaper than S3.
+   The cost moves to **Class A/B operation counts** — millions of tiny ops add up.
+2. **Workers = requests + CPU time**, not GB-seconds of wall-clock. Idle-waiting on I/O is
+   nearly free; the bill is driven by request count and *compute*. A handler that does
+   little CPU and waits on fetches is cheap even if slow.
+3. **D1 = rows read + rows written**, not queries — unindexed scans are the silent
+   multiplier. Index and watch `rows_read`.
+4. **Durable Objects = active duration (GB-s) + requests** — idle DOs pinned in memory
+   (esp. WebSockets without hibernation) bill continuously. Hibernate.
+5. **KV = per-op + storage** — read-heavy is its sweet spot; write-heavy is both wrong and
+   costly.
+6. **Workers AI = Neurons per inference** — model size and volume drive it; AI Gateway
+   caching cuts repetitive spend.
+7. **Queues = per-operation** on push/pull/retry — fine, but DLQ loops on poison messages
+   waste ops.
+
+Levers: AI Gateway caching, Cache API + good cache keys, batching to stay under subrequest
+limits, indexing D1, DO hibernation, sharding hot DOs, and Smart Placement to cut origin
+round trips.
+
+## Limits to check before betting on them (request increases early)
+
+Workers CPU-time (30s default / 300s max paid, 10ms Free), **subrequests 50 Free / 1000
+paid**, 128MB isolate memory, bundle size (3MB/10MB), **D1 10GB/database** + rows-billing,
+KV value 25MB / ~1 write/s per key / ~60s propagation, R2 operation classes, Durable Object
+single-thread throughput, Queues message ≤128KB + throughput quotas, Workers AI per-model
+rate limits, Vectorize index dimension/count limits. Many are plan-tier (Free vs Paid vs
+Enterprise) — verify the current numbers against Cloudflare docs (they change), and confirm
+the plan tier before designing around a limit.
+
+## Observability
+
+`wrangler tail` for live request logs, **Workers Logs / Logpush** for persisted logs to a
+destination, **Analytics Engine** for high-cardinality custom metrics written from a
+Worker, **Workers Trace Events / Tail Workers** for structured per-invocation traces, and
+the dashboard's per-binding analytics (D1 query metrics, KV/R2 op counts, DO duration,
+Queue depth, AI Gateway logs). Alarm on the things that predict pain: Worker error rate +
+CPU-limit (1102) exceptions, subrequest-limit errors, D1 `rows_read` trends, DO duration +
+queue-up, Queue backlog/DLQ depth, and Workers AI rate-limit (429) responses.