**Note** from Bead: Acequia Authorization · [canonical source](https://redfish.acequia.io/guerin/.agents/9b2fcc1c-8960-49fb-ab6d-28b331a4e179/2026-06-22/notes/01-acequia-access-caching-policy.md) · session 2026-06-22 · discussion: Talk: Acequia Authorization
**Bead:** `9b2fcc1c` (`acequia-authorization`) · 2026-06-22 · for Stephen **Trigger (verbatim):** *"acequia-access.json should also allow me to set cacheing policy on a URI or full directory."*
## The ask Today `acequia-access.json` is the per-resource **access** sidecar (anonymous/authenticated grants, scope, recursion — note 00's "sidecar for public/anonymous grants"). Extend it so the **same sidecar also declares caching policy** for a URI or a full directory (recursive), the way **`.htaccess` governs *both* access *and* `Cache-Control`/`Expires`** in one file. One constraint surface for a path: *who may flow* **and** *how long the flow is fresh.*
## Why one sidecar (not a separate file) - **`.htaccess` precedent** — Apache already proves that access rules and cache headers (`mod_expires`, `mod_headers`, `Cache-Control`, `Expires`, `ETag`) co-locate in one per-directory file. Stephen's stated trajectory is `acequia-access.json` *growing in expressiveness like `.htaccess`* — caching is the natural next axis. - **Same scope semantics** — access already supports per-URI and recursive-per-directory; caching wants the identical granularity (a policy on a file, or on a subtree). Reuse the scope/recursion machinery rather than inventing a parallel one. - **Co-located governance** — the agent/handler serving a path reads one sidecar to decide *both* admission *and* freshness. Fewer round-trips, one place to reason about a corridor.
## Sketch (illustrative, not ratified) ```jsonc { "access": { "read": "anonymous", "recursive": true }, // existing "cache": { // proposed "maxAge": 3600, // Cache-Control: max-age "sMaxAge": 86400, // shared/CDN/edge cache "staleWhileRevalidate": 600, "policy": "public", // public | private | no-store "vary": ["Accept", "Accept-Bead-Version"], "immutable": false, "recursive": true // applies to the whole subtree } } ``` The handler/animator translates `cache` into response headers (`Cache-Control`, `Expires`, `Vary`, `ETag`) and into Service-Worker / OPFS caching hints on the parciante nodes. Per-URI entries override the directory default (nearest-sidecar-wins, like `.htaccess` cascade).
## Why it matters beyond convenience - **Caching is paving applied to data.** A `cache` policy on a path is exactly the data-side twin of paving-the-cowpath (`43d0d033`): the gate surface that says *who may flow* is the natural place to say *which paths are stable enough to cache/pave*. One sidecar could eventually declare access **+** caching **+** which paths are paved — the unified "roads" constraint surface. - **Local-first coherence** — decentralized-cache-management (`4456cd24`) treats every replica as a peer holding shared state; a per-path freshness policy is what lets those peers decide TTL/eviction without a central origin. `acequia-access.json.cache` is where that policy lives. - **Apoptosis** — `maxAge` / `staleWhileRevalidate` are apoptotic signals for cached data (time-bounded, orderly expiry) rather than necrotic stale data (project_apoptosis-vs-necrosis).
## Open questions 1. **Header authority** — does the nephele/WebDAV authenticator emit the cache headers, or a downstream handler/SW? (Likely both: origin sets `Cache-Control`; SW honors + extends for offline.) 2. **Conflict with content-negotiation** — `Vary` must include the duck-typing axes (`Accept`, `Accept-Bead-Version`) so a cached file-face isn't served to a folder/agent-face request. 3. **Per-token cache** — should cache policy vary by capability (a privileged reader gets fresher/longer cache than anonymous)? Or is cache policy identity-independent (simpler)? 4. **Schema home** — fold `cache` into the existing `acequia-access.json` schema (one file, as Stephen asked), confirmed over a separate `acequia-cache.json`. *Offered as a design note in this bead per Stephen's direct request; not ratified into the nephele sidecar schema yet.*