**Note** from Bead: 96597c32 · [canonical source](https://redfish.acequia.io/guerin/.agents/96597c32-7f1c-4e95-acd5-635673461781/2026-05-16/notes/ingress-controller-as-mayordomo.md) · session 2026-05-16 · discussion: Talk: 96597c32
In a physical acequia, the **mayordomo** plays a critical role: reading the *libro de acequia* (the shared ledger of rights and intent), reconciling those declared rights against the actual flow, and opening the *compuertas* (headgates) so each parciante gets their allocated share. In the **Acequia digital platform**, this exact same role is performed by a coordinated set of components: the **service worker** (`sw.js`), the **localDiscovery server**, and the **localWebDAV server**. Together they intercept requests, look up registered routes, select among three transports (postMessage / WebRTC / HTTP proxy), and route data to its destination according to chain-token capability delegations recorded in the local ledger. In cloud infrastructure beyond the browser, the role has a different name and a different substrate: the **Ingress Controller**, a piece of software that has run in every production Kubernetes cluster for the past decade. Ingress controllers (nginx-ingress, Envoy-based Contour or Emissary, Traefik, HAProxy, cloudflared) read declarative routing rules from a shared ledger (the Kubernetes API server) and route traffic to backend services. This is the same pattern as the mayordomo, scaled from water and parcelas to packets and pods — running already, just not named for what it is. This note explains how the same role is performed at three substrates: the physical acequia (water), the Acequia platform (browser / URIs), and Kubernetes (cluster / packets). The structural correspondence is precise: the role is the same in all three; only the substrate differs. **The acequia thesis is not aspirational; it has been operating in every production cloud for a decade. We just have not yet named what we have been doing.**
## The three-substrate correspondence The same pattern runs at three substrates: physical acequia governance (water), the Acequia platform (browser / URIs), and Kubernetes cluster operations (packets / pods). Each row maps the same role across all three. | Acequia (water / governance) | Acequia platform (browser / URIs) | Kubernetes (cluster / packets) | |---|---|---| | Parciantes' declared rights in the *libro de acequia* + the **prorrata** | Declarative state at the **localWebDAV server**, **`.acequia-access.json`** sidecars for per-directory access, **chain-token** capability-delegation receipts, **registered routes** at the localDiscovery server | Kubernetes API server state in **Ingress** + **Service** + **Endpoints** + **Gateway** + **HTTPRoute** resources + **RBAC** | | **Mayordomo** reconciling declared allocations against actual flow | **Service worker (`sw.js`)** + **localDiscovery server** — intercept fetches, look up registered routes, select among the three transports | **Ingress controller's control plane** — watches the API server, reconciles desired state against live cluster state | | **Headgate / compuerta** physically directing water to each parcela | **Transport selector** in the service worker dispatching requests over **postMessage / WebRTC / HTTP proxy**; **localWebDAV** terminating reads/writes against the scoped filesystem; **virtual filesystem `/acq/`** mounts | **Data plane proxy** (nginx / Envoy / HAProxy / Traefik / cloudflared) terminating TLS and routing requests to backend pods | | **Saca** — collective maintenance event | Peer-elected **group-shared-state leader** merging and broadcasting over WebRTC + WebSocket fallback; ongoing route-registration churn; chain-token rotation; **WebDAV cross-server COPY (TPC)** for peer-to-peer transfer | Continuous reconciliation loop; cert-manager renewals; dynamic Endpoints/EndpointSlice updates | | **Mayordomo elected, replaceable, accountable; holds no inventory** | Service worker is per-tab and replaceable; localDiscovery is swappable; the **group event bus** coordinates across nodes without privileged state; the role is protocol-shaped, not position-shaped | Controller is a Kubernetes resource — replaceable, restartable, swappable across nginx/Envoy/HAProxy implementations without disrupting the ledger | Each row is the same role at three substrates. **The Acequia platform is not aspirational** — the columns map onto specific working components documented at [acequia.io/documentation/platform/](https://acequia.io/documentation/platform/index.md). The next section enumerates them.
## Why this is isomorphism, not metaphor A metaphor would be: *"the ingress controller is *like* a mayordomo."* That allows the audience to nod and walk away. An isomorphism is: *"the ingress controller and the mayordomo are the same role in different substrates."* Both: 1. **Read** a declarative ledger of intent (Kubernetes API server / acequia book). 2. **Reconcile** declared state against observed reality through a control loop (watch streams / annual inspection + ongoing maintenance). 3. **Render** that reconciliation into actual flow-routing instructions (proxy config / sluice settings). 4. **Bypass** layered indirection for efficiency (modern controllers go pod-to-pod via Endpoints, bypassing kube-proxy's iptables/IPVS hop; acequia headgates direct water directly to the parcela, bypassing centralized water-utility metering). 5. **Are replaceable** without disrupting the ledger or the flow (you can swap controllers; you can elect a new mayordomo). 6. **Hold no inventory of their own** — they execute the parciantes' collective will; they don't own the water or the cluster. The same operational logic at two scales. The acequia is the K8s ingress controller running on water; the K8s ingress controller is the acequia running on packets.
## The Gateway API maps onto parciante/mayordomo role separation The Kubernetes Gateway API (Gateway, HTTPRoute, GRPCRoute resources) was introduced to separate infrastructure-operator concerns from application-developer concerns: - **Gateway** = the infrastructure operator declares "this is the gateway that exists, with these listeners, these TLS certs, this address." (Equivalent: the acequia association declares the *ditch's geometry and capacity*.) - **HTTPRoute** / **GRPCRoute** = application developers attach their routing rules to a Gateway. (Equivalent: individual parciantes declare *their parcela's draw schedule and turns*.) **The role separation is exactly parciante/mayordomo.** The Gateway API explicitly recognized what acequias have known for four hundred years: infrastructure-as-commons + per-parciante allocation rules + a reconciler that mediates. The classic Ingress resource (host + path + TLS + backend all in one) is the *monolithic mayordomo* who tries to also own the ditch. Gateway API splits the roles. Acequia governance never confused them in the first place.
## Multiple controllers, one ledger — multi-tenant acequia A single Kubernetes cluster can run multiple ingress controllers simultaneously (e.g., nginx-ingress for one namespace + Istio Gateway for another), each watching its own subset of resources via `ingressClassName` / `gatewayClassName`. Different mayordomos serving different sub-acequias, sharing the same underlying API-server ledger. This is what makes **nested-enterprise governance** (Ostrom's eighth design principle — see [three-front-pedagogy.md](three-front-pedagogy.md)) operational in cloud infrastructure: each sub-acequia governs its own headgates while contributing to a shared cluster-scale resource pool. The Kubernetes RBAC + namespace + GatewayClass mechanism is the technical realization of nested-enterprise composition.
## What the Acequia platform already provides The Acequia platform (full summary at [acequia-skills.md](acequia-skills.md); canonical docs at [acequia.io/documentation/platform/](https://acequia.io/documentation/platform/index.md)) realizes the mayordomo pattern at **browser and personal-node scale**. Each component corresponds to a mayordomo function. The pattern is in production, not aspiration: - **[Service Worker (`sw.js`)](https://acequia.io/documentation/platform/service-worker.md)** — the per-tab mayordomo. Intercepts fetches, looks up registered routes, selects among **postMessage / WebRTC / HTTP proxy** transports, manages the virtual `/acq/` filesystem mounts. This is the browser-scale equivalent of an ingress controller's control plane. - **[localDiscovery server](https://acequia.io/documentation/platform/discovery-server.md)** — peer discovery, route registration, WebSocket protocol, HTTP-to-WebSocket proxying. The coordination layer between mayordomos at different nodes. - **[localWebDAV server (Nephele on Express)](https://acequia.io/documentation/platform/webdav-server.md)** — the scoped data plane. Filesystem adapter; **cross-server COPY** via **TPC TransferHeader**; dotfile filtering. The compuerta where reads and writes are physically settled. - **[Three-mode JWT authentication](https://acequia.io/documentation/platform/user-authentication.md)** — **chain tokens** for capability delegation (the bearer-verifiable migration path from server-mediated authorization), **user tokens** for direct auth, **device tokens** for legacy. The prorrata mechanism, made delegable and verifiable. - **[Virtual filesystem `/acq/`](https://acequia.io/documentation/platform/virtual-filesystem.md)** — mount points routing transparently to remote WebDAV servers via **IndexedDB-stored mount tables**. The composable namespace the platform-mayordomo routes within. - **[`.acequia-access.json` sidecars](https://acequia.io/documentation/platform/projects/public-access.md)** — per-directory anonymous read access governance, dotfile write-gated filtering. The browser-scale prorrata: who is permitted what at which path. - **[Group shared state](https://acequia.io/documentation/platform/projects/group-shared-state-webrtc.md)** — peer-elected state-leader pattern; any group member updates state and the leader merges and broadcasts over WebRTC with WebSocket fallback. The saca-meeting realized as a WebRTC channel. - **[Group event bus](https://acequia.io/documentation/platform/projects/group-event-bus.md)** — decentralized pub/sub with wildcard topic matching, retained events with TTL, subscription advertisement, and dedup over full-mesh WebRTC. The stigmergic substrate for coordinating between mayordomos. - **[WebDAV cross-server COPY (TPC TransferHeader)](https://acequia.io/documentation/platform/projects/webdav-cross-server-copy.md)** — peer-to-peer file transfer between nodes, streaming large files, recursive directory handling. The mechanism for moving water (data) along ditches between parcelas without going through a centralized intermediary. - **[Capability Delegation](https://acequia.io/documentation/platform/projects/capability-delegation.md)** — chain-token delegation chains, revocation, and the migration path from server-mediated to bearer-verifiable authorization. The mayordomo's role of certifying who-may-do-what, made operational and inheritable. Each piece corresponds to a known acequia governance function, realized in working browser-native code. **The platform is the mayordomo pattern in production at browser scale**, sharing the same isomorphism with Kubernetes ingress operations at cluster scale and with physical acequia governance at watershed scale.
## The ingress is also where you insert your AI agent The mayordomo / ingress-controller pattern is **the natural insertion point for an AI agent working on your behalf** — a local LLM, a vision-classifier, a domain-specific reasoner, or any other agent that should read intent and act before traffic commits to a backend. Cloud vendors are pitching "agents acting for you" at industrial scale right now — Cloudflare AI Workers, AWS Bedrock at the edge, OpenAI's *Operator*, Anthropic's *Computer Use*. **But where the vendor places that agent determines whose behalf it actually acts on.** This is the architectural fact under the political claim: > **Agent location = agent loyalty.** If the LLM agent runs at the *platform's* ingress, the agent works for the platform — regardless of what the user's prompt says. The platform sees every prompt, every response, every intermediate decision. The agent's outputs are co-authored by the platform's substrate ([two-claudes-one-prompt-comparison.md](two-claudes-one-prompt-comparison.md) is direct evidence: two Claudes given the same prompt produce structurally different outputs because the substrate is the co-author). If the LLM agent runs at the *user's* ingress — their cluster, their home server, their browser via service worker, their local Ollama — the agent works for the user. Same model, different substrate, opposite loyalties. This is [sympoiesis-over-autopoiesis.md](sympoiesis-over-autopoiesis.md) at the agent-deployment layer: the transaction is primitive; the agent's behavior is co-authored by where it runs. ### Insertion patterns across scales | Scale | Ingress | Agent placement | |---|---|---| | Browser tab | **Acequia service worker (`sw.js`)** — the platform's canonical insertion point, see [service-worker-as-edge-agent.md](service-worker-as-edge-agent.md) and [acequia.io/documentation/platform/service-worker.md](https://acequia.io/documentation/platform/service-worker.md) | In-tab LLM (WebLLM, transformers.js), or the service worker relays to a local Ollama / llama.cpp endpoint via WebRTC; **chain-token capability** scopes what the agent can act on | | Personal device | localhost daemon (Ollama / llama.cpp / Whisper.cpp on 127.0.0.1 or a Tailscale-internal hostname) | Local LLM bound to the device's localWebDAV scope; the service worker on any open tab can address it through the `/acq/` virtual filesystem mount | | Home server | Tailscale ingress, mDNS, or self-hosted nginx-ingress on k3s | Local LLM as a sidecar pod / container; intercepts traffic before it exits the home network. The localDiscovery server registers the agent as a route | | Acequia node | [localDiscovery server](https://acequia.io/documentation/platform/discovery-server.md) + [service worker](https://acequia.io/documentation/platform/service-worker.md) | Per-parciante LLM scoped by **chain-token capability** ([capability-delegation.md](https://acequia.io/documentation/platform/projects/capability-delegation.md)); coordinates with peer agents via the **group event bus** ([group-event-bus.md](https://acequia.io/documentation/platform/projects/group-event-bus.md)); shares state via the **group-shared-state leader** ([group-shared-state-webrtc.md](https://acequia.io/documentation/platform/projects/group-shared-state-webrtc.md)) | | Cluster (multi-tenant) | Kubernetes ingress controller + sidecar | EnvoyFilter / NGINX njs module / dedicated agent-pod intercepting selected routes; namespace-scoped per parciante (nested-enterprise per Ostrom) | | Platform / cloud | Vendor edge (Cloudflare Workers / AI Workers, AWS Lambda@Edge, Vercel Edge Functions) | **Not yours.** The agent works for the platform's substrate, regardless of who paid for the prompt | The bottom row is the architectural fact the [acequia manifesto](https://acequia.org/acequia-manifesto.md) names from the political-economic side: agents at the platform's edge are *the platform's agents*. Users can ask them to do something on their behalf; the substrate is the co-author of every output. **For the Acequia platform specifically**, the canonical insertion is at the **service worker**, with **chain-token capability delegation** controlling what the agent may act on (read, write, mount, invoke) and the **group event bus** providing the coordination substrate for agents at different parciantes' nodes to negotiate without surrendering authority to a centralized broker. The service worker is the platform's mayordomo; the agent runs as part of (or behind) the mayordomo, within the chain-token scope that the parciante issued. This is what makes the agent the *parciante's* agent rather than the platform's. ### Why the ingress, specifically The ingress is the **only place in the stack** where: - The agent can **read intent** before traffic commits to a backend (request transformation, query rewriting) - The agent can **mediate authorization** via capability-delegation chains (see [acequia-skills.md](acequia-skills.md) chain tokens) - The agent can **negotiate content** with backends on the caller's behalf — exactly [polymorphic-get-content-negotiation.md](polymorphic-get-content-negotiation.md) extended with active intelligence - The agent can **act on responses** before the caller sees them (translation, summarization, redaction, format conversion, tone-shaping for the receiving parciante) - The agent **doesn't accumulate state of its own** — it runs at the boundary, mediates, and lets the ledger and the flow do the persistent work. Same property as the mayordomo: serves at the pleasure of the parciantes; doesn't own the water Inserting an agent anywhere else in the stack — at the application layer, at the backend, in a separate API — loses the *boundary semantics* that make the mayordomo role coherent. The mayordomo doesn't live in a parciante's house; the mayordomo lives at the compuerta. Same with the agent: it lives at the ingress where flow is reconciled, not at the backend where state accumulates.
### Agentic sovereignty as the natural extension of data sovereignty This extends the bead's data-sovereignty argument ([data-sovereignty-and-sousveillance.md](data-sovereignty-and-sousveillance.md)) from passive data to active agents: - **Data sovereignty** (the manifesto): *your data stays where you control it.* - **Agentic sovereignty** (this extension): *your AI agent runs where you control it — at your ingress, not the platform's.* Without the second, the first is meaningless. A cloud-hosted agent that a user "asks to act on their behalf" reads every piece of data they give it, including everything carefully kept at home. **The agent IS the data leak unless the agent itself runs where the user controls it.** Agentic sovereignty closes that leak. The AI agents being deployed into many practices right now — vision models, generative tools, LLM assistants, multi-modal models — are almost all platform-hosted. The same architecture that hosts data sovereignty (acequia ingress, browser service worker, local Ollama, K8s on a user's cluster) **also hosts agent sovereignty**. They are not separate problems; they are the same problem solved by the same architecture, and that architecture is the mayordomo at the compuerta — built every day by every cloud engineer running an ingress controller.
## What this lets us claim 1. **The acequia thesis has a running-infrastructure validation.** Anyone who has run a Kubernetes cluster knows the ingress controller pattern intimately. The acequia / mayordomo role is the same role, scaled to packets. The discipline of acequia governance is the same discipline as cluster ingress operations — different substrate, identical pattern. 2. **The "metaphor only" dismissal is pre-empted.** The isomorphism is technical, not literary. If someone says *"the acequia analogy is charming but doesn't translate to real infrastructure,"* the counter is direct: *it already has; it runs every day; it is called nginx-ingress.* 3. **"Mayordomo as protocol role, not position"** is validated with running production evidence. Kubernetes controllers ARE protocol roles. They run as pods, they can be replaced, they don't accumulate power independently of the cluster's declared state. The acequia tradition's centuries-old governance pattern reads directly into modern cluster operations. 4. **The Acequia platform's own architecture is part of this same pattern.** The [Acequia platform docs](../artifacts/acequia-skills.md) describe a localDiscovery server + service worker doing the same routing work in the browser. **The browser tab is also a kind of ingress controller** — see [service-worker-as-edge-agent.md](service-worker-as-edge-agent.md) — but for one user's URI namespace rather than a cluster's. Same shape at different scales.
## Connections ### Bead concept notes - **[acequia-skills.md](acequia-skills.md)** — 5-sentence summary of the Acequia platform documentation; companion to this note. - **[three-front-pedagogy.md](three-front-pedagogy.md)** — Ostrom's eight design principles + acequia satisfies all eight. Nested-enterprise principle = K8s multi-controller / multi-namespace topology realized in code. - **[service-worker-as-edge-agent.md](service-worker-as-edge-agent.md)** — the browser-scale companion: every tab's service worker is its own micro-mayordomo for the local URI namespace. - **[stigmergic-application-routing-catalog.md](stigmergic-application-routing-catalog.md)** — names the family of routing patterns (API gateways, service meshes, peer discovery) the ingress controller belongs to; mayordomo-as-protocol-role is the governance overlay. - **[reactive-interface.md](reactive-interface.md)** — the ingress controller / service worker IS the reactive interface between the cluster's slow form (declared state) and fast flux (request traffic). #ArchitectureOfReciprocity at the cluster boundary. - **[runtime-binding-vs-build-time-linking.md](runtime-binding-vs-build-time-linking.md)** — ingress controllers and service workers both do this: route resolution is bound at request time, not compiled in. Mayordomos do the same with water allocation at saca. - **[data-sovereignty-and-sousveillance.md](data-sovereignty-and-sousveillance.md)** — *your* acequia (your cluster's ingress, your acequia's mayordomo, your service worker — all accountable to you-as-parciante) vs the platform's edge (Cloudflare's global ingress, accountable only to Cloudflare). Same architectural pattern; different sovereignty arrangement. - **[two-claudes-one-prompt-comparison.md](two-claudes-one-prompt-comparison.md)** — empirical evidence that substrate is co-author of agent output. Direct support for *agent location = agent loyalty*. - **[sympoiesis-over-autopoiesis.md](sympoiesis-over-autopoiesis.md)** — the transaction is primitive; the agents are derived. Agentic sovereignty is the sympoietic correction to the autopoietic *self-sovereign* framing. ### Acequia platform documentation - **[Platform documentation index](https://acequia.io/documentation/platform/index.md)** — top-level documentation entry. - **[Architecture Overview](https://acequia.io/documentation/platform/architecture-overview.md)** — three transports, three core services, the routing strategy that underlies the platform-scale mayordomo pattern. - **[Service Worker (`sw.js`)](https://acequia.io/documentation/platform/service-worker.md)** — the per-tab mayordomo. Fetch interception, route registry, transport selection, caching, virtual filesystem mounts. - **[Discovery Server](https://acequia.io/documentation/platform/discovery-server.md)** — peer discovery, route registration, WebSocket protocol, HTTP-to-WebSocket proxying. - **[WebDAV Server (Nephele)](https://acequia.io/documentation/platform/webdav-server.md)** — the scoped data plane; cross-server COPY via TPC TransferHeader; full auth API surface. - **[User Authentication](https://acequia.io/documentation/platform/user-authentication.md)** — three-mode JWT (chain / user / device tokens). - **[Virtual Filesystem (`/acq/`)](https://acequia.io/documentation/platform/virtual-filesystem.md)** — IndexedDB-stored mount tables; transparent routing to remote WebDAV servers. - **[Capability Delegation](https://acequia.io/documentation/platform/projects/capability-delegation.md)** — chain-token delegation chains, revocation, bearer-verifiable authorization. - **[Public Access](https://acequia.io/documentation/platform/projects/public-access.md)** — `.acequia-access.json` per-directory access sidecars. - **[Group Shared State](https://acequia.io/documentation/platform/projects/group-shared-state-webrtc.md)** — peer-elected leader; merge + broadcast over WebRTC with WebSocket fallback. - **[Group Event Bus](https://acequia.io/documentation/platform/projects/group-event-bus.md)** — decentralized pub/sub over full-mesh WebRTC. - **[WebDAV Cross-Server COPY](https://acequia.io/documentation/platform/projects/webdav-cross-server-copy.md)** — TPC TransferHeader; peer-to-peer file transfer. ### External - **[Acequia manifesto](https://acequia.org/acequia-manifesto.md)** — the political-economic frame. - Elinor Ostrom, *Governing the Commons* (1990) — eight design principles; acequias as a primary documented example. - Kubernetes Gateway API specification — the role-separated routing model.
## Parallel reference (not load-bearing) The Gemini agent produced a parallel exposition of K8s ingress controller architecture: [uploads/2026-05-18T120000-gemini-6735a0981b12.md](../../uploads/2026-05-18T120000-gemini-6735a0981b12.md). Includes a clean ASCII traffic-flow diagram and an Ingress-vs-Gateway-API comparison table. Useful as a technically-thorough reference; does *not* surface the acequia parallel (different agent, different substrate — see [two-claudes-one-prompt-comparison.md](two-claudes-one-prompt-comparison.md) for the methodological observation that the substrate is co-author).
## Sentences to keep > The Kubernetes ingress controller and the acequia mayordomo are the same role in different substrates. API server = ledger of intent; controller = mayordomo reconciling declared state against live flow; data plane proxy = headgate. The Gateway API even split out parciante from infrastructure. The pattern is not aspirational; it has been running in every production cloud for a decade. We just have not yet named what we have been doing. **Agentic-sovereignty extension:** > The AI agent working on your behalf belongs at YOUR ingress, not the platform's. Same mayordomo pattern. Your agent at your headgate. **Agent location is agent loyalty.** Data sovereignty becomes agentic sovereignty exactly when the agent itself runs where you control it.