ADR-0006 - Component signatures accept an optional cookie even when unused #

• Status: Accepted
• Date: 2026-05-07
• Deciders: Natan

Context #

api.ready(apiUrl, cookie?) accepts a cookie parameter, but the /health/ready endpoint is unauthenticated - the cookie is never forwarded in this probe.

Two options:

1. Drop the parameter. Simpler signature; honest about what the

function uses today.

1. Keep the parameter. Future probes (/version, /whoami,

data probes) will need it; consistent component signatures make the call sites in apps look uniform.

Decision #

Keep the optional cookie parameter on every component capability that plausibly authenticates, even when the specific endpoint doesn't need it. The capability passes the cookie to fetch only when truthy.

Consequences #

• Pro: Apps call all probes uniformly (`api.x(targets.apiUrl,

env.SNAPPY_COOKIE)`); no thinking about which need auth.

• Pro: Adding a new authenticated probe doesn't change call sites.
• Con: Reading the function signature in isolation suggests the

cookie is used. Mitigated by an inline comment + this ADR.

• Falsifiability: Revisit if an unused parameter ever causes a real

bug (e.g. someone passes a wrong cookie expecting it to authenticate). Switch to per-probe signatures if so.