DECISIONS.md

# Overslash — Decisions

Settled architectural decisions. Don't re-litigate without new information.

---

## D1: Standalone service, not a library

**Date**: 2026-03
**Decision**: Overslash is a standalone REST API service, not embedded in Overfolder's agent-runner.
**Rationale**: Auth, secrets, approvals, and action execution are general-purpose. Any agent platform should be able to use Overslash. Decoupling also simplifies agent-runner.

## D2: Replace Nango with native OAuth

**Date**: 2026-03
**Decision**: Overslash owns OAuth flows natively instead of using Nango.
**Rationale**: Nango adds a dependency and limits control over the token lifecycle. Overslash needs tight integration between OAuth tokens, permission rules, and approval workflows. See `docs/design/nango-integration.md` for the evaluation that led to this decision.

## D3: Rust + Axum (same stack as Overfolder)

**Date**: 2026-03
**Decision**: Use Rust/Axum, matching the Overfolder stack.
**Rationale**: Shared expertise, proven stack, consistent tooling. AES-256-GCM for secrets at rest.

## D4: Valkey over Redis

**Date**: 2026-03
**Decision**: Use Valkey (not Redis) for caching and pub/sub.
**Rationale**: Valkey is the open-source fork of Redis, maintained by the Linux Foundation. License-compatible, drop-in replacement, actively developed. No reason to use Redis's restrictive SSPL license.

## D5: Cloud SQL Auth Proxy by default (no VPC)

**Date**: 2026-03
**Decision**: Default to Cloud SQL Auth Proxy mode instead of VPC private networking.
**Rationale**: VPC connector costs ~$7/month even idle. Auth Proxy is free, secure (IAM-authenticated), and sufficient for pre-GA. VPC mode is available via `use_private_vpc = true` for production hardening later.

## D6: Podman-first container tooling

**Date**: 2026-03
**Decision**: Prefer Podman / podman-compose over Docker where available.
**Rationale**: Rootless by default, daemonless, OCI-compliant. Docker is supported as fallback. Makefile auto-detects `podman-compose` first.

## D7: Identity hierarchy with live inheritance

**Date**: 2026-03
**Decision**: `inherit_permissions` is a live pointer, not a copy. Child dynamically has parent's current + future rules.
**Rationale**: Static copies create drift. Live pointers mean granting a user a new permission automatically flows to their agents. See SPEC.md for full design.

## D8: Two-tier rate limiting (User bucket + identity caps)

**Date**: 2026-04
**Decision**: Rate limits use two counters per request: a User-level bucket (shared by all agents under that user) and optional per-identity caps. Not per-agent buckets alone.
**Rationale**: Per-agent-only limits are easily circumvented by spawning sub-agents. The User bucket ensures a hard ceiling regardless of agent topology. Identity caps are a convenience for isolating misconfigured agents from consuming the entire User budget. See SPEC.md §13.

## D9: Merge queue on `dev`, merge-commits on `master`

**Date**: 2026-04
**Decision**: PRs target `dev` and merge through GitHub's merge queue (squash, ALLGREEN, required check `ci-ok`, strict-up-to-date off — the queue handles rebasing). `dev` flows to `master` via **merge commits only** (`master` ruleset disallows squash/rebase) so feature history is preserved on `master`. Repo was made public to unlock merge queue without an Enterprise upgrade. The Stop hook arms `gh pr merge --auto --squash` once its three gates pass, but **only when the PR's base branch is `dev`** — never on PRs targeting `master`.
**Rationale**: Keeping branches up-to-date with base was a recurring source of agent churn. The merge queue serializes PRs and rebases them in-place, eliminating that responsibility. Squash on `dev` keeps feature PRs as single commits; merge-commits on `master` retain the full feature history at release-cut time. See `.claude/hooks/pr-mergeability-gate.sh` and rulesets `dev` (id 14770759) / `master` (id 14707284).

## D10: MCP over Streamable HTTP + OAuth 2.1

**Date**: 2026-04
**Decision**: MCP clients connect via `POST /mcp` on the API, gated by `Authorization: Bearer`. Two single-credential modes: user JWT (aud=mcp, minted via `/oauth/authorize` → `/oauth/token` on the same Axum process) or static `osk_…` agent API key. The dual-credential model and stdio-only transport are retired. `overslash mcp` becomes a thin stdio↔HTTP compat shim for editors whose MCP transport is stdio-only; `overslash mcp login` runs the standard OAuth Authorization Code + PKCE flow and writes `~/.config/overslash/mcp.json`.
**Rationale**: OAuth 2.1 is the standard auth flow in the MCP spec, and Streamable HTTP is the reference transport for remote MCP. Hosting the Authorization Server (`/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`, `/oauth/register`, `/oauth/authorize`, `/oauth/token`, `/oauth/revoke`) next to the API means DCR, consent, refresh, and revocation share infra and reuse the existing IdP login flow. Editors speaking stdio get the compat shim so Overslash doesn't break their setup. Implementation landed in PR #121 (single binary) and PR #123 (HTTP transport + AS). Full design at `docs/design/mcp-oauth-transport.md`.

## D11: Semantic search uses local pgvector + fastembed, not an API

**Date**: 2026-04
**Decision**: `GET /v1/search` (§10) ranks candidates with a hybrid of keyword + Jaro-Winkler fuzzy and pgvector cosine similarity, where the embeddings come from **locally hosted** `BAAI/bge-small-en-v1.5` (384-dim) via the `fastembed` crate. Dev, CI, and the shipped compose images run `pgvector/pgvector:pg16`; vanilla Postgres is supported — both the extension migration and the table migration are wrapped in `DO $$` blocks that probe `pg_available_extensions` and no-op cleanly. A boot-time preflight (`SELECT … FROM pg_extension`) plus the env kill-switch `OVERSLASH_EMBEDDINGS=off` force-disable embeddings at runtime; search then falls back to keyword + fuzzy transparently.
**Rationale**: The service/action catalog is tiny (~9 global templates × ~20 actions plus DB-tier templates) — an external embedding API would add a per-query cost, a new secret, and network latency for a corpus that fits trivially in CPU-embedded memory. The local model is a one-time ~130 MB download cached under `OVERSLASH_EMBED_CACHE_DIR`; ONNX runtime adds ~40 MB to the binary, which is acceptable for a single-binary server distribution (the `embeddings` Cargo feature lets library consumers opt out). Keyword + fuzzy alone handles exact matches and typos well but misses paraphrased intent — the embedding signal covers that gap, and the hybrid weighting (0.4 keyword + 0.6 embedding) keeps exact service / action names dominant when they match literally. The pgvector no-op path means a self-hosted deploy on vanilla Postgres still boots and serves search, just without the embedding signal.

## D12: Multi-org trust model — each IdP is its own trust domain

**Date**: 2026-04 (amended 2026-05)
**Decision**: Overslash treats each IdP as its own trust domain. An IdP can only admit members into resources it controls: Overslash-level IdPs admit into personal orgs and into corp orgs the user themselves created (the creator becomes a regular admin of the new org); per-org IdPs admit into that org only. Users are keyed at auth time by `(provider, subject)`, never by email. There is no cross-IdP account linking — a human who uses Google for their personal Overslash account and Okta for Acme simply has two distinct `users` rows.
**Rationale**: If email alone could attach a login to an existing membership, a user who registers a Google account claiming `amartcan@acme.org` would inherit whatever Acme provisioned for its real employee via Okta. By restricting each IdP to its own trust domain, an external IdP (Google) cannot vouch its way into resources controlled by an internal one (Acme's Okta).

**2026-05 amendment — opt-in invite-gated admission**: a corp org may opt in (via `orgs.allow_overslash_managed_signin`, default `true` for new orgs) to invite-gated membership. Two things change when the flag is on:

1. Authentication via Overslash's shared OAuth apps (`GOOGLE_AUTH_*`, `GITHUB_AUTH_*`, future env-var providers) becomes available — until now D12 forbade env-var creds on corp subdomains.
2. Sign-in is decoupled from membership: the IdP proves who you are, and a second gate — including authentications through a dedicated `org_idp_configs` row — decides who belongs. The per-provider `allowed_email_domains` whitelist is bypassed when the flag is on.

**2026-07 amendment (migration 092) — invite vs domain is itself a toggle**: the second gate is configurable via `orgs.require_invite_admission` (default `true`, preserving the 2026-05 behavior above):

- `require_invite_admission = true` — invite-only: every new member must match a pending `org_invites(email, role)` entry.
- `require_invite_admission = false` — domain admission: any verified email whose domain is on the org-wide `orgs.managed_signin_allowed_domains` list self-provisions as `member`. An empty allowlist is treated as misconfigured (reject `domain_admission_not_configured`), never as open admission.

The trust boundary is either "the admin's curated invite list" or "the admin's curated domain allowlist" — both admin-controlled. Domain admission trusts the verified-email domain (split on `@`, case-insensitive); it does **not** verify Google's `hd`/Workspace claim (see TECH_DEBT.md). The email-spoofing concern the original D12 raised does not apply: there is no second-source IdP to phish; the managed IdP authenticates the email holder and the admin chose which emails/domains matter. Existing orgs keep both flags at their safe defaults (`allow_overslash_managed_signin` per provisioning, `require_invite_admission = true`) until an admin opts in. Full design at `docs/design/multi_org_auth.md`.

**2026-08 amendment — one resolver for provider availability**: the "which IdPs can this org sign in with" rule (enabled `org_idp_configs` rows ∪ managed providers when the flag is on, dedicated wins on collision) was open-coded in every handler that needed it, and they drifted. `/oauth/authorize` never learned the 2026-05 amendment at all and answered 503 `login_required` for managed-signin-only orgs; `/auth/providers` and credential resolution disagreed about disabled rows. `crates/overslash-api/src/services/org_signin.rs` now owns the rule, and `/oauth/authorize`, `/auth/providers`, `/v1/org-idp-configs` and `resolve_auth_credentials` all read it from there. Admission (invites / domain allowlist) stays separate in `routes::auth::provisioning` — availability is not membership. Relatedly, anything that *starts* a login on a corp subdomain must redirect to the org's **app** host: the `oss_auth_*` cookies carry `Domain=SESSION_COOKIE_DOMAIN` (`.app.<apex>`), so a login kicked off on `<slug>.api.<apex>` — the host the AS metadata advertises — has its cookies rejected by the browser.

## D13: Auto-call-on-approve is a per-Identity setting (default on)

**Date**: 2026-05
**Decision**: `auto_call_on_approve` lives on the agent identity itself (`identities.auto_call_on_approve`, default `true`) and applies uniformly to MCP, REST, and white-label agents — there is no separate per-MCP-binding column anymore. Org admins can flip `orgs.default_deferred_execution` to seed *new* agents with auto-call OFF (existing agents keep their value). When auto-call is ON, the `approval.executed` webhook payload includes the full execution `result` (only when `triggered_by="auto"` and the call succeeded); manual `/call` paths omit it because the caller already received the result inline. The toggle also governs cascade-resolved approvals (`resolved_by='cascade'`): each cascaded approval is auto-called per its *own* requesting identity's setting; because cascade executions are created with `remember=false`, a cascade-triggered replay never writes rules or re-cascades.
**Rationale**: Pre-migration the toggle was on `mcp_client_agent_bindings`, so REST API agents and white-label embeddings (Overfolder, etc.) silently fell through to manual-only `POST /v1/approvals/{id}/call`. White-label platforms are explicitly first-class consumers per SPEC.md §1, and the bound-to-MCP gate forced every white-label integration to do an extra round-trip on every approval. Moving the toggle to the identity makes the policy uniform across surfaces; the org-level default lets a tenant flip the policy without touching individual agents; and including the result in the webhook lets a white-label UI render the outcome from a single delivery instead of a follow-up `GET /v1/approvals/{id}/execution`. Manual-call paths are unchanged because the caller already has the response.

## D14: `connection: <uuid>` action calls removed; free-form authed calls go through Service + HTTP verb

**Date**: 2026-05
**Decision**: `POST /v1/actions/call` no longer accepts a top-level `connection: <uuid>` field. Callers that previously used it (raw URL + stored OAuth connection) must instead use SPEC §8 "Service + HTTP verb" — naming a service instance plus `method` + `path` (or `url`). The instance binding provides auth; the template's `hosts[]` bounds where the bearer can land. The `CallRequest` parser uses `deny_unknown_fields`, so stale callers get a parse-time 400 naming the removed field.
**Rationale**: The connection-based shape was an implementation deviation from SPEC §8 and carried a host-binding gap — `host(req.url)` was never validated against the connection's `provider_key`, so an agent with a managed OAuth connection could direct the bearer at any URL and exfiltrate the token. Implementing SPEC §8 "Service + HTTP verb" subsumes the legitimate use case (free-form authed calls) while inheriting the host bound from `svc.hosts`. Removing the deviated shape is a straight code-and-surface reduction; nothing in-tree depended on it that wasn't trivially rewritable to the verb shape.

## D15: Mode A is the `http` service instance, not a separate code path

**Date**: 2026-05
**Decision**: Mode A (raw HTTP) is implemented as the **synthetic `http` service**: a global template (`hosts: []`, `auth: []`, `runtime: Http`) shipped in the registry and a system-managed org-level service instance (`is_system = true`, no owner, no credentials) created for every org at bootstrap. Callers send `service: "http"` with `method` + `url` (the no-`service` legacy shape is rejected with a 400 carrying a migration hint). The `groups.allow_raw_http` boolean was dropped in migration 063 — group access to raw HTTP flows through the standard `group_grants` mechanism on the `http` instance, with the same access-level → verb-risk mapping as any other service. Permission keys derive identically to the legacy form (`http:{METHOD}:{host}{path}`) so existing rules continue to match.
**Rationale**: Pre-migration, raw HTTP carried two parallel code paths (a separate Mode A branch in `actions.rs::resolve_request` and `resolve_action_metadata`, a `service_name == "http"` special case in `check_group_ceiling`, and a dedicated `PermissionKey::from_http` builder) plus a special-purpose `allow_raw_http` boolean. Treating `http` as just another service collapses all four into the standard verb-shape path: `actions.rs` loses ~60 lines of branch duplication, `permissions.rs` loses the http special case + `from_http`, the column is gone, the dashboard's standalone "Allow raw HTTP" toggle disappears (raw HTTP is granted via the same UI as `github` or `slack`), and access-level granularity gains read/write/admin instead of a binary flag. Owner experience is unchanged — Everyone+Admins keep an admin grant on the `http` instance from the migration backfill, mirroring the prior `allow_raw_http = true` default. Org admins can now downgrade or revoke raw HTTP per-group like any other service.

## D16: Reactive auth flows carry the caller's `return_url`

**Date**: 2026-05
**Decision**: `POST /v1/actions/call` accepts an optional `return_url` body field. When a call reactively mints an OAuth flow — `reauth_required` (refresh-token failed / no refresh token), `missing_scopes` (incremental scope upgrade), or `needs_authentication` (no connection yet) — that `return_url` is stamped onto the minted flow row, so the `/v1/oauth/callback` handler 303-redirects the user back to the partner once consent completes, identical to the first-connect path. The hint is format-validated once at the request boundary (`parse_return_url` → 400 on malformed input); the host is re-checked against `OVERSLASH_CONNECTION_RETURN_URL_HOSTS` at callback time, and an off-list host silently falls back to the historical JSON response.
**Rationale**: First-time connects already pass `connect_return_url` → flow row → callback 303. But reactive reauth/upgrade flows are minted server-side during a *failed* action call, where the partner had no first-class place to supply a return URL, so they hardcoded `return_url: None` and the user landed on raw callback JSON. A body-field hint on the action call (mirroring `return_url` on the connect endpoint) closes the gap with no new transport surface and reuses the existing boundary validator and callback-side allow-list gate unchanged. The org-config alternative (a per-org configured callback URL) was rejected as heavier schema for no extra safety — the allow-list already bounds where the callback will redirect.

## D17: Builtin GitHub service uses GitHub App user-to-server OAuth

**Date**: 2026-06
**Decision**: The shipped `services/github.yaml` template targets **GitHub App user-to-server tokens**: the OAuth flow declares no scopes (GitHub Apps ignore the `scope` parameter — access is the intersection of the app's fine-grained permissions and its installations), and the org's configured GitHub client credentials (`OAUTH_GITHUB_CLIENT_ID`/`SECRET` or BYOC) must belong to a GitHub App. The previous classic-OAuth-App template is retained verbatim as `services/github_legacy_oauth.yaml` (key `github_legacy_oauth`, title "GitHub (Legacy OAuth)") for orgs whose configured client is still an OAuth App; it is pre-annotated `x-overslash-hidden: true` in its info block so it drops out of the catalog once hidden-template support lands. Both templates keep `provider: github` — same provider row, credentials cascade, and connections pool, so existing connections and permission rules (`github:<action>:{repo}`) work unchanged. Installation (server-to-server) tokens are out of scope — they need RS256 JWT signing with an app private key, which doesn't exist in the gateway yet.
**Rationale**: GitHub recommends GitHub Apps over OAuth Apps: fine-grained per-repo permissions instead of broad `repo` scope, and short-lived (~8h) tokens with refresh. The user-to-server flow is endpoint-compatible with the OAuth App flow (same authorize/token URLs, same code-exchange and refresh grants), so the migration is template-only: the existing refresh machinery handles expiring tokens (`oauth_providers.supports_refresh` defaults true), the scope gate passes because github actions declare no `required_scopes`, and the `default_identity_scopes` sent on the authorize URL are harmlessly ignored by GitHub Apps. Keeping the legacy template as a separate hidden key (instead of mutating `github` in place per-org) gives OAuth-App orgs a zero-breakage path while new setups land on the recommended model.

## D18: Audit response-body capture is org-opt-in, inline, and truncated; transport failures always audit

**Date**: 2026-06
**Decision**: Upstream response bodies can be persisted on `action.executed` audit rows under `detail.response` (`{body, truncated, content_type}`), governed by a new org setting `orgs.audit_response_body_mode` (`off` default / `errors_only` / `all`, managed via `GET/PATCH /v1/orgs/{id}/audit-settings`). "Error" reuses the normalized `detail.is_error` semantics (upstream HTTP ≥ 400, MCP in-band error). Bodies are stored inline in the existing `detail` JSONB as strings — truncated at a char boundary to `AUDIT_RESPONSE_BODY_MAX_BYTES` (64 KB default) and NUL-sanitized (Postgres rejects ` ` in jsonb and `log_audit` swallows errors, so an unsanitized body would silently drop the row). Streamed executions record `response: {skipped: "streamed"}` instead — their bodies never pass through a buffer. Platform-runtime calls are excluded (in-process, no upstream). Independently of the setting, transport-level failures (DNS/connect/timeout, response-too-large, MCP transport/JSON-RPC errors) now always write an `action.executed` row with `is_error: true` and a fixed-string `detail.error` `{kind, message}` — never the raw reqwest/MCP error text, whose Display can carry the resolved URL with injected secrets.
**Rationale**: The response body is the most useful artifact when debugging a failed agent action, but storing every body is a privacy and storage liability — so capture is admin-gated, defaults off, and offers an errors-only middle mode (error payloads are small and the debugging gold; success bodies are the volume). Inline JSONB avoids a migration and a lazy-fetch endpoint at 64 KB scale; a string (not parsed JSON) keeps one predictable shape since truncated bodies rarely parse. The transport-failure rows fix an audit blind spot: before this, a DNS failure or timeout was visible in metrics (#368) but wrote no audit row at all — `is_error` only covered responses that arrived.

## D19: Releases are cut by release-please; binaries report the release tag

**Date**: 2026-06
**Decision**: Release tagging and changelog generation are automated with **release-please** (manifest mode, single root component, `release-type: simple`). After a `dev` → `master` promotion PR merges, `release-please.yml` opens a `chore(release): vX.Y.Z` PR against `master` computed from the conventional commits since the last release tag (`bump-minor-pre-major: true` so a `feat!:` bumps minor, not 1.0.0); merging it creates the tag + GitHub release, and the tag push triggers the existing `release.yml` binary build unchanged. The workflow authenticates with the `RELEASE_PLEASE_TOKEN` fine-grained PAT (contents + pull-requests write) because `GITHUB_TOKEN`-created PRs/tags never trigger other workflows. Crate versions in `Cargo.toml` stay untouched (bumping them would invalidate `Cargo.lock` and break the `--locked` release build); instead the release workflow injects `OVERSLASH_VERSION` at compile time and the CLI reports it via `common::version()` (`option_env!` with `CARGO_PKG_VERSION` fallback for local builds). Two follow-ons (2026-07): the release commit is merged **back into `dev`** automatically by `sync-dev.yml` on the tag push — a merge, never a rebase, since `dev` forbids non-fast-forward pushes, and never a sync PR, since `dev`'s squash-only rule would leave the release commit outside `dev`'s history and the drift would recur; and non-release builds no longer report the frozen `0.1.0` — `overslash-core`'s `build.rs` emits `OVERSLASH_VERSION` from `.release-please-manifest.json` with a `-dev` suffix (`0.5.0-dev`) when the release workflow did not set it, which is what makes the sync-back load-bearing rather than tidiness.
**Rationale**: v0.1.0–v0.2.0 were manual tag pushes: easy to forget, no changelog, and the binaries reported the stale crate version (`0.1.0`) because nothing ever bumped `Cargo.toml`. release-please leans on the conventional-commit discipline `dev`'s squash-merge policy already enforces, so the version bump and changelog come for free. The compile-time version override was chosen over having release-please bump the ten workspace `Cargo.toml`s because the crates are internal and unpublished (their versions are cosmetic) while a `Cargo.toml`-only bump without a regenerated `Cargo.lock` hard-fails `cargo build --locked` — wiring lockfile regeneration into the release PR would add a custom step for zero benefit. Runbook: `docs/runbooks/release.md`.

## D20: White-label OAuth is a token vault, not overslash-orchestrated

**Date**: 2026-06
**Update**: The *integration-managed* refresh mode and the `connection.refresh_required` webhook described below are **superseded by D21** — `byoc_credential_id` is now required on import (no null/no-client mode) and white-label auth-recovery is driven by the per-org `headless` flag instead. The orchestrated-vs-vault and "overslash issues no `redirect_uri`" parts stand.
**Decision**: White-label partners (e.g., Overfolder) that own their OAuth no longer route the dance through overslash. They run authorize + code-exchange themselves and `POST /v1/connections/import` the resulting `{access_token, refresh_token?, expires_at?, scopes?, account_email?, byoc_credential_id?}`; overslash stores the connection (identical row to an orchestrated callback), refreshes it, and injects it at execution — issuing no `redirect_uri`. Refresh is per-connection and fixed at import: *self-refresh* when the import references a BYOC client via `byoc_credential_id` (overslash runs the `grant_type=refresh_token` call autonomously, hard-pinned to that client — no `redirect_uri` needed), or *integration-managed* (`connections.integration_managed = true`) when `byoc_credential_id` is null, where overslash injects until expiry then surfaces `reauth_required` — marked integration-managed with **no overslash reconnect link** — plus a `connection.refresh_required` webhook, for the partner to refresh and re-import. Overslash refreshes **only** when it holds the connection's client: an imported connection with a null `byoc_credential_id` does **not** fall back to the env/org `OAUTH_*_CLIENT` cascade (a refresh token is valid only against the issuing client). Secretless import (no client) is explicitly supported — it also covers opaque bearer tokens/PATs — but BYOC self-refresh is the recommended path for unattended agent execution. This reverts the per-request `redirect_uri` override + `oauth_callback_allowed_hosts` allow-list (#388/#392) and the per-org `oauth_redirect_url` + `use_org_redirect` switch (#398), and removes `POST /v1/oauth/exchange`, the `include_raw`/raw-authorize-URL surface, and `oauth_connection_flows.redirect_uri` (migration 079). Orchestrated OAuth (default `/v1/oauth/callback`) stays for normal orgs and the dashboard's own connect UI. Full design: [docs/design/white-label-token-vault.md](docs/design/white-label-token-vault.md).
**Rationale**: The `redirect_uri` belongs to *a provider's OAuth client*, and clients are per-provider — so any model that keeps overslash issuing the redirect inherits a per-provider configuration problem (a single per-org URL forces all providers to share one callback; a per-request override needs an allow-list and per-call URL plumbing). A partner that already owns its OAuth gains nothing from overslash re-doing the dance. Making overslash a pure token vault deletes the entire redirect/exchange/allow-list surface, is inherently multi-provider, and matches overslash's identity (secret management + authenticated execution); the permission-chain and approval value-add still apply at execution time regardless of where the token came from. The key enabler is that the refresh-token grant needs only client_id + client_secret + refresh_token — never a `redirect_uri` — so overslash can keep tokens fresh without ever touching the authorization-code redirect.

## D21: Headless org capability replaces the `integration_managed` connection flag

**Date**: 2026-06
**Decision**: The `connections.integration_managed` flag (D20) is **removed** (migration `085_drop_connection_integration_managed`) because it conflated two unrelated axes: *who refreshes* a connection and *who runs the user-facing auth flow*. They are split cleanly: (a) **refreshability is structural** — a connection with a pinned `byoc_credential_id` self-refreshes via that client, one without refreshes via the orchestrated org/env cascade; no stored boolean. (b) **flow-ownership is a per-org capability**, `orgs.headless` (migration `084_orgs_headless`, admin/provisioning-only via `GET`/`PATCH /v1/orgs/{id}/headless`, no dashboard toggle). `POST /v1/connections/import` now **requires** `byoc_credential_id` (null → 400), so the no-client "integration-managed" mode (inject-until-expiry, never refresh) is gone and every imported connection self-refreshes. For a **headless** org, the three auth-recovery envelopes (`reauth_required`, `needs_authentication`, `missing_scopes`) are **URL-less**: they omit `auth_url`/`short` (and `upgrade_url` for `missing_scopes`), carry a `headless: true` discriminator (present only on these URL-less variants) plus `provider`/`required_scopes`/`account_email`, and mint **no** `oauth_connection_flows` row; the integration re-runs its own dance and re-imports (idempotent on identity+provider+account_email). `upgrade_scopes` is rejected for headless orgs. The `connection.refresh_required` webhook is **dropped** — the signal is inline on the failing call. The gated `/connect-authorize` flow is unchanged for non-headless dashboard customers.
**Rationale**: A white-label org's end users have no Overslash dashboard session, so handing them a gated `/connect-authorize` link is a white-label violation — yet `integration_managed` keyed that behavior off *how the connection refreshes*, which is orthogonal and (post-D20) the wrong question. Nobody was relying on the no-client import mode yet, so requiring BYOC removes a weak path (a connection that lived only as long as the imported token) and lets the single remaining special case — URL suppression — be driven by the org capability that actually models the white-label boundary. A per-org flag is the pragmatic stand-in for a full `flow_owner` axis without a connection-level migration. Breaking for the one white-label consumer (Overfolder), which already pins a BYOC on import and consumes the envelope — coordinated cross-repo change. Full design: [docs/design/white-label-token-vault.md](docs/design/white-label-token-vault.md).

## D22: OAuth connections resolve at the owner identity (service instances stay per-agent)

**Date**: 2026-06
**Decision**: Connections are **not user-scoped** — `connections.identity_id` can point at a user *or* an agent, and storage/ownership semantics are unchanged. What changes is the action-execution **auth resolver**: it now looks connections up at the **owner** identity instead of the calling identity. `resolve_service_auth`, `check_required_scopes`, and the auto-resolve fall-through of `resolve_instance_auth` derive the owner via `group_ceiling::ceiling_user_id_from_identity` (user→self, agent/sub_agent→`owner_id`) and build their `UserScope` from it before calling `find_my_connection_by_provider` (note: `UserScope` is really an identity scope — its `user_id` field holds any `identity_id`, so this is a read-path change only). The three reactive auth-recovery mints (`reauth_required`, `needs_authentication`, `missing_scopes`) and the OAuth client-credential resolution are keyed on the same owner identity, so a freshly minted connection lands on the owner and one reauth heals every agent under it. **Service-instance binding and permission/group-ceiling checks remain on the calling agent identity** (group ceiling unchanged). Explicit instance→connection bindings still resolve org-scoped via `scope.get_connection` and are untouched. *(Superseded by D120: a pinned connection must be the instance owner's own.)* This aligns the connection *read* path with the *write* path, where `on_behalf_of` import already binds to the owner. **Owner-only — no caller fallback**: a legacy agent-bound connection surfaces one `needs_authentication`, after which the reconnect lands on the owner; the sibling import/migration re-homes the rest.

**Rationale**: The resolver previously built `UserScope::new(org_id, calling_identity_id)`, so a child agent never saw the owner user's connection. With Overfolder binding connections to the user identity (connect/reauth flow + `on_behalf_of` import), an agent holding its own stale connection got `reauth_required` for a row the user's reauth flow could never heal — an infinite reauth loop (dev trace d57fe333: agent connection `f46cabbe` broken, user connection `85844f1a` healthy). Resolving at the owner makes "one credential per (user, provider)" the effective model at execution time without changing connection storage, while keeping the per-agent permission ceiling intact. Owner-only (vs. caller-first or nearest-ancestor) is required precisely because the bug case has a *broken* connection closer in the chain than the *healthy* one — any strategy that prefers the nearest connection would pick the broken agent row.

## D23: OAuth connections bind to the owner identity on import/connect

**Date**: 2026-06
**Decision**: The connection *write* path now matches the D22 read path: `kernel_create_connection` and `kernel_import_connection` bind the resulting connection to the **owner** identity (ceiling root via `group_ceiling::resolve_ceiling_user_id`, user→self / agent→`owner_id`) by default — instead of falling back to the *calling* identity when `on_behalf_of` is omitted. `on_behalf_of`, when supplied, is still validated (`validate_on_behalf_of` enforces target == caller's owner) but the binding is the owner either way; audit attribution stays on the caller (`kernel_create_connection_for_identity` takes `caller_identity_id` separately; import logs `identity_id: Some(caller_identity_id)`). Migration `086_connection_owner_identity` re-homes existing agent/sub_agent-bound rows: owner-wins delete for a same-`(provider, account_email)` owner row, most-recent-wins collapse among remaining agent rows, re-point to the owner, then re-establish one `is_default` per `(identity, provider)` (the partial unique index forces demote-before-re-point). Down is a documented no-op (the original agent identity isn't retained).

**Rationale**: Without this, every implicit (no-`on_behalf_of`) agent connect/import accreted a connection on the agent that the D22 read path could never see — the exact source of the dev mismatch (the "main" agent `52d10791` held 4 leftover google connections while the real one lived on user A M `1d6a5835`). Binding writes to the owner makes storage agree with resolution so connections stop accreting on agents, and the migration heals the legacy rows that D22 noted it would "surface one `needs_authentication`" for. Reusing `resolve_ceiling_user_id`/`validate_on_behalf_of` keeps the change to a few lines per kernel with no new identity-walking logic.

## D24: Overslash wraps Slack as a decorated MCP service on the `oauth` auth kind

**Date**: 2026-07
**Status**: Superseded by "Slack goes through its Web API, not its MCP server" (below). The `oauth` MCP auth kind and the `template_oauth_provider` / `McpDetail` fixes stand, and HubSpot still uses them.
**Decision**: `services/slack.yaml` wraps Slack's official first-party MCP server (`https://mcp.slack.com/mcp`, GA Feb 2026) as an `x-overslash-runtime: mcp` template on the `auth.kind: oauth` provider-connection mechanism shipped for MCP servers in #418 (alongside HubSpot). Overslash is the MCP *client*: it exposes Slack's tools through `/v1/actions/call`, decorates **only** the tools that benefit from gateway features (the write `send_message` gets `disclose` + `scope_param: channel`; the ID-scoped reads `read_channel_history`/`get_user` get `scope_param`; plain reads stay bare), and resolves the caller's owner Slack connection (D22) into the outbound bearer. Two gaps in the #418 mechanism are closed so both Slack and HubSpot behave correctly: `platform_services::template_oauth_provider` now also returns an MCP `auth.kind: oauth` provider (so auto-connect orchestration, pinned-connection validation in `kernel_create_service`, and credentials-status surfacing treat MCP-oauth like HTTP OAuth), and `McpDetail` exposes the `provider` so the dashboard can render a "connect <provider>" affordance for oauth MCP services (service detail + create pages reuse the existing OAuth connect surface).

**Rationale**: Slack's MCP server is broader and LLM-native (search, canvases, drafts, reactions, files) and is maintained by Slack — wrapping it tracks Slack's capabilities for free while Overslash still owns permissions/approvals/audit, instead of hand-wrapping a handful of Web API methods that would drift. OAuth (not a static bot token) is required because the server is an OAuth-protected resource; the DCR-based nested-upstream-OAuth path can't be used because Slack's MCP auth server (like HubSpot's) doesn't support Dynamic Client Registration — the `oauth` provider-connection kind sidesteps DCR by reusing a pre-configured provider client. The `template_oauth_provider`/`McpDetail` fixes are the difference between an oauth MCP service that self-heals and connects through the dashboard versus one that silently 400s on a pinned connection and never prompts to connect. Caveat: the seeded `slack` provider targets the v2 bot-token endpoints; Slack's MCP prefers a **user** token (`oauth.v2.user.access`), so a production deployment configures the provider/scopes accordingly — the injection mechanism is identical either way.

## D25: Org trials are a `plan` tier with banner-only enforcement; self-serve trials go through Stripe

**Date**: 2026-07
**Decision**: Two distinct trial mechanisms, unified in the dashboard as one "trial" banner. **(a) Instance-admin managed trials** extend the `orgs.plan` CHECK with a `'trial'` tier and add `orgs.trial_ends_at TIMESTAMPTZ` (migration `093_org_trial`, mirroring `052`). An org is "on trial" while `plan='trial'` and `trial_ends_at` is in the future, "expired" once it passes — the lifecycle is **derived**, no separate status column and no background sweep. Instance admins (session-only `InstanceAdminAuth`) start (`POST /v1/orgs/{id}/trial`, defaulting to `TRIAL_DEFAULT_DURATION_DAYS`, default 30), bump (`PATCH /v1/orgs/{id}/trial`, extends from the later of current-end/now so an expired trial still gains a fresh window), and opt out (`PATCH /v1/orgs/{id}/plan` → `standard`|`free_unlimited`, which clears `trial_ends_at`); each invalidates `FreeUnlimitedCache` (generalized to cache `(plan, trial_ends_at)` and answer both `is_free_unlimited` and `trial_status`, 30s TTL). **Enforcement is banner-only**: an expired trial keeps serving API calls and stays under normal rate limits — it is NOT `free_unlimited`, so it gets no bypass, and there is NO hard gate in the rate-limit middleware. Expiry only changes what the dashboard shows (an escalating banner fed by `/auth/me/identity.trial`, which reaches every member, plus the admin-only synthetic `/v1/orgs/{id}/subscription` branch reporting `status: trialing | trial_expired`). **(b) Self-serve trials** ("Not sure. Trial for free for a month" on the org-create page) are **Stripe-native**: the checkout sets `subscription_data[trial_period_days]`, so a card is collected but the first charge is deferred by the trial window (Stripe emits `status='trialing'`). These stay `plan='standard'` with a trialing subscription and do not touch the trial tier. `free_unlimited` (e.g. Reveni) is exempt from both — never `'trial'`, never billed.
**Rationale**: A `plan` tier plus a nullable timestamp is the smallest change that reuses the existing `free_unlimited` plumbing (CHECK constraint, `FreeUnlimitedCache`, synthetic-subscription branch) and keeps "add a tier" a one-migration operation. Deriving the lifecycle from `trial_ends_at` avoids a background job and a second status column. **Banner-only** is a deliberate product choice (confirmed with the operator): a hard gate that locks an agent gateway out mid-workflow is hostile for an evaluation period, and the middleware stays simpler for it; the tier + timestamp scaffolding leave a cached hard-gate as a small future change if ever needed. Routing self-serve trials through **Stripe with a card on file** closes the billing-bypass hole that a free self-serve org would open (org creation is otherwise blocked under `cloud_billing` precisely to force everyone through Stripe) while reusing the existing checkout, webhook status-mirror, and the dashboard's pre-existing `trialing` handling almost entirely.

## D26: MCP enrollment org follows the subdomain, not the session

**Date**: 2026-07
**Decision**: On a corp subdomain (`RequestOrgContext::Org { org_id }`), `/oauth/authorize` enrolls the agent into `org_id` unconditionally — the session org, any pre-existing binding, and the client's registration are all subordinate to the subdomain (design: [mcp-enrollment-org-scoping.md](docs/design/mcp-enrollment-org-scoping.md), builds on D12). Three code changes in `crates/overslash-api/src/routes/oauth.rs` make the subdomain the boundary: (1) the parked request's `org_id` is derived from `ctx`, not `session_claims.org`; (2) a warm session whose org ≠ the subdomain org is **re-authed** through the org's IdP (`idp_bounce`, `next=` preserved) rather than silently enrolling into the session org; (3) the fast-path `(user, client_id) → agent` lookup is org-scoped. This required migrating `mcp_client_agent_bindings` from `UNIQUE (user_identity_id, client_id)` to `(user_identity_id, client_id, org_id)` (migration `095_mcp_enrollment_org_scoping`). **Hardening**: DCR clients are org-stamped — `oauth_mcp_clients.org_id` (nullable) is set from `ctx` at `POST /oauth/register` (subdomain → that org; root → NULL = multi-org); a corp subdomain's `authorize` accepts a client whose `org_id` is NULL or equals `ctx.org` and rejects one stamped for a different org (cross-subdomain replay protection), and the admin **Org Settings → MCP Clients** list/revoke is scoped to the admin's own org. **Root apex is unchanged and stays the multi-org hub**: no subdomain to honor, so enrollment follows the session org (which may be a corp org the user belongs to), and no re-auth-on-mismatch fires. NULL-`org_id` clients registered before the migration keep working as "any subdomain."
**Rationale**: The corporate ask ("point our MDM-managed Claude at `acme.api.overslash.com` and trust every enrolled agent is an Acme agent") requires the subdomain to be an *enforced* boundary on where the agent lands, not merely a discovery/cold-login signal. Deriving the org from `ctx` + re-auth-on-mismatch makes the guarantee structural across every path (discovery, cold login, warm re-auth, fast-path rebind). Org-stamping the client is defense-in-depth that also makes the admin client list correctly per-org; keeping NULL/root clients accepted preserves back-compat and the root multi-org experience without a leak, because items 1+2 force the agent into `ctx.org` regardless of the client. The subdomain lock is opt-in — you get it by pointing a client at the subdomain — so it never restricts the root hub.
## D27: MCP-wrapped services get scoped/monotype tools via `mcp_tool` alias + `x-overslash-transform`

**Date**: 2026-07-09
**Decision**: Overloaded MCP tools (e.g. HubSpot's `get_crm_objects(objectType, …)`, `manage_crm_objects`) may be wrapped in higher-level, single-purpose tools — one per (object-type × operation), like `get_contact(id)` / `search_deals` / `update_deal_stage` — layered **alongside** the raw tools, which stay as the escape hatch. Two tiers. **Tier 1 (works today, no runtime change):** alias the action to a raw tool with `mcp_tool:` and pin the discriminator with a param `default:` (`apply_defaults` runs pre-resolve for MCP too). Limitation: the discriminator stays visible/overridable and arg names/shapes must match upstream, since args forward verbatim. **Tier 2 (proposed):** a new optional per-action field **`x-overslash-transform`** — a jq program that rewrites the caller's (defaulted) params into the upstream `arguments` at the `resolve.rs` seam (`let arguments = serde_json::to_value(&req.params)`), reusing the jq engine already behind `x-overslash-disclose`; absent → verbatim (zero regression). This buys true REST shapes (scalar `id` → `objectIds:[id]`, locked/hidden `objectType`, flat map → `createRequest` envelope, and auto-injection of HubSpot's `chatInsights` telemetry). Availability (`get_user_details`) gates each resource's verb set (full CRUD vs read-only vs write-only). Report-building, workflow authoring, and quote/invoice creation are **non-goals** (no MCP tool backs them). Extension named single-word without underscores to match `x-overslash-{risk,disclose,redact,runtime,mcp}` — chosen over `x-overslash-map` / `x-overslash-arg_map`. See [docs/design/hubspot-resty-tools.md](docs/design/hubspot-resty-tools.md) and the draft [docs/design/hubspot-resty-draft.yaml](docs/design/hubspot-resty-draft.yaml).
**Rationale**: The overloaded surface is model-ergonomic but fights Overslash's per-action permission keys, approvals, and disclosure, and cannot express per-type/per-verb availability. Aliasing + defaults already exist, so Tier 1 is free; Tier 2 is one localized seam and one jq field rather than a bespoke templating language, and stays inert for every service that doesn't opt in. Keeping the raw tools avoids losing advanced `filterGroups`/SQL and un-wrapped object types.
## D28: Email integration is a REST facade over the `overfwd` gateway, not a native mail transport; Overslash uses Inline mode

**Date**: 2026-07
**Decision**: Agents send and read/search mail through a separate MIT-licensed OSS project, **overfwd** (repo `overspiral/overfwd`), a thin stateless Rust **Mailbox Gateway** that presents a REST facade (`search`/`get`/`send`) and translates it to IMAP/SMTP (`async-imap` + `lettre` + `mail-parser`/`mail-builder`). Overslash treats it as an ordinary HTTP service — **no `Runtime::Imap`, no non-HTTP execution path in the core**, and JMAP is not used even internally. Scope is **send + on-demand read across the standard-IMAP long tail** (Migadu, Fastmail, iCloud, Zoho, Proton Bridge, corporate Dovecot/Cyrus…); Gmail stays on its REST service and **Microsoft Graph is a separate later track** — the gateway explicitly does **not** cover Gmail/Outlook (they require OAuth XOAUTH2 for IMAP, so the gateway buys nothing there). Own-inbox and real-time inbound are deferred (no inbound-event ingestion subsystem today). Auth has two axes: a gateway `api_key` (`Authorization: Bearer`, server-config `require_api_key`) and a mailbox credential. overfwd offers three credential sources — **Inline** (creds per request), **Portfolio** (gateway-stored, referenced by `account_id`), **Session** (= an ephemeral Portfolio account) — but **Overslash uses Inline only**: the `user:pass` secret is injected as `X-Mailbox-Auth: Basic base64(user:pass)`, host/port are non-secret (interim: prefilled forked templates; a generic per-instance `config jsonb` override is deferred), and on the Overslash→gateway hop the api_key is a **single static Overslash-identity bearer**, so the gateway never sees Overslash tenants. Reads are ordinary `read` (auto-approvable); `send` is `write` (gated, discloses To/From/Subject/Body). Cloud hosting is **Cloud Run** (one shared stateless service; Portfolio store disabled in Cloud). Two bounded Overslash core changes: an `encode: base64` option on `SecretRef`, and multi-injection in `ServiceAuth` (Cloud-only: api_key + creds). See [docs/design/email-integration.md](docs/design/email-integration.md).

**Rationale**: Overslash's executor is HTTP-hardwired (`http_caller` is reqwest-only; `ActionRequest`/`ServiceAuth`/`secret_injection` are HTTP-shaped), so native IMAP/SMTP/JMAP would mean a whole new runtime + auth scheme. A REST facade over a gateway we own keeps the entire permissions/approvals/audit/disclosure pipeline for free (per-action `risk`, `disclose`, permission keys) with no core execution change. JMAP was the initial idea but the facade decision made it a pure implementation detail, and its real-world coverage (no Gmail/Outlook) never justified the translation layer — a direct REST→IMAP/SMTP gateway is simpler and in-stack. Keeping overfwd **stateless + credential-free by default** preserves the "secrets never leave the vault" thesis (Overslash stays the single credential authority; the gateway is a pure function of request + credential), dissolves the two-layer multitenancy problem (a shared multitenant gateway needs zero per-tenant state), and is the sharpest wedge against EmailEngine (stores creds, Node, paid) and Nylas/Unipile (cloud-only, data flows through them). Shipping overfwd as a standalone OSS product — with Portfolio/Session as opt-in convenience tiers layered on the same stateless core — lets it stand on its own while Overslash consumes only the privacy-max Inline path.
## D29: Layered service templates — one `extends`/`delta` primitive for forks and catalog overlays

**Date**: 2026-07
**Decision**: A `service_templates` row is now a **layer**. Migration `097_layered_service_templates` adds `extends text` (base template key; NULL = **standalone** full-doc layer, today's org/user template) and `delta jsonb` (a **derived** layer's masks + extensions), makes `openapi` nullable, and adds a shape CHECK (`(extends NULL AND delta NULL AND openapi NOT NULL) OR (extends NOT NULL AND delta NOT NULL)`). A template is resolved by the **fold** `resolve(layer) = apply(delta, resolve(extends))`: the pure algebra (`apply_delta`/`validate_delta`) lives in `crates/overslash-core/src/service_layer.rs`; the recursive I/O walker in `crates/overslash-api/src/services/template_resolve.rs` unifies the two former `resolve_template_definition` copies so discovery, instantiation, and **execution** all read the effective surface (a masked-out action then returns not-found everywhere for free). Masks are monotonic/order-independent (`allowlist` ∩ / `denylist` \ / `risk` clamp-**up**-only / additive `disclose` / relabel / template `hidden`) so containment is structural; extensions are bounded (add actions/hosts, **no auth**, **no rebinding**; a key colliding with any base key — visible or hidden — is rejected at write time, and the base wins with a `shadowed_extension` warning at resolve time). `extends` is a **live pointer** (tracks upstream), resolved on-demand (no persistent resolved-template cache in v1). `extends` and `key` are **decoupled**: `key == extends` → shadow-with-delta (base resolved one tier up, never itself); `key != extends` → a distinct catalog entry alongside the base. Authority is namespace-based (no classifier): org-namespace layer → admin; user-namespace layer → the new `orgs.user_template_policy` enum (`none | restrictive | full`, migrated in place off `allow_user_templates`), with `restrictive` **reserved** (v1 blocks it; the classifier lights it up later with no migration). Deleting a base with live dependents is blocked (reparent/detach first). The #435 catalog gate coexists and is how an admin hides the raw global.

**Rationale**: Two corporate-refocus asks are the same missing primitive — curate/whitelist tools while tracking upstream, and share a prefilled service without sharing an instance. A fork (full copy) stops tracking upstream and is an unreviewed capability grant; the catalog gate is template-granularity only ("GitHub, but only 4 actions" is inexpressible). Collapsing both into a live-pointer layer with a structural delta gives curation that tracks upstream and, for API owners, bounded authoring — with containment provable by construction (the fold applies each delta to the previous layer's *output*, so a child can never re-expose what a parent hid). Storing the delta structurally (distinct columns, not reusing `openapi`) keeps the JSON self-describing and lets the deferred restrictive/expansive classifier be a pure-compute add with no future migration. Supersedes the earlier org-catalog-overlay draft ([docs/design/layered-service-templates.md](docs/design/layered-service-templates.md)).

## D30: 7-day minimum release age (supply-chain cooldown) on dependency updates

**Date**: 2026-07-11
**Decision**: New dependency versions are gated behind a 7-day cooldown before adoption, via Dependabot's native `cooldown: default-days: 7` on every update entry in `.github/dependabot.yml` (cargo, npm, github-actions). Mirrors overfolder PR #490. Unlike overfolder, no `.cargo/config.toml` staging of cargo's `min-publish-age` (RFC 3923): that feature is nightly-only as of 2026-07 (inert on stable), and this repo deliberately gitignores `.cargo/` for developers' local mold-linker config — tracking a file there would collide with every dev's local setup. See [TECH_DEBT.md](TECH_DEBT.md) for the resulting manual-`cargo update` gap.
**Rationale**: Blocks the short-lived malicious-publish window — most registry supply-chain attacks are caught by scanners within days of publish, so waiting a week before adopting a new version avoids the overwhelming majority of them at near-zero cost (updates flow weekly via Dependabot anyway).

## D31: GitHub Actions pinned to full commit SHAs, not floating major tags

**Date**: 2026-07-16
**Decision**: Every third-party action in `.github/workflows/*.yml` is pinned to a 40-char commit SHA with a trailing `# vX.Y.Z` comment (GitHub's recommended hardening); Dependabot maintains both the SHA and the comment, so D30's `cooldown` now gates every Actions bump the same way it gates cargo/npm. Local `./.github/actions/*` refs are path refs and stay unpinned. Pins were chosen ≥7 days old so adoption itself respects the window, and the shared actions reuse overfolder's exact pins to keep the two repos in lockstep. Extends D30 and mirrors overfolder's 2026-07-13 decision. Obsoletes PR #457 (`taiki-e/install-action` v2 → v2.82.9, tag-to-tag; closed unmerged — this lands the same version as an immutable SHA). Enforced by convention + Dependabot maintenance only, as in overfolder — no `zizmor`/`pinact` checker. See [TECH_DEBT.md](TECH_DEBT.md) for the two pins that track branches rather than release tags.
**Rationale**: A floating major tag (`@v7`) is a *mutable pointer* GitHub re-resolves at CI runtime, so D30's cooldown never actually applied to Actions — Dependabot only opens a PR when it sees a new version, and nothing is proposed when the tag itself moves underneath us. A re-pointed or compromised tag reaches CI on the next run with no PR, no review, and no 7-day delay, which is precisely the window D30 exists to close. Tradeoff accepted: a (grouped) Dependabot PR per action release instead of silent tag drift.

## D32: Per-scheme instance credential bindings (`service_instances.credentials`), not a mixed config map

**Date**: 2026-07-16
**Decision**: A service instance binds secrets **per securityScheme key** via a new `credentials jsonb` column (migration `100_service_instance_credentials`): `{scheme_key → secret NAME in the org vault}`. *(Amended by D119: the values are now secret paths naming a per-user or org vault.)* Values are vault references *by construction* — the map holds names only, never literal values, and there is deliberately **no mixed literal/secret-ref config map** (the tagged `{"secret": …}` shape considered in D28's deferred "config jsonb" idea is rejected: a map that can hold literals makes "raw token pasted as plain config" schema-representable and needs a template-aware runtime gate to catch; separating by kind makes it unrepresentable). `url` stays a typed column; if a second non-secret knob appears it gets its own separate `config jsonb`. To label the slots, `ServiceAuth::Secret` (named `ServiceAuth::ApiKey` when this decision was taken) now carries its compiled securitySchemes key (`scheme`) plus the standard OpenAPI `description`. `secret_source` is **reframed as fallback policy**, not a binding class: every secret slot is per-instance overridable via `credentials[scheme]`; unbound slots fall back to the legacy scalar `secret_name` (instance-source) or the scheme's fixed `default_secret_name` in the org vault (org-source, `optional` skip preserved). The `multiple_instance_secrets` validation is gone (replaced by a duplicate-scheme-key check); templates may declare any number of instance-source schemes. API: `credentials` on create/update is a **whole-map replace**; `secret_name` stays as an alias for the sole instance-source scheme (400 when several exist) and is **dual-written** for one release so rolling deploys keep working, then the column can drop. Dashboard renders one labelled row per scheme (`ServiceCredentials.svelte`). No clash with D29 layers: `Delta` has no auth field by design — layers customize the shared definition, instance credentials fill its slots per deployment.
**Rationale**: `email.yaml` (D28) exposed the flaw twice over. The single scalar + one unlabelled picker mis-bound a real dev instance's gateway token as the mailbox credential (injected into the wrong header while the optional gateway slot was silently skipped). Deeper, `secret_source: org` + a fixed name was itself a workaround for single-slot storage: the gateway key is per-*deployment* and the deployment URL is already per-instance, so two overfwd gateways in one org need different keys — inexpressible with an org-fixed name, natural as an instance binding with an org-wide default.

## D33: Non-secret per-instance values live in their own `service_instances.config`, gated by a template opt-in

**Date**: 2026-07-18
**Decision**: A service instance may pin **non-secret** parameter values in a new `config jsonb` column (migration `102_service_instance_config`): `{param name → value}`. This is the separate column D32 reserved ("if a second non-secret knob appears it gets its own separate `config jsonb`") and closes D28's deferred Core-change #3. A value is storable **only if the template marks that parameter `x-overslash-instance-config: true`** (unprefixed alias `instance-config`), so the surface is template-declared rather than an open bag; unknown keys are a 400, blank values are a 400 (omit the key to unset). At execution time the map is overlaid **after** alias rewriting and **before** defaults, giving precedence `caller arg > instance config > template default` (D36 later inserts an org-layer default between instance config and the template default), and the eligibility check is re-applied at overlay time so a template that stops declaring a param cannot keep feeding a stale pin into requests. `/v1/actions/validate` applies the same overlay so a dry-run and a real call agree. The templates API exposes `instance_config_params[]` (deduped across actions, `required` = AND across occurrences) and the dashboard renders one field per entry on the instance create/edit forms. Secrets are unaffected: they stay vault references in `credentials` (D32), and nothing in `config` is encrypted.
**Rationale**: `services/email.yaml` could not reach a self-hosted mailbox at all. overfwd takes its IMAP/SMTP endpoint from `X-Mailbox-Imap`/`X-Mailbox-Smtp` request headers and otherwise falls back to autoconfig (Mozilla ISPDB + DNS SRV), which resolves only public providers — and cannot resolve anything for a login that isn't an email address. D28's interim answer was "prefilled forked templates", i.e. one fork per deployment to vary a hostname, which is a capability grant used as a config mechanism. The endpoint is a property of the deployment, not of the call: an agent has no way to know it, so it does not belong in caller args; it is not a credential, so it does not belong in the vault. Keeping literals in a column that *cannot* hold vault references preserves D32's central property — "raw token pasted as plain config" stays unrepresentable, with no template-aware runtime gate needed to catch it.

## D34: Dev-auth can mint a private org per e2e spec; teardown is a cascade delete

**Date**: 2026-07-18
**Decision**: `GET /auth/dev/token` accepts an optional `org=<slug>` (dev-gated as before). Absent, it resolves the shared `dev-org` exactly as it always has — every existing screenshot script and spec is untouched. Present, it resolves-or-creates that org and derives **per-org profile emails** (`dev+<slug>@overslash.local`), because `find_user_identity_by_email` is a global lookup and reusing the fixed addresses would have a second org's login resolve the first org's identity. `dev-org` is rejected as an explicit slug, and slugs are validated against the same rules as `POST /v1/orgs`. `DELETE /auth/dev/orgs/{slug}` (also dev-gated) drops the org; it is idempotent, refuses `dev-org`, and is implemented as a bare `DELETE FROM orgs` because 29 of the 30 FKs referencing `orgs(id)` are already `ON DELETE CASCADE` (the exception, `users.personal_org_id`, is `ON DELETE SET NULL`, so a `users` row survives as an orphan — deliberately not chased, since deleting it would reach outside the org boundary). The scenarios library exposes `login(profile, { org })`, `freshOrgSlug()` and `deleteOrg()`.
**Deliberately not done yet**: `playwright.config.ts` keeps `fullyParallel: false` / `workers: 1`. Per-org isolation is the precondition for parallelism, not parallelism itself — the shared-`dev-org` specs (the majority) still collide with each other, and the GreenMail container's mail is global rather than org-scoped. Flipping workers is a separate change once enough specs have moved over.
**Rationale**: The dashboard e2e suite had no state isolation and knew it — `playwright.config.ts` pins `workers: 1` with the comment "tests share dev-login users", and the scenarios README told authors to work around collisions by hand with `${name}-${Date.now()}` suffixes. That makes whole categories of user story untestable: anything asserting "my services", "my secrets" or an empty state is at the mercy of whatever ran before it. Per-database isolation (the Rust suite's `CREATE DATABASE ... TEMPLATE` trick) is the wrong granularity here because the dashboard talks to one long-lived stack; per-org is the natural tenant boundary and the schema already made it a one-line teardown.

## D35: Credential slots are declared once and composed into injections by a jq template

**Date**: 2026-07-20
**Decision**: A template's **credential slots** (the vault secrets an operator binds) are declared once under `components.x-overslash-secrets` — `{slot key → {label, description, default_secret_name, source, optional}}` — and are separate from the **injections** that read them (`securitySchemes`). A scheme builds its value with `x-overslash-template: {lang: jq, expr: …}` over those slots, e.g. `'"Basic " + (.mailbox_user + ":" + .mailbox_pass | @base64)'`. A slot may feed several injections and an injection may join several slots; a scheme with no template injects one secret verbatim, and always implicitly declares the slot named after itself (so the 18 single-secret templates declare no secrets block). `x-overslash-prefix` and `x-overslash-encode` are **removed** — along with `SecretEncoding` and `TokenInjection::encode` — and now fail template validation with a message naming the equivalent `expr`. `TokenInjection::prefix` survives for OAuth only (a live token is not a vault secret), as does `SecretRef::prefix` for raw-HTTP Mode A, whose documented per-call `secrets[]` shape has no template to carry it. jq is the one expression language in the product (it already runs response filters and disclosures), so this adds no grammar, no parser and no new syntax to document — and brings `@base64`/`@uri`/interpolation/defaults for free. Which slots an expression reads is resolved **statically at template-compile time** by walking jaq's public AST (`overslash-core` takes a `jaq-core`-only dependency for lexing/parsing; evaluation stays in `overslash-api`), stored on the compiled `ServiceAuth::Secret`, and narrowed into each `SecretRef`'s `bindings` — so the request path decrypts exactly the secrets that header needs and hands jq nothing else. Dynamic key access (`.[$k]`, `getpath`, `to_entries`, `keys`, `..`) is rejected at load time, because it would defeat that analysis. Slot keys are flat strings in the existing `credentials jsonb` (D32), so **no migration**. `ServiceDefinition::slots_for`/`all_slots` own the implicit-slot rule in one place; the templates API exposes `secrets[]` and the dashboard renders one picker per slot.
**Rationale**: D28's `email.yaml` forced the mailbox login to be stored as a *single* secret whose literal value was `user:pass`, because `encode: base64` + `prefix: "Basic "` were the only transforms and they applied to one opaque value. That fuses a username and a password in the vault (no independent password rotation, and neither half is separately auditable), asks the dashboard user to know a colon convention, and generalizes to nothing — the next template wanting `{tenant}\{user}:{pass}` or one secret in two places needs another one-off extension. Two costs of a general evaluator were addressed rather than accepted: jq runtime errors embed their operands, so the credential path never propagates jaq's message (only "template for scheme X failed"); and `"user" + null` is `"user"` in jq, so a missing slot would silently render `Basic base64("user:")` — a truncated credential indistinguishable downstream from a wrong password — which is why `render` refuses to build a value for a slot it has no value for.

## D36: An org layer may preset the per-instance surface (`delta.instance_defaults`); a user layer may not

**Date**: 2026-07-20
**Decision**: `Delta` gains a third half alongside the masks and `extensions`: `instance_defaults`, carrying exactly the **non-secret** surface a service instance can otherwise set — `url` (the endpoint) and `config` (values for params the template declares `x-overslash-instance-config`, D33). Credentials, connections and `discovered_tools` are deliberately excluded, so D29's "a delta never touches auth" invariant is untouched. Precedence at execution is `caller arg > instance.config > layer default > template default` for params and `instance.url > layer default > template servers[0] / mcp.url` for the endpoint — a preset, never a pin, so a developer can still point one instance at a local deployment. Authority is **org-tier only**: a user layer setting the field is a write-time error (`instance_defaults_user_tier`), on both `POST/PUT /v1/templates` and the `/v1/templates/validate-delta` lint preview, since redirecting where an org's traffic lands is an org-admin decision; every tier still *inherits* defaults set upstream. The endpoint's **origin** (`scheme://host[:port]`, not the bare hostname) is unioned into the effective `hosts` so the service+HTTP-verb shape's host-and-port matcher accepts the gateway without silently allow-listing `:443` on it. `InstanceDefaults` is `deny_unknown_fields` — a misspelled key would otherwise deserialize to an empty struct, validate clean, and silently leave traffic on the shipped default. The declared-keys/blank-value rules move to `overslash_core::instance_config`, shared by the instance and layer write paths. Normalization (trailing `/`, whitespace) happens at **fold** time, not write time, so pre-existing rows fold correctly and a layer default injects byte-identically to the same value pinned on an instance. `TemplateDetail.instance_defaults` exposes the folded result; the layer editor renders an org-scope-only "Instance defaults" section and the instance create/edit forms render inherited values as placeholders.
**Rationale**: `email`'s mailbox credential is `secret_source: instance`, so every user creates their own instance — and with only D33's per-instance `config` and the per-instance `url`, each of them had to paste the same org gateway URL and IMAP/SMTP host by hand. There was no org-wide default at all. A bespoke `base_url` field would have solved only the endpoint; generalizing to "everything an instance can pin" costs one struct instead of two mechanisms, and covers the corporate-Dovecot case (same IMAP host org-wide, different credential per user) that a URL override alone does not. It is not a rebinding in D29's sense: method, path and auth are untouched, only the origin the same operation is dialled on.
## D37: Yahoo Mail rides the generic `email.yaml` gateway — no native template, no `yahoo` OAuth provider

**Date**: 2026-07-20
**Decision**: Yahoo Mail is consumed through the generic **`services/email.yaml`** Mailbox Gateway template (D28) with a **Yahoo app password** as the mailbox credential. There is deliberately **no `services/yahoo_mail.yaml`** and **no `yahoo` row in `oauth_providers`**. A Yahoo mailbox is an ordinary `email` service instance: the app password binds to the **`mailbox_pass`** credential slot and the full Yahoo address to `mailbox_user`, which the `mailbox` scheme composes into `X-Mailbox-Auth` through its jq template (D35), both stored in `service_instances.credentials` (D32). The endpoints are either pinned per-instance via `service_instances.config` (D33) as `X-Mailbox-Imap: imap.mail.yahoo.com:993` / `X-Mailbox-Smtp: smtp.mail.yahoo.com:465`, preset org-wide by an org layer's `delta.instance_defaults` (D36), or left unset so overfwd's autoconfig resolves `yahoo.com` from the Mozilla ISPDB. Zero new code, no new template, no migration. **Reopen only if both** of these change: overfwd gains SASL OAUTHBEARER **and** Yahoo grants `mail-r`/`mail-w` — either one alone is insufficient.
**Rationale**: A `gmail.yaml`-shaped template is a set of OpenAPI paths over HTTPS, and Yahoo Mail has none to point `servers:` at — the proprietary Mail API (JSON-RPC at `mail.yahooapis.com`) is retired and Yahoo's own sender documentation offers only IMAP (`imap.mail.yahoo.com`) and SMTP (`smtp.mail.yahoo.com`). Yahoo's OAuth host (`api.login.yahoo.com/oauth2/{request_auth,get_token}`) is real but does not help: the `mail-r`/`mail-w` scopes are **not self-serve** (they require a signed Commercial Access Agreement) and they authenticate IMAP/SMTP via SASL OAUTHBEARER rather than HTTP requests, while overfwd accepts only `X-Mailbox-Auth: Basic base64(user:pass)` and states outright that it has no OAuth flow. An OAuth Yahoo would therefore need work in a second repo (`overspiral/overfwd`) *and* a business agreement with Yahoo, for a surface the gateway already covers. **Yahoo is explicitly not the Gmail/Outlook carve-out** in D28: those are excluded because Google/Microsoft *force* XOAUTH2 for IMAP, so routing them through the gateway buys nothing over their REST APIs and loses fidelity (labels, threads, search operators). Yahoo is the mirror image — it has no REST API to lose fidelity against and still accepts an app password over standard IMAP/SMTP — which places it squarely in the "standard-IMAP long tail" the gateway was built for. See [docs/design/email-integration.md](docs/design/email-integration.md).

## D38: A credential template may read declared non-secret inputs (`components.x-overslash-config`)

**Date**: 2026-07-20
**Decision**: A template declares **non-secret per-instance inputs** under `components.x-overslash-config` — `{key → {label, description, required}}` — and a `securityScheme`'s jq template may read them alongside its slots, e.g. `email.yaml`'s `'"Basic " + (.mailbox_user + ":" + .mailbox_pass | @base64)'` where the username is config and only the password is vaulted. Values live in the existing `service_instances.config` jsonb (D33) and share its namespace: a config var colliding with an `x-overslash-instance-config` param name is a **template compile error**, since one key is one field on the instance form. **No migration.** Which reads are secret is settled statically at compile time — `credential_template::partition_reads` splits the AST walk's results against the declared config keys, everything undeclared stays a secret slot (the safe default), and `ServiceAuth::Secret` carries `slots` and `config_keys` separately because they resolve from different stores. Every D35 refusal is unchanged: a config declaration buys an expression no freedom, because anything that can reach an unnamed key can reach a secret. A scheme whose template reads *only* config is rejected — a header of public values authenticates nobody and belongs in `parameters`. Resolution is **instance value > org layer's `instance_defaults.config` > unset**; `required` + unset marks the scheme unresolved exactly as an unbound slot does, and `render` refuses a missing config value for the same reason it refuses a missing slot (`"user" + null` is `"user"`, so the missing *username* renders `Basic base64(":pass")` — the D35 truncation hazard with the halves swapped). **No new delta field**: because a config var is a key of the same map, D36's `instance_defaults.config` presets it for free — an org layer sets its shared mailbox login once and every instance inherits it, with the instance still winning, and D29's "a delta never touches auth" is intact because what a layer supplies is the half that is not a credential. `instance_config::configurable_keys` gains the config vars, so the instance and layer write paths accept the same keys from one definition. Values ride on `SecretRef.config` and are therefore **persisted in approval payloads in the clear**, which is sound only because they are non-secret by declaration. **Hard cutover, no compat shim**: an `email` instance that bound `mailbox_user` in `credentials` now fails validation with a message telling the operator to move it to `config`.
**Rationale**: D35 fixed the vault half of `email.yaml` (username and password became separate secrets) but left the username *in the vault*, because a credential template's only possible input was a decrypted slot. A mailbox username is the public half of a login — usually the email address itself — so vaulting it buys nothing and costs a write-only dashboard field plus a second vault entry per mailbox. D33 had already built the machinery for exactly this kind of value (per-instance, non-secret, template-declared, its own column that *cannot* hold a vault reference), but scoped it to action params: config reached call arguments and never credential rendering. This is the smaller of the two possible fixes — the alternative, a `secret: false` flag inside `x-overslash-secrets`, keeps one block at the price of misnaming it and making every consumer branch on the flag. D32's central property survives untouched: `config` still cannot hold a vault reference, so "raw token pasted as plain config" stays unrepresentable.
## D39: The shared Mailbox Gateway is platform-hosted, and its key comes from a platform rung below the org vault

**Date**: 2026-07-20
**Decision**: overfwd (`overspiral/overfwd`) is deployed **once, by Overslash**, as a Cloud Run service serving `mailbox.overslash.com` (`mailbox.dev.overslash.com` in dev) — the hostname `services/email.yaml` has always shipped as `servers[0]`. Terraform lives in `infra/modules/cloud-run-overfwd/`, gated on `enable_overfwd`; the image is a third-party one we deploy but do not build, so it is **digest-pinned** and pulled through an Artifact Registry remote repository rather than from Docker Hub at deploy time. The gateway runs with `OVERFWD_REQUIRE_API_KEY=true`. Because the `gateway` scheme is `secret_source: org` with a fixed `default_secret_name`, requiring the key would otherwise mean every org independently storing the *same* platform key — so the credential cascade gains one rung **below** the org vault: `Config::platform_credential` (`OVERSLASH_PLATFORM_GATEWAY_SECRET_NAME` / `_HOST` / `_KEY`, all three required), consulted for an **org-source** slot whose secret is absent from the org vault. It is pinned to a single host and matched on both the vault secret name and the effective request origin — checked at resolve time (`resolve_instance_auth`, deciding whether the optional scheme is emitted at all) and **again** at send time against `action_req.url`, so an approval replayed after its instance was repointed cannot carry the key out. An instance binding or an org secret still wins, so a self-hosted overfwd, a keyless one, and a per-org key all keep working unchanged. Both services read one GSM secret (`overslash-{env}-overfwd-gateway-key`), so rotation is one `versions add` plus a revision roll. The rung is deliberately **one entry, not a map**: there is exactly one platform-hosted upstream, and a general "fill any credential from env" mechanism is what `OVERSLASH_DANGER_READ_AUTH_SECRET_FROM_ENVVARS` (OAuth clients, tier 4) exists to gate loudly.
**Rationale**: Overfolder built a per-org deployment (overfolder#528) and backed it out (#530) for the right reason: overfwd is stateless — no credentials and no mail at rest, the mailbox login presented per request — so a per-org copy protects nothing a shared one leaks, while multiplying cost, keys to rotate and images to patch. That makes the gateway a platform service, and a platform service cannot ask its tenants to hold its key; the alternative (`require_api_key=false`) would put an unauthenticated IMAP/SMTP proxy on the public internet. Host-pinning is the load-bearing part: `instance.url` is tenant-controlled (D36 lets an org layer redirect every instance in the org), so a rung that filled the slot regardless of destination would hand the platform key to any host a tenant named. **SSRF posture**: a shared gateway takes endpoint headers from every tenant, and overfwd's filter (`autoconfig.rs::is_public_domain` + a loopback/private-refusing resolver) originally covered only the domain-derived path — an explicit `X-Mailbox-Imap: host:port` was parsed by `auth.rs::HostPort::parse` with no address check at all, deliberately, so the local GreenMail stack works. That gap was closed upstream in **overfwd v0.3.0** (`OVERFWD_BLOCK_PRIVATE_ENDPOINTS`, off by default, which this deployment sets to `true`): a target that is *or resolves to* a loopback / RFC1918 / link-local / CGNAT / IPv6-ULA address is refused before anything is dialled, so a hostname whose A record points inward is caught too. Hence the image is digest-pinned at v0.3.0 or newer. Two further layers stand behind it: the service is attached to **no VPC connector** (it also needs plain egress to IMAP 993 / SMTP 465, which a connector without NAT would break), so "internal" is the container and the GCP metadata endpoint and nothing of ours; and the endpoint headers are `x-overslash-instance-config`, i.e. org-admin-set rather than agent-supplied. See [docs/design/email-integration.md](docs/design/email-integration.md) and [docs/runbooks/mailbox-gateway.md](docs/runbooks/mailbox-gateway.md).

## D40: Permission keys carry a scope label (`{service}:{action}:{label}={value}`); value-only patterns stay valid and label-agnostic

**Date**: 2026-07-21
**Decision**: `x-overslash-scope_param` accepts a param name, a `param:label` pair, or a **list** of either. Each scoped value mints `{service}:{action}:{label}={value}` (label defaults to the param name), keys are deduped, and `services/email.yaml`'s `send` now scopes `[to:recipient, cc:recipient, bcc:recipient]`. On the matching side, a key answers to two forms: itself, and its **value-only** form with the `label=` prefix stripped — so `email:send:*@example.com` covers `recipient=a@example.com`, while `email:send:cc=*@example.com` covers only the `cc` label. A prefix counts as a label only when it is a bare identifier, so a value containing `=` is never sliced.
**Rationale**: `scope_param` named one param, so cc/bcc recipients consumed no permission key at all: a grant for `email:send:*@example.com` gated the `to` line and let a bcc go anywhere — the gap `email.yaml` had carried as a comment since the send action shipped. Fanning out over several params closes it, but raises a second question the flat arg cannot answer: are `to=a@x.com` and `cc=a@x.com` one decision or two? Both answers are right for different templates, so the **label is author-controlled**. Params that mean the same thing to the person granting access share a label and collapse (one address on two headers is one approval); params that don't stay distinct and can be granted separately. Labelling the arg is what makes that expressible at all — an unlabelled union could only collapse, and an unlabelled fan-out could only split. Back-compat is the load-bearing constraint on the matching rule: keys are stored on approvals and audit rows and are typed by hand into grants, so changing the derived shape had to leave every existing rule matching. Hence value-only patterns match any label rather than being migrated, and the broadening ladder offers the value-only form as its own rung ("this correspondent, whichever header") between the exact key and `{service}:{action}:*`. Templates whose recipients are arrays of *objects* (`outlook`, `google_calendar` attendees) cannot use this — scoping them needs a value extractor on the scope entry, tracked in [TECH_DEBT.md](TECH_DEBT.md). **The compat rule is deliberately one-way**: a value-only pattern covers a labelled key, but a `label=`-qualified pattern does not cover a label-less one. That direction is reachable — approvals persist their derived keys and `cascade_resolve` re-matches those stored strings against rules written later — so an approval filed just before this shipped (`email:send:a@example.com`) is not auto-resolved by a rule remembered just after (`email:send:recipient=a@example.com`). It cannot be: the stored key records no label, so nothing says whether that address was a `to` or a `bcc`, and honouring a `cc=`-scoped grant over it would grant more than the operator wrote. The cost is a human click on approvals filed inside one `APPROVAL_EXPIRY_SECS` window (30 min by default), after which the population is empty; the alternative is silently widening a narrow grant.

## D41: Members are `identities`; invites and impersonation both pre-create them, and first sign-in adopts by email

**Date**: 2026-07-21
**Decision**: A person belongs to an org iff a `kind='user'` identity for them exists in that org — there is exactly **one** such identity per person per org, and the former `org_invites` table is dropped (migration 103). A pending invite is now that identity with `external_id IS NULL` ("belongs to the org, never signed in"); an admin invite additionally carries `is_org_admin` + Admins-group membership. Three paths create the same row: an admin invite (`/v1/org-invites`, reimplemented as a projection over identities, same wire shape), **name-based impersonation** (`X-Overslash-As: alice@acme.com[/agent/...]` — an impersonation-scoped key provisions the user, and any named agent chain, on demand), and a first SSO sign-in. `provision_org_subdomain` gained an **adopt-by-email** branch after the `(org, external_id)` short-circuit: it finds the pre-created identity by verified email and stamps the IdP subject onto it instead of forking a second identity, so the person lands on their pre-created agents, connections, and audit history. This subsumes and deletes both the old `existing_member` (users-by-email) short-circuit and the `org_invite::find_pending`/`mark_accepted` gate. `orgs.require_invite_admission` keeps its exact meaning — with it on, a verified email with no pre-created identity is rejected `not_invited`; the domain-allowlist and legacy per-provider-IdP admission branches are unchanged and still mint fresh identities. A second IdP for the same email re-points that identity's `external_id` (one human = one identity per org). Auto-created identities are unprivileged by construction (`inherit_permissions = false`, plain member) and impersonation auto-creations are audited `identity.provisioned`.
**Rationale**: A pending invite (`org_invites(email, role, accepted_at)` — no token, no expiry) carried exactly the information a pre-created user identity already can: an email, an admin bit, and a "has it been claimed" flag (`external_id IS NULL`). Keeping both meant two representations of "this person may join", and the impersonation feature — which must let a white-label backend (Overfolder) name a user by email and have them JIT-provisioned — only pays off if that provisioned identity *is* the one the person later signs into, rather than being orphaned beside a fresh SSO identity. Making admission key on the identity (not on a `users`+membership pair) is what unifies the two: invite, impersonation, and sign-in all reduce to "ensure the user identity exists, then attach the IdP subject". The one deliberate behaviour change is that a second IdP now lands on the same identity rather than forking a second one onto a shared `users` row — which is what the agents, connections, and Myself group per identity already assumed. `external_id` stays pinned to the subject that originally claimed the identity and is never rewritten by a later provider: a flip-flopping subject would make the `(org_id, external_id)` fast path miss on alternating logins and make `connect_gate`'s cross-org subject match depend on whichever IdP was used last. Security posture is unchanged: the old gate also admitted on verified-email match, and the `(org_id, external_id)` unique constraint keeps the first link safe. The `/v1/org-invites` endpoints are retained as a compatibility projection because external callers depend on them. See §4 of [SPEC.md](SPEC.md).

## D42: SQL-bearing tool params get a field-nominated, Postgres-exact parse policy (`pg_query`); read/write + table rules enforce in Overslash, column masking pushes to the DB

**Date**: 2026-07-24
**Decision**: For tools that take a raw SQL string — first the Metabase MCP's `execute`/`export` (`query`), later HubSpot `query_crm_data`, Shopify ShopifyQL, etc. — Overslash gains a **content policy driven by two field-level `x-overslash-*` annotations**, not a hardcoded per-service code path: (1) `x-overslash-sql: true` marks the string param that carries the query (deliberately **not** a synthetic OpenAPI `type`/`format: sql` — 3.1 has no such type and we don't invent one; it's an extension on an ordinary `string`, normalized via `openapi/alias.rs` like every other `x-overslash-*`); (2) `x-overslash-sql-database: <jq expr>` names a **jq expression over the call params** (single field `.database_id`, or a composition like `.project + "/" + .dataset`) whose result is looked up in per-instance config (`x-overslash-instance-config`/`x-overslash-config`, **D38**) to resolve the **dialect** and a human **DB label** for audit — unresolved falls back to `postgres`, fail-closed. Parsing uses the **`pg_query` crate (Rust bindings over `libpg_query`, Postgres's own C parser)**, chosen over pure-Rust `sqlparser-rs` because correctness of read/write + table/column *is* the point and libpg_query parses anything Postgres accepts identically and exposes `.tables()`/column refs/statement types directly; it is gated behind a **`sql_policy` Cargo feature, off by default** (it adds a C-toolchain build dep and binary weight, which the default build must not pay). Enforcement scope is deliberately **asymmetric and honest**: **read-vs-write** is classified from the parse tree (fail-closed — `SELECT`/`WITH`-only → read; DML/DDL/`TRUNCATE`/`COPY`/multi-statement/**writable CTE**/`DO`/`CALL`/unparseable → write), elevating the action's otherwise-static `Risk` so writes route to approval bubbling; **per-table** rules are enforceable by deriving one permission key per referenced relation, DB-label-scoped, reusing the existing `scope_param` key shape (`metabase:execute:table=reveni-prod/public.orders`) and glob rule engine with no new grammar; **column** rules are fail-closed detection only — **`SELECT *` surfaces `*` as a literal column name** so a deny-`*` rule forces explicit enumeration (after which listed columns bite), but views/CTEs hide base-table columns from any parser, so **true column masking (PII) is pushed down to Metabase data-sandboxing / column DB grants**, never claimed as an Overslash-side guarantee. A **read-only Metabase key/group remains the backstop** regardless (parse = belt, key = suspenders). Sequencing: **audit first** — ship `services/metabase.yaml` with per-operation actions and a `disclose` filter capturing the raw `query` (Reveni's only near-term need, no parser required) — then the classifier, then per-table keys, then column rules. Design notes: [docs/design/metabase-mcp.md](docs/design/metabase-mcp.md).
**Rationale**: The Metabase MCP's own read-only guard is a client-side regex that Metabase does not enforce (see the design doc); asking "should Overslash re-implement per-table/column authorization by parsing SQL" splits cleanly once you separate what a parser can *guarantee* from what it can only *detect*. Statement kind and referenced table names are structurally present in the parse tree, so read/write routing and per-table gating are real, enforceable wins that beat both the regex and a read-only key *for approval routing* — and they land on the existing risk→approval and `scope_param`→glob machinery with almost no new surface. Resolved column identity is **not** structurally recoverable without catalog resolution (`SELECT *`, view expansion, CTE aliasing), so promising column masking in the gateway would be security theater; the DB/Metabase own that boundary because they own the schema, and the `*`-as-column convention keeps the gateway honest by converting the unknowable case into a forced-enumeration deny rather than a silent hole. Choosing libpg_query over `sqlparser-rs` trades a C build dep (contained by the default-off feature) for Postgres-exactness, which is the whole value proposition here; the dialect is resolved from the nominated DB field rather than pinned per action precisely so a second backend (`sqlparser-rs` for best-effort dialects, or another engine) can be added later without touching the rule surface. Making the policy attach to **fields** rather than to a Metabase-specific handler keeps it a generic gateway capability (CLAUDE.md Rule 4) — Metabase is just the first template to set the two annotations. Auditing first matches the customer's actual near-term ask and defers all parser/build cost until the enforcement tiers are wanted.

## D43: One `x-overslash-sql-field` annotation nominates the SQL param and its body path; `risk: dynamic` is explicit; column rules are deny-screen only

**Date**: 2026-07-24
**Decision**: D42's two-annotation sketch ships as **one field annotation plus one declared-risk value**. (1) **`x-overslash-sql-field: <dotted-path>`** on a param both marks it as the raw-SQL field and names the SQL string's location in the assembled JSON body. Two modes fall out of the param's type: a **string param** is *placed* at the path (`query` with `native.query` sends `{"native":{"query":…}}` while the caller surface stays flat — Metabase `run_query`), and an **object param** is *descended into* (the path anchors at the param name: `query` with `query.native.query` reads the SQL inside the caller-supplied dataset object — Metabase `export_query`, whose upstream endpoint takes the query as one nested object). A raw non-JSON body (`Content-Type: application/sql`) is not representable — the assembler only emits JSON built from params — and is deliberately out of scope until a raw-body content type exists. The separately-sketched generic `x-overslash-body-path` is **not** shipped: its only consumer was the SQL param, and the sql-field path subsumes it; introduce it independently if a non-SQL param ever needs nesting. `x-overslash-sql-database` stays as decided (jq over call params → `sql_databases` config var, exempted from the "config must be read by a scheme" gate). (2) **`risk: dynamic`** is a fourth declared-risk value (`DeclaredRisk`; the runtime `Risk` stays a tri-state): template validation rejects it on an action with no sql-field param (`dynamic_risk_without_sql`), static/display contexts resolve it as **write** ("write until proven read" — listings, approval-card fallback, the mutating-actions-declare-disclose gate, layer-fold clamping), and at call time it starts from **read** and merges the classifier's verdict as a floor via `Risk::max_severity` — a build without the `sql_policy` feature, an unsupported dialect, an unparseable statement, or an sql param the caller never supplied all resolve to write. A static risk with an sql-field param is also legal: the classifier can only elevate it. (3) **Per-table keys are split by context**: relations referenced in select context mint `{service}:{action}:table={label}/{relation}`, **mutation targets** (DML/DDL context, straight from the parser's per-relation tagging — `select_tables()` vs `dml_tables()`/`ddl_tables()`) mint **`table_mut={label}/{relation}`**, and the all-tables sentinel is mutation-shaped (`table_mut={label}/*`) because every non-enumerable case also classifies write. A relation both read and mutated (`INSERT INTO a SELECT * FROM a`) carries both keys. The two labels are disjoint on the matching side — a rule for one never covers the other — while D40's label-less **value-only form** (`{service}:{action}:{label}/{relation}` stripped of `table[_mut]=`) covers both, giving the broadening ladder a "this table, read or write" middle rung. This is what keeps **Allow & Remember honest** (a rule remembered from a read approval never silently authorizes later mutations of that table), makes asymmetric policies expressible (allow `table=pagila/*` + allow `table_mut=pagila/public.scratch`), and makes write-only denies possible (deny `table_mut=pagila/*` leaves reads untouched). (4) **Column keys are deny-screen only** (`check_permissions_screened`): named identifiers mint `{service}:{action}:column={label}/{ident}` and a star select mints **`{service}:{action}:column_star={label}`** — its own label, because a glob pattern cannot name the literal `*` without matching everything, so "force enumeration" is the typable deny `{service}:*:column_star=*` and per-column denies stay independent (`{service}:*:column=*/ssn`). Screen keys can trip a deny at any chain level but never need allow coverage and never appear in approvals. **A deny overrides every allow mechanism**: SQL-classified calls run a deny-only chain sweep (`denied_anywhere`) even on the paths that skip the full walk — the `auto_approve_reads` read bypass and the users-approve-themselves rule — while table-key *allow* coverage is deliberately still bypassed by `auto_approve_reads` for read-classified calls (a blanket read grant covers the service's read surface; the table tier gates agents without one — and a write-classified call never takes the bypass, so `table_mut=` coverage is always walked). Table keys append to the scope_param keys but **replace** the bare `{service}:{action}:*` fallback (no table rule can cover `:*`, so keeping it would collapse the tier into "grant the whole action"), and the broadening ladder gives slash-carrying labelled keys `**` rungs (`table=db/*` → `{service}:{action}:**` → `{service}:**`) because `*` does not span `/`.
**Rationale**: The merge came from asking where SQL can actually live in a request: directly as the body, as a flat string body param, or at a path inside a JSON object param. One dotted body path answers "which param" and "where in the body" for all representable cases, so two annotations would encode one fact twice — and the annotation doubles as caller-surface control, keeping Metabase's `run_query` flat and agent-friendly while matching the upstream's nested payload byte-for-byte (verified against a live Metabase + Pagila stack; the export endpoint's nested-object contract is exactly what forced extraction mode). `dynamic` is declared rather than inferred (a static `read` + parse-elevation would look identical at call time) because the template should say out loud that an action's class is decided per call — validation can then demand the sql param, catalogs can render it, and a fail-closed resolution exists for every path that produces no verdict. `column_star` exists because D42's "deny-`*` forces enumeration" was unimplementable in the glob engine as literally written. The read/mut split closes a hole the single-label shape shipped with for a few hours: one `table=` key meant a rule remembered from a *read* approval covered later *mutations* of the same table at Layer 2 (the human approved a SELECT and durably authorized INSERTs, gated only by the coarse per-service ceiling), and neither "read anything, write only scratch" nor a write-only deny was expressible. The parser already tags every relation with its context, so the split costs one more label and nothing else; it was done before any `table=` rules existed in the wild, so no compat story was needed — and it mirrors how the database itself models the boundary (`GRANT SELECT` vs `GRANT INSERT`). The deny-sweep-under-bypass rule resolves a real conflict surfaced by tests: `auto_approve_reads` skips Layer 2 wholesale, which would have silently skipped PII column denies too; "deny rules override allow rules" is the documented contract, so the bypass stays an allow-only fast path. Sequencing note: all D42 tiers shipped together (template, classifier, table keys, column screen) — the audit-first cut proved unnecessary once the classifier landed in the same change. See [docs/design/metabase-mcp.md](docs/design/metabase-mcp.md).

## D44: A template resolves deployment-specific values from `${VAR}`, sourced only from `OVERSLASH_TEMPLATE_VAR_*`

**Date**: 2026-07-30
**Decision**: A service template may write **`${NAME}`** or **`${NAME:default}`** in any string value, resolved at compile time from environment variables under the single prefix **`OVERSLASH_TEMPLATE_VAR_`** (`NAME` is `[A-Z][A-Z0-9_]*`, the prefix is stripped, `$${` escapes a literal `${`, anything else after `$` is copied verbatim so jq and prose survive). **Unset with no default is a compile error** (`template_var_unset`), never an empty string: shipped templates log-and-skip exactly as they do for any other load failure, `POST /v1/templates/validate` reports it to the editor, and the message names the environment variable to set. A third form, **`${NAME?}`, defaults to null** — unset replaces the whole value (it must *be* the whole value; `template_var_optional_not_whole` otherwise) rather than erroring. The three forms map onto three genuinely different situations, and the two shipped templates use two of them. `services/email.yaml`'s `servers[0]` is `https://${MAILBOX_HOST}` with **no fallback**: a self-hoster has no Overslash gateway, so both a literal default and a null would be wrong, and unset correctly means "this deployment has no `email` template". `services/metabase.yaml`'s is `${METABASE_URL?}`: Metabase is self-hosted, so no host is honest for every deployment, but *dropping* the template would be wrong too — the deployment merely doesn't know the URL, and the operator does. Null makes `extract_hosts` skip the entry, leaving a host-less template, which is the pre-existing "operator supplies the endpoint at instantiation" shape (`telegram`, `whatsapp`, every MCP template). `configurable_url` therefore also returns true for any host-less template (except the `http` pseudo-service, whose callers pass a full URL per call), and `kernel_create_service` **requires** `url` for a host-less HTTP template unless a layer's `instance_defaults.url` supplies one — the HTTP twin of the check MCP templates already had. One consequence had to be closed at the same time: `resolve_verb_host_and_path` read `hosts: []` as *unbound* ("the caller names the target on every call"), which was safe only while `http` was the only host-less HTTP template. A named service compiling host-less would otherwise have become a raw-HTTP escape hatch reachable at any host — the binding gap D14 removed Mode B to close. The unbound branch is now keyed on `registry::HTTP_PSEUDO_SERVICE` rather than on emptiness, and every other host-less template refuses the verb shape and directs the caller to its actions. A literal default belongs only on a variable that means something in a standalone deployment; neither shipped template qualifies. Expansion runs for **org- and user-authored templates too**, not just shipped ones, and always on the **parsed document's string values** (`template_vars::expand` over `serde_json::Value`), never on YAML source: a value carrying `"` or a newline therefore cannot restructure a document, which is what makes the tenant-authoring case safe rather than merely validated. Object keys and non-string values are untouched. The **stored document keeps its references unexpanded** — expansion happens at load (`registry::load_from_dir`) and at resolve (`template_resolve`, `embedding_backfill`), so one row follows whichever deployment reads it instead of freezing the authoring one's hosts. Terraform derives `OVERSLASH_TEMPLATE_VAR_MAILBOX_HOST` from the **same `overfwd_domain`** that feeds `platform_gateway_host`, so the template host and the platform-key host gate cannot drift; a `template_vars` map carries any others. `GET /v1/templates/vars` lists the configured set, names **and values**, to any authenticated caller. Layer **deltas** are not expanded — `instance_defaults.url` is an org-authored literal, not a template.
**Rationale**: `email.yaml` shipped the literal `mailbox.overslash.com` while dev deployed `mailbox.dev.overslash.com`, and `infra/variables.tf` documented the coupling as a rule humans had to keep ("must match `servers[0]`"). It was not being kept, and the failure was doubly silent: a dev default instance sent mail through the *prod* gateway, and because `Config::platform_credential_for` matches the host for exact equality (D39), it was also denied the platform gateway key and sent a bare unauthenticated request. Neither existing knob reaches this — `OVERSLASH_SERVICE_BASE_OVERRIDES` is SSRF-gated to loopback by design and rewrites the URL *after* the host check, and D36's `instance_defaults.url` is per-org DB state that cannot fix a shipped global default. Both halves derive from `hosts[0]`, so the fix had to land before `extract_hosts`, i.e. at compile. **The prefix is the security boundary, and it does double duty.** It makes `DATABASE_URL`, `SECRETS_ENCRYPTION_KEY` and every other variable structurally unnameable — there is no syntax that reaches them — which is what allows the same mechanism to serve tenant-authored templates without becoming an environment-read primitive. The price, accepted explicitly: **every value under the prefix is readable by any tenant who can author a template** (write `${FOO}` into a `servers[].url`, read the resolved definition back), so it is a non-secret-by-declaration namespace like `service_instances.config` under D33 — hostnames and base URLs, never a credential. Gating the listing endpoint would have been theatre for exactly that reason. Deliberately *not* a per-org setting: this is a fact about the deployment, identical for every org on it, and an org that genuinely wants its own gateway already has `instance.url` and `instance_defaults.url` (D36). The null form exists because the first cut had only the two ends — a literal default or a hard failure — and self-hosted Metabase fits neither: `http://localhost:3033` is a plausible-looking wrong answer for every deployment that is not the dev harness (and silently pointing an instance at localhost is worse than asking), while failing the load would mean a deployment could not offer Metabase at all without a platform-level env var for a URL only the instance's owner knows. Null is not a fourth resolution tier, just an absent value handed to machinery that already existed for host-less templates. One pre-existing hazard is unchanged and worth naming: a tenant template naming `default_secret_name: overfwd_gateway_key` on the platform gateway host receives the platform key, exactly as it could by hardcoding that host before — template variables only save it from knowing the string.

## D45: The real-time stream is SSE over a durable `events` table fanned out by Postgres `LISTEN/NOTIFY`; events carry a frozen `audience` and are never org-broadcast

**Date**: 2026-07-31
**Decision**: `GET /v1/events/stream?topics=...` ships as **Server-Sent Events**, not WebSocket, with a fixed **30-second connection ceiling** and `Last-Event-ID` resume per SPEC.md §10. Every event is appended to a new **`events` table** whose `BIGSERIAL id` *is* the resume cursor (`WHERE id > $cursor`), alongside a stable `event_id` uuid for the wire envelope; an `AFTER INSERT` trigger `pg_notify`s **only that id** on the `overslash_events` channel, and each replica's `PgListener` task fetches the row and republishes it on a process-local `tokio::sync::broadcast`. **Writers never publish to the bus directly**, even same-replica: one delivery path means one ordering and one dedupe rule, and no divergence between the single-replica case under test and the multi-replica case deployed. Visibility is an `audience uuid[]` column **resolved once at emit time and frozen** — `chain(requester) ∪ chain(current_resolver)` for approvals (mirroring `mine`/`assigned`/`actionable`), `chain(owner) ∪ {actor}` for connections (**not** the owner's descendants), `chain(requested_by) ∪ chain(target)` for secret requests — with org admins bypassing it. The delivery predicate (`org AND topic AND (admin OR audience ∋ me)`) runs in SQL on the replay path and in memory on the live path. An identity-bound credential is **required** (403 otherwise), and there is **no `?token=` query-param auth mode**. A single `services::events::emit` seam appends to the log *and* calls the webhook dispatcher, replacing all 8 hand-rolled `tokio::spawn { dispatch(...) }` call sites and the 9 event-name string literals (now an `EventType` enum); `secret_request.created`/`.fulfilled` are added to both transports, with the provide token/URL deliberately excluded from the payload. The approval taxonomy carries **three** events for "someone must decide": `approval.created` (raised), `approval.bubbled` (moved between resolvers, `via: user|auto`), and the derived **`approval.pending`** (is it waiting on me *now*), which fires after creation and after every hand-up so an inbox consumer subscribes to one type rather than reconstructing the answer from two shapes. `pending` goes to the stream and to webhooks but **deliberately not to the audit log** — it restates a fact the other two already recorded, and a row per gated agent call would be pure volume; the audit log records facts, the stream delivers notifications. Ordered sequences go through `emit_all`, which appends the whole batch within one task before dispatching any webhook, because two independent `emit` calls would race and could deliver a derived signal ahead of its cause. Backpressure is handled by *ending* the connection on broadcast `Lagged` — the client resumes from its cursor and Postgres serves the backlog. Streams are capped per identity (4) and per org (64) per replica, refused with 429 + `Retry-After`. Design notes: [docs/design/event-stream.md](docs/design/event-stream.md).
**Rationale**: SSE over WebSocket because the traffic is strictly one-way server→client — there is no client→server message to justify a bidirectional protocol — and SSE survives the `vercel.json` rewrites and Vite dev proxy unchanged, gets `Last-Event-ID` resume from the browser for free, and already had an in-repo precedent (`routes/mcp/elicitation.rs`). The 30-second ceiling is not a limitation to work around but the mechanism that makes resume trustworthy: the reconnect path runs twice a minute in production instead of being exercised for the first time during an incident, and no proxy in the path gets to decide the timeout for us. `LISTEN/NOTIFY` over Redis pub/sub because resume demands a durable, replayable log **regardless** of transport — `webhook_deliveries` could not serve (per-subscription rows, none at all for an org without a webhook, no record of who could see what) — and once that table exists, Postgres is already a mandatory dependency on the write path while Redis is optional and deliberately fails open for rate limiting; making real-time delivery the first thing to hard-depend on Redis would have inverted that posture for no gain. Only the cursor crosses NOTIFY, so the 8 KB payload ceiling is irrelevant and no event body lands in `pg_stat_activity`. Audience is frozen at emit rather than re-derived per subscriber because the emitting path already holds the identity chains (one query, not one per subscriber) and because an event is a historical fact — re-deriving would let tomorrow's re-parenting change who could see what happened today. Audience is deliberately **narrower than `GET /v1/approvals`**, which today has no ACL gate and lets any identity list every pending approval in its org: that is a known gap, and a new fan-out surface is the wrong place to reproduce it. Connections exclude the owner's descendants because sub-agents *use* an owner-level connection via `on_behalf_of` but cannot list or manage it, and an event stream must never be wider than the read model it reflects. Query-param tokens were rejected despite `EventSource` being unable to set headers: a credential in a query string lands in access logs, proxy logs and `Referer`, and it is unnecessary because the dashboard reaches the API same-origin through proxies so a plain `EventSource` carries the `oss_session` cookie (the corollary — `SameSite=Lax` means a direct cross-origin `EventSource` would *not* — is why the stream must stay on the relative proxied path). The single `emit` seam is what makes SPEC §10's "same payload regardless of transport" structural rather than aspirational; the dashboard keeps its polling as a live fallback (ticks skipped while the stream is up) so an environment that breaks SSE degrades to exactly the behaviour that shipped before.

## D46: The widget SDK is one `@overslash/sdk` package — headless controllers plus custom elements, no framework bindings

**Date**: 2026-08-01
**Decision**: Third-party integration ships as **one** npm package at `sdk/`, with subpath exports (`.`, `./controllers`, `./elements`, `./node`, `./format`) rather than separate `core`/`ui` packages, and with **zero runtime dependencies**. The UI layer is **custom elements only** — there is no `@overslash/react`, no `@overslash/svelte`, and none is planned; a host that wants its own markup composes the headless controllers, which are framework-free state machines over a `Store<T>` (`getState`/`subscribe`/`dispose`) that is `useSyncExternalStore`'s contract verbatim and wraps into a Svelte `readable` in three lines. The controllers are ports of logic that exists today and is reachable only from Svelte: `lib/approvals/resolution.svelte.ts` (optimistic override, execution states, stream-driven refetch with the 30s×1.5s poll as fallback), `lib/approvals/format.ts` (206 lines of pure display helpers), `lib/oauth-connect.ts` (popup-and-poll). `POST /v1/actions/call` is always sent with `?wrap=true`, so `pending_approval` is a **return value** carrying everything a card renders rather than an exception to catch, and `waitForApproval` exists because the single-agent archetype's run loop cannot pause — an approval must block inside the tool's `execute()`.
**Rationale**: Two consumers with incompatible stacks (Svelte 5 + Tailwind; React 19 + plain JS + hand-rolled tokens) and a third that is whatever a vanilla page is. Framework bindings would mean versioning N packages against one wire protocol to save each host three lines of glue, and custom elements are the only UI form all three consume natively. One package rather than two because the halves version in lockstep and subpath exports already give the tree-shaking boundary splitting would buy — importing the client never pulls element code. Zero dependencies is a hard constraint, not taste: the first target consumer's contributing rules forbid adding dependencies without asking, and everything needed is reachable from `fetch`, WebCrypto and the DOM. Deliberately **not** migrating the dashboard onto the SDK in the same change: it is the best possible dogfood and the type names are shaped for it, but tying the SDK's first release to a dashboard-wide refactor would inflate the review surface of both. See [docs/design/widget-sdk.md](docs/design/widget-sdk.md).

## D47: SDK wire types are hand-written mirrors of the Rust DTOs; the SSE and webhook envelopes are one type

**Date**: 2026-08-01
**Decision**: The SDK's TypeScript types are **hand-written**, each carrying a `/** Mirrors <rust path> */` header, following the discipline `dashboard/src/lib/session.ts` and `types.ts` already use. Codegen is deferred, and explicitly blocked on a prerequisite: the gateway API has no OpenAPI description (the `services/` YAML documents *third-party* services, not Overslash), so generating a client means first annotating every route and DTO in `crates/overslash-api` with `utoipa`. The `EventEnvelope`/`EventType` pair is **shared between the SSE stream and webhooks** rather than duplicated per transport.
**Rationale**: A mirror that drifts is the obvious risk, and it is bounded by making the source explicit in every type's doc comment so a PR touching a Rust DTO can grep for its dependents. The alternative is not "generated types now" but "no SDK until the API is spec'd", which trades a maintained convention for an indefinite block. One envelope type because D45 made the two transports byte-identical on purpose — "the same event payload regardless of transport" — so expressing them as two types would encode a difference that does not exist and would let one drift from the other. It also means a consumer that already verifies webhooks needs no second parser for the stream.

## D48: Widget UI renders in open shadow DOM, themed only through `--overslash-*` custom properties and `::part`

**Date**: 2026-08-01
**Decision**: Every element renders into an **open shadow root** with a constructable stylesheet (a `<style>` clone as fallback). Branding is a documented `--overslash-*` custom-property contract; every structural node carries a `part` for overrides `::part()` can reach. There is **no light-DOM mode**. Registration is explicit via `defineOverslashElements({ prefix })` — importing the module is side-effect-free — so SSR does not break and two SDK versions can coexist on one page under different tag names. Copy is overridable per element via a `strings` property merged over English defaults; no i18n framework.
**Rationale**: The three target hosts carry three different global CSS regimes (Tailwind v4 with hardcoded dark hexes; hand-written tokens plus BEM with an explicit ban on hardcoded values; whatever a vanilla page is). Light-DOM markup inherits all of them and renders differently in each, which for a component whose job is *asking a human to authorise something* is not a cosmetic problem: a misrendered risk badge or a collapsed disclosure list changes what the person is agreeing to. Shadow DOM is the only way one stylesheet behaves identically everywhere. The standard objection is answered rather than dismissed — custom properties inherit *through* the boundary, so brand theming needs no piercing at all, and `part` covers the rest. A host that genuinely needs its own markup is not stuck: the headless controllers are the supported answer (D46), which is why a configurable light-DOM mode would only double the test matrix for a case already served.

## D49: SDK realtime is a fetch-based SSE parser over D45's stream, with polling as the fallback

**Date**: 2026-08-01
**Decision**: `SseEvents` parses `GET /v1/events/stream` out of a **`fetch` response body** (`ReadableStream` → decode → SSE line parsing) rather than using `EventSource`, behind an `EventsTransport` interface whose other implementation, `PollingEvents`, does bounded 1.5s polls. The client opens **one** connection and multiplexes subscribers over it, subscribing the union of their topics; poll ticks are skipped while the stream is live. Reconnect semantics follow the dashboard's: the routine 30s close is not an error, a ~8s grace window precedes reporting `down`, backoff is jittered 1s→30s, and `Retry-After` is honoured on 429. **The SDK owns the resume cursor**, updating it per frame as the server's replay ordering requires, so `stream.resync` is emitted only when reconnecting having never received a cursor. Events are treated as notifications: controllers refetch the resource an event names and never render from the payload.
**Rationale**: Two of the SDK's three auth modes are bearer modes, `EventSource` cannot set an `Authorization` header, and D45 deliberately refused a `?token=` query-param mode because a credential in a query string lands in access logs, proxy logs and `Referer`. That alone forces a hand-rolled parser; owning it then turns out to be strictly better. `EventSource` holds its cursor internally, so a fatal error destroys it and the reconnect starts blind — which is exactly why the dashboard must synthesise `stream.resync` and make every subscriber refetch. Holding the cursor ourselves makes reconnect after *any* failure precise, and reduces `resync` to the genuinely blind case. One multiplexed connection because the per-identity cap is 4 concurrent streams: a page with an approval list, two cards and a connect button would otherwise exhaust it against itself. Polling is retained rather than treated as legacy because it is what makes the SDK work in transport mode against a host proxy that does not forward streaming responses, and against a server older than D45.

## D50: Browser credentials are short-lived `aud=widget` tokens minted by the host backend; `X-Overslash-As` never reaches a browser

**Date**: 2026-08-01
**Decision**: A browser widget authenticates with a **stateless HS256 JWT, `aud=widget`**, minted at `POST /v1/widget-tokens` by a host backend holding an impersonate-scoped API key, with `X-Overslash-As` selecting (and provisioning) the end-user identity exactly as elsewhere. TTL is clamped to `[60, 3600]`, default 900s; claims are `sub`, `org`, `key_id`, `impersonated_by`, `caps`, `origins`. There is **no refresh endpoint** — the host re-mints from its own authenticated endpoint. A static `(method, path)` allowlist keyed on `caps` is enforced in the extractor, fail-closed, and reached through a dedicated `/widget/*` router subtree carrying `allow_credentials(false)` permissive CORS, leaving `cors_global` untouched; the real origin restriction is the `origins` claim, checked at authentication. With a widget token present, `GET /v1/approvals` defaults to `?scope=actionable` and refuses anything outside `mine|assigned|actionable`. Resolution authority is **unchanged** — `WriteAcl` plus `classify_approval_relationship` under the impersonated identity, self-approval still impossible without an MCP client binding. Rate limiting extends to `aud=widget`. `X-Overslash-As` is **not** added to any CORS allow-list. Until this ships, browsers use the SDK's host-proxy transport mode; the SDK's `{ token: () => … }` signature is stable either way.
**Rationale**: `osk_` keys are org-wide secrets and the `oss_session` cookie is `SameSite=Lax`, so today the only browser-safe path is a proxy every integrator must build first. A per-identity, capability-narrowed, 15-minute token is the smallest credential that removes that requirement, and it composes with the existing impersonation machinery instead of adding a parallel one — the mint path inherits the ACL cap (target ≤ minting identity), so a widget token can never exceed what the host key could already do directly. The `caps` allowlist *is* the XSS blast radius, and stating it that way is what keeps it honest: a stolen token can act on one identity's approvals for at most fifteen minutes and can read no secret, mint no key and impersonate nobody. The listing pin exists because `GET /v1/approvals` still has no ACL gate and any identity can enumerate its org's pending approvals; a new browser-facing credential is the wrong thing to hand that gap to, and D45 already refused to inherit it on the stream. No refresh endpoint because the host's session — not Overslash — is the authority on whether that user is still logged in, and a refresh endpoint would re-implement that check with less information. Accepting a *function* for the token in the SDK is what makes a 15-minute TTL invisible to the integrator. `X-Overslash-As` stays server-only because it is meaningful only alongside an `osk_` key, and a widget token names its identity in its own claims, leaving the browser nothing to assert.

## D51: Binary payloads leave via a capability URL minted per request (`deliver: "url"`), never inline over MCP

**Date**: 2026-08-04
**Decision**: `POST /v1/actions/call` takes `deliver: "inline" | "url"`, defaulting to `inline`, and the flag is exposed on the `overslash_call` / `overslash_read` MCP tool schemas. With `deliver: "url"` the caller gets a descriptor — `{download_url, expires_at, mime?, size_bytes?, filename?}` — and the bytes move out of band via `GET /v1/downloads/{token}`, which is **unauthenticated by design**: the token is 256 bits of randomness, stored only as a SHA-256 hash, short-lived (`DOWNLOAD_TOKEN_TTL_SECS`, default 900s), and **multi-use until expiry** so a resumed or retried transfer works. The row stores a credential-*free* `ActionRequest` plus an identity, never a resolved credential — a raw-HTTP call passing a credential in an inline header is rejected at mint, since that is the one shape whose headers are caller-supplied; both the credential and the identity's existence are re-checked at fetch time. HTTP-runtime actions need no declaration — the action *is* the download, so the token captures the resolved request. MCP-runtime actions declare `x-overslash-download` (jq filters over the tool result: `url` required, `mime`/`size`/`filename` optional, `auth: inherit|none`), and the resolved location **must be same-origin with the MCP server's own URL**. OAuth-authenticated services are refused (400) — their credential is minted live and `AuthHeader` has no `Serialize` precisely so it cannot be persisted. That gate reads `oauth_injected`, **not** `auth_header.is_some()`: a template declaring a query-param token injection resolves OAuth successfully but builds no header, so the header check would read as "no credential needed" and mint a token whose fetch carries nothing. Combining `deliver: "url"` with `filter` or `prefer_stream` is a 400, as is a raw-HTTP call passing a credential in an inline header. Mint writes `action.deferred` (HTTP runtime only — MCP already wrote `action.executed`), redemption writes `action.downloaded`. Inline `prefer_stream` stays exactly as it was; both paths now share one streaming-response builder.
**Rationale**: Overslash could return bytes exactly one way — `prefer_stream: true` — and that is a REST-DTO field the MCP dispatch fork returns before ever reaching. The buffered path MCP *did* reach ran every body through `String::from_utf8_lossy` and cropped strings at 200 chars in compact mode, so binary over MCP wasn't awkward, it was unreachable. It should stay unreachable: an agent that wants a 40 MB video does not want it in a context window, it wants it on disk — the motivating caller fetches with `curl -o` from a sandboxed VM that has network egress but deliberately holds none of the caller's credentials (`build_scrubbed_env`). A capability URL is the only representation of a file that satisfies both, and putting it at the Overslash level rather than in each upstream generalizes to services we don't control (Drive's `get_file_content` already compiles to `response_type: "binary"`, which nothing read until now) and keeps the permission check and audit trail where they already live. Deferring moves *byte delivery* only — the action call is fully gated and audited before a token exists, exactly the presigned-URL model. Credentials are re-resolved rather than captured because storing a resolved `Authorization` would put a second copy of a live secret at rest outside the vault with a lifetime we don't control; re-resolving means a rotated secret is picked up and a revoked one fails closed. Multi-use rather than single-use because the motivating payload is large: single-use turns every dropped connection into an unrecoverable failure, and exposure is bounded by the TTL instead, with `use_count` making a leaked URL visible. Same-origin is the load-bearing constraint on the MCP path: the URL comes from the MCP server's own response and the fetch attaches that instance's credential, so without it a hostile or compromised server could name `169.254.169.254` and be handed the bearer. It costs nothing, because "the bytes are on the host you just talked to" is the actual contract.

## D52: Invitations are accepted in-app by linking the pending identity to the caller's `users` row, keyed on their IdP-verified email

**Date**: 2026-08-05
**Decision**: `GET /v1/account/invitations` (plus `.../{id}/accept` and `.../{id}/decline`) answers "which orgs invited *me*", the invitee-side mirror of the admin-only, org-scoped `/v1/org-invites`. The lookup key is the caller's **`users.email`** — refreshed from IdP userinfo on every sign-in — never `claims.email` or `identities.email`, both of which an org admin writes. A row qualifies only if it is a `kind='user'` identity with that email, unarchived, `external_id IS NULL` **and** `user_id IS NULL`, and not `provisioned_by = 'impersonation'`; personal orgs and orgs the caller already belongs to are dropped. Accepting runs the same `adopt_pending_identity` primitive as the SSO callback (link `user_id`, bootstrap Everyone/Myself, `membership::create` with the invite's role, welcome email, `identity.adopted` audit) but does **not** set `external_id` — there is no IdP subject for that org to record — so "pending" everywhere now means `external_id IS NULL AND user_id IS NULL`. Accepting is refused (`403 org_requires_idp_signin`) for an org with `allow_overslash_managed_signin = false`; the invitation still lists, with a link to that org's own sign-in. Declining archives the identity with `archived_reason = 'invite_declined'`. Every wrong-owner request answers 404, never 403. The list is embedded in `/auth/me/identity` so the sidebar section costs no extra round trip.
**Rationale**: An invite has been a pre-created identity since migration 103, and the only thing that ever told the invitee it existed was an email linking to `<slug>.<apex>/`. A user already signed in on the apex had no way to discover or act on it, and the "accept" they were being sent to do was a side effect of an SSO callback rather than an operation anyone could name. The email match is the entire authorization story here, which is why it has to read the one email column the *IdP* asserts: `identities.email` is the field an admin fills in to create the invite, so trusting it would let any admin mint an invitation for an address and then read back which other orgs had invited it. `user_id IS NULL` joins the pending predicate because in-app accept is the first path that produces a member with no `external_id` — without it an accepted member would show as "pending" on the Members page forever and stay revocable from the admin's Invites card. The managed-sign-in gate exists because an org that runs its own IdP has made an admission decision that an apex Overslash session was never part of; surfacing the invitation but sending them to that IdP keeps discovery useful without spending the org's trust boundary. Decline archives rather than deletes because a pending member can already own an agent subtree — `delete_identity_leaf` would refuse — and archiving frees the address for a fresh invite while leaving the audit trail intact.

## D53: Auto-approval is a second ceiling on the `read < write < admin` ladder, bounded by the access ceiling

**Date**: 2026-08-07
**Decision**: `group_grants.auto_approve_reads` (boolean) becomes `group_grants.auto_approve_level` — `none | read | write | admin` — carrying the same semantics `access_level` already has: a grant auto-approves exactly the risks its level permits, via the same `AccessLevel::permits_risk`. The two columns are independent settings on one ladder, with one invariant: **`auto_approve_level <= access_level`**, enforced at the API and by a DB `CHECK`. Raising auto-approval above the ceiling is a `400`; *lowering* the ceiling under an existing level silently clamps the level down, because that direction only ever reduces privilege and a two-call downgrade is a worse contract than a one-call one. The risk-shaped guard in `check_group_ceiling` (`!risk.is_mutating() && …`) is gone — the level decides, and `GroupCeilingResult::WithinCeiling { read_bypass }` is now `{ auto_approved }`. Defaults are unchanged: the Myself auto-grant stays `access_level = admin` with `auto_approve_level = read`, and the backfill maps `auto_approve_reads = true` to exactly `'read'`. `auto_approve_reads` survives one release as a deprecated API alias (`true` ⇒ `"read"`, response value derived as `level != "none"`) and the DB column is kept in sync by the writers until it is dropped. **D42's deny-sweep is widened**: `denied_anywhere` now runs for any *mutating* call that took the auto-approve bypass, not only SQL-classified ones. Read bypasses keep their zero-extra-query fast path.
**Rationale**: The boolean pinned auto-approval to reads, so the only policy an org could express was "reads are free, everything else waits for a human". That is the right default and a bad ceiling: a team that trusts its agents to write to a scratch Jira project or an internal Slack channel had no way to say so, and the workaround — hand the identity blanket permission rules — is strictly worse, because it is invisible to the group view and outlives the grant. Putting auto-approval on the ladder `access_level` already uses means there is no new policy vocabulary to learn or implement: one enum, one `permits_risk`, and the UI is a second dropdown next to the first. Bounding it by the access ceiling is what keeps the pair honest — auto-approval is permission to skip the *human*, never permission to exceed what the group was granted, so the ceiling stays the single answer to "what is the worst this group can do". D42 recorded that "a write-classified call never takes the bypass, so `table_mut=` coverage is always walked", and a write-level grant breaks that assumption by design: **table-key allow coverage is now bypassable for writes**, but only where an admin explicitly opted a grant into it and never above the ceiling. What is *not* negotiable is deny. D42 shipped the sweep only for SQL-classified calls, which was defensible while the bypass could only free reads; once it can free mutations, a deny rule is frequently the only thing standing between an agent and a carve-out an admin made on purpose, so every auto-approved mutation now pays for the sweep. Reads were deliberately left on the old path — that behaviour predates this change, and making a previously-inert deny suddenly bind would break working agents in the name of consistency.

## D54: Container images build with `docker buildx` + cargo-chef, not Kaniko

**Date**: 2026-08-11
**Decision**: All three Cloud Build triggers (`infra/modules/cloud-build`, `-shortener`, `-metrics-exporter`) build with `docker buildx` under the `docker-container` driver, exporting and importing layer cache via `--cache-to`/`--cache-from type=registry,mode=max` against a `<image>/cache:buildcache` ref in the same Artifact Registry repository. The dependency layer the cache exists to preserve is produced by **cargo-chef**: `cargo chef prepare` distills the workspace into a `recipe.json` of dependencies only, `cargo chef cook` compiles it, and the real `cargo build` follows a plain `COPY . .`. The hand-maintained per-crate `COPY crates/*/Cargo.toml` + `echo "fn main(){}"` stub scaffold, and the `find crates/ -name "*.rs" -exec touch {} +` that existed to defeat it, are gone from all three Dockerfiles. Build contexts are now whole-repo, so `.dockerignore` — not a `COPY` allow-list — decides what reaches the image.
**Rationale**: Kaniko was archived upstream in June 2025 ("no longer developed or maintained"), so the deploy path depended on an unmaintained builder; the exit-137 OOM on the Rust dependency layer was a symptom, and `--compressed-caching=false` was a workaround for one instance of it rather than a fix. BuildKit diffs layers incrementally instead of snapshotting the whole filesystem, which removes that failure class outright. Cache mounts (`RUN --mount=type=cache`) would remove the multi-GB layer entirely, but their contents are **not** exported by the registry cache exporter, and Cloud Build runs every build on a fresh VM — a cache mount there is always cold. A cargo-chef `cook` layer is the form of dependency cache that actually survives the trip through a registry, which is why the layer stays a layer. The stub scaffold's cost was measurable in git history: `aad3d8d4`, `9b3b059c`, `c19ccc96`, `eb06cb78` are four separate "copy X manifest" fixes, one per new crate, each discovered by a broken build. cargo-chef derives that list from the workspace, so adding a crate needs no Dockerfile edit.

## D55: Display-param resolvers work on MCP actions, and may canonicalize the permission key

**Date**: 2026-08-11
**Decision**: `x-overslash-resolve` becomes runtime-agnostic and gains a second output. The **target** is either `get:` (HTTP — an authenticated follow-up GET against the same service host, unchanged) or `tool:` + `args:` (MCP — a `tools/call` against the same instance, sharing `mcp_caller::build_client` with real dispatch so auth, SSRF pinning and host overrides cannot drift). The named tool must be `risk: read`, enforced at template compile. The **projection** is either `pick:` (one dot-path) or `display:` (a `{dot.path}` template reusing the description grammar, so `{name}[ ({phone})]` drops the bracketed segment when the phone is unknown; an empty string counts as absent, and an unresolved placeholder collapses to empty rather than leaking a literal `{name}`). MCP resolvers project over the tool's `structuredContent`, falling back to the first text block parsed as JSON. The MCP disclosure projection gains `resolved`, making `.resolved.recipient // .arguments.recipient` read exactly like the HTTP shape's `.resolved.fileId // .params.fileId`. Optional `scope:` names a dot-path whose value replaces the raw argument **when deriving permission keys only** — the outgoing request always carries the caller's literal arguments. Resolution stays best-effort: 3s timeout, failures dropped silently. Parsing is now lenient — a half-declared resolver lands on the action and is reported by `template_validation` rather than being silently dropped. Parameter-level aliases (`resolve:`, `aliases:`, `instance-config:`, …) now normalize inside an MCP tool's `input_schema.properties`, which they never did before. `POST /v1/actions/validate` deliberately does **not** canonicalize: it runs on `resolve_action_metadata`, which is documented as cheap — no OAuth, no upstream calls — and resolution is an authenticated round trip. The dry run therefore previews keys built from the caller's raw argument, which is the stricter reading (an address `/call` would collapse onto a granted canonical key previews as uncovered, never the reverse). If that divergence becomes load-bearing, the fix is to run resolvers in `validate` and accept that it starts touching the provider.
**Rationale**: The motivating approval read `Send WhatsApp message "Hola Sonia, …" to 239135323373760@lid`. A reviewer cannot approve that, and a privacy LID's digits are *not* a phone number, so no local formatting could have fixed it — the mapping has to be looked up, and the only thing that can look it up is the container holding the WhatsApp session. Resolvers already existed for exactly this job and were HTTP-only for an incidental reason: they were written as a GET against a URL, and MCP actions have no URL. Making the target polymorphic was strictly smaller than inventing a second mechanism, and it means every MCP template — telegram, slack, hubspot — inherits the capability. The read-only constraint on `tool:` is the one hard rule: a resolver runs *before* a human has seen the approval, so a resolver pointed at a write would make the act of reviewing a call perform a mutation. Resolution must be gateway-side and derived from the real argument, never a label the agent supplies, or an approval could read "to Sonia" while the message went elsewhere. `scope:` exists because the readability problem had a permissions twin: the same human is reachable at several opaque addresses, each minting its own key, so "Allow & Remember" for Sonia only remembered *one way of addressing* Sonia, and the rules list was a wall of JIDs. Canonicalizing onto the phone number makes a grant both stable across addresses and legible. It is safe in the direction that matters — a failed lookup yields no canonical value, so the key stays the raw argument, matches no grant, and gates — and it spends no new trust, since the value comes from the same upstream the call is about to act on. It is nonetheless a live behaviour change: a grant already stored against a raw `@lid` stops matching and re-prompts once. Parse leniency changed because the old silent drop turned a typo'd `resolve:` block into a no-op whose only symptom was an approval still quoting a raw ID — the linter should name that, not swallow it. The alias walk was the same class of bug found while wiring this: `resolve:` sat next to an already-unprefixed `risk:` in `services/whatsapp.yaml` and did nothing, because alias normalization stopped at the tool object and never descended into `input_schema`.
## D56: Call timeouts resolve through a five-layer cascade clamped by two ceilings; streaming bounds time-to-first-byte, not the transfer

**Date**: 2026-08-11
**Decision**: `POST /v1/actions/call` takes `timeout_ms`, and how long a call may wait upstream resolves most-specific-first through **per-call → action template (`x-overslash-timeout_ms`) → service template (`info.x-overslash-default_timeout_ms`) → org (`orgs.call_timeout_ms`) → deployment (`CALL_TIMEOUT_MS`, default 30000)**. The result is clamped by `orgs.max_call_timeout_ms` and `CALL_TIMEOUT_MAX_MS` (default 110000); caps combine by *tightest wins* rather than by specificity. A caller-supplied value above the effective maximum is a **400** naming the ceiling, while a template or org *default* above it is silently clamped with a warning. Exceeding the budget is a **504** carrying `timeout_source` — the layer that set it — plus an `action.executed` audit row with `detail.error.kind = "timeout"`. Resolution happens once, before the MCP/HTTP/deferred forks, in a pure `services::call_timeout::resolve`; a gated call stores its resolved budget on the approval, and replay re-clamps that stored number against the org's *current* maximum rather than re-running the cascade. Org policy is two nullable columns, not one, exposed on the existing `/v1/orgs/{id}/execution-settings`. `EXECUTION_REPLAY_TIMEOUT_SECS` stops being a latency policy and becomes a derived outer wall (`Config::replay_wall_clock`), always at least `CALL_TIMEOUT_MAX_MS` plus slack, from which the orphan-reaper grace is also derived. **Streaming is bounded differently**: for `prefer_stream: true` the resolved timeout bounds only time-to-first-byte, and the transfer is bounded by a per-chunk idle timeout (`CALL_STREAM_IDLE_TIMEOUT_MS`). `ActionPatch` gains `timeout_ms` — the first non-restrictive field on that struct.

**Rationale**: Before this there was one global env var, it applied only to approval replays, and the inline call path had no timeout in code at all — it simply rode until Cloud Run cut the connection at 120s, handing the caller an opaque proxy 504 with no audit row. An org whose Metabase aggregations legitimately take 90s could not say so, and an org that wanted to bound its agents could not say that either. Five layers rather than a flag because the knowledge is genuinely distributed: the deployment knows its own request cap, the org knows its tolerance, the template author knows the upstream, and only the caller knows this particular query. Two org columns rather than one because a single column cannot be both a default and a ceiling — as a default only, a per-call override escapes governance; as a ceiling only, every call runs at the maximum with no sane middle. Templates set defaults and never caps, because a template encodes knowledge while a cap is policy, and user- and org-authored templates exist: letting a template author set a cap would let them bind their own admin. The 400-vs-clamp asymmetry is the same argument from the other side — the caller is present and can act on an error, whereas a mistyped template value that 400s every call in the org is strictly worse than one that quietly runs at the ceiling. `timeout_source` on the 504 is the field that pays for itself: without it, "why did this time out at 30s when the org default is 90s" is an afternoon of grepping. Exceeding `CALL_TIMEOUT_MAX_MS` errors rather than silently promoting the call to a background execution, because auto-promotion would change the *response shape* based on a number in a template the caller never saw — exactly the class of surprise that breaks agents.

The streaming split is the load-bearing implementation decision. `reqwest`'s `RequestBuilder::timeout` is a **total** deadline that covers the response body, and `read_timeout` is `ClientBuilder`-only in 0.13 — so the obvious implementation (one `.timeout()` on both paths) would abort a streamed transfer mid-body, *after* `write_stream_audit` had already recorded a 200 and after axum flushed the headers. The client would receive a silently truncated body while the audit trail claimed success, and a legitimate 900MB export would fail at exactly the resolved timeout no matter how healthy the transfer was. Splitting the phases — a `tokio` timeout on the header phase, a per-chunk idle guard on the body — is what makes the resolved timeout mean the same thing to a caller on both paths ("how long before you give up on this upstream") without redefining slowness as failure. Replay re-clamps rather than re-resolving because the stored payload has the request but not the action key the template rungs were read from; re-clamping is the half that can be done, and it is the half that matters, since it is what stops a stale approval from outranking a tightened org policy. `ActionPatch::timeout_ms` breaks that struct's "restrictive, monotonic" contract knowingly: a timeout grants no capability the caller did not already have, and both maxima still clamp it — the alternative was forcing an org with a slow self-hosted upstream to re-author the entire action through `Extensions` to move one number.

## D57: An oversized response returns the 502 with a capability URL already minted, and action parameter contracts reach the model

**Date**: 2026-08-11
**Decision**: When a buffered HTTP call exceeds `max_response_body_bytes`, the gateway mints a `deliver: "url"` capability token for the *same* request at the point of failure and returns it on the 502 as `download_url` + `expires_at`, with a hint that leads with narrowing the call. It stays a **502** — nothing silently succeeds, and a caller that ignores the new fields sees exactly the pre-D57 error. Minting is **best-effort**: the existing refusals (OAuth-injected services, raw HTTP carrying inline credential headers) and any other mint failure collapse to `None`, and the hint falls back to the transport-aware wording introduced alongside this (`deliver: "url"`, plus `prefer_stream: true` only where it is reachable). The hint therefore has three forms under one rule: never name a recovery the caller cannot use — a minted URL supersedes both flags, since telling a caller to retry with `deliver: "url"` when its URL is already in the body is the same wasted round trip that naming `prefer_stream` over MCP was. The `action.deferred` audit row records `cause: "response_too_large"` to distinguish it from a caller that asked. Separately, `SearchResult` action rows now carry `params` — a lean model-facing projection of the action's parameter contract (name, type, required, description clamped to 160 chars, enum, default), required-first then alphabetical, with `instance-config` params excluded. And `filter` is declared on the `overslash_call` / `overslash_read` MCP tool schemas and forwarded by the dispatcher, lifting a bare jq string into the wire's `{lang, expr}`; it now also applies on the MCP-runtime and platform-runtime forks, which previously accepted it, validated its syntax, and silently ignored it.

**Rationale**: An agent asked "which Metabase cards are popular", found only `run_card` (one card by id) and `list_cards` (every card in the instance), picked the latter, pulled 31 MB / 2,033 cards, blew the cap, and had to re-issue with `deliver: "url"`. Three things had to be true at once for that to happen, and the fix addresses all three.

The obvious remedy — "it should have passed a `filter`" — does not work and is not a documentation gap. The cap is enforced *inside* `http_caller::call` while the body is still arriving; the filter is post-processing of an already-buffered body, so on an oversized response it never runs. That ordering is deliberate (a filter cannot un-send bytes the upstream already sent) and is pinned by `test_filter_does_not_rescue_oversized_upstream`. Given that, the only two available fixes are making the retry cheaper and making the narrower call visible in the first place.

Minting into the error is nearly free because `deliver: "url"` on the HTTP runtime **never needs the body**: it persists the credential-free `ActionRequest` and replays it at redemption. So the failure already holds everything the retry needs, and asking the caller to construct that second round trip was asking it to re-derive what we knew. Keeping the 502 rather than transparently returning a 200-with-URL is the load-bearing half: an agent that ignores an unfamiliar field must not read a failed call as a successful one with no data.

Parameter contracts reaching the model is the actual root cause. `ServiceAction.description` was documented as "the only string about an action that ever reaches the model — parameter descriptions, defaults, and response schemas do not", which made every declared paging parameter folklore: it existed, it worked, and nothing advertised it. A template author's only recourse was to restate the whole contract in prose. The projection is deliberately not `ActionParam` itself — `resolve`, `sql_field`, `sql_database` and `instance_config` are gateway plumbing the caller neither supplies nor benefits from seeing, and `instance-config` params are actively harmful to list, since an org admin pins them and a caller supplying one can only get it wrong. Ordering is explicit because `params` is a `HashMap`: without a sort, byte-identical requests return differently-ordered JSON.

`filter` over MCP closes the last gap. Both tool schemas are `additionalProperties: false`, so an undeclared property is a hard reject — an MCP agent could not pass a filter at all, which is to say the one server-side lever for shrinking a response before it enters a context was reachable only from the CLI, the SDK and raw HTTP. Applying it on the other two runtimes is a correctness fix rather than a feature: they have no upstream size cap to dodge, but they have the same context budget, and a caller could not distinguish a filter that matched nothing from one that never ran.

## D58: The Live Map rides a new `activity` topic whose per-call events are emitted only behind a flag, from the one wrapper that already classifies the outcome

**Date**: 2026-08-11
**Decision**: `GET /v1/events/stream` gains a fourth topic, `activity`, carrying `action.called` and `action.completed`. Both are emitted from **`routes/actions/mod.rs::call_action`** — the wrapper that already brackets the request for `overslash_action_executions_total` — and not from the four terminal sites inside `call_action_impl` (MCP ok, MCP transport error, HTTP ok, HTTP transport error). The pair shares a `call_id` minted in that wrapper, and `action.completed` reports the wrapper's existing `status_label` (`called | denied | rejected | failed | upstream_error`) plus `duration_ms`. Emission is gated on `config.live_map_enabled` (`OVERSLASH_LIVE_MAP`), reported to clients as `live_map` on `GET /v1/version`, and set on dev and in `scripts/e2e-up.sh` — never in production. The topic string is **always** valid regardless of the flag. Audience is `chain(actor)` (`audience::for_action`), resolved once before the call and reused by both events; org admins bypass it through the existing delivery predicate. The dashboard subscribes to `approvals,activity` unconditionally and renders the graph at `/map`, whose nav item is gated on `live_map`.
**Rationale**: The Live Map's subject is per-call traffic, and the stream had no per-call event: its three topics fire when something is *gated* or *reconfigured*, and the overwhelming majority of calls are auto-allowed, so a map built on them would have been almost entirely still. Adding the events was therefore the feature, not an optimisation of it. Gating them is not caution about correctness but about volume: these are the first events on the gateway's hottest path, one durable `events` row each, where every other event in the system is emitted per operator action. The flag is what lets that cost be opt-in per deployment rather than a tax on every org, and `/v1/version` reports it for the same reason `sql_policy` is reported there — a page that renders a permanently motionless graph is worse than a page that is honestly absent. Emission sits in the metrics wrapper because that function already owns the outcome taxonomy, including the `UpstreamErrored` marker that distinguishes an upstream's 500 riding behind an outer 200 from Overslash's own failure; duplicating those rules across four call sites to gain a slightly earlier `service` resolution would have been a bad trade, and the wrapper's `service`/`action` strings are what the map matches against `listServices()` anyway. The pair is deliberately **not** ordered: the two events bracket the upstream call, so `emit_all` — which exists precisely to keep a derived event behind its cause — cannot span them, and each `emit` spawns its own task. That is why `call_id` is minted rather than inferred from arrival order, and why the client treats a `completed` for an unknown `call_id` as a packet already on its return leg instead of dropping the call. The audience is the actor's chain and nothing wider: an org-wide fan-out of every call would be the broadest disclosure surface in the system, whereas the chain rule discloses exactly what `GET /v1/audit` already shows the same caller, and lets a parent keep watching its sub-agents. Admins bypassing it is what makes one stream serve both an operator's org-wide view and a member's personal one, with no second ACL.

## D59: The audit log records the actor's name as of write time, and searches what it recorded

**Date**: 2026-08-11
**Decision**: `audit_log` gains `actor_name` and `owner_user_name` (migration 110), filled at INSERT time by a CTE inside the existing statement — no second round trip on a path that runs at every mutation. `owner_user_name` is the actor's `owner_id` — which is a *flattened pointer to the root user*, maintained for every descendant on create and on move, so a sub_agent at any depth already resolves to the human at the top — falling back to the actor's own name when the actor is a user, whose `owner_id` is NULL. This is exactly what the join it replaces computed, at every depth: **`user =` and `user ~` semantics are unchanged**. Both columns are NULL when there is no actor. The dashboard's free-text `q`, `identity ~` and `user ~` all match these columns, and the table renders the recorded name — marked with a dotted underline when it differs from the identity's current name, with the live name in the hover and a "Recorded as" line in the expanded pane. The SPIFFE `identity_path` stays live and id-keyed, so the current chain is always one hover away, and `identity = <name>` still resolves through an id, so filtering by actor is unaffected by renames. `query_filtered` consequently drops **both** `identities` joins; kind and ownership move into `EXISTS` subqueries that cost nothing when those filters are absent. The free-text clause keeps its exact `NOT EXISTS` semantics and gains one redundant, indexable pruning conjunct over the longest term of three characters or more, which a `pg_trgm` GIN index on `action || description || actor_name` serves.
**Rationale**: A stale name is not the compromise here, it is the point: an audit row should say who acted under the name they had when they acted, and reading the name through a live join silently rewrites history every time someone is renamed. The deleted-identity case makes it sharper — `identity_id` is `ON DELETE SET NULL`, so before this change deleting an identity erased the actor from every row it had ever written, and the log lost exactly the name a reader needs most. What forced the change now was performance, and the two motivations point the same way. `q` matched a **joined** column, and a free-text predicate spanning two tables forecloses every indexing strategy on `audit_log`: the planner will not use a trigram index for an OR that reaches outside the table, so a term matching nothing walked the org's entire history — 2487 ms on 400k rows, of which ~1.7 s was the per-row identity join alone. Materializing the name is what makes the predicate local, and therefore indexable at all. The pruning conjunct exists because #533's multi-term form is a correlated `NOT EXISTS` over `unnest`, which is an anti-join subplan the planner cannot turn into an index scan; a single-parameter conjunct gives it something to prune with, and it is sound because it is a *superset* of the real predicate — a row matching any one column matches the concatenation, so it can only admit extra rows, which the `NOT EXISTS` then rejects. Search and display had to move together: if search matched the historical name while the table showed the current one, an operator searching for what is on their screen would get nothing, which is the worst of both semantics. The divergence that remains is deliberate and narrow — the User column keeps labelling by live email, because it shows an *email*, not a display name, and resolves it by id.


## D60: An instance that was never configured fails as `needs_authentication` naming the fields, not as an unauthenticated request

**Date**: 2026-08-11
**Decision**: When credential resolution produces nothing at all — no OAuth header, no secret — and the template declares a credential the instance never supplied, `POST /v1/actions/call` returns **401 `needs_authentication`** instead of dialling upstream. `resolve_instance_auth`'s `instance_secret_missing` boolean becomes a `MissingCredentials { slots, config }` carried out on `ResolvedAuth`, so the gate names the exact fields rather than re-deriving the resolution chain. The existing `needs_authentication` code is reused rather than a new one minted, gaining two fields: `missing_credentials` (slot keys and `required` config vars that resolved to nothing) and `hint_url` (a dashboard deep-link — `/services/{id}?tab=credentials` with an instance, `/services/new?template={key}` without one). The secret-backed shape carries **no** `auth_url`/`provider`: there is no consent page to send anyone to. Both fields render in the headless branch too, minus the link. The gate runs in **both** call shapes; the OAuth gate's absence from the verb shape is a separate, pre-existing gap and stays. It does **not** fire when the template requires no credential the instance is missing — `deepwiki`, the `platform` runtime, and an optional-only credential such as `email`'s gateway key on a keyless overfwd all still send exactly as before. Affected shipped templates: `email`, `stripe`, `resend`, `metabase`, `test_email`, plus every org/user template declaring a secret scheme. MCP-bearer templates (`telegram`, `whatsapp`) are untouched — they fork earlier and already error rather than sending unauthenticated. The gate lives in `resolve_request`, so like its OAuth twin it runs **before** the permission gate: an unconfigured instance answers `needs_authentication` even where the caller would have been denied or sent to approval.
**Rationale**: `resolve_instance_auth` has refused to emit a *partial* credential set since it was written, and D38 extended that refusal to a `required` config var with no value — correct, and covered by tests: nothing truncated is ever sent. What it did afterwards was the defect. It fell through to `resolve_service_auth`, which knows only OAuth and the env-backed OAuth *client* cascade, so for a secret-backed template it resolved nothing and the call went out with an empty credential set. The gateway therefore knew precisely what was wrong — "this instance has no `mailbox_user`" — and told the caller something else: whatever a real overfwd says to an unauthenticated request. That is the same failure shape as the Metabase field report, and it was already an internal contradiction, since `derive_credentials_status` classifies exactly this state as `NeedsAuthentication` for the dashboard badge while the call path shipped the request anyway. Reusing the `needs_authentication` code is what makes the fix free for consumers: it is already on the MCP relay's typed-error whitelist, already mirrored by `?wrap=true`, and already the thing every agent branches on — a new code would have needed all three taught about it, and would have split one question ("what do I have to do before this call works?") across two vocabularies. The cost is that `auth_url` is no longer implied by the code, which is why the variant's doc comment now states it and why the field list ships alongside: an agent that reads `missing_credentials` can tell the user what to fill in even where no link exists, which is exactly the headless case. Deriving the missing keys from the resolver rather than recomputing them in the envelope builder is deliberate — the chain (per-slot binding → legacy scalar `secret_name` → org default → platform credential, plus the config pass) is intricate enough that a second implementation would drift, and the drift would be silent: a wrong field name in an error message, not a failing call. The builder keeps a derivation only for the no-instance path, where there is no resolution attempt to report. The behaviour change D38 deferred is now taken deliberately, and it is genuinely a change: any secret-backed template that previously produced an upstream 401 now produces ours. That is the point — the upstream 401 was never actionable, and this one names the field and links the form. Running before the permission gate is inherited rather than chosen: the OAuth gate has sat there since it was written, so "deny beats every allow mechanism" (D42) has always been conditional on credentials resolving at all, and this changes the size of that pre-existing window rather than opening a new one. It leaks nothing the caller did not already supply — they named the service and resolved the instance to get here, and `hint_url` is a dashboard path, strictly less than the minted flow URL the OAuth shape already hands back on the same path. Two D53 tests had to bind a credential they had left unset as scaffolding, which is the honest signal of the change: an unconfigured instance now stops earlier than it used to.

## D61: A truncated compact result is stored and re-fetchable behind a capability URL

**Date**: 2026-08-11
**Decision**: When a `verbose: false` render actually truncates, the full `ActionResult` is serialized, encrypted with the existing AES-256-GCM keyring, and written to a new `call_results` table; a `download_tokens` row is minted pointing at it, and the descriptor is stamped into the same envelope as the cropped body under `_full_result: {download_url, expires_at}`. Redemption reuses `GET /v1/downloads/{token}` unchanged — per-IP throttle, hash claim, identity re-check, `action.downloaded` audit — with one branch: a row carrying `call_result_id` serves stored bytes instead of replaying `request`. Migration 111 makes `download_tokens.request` nullable and adds `CHECK (num_nonnulls(request, call_result_id) = 1)`, so a token names **exactly one** source of bytes. Storage is bounded by `CALL_RESULT_MAX_BYTES` (default 1 MB, `0` disables) and shares `DOWNLOAD_TOKEN_TTL_SECS` (900s) — one TTL knob, one sweeper step (`call_result_expiry`), with the token's expiry clamped to the result's so the stated `expires_at` is true rather than optimistic. Storing is **best-effort**: every failure path returns `None` and the envelope falls back to the pre-D57 hint, because the call it belongs to has already succeeded. The `_hint` gains a second form. D57 already rewrote the cropped-response hint to lead with narrowing (paging params, then a `filter`); the stored variant keeps that ordering and only swaps the fallback, since a stored copy is free where `verbose=true` pays for the upstream call again. Nothing is stored for verbose renders, for compact renders that fit, or for `deliver: "url"` calls.

**Rationale**: This is the *rendering* twin of D57. D57 covers the call that never produced a usable body — the transport cap tripped, nothing was buffered, so the only thing that can be handed back is a token to replay the request. This covers the opposite case: the call succeeded, the body was buffered, and it was the 8 KB compact render that dropped it. The motivating field report has an agent driving Metabase receive 10 of 254 rows inline, then **re-run a 30-second query purely to change the delivery mode of bytes the gateway had in hand and threw away**. The hint it was handed made this worse rather than better: "pass verbose=true to see the full response" reads as a cheap toggle, but `verbose` is a field on a *new* `CallRequest`, so acting on it pays for the upstream call a second time — and `deliver: "url"` on the HTTP runtime mints *before* calling (D51), so that is a third. Every documented recovery from a crop was a re-execution. The store is deliberately narrow: only a caller who asked for compact *and* got less than the upstream sent has anything to re-fetch, so a verbose dashboard call and an under-budget compact call both write nothing — storing unconditionally would make Overslash a full copy of every upstream response at rest, which the audit path already refused (org-gated, 64 KB cap, off by default). Over the size cap we store nothing and say why, because a silently shortened "full result" is strictly worse than none: the agent would fetch it and believe it complete.

A separate table rather than a body column on `download_tokens` because that module's whole documented invariant is "the row keeps a credential-free `ActionRequest` and replays it"; a row that replays nothing would leave `request`, `credential_ref` and `service_instance_id` as dead weight and make redemption bimodal in the one dimension its docs are about. Not `executions` either — `approval_id` is `NOT NULL` with an FK to `approvals`, and `services::inbox` defines `result_unread` off that table, so every inline call would become a permanent unread item in `get_events`. The blob is encrypted because **we do not choose the contents**: an upstream is free to return a refresh token in a JSON field, and the response headers — `Set-Cookie`, an echoed `Authorization` — are serialized into the same blob, so plaintext bodies would re-open from the response side exactly the hole D51 closed from the request side. The consequence is accepted knowingly: the column is `BYTEA`, so nothing can query *inside* a stored result, and audit capture remains the consented path for that. `call_results.body_ciphertext` joins `key_rotation::TARGETS` in the same change, since an encrypted column that never rotates looks safe while silently pinning one key forever.

Access is the bearer-token model rather than a new authenticated re-read endpoint, and that choice is what keeps this small: no new REST surface, no new MCP action, and therefore no question about whether an agent re-reading its own output should raise an approval. It also closes a gap D51 left and D57 had to work around — `deliver: "url"` refuses OAuth-authenticated services because a deferred fetch cannot re-mint an OAuth bearer, which is one of the refusals D57's best-effort mint collapses to `None` on. A result-backed token **dials nothing**, so on this path every Gmail / Drive / Calendar truncated result gains file delivery it has never had. `content-length` is dropped from the forwarded-header allowlist on this path alone: the stored body went through `String::from_utf8_lossy`, so the upstream's byte count can disagree with what is actually written, and a mismatched length is a framing error rather than a cosmetic one. The upstream status is likewise not replayed onto the redemption response — the stored body may be a 404 the agent asked to look at again, and a `curl` seeing 404 would write nothing and report a failure that did not happen.

This does **not** fix the truncation itself. Compaction is still uniform across the JSON tree, so a Metabase-shaped payload still spends its 8 KB budget on `cols` and `results_metadata` before reaching `rows`, and the agent still sees 10 of 254 inline. What changed is the price of the recovery: a `curl` instead of a re-query. D57's two levers — advertised paging params and a reachable `filter` — attack the same problem from the request side, and between them the cropped-response hint can now name three genuinely cheaper moves. Making truncation itself priority-aware is tracked in TODO.md §3.
## D62: Async calls are a leased row the caller polls, not a detached task, and `execution: "async"` never changes a gated call's response shape

**Date**: 2026-08-11
**Decision**: `POST /v1/actions/call` takes `execution: "sync" | "async"`. An async call is accepted with **202 `{"status": "accepted"}`** carrying an `execution_id`, and is dialled off the request path by a claim-and-lease worker; the caller polls `GET /v1/executions/{id}`, subscribes to the new `executions` SSE topic, or reads it in the dashboard. The row lives in **`executions`**, extended rather than duplicated: `approval_id` becomes nullable and `request IS NOT NULL` marks a row as worker-run, deliberately orthogonal to `approval_id` so that "gated call, approved, then run async" is a legal third shape. The field is named `execution` and not `async` because `async` is a Rust keyword and reserved in JS/TS. The fork sits **after** the entire validation and authorisation pipeline and **before** every dispatch fork, so an async call inherits aliases, instance config, coercion, `validate_args`, the D42 SQL policy, owner impersonation, the group ceiling, the deny screen, the chain walk, and D56 timeout resolution unchanged — and cannot dodge any of them. A **gated** async call therefore returns the ordinary `pending_approval` envelope, not a 202. Routing that approval's eventual replay through the worker was *not* in the first cut — a gated call ran synchronously when approved, so `execution: "async"` was accepted and then forgotten at the gate, with `approvals.execution_mode` shipping reserved and read by nothing. That gap was the largest thing this decision left undone, and it was deliberate scope rather than an oversight discovered late — the direct path is what makes the D56 ceiling escapable at all, and the gated path followed without changing anything decided here. **[D66](#d66-a-gated-async-call-is-queued-when-its-replay-is-triggered-not-when-it-is-approved) closes it.** Concurrency is a `FOR UPDATE SKIP LOCKED` claim under a renewable lease with a heartbeat that doubles as the cancel poll; `attempts` counts only attempts that *lost* a lease, and is incremented by the reclaim sweep rather than by the claim. Cancellation is cooperative: it stops Overslash waiting, it does not stop the upstream. `prefer_stream`, `deliver: "url"`, `return_url`, platform-runtime actions, and `response_type: binary` are each a **400** in combination with async; `filter` and `verbose` are allowed. The deployment ceiling is per-mode — `ASYNC_CALL_TIMEOUT_MAX_MS` (default 900000) replaces `CALL_TIMEOUT_MAX_MS` in the same `call_timeout::resolve` call, with no change to the resolver.

**Rationale**: D56 capped the synchronous ceiling at 110s because Cloud Run cuts every request at 120s, and explicitly refused to auto-promote an over-ceiling call to a background one — that would change the response shape based on a number in a template the caller never saw. This is the surface that 400 points at, and the shape of it follows from taking that refusal seriously: promotion has to be something the caller *asks for*, in the request, so the response shape is always predictable from the request alone. That is also why a gated async call returns `pending_approval` rather than 202 — the caller asked for async, but the gate is a different axis, and collapsing the two would mean an agent could not tell "queued" from "waiting on a human" without a second field.

The load-bearing constraint is not CPU, and it is worth recording because the obvious reading of `infra/modules/cloud-run/main.tf` gets it backwards. `cpu_idle` is absent there, which looks like the API is on the throttled default; in fact the provider only defaults it to true when the `resources` block is *absent*, so this service has always had always-allocated CPU (the sibling shortener and overfwd modules set `cpu_idle = true` explicitly to opt **into** throttling and earn the 256Mi floor). Background work on the API instance therefore already works, and the maintenance loop, `emit_all`, and `spawn_auto_call` were never throttled. What *does* bind is scale-in: Cloud Run's autoscaler is request-driven, a queued row generates no scale-out pressure, and SIGTERM gives ~10s before SIGKILL. Instance death is thus the **normal** case, not the exceptional one — which is precisely why a detached `tokio::spawn` is not an option and the work has to be a durable row under a lease, so a killed job is late rather than lost. It is also why dev moves to `min_instances = 1`: at 0 there is simply no process to drain the queue.

Extending `executions` rather than adding a sibling table buys the six-state CHECK, the expiry sweep, `ExecutionSummary`, `result_viewed_at`, `tags`, MCP `get_result` and CLI `get-result` for free; the cost is one partial unique index and a discriminator. Making that discriminator `request IS NOT NULL` rather than an `origin` enum keeps the two axes independent, which is what lets the new lease sweeps say `AND request IS NOT NULL` while the pre-existing orphan sweep says `AND request IS NULL` — so neither can ever reach the other's rows, and the old sweep's semantics are unchanged rather than merely untouched. `attempts` counts lost leases rather than claims because that makes a clean hand-back at shutdown free: the worker releases its lease on SIGTERM and nothing has to decrement. It defaults to **1** because an action call is not idempotent and there is no idempotency-key concept — a `POST` that already reached the upstream must not be replayed because a worker died.

The per-mode ceiling needs no new resolver because `call_timeout::resolve` already takes `global_max_ms` as a parameter; async simply passes a different one. The 110s number exists because a proxy is counting, and for an async call no proxy is — so reusing it would have been cargo-culting a constraint that does not apply. `orgs.max_call_timeout_ms` still clamps async, which means an org that set 60000 to bound how long its agents hold connections has also bounded its async jobs; that is knowingly kept, because governance that only binds the cheap path is not governance, and no org is surprised by a call running *shorter* than they authorised.

---

## D63: A service icon is one authored string with two forms, implicit from the template key, resolved server-side to an absolute `icon_url`

**Date**: 2026-08-12
**Decision**: `info.x-overslash-icon` (alias `icon:`) accepts either `builtin:<name>` — an asset Overslash ships and serves itself — or an `https://` URL hosted elsewhere. It is normally **absent**: a template whose key matches a shipped asset resolves to `builtin:<key>` implicitly, so 18 of the 23 shipped templates declare nothing and `github_legacy_oauth` is the only one that needs an explicit value (its key deliberately differs from the `github` mark it reuses). The implicit lookup runs inside `compile_service`, **not** at response time, because a derived layer resolves through `apply_delta` under its *own* key: a layer named `acme_github` has no `acme_github.svg`, so a later lookup would find nothing and silently demote it to a monogram, where resolving at compile makes the existing `delta.icon.or(base.icon)` fold inherit the base's mark for free. `Delta` gains `icon` alongside `display_name`/`description`, and `validate_delta` runs the same check the standalone path runs — without that, the derived-layer write path is an unvalidated back door into the https-only rule. Parsing is permissive (classify, reject only empty/oversize/control characters) and **policy is separate**: `template_validation` rejects any non-https remote as an `invalid_icon` error, and `resolve_icon_url` re-checks the scheme when the response is built, so a value stored before the rule existed still never reaches a browser. A malformed icon is a compile **warning**, not an error, because `ServiceRegistry::load_from_dir` skips a whole file that fails to compile and losing a service over a typo'd logo is strictly the worse failure — the same reasoning `hidden` and `default_timeout_ms` already carry. Assets are generated from the pinned `simple-icons` package into `assets/service-icons/` by `make service-icons` (committed-but-generated, like `SCHEMA.sql` and the sqlx cache), named by **template key** rather than upstream slug, and baked into the API binary with `include_bytes!`. They are served at `GET /icons/{key}.svg` from `global_routes` — outside auth and outside rate limiting, because an `<img>` sends no `Authorization` header and cross-origin sends no cookie — with `nosniff`, a sandboxing CSP, and a day of `Cache-Control` plus a strong ETag. The wire field is `icon_url`, absolute, on `TemplateSummary`/`TemplateDetail`/`AdminTemplateSummary` and `ServiceInstanceSummary`/`Detail`. **No migration**: the value already persists inside the existing `openapi` and `delta` jsonb.

**Rationale**: Deriving an icon from the template's own `servers[]` favicon is the obvious idea and it is wrong here. The shipped hosts are `api.github.com`, `api.stripe.com`, `www.googleapis.com` — which is shared by Drive *and* Calendar, so two distinct services would collide on one mark — `gmail.googleapis.com` and friends, which serve no favicon at all, and `${METABASE_URL?}`, which points at a *customer's internal host*. Beyond the collisions, a favicon tier fires a third-party request per service row on every catalog render, from every operator's browser. There is no favicon tier at any priority.

Hosting is the second thing that looks like a shortcut and isn't. A CDN does not solve the trademark question: simple-icons' own disclaimer states that the project's CC0 covers the path data and not the marks, and asks users to seek their own permissions — Slack, LinkedIn, Eventbrite and Microsoft have no entry at all, several because the brand asked to be removed. What a shared icon set *does* buy is provenance and a consistent glyph set instead of hand-downloaded files of unknown origin. Given that, bundling beats hotlinking on every axis that remains: the dashboard currently loads **zero** third-party hosts at runtime and `@fontsource-variable/inter` already set the precedent of vendoring rather than hotlinking Google Fonts; bundling keeps that posture, works air-gapped, and needs no `img-src` if a CSP ever lands. The four brands with no mark ship none and render the monogram — which is exactly what every service rendered before this change, so nothing regresses.

Naming assets by template key rather than upstream slug is what makes the convention possible at all, and it is why `google_calendar.svg` is generated from simple-icons' `googlecalendar`. The alternative — an explicit `icon:` on all 23 templates — is 23 lines that restate the key, 23 chances to typo, and a silent monogram when someone renames an asset. The registry test asserts every shipped template resolves to *some* icon, with the four pending ones listed by name, so a rename fails CI instead of quietly degrading.

No denormalized column, though `display_name`, `description`, `category` and `hosts` all have one. Those exist so the catalog needn't compile every row, but every read path that renders an icon already runs the full fold — it must, because a derived layer's effective name lives in its delta rather than its column. A sixth column would buy marginally better *degraded* rendering in exchange for a write-path invariant to keep in sync across create, update and the derived-layer branch that already knowingly passes `hosts: &[]`. And the degraded case wants the fallback: "the base template is broken" is a state where a letter tile is more honest than a stale mark.

`/v1/search` deliberately does **not** carry `icon_url`. It fans out up to 100 rows per (instance × action) behind MCP `overslash_search`, and every field is paid for in the caller's context window for something no model can render — the same reasoning D57 applies to action descriptions. The `overslash` meta-service's `list_services` *does* return it, because it hands back `ServiceInstanceSummary` through the shared kernel; that is roughly one row per instance rather than a hundred, and those actions are what a dashboard-like client calls. Accepted knowingly rather than special-cased.

Instances get no icon of their own. An instance is a binding of a template to a credential — two Gmail instances are both Gmail — and a per-instance icon would be the first place a user-supplied image URL reached other users' browsers, a materially worse surface than an admin-authored template. The URL is absolute rather than relative because the same JSON is read by the dashboard on a *different origin* in cloud (`app.` vs `api.`), the CLI and the SDK; a relative path would resolve against whichever origin served the page and 404. Absolute does **not** mean self-sufficient, though, and the first cut of this claimed it did: on cloud `public_url` is the *app* origin, not the API's, so every `icon_url` lands on the dashboard host — which serves only what `vercel.json` explicitly proxies. Without a rewrite every icon 404s to `text/html` and degrades to a letter tile, silently, because the fallback is doing its job. `/icons/:path*` is proxied alongside `/health` in all four blocks, and a test asserts that pairing so the next browser-facing route added outside auth cannot repeat it.

## D64: Display-param resolvers are cached on a bounded-staleness window, Valkey-backed with a process-local fallback

**Date**: 2026-08-12
**Decision**: An `x-overslash-resolve` answer — both halves, the `display` string and the `scope`-derived canonical value — is cached and reused. The store is `REDIS_URL`-backed when one is configured and a `DashMap` otherwise, chosen once at boot by `services::resolve_cache::create_resolve_cache`, mirroring `rate_limit::create_store_with_eviction`; a Redis error at request time is a **miss**, never a fall-through to the in-memory map, so a hit can never depend on which of two stores answered. Every operation is bounded by `RESOLVE_CACHE_TIMEOUT_MS` (100ms) and fails open — the call resolves live. All of an action's resolvers are read in one pipelined round trip (single-key `GET`s, not `MGET`, which is cross-slot and would hard-error on a clustered Valkey) and written back in one pipeline of `SET .. EX`, because the TTL is per-resolver. The lookup is a **two-phase** `plan()` executed by the caller *before* it assembles credentials: on HTTP a full hit skips the vault decrypt that builds resolver headers, on MCP it skips `build_client` entirely — the vault reads plus the blocking `to_socket_addrs` in `ssrf_guard::build_pinned_client`. Keys are `osr:v1:{namespace}:{org_id}:{sha256}` over a **length-prefixed** preimage of `(org, ceiling user, instance, credential fingerprint, service key, runtime, target, display template, scope path)`; the org id is the only plaintext component. Values are JSON, **encrypted with the existing keyring**, and carry a `neg` marker distinguishing "the resolver ran and projected to nothing" (success TTL) from "the resolver did not answer" (`RESOLVE_CACHE_NEGATIVE_TTL_SECS`, 30s). TTL resolves most-specific-first — the resolver's `cache_ttl:`, else `RESOLVE_CACHE_TTL_SECS` (300s) — then clamps to `RESOLVE_CACHE_SCOPE_TTL_MAX_SECS` when the resolver declares `scope:`. `cache_ttl: 0` skips the read as well as the write. Failures that are *ours* rather than the provider's — a credential that would not build, an MCP client that could not be constructed — are never negatively cached. `POST /v1/actions/validate` still does not resolve.

**Rationale**: `services/gmail.yaml` asks `GET /gmail/v1/users/me/profile` on nineteen actions to turn `me` into an address that only changes when the connection does, and `resolve_request` runs on *every* `/v1/actions/call`, including auto-approved reads that never gate. An agent listing messages twenty times paid twenty identical round trips, and a provider that was merely down cost every call the full 3s resolver timeout on top of its own latency.

The load-bearing consequence, and the reason this is written down rather than treated as an implementation detail: **a cached resolver answer is an authorization decision, not just a latency optimisation.** `scope:` canonicalizes the permission key while the outgoing request keeps the caller's raw argument (D55). Live, those two are consistent by construction — the canonical value is derived microseconds before the key is built. Cached, they are not: the key reflects the mapping as of up to a TTL ago and the call targets the mapping as of now. If a WhatsApp JID is re-pointed inside the window, a grant minted for the old person still matches, and the message goes to the new one with no human in the loop. That is precisely the failure D55 exists to prevent ("an approval could read 'to Sonia' while the message went elsewhere"), reintroduced on a timer. It is accepted, bounded, and paid for three ways: a short default, a separate and tighter ceiling for `scope`-bearing resolvers, and a `resolver_cache_ttl_wide` warning so an author widening the window is told what they are widening. The knob is on the template because only the author knows whether a mapping is immutable — `me` → your own address is safe for an hour, a JID → a phone number is something the provider can re-point under you. Defaulting long and asking WhatsApp to opt down would get the incentive backwards: whoever forgets the knob must land in the safe place. Everything else about a miss fails closed — no canonical value means the key stays the raw argument, matches no grant, and gates.

The credential fingerprint is the field that makes the cache safe to share at all. gmail's `userId: me` produces a byte-identical URL for every user alive, so a key without it would serve one person's email address into another person's approval *and* into their permission key. It is never the credential: a bearer rotates hourly, which would miss on exactly the long-lived lookups worth caching, and an unsalted hash of a live token sitting in a shared store is an offline confirmation oracle. OAuth contributes the connection id (threaded out of `resolve_effective_mcp` for this, which also fixed MCP calls never recording the account they authenticated as); secret-backed schemes contribute vault *references*, which also covers a case the connection id misses entirely — a Mode B/C call passing explicit `req.secrets` has no connection and no principal, so two agents under one owner using different secret names would otherwise share one entry. The preimage is length-prefixed rather than delimiter-joined because `service_key` is org-authored and a field containing the delimiter could otherwise shift the boundaries.

Values are encrypted because of what they are: names, phone numbers, email addresses, file titles. Process-local that is unremarkable; in Valkey it is a new data-at-rest surface, and `infra/modules/memorystore/main.tf` sets neither `auth_enabled` nor `transit_encryption_mode`, on an instance `infra/main.tf` shares with the public URL shortener. Encryption is the half that ships with the code and needs no operator action; turning on AUTH and TLS is a separate infra task, breaking for `oversla-sh` too. It costs microseconds, and rotation invalidating the cache is harmless since entries are ephemeral by construction — but it does extend the master key to a second purpose, which is the one thing here worth revisiting if the keyring's blast radius ever becomes a concern.

Two smaller choices. The in-memory backend, on overflow, evicts a bounded arbitrary sample and inserts, rather than declining the write: declining freezes the map on whatever arrived first, so a hot key could never be re-admitted after expiring while a flood of one-shot arguments squatted — the opposite of what a cache is for. And local failures are excluded from the negative cache because caching them turns a transient misconfiguration into a sticky one on every replica; a provider 404 or timeout, by contrast, is a real answer and is exactly where a negative entry earns the most.

Not done: single-flight. Concurrent identical misses still both fire, which is today's behaviour — the thundering herd is now cross-replica but no larger. And `validate` still does not resolve, because consulting the cache there would make a dry run's answer depend on cache state and reopen the asymmetry D55 chose deliberately.

## D65: jq error text never leaves a surface whose operands may be redacted

**Date**: 2026-08-12
**Decision**: `services/disclosure.rs` collapses every per-filter failure to a **fixed classification** — `filter runtime error`, optionally qualified `(cannot index)` / `(cannot calculate)` / `(cannot use)` — chosen by a `classify(&str) -> &'static str` whitelist over jaq's own fixed error prefixes. The return type is the guarantee: nothing operand-derived can escape by construction, even when the message is attacker-shaped (a filter may raise `error("cannot index …")` itself; the worst that buys is a wrong hint). The engine's message is dropped and persisted nowhere. What an operator needs to find a broken template — the field label, a sha256 of the filter expression, and the class — goes to `tracing::warn!` instead, following the `filter_audit_entry` precedent that already logs `expr_sha256` and never logs output values. `services/response_filter.rs` is **explicitly excluded** and keeps propagating jaq text verbatim. No backfill: existing rows are left as written.

**Rationale**: This generalises the rule `services/credential_template.rs` has enforced since it shipped ("jq's runtime errors embed their operands, and the operands here are credentials … Keep it that way") to the second place where that is true. It is true in jaq by construction, not by accident: `jaq-core`'s `Error::index`, `Error::math` and `Error::typ` each interleave static strings with the *values themselves*, and `run_jq_blocking` flattens the result with `format!("{e}")`.

Disclosure was doing the opposite — `cap_message(msg)`, up to 512 characters of that text, straight onto `DisclosedField.error` — and it runs against the **un-redacted** projection. That input is not negotiable and must stay: the shipped Gmail template redacts `body.raw` and discloses To/Subject/Body extracted *from* `body.raw`, so redacting before extraction would delete the feature. The fix therefore has to sit at the error surface.

The sharp case is not the malicious template author, who per SPEC §12a *Trust boundary* can already put a redacted value straight in `.value` and is understood to be doing so deliberately. It is the **accidental** one: a template that did declare `redact: [body.card_number]` and discloses `.body.card_number.last4` loses the redaction the moment a caller sends a plain string instead of the object shape the filter assumed. Nothing in the filter text tells a reviewer that, the value lands on two durable rows (`approvals.disclosed_fields`, `audit_log.detail.disclosed`) plus the inline `pending_approval` envelope the calling agent reads, and the error channel quotes the *enclosing* value rather than the addressed one — so `.body + 1` yields every redacted path in the body at once, bypassing the per-field `max_chars` clamp that bounds the deliberate channel.

The response filter is left alone because its exclusion is principled rather than an oversight: its operand is the upstream response body, which the caller already receives on `result.body`. Same data, no new exposure — and its jq text is genuinely the most useful thing a caller debugging a filter can be handed. A classification is kept rather than a single bare string because the class comes from a whitelist and costs nothing, and "your dot-path indexed something that is not an object" is the one hint that actually shortens the round trip for a template author who can no longer read the message.

---

## D66: A gated async call is queued when its replay is *triggered*, not when it is approved

**Date**: 2026-08-12
**Decision**: Completes the gated-async path [D62](#d62-async-calls-are-a-leased-row-the-caller-polls-not-a-detached-task-and-execution-async-never-changes-a-gated-calls-response-shape) reserved. `permission_gate` stamps `approvals.execution_mode` from the request's `execution` mode, and both triggers of a replay read it back: `POST /v1/approvals/{id}/call` and `spawn_auto_call` **enqueue** an async approval — an `UPDATE` lifting `approvals.replay_payload` into `executions.request` on the pending row — instead of claiming it and dialling. The enqueue happens at *trigger* time, not when the approval is resolved, so `auto_call_on_approve = false` keeps meaning "nothing runs until the agent says so" and `services::inbox`'s `ready_to_call` keeps meaning what it says; `ExecutionSummary` grows a `queued` flag because a queued row sits in `pending` and the inbox, the approval page and the queue row all have to tell "queued on a worker" from "waiting on you". `claim_for_execution` gains **`AND request IS NULL`**, which is the load-bearing line: the enqueue leaves the row `pending`, exactly what the synchronous claim accepts, so without it a manual `/call` and a worker can both take the row and both reach the upstream. `/call` answers **202 with the ordinary `ApprovalResponse`** (plus `execution_mode` and `poll_after_ms`), not the `accepted` envelope. On the worker an approval-backed row runs the *same* post-execution tail the inline replay runs — extracted to `routes::approvals::tail` — so the rules, the cascade, the `approval.executed` audit row and the approval event are identical whichever trigger dialled it, and its `action.executed` row is stamped `AuditSource::Replay`. An approval with no `replay_payload`, or a deployment that has since turned `ASYNC_EXECUTION_ENABLED` off, falls back to the inline synchronous replay. Cancelling a row a worker already owns falls through to the cooperative `request_cancel` and emits nothing — the worker announces the terminal state when it observes the flag. Two D62 defects are fixed as prerequisites: the async ceiling was never actually passed to `call_timeout::resolve` (so `ASYNC_CALL_TIMEOUT_MAX_MS` was unreachable and the feature could not escape the 110s cap it exists to escape), and the `enabled` check sat *below* the gate (so a gated async call on a flag-off deployment filed an approval instead of a 400). No migration: migration 112 already ships every column, and the `create_pending_async_from_approval` helper it shipped — written for the approve-time design — is retired.

**Rationale**: The alternative was queueing at approve time, which the already-shipped INSERT helper anticipated. It loses on the contract: `auto_call_on_approve = false` is a per-agent promise that an approved action waits for the agent, and a row queued at approve time runs anyway. It also breaks the inbox — the window between "approved" and "a worker claimed it" is unbounded when every replica is saturated or the flag is off, and throughout it the agent is being told to dispatch a row it cannot have. And it makes `POST /v1/approvals/{id}/call`, the documented resume path for MCP `overslash_call({approval_id})` and `overslash call`, permanently unable to do anything but report "already queued". Trigger-time enqueue keeps one decision point and needs no second path.

The claim predicate matters more than any of the handler-level guards above it. `/call` also probes before falling back to the inline replay, and that probe catches the common race — but it is a check-then-act in a different transaction, and the case it cannot cover is a deployment that turned the worker off between the enqueue and the trigger, which skips the async branch entirely and goes straight to the claim. Excluding the two triggers by predicate makes "a gated async call is dialled at most once" provable from the SQL rather than argued from the order of handlers.

The 202 carries the existing envelope rather than a new one because both alternatives are worse in the same way: the dashboard assigns the response straight into its `ApprovalResponse` store and MCP forwards any 2xx body verbatim, so a second shape under one route is a runtime break with no type error to catch it. The HTTP code plus `execution_mode` is the honest signal, and `ApprovalResponse` has no `status` discriminator of its own to be consistent with — its `status` is the *approval's*.

Moving the tail rather than reimplementing it is what makes "an approved call owes the same things whichever trigger ran it" checkable: the tests assert *counts*, not existence, because a tail that was copied instead of moved passes an existence check and doubles the audit trail. It stays under `routes::approvals` so the `tail → spawn_auto_call → execute_claimed_approval → tail` cycle remains inside one module and `spawn_auto_call` stays private; the boxed `dyn Future` that breaks that cycle sits on the edge that closes it and is untouched.

## D67: A key nothing reads is a warning on every path, and `openapi::ext` is the only thing that knows where each extension is read

**Date**: 2026-08-12
**Decision**: `openapi::lint_extensions` runs on the alias-normalized document at every validation entry point and reports four classes of key the compiler will silently ignore: **`unknown_extension`** (an `x-overslash-*` name nothing reads, with a `closest_match` suggestion), **`misplaced_extension`** (a known name at a position whose extractor does not read it), **`unprefixed_alias_ignored`** (a bare spelling at a position the alias walk does not rewrite), and **`unknown_template_key`** (an unrecognized bare key at a position whose fields we enumerate). Every one is a **warning, never an error, on every path**. Position comes from **`openapi::ext`**, a `READS` matrix of extension × position that every extractor now reads through via `ext::get(obj, pos, ext)`; the accessor carries a `debug_assert!` against the matrix, and `no_extension_getter_bypasses_the_accessor` bans the `obj.get("x-overslash-…")` spelling in `openapi/` production code. Enforcement lives in **`shipped_services_lint_clean`**, which filters on `LINT_CODES` rather than on `warnings.is_empty()` so an unrelated warning can neither disarm nor break the gate. Three positions are deliberately **open-world** for bare keys — request-body and MCP tool-input properties (JSON Schema), a `discovered_tools` snapshot (the MCP wire shape), a platform-action param, and any unrecognized security-scheme `type` — because at those positions the sibling keys are vocabulary we do not own, and a payload field genuinely named `risk` or `template` must not be reported. A position's own declared fields also win over the extension vocabulary, which is what keeps `x-overslash-mcp.auth.provider` — a read field that shares a name with an `oauth2` scheme's `provider` alias — from reading as misplaced. Two normalizer/reader disagreements found while writing the matrix are fixed rather than reported: `APIKEY_HTTP_SEC_ALIASES` is **split** into `APIKEY_SEC_ALIASES` / `HTTP_SEC_ALIASES`, since `extract_http_auth` reads only `default_secret_name` and `label` and generates its own injection template; and `normalize_parameters_in` gains `normalize_body_properties_in`, so an unprefixed `resolve:` in a request body works instead of being a no-op — the HTTP twin of D55's `input_schema` walk, and a **live behaviour change** with zero shipped-template impact (all nine body-property annotations already use the canonical spelling). Path-item level stays un-extended on purpose: `risk:` hoisted out of a method is not a concept, so the lint reporting it is the right outcome. `registry::load_from_dir` logs findings and still loads the template; `template_resolve` lints the *stored* document into the resolution report the catalog already badges; `validate_delta` re-roots a finding's dot-path from the synthetic `paths.{path}.{method}` onto `extensions.actions.{key}.operation`, so it names something the author can find.
**Rationale**: `services/metabase.yaml` carried `response_type: binary` on `export_query` for months and it did nothing — the compiler only *derives* a response type from a `responses:` block, so a large xlsx export was buffered against `max_response_body_bytes` and the only evidence was the absent `prefer_stream` hint. D57 fixed that instance; nothing would have caught the next one. **Neither motivating bug is a misspelling**, and that decided the scope: `response_type` is a `ServiceAction` field name and `resolve:` is an alias, so a lint over `x-overslash-*` names alone would have caught neither, while a closed-world bare-key check alone would have missed `x-overslash-download` on an HTTP operation and every stray key at an open-world position. Each half misses the other's motivating case, which is the argument that four rules is the scope rather than gold-plating. **Warnings, not errors, because the two strict options are both worse than the disease.** An error at `load_from_dir` means the template is *skipped* — a stray key would remove a service, where before it merely removed a field, and that is a strictly larger outage than the bug. An error on create/update would make an already-active stored org or user template un-saveable by its owner, on tenant data no one can survey, over a key that was inert the whole time. Neither is worth it when the population of shipped offenders is empirically zero and a CI gate holds the line for free. That leaves visibility as the real problem, which is why the lenient paths all had to grow a surface: `POST /v1/templates/validate` already rendered warnings in the editor but the header still read "Valid" over them; the draft page rendered `import_warnings` and dropped `validation.warnings` entirely; the layer editor rendered warnings with no `path`. **`template_resolve` is the highest-leverage placement** and the reason the severity question is answerable at all — it is the only thing that ever looks at a row written *before* the lint existed, so the badge count is how the affected population becomes visible without a migration or a grandfathering table, both of which would have preserved the bug class they were protecting. **The accessor is the part that has to survive.** A hand-maintained position table drifts in the direction that matters most: it claims a key is read somewhere it is not, and the lint then blesses the exact no-op it exists to catch — and a name-level source grep cannot see that, because it reconciles *names* while the lint needs *name × position*. It also could not have distinguished `template` on an `apiKey` scheme from `template` on an `http` one, which is a live instance of the bug. Routing reads through `ext::get` makes the matrix a precondition of the reader instead of a description of it, and the mechanism proved itself during this change: PR #550 landed `x-overslash-icon` on `dev` mid-flight, and the guard failed on the unregistered reader immediately rather than shipping a lint that warned about a correct template. The `.get("x-overslash-…")` ban is scoped to reads and deliberately leaves compound dot-paths and message text alone — those are not reads, and routing them through `Ext::key()` would buy nothing and cost legibility. One honest limit, recorded in TECH_DEBT: the matrix's *position* claims rest on review, since only its *name* claims are mechanically checked.

## D68: A hybrid call is a row that is durable before it is dialled, and a hybrid row is failed, never re-dialled

**Date**: 2026-08-13
**Decision**: `execution: "hybrid"` on `POST /v1/actions/call`, behind the same `ASYNC_EXECUTION_ENABLED` flag as [D62](#d62-async-calls-are-a-leased-row-the-caller-polls-not-a-detached-task-and-execution-async-never-changes-a-gated-calls-response-shape). The request path **never dials**: `routes::actions::hybrid::start` inserts an `executions` row *already claimed by this process* (`create_hybrid_claimed` — a single statement at `status = 'executing'`, `triggered_by = 'hybrid'`, under this replica's lease), spawns the ordinary `async_executor::job::execute` with `JobMode::Hybrid { observer }`, then races a `oneshot` receiver against `sleep(handoff)`. Win the race and the caller gets the ordinary **`called`** envelope, rendered by the same `render_stored` the synchronous path uses, with a new optional `execution_id` correlating it to the row. Lose it and the caller gets the **`accepted`** envelope `async_accept` already produces, and polls `GET /v1/executions/{id}`. `action.accepted` is audited **only** on the handoff branch. The handoff is `HYBRID_HANDOFF_MS` (default 5s) with a per-call `handoff_after_ms`; a caller-supplied value above `HYBRID_HANDOFF_MAX_MS`, below 100ms, or not less than the call's own `timeout_ms` is a **400**, while the deployment default is silently **clamped** to that budget — the split `timeout_ms` already makes. Hybrid resolves its D56 budget against the *async* ceiling, safe because the connection is bounded by the handoff and never by the budget. `HYBRID_MAX_INFLIGHT` (default 32) caps concurrent hybrid jobs per replica; over it, the call falls through to `async_accept` and is answered `accepted` on the ordinary queue, so saturation is invisible to the caller. `ExecutionDetail.origin` gains `hybrid`, and the list filter accepts it. Migration 114 widens `approvals_execution_mode_check`; a *gated* hybrid call is stamped `'hybrid'` and then queued exactly as async is (`ApprovalRow::is_async` matches both).

**The invariant**: a hybrid row never returns to `pending`. `claim_async_batch` takes `pending AND request IS NOT NULL`, so any path back to `pending` hands a live upstream request to another replica to send a second time, and an action call has no idempotency key. Three statements could do it, and all three now carry `triggered_by IS DISTINCT FROM 'hybrid'`: `requeue_expired_leases`, `fail_exhausted_async`, and `release_async`. A hybrid row whose lease expires is failed by a dedicated sweep with the distinct reason `hybrid_instance_lost`, and the job's own shutdown path finalizes `worker_lost` rather than releasing.

**Rationale**: The obvious framing — "sync that gets promoted at a timeout" — cannot be built, and `TODO.md` recorded why: an in-flight upstream request cannot be handed to a leased row without either sending it twice or degrading to a detached task with no durable record. Inverting it dissolves the problem. Hybrid is *async that the connection waits on*: the job owns a durable row from before the first byte and dials exactly once, and the connection is a spectator with a deadline. Nothing is handed over at the deadline except who reports the result, which is why both response shapes describe the same row and why the 200 branch can reuse the synchronous renderer instead of a parallel one.

Inserting **before** dialling rather than lazily at the handoff costs an INSERT on calls that never need it, and buys the property the mode is named for. The lazy alternative leaves the window between dial and handoff with no durable record at all — a crash there means the side effect happened and nothing anywhere knows — and it puts a database write on the handoff path, where a failure leaves a live upstream call with nowhere to put its result. The accepted consequence is an availability inversion: a database outage turns a hybrid call into a 500 where a synchronous one would have succeeded. That is the correct direction to fail, because the alternative is dialling an upstream with nowhere to put the answer.

Excluding hybrid from **both** reclaim arms rather than one is not belt-and-braces. The two are disjoint by arithmetic on `attempts`, so at the default `max_attempts = 1` a hybrid row lands in the exhaust arm and is failed — *accidentally* right. Raise the knob and the same row lands in the requeue arm and is dialled again. Excluding both is what makes the invariant independent of an operator's configuration, and `a_hybrid_row_still_fails_when_max_attempts_is_raised` is the test that pins it.

A **gated** hybrid call is queued, not raced, because `spawn_auto_call` has no connection to race on at all — so racing the other trigger would make one approval behave differently depending on which of its two triggers fired, the exact failure D66 was written to prevent. The connection that would be racing is a resolver's browser, not the caller whose latency budget motivated the mode. `execution_mode` still stores `'hybrid'` rather than folding to `'async'` at stamp time: both triggers treat them identically, but a lossy stamp cannot be un-lost, and the approval card should be able to say which mode was asked for.

`StoredOutcome` had to grow **`typed: ActionResult`** rather than have the connection re-parse the row's JSON, because `run_platform` stamps a `runtime` key into that JSON and `run_mcp` produces the MCP shape — both deliberately, for the *row*. It also grew `is_error` **separate from** `upstream_errored`: those are the `>= 400` and `>= 500` rules, and collapsing them would mis-report every HTTP 4xx and every MCP in-band tool error, whose `status_code` does not encode the flag. The inline report is sent **after** `finish` returns, so the connection can never answer 200 for a row the database has not accepted, and a lost lease reports nothing at all — the sender drops, the caller gets 202, and reads whatever the row's real owner wrote. Every non-answer ending (cancelled, lease lost, shutdown, panic) is signalled the same way, by dropping the sender, which is one less state to keep in sync with the row.

Metrics get a purpose-built `overslash_hybrid_calls_total{outcome}` and `overslash_hybrid_handoff_seconds` rather than a new value on `record_execution`'s `mode`, which is the call *shape*. Folding handed-off calls into the existing duration histogram would fill it with samples clustered at the configured handoff, making its p99 a reading of the deployment's own config rather than of its upstreams.

## D69: A SELECT is a read only while every function it calls is one, and Postgres's own volatility catalog decides which those are

**Date**: 2026-08-13
**Decision**: `sql_policy::analyze` now screens **function calls**, not only statement shape. A top-level `SELECT` that clears the D42 gauntlet (single statement, no writable CTE, no `SELECT … INTO`, no row locking) classifies read **only if every function it invokes is on the safe list**; any miss returns `WriteReason::UnsafeFunction`, which elevates the risk floor to write **and** sets `tables_exhaustive = false`, so the call mints the `table_mut={label}/*` sentinel instead of the per-table keys the parser enumerated. The safe list is two lists. The bulk is **generated from `pg_catalog`**: every IMMUTABLE or STABLE function, aggregate and window function, committed as `sql_policy/catalog_functions.rs` (2 475 names, byte-sorted, binary-searched) by `scripts/gen-sql-safe-functions.sh` against the Postgres major `libpg_query` vendors. Postgres's own contract is that a non-volatile function "cannot modify the database", so volatility — not our taste — draws the line, and it lands `nextval`, `setval`, `set_config`, `pg_read_file`, `lo_import`, `dblink` and `pg_terminate_backend` on the far side without our naming one of them. Two classes of non-volatile function are **subtracted by the generator**: the relation-slurping XML functions (`table_to_xml`, `schema_to_xml`, `database_to_xml` and their `…schema` variants), which are STABLE but read a relation named at *runtime* and would therefore break the table enumeration; and `txid_current` / `pg_current_xact_id`, which are STABLE but assign a transaction id. The second list is a hand-maintained **VOLATILE-but-harmless carve-out** in `sql_policy/functions.rs` — `pg_sleep`, `pg_sleep_for`, `pg_sleep_until`, `random`, `random_normal`, `gen_random_uuid`, `clock_timestamp`, `timeofday` — each with a comment saying what it cannot change. Names are compared **exactly** after stripping one leading `pg_catalog.`; anything still carrying a `.` is schema-qualified outside the catalog and never matches, and a quoted `"COUNT"` correctly misses the lowercase `count`. The escape hatch is per database: `SqlDatabaseEntry` gains `safe_functions: []` in the existing `sql_databases` instance config, normalized the same way, so an operator unblocks their PostGIS `st_*`, their `unaccent`, or an in-house UDF with a config edit rather than a release. The offending names ride in `WriteReason`'s payload — capped at five plus a count — into `audit_log.detail` and the approval detail block, and deliberately **not** into the tag index, which gets `sql_reason:unsafe_function` and nothing more.

**Rationale**: D42 wrote the limitation down and shipped it: "volatile functions inside a SELECT (`SELECT nextval('s')`) classify read — function-level policy is out of scope, DB grants own it." Delegating to DB grants is sound in principle and hollow in practice, because the gateway is exactly the layer an org reaches for when it *cannot* re-grant the upstream — the Metabase service account is shared, and a `risk: dynamic` action's whole promise is that Overslash tells read from write on that account's behalf. Under the old rule `SELECT pg_read_file('/etc/passwd')`, `SELECT dblink_exec('…','DELETE FROM t')` and `SELECT query_to_xml('DELETE FROM t', …)` were all reads that auto-approved and executed, and the last two are arbitrary write execution through a statement the classifier had just certified.

**The generated list is the load-bearing choice, and the alternative was a denylist.** A curated list of dangerous functions is smaller, easier to review, and wrong in the direction that costs: it is an enumeration of badness over a namespace that extensions and every `CREATE FUNCTION` extend at runtime, so a UDF — the one thing whose body the parser provably cannot see — sails through by default. Fail-closed inverts that, and the reason it is affordable at all is that Postgres already publishes the answer. Hand-curating ~400 common functions was the third option and is strictly worse than generating 2 475: same failure mode, more work, and no principle behind an omission.

**`pg_sleep` is why the carve-out exists rather than a footnote.** Volatility alone would refuse it, and refusing it would be indefensible — it burns wall-clock in the caller's own backend and touches nothing. That it sits next to `nextval` under the same `provolatile = 'v'` is the proof that the catalog is a *floor* for this policy, not the whole of it. The carve-out is kept short on purpose: each entry must survive "what can this change?", and a test asserts none of them has since become STABLE, which would mean the generator now covers it and the justifying comment has gone stale.

**Dropping `tables_exhaustive` is the half that makes the elevation real.** Classifying write while still claiming the table lists are complete would let a `table_mut={label}/public.film` grant authorize `SELECT my_udf(id) FROM public.film`, and the UDF body reaches anything it likes — the relations in the `FROM` clause are not the relations the statement touches. This is the same reasoning `DO`/`CALL`/`EXECUTE` already got, applied to the case where the opaque body is a function's instead of a block's. The cost is honest and visible: an unlisted-but-harmless function now needs an all-tables mutation grant, which is exactly the pressure that makes `safe_functions` get used instead of `metabase:**`.

**The escape hatch is per database and not global** because vouching for `unaccent` on a reporting replica says nothing about production, and the config already keys on the database for dialect and label. It widens the read/write boundary, so it belongs where a reviewer already looks to see which database a grant names.

**The names stay out of the tag index** for the reason `ParseError`'s message does: they are caller-controlled and unbounded, and one agent looping over `f1()`, `f2()`, … would turn the audit tag namespace into a cardinality bomb. `sql_reason:unsafe_function` is enough to find the rows; `detail` answers which function.

**The enumeration is checked, not trusted, and that is the part that nearly shipped wrong.** The first draft read function names off `pg_query`'s `nodes()` iterator, which the crate documents as covering "a subset of nodes" and which is in fact a hand-written per-variant field list. It silently skips seven positions — an aggregate's `FILTER`, `LIMIT`/`OFFSET`, a `VALUES` row, `DISTINCT ON`, a window frame's `ORDER BY`, `agg_order`, and an array subscript — so `SELECT count(*) FILTER (WHERE nextval('s') > 1) FROM t` classified read with the gate in place. For D42's *table* enumeration a gap like that is a known imprecision; for a screen it is a bypass, because a call nobody reached is a call nobody screened. Two things fix it and both are needed: `blind_spots` re-roots the walk at each dropped field, which buys back *precision*; and `count_func_calls` renders the tree through a counting sink — `prost` derives `Debug` structurally over every field, so one `FuncCall {` appears per call wherever it sits — and any shortfall against the walk fails the statement closed under a reserved `<unenumerated call>` name. The oracle is what makes the guarantee survive a `pg_query` upgrade, since it rests on prost's derive rather than on anyone's field audit staying current; the 27-position `no_call_hides_from_the_walk` test is its specification and only ever grows. It costs ~12% of an already sub-millisecond classify, and only on statements that would otherwise have been reads.

**Operators are deliberately not screened.** An `A_Expr` names an operator, not a function, so a user-defined operator backed by a volatile function slips the gate. Closing it would mean resolving operators to their implementing functions, which needs the catalog we do not have at classify time; the exposure requires a custom operator to already exist in the database, and the read-only upstream credential still backstops it. Recorded as a non-guarantee in the module docs rather than half-solved.

The change is **not backwards compatible for existing `risk: dynamic` callers**, and that is intended rather than tolerated: every query it reclassifies was one the old rule certified as a read without evidence. Queries using extension functions or in-house UDFs go from read to write-plus-sentinel on deploy, fixed by `safe_functions` without a release. The measured blast radius is small — over a 26-query corpus of ordinary analytics SQL (window functions, `percentile_cont … WITHIN GROUP`, `jsonb_build_object`, `string_agg`, `to_char`, `extract`, `date_trunc`, `coalesce`/`nullif`/`trim`, `greatest`/`least`) exactly one classifies write, and it is the deliberate `nextval`. Several of those never reach the screen at all: `COALESCE`, `NULLIF`, `GREATEST` and `LEAST` are grammar constructs rather than `pg_proc` entries, which is precisely why a token-level screen was rejected — it would have failed all four.
## D70: An agent's icon is its MCP client's mark, and its identity is a hash stripe — not a picker

**Date**: 2026-08-13
**Decision**: An agent renders as **the logo of the MCP client bound to it**, drawn over **three colours derived from the last nine bytes of `sha256(agent id)`**, one byte per channel. Both halves are resolved server-side onto `IdentityResponse` as `icon_url` / `icon_stripe` / `mcp_client_label`, and both are pure functions of data already stored — so there is **no `identities.icon` column, no migration, and no icon picker**. The client is identified by normalized-substring match against a static table in `overslash_core::mcp_client_icon`, tried over `clientInfo.name` (the `initialize` handshake), then `oauth_mcp_clients.client_name` (DCR), then `software_id`; anything unmatched resolves to `client_unknown`, a bot glyph we author ourselves, so an agent mark is **never absent**. Client marks live in the **existing** `assets/service-icons/` set under a **`client_` prefix**, which is what keeps them out of `ServiceIcon::implicit_for_key`'s `builtin:<template key>` rule — an unprefixed `cursor.svg` would silently become the icon of any future service template keyed `cursor`. They follow D63's manifest discipline unchanged: `simple-icons` where a mark exists, `pending` with owner + guidelines + note where it does not (`client_vscode`, `client_chatgpt`), and a pending client degrades to the letter tile exactly as a pending service does. `GET /v1/identities` resolves every agent's client in **one** `DISTINCT ON` query (`clients_for_agents`) whose tie-break matches `get_by_agent_identity`'s, and the plain `From<IdentityRow>` impl is **replaced** by `from_row(row, &IdentityIconCtx)` so the lookup cannot be forgotten.
**Rationale**: Users and services both got real marks (D63, #549, #550) and an agent was the last identity kind still drawn as a bare name — `TODO.md` had carried "identities and services carry no icon field" as the reason the Live Map rendered monograms. The client logo is the useful default because it is the one thing about an agent a reader did not choose and cannot infer from the name: `releaser` tells you nothing about whether it is Claude Code or a cron job. But a logo alone **makes siblings indistinguishable** — a team running five Claude Code agents gets five identical rows, which is worse than the monogram it replaced, and that objection is what the stripe answers rather than a second mechanism bolted on. Hashing the **agent's** id, not the client's, is the whole point: the logo already carries the client, so the stripe has to carry what the logo cannot. **A picker was considered and rejected**: it needs a column, a migration, a PATCH surface, an ACL answer (identity mutation is `AdminAcl` today, which would put a cosmetic choice behind org-admin), and a UI — all to hand-maintain something the binding already knows, and all of which can still be added later on top of this without changing what an un-picked agent renders. **The `From` impl had to go.** With it, an endpoint that skipped the enrichment still compiled and still returned valid JSON — it just quietly drew every agent as the generic bot, a failure with no error and no visual signal that anything was missing. Making the context a constructor parameter turned that into a compile error, and it immediately caught `patch_auto_call_on_approve`, which nothing in the plan had listed. Matching is deliberately **substring over a normalized string rather than equality**, because none of the three sources is a controlled vocabulary — they are free text chosen by whoever wrote the client, and `Claude Code 2.1.0`, `claude-code` and `claudeCode` all have to land on one mark. Ordering the table specific-before-general (`claudecode` before `claude`, `githubcopilot` before `copilot`) is asserted by a test rather than left to reading order, since the failure mode is silent: a general needle listed first makes every later specific one unreachable. Nothing here gates access, so a wrong guess costs a wrong logo and never a wrong permission — which is why the table can afford to be lenient.

## D71: A decision number is allocated when the PR merges, and until then the author writes a placeholder

**Date**: 2026-08-14
**Decision**: A new entry in this file is written with a placeholder heading and referred to by that placeholder everywhere else in the same PR. `.github/workflows/allocate-decision.yml` rewrites it to the real number across every tracked file on the push to `dev`, and commits the result as `chore(docs): allocate D<n> (#<pr>)`. Decision numbers no longer appear in commit subjects or PR titles. `scripts/check-decisions.sh` runs in CI (the `docs` job, unconditional — the `lint` job's `rust` filter skips exactly the docs-only PRs that move a number), in `make check`, and in the pre-commit hook. See [docs/runbooks/decision-numbering.md](docs/runbooks/decision-numbering.md).

**The number was never valid when it was picked.** `max + 1` is chosen at authoring time and only means anything at merge time. Between those two moments every decision that lands first invalidates it, and the file is append-only, so two branches also always collide on the same hunk. That collision is loud and costs a minute. The stale number is neither: it is denormalized into roughly ten files across five languages — `STATUS.md`, `TODO.md`, `SPEC.md`, Rust comments, Svelte, migrations, service YAML, Terraform `description` strings — and a renumber that misses one leaves a reference pointing at an unrelated decision, which reads plausibly and never errors.

**Rationale**: Throughput made a latent problem structural. Jul 24 – Aug 10 averaged 0.61 decisions a day; Aug 11–13 produced 6, 7 and 4, so 18 of the first 70 decisions — a quarter of the file's history — landed in eight days. With about a day of review latency, six or so decisions are in flight at once and a freshly picked number is stale on arrival. Nine of the 47 commits touching this file since July mention renumbering; #546 renumbered three times in one PR and still merged with a subject naming D60 for what shipped as D62, #542's renumber reached this file and none of the six others that cited it, and #547 shipped as D61 while five files kept its authoring number, one of them crediting D62 — a decision from an unrelated PR. Fourteen citations were wrong when this was written, all of them naming a decision that exists. No lint catches that class — both cite numbers that exist — so allocation had to move rather than merely be checked.

Two alternatives were rejected. `merge=union` on this file in `.gitattributes` removes the textual conflict, but that conflict is currently the only thing detecting a duplicate number; without a lint first it trades a loud problem for a silent one. One file per decision under `docs/decisions/`, with this file generated as an index — the `docs/design/INDEX.md` pattern — genuinely removes the textual conflict, but it does nothing about the number being guessed and makes duplicates *more* silent, since `0071-a.md` and `0071-b.md` merge cleanly where a shared hunk would not. It also costs a 70-entry migration plus 169 cross-references. Worth revisiting only if the EOF conflict, now reduced to "keep both placeholders", turns out to still hurt.

## D72: An identifier says who; a name says what to call them — both travel together

**Date**: 2026-08-14
**Decision**: A display name may be supplied alongside the identifier on every surface that names a person. Impersonation gains a companion `X-Overslash-As-Name` header, accepted either literally or in the RFC 8187 `UTF-8''<pct-encoded>` form; it names the **user root only** and is applied in one direction — a root being provisioned now is created with it, a root that exists but has never signed in (`external_id IS NULL`, not an org admin) has it refreshed and audited as `identity.updated`, and an adopted root ignores it entirely. The refresh runs **after** the ACL cap, and re-sending an unchanged name writes nothing. `POST /v1/identities` and `PATCH /v1/identities/{id}` gain a matching `email` field, `user`-kind only, with one live identity per email in an org (`409` on duplicate) and the address changeable only while `external_id IS NULL` (`409` after a sign-in), re-checked under `FOR UPDATE` inside the patch transaction. Names over 128 characters, empty, control-bearing, or undecodable are `400` — never truncated.
**Rationale**: For an agent the identifier *is* the name — the path segment `alice@acme.com/henry` names Henry. For a person it is not, and nothing carried the difference: `user_name_from_email` guessed a label from the local part, so a white-label backend that knew perfectly well it was acting for Alice Smith produced a member called `alice`, visible in the members list, on approval cards, and in `audit_log.actor_name` until her first SSO sign-in overwrote it. **The encoding is the load-bearing detail.** A header value is a byte string: `fetch` isomorphic-encodes it and throws above U+00FF, and `HeaderValue::to_str()` rejects the same bytes server-side, so `José` cannot be sent literally by any browser or Node client — the feature would have worked only for the ASCII half of its users. Percent-decoding *every* value was the alternative and quietly mangles `50% Club`; RFC 8187's prefix is the same trade `Content-Disposition`'s `filename*` already makes, so decoding is opt-in and a literal `%` is safe. The decoder is strict where the common crates are lenient: `%ZZ` is a `400` rather than a pass-through, because a caller that meant to encode and got it wrong should not have the mistake persisted as someone's name. **Adoption is the boundary in both halves**, and for one reason: the OAuth callback adopts a pre-created identity by *verified email*, so the address decides which human can claim the account and the IdP profile is the better source for the name. Before adoption both are placeholders anyone authorized may improve; after it, header traffic must not fight the IdP and an admin must not silently repoint who can claim the row. Org admins are excluded from the header rename even while unadopted — a deliberately narrower guard than "unadopted", since the blast radius is larger and the value smaller. **Ordering against the ACL cap is the security-relevant choice.** Provisioning already ran before the cap and stays there: a row that did not exist a moment ago leaks nothing. A rename does not have that excuse — it writes to a row the request did not create — so `resolve_target` reports the renameable root back and the extractor applies it only once the cap has agreed, which is what stops a refused impersonation from leaving a rename behind on its way to a `403`. The `name <> $3` predicate is not an optimisation either: this runs on the auth path of *every* request, and steady-state traffic sending the same name must not write a row per request. Extending the CRUD API rather than only the header keeps the three admission paths (invite, impersonation, admin create) converging on one row with one set of invariants; `/v1/org-invites` stays the "…and tell them" path, since it sends mail and handles the admin role, and it is the one endpoint that still cannot express a name.

## D73: An action may declare the mode a call defaults to, and a template that declares an impossible one is demoted, not obeyed

**Date**: 2026-08-14
**Decision**: `x-overslash-wait-mode` on an operation or an MCP tool — with `x-overslash-handoff_after_ms` beside it — is rung 2 of the execution-mode cascade, under `CallRequest.execution` and above a floor of `sync`. Resolution is a pure `services::wait_mode::resolve`, shaped like [D56](#d56-call-timeouts-resolve-through-a-five-layer-cascade-clamped-by-two-ceilings-streaming-bounds-time-to-first-byte-not-the-transfer)'s `call_timeout::resolve` and folded once in `call.rs`, below `resolve_request` (where the rung first exists) and above the D56 ceiling, the approval stamp and both dispatch forks. The caller outranks the template in **both** directions: `execution: "sync"` on an action declaring `hybrid` runs synchronously, so the key is a default and never a cap. There is deliberately no service rung, no `orgs` column and no `ActionPatch` — "this export is slow" is per-action knowledge, and a whole-service default would mostly make fast actions defer for nothing; `info.x-overslash-default_wait_mode` stays unclaimed if that is ever wanted. `ExecutionMode` moves from `routes::actions::dto` into `overslash-core` so the compiler and the request share one enum, and `ActionSummary` gains `wait_mode` so the declaration is visible before anyone calls the action. **A template default that cannot be honoured is demoted to `sync` silently**: `prefer_stream`, `deliver: "url"`, `return_url`, `runtime: platform`, a binary response, or `ASYNC_EXECUTION_ENABLED` off each drop the rung, while a *caller* naming the same mode against the same flag still gets the existing 400. `flags::validate_resolved` returns the two template-shaped blockers rather than only refusing on them, so the demotion rule and the refusal rule read the same facts. The handoff rung takes the deployment side of that split — clamped to `[100ms, HYBRID_HANDOFF_MAX_MS]` and to the call's own budget, never refused. `handoff_after_ms` alone is no longer a 400: the check moves to `flags::validate_effective`, after the fold, since against an action declaring `hybrid` it is a coherent request.
**The name is `wait-mode`, not `execution`.** `info.x-overslash-execution` is claimed by `docs/design/policy-engine-mode.md` for external-versus-gateway execution, and two keys of the same name at different positions would be a lint the vocabulary cannot express. The cost is a real one, recorded here because it will confuse someone: the extension key and the request field it defaults have different spellings.

**Rationale**: D56 refused to auto-promote an over-ceiling call and D62 quoted that refusal — a response shape must not change "based on a number in a template the caller never saw". Both predate `hybrid`, and `hybrid` is what makes the refusal worth narrowing. It is the one mode whose surprise is bounded: the caller still gets the answer inline whenever the upstream is fast, and the worst case is a 202 and one extra poll. The status quo for a four-minute action is a 504 at the synchronous ceiling, which is not the safer outcome — it is the same surprise with no result attached. What D56 was really protecting is preserved intact, because the caller can always say `sync` and the envelope names the rung that chose otherwise.

**The demotion is the load-bearing half, and it is not symmetry-breaking for convenience.** It is D56's own clamp-versus-refuse asymmetry moved from a number onto a mode: a caller-supplied value that violates a bound is a 400 because the caller is present and can act on it, while a template default that violates one is narrowed, because the template author is not the caller and a mistyped value that 400s every call in the org is strictly worse than one that quietly does what every call did before the key existed. Refusing instead would make `x-overslash-wait-mode` the first extension key that can take an action *down* — a shipped template tagging a binary-returning export `hybrid` would 400 every call to it, for every org, over an annotation that was inert the day before. That is a strictly larger outage than the bug it would report, which is the argument D67 already settled for the extension lint.

**Silent to the call is not silent to us**, and that is the whole cost of choosing leniency. A demotion emits a `tracing` event naming the blocker, increments `overslash_wait_mode_demoted_total{reason}` — unlabelled by template on purpose, since `reason` is a closed set of six while a template dimension would grow with the catalog on a series that should sit at zero — and the two deferred envelopes carry `execution_mode_source`, skipped when the caller named the mode. Without that field an agent receiving a 202 it never asked for cannot tell "this action defers by declaration" from "something odd happened once", and would have to guess whether to expect the same shape next time. The counter is the only thing that makes a *wrong* declaration visible at all: every affected call still returns 200, so the author's mistake is invisible by construction from the outside.

**No migration.** `approvals.execution_mode` already admits all three values (114) and `ApprovalRow::is_async` already matches `hybrid`, so a gated call whose mode came from a template stamps and queues exactly as an explicitly-named one does — D66 and D68 are unchanged, and a template rung reaching the gate was already the shape they described. Nothing about a deferred call is stored differently for having been declared rather than requested, which is what keeps the rung honestly a *default* rather than a second kind of call.

## D74: Compact keeps the means to fetch the next page — pagination headers survive, and the key cap ranks cursors above the alphabet

**Date**: 2026-08-19
**Decision**: The `verbose: false` render — the **default on MCP** — stops discarding the way forward. Three rules, each with a test, and a fourth that covers the cases where they cannot be honoured. (1) A curated allow-list of response headers survives compaction: `link` (RFC 8288 `rel="next"`), plus `x-next-page` and `x-total-count`. Everything else is still dropped, the map is omitted entirely when nothing matches, and lookup is case-insensitive. The preserved set is bounded by `MAX_PRESERVED_HEADER_BYTES` (1 KB of the 8 KB budget), spent in allow-list order; a header that does not fit is dropped **whole**, never cropped. (2) The object-key cap stops meaning "alphabetically first 20". `truncate` ranks survivors by what a key *is*: `keep_rank` puts a continuation key (`CURSOR_KEYS`, matched after lowercasing and stripping `_`/`-`) first, a non-empty array second, everything else third, ties broken by the map's own order so byte-identical inputs render identically. (3) A cursor-keyed **string** is exempt from string truncation up to `MAX_CURSOR_VALUE_CHARS` (1024) — a `nextPageToken` cropped at the last pass's 40 chars is as useless as one never sent, and worse, it looks usable. (4) `_truncated` changes from `true` to an object, `{"dropped": [...]}`, whose **presence** is the truncation signal and whose list names the load-bearing things that still went: a cursor the cap could not save, a header too large to carry, a body replaced by the placeholder. The list is deduped and capped at ten entries. `render_stored` (D61) therefore gates on presence rather than `== true`, and a response whose body fit but whose `Link` did not is now marked — and stored — because something an agent came for is missing. Separately, `http_caller` stops collapsing repeated response header lines: they combine with `", "` per RFC 9110 §5.3, `set-cookie` excepted.

**Rationale**: Both halves were silent, and silence is what makes them worse than a plain size limit. A cropped list at least announces itself with `…+244 more items`; a dropped cursor announces nothing, and the agent has no way to distinguish "this endpoint has one page" from "the gateway removed the second one". Compact is not an opt-in for the careful — it is what every MCP call gets unless it asks otherwise — so this was the shape of essentially all agent traffic.

The header half is the simpler bug: the module dropped `headers` wholesale on the reasoning that response headers are noise to a model, which is true of `server` and `date` and false of exactly one thing. An allow-list keeps the original argument intact while admitting the exception, and the byte bound is what stops the exception from eating the payload it was meant to make reachable. Dropping an oversized header rather than truncating it is the same judgement applied twice: half a URL is not a smaller cursor, it is a wrong one, and a caller that acts on it gets a 404 instead of an error it can read.

The key-cap half is subtler and was invisible by construction. `serde_json` is built **without** `preserve_order`, so `Value::Object` is a `BTreeMap` and `map.keys().skip(max_obj)` cuts by sort position — `nextPageToken` lost to anything spelled `a` through `m`, deterministically, on every payload with more than twenty keys. The same accident is the real mechanism behind the separately-reported "the truncator spends its budget on metadata before it reaches the rows": nothing in the truncator knew what metadata was, but `metadata` sorts before `rows`.

**Enabling `preserve_order` was the obvious fix and is the wrong one.** It changes map iteration order across the entire workspace — canonical JSON, template normalization and persist, every snapshot and every place a `BTreeMap` ordering is assumed rather than stated — which is a large blast radius for a one-function bug. More decisively, it does not actually fix this: it makes "the first twenty" mean the first twenty the upstream sent, and Google puts `nextPageToken` *after* the `messages` array, so the cursor would still be evicted by the rows it belongs to. Ranking structurally is local, testable in isolation, and targets the property that actually matters — that the cap keeps what is load-bearing rather than what sorts early. `CURSOR_KEYS` is deliberately narrow for the same reason: `limit`, `count`, `total`, `page` and `offset` are ordinary field names in enough payloads that promoting them would evict real data on a false positive, and none of them is what you need to ask for page two.

**This is not the priority-aware truncation TODO.md §3 describes, and does not close it.** That item is about how the *budget ladder* is spent — detecting the principal collection by shape, adding a depth lever so nested descriptor subtrees collapse while their scalar leaves survive. What changed here is only which keys survive a cap that has already fired. A Metabase-shaped payload still renders 10 of 254 rows; what it no longer does is render them without the cursor.

**The marker becoming an object is a wire-shape break, taken deliberately.** `_truncated: true` could say that something went and never what, which left the one in-band signal of a crop unable to carry the fact this decision exists to surface. The break is small — one production call site, a handful of test assertions, and nothing in the SDK or dashboard types it — and paying it now is cheaper than shipping `_truncated: true` alongside a second field meaning "and here is what that cost you".

**The `http_caller` fold is part of the same bug, one layer earlier.** `ActionResult.headers` is a `HashMap`, and collecting the response's header iterator into it keeps only the last of any repeated field line. `Link` legally repeats, so an upstream splitting `prev` and `next` across two lines lost one before compaction was ever reached — preserving the header downstream while dropping half of it upstream would have been a fix that tested green and failed in the field.

This is a prerequisite for the generic-pagination work: a uniform `next` surfaced on top of a pipeline that eats the cursor is worse than no `next` at all, because an agent that can see how to page and then receives a response with the cursor removed will trust the truncated result.

## D75: One vocabulary for paging — the gateway injects the page size, and hands back the next call rather than the upstream's spelling

**Date**: 2026-08-27
**Decision**: `x-overslash-pagination` on an operation or an MCP tool (bare alias `pagination:`) says two things and no more: **which declared parameter bounds a page**, with the bound to use when the caller names none (`page_size: {param, default, max}`), and **how to reach the next page** (`next: {style, param, from}`, plus optional `items` / `has_more` paths). Four styles cover the whole corpus — `cursor` (an opaque value read from a dotted body path: Slack's `cursor`, Notion's `start_cursor`, Google's `pageToken`), `offset` (advance by the page size: HubSpot, Outlook's `$skip`, Metabase), `page` (increment an ordinal: WhatsApp), and `link` (RFC 8288 `rel="next"`, HTTP only — an MCP tool result has no headers, and that combination is refused at compile).

`page_size.default` **seeds the parameter's own `default:`** at compile time when it declares none, rather than adding a second injection path. `validate_input::apply_defaults` then puts it on the wire exactly as a hand-authored default would, and `/v1/search` rows show it for free because D57 already surfaces `ParamInfo.default`. A parameter that declares its own default keeps it; the two disagreeing is a warning, because the parameter is the more specific statement and the one an org layer patches.

A paged result carries `_pagination` beside `_truncated` / `_hint` / `_full_result`: `{has_more, next: {service, action, params}}`, where `params` is the **difference** between the call just made and the next one, in the action's own parameter names. `has_more: false` with no `next` is emitted rather than nothing, so "this was the last page" is distinguishable from "the cursor went missing". `/v1/search` rows gain a bare `paginated: true`; `ActionSummary` gains a fuller `pagination` object, and the service detail page renders a "pages" pill beside D73's `wait_mode` one. The oversized-response 502 hint now names the page-size parameter when the action declares one.

A **stored** call — the async worker's job, an approval replay — is a resolved request, so the action key and the argument map the marker is computed from are gone by the time it runs. The declaration and the arguments therefore ride on the replay payload (`StoredPagination`), which is the same answer D56 gave the timeout cascade for the same reason. Payloads written before the field existed parse to `None` and replay exactly as they did.

The gateway never follows a page. `gmail.yaml` is the only shipped template annotated here; the corpus sweep and the MCP-side templates are a follow-up.

**Rationale**: An agent asked which Metabase cards were popular, found `run_card` (one card) and `list_cards` (all 2,033), and blew the 5 MB cap. D57 fixed that template. This is the platform gap under it: nothing in Overslash read a `Link` header, followed a `nextPageToken`, or knew that `per_page`, `limit`, `page_size`, `maxResults`, `pageSize` and `$top` were six spellings of one idea. Seventeen of thirty-six HTTP-runtime list operations declared no bound at all, and the severe cases are unbounded collections of *rich* objects — `eventbrite.list_event_attendees` is the same shape as the Metabase case, waiting.

**The page-size half is the one that prevents damage, and it needed no new machinery.** `default:` was already load-bearing: `apply_defaults` injects it at call time, so a page-size parameter without one does nothing when the agent omits it — which is the common case, since an agent that has never called an action does not know it should pass a bound. The extension could have carried its own injection pass; seeding the parameter instead means one mechanism, one precedence order (`caller > instance.config > layer > template default`, unchanged), and one place the value is visible. The cost is that the number in the extension is inert when the parameter also declares one, which is why that case warns rather than passing silently.

**`next` is an arg map, not an opaque token.** A token would hide the upstream's vocabulary more completely, and pay for it with a decode path, a tamper surface, and a reserved argument appearing in no action's declared schema — so `validate_args` would need an exception and the dashboard's API Explorer could not replay it. An arg map needs none of that, and an agent can see what it is about to ask for. It carries the delta rather than the full effective argument set for two reasons: bytes, inside an 8 KB compact budget where every field competes with the rows; and disclosure, since echoing the whole set would put resolved instance-config pins and filter arguments back into a model's context on every page.

**Read before the render, never after.** The continuation comes from `ActionResult.body` and `.headers` as they arrived — not from `filtered_body`, so a jq filter that projects the rows out does not also cost the caller the page, and not from the compact render, whose job is to drop things. D74 makes a cursor *survivable* through compaction, which is a weaker promise than never routing the extraction through it. `_pagination` is then handed *into* `compact` rather than stamped after it, so its bytes are measured with the envelope instead of charged to `MARKER_RESERVE_BYTES` — the same discipline D74 applied to the preserved headers, and for the same reason: a marker sized by guesswork eventually pushes the output back over budget.

**A stored call has to be told, because it cannot ask.** `StoredCallRequest` holds a resolved `ActionRequest` — a URL, headers, a body — and its own `timeout_ms` doc already records why: "replay cannot re-run the cascade: it has the request but not the action key the template rungs were read from." Pagination hits that wall twice over, needing the argument map as well, so both travel with the payload and the stored render stamps `_pagination` where `render_stored` would have. Leaving it out would have made `next` present on a synchronous call and absent on the same action called `execution: "async"` — a difference no caller can see, and the exact "worse than not shipping it" failure the issue warned about.

**The gateway does not loop, and this is not a smaller version of looping.** Auto-following would multiply latency, per-page approvals and the size cap by a page count nobody chose, and would have to decide when to stop — a question about the caller's task. Offering the next call keeps every request bounded and leaves that judgement where it can be made. `deliver: "url"` and `Prefer: stream` return before the render funnel and so carry no `_pagination`; that envelope holds a download token rather than rows, and paging is a buffered-path idea.

**`page` must be told where pages start.** A page ordinal has no universal origin — WhatsApp counts from 0, GitHub from 1 — and the parameter's own `default:` is the only place a template says which, so a `page` style whose parameter declares none is a validation error. The runtime deliberately does not fall back to 0 the way `offset` can: an offset of 0 means "from the start" in every API that has offsets, but a guessed page of 0 against a 1-based upstream makes `next` name the page just fetched, and a caller following it re-reads page one forever. A traversal that stops early is a bounded mistake; one that never terminates is not.

**A malformed declaration is dropped, not fatal** — D67's leniency, and D73's before it. An action whose `pagination` block is misspelled goes back to being exactly as unpaged as it was, with an authoring error the template author can see. What is *not* lenient is a `page_size.param` naming a parameter the action does not declare: that is an error, because it reads as a bound and applies none, which is the precise silent unboundedness the key exists to end.

**One exemplar, not a sweep.** `gmail.yaml` was picked over the more urgent unbounded cases because it demonstrates both halves at once — `maxResults` declares no default, and `nextPageToken` sits after the `messages` array, the exact payload D74's key cap was ranked for. Annotating twenty templates in the same change would have made the mechanism hard to review and the template judgements impossible to argue with individually. The follow-up closes with a corpus gate shaped like `shipped_mutating_actions_declare_disclose`.

## D76: Bytes move into a service the same way they move out — a capability the gateway proxies, never the service's own credential

**Date**: 2026-08-31
**Decision**: An MCP action may declare `x-overslash-upload` (bare alias `upload:`), naming a plain-HTTP byte route on the service instance's own origin: `{path, method, filename_param, auth, max_bytes, result}`. An action carrying it is **served by the gateway** — the two dispatch sites intercept it before `mcp_caller::invoke`, so the upstream never sees a tool by that name — and what it returns is a one-shot `upload_url` on `POST|PUT /v1/uploads/{token}`. Redeeming that URL streams the request body through to the byte route with the instance's bearer re-resolved from the vault at that moment. `upload_tokens` is a **separate table** from `download_tokens` and its claim consumes.

The organizing invariant: **everything the reviewer approved is fixed at mint time; the anonymous redemption leg contributes only bytes.** The filename, the route, the ceiling and the declared content all come off the token; the redeemer contributes bytes and at most a `Content-Type` hint.

Optional `sha256` and `size_bytes` arguments bind a capability to one file. Size is enforced *during* the stream and cuts the transfer; sha256 is verified after the last byte and, on a mismatch, the redemption answers 422 and **withholds the upstream's reference** so nothing downstream can name those bytes.

A `media_descriptors` ledger records every descriptor the gateway sees — in *both* directions — and `x-overslash-resolve` grows a non-tool `source: media` target that reads it, so a `send_file` approval's primary row reads `invoice.pdf (application/pdf, 240912 bytes)` instead of `/media/<64 hex>`.

**Rationale**: `services/whatsapp.yaml` said it outright: originating bytes "is out-of-band work for whoever operates the container — not something an agent can do through this service." `send_file` therefore only ever *forwarded* a `media_path` some earlier `download_media` produced. An agent could re-send a file someone sent it and could not send a file it made.

**The direct route — hand the agent the container's URL and token — is the one thing the vault exists to prevent.** There is no narrower credential to mint: the container has a single static `AUTH_TOKEN` with no scopes, audience or expiry, and it authorizes `/mcp`, which is every WhatsApp write. Proxying also buys what the direct route structurally cannot: the gateway sees the descriptor, so it can say what a later approval is actually about.

**The token layer is where the download mirror stops.** `download_tokens` is deliberately multi-use so a dropped transfer can resume with `curl -C -`, and its `claim` bumps a counter unconditionally. Redeeming a download twice re-fetches the same bytes; redeeming an upload twice stores two *different* payloads under one authorization, so "what the reviewer approved" would stop having an answer. Bolting a consume onto a table whose contract is the opposite invites a later change to the shared claim to quietly make uploads replayable — hence a second table, whose declared/stored column split also makes a started-and-abandoned push legible rather than inferable.

**There are two dispatch sites, and the second is the one that matters.** `upload_media` is `risk: write`, so for any gated agent the *first* call is replayed from a stored payload after approval, through `stored_call::run_mcp` — and replay resolves nothing: it holds a URL and a tool name, not an action key, so it cannot look the declaration back up. Intercepting only in `call_mcp::dispatch` would work perfectly until a human said yes, at which point the replay would dispatch `tools/call {name: "upload_media"}` and get `-32603 Unknown tool`. The spec therefore rides on `StoredMcpCall`, the same answer D56 gave the timeout cascade and D75 gave pagination, for the same reason.

**Declaring it as a tool, rather than a platform action, is what buys the approval.** A platform action would give the same in-process dispatch and lose the whole point: `ext::READS` records `Ext::Disclose` as *not* read at `Pos::PlatformAction`, and the `shipped_mutating_actions_declare_disclose` gate skips `Runtime::Platform` for that reason, so the approval would render the bare `{runtime, action, params, service}` projection. The cost is honest and small: the container-catalog drift guard learns a `GATEWAY_SYNTHESIZED` list, teaching it that "exposed" and "served as a tool" are now different sets.

**A hash can be detected, not prevented, and the design says so rather than implying otherwise.** It is not known until the last byte, which is after the upstream has them. Withholding the reference is what makes detecting it worth anything — nothing downstream can name bytes it was never told the name of — but the bytes do linger upstream as an unreferenced orphan, and an operator who believes the check is preventive will not think about that. Size is different and *is* prevented: the meter cuts the transfer mid-stream, and the verdict is read from the meter rather than matched against the transport error's text, because that text arrives as a generic reqwest failure an unknown number of `source()` hops down.

**The ledger write is deliberately not gated on `deliver: "url"`.** The template's own guidance tells agents to call `download_media` *without* it when they want the reference to forward — which is the common case — so recording only on the deferred path would have left exactly the calls that produce references to later approvals unrecorded, and every one of those approvals showing a bare hash. Lifting the jq evaluation above the mint gate costs one already-paid batch on a path that was not paying it.

**`source: media` rides inside `x-overslash-resolve` rather than growing the extension vocabulary.** `ParamResolver` already models mutually-exclusive targets (`get` for HTTP, `tool` for MCP) behind `has_one_target`, and `.resolved.<param>` already reaches the approval projection, the audit `disclosed` block and the dashboard. A new projection key would have meant a second enrichment path with its own template vocabulary, null for every service but one; a heuristic scan for sha256-shaped arguments would have meant enriching a field nobody declared, and the entire value of the enrichment is that a reviewer can trust it. `scope:` is *refused* alongside `source:` — `scope` canonicalizes the permission key, and collapsing every file sharing a filename onto one grant is a silent authorization widening that costs three lines to make unrepresentable.

**Bytes the gateway never handled stay un-enriched, and that is the correct outcome.** A `media_path` pushed to the container out of band is not in the ledger and the File row falls back to the raw path. Probing the upstream at approval time would put a network round-trip and a credential use inside the approval path for a cosmetic gain. The fallback is lossless — the reviewer still sees exactly the string the call will send — so a miss is less helpful, never misleading.


## D77: A `service` is an instance name; a template key is refused, not resolved

**Date**: 2026-09-10
**Decision**: `service` on `/v1/actions/call` and `/v1/actions/validate` names a **service instance**, and nothing else. A key that resolves to no instance but does match a template — `gmail`, `github`, `hubspot` — is now a `ServiceResolution` 400 naming the instances of that template the caller can actually reach, the `create_service` call that adds one, and a dashboard deep-link to the form. The instance-less fallback that used to resolve such a call against the template definition and auto-pick a connection by provider is **removed**; `resolve_service_for_call` is the one place all three call shapes (service+action, verb shape, `/validate`) resolve through, so they cannot drift on it.

**Rationale**: the two namespaces look alike and `overslash_search` returns both — `service: "gmail_work"` next to `template: "gmail"` — so agents reach for the template key routinely. What they got back was not an error about that. The template resolved, auth fell through to `resolve_service_auth`, no connection matched, and the answer was `needs_authentication`: *authenticate this service*, when the caller was already authenticated and had simply named the wrong thing. Agents obligingly started an OAuth dance the user did not need. The one place that answered correctly was the MCP runtime, and only by accident — an MCP template carries no `url`, so config resolution failed first and `mcp_missing_config_error` produced the good message. Every HTTP and OAuth template missed it.

**Refusing outright, rather than only when instances exist.** Keeping the fallback for callers with zero instances would have preserved a working path, but it makes resolution depend on state the agent cannot see: the same call succeeds until someone creates an instance, then starts failing. The narrower rule is also the honest one — an org that has instances has decided how it addresses that service, and a bare template key is ambiguous the moment there are two.

**No auto-routing when there is exactly one instance.** Resolving `gmail` to `gmail_work` because it is currently the only one would make the call's meaning a function of how many instances happen to exist. The agent learns the name once from the error and uses it thereafter; the alternative teaches it nothing and breaks later.

**`overslash` and `http` are not exceptions.** `bootstrap_org` seeds every org a system `service_instances` row whose `name` equals its `template_key`, so both resolve in the instance arm and never reach the guard — the platform meta-service and the raw-HTTP pseudo-service keep working with no special case in the resolver.

**The listed names are ceiling-filtered, and that is load-bearing.** `instance_names_for_template` runs the same group-visibility filter as search, so the error tells a caller what *it* can reach and never reveals that another user has an instance of the same template. An agent denied by a group grant now sees a 400 saying it has no instances rather than a 404 saying nothing exists; both are denials, and the 400 leaks strictly less than a message naming instances would.

**The next step it names now exists.** Every one of these messages used to point at `overslash_auth.create_service_from_template`, which was removed from the MCP surface — agents that followed the hint hit a second dead end. They now name `overslash_call(service="overslash", action="create_service", …)` with the template key filled in, and `ServiceResolution` grows a `hint_url` alongside it for the human, matching the convention `NeedsAuthentication` and `CredentialMissing` already follow.

**Every "fix the instance" message names the call, not just the field.** The `overslash` meta-service is the only lever an agent has — `hint_url` is a dashboard link, which is useful to a human and inert to an agent — so "instance 'x' is missing `secret_name` configuration. Set `secret_name` on the instance" was a dead end of the same shape as the one above. The two config gaps (the MCP `url`/`secret_name` resolver and its HTTP `effective_base` twin) now name `update_service` with the instance id and the missing field filled in. Both are legacy-row paths, since `create_service` validates those fields up front, which is exactly why the message has to carry its own instructions: nobody hitting it is holding the docs.

## D78: An MCP tool's pagination paths address the tool's own payload, not the gateway's envelope

**Date**: 2026-09-11
**Decision**: `services::pagination::next_page` unwraps the MCP result envelope before resolving `from` / `items` / `has_more`, using the projection D55 already settled for `x-overslash-resolve`: `structuredContent` when the server sends it, otherwise the first text content block parsed as JSON. A template therefore writes `from: response_metadata.next_cursor` on a Slack tool and `items: results` on a HubSpot one — the paths a person reading the vendor's docs would write. The unwrap requires all three envelope keys (`runtime: "mcp"`, `tool`, `is_error`), so an HTTP body that happens to carry a `runtime` field is left exactly as it arrived.

With that, the corpus sweep D75 deferred lands: every shipped list action either declares `x-overslash-pagination` or appears in `registry::tests::shipped_list_actions_declare_pagination`'s `ALLOW_MISSING` with a comment naming the upstream reason. The gate calls an action list-shaped when its key says so (`list_*`, `search*`, `query_*`, plus Metabase's two feeds) **or** when it declares a numeric parameter under one of the seven page-size spellings the corpus uses — the second signal is what catches `slack.read_channel_history`, `whatsapp.get_conversation` and `x.get_user_tweets`, which read as single-object gets.

**Rationale**: D75 shipped the extension and annotated `gmail.yaml`, which is HTTP. The first MCP template to declare the key would have found `ActionResult.body` holding `{runtime, tool, structured, content, is_error}` — `mcp_caller`'s envelope — so `from: response_metadata.next_cursor` resolves to nothing and the action reports `has_more: false` on a collection that has more. That is the "partial answer that reads as a complete one" the extension exists to end, arriving through the extension itself.

**The spelling `structured.response_metadata.next_cursor` was the alternative, and it is worse twice over.** It asks every template author to know a gateway-internal frame that no upstream's documentation mentions, and it still fails on the servers that emit only a text block — which is most of them, and not predictable per tool: D55's own rationale is that "servers differ on whether they emit `structuredContent` for the same tool". A template cannot be authored against a shape that varies by deployment, so the projection has to be the gateway's job. It already was, one key over.

**The sweep found two shapes the vocabulary cannot express, and both are allow-list entries rather than extensions to it.** Stripe's continuation is `starting_after=<id of the last object on the page>` — an array-indexed body position, and `dotted` refuses indices on purpose ("a path grammar rich enough to need a parser is a path grammar rich enough to be wrong in a template nobody notices"). `email.search` has a page size and no continuation at all, which `parse_pagination` refuses by design: a page size with no way to reach page two is a limit. Both actions are now *bounded* — `limit` gained a `default:`, and Stripe's `starting_after` is declared so a caller can walk it by hand — and both say in their `description` what the gateway will not do for them. Widening the grammar to swallow one upstream would have cost the property that makes the extension reviewable.

**`page_size.default` is written only where the parameter declares none.** D75 made a shadowed default a warning rather than an error, which left the sweep free to restate numbers; it doesn't. Twenty of the annotated actions already declared their own `default:`, so their blocks name the parameter and stop. The corpus emits no `pagination_default_shadowed`.

**Nine actions declare a style and no `items`, deliberately.** Seven WhatsApp tools and two HubSpot ones page over result shapes belonging to a container the operator runs or a vendor's MCP server, and this repo cannot verify them. A guessed `items` path behaves exactly like an absent one — `structural_has_more` treats a path that resolves to nothing as a fact about the template, not the collection, and keeps offering — so guessing buys nothing and asserts something false. The cost of the honest version is one empty call at the end of a traversal, against a `pagination_unbounded_end` warning that says so.

## D79: A first-level agent is born able to set itself up

**Date**: 2026-09-15
**Decision**: A newly-created **first-level** agent (`kind = 'agent'`, `depth = 1` — a direct child of a user) is seeded with four `permission_rules` allow rows: `overslash:manage_services_own:*`, `overslash:manage_templates_own:*`, `overslash:manage_connections_own:*` and `overslash:request_secrets_own:*`. The seed is gated by a new org column `default_agent_self_setup`, default `true`, exposed on the existing execution-settings endpoint and the `/org` settings card. It is applied at identity-creation time and is **never retroactive**: flipping the flag does not touch an agent that already exists, and there is no *automatic* backfill for agents that predate the change (D80 adds an explicit, admin-triggered one). The rules are ordinary `permission_rules` rows, visible and revocable per agent in the dashboard. Alongside it, `overslash_search` rows for an un-connected service now carry an `auth.setup` array naming the calls that make them callable, and the `credential_missing` / secret-backed `needs_authentication` envelopes carry a `self_serve` field beside `hint_url`.

**Rationale**: Setting up one Metabase instance over MCP cost four approval round-trips — `get_template`, `get_template` again, `request_secret`, `create_service` — for a flow `SKILL.md` documents as an agent doing it itself. Every org's `Everyone` group already grants `overslash: write` (`repos/org_bootstrap.rs`), so Layer 1 has always said yes to these calls; only Layer 2 said no, because nothing has ever seeded a rule for a new identity. `create_permission_rule` had exactly two call sites, both requiring a human: the admin-gated `POST /v1/permissions` and "Allow & Remember" on an approval. The default was not a considered position, it was the absence of one.

**The `_own` half only, and that is the whole safety argument.** This grants exactly the four anchors whose dangerous twin is the *socialisation* step, per [agent-self-management.md §1](docs/design/agent-self-management.md): `manage_services_share`, `manage_templates_publish` and `request_secrets_share` are not seeded, and `request_secrets_share` is annotated in `services/overslash.yaml` as never auto-grantable to an agent. So a seeded agent can build tooling for its owner and cannot hand it to anyone else. Org-level instances still require Admin (`kernels.rs`), grants on non-Myself groups still require Admin (`routes/groups.rs`), the curated-catalog gate (`allow_services_outside_catalog`, default false) is untouched, and a deny rule still overrides every allow — including this one.

**An agent owned by an org admin is not bounded by those `_share` checks, and that is disclosed rather than fixed.** `ctx.access_level` comes from the group ceiling, not from `permission_rules`, so an agent whose owner sits in Admins resolves `AccessLevel::Admin` through the Admins→`overslash: admin` grant and passes every `< Admin` guard. That is the existing, documented meaning of an admin-owned agent; narrowing it here would be re-litigating the ceiling model in a PR about defaults. It is instead named in the `/org` toggle help and on the enrollment consent screen, which is where the person authorizing the agent can act on it.

**`kernel_update_service` needed a guard before this could ship.** It checked only `is_system`: the ownership test lived in `routes::services::require_owner_or_admin`, and the platform/MCP bridge calls the kernel directly. With `manage_services_own` seeded, an agent could rebind *any* non-system instance in the org by id — including its `url`, which points another owner's injected credential at a host the caller chose — with no human anywhere. The hole predates this change (it cost one approval, and "Allow & Remember" on that approval minted precisely the rule now seeded), but making it reachable unattended is what turns it into a regression, so the guard moved into the kernel. It tests the **ceiling user**, not `caller_may_manage_owned`'s ancestry: an agent is deliberately not an ancestor of its own owner-user, so ancestry would refuse an agent the very instance it just created. `kernel_get_service`'s by-id branch got the same treatment — it skipped the ceiling-scoped resolvers the name branch uses, so an id was a probe.

**Depth, not kind, is the test.** `POST /v1/identities` refuses `kind: "agent"` under a non-user parent, but the MCP enrollment path (`routes/oauth/consent.rs`) always writes `kind = 'agent'` while letting the user pick one of their own agents as the parent — a depth-2 agent row. Keying the seed on kind would have silently seeded those. Both guards live inside `bootstrap_agent_in_org` rather than at its call sites, so the three creation paths (REST, enrollment, impersonation provisioning) call it unconditionally and cannot drift apart. The org-service agent is the deliberate non-call: no parent, so `depth = 0`, and its Admins membership already resolves a higher ceiling than these rules would grant.

**The rules never expire.** A TTL would reintroduce the approval storm the change exists to remove, on a schedule. The off-switches are the org toggle and per-agent revocation in the Permission Rules table the agent detail page already renders.

**Permissions were only half the problem.** In the same session the agent did not know `request_secret` existed — it found it only after the human asked whether such a thing existed. Granting a permission an agent cannot discover changes nothing, so the search row for an un-connected service now names the calls that fix it (`auth.setup`), the MCP handshake instructions and `overslash_search`'s description say the agent may run them itself, and the two credential-error envelopes carry `self_serve` beside `hint_url` — the first is the call an agent can make, the second the page a person can open. That split is the same one D77 drew for `create_service` / `update_service`; this extends the sweep to the envelopes it missed.

**The `pending_approval` envelope now names its own next step.** It already carried `auto_call_on_approve`; it now also carries `next_step`, `"get_result"` or `"call_pending"`. Both values are live platform action keys. Under the default (auto-call on) the background replay wins the execution claim race, so an agent that guesses `approval_id` collects a `409 execution has already completed` instead of its own result — which is exactly what happened in the session that prompted this.

## D80: Backfilling the self-setup default is an explicit admin act, never a side effect

**Date**: 2026-09-15
**Decision**: `POST /v1/orgs/{id}/agent-self-setup/backfill` grants D79's four `_own` anchors to every live first-level agent in the org that lacks them. Admin-gated, audited as `org.agent_self_setup.backfilled` with the counts and the patterns, and idempotent. It refuses with a `409` while `default_agent_self_setup` is off. The `/org` **Agent defaults** card grows a button beside the toggle, labelled with how many agents a click would touch (`agents_missing_self_setup`, carried on the execution-settings response the card already fetches) and gated behind a confirm dialog. There is no bulk undo: revocation stays per agent in the existing Permission Rules table.

**Rationale**: D79 applies at identity-creation time and is deliberately never retroactive, which is the right default — a policy change should not silently rewrite the permissions of agents that already exist. But it leaves every org that predates the flag with a population the policy never reached, and the only remedy was granting four rules per agent by hand. The backfill is that remedy, kept as a separate deliberate act: flipping a policy and rewriting every existing agent's permissions are different decisions, and collapsing them into the toggle would make the retroactive case unavoidable rather than chosen.

**Refusing while the toggle is off is the point, not a convenience.** The alternative — a one-off grant independent of the policy — lets an org hand out exactly the privilege it has declined for new agents, and leaves the two controls disagreeing about what the org's position is. The guard lives in the repo statement, so it holds for a direct API caller too; the route re-reads the flag only so the answer is a `409` naming the reason instead of a success that granted nothing.

**Set-based, and it counts agents rather than rules.** One `INSERT … SELECT` over the qualifying agents, so an org with hundreds is one round trip and the write is all-or-nothing. The response reports `agents_granted` and `rules_written` separately because they are not `n` and `4n`: an agent already holding two anchors contributes two rules and one agent. "Grant to 7 agents" is the sentence an admin reasons about, so that is what the button says.

**Idempotency is the statement's, not the schema's — and the statement needs a lock to mean it.** `permission_rules` still has no unique index, deliberately: the two pre-existing writers legitimately re-insert the same pattern with a fresh `expires_at`, so a unique constraint would break "Allow & Remember" refreshing an expiry. That leaves `NOT EXISTS` only as good as the statement's snapshot — under `READ COMMITTED` two overlapping backfills on one org each see the rule missing and each insert it, doubling a rule list that nothing later cleans up. A transaction-scoped advisory lock keyed on the org serializes them, the same device and the same reasoning as `identity::provision`'s get-or-create. Pinned by holding the lock externally and asserting the backfill blocks; racing two real requests does not reproduce the interleaving and passes with the lock removed.

**"Already has this rule" means what the permission check means.** Every `NOT EXISTS` in the seed, the count and the backfill carries `expires_at IS NULL OR expires_at > now()`, matching `permission_rule::list_by_identity`. The seeded rows never expire, so this only bites where a rule on one of the four patterns came from somewhere else with a TTL — `POST /v1/permissions`, or "Allow & Remember". Without the predicate, an agent whose `manage_services_own` grant has lapsed reads as covered while the runtime treats it as ungranted: the catch-up skips precisely the agent that needs it, and the pending count under-reports. The lapsed row is left in place, inert, rather than deleted — it is somebody's record of a decision, and a second live row grants correctly beside it.

**A failed count after a committed write is not a failed write.** Both the backfill and the settings PATCH re-read `agents_missing_self_setup` to label the button. That read is best-effort and the field is omitted when it fails, because by then the rules (or the settings) are committed: answering `500` would tell an admin their change was lost, and the reasonable response to that is to click again. The GET keeps the hard failure — nothing has been written there, so an incomplete answer is just an incomplete answer.

**No bulk undo ships with it.** Asymmetric on purpose: the grant is bounded (four known patterns, first-level agents, never the `_share` half) and the per-agent table already revokes. A bulk revoke is the more dangerous of the two directions — it would need to distinguish a seeded rule from an identical one an admin wrote or an approval remembered, and `permission_rules` records no provenance to distinguish them by. Better absent than wrong.

## D81: `link` pagination reads the next URL from a header *or* the body

**Date**: 2026-09-15
**Decision**: `x-overslash-pagination`'s `link` style keeps its meaning — "the response names the whole next URL; lift out the query parameters the action declares" — and gains two optional fields that say *where* the URL is and *which* key it may introduce. `next.from` is a dotted body path holding the URL; absent, the RFC 8288 `Link` header is read exactly as before. `next.param` names the one query key `declared_query_params` will lift although the call just made did not send it. An MCP tool may now declare `link` provided it declares `from`: a JSON-RPC result has no headers, but it has a payload, and `next_page` already projects it through D78's `mcp_payload` before walking a dotted path.

**Rationale**: Shortcut answers `/api/v3/search/stories` with `{total, data, next}`, where `next` is `/api/v3/search/stories?query=…&page_size=25&next=a8acc65~24` — a URL — while its `next` *parameter* takes only `a8acc65~24`. `cursor` echoes the body value back verbatim, so declaring it would send the upstream a page token that is really a URL; `link` read only the header. Neither could page the action, and it is the one an agent reaches for first. The shape is not Shortcut's alone: Zendesk's `next_page`, Twilio's `next_page_uri` and Salesforce's `nextRecordsUrl` are all whole URLs sitting in a response body.

**This is one style learning a second source, not a fifth style.** What makes `link` `link` is that the continuation is a *URL to be decomposed* rather than a value to be echoed — and that is a fact about the continuation, not about the transport that carried it. Adding a `body_link` style would have duplicated `declared_query_params`, `split_links`' percent-decoding and the type-preservation rule, and left two names for one idea. The old spelling still parses and still means the header, so nothing in the corpus moved.

**`next.param` exists because the intersection rule is otherwise unsatisfiable for a real cursor.** `declared_query_params` emits only keys the call already sent, so a next URL cannot introduce arguments the caller never chose. A continuation key, though, appears for the first time *on page two* by definition. `github.yaml` worked around this by declaring `page` with `default: 1` — a value that is meaningful for an ordinal and not for an opaque token, where the only available default would be an empty `next=` going out on page one. So the exception is stated in the declaration instead: one key wide, named by the author, and already required by `check_pagination` to be a parameter the action declares.

**`MAX_CURSOR_VALUE_CHARS` bounds the lifted key, not the URL.** The cursor arm caps the value it is about to put in the marker; the `link` arm parses its URL and throws it away, so the same cap belongs on the one key that survives without the caller having chosen it — the `param` continuation, applied in `declared_query_params`. Capping the URL instead would have punished exactly the callers this style serves: Shortcut echoes the caller's whole percent-encoded search expression back inside its next URL, so a long-but-legitimate `query` would push it past any ceiling and stop the traversal with `has_more: false`. That is a partial answer that reads as a complete one, which is the failure the extension exists to end, arriving through the extension itself. An empty body value keeps the cursor arm's reading — "no more pages" spelled awkwardly rather than a URL — and the header arm needs no such check, since `link_next` only returns a URL it actually found.

## D82: An alert threshold is not allowed to be a reading of the deployment's own configuration

**Date**: 2026-09-16
**Decision**: The `[P0] API High P99 Latency` policy — `ALIGN_PERCENTILE_99` over `run.googleapis.com/request_latencies` at 5 000 ms — is **deleted**, not retuned, and replaced by `[P1] API Slow Requests`: a PromQL **ratio over a threshold** on the gateway's own `overslash_http_request_duration_seconds`, excluding every path whose duration is set by a configuration knob rather than by the gateway's health. The exclusion set lives once, in `local.gateway_path_exclusions`, because the numerator, the denominator and the rate guard must carry an identical set or the ratio is meaningless. `overslash_http_request_duration_seconds` and `overslash_action_execution_duration_seconds` gain explicit buckets via `set_buckets_for_metric` so they render as real histograms rather than per-process summaries.

**Rationale**: [D68](#d68-a-hybrid-call-is-a-row-that-is-durable-before-it-is-dialled-and-a-hybrid-row-is-failed-never-re-dialled) already kept handed-off calls out of `overslash_action_execution_duration_seconds` on the grounds that folding them in makes "its p99 a reading of the deployment's own config rather than of its upstreams." The Cloud Run alert was committing exactly that error one layer up, and had been since PR #200 — written when the API was CRUD, and left in place as SSE (#504, #542), the D56 timeout ladder (#535) and hybrid calls (#546) landed underneath it. `GET /v1/events/stream` holds every connection for a fixed 30 s **by design** (SPEC.md §10), so each one is a 30 000 ms sample against a 5 000 ms threshold; production pins `CALL_TIMEOUT_MS` to 110 s, so `/v1/actions/call` legitimately runs twenty times the threshold. The alert's p99 was therefore a readout of `EVENTS_STREAM_MAX_CONNECTION_SECS`, and it paged PagerDuty for it.

It is **deleted rather than filtered** because `run.googleapis.com/request_latencies` carries no route label at all — there is no predicate that separates "the gateway is sick" from "somebody opened an SSE connection", and the only remaining lever, the threshold, would have to clear 30 s to be quiet. At that point Cloud Run's own 120 s request cap and the P0 5xx alert have already fired, so the surviving alert would be strictly redundant. The replacement metric was already being emitted: the outermost Axum middleware times `next.run(req).await` — time to response *headers*, not body completion — so an SSE connection records ~0 s there, and `MatchedPath` bounds the `path` label by route count rather than by URL cardinality.

**A ratio, not a percentile**, because production runs `min_instances=1 / max=3` on `db-f1-micro`: a p99 over a 60 s window at that volume is simply "the slowest request that minute", so a single cold start pages. The ratio asks what fraction of requests crossed 2.5 s, which needs an exact bucket edge and no interpolation, and it is paired with a minimum-request-rate guard so one slow request at 3am can never be 100 % of a one-request sample. The `clamp_min` floor is deliberately `0.001` rather than this module's usual `1` — at production volume the denominator is a per-second rate legitimately below 1, and clamping at 1 would silently deflate the ratio toward zero.

**P1, not P0**, on the precedent already set for `upstream_error_rate`: P0 in this repo means users are getting errors or nothing at all. A latency problem severe enough to warrant waking someone *becomes* a P0 on its own, because D56's timeout ladder converts it into a 504 and Cloud Run counts that as 5xx — so a latency P0 is a second page for one incident, arriving earlier and carrying less information. The plausible 3am causes here (`db-f1-micro` contention, running out of three instances, a cold start) are not fixed faster at 3am than at 9am.

**The exporter's default is a trap, and it had already sprung.** `metrics-exporter-prometheus` renders a histogram as a Prometheus *summary* unless buckets are set for it — `{quantile="…"}` plus `_sum`/`_count`, no `_bucket`, no `le`. Nothing in the repo had ever called `set_buckets_for_metric`, which meant the two dashboard widgets querying `histogram_quantile(…_bucket)` had been rendering **empty since the day they were written**, silently, in a module whose whole job is to notice things. Summary quantiles are also computed per process over a sliding window, so with three replicas they cannot be aggregated into a service-level number at all. A unit test now asserts the rendered text carries `_bucket`, `_count`, `le="2.5"` and a `path` label, because every one of those spellings is load-bearing for the alert and a drift in any of them would leave it parsing cleanly and matching nothing — failing open, with nothing anywhere to say so.

Finally, the gate flags are now written into both `infra/env/*.tfvars` even at `false`. `oauth_refresh_alert_enabled` and `upstream_error_alert_enabled` were declared only in `variables.tf`, defaulted `false`, and set in no environment — so both alerts have been dead everywhere since they were written, for the same reason the dashboard widgets were: nothing that an operator reads ever mentioned them.

## D83: A template nominates its own credential probe, and `create_service` mints the link that fills it

**Date**: 2026-09-15
**Decision**: Two halves of one flow. (1) An operation or MCP tool may carry `x-overslash-test` (unprefixed `test:`, `true` or `{ params }`), marking it as the action a service instance runs to prove its credentials work. Template validation makes two rules hard errors: at most one action per template may carry it, and it must be `risk: read`. `POST /v1/services/{id}/test` resolves that action and runs it through the ordinary call path, returning a verdict (`ok` / `failed` / `denied` / `pending_approval` / `needs_authentication` / `not_supported`) carrying status, latency and the upstream error — never the response body. (2) `POST /v1/services` auto-mints a signed, single-use setup link for every unbound per-instance credential slot and returns it as `setup.setup_url`, the exact twin of the `connect.auth_url` it already returns for OAuth templates; `skip_credentials: true` opts out, as `skip_connect` does. Migration 118 adds `service_instance_id` + `credential_key` to `secret_requests` (both-or-neither by check constraint); fulfilling such a request writes the vault secret **and** binds the instance's credential slot. The link opens `/services/setup/{req_id}`, a standalone page that leads with the service and, for a signed-in visitor, runs the probe in place.

**Rationale**: Standing up a secret-backed service took three disconnected moves and ended with nobody knowing whether it worked. An agent following D79's setup hint called `create_service`, then `request_secret`, then handed its user a page reading "paste a value for `resend_key`" — which says nothing about why, or for what. Nothing ever exercised the credential, so the first signal that the key was wrong was a 401 on a real call, minutes or days later. The dashboard wizard had the same gap from the other side: `SecretNamePicker` binds a *name*, and its own hint text said "create it on the Secrets page". OAuth was the one path already joined up, and even there nothing verified the result.

**The setup link is the twin of auto-connect, not a new mechanism.** `kernel_create_service` has always auto-initiated the OAuth dance for an OAuth-backed template and returned the URL to hand over. The secret path simply had no equivalent, which is the whole asymmetry: an agent could finish an OAuth setup in one call and needed two for an API key, the second of which produced a worse page. Mirroring the existing block — best-effort, opt-out by a `skip_*` flag, surfaced as a sibling field on the same response — means an agent that already knows to hand over `connect.auth_url` needs no new rule. The knock-on is that the search setup hint collapses from "create_service, then one `request_secret` per slot" to a single step whose `note` names the field the URL arrives on.

**Additive columns on `secret_requests`, not the `credential_requests` table with a kind discriminator that [agent-credential-provisioning.md](docs/design/agent-credential-provisioning.md) proposes.** That generalization exists to hold OAuth-client collection alongside secrets. The OAuth half of *service setup* is already carried end to end by `oauth_flows` + `service_instances.connection_id`, so a second table would have exactly one kind in it today and a migration either way when the second arrives. The check constraint (`(service_instance_id IS NULL) = (credential_key IS NULL)`) is what keeps the two-column shape honest: a slot key with no instance names nothing, and an instance with no slot key leaves fulfilment with no binding to make.

**The pair is validated at mint, and fulfilment re-derives nothing.** Minting runs as a caller holding `manage_services_own`, with the template in hand; it resolves the slot key (inferring it when the template declares exactly one, refusing with both names when it declares several) and checks the instance is reachable. Fulfilment runs from a public route carrying a signed capability token and *no identity*, so it binds the slot the row names through a narrow `OrgScope::bind_credential_slot` rather than re-entering `kernel_update_service` and its permission checks. Re-entering would mean inventing an identity to satisfy a check that has already happened. The bind is a single `jsonb_set`, not a read-modify-write of the whole map, so two links outstanding on one instance cannot erase each other.

**The probe is not a bypass, and the Test button needs a session.** A public `POST /public/services/setup/{id}/test` running as the instance owner with approvals skipped was the obvious shape and is rejected: it would be a new, permanently-open path to executing an action as someone else, justified only by the caller holding a link. Instead the probe goes through `call_action_impl` unchanged — same permission chain, same Layer-2 gate — and the setup page offers the button only to a visitor with an `oss_session` for the org. This costs nothing in the case the feature exists for: a fresh instance's Myself auto-grant carries `auto_approve_level = 'read'` and the probe is *forced* to `risk: read` by validation, so the owner's own probe auto-approves. An anonymous link recipient sees "Sign in to test" rather than a button that silently elevates.

**`risk: read` and "at most one" are errors rather than lints for the same reason.** The probe fires unattended the moment a credential lands — from the wizard's post-create step, and from the setup page on submit. A write-risk probe is an action nobody chose to run; a second candidate is not a richer template but an unanswerable question about which one the button means. `ServiceDefinition::test_action` still picks deterministically when it finds several, but that exists to keep a row already in the database renderable, not to bless authoring one.

**The verdict carries no upstream body.** "Do these credentials work" is the whole question, and piping an arbitrary response through a button anyone with instance access can press would make a new disclosure surface out of a diagnostic. What it does carry is latency, the upstream status, and a truncated upstream error — enough to tell a wrong key from a service that is merely down. A transport failure reaching the upstream is reported as `failed` rather than a gateway `502`: answering `502` tells the operator *Overslash* is broken when what happened is that their service could not be reached.

**One write path, two pages.** `/services/setup/{req_id}` renders the service and submits to the existing `/public/secrets/provide/{req_id}`. A second POST endpoint would have put the credential-binding step in two places, which is how they drift; the setup page is a framing of the same handshake, not a second protocol. A request with no `service_instance_id` 404s on the setup route and keeps the older page.

**A defaulted required param needs no mention in `test.params`.** Both `/v1/actions/call` and `/v1/actions/validate` run `apply_defaults` before the required check, so demanding that a probe restate Gmail's `userId: me` would make the template say the same thing twice and drift the moment the default changed.

## D84: A SQL permission key names the database twice — by name and by id — and matches on either

**Date**: 2026-09-17
**Decision**: The D42 db label is no longer the operator-pinned `sql_databases` entry with the raw db-key as fallback. It is the database's **own upstream name**, carried into policy through D55's `scope:` channel (`x-overslash-resolve` on the same param that declares `x-overslash-sql-database`), with the pin retained as an override. The raw key does not disappear: `PermissionKey::from_sql_analysis` renders the database as the alternation group `{name,id}`, and `permissions::matching::match_forms` expands it, so one call is covered by a rule written on *either* spelling. Metadata tags carry the same pair as two tags — `db:<name>` and `db_id:<id>` — and the audit `detail.sql` block gains `db_id` beside `db`. `evaluate_sql_policy` splits into `classify_sql` (before resolution, where the instance row still exists) and `finalize_sql_keys` (after it, where the resolved name does).

**Rationale**: `db:4` is what an audit row said about a statement aimed at `reveni-transactional`, while the approval sitting next to it read `Database: reveni-transactional` — the same fact, resolved on one surface and not the other. The pin that was supposed to close that gap is invisible: `sql_databases` was empty on every instance we looked at, so four production databases were labelled `4`, `35`, `71` and `74`, and nothing anywhere said so.

**The objection this reverses was correct, and is answered rather than overruled.** `services/metabase.yaml` and the test `disclosure_names_the_database_while_keys_keep_the_id` both argued that "a grant keyed on a name an upstream admin can rename — or that silently reverts to the id when a 3s lookup times out — is a grant that breaks or aliases without anyone touching Overslash." Both failure modes are real and both are properties of keying on the name *alone*. Keying on the pair removes them: a rename cannot orphan a grant, because the id rung still matches; a resolver that does not answer degrades the key to the id rung rather than re-targeting it; and [D40](#d40-derived-permission-keys-stay-backward-compatible)'s one-way compat rule holds, because every `table=4/…` rule written before this change keeps matching after it.

**Alternation belongs inside one key, not in two keys.** The permission engine requires *every* derived key to be covered by an allow rule, and blocks on *any* key hitting a deny rule. Two separate keys would therefore demand grants on both spellings — the opposite of "either". One key with several match forms gives allow "one requirement, several acceptable spellings" and deny "any spelling blocks", and `match_forms` already existed for exactly this: the value-only compat rung is the same mechanism. Both `check_permissions` and the deny sweep route through `rule_matches`, so neither call site changed.

**`{a,b}`, not a private separator**, because `glob-match` already reads `{a,b}` as alternation in a *pattern*. The key and a rule written from it are then one syntax: a derived key pasted verbatim into a rule covers its own call, and multi-database rules (`table={4,35,71}/public.*`) work with no code at all. The cost is that `{`, `}` and `,` become shape-significant, so `sanitize_db_label` collapses them alongside `/`, `=` and whitespace — `,` matters most, being far likelier in a real database name than either character the sanitizer was originally built for. The same collapse now applies to relation and column identifiers, which a quoted Postgres identifier may legally carry.

**The label is also lowercased and length-capped**, which is not cosmetic: `tags::tag` lowercases and `sanitize_db_label` did not, so a database named `Reveni Transactional` would have tagged `db:reveni-transactional` while keying `table=Reveni-Transactional/…`. That divergence could not arise while labels were numeric ids and arrives the moment they are names.

**Tags spell the pair as two tags, not as a group.** Tag search is exact set containment (`tags @> …`), so a single `db:{name,id}` tag would match neither `?tag=db:name` nor `?tag=db_id:id`; a set says "either" with two elements. Only the scalar pair is doubled — `table:`/`column:` stay on the name, because 24 tables and 24 columns doubled is 96 against a `MAX_TAGS` of 64, and `?tag~` already finds a relation without knowing the label. `db_id:` is the rename-proof search axis: it finds calls from both sides of a rename, which `db:` by construction cannot.

**Residual risk, accepted deliberately.** While a resolver is failing, a *deny* rule written only on the name stops matching, because the name half of the key is what is missing (an id-written deny is unaffected, as is an allow rule, which fails closed by simply not matching). This is narrower than the [D64](#d64-a-cached-resolver-answer-is-an-authorization-decision) hazard it resembles and is bounded by the same cache, and the resolver shares a host with the call it precedes — if `GET /api/database/4` is failing, `POST /api/dataset` is usually failing too. Denies over SQL are best written label-agnostically (`table=*/public.secrets`) or on the id. Fail-closing instead — classifying write and routing to approval whenever a declared resolver misses — was rejected because it converts any upstream blip into an approval storm, and because it would invert `param_resolver`'s documented best-effort contract for every resolver rather than this one.

**`/v1/actions/validate` still runs no resolvers** ([D55](#d55-resolve-scope-canonicalises-the-permission-key-not-the-request)), so the dry run keys on the raw id alone. That is safe *because* of the alternation rather than despite it: the id is one of the spellings the real call answers to, so every key the preview mints is a key the call is covered by. The preview can only read stricter — a name-written grant shows uncovered there and works here — never the reverse.

**The `sql_databases` config survives with two jobs, not three.** It still carries the parse dialect and [D69](#d69-a-select-is-a-read-only-while-every-function-it-calls-is-one)'s `safe_functions`, and `label` remains as an override for anyone who wants a name upstream cannot touch. What it no longer is, is load-bearing: forgetting it now costs a nicer label, not a grant that silently stops matching. A template that declares `x-overslash-sql-database` without a `scope:` resolver on the same param now warns (`sql_database_without_resolver`), because the canonical map is keyed by param name and a resolver on any other param is invisible to the label.

## D85: A setup link never silently replaces a credential

**Date**: 2026-09-20
**Decision**: `service_setup::mint` — the one function `POST /v1/services`' auto-mint, `overslash.request_secret` and `POST /v1/secrets/requests` all pass through — refuses to mint a provide link whose `secret_name` already names a live vault secret. The refusal is `secret_name_conflict` (409), carrying one `conflicts[]` entry per slot with its `credential_key`, `secret_name` and `current_version`, plus a `hint` naming the way out. `force: true` on any of the three surfaces mints anyway; the response then reports what it will supersede (`setup.warnings[]` on a create, a scalar `warning` on the two bare-request surfaces) and the audit row carries `force`. `kernel_create_service` runs the same check **before** it writes the instance row, so a refused create leaves nothing behind. Independently, both public pages read the current version live at load and render an overwrite banner (`overwrites_version` on the provide metadata), which is the last point the truth is available before the write. Alongside it, the instance-name half is squared up: the create path's `constraint().is_some()` catch narrows to the two name indexes by name, `kernel_update_service` gains the same catch (renaming onto a taken name was a 500), and both look the holder up so the message can say *which* row — above all when it is an `archived` one, which keeps its name while the default service list hides it.

**Rationale**: A slot's vault name is the template's `default_secret_name`. It is fixed per template and mixes in nothing per-instance, so the second instance of a template an org had already set up minted a link pointing at the *first* instance's secret. Fulfilment runs through `put_secret`'s `ON CONFLICT (org_id, name) DO UPDATE … current_version + 1`, which cannot tell a rotation from a collision, so the value was replaced and nobody was told. The person opening the link is shown a name, not a history; the agent that minted it had no way to know the name was taken; the owner of the first instance found out when a call started returning 401. Three parties, none of whom could see it.

**The check belongs at mint time, on the write path, and nowhere near the bind path.** Reusing a secret *name* is a feature *(within your own vault; since D119 a name in someone else's vault is neither a conflict nor bindable)*: `SecretNamePicker` exists to bind one, `credentials: {slot: name}` is how an agent does it, and two instances sharing one API key is ordinary. A uniqueness constraint on `secrets.name`, or a refusal to bind an existing name, would have broken the common case to fix the rare one. What is never deliberate is minting a link that **writes** to a name somebody already filled — so that single act is what is gated, and binding is untouched. This is also why the 409's hint leads with the bind escape rather than with `force`: sharing is usually what was meant, and unlike `force` it destroys nothing.

**`force`, not a silent warning, and not an unconditional error.** A warning on the response would have left the overwrite in place and put the notice where the agent reads it and the human does not — the same shape as the bug. An unconditional error would have made rotating a credential through a link impossible, which is a real operation with no other one-call path. `force` splits the two states that were previously indistinguishable at the write: a caller either knows it is replacing a credential or it does not, and the whole defect was that "did not know" was silent. It is deliberately absent from the instance-name conflict, where it would have no safe meaning — nothing is being replaced there, the name is simply occupied.

**The create path checks twice, and the second check is not redundant.** `kernel_create_service` pre-flights before the insert because the auto-mint block deliberately swallows mint failures (D83's best-effort contract, so a shortener outage cannot fail a create). A conflict swallowed that way would have committed an instance and its Myself grant, then returned `200` with no `setup` bundle and no reason — a half-finished service the caller did not ask for. `mint`'s own check stays as the backstop because it is the only function all three surfaces share, and a fourth caller must not be able to reintroduce the silent overwrite by forgetting it.

**The mint-time check cannot close the race, and the page is where that is admitted.** A link minted while a name was free can still be opened after somebody else has filled it. Closing that properly needs the *intent* recorded on the `secret_requests` row and re-checked at fulfilment — a migration and a second refusal path, deferred. What ships instead costs nothing and covers the case that matters: the public pages read the live version at load and say plainly that saving replaces it. That notice is strictly better placed than a mint-time one anyway, because the person reading it is the only party who knows whether the value they are about to paste is the same credential. It warns and does not block, for the same reason.

**A soft-deleted secret does not conflict.** `get_secret_by_name` filters `deleted_at IS NULL`, and the upsert resurrects such a row rather than colliding with it. From the operator's seat the name is free, and the old versions stay behind it either way — so treating a deleted slot as an obstacle would refuse a create for a credential nobody is using.

**The instance-name work is the same defect read from the other side.** `create_service` already answered 409, but by catching *any* constraint violation and reporting it as "already exists" — so a bad `connection_id` foreign key told the caller to rename, which cannot work. `kernel_update_service` caught nothing at all and surfaced a taken name as `500 database error`. And neither unique index carries a status predicate, so an archived instance holds its name while `GET /v1/services` hides it: since `name` defaults to the template key, archiving one `holded` made every later `create_service` for that template fail with no visible cause. Naming the holding row, and saying when it is archived, is what turns that into something an operator can act on.
## D86: A service does not go live until its credential probe passes

**Date**: 2026-09-20
**Decision**: A service instance created by a setup flow is written `status = 'pending_setup'` — a fourth lifecycle value — and becomes callable only when `POST /v1/services/{id}/activate` gets a green verdict from the template's `x-overslash-test` probe. A setup link is always minted `require_user_session = true`, whatever the org's `allow_unsigned_secret_provide` says. Unverified instances are swept after `MAX_LINK_TTL_SECS + sweep_grace` (~24h). The gate defaults on exactly when the kernel mints a setup link, and `verify: true` / `verify: false` on `create_service` force it either way.

**Rationale**: The probe was diagnostic, and that was half a feature. [D83](#d83) gave setup a credential probe and stopped there: `kernel_create_service` committed the instance, fulfilment bound the slot, and *then* a verdict appeared that nobody was obliged to act on — the wizard's exit button said "Continue anyway". So a key with a trailing newline, a key for the wrong account, a key revoked last week all still produced a live, agent-visible, agent-callable service that failed on the agent's first real call. That is the failure D83 set out to remove; it moved it by one step.

**`pending_setup`, not a reuse of `draft`.** `draft` is a state a person parks an instance in deliberately, via `PATCH /status`, and the services list offers it as a filter facet. Sharing one word would mean the sweeper could not tell an unfinished setup from a deliberately shelved instance, and a blanket age purge would start eating the second. The separation is enforced at the API rather than in the schema: `pending_setup` is absent from the status allow-list that `PATCH /status` and `update_service` validate against, so it is a valid *source* status — park it as `draft`, or force it `active` — and never a valid target. Every row in that state was therefore put there by a setup flow, which is what makes a purge predicate keyed on age alone safe without a second marker column.

**It costs almost nothing, because the gate already existed.** Every name-resolution query in `repos/service_instance.rs` filters `status = 'active'`, and `overslash_search` skips non-active rows. A new non-active value is excluded from the call path and from discovery for free. Meanwhile the probe reaches it anyway: `probe::run` addresses the call by `service_id`, and that branch of `resolve_instance_for_call` is an any-status lookup by id. Verify-before-live works *because* those two lookups already disagreed, deliberately. The alternative shapes both lose on exactly this — `verified_at` would have meant adding a second condition to five hot-path queries and two search filters, and a `setup_expires_at` column beside `draft` would have put one invariant under two writers.

**The gate defaults on where a probe runner exists, and nowhere else.** An agent **cannot probe the instance it just created**: `require_owner_or_admin` is `caller_may_manage_owned`, which admits the owner, an ancestor of the owner, or an admin — and an agent is deliberately not an ancestor of its own owner-user. So the default rule restates the auto-mint's own condition rather than approximating it: a probe declared, a slot unbound, an owner to mint for, and no `skip_credentials`. That is the one flow where a human lands on a page we control, holding a session, and their browser can produce a verdict. An OAuth create is left live (the callback is server-side, with no caller to run a probe as), as is a create whose credentials the caller already bound, as is a template that declares no probe. Gating any of those would create an instance only the sweeper could resolve.

**`verify` exists because the structural rule is not quite enough.** The dashboard wizard probes whether or not a link was minted — including when the user named an existing vault secret — so it asks for the gate explicitly. `verify: true` on a probeless template is a `400` rather than a silent downgrade to `active`: answering "fine, it's live" to a caller that asked for verification is how a dashboard comes to report a service checked that nothing ever checked.

**Activation is its own verb, not a side effect of `/test`.** `/test` is a diagnostic the service detail page runs against live instances, and `require_owner_or_admin` admits an org **admin** to instances they do not own — so promote-on-green there would mean an admin sweeping the org's services silently published other people's unverified drafts. Nor is promotion the client's to declare: routing it through `PATCH /status` after a verdict the client claims to have seen would make the whole gate advisory. "Activate anyway" is therefore `activate?force=true` — it runs no probe either, so nothing is saved by going around it, and going around it would skip the `service.activated` event an agent may be blocked on. `PATCH /status` stays reachable as an override, and now writes the audit row it never had, flagging `bypassed_verification` on the one transition worth finding later. `not_supported` promotes, because a template can lose its `x-overslash-test` after an instance was gated on it and refusing forever over a probe that no longer exists is worse than recording which verdict let it through.

**Every activate outcome is a `200`.** A red verdict is the answer to the question the caller asked, not a failure to answer it; a 4xx would make the dashboard render an error where it should render a verdict and a retry.

**A setup link always requires a session.** Less a new policy than the page declining a submission it could not complete: fulfilment is what triggers the probe, the probe runs through `call_action_impl`, and `call_action_impl` needs an identity to evaluate a permission chain against. An anonymous fulfilment could therefore never produce a verdict — it would leave the instance accepted-but-never-live until the sweeper deleted it, with nobody told why. The floor lives in `service_setup::mint`, one-directional (it can only tighten the org's setting) and keyed on `service_instance_id.is_some()`, which is the check constraint's own definition of a setup request. `allow_unsigned_secret_provide` still rules a bare secret request, where the only outcome is a stored value. Links minted before this are unaffected — the column is captured at mint precisely so a policy flip never breaks an in-flight URL.

**The consequence is that the fulfiller is often not the owner, and that is reported rather than hidden.** The probe runs as whoever submits, and a fresh instance's Myself auto-grant belongs to the owner — so a colleague finishing a link gets `denied` and the instance stays gated for its owner to finish. Promotion staying behind owner-or-admin therefore costs nothing that was ever obtainable. The dashboard says so in as many words instead of reporting "saved" and leaving the service quietly dead.

**The purge window is derived from the longest link, not the default one.** `POST /v1/secrets/requests` takes a caller-supplied `ttl_seconds` clamped to `MAX_LINK_TTL_SECS`, so a link can outlive the auto-mint's one-hour default by hours. An unverified instance must outlive every link that could still fulfil it — the `secret_requests` rows cascade with the instance, so sweeping early would delete a live URL out from under whoever was about to paste into it. Measured from `created_at`, not `updated_at`: a credential rebind bumps the latter, so a person pasting a third wrong key would push the deadline out indefinitely and the sweep would never bound the table. `PATCH /status` → `draft` is the escape hatch for a setup that genuinely needs longer.

**The vault secret survives the purge.** `mint_bundle` stores under the *template's* `default_secret_name`, so two Resend instances owned by one user share `resend_key` — deleting it with an instance could pull the credential out from under a different, live service. [D85](#d85) refuses to *mint* into that collision unforced, which narrows the window but does not close it: a `force: true` create deliberately shares the name, and rows that predate D85 already do. `DELETE /v1/services/{name}` leaves secrets alone for the same reason, and a sweeper that destroyed more than the manual delete would be the inconsistency. An orphan row is recoverable; a credential a human typed is not. The sweep emits metrics and a log line, no audit row and no event, matching `subagent_purge` and every other sweep: an audit row records somebody's act, and a sweeper is nobody.

**Two agent-facing contracts had to move with it.** `secret_request.fulfilled` used to mean "your service is callable" — its payload comment said exactly that — and now means "the credential landed", one round trip early. It gains `service_status`, and the terminal signal becomes a new `service.activated` event on a new `services` topic (a new wire string, never an overload, per [D62](#d62)), whose audience includes the `secret_requests.requested_by` set because `chain` walks upwards and the waiting agent is a *descendant* of the owner. And `overslash_search`'s `auth.setup` chain would otherwise tell an agent to call `create_service` again for a template whose gated instance it cannot see — a `409` on the unique name index, which knows nothing about lifecycle status. It now emits a "finish the one you have" chain instead.

## D87: The `services` topic carries the whole fleet lifecycle, and the Live Map refetches rather than renders from the event

**Date**: 2026-09-20
**Decision**: The `services` topic [D86](#d86-a-service-does-not-go-live-until-its-credential-probe-passes) opened for `service.activated` also carries `service.created`, `service.updated` and `service.deleted`. Create and manage are emitted from the kernels (`kernel_create_service`, `kernel_update_service`), so the MCP `create_service` path raises them without a second call site; the status flip and the delete are emitted from the services routes, which is where those two live. The payload is `{service_instance_id, name, owner_identity_id, status, actor_identity_id}` and nothing more — no `icon_url`, no `credentials`, no `test_action`. Audience is `audience::for_service`, which *is* `for_connection`: the owner's chain plus the actor — deliberately **not** D86's `for_service_setup`, which additionally reaches downwards to the agent blocked on a setup link. Emission is unconditional, unlike `activity` ([D58](#d58-the-live-map-rides-a-new-activity-topic-whose-per-call-events-are-emitted-only-behind-a-flag-from-the-one-wrapper-that-already-classifies-the-outcome)). The dashboard subscribes to `approvals,activity,executions,services` and the Live Map refetches its fleet on any of the three, on `stream.resync`, and — as a fallback for an API that does not yet emit them — when traffic names a service its snapshot does not list, once per service id.
**Rationale**: The map holds a *snapshot* of the fleet, and nothing told it when the fleet changed. A service created while the map was open was invisible until a reload: the only incremental path was `action.*`, whose payload carries a service *name* and nothing else, so the first call to a new instance minted a placeholder node keyed by bare name — no owner, hence no `rootOf` entry, hence drawn on the shared org ring **outside its owner's container**; and no `icon_url`, hence a two-letter monogram instead of the catalog mark. Further traffic could not correct it, because every subsequent event resolved to the same unlisted id. The existing self-heal was keyed on the wrong endpoint — it refetched for an unknown *actor* — so a known agent calling a new service never asked.

Refetching rather than enriching the payload is the load-bearing half. The obvious alternative was to widen `action.*` (or `service.created`) with `owner_identity_id` and `icon_url` and have the client mint a correct node in place. But `icon_url` and `test_action` are properties of the **template**, resolved per caller and per deployment `public_url` at read time; freezing them into an event makes the event wrong the moment the template is edited, and an event is a historical fact that must not be re-derived later ([`events/audience.rs`](crates/overslash-api/src/services/events/audience.rs) makes the same argument for visibility). The consumers already state the rule — `dashboard/src/lib/stores/events.svelte.ts` and `sdk/src/controllers/events.ts` both open with "events are notifications, not state; handlers should refetch the resource they care about" — and this is the case that pays for it: one refetch produces a node that is correct in every field, including the ones a payload could not have carried honestly.

Two audiences on one topic is not an oversight. `service.activated` answers a question somebody is *blocked on*, so D86's rule reaches the descendant agent that handed over the setup link — `chain` walks upwards and would otherwise miss it. These three state that the fleet changed shape, which is a fact about the instance rather than an answer anyone awaits, so their audience is the read model: whoever could have listed the instance over REST. Collapsing them onto one rule would either tell agents about instances they cannot list, or stop telling the one agent that is waiting.

Reusing `for_connection` wholesale rather than writing a service-specific rule is deliberate: the two resources have the same ownership shape, and a user-level instance is listed by its owner-user and that user's ancestors, never by its siblings, so the stream must not be wider. Both terms are load-bearing, because owner and actor are routinely *different* identities on this path: an instance's owner is always a user or nobody — a plain create resolves to the caller's ceiling user, and `on_behalf_of` resolves to a user or `validate_on_behalf_of` rejects it — so when an agent creates a service, `chain(owner)` is the term that reaches the user watching their own map (the agent is nowhere on that chain, which runs upwards) and `{actor}` is the term that reaches the agent. Org-level instances reach only the actor, narrower than `GET /v1/services`, which shows them org-wide; that bias is this module's standing one and costs little here, since creating one already requires admin and admins bypass the audience array.

The client-side fallback stays even though the event makes it redundant, because the two cover different failures: the event covers a service created anywhere, the fallback covers a snapshot that is stale for any other reason (a dashboard newer than its API during a deploy, an event missed before a resync). It fires **once per service id** rather than on every call, because "unlisted" has two causes and a refetch fixes only one — an org admin watching calls to a user-level instance they cannot themselves list, and the raw-HTTP pseudo-service, would otherwise ask again every cooldown for as long as the tab is open. The cooldown itself became trailing-edge in the same change: dropping an ask inside the window is what a rate limiter does to traffic it can afford to lose, and this ask is a one-shot signal that the snapshot is wrong.

**Residual risk, accepted deliberately.** `parse_topics` rejects the whole `?topics=` list when it does not recognise one name, so a dashboard that asks for `services` against an API predating [D86](#d86-a-service-does-not-go-live-until-its-credential-probe-passes) gets a 400 and reconnects on backoff until the API catches up. D86 narrowed this window rather than opening it — the topic string already existed by the time the dashboard began asking for it — and the stream recovers on its own. The alternative, silently ignoring unknown topics, would turn a client typo back into a subscription that delivers nothing forever, which is what the loud failure exists to prevent.

## D88: A template can declare its parameter set a floor rather than a fence, per service and per action

**Date**: 2026-09-21
**Decision**: `x-overslash-additional-properties` (unprefixed alias `additional-properties:`), a boolean, readable under `info` as a service-wide default and on an operation or MCP tool as a per-action override. Nearest wins, including when the nearer value is the falsy one, so an operation may write `false` to re-tighten under a service that relaxed globally. When set, `validate_args` stops rejecting arguments the template never declared and stops enforcing `enum` membership; `required` is enforced either way. The default is unchanged — strict — and a malformed value warns and falls back to strict, so the relaxation cannot be granted by a quoting mistake. The two rungs are folded into one `ServiceAction::additional_properties` at compile time rather than resolved per call, unlike the five-rung `timeout_ms` cascade, because there is no per-call or per-org rung to leave room for. **Not read on a platform action**, and the `info` default deliberately does not reach one. A service layer cannot set it: `ActionPatch` is restrictive-only, and an action a layer *adds* declares the key itself or does without.

**Rationale**: The closed world is right for a template we authored and wrong for the ones we cannot author completely. A pasted `tools/list` snapshot, an upstream like HubSpot whose real query surface is wider than the operation we transcribed, and any endpoint whose enum drifts upstream all produce the same failure: the caller knows a parameter the gateway refuses to forward, and the only fix is a template edit and a redeploy. `x-overslash-aliases` covers the *renamed* case; nothing covered the *undeclared* one. The one escape hatch that existed was accidental — `validate_args` returns `Ok(())` when the action declares no params at all — which is all-or-nothing and not something a template could ask for deliberately.

`enum` rides along with the key although JSON Schema's `additionalProperties` governs undeclared keys only. That is a deliberate widening, and the SPEC entry says so, because the two are the same closed-world assumption about a schema we transcribed rather than own: the template that cannot name every parameter is the same template whose enum snapshot has gone stale. Coercion still case-normalizes a near-miss onto its canonical member, so the common repair survives. What the author gives up is the Levenshtein "did you mean" in `ArgError::Unknown` — a misspelled optional param now reaches the upstream instead of returning a self-correctable 400 — which is the real cost and belongs in the authoring decision rather than hidden in it.

Platform actions are excluded for the sharper version of the reason `disclose` / `redact` / `timeout_ms` are: there the reader simply does not exist, and here it would exist and be *wrong*. A platform action is answered in this process against a param set Overslash fully owns, so an undeclared argument would pass the gate and then be silently ignored by the handler — strictly worse than the 400 it replaced.

**One routing gap had to close with it.** `resolve` builds a JSON body only when the operation declares a `requestBody`, so a relaxed non-`GET` action with none would have accepted the undeclared argument at the gate and dropped it a few frames later — the worst of the three outcomes, and the one a caller cannot detect. A body is now synthesized for exactly that case, with `application/json`. It can only fire on arguments that were a 400 before this change, so no existing template changes shape.

The symmetric hole — a declared but *non-JSON* `requestBody`, where only JSON is serialised today — is closed at the other end. Synthesising a JSON payload over a declared `application/x-www-form-urlencoded` would be worse than dropping, because a form endpoint reading JSON fails in a way nobody can debug from the call site. So the combination is simply unauthorable: `check_action` raises `additional_properties_needs_a_json_body`, an error on `unknown_pagination_param`'s reasoning — a promise the gateway believes it kept and never did. The author's two ways out, declaring the body as JSON or dropping the key, are both things only they can choose. The `GET` path needed nothing: `resolve` already routes a param it cannot find in `action.params` to the query string.

**Discoverability is part of the feature, not a follow-up.** A relaxation a model cannot see is one it will not use, so `/v1/search` rows carry `additional_properties` beside `paginated`, on the same argument that bare boolean was added under: it states a fact about what `params` leaves out, which no amount of reading `params` can supply. The dashboard gets the same flag on the action-detail response, because the API Explorer is the user-facing half of this and would otherwise keep enforcing client-side exactly the constraint the server stopped enforcing — a closed `<select>` on an advisory enum, and no way to type an argument the form never heard of.

**Two security properties do not extend to undeclared arguments, and that is the reason this is a per-action opt-in rather than a per-call flag.** Permission-key derivation (`PermissionKey::from_service_action` via `x-overslash-scope_param`) reads declared params only, so an undeclared argument can change what a call does without changing the key the chain checks. And `x-overslash-redact` cannot cover a path it has never seen, so a relaxed action's approval payload and audit row may carry undeclared values in the clear. Both are acceptable when a template author opted in for one action with the upstream contract in front of them; neither would be acceptable as something a caller could switch on.
## D89: `rust-toolchain.toml` stays out of the Docker build context; the `FROM` tag is the toolchain

**Date**: 2026-09-21
**Decision**: `rust-toolchain.toml` is listed in `.dockerignore`. Inside a container image the Rust toolchain is whatever `FROM rust:<ver>-…` provides, and nothing else. `crates/overslash-api/Dockerfile.dev`'s three `COPY rust-toolchain.toml ./` + `RUN rustup show` pairs — the layers that existed to materialize the pinned toolchain — are gone with it. The link the exclusion breaks is restored by `scripts/check-rust-version.sh`, which asserts every `FROM rust:<ver>` across the tracked Dockerfiles carries the same `<major>.<minor>` as the toml's `channel`; it runs in `make check` and as a `lint`-job gate placed before toolchain setup, alongside the line-count gate, so drift fails in seconds on nothing but bash. The toml keeps `profile = "default"` and `components = ["rustfmt", "clippy"]` for local and CI use, where they are wanted.
**Rationale**: rustup does not normalize a partial version onto an installed patch release. We pin `channel = "1.98"`; `rust:1.98-trixie` ships `1.98.1` installed under the *minimal* profile. Those are two unrelated toolchain names as far as rustup is concerned, so the first `cargo` invocation after the toml entered the image synced an entire second toolchain — six components, 1.5 GB on disk, ~15 s — and `profile = "default"` meant it pulled `rust-docs` nobody would ever read. It happened in the `planner` stage (`cargo chef prepare`) and again in the `builder` stage (`cargo build --release`), both of which sit *after* `COPY . .` and are therefore invalidated by every commit, in all three images. No layer cache could absorb it, and with `--cache-to mode=max` (D54) that 1.5 GB was exported to Artifact Registry on each build. Measured against `rust:1.97-trixie` before the 1.98 bump, and reproduced identically after it, which is why the fix is structural rather than a version bump. The cheaper-looking alternative — pin the toml to the exact patch (`1.98.1`) — still costs a lazy component fetch for the missing `rustfmt`/`clippy`, and couples a repo-wide pin that developers and CI read to the patch release Docker Hub happens to ship behind a `1.98` tag; bumping one would silently re-break the other. Setting `ENV RUSTUP_TOOLCHAIN` in each Dockerfile also works and was rejected for the same coupling, in three more places. Excluding the file says the true thing: a release image's toolchain is chosen by its base image. The cost is that two pins must now move together, which is exactly what the gate enforces. Note the artifacts are unaffected either way — the `cargo chef cook` layer survives the toolchain switch, because both names resolve to the same `rustc` and Cargo fingerprints on the version string, so this was pure download and layer bloat, never a hidden rebuild.

## D90: An `object`/`array` parameter declares its shape, and a string may declare that it carries one

**Date**: 2026-09
**Decision**: The loader carries a parameter's nested schema instead of dropping it. `ActionParam` gains `shape: Option<Box<ParamShape>>`, lowered from the schema's own `properties`/`items` by one `openapi::extract::shape::lower_shape` shared by all three lowering sites. `ParamShape` is a deliberately **reduced** JSON Schema — type, `required`, `description`, `enum`, `default`, and the recursion — because nothing would read `format`, `minimum` or `oneOf`, which is the same reason the flat parameter contract carries no more than it does. `NestedParam` is **not** `ActionParam`: a nested property cannot carry `location`, `instance_config`, `aliases`, `resolve` or `sql_field`, and modelling them would advertise behaviour nothing implements. Lowering stops at `MAX_PARAM_SCHEMA_DEPTH = 5`, does not follow `$ref`, and degrades rather than fails — a level past the cap, an `items: {}`, or an object with no `properties` keeps the bare `object`/`array` the param already had. `items: {type: object}` is kept though it declares no properties, because "each element is an object" is the difference between a model sending `["a","b"]` and sending what the upstream wants. `additionalProperties` is read as a **schema as well as a bool**: HubSpot writes its free-form property map as `additionalProperties: {type: string}`, and reading only the bool form would take that as `false` and reject every key the upstream accepts.

At call time the shape is enforced with **exactly the three checks the top level performs** — required present, unknown key rejected, string `enum` respected — at every depth, naming the field by its full path (`createRequest.objects[0].objectType`); `ArgError.field` was already a `String`, so the path needed no new vocabulary and the top-level messages are byte-identical. Type rejection stays out of scope at every depth, so a value whose *kind* does not match the shape is not an error and is simply not descended into: the shape describes a structure, it does not assert one. Relaxation **spreads inward and never back out** — `x-overslash-additional-properties` opens the nested checks, a sub-schema may open itself further with `additionalProperties: true`, and neither can re-close a level its action opened, because `additionalProperties` is absent far more often than it is deliberately `false` and honouring a re-tightening would mostly mean honouring an omission. An array is checked to its first 100 elements: validation is a floor that lets an agent self-correct, not a gate the upstream depends on.

A **string** param may declare `contentMediaType: application/json` (plus `contentSchema`, lowered into the same `shape`), meaning its wire value is a *serialized* document rather than the document itself. The standard JSON Schema spelling is used rather than a new `x-overslash-*` key: a parameter position is open-world in the extension linter, every OpenAPI document we might import already emits it, and there is no vocabulary entry to keep in step. The governing rule is **parse to read, never to rewrite**. `serde_json` is on default features, so its object type is a `BTreeMap` and any parse/serialize round trip re-sorts every key — so structure is serialized **once**, in `coerce_args`, above validation, permission-key derivation, the approval and `replay_payload::build`; a string the caller supplied is **never re-encoded**; validation parses into a read-only view; and a param declaring no `contentSchema` is not parsed for a shape at all, because nobody asked to look inside. `ArgError::NotJson` bites even under `additional-properties`, since that relaxation exists for a stale *enum* and "is this string JSON" cannot go stale. There is **no sniffing**: a string is never parsed because it happens to open a `{`, or a redact path would reach into user data no template ever named.

Of the four hand-rolled dotted-path walkers, only **`redact_at`** learns to descend into such a string. It is the only one where *not* descending is a security bug rather than a missing feature — a lost redaction puts the value on `approvals.action_detail`, `audit_log.detail` and the inline `pending_approval` envelope — and the only one safe to change, because it mutates a display projection that is already not byte-identical to the wire. It descends strictly by declaration (`apply_redactions` takes the declared param names), never on a hunch. `pick_value` and `pagination::dotted` walk upstream *responses*, not call params. `description::lookup` could descend trivially and deliberately does not: a description is the line a human reads to decide, and a placeholder that resolves only when the blob happens to carry that key makes the approval card's meaning depend on attacker-shaped data, rendering as "no value" rather than "we could not look" — `disclose:` is the right surface for that, with `fromjson`, `max_chars` and D65's error discipline. jq surfaces need no change at all: `fromjson` has always been available, and `services/gmail.yaml` already does the harder base64 version.

**Separately**, `x-overslash-scope_param` gains a **mapping entry form** — `{param, label?, extract}` — where `extract` is a jq program over **that param's own value**. This closes the "object-array recipients can't be scoped" debt: Graph's recipients are `[{emailAddress: {address}}]`, so a bare entry files the whole JSON object as the key's value. Rooting at the param rather than at the params map keeps `param` load-bearing, keeps a key's provenance to exactly one param, and keeps the expression short on a surface that is read to make security decisions; a jq program contains `:`, `=` and `|`, so the mapping is a second constructor rather than a second string grammar, and a lone bare entry still serializes as a scalar so every shipped template round-trips byte-identically. Evaluation stays in `overslash-api` and key derivation stays in `overslash-core`, joined by a **typestate**: `ScopePlan::build` is pure and leaves extractor entries `Pending`, `ScopePlan::finish` refuses to produce the `ScopeValues` that `from_service_action` now demands while any remain, so "forgot to evaluate" is unrepresentable rather than a convention two call sites must both remember.

**Failure narrows, never widens.** An `extract` that errors, times out, yields a non-scalar or empty output, or exceeds `MAX_SCOPE_VALUES = 64` mints `{service}:{action}:scope_error={label}/{param}` **and suppresses the `:*` fallback**. The hole this closes is not the fallback itself — a call *needing* `:*` demands a broader rule, not a narrower one — but a **partial** failure: a mixed list whose plain entries resolved would mint a non-empty key set, so no fallback fires, and the failed param's values are simply not in the gate. Silently. Every guard fails the entry rather than truncating it, for the same reason. The sentinel carries its own label and a `/`, and `*` does not span `/`, so neither a `{label}=*` grant nor a plain `{service}:{action}:*` covers it; only the honest `{service}:{action}:**` does, and `{service}:*:scope_error=**` is a typable deny. A failure is an **approval, not a 403** — a template typo must not be an outage with no human path forward — but the approval is **not rememberable**: `suggest_tiers` offers no rung for a sentinel, a `remember_keys` entry whose only coverage is one is refused by name, and a bare Allow & Remember degrades to a one-shot allow, because a standing rule for "we could not tell" would durably authorize every future call that fails the same way. `ScopeExtractError` is fieldless so jaq's operands cannot ride out (D65), and the audit trail is the sentinel key plus a `tracing::warn!` carrying only the class.

One pre-existing hole is closed alongside: `matching::expand_alternations` documents as an invariant that every value in a key has been through `sanitize_key_component`, but `scope_arg` never had — so a scope value spelling `{a,b}` expanded into two forms and a grant for one branch covered a call naming the literal. **Extracted** values now get the full sanitization, because they are content lifted out of caller-supplied structure; **plain** values get only the three alternation metacharacters (`{`, `}`, `,`), because the full version also collapses `/`, which is live in every shipped GitHub key (`repo=overfolder/backend`) and would silently re-target existing grants.

**Rationale**: A template was always *writable* as full OpenAPI, but the compiler reduced every parameter to `(type, enum, default)`. Measured across the shipped corpus that left 21 opaque `object` params, 38 arrays with no item type, and 8 templates authoring a full schema no caller ever saw — while `lower_input_schema`'s own doc comment excused the loss by pointing at a raw `input_schema` field `ServiceAction` does not have. An agent meeting an action on a `/v1/search` row saw `type: "object"` and had to guess, and a guess costs a round trip or an upstream 400 *after* an approval was burned. Two live bugs came out of writing it down: a JSON string sent to an `array` param was comma-split into quoted fragments and sent upstream with no error raised anywhere, and HubSpot's own prose — which two integration tests encoded — put `objectType` on the request rather than on each object, so the template's `Object type` disclose filter had been reading a key that is never present and every HubSpot write approval showed a blank object type. The corpus gate in `registry/corpus_tests.rs` keeps the sweep swept and refuses an `ALLOW_MISSING` entry that has stopped excusing anything; it caught a stale one on its first run. See also D40 (labelled scope keys), D43 (the `column_star` sentinel this borrows its shape from) and D65 (jq operands never leave a redactable surface).

## D91: An API key's org comes from the credential, and an org's first key comes from creating the org

**Date**: 2026-09-22
**Decision**: `POST /v1/api-keys` takes `AdminAcl` plus the `OrgScope` extractor and no longer has an `org_id` field. The org a key lands in is the presented credential's currently *active* org — a session JWT's `org` claim, which `/auth/switch-org` re-mints, or an `osk_` key's own org — and the caller cannot name a different one. `identity_id` is still a caller input, resolved through that same `OrgScope`, so an identity in another tenant is indistinguishable from one that does not exist. The handler's **unauthenticated bootstrap branch is removed**: an org's first admin User and its `osk_` key are minted by `POST /v1/orgs` itself and returned once, as `identity_id` and `api_key` on the creation response. Migration 121 adds `UNIQUE (org_id, id)` on `identities` and a composite `api_keys (org_id, identity_id) REFERENCES identities (org_id, id) ON DELETE CASCADE`, replacing the single-column `api_keys_identity_id_fkey` it subsumes and adding the index that cascade never had.

**Rationale**: The handler built `OrgScope::new(req.org_id, …)` from the request body and never compared it to `acl.org_id`, while the admin branch honoured a caller-supplied `req.identity_id`. The authorization that did happen was resolved from the caller's own credential, so it proved admin-of-A while the write landed in B; `api_keys` had independent foreign keys on the two columns and no composite constraint, so the database did not cross-validate the pair either. An org admin could mint a live key bound to an identity in another tenant. Found by the CASA assessment as **V2** (3.1.2, 3.1.4).

The missing comparison is the symptom. The cause is that one route carried two authorization models: the bootstrap branch — "no keys, no identities yet for this org, so mint its first admin" — has no credential to derive an org from, so it needed an org id in the body, and the authenticated branch then trusted the field the credential-less branch had put there. Validating `req.org_id == acl.org_id` would have closed the hole and left the shape that produced it. Measured on `dev`, `routes/api_keys.rs` was the **only** handler in the routes tree taking its org from `req.*`: 91 handlers take the `OrgScope` extractor and ~70 more construct one by hand from `acl.org_id` / `auth.org_id` / `session.org_id` / `claims.org` or an already-authorized row. The one deliberate cross-org handler, `routes/orgs/billing_admin.rs:76`, is `InstanceAdminAuth` with a `Path(id)` — staff admin, not a body field. The field was an outlier, not a design, so it is gone rather than checked.

Deriving from the credential rather than from the *user* is load-bearing, because a human can belong to several orgs. A user-derived org would reintroduce the same bug in a subtler form: an org-A session would look valid for a request naming org B on the grounds that the user is a member of B. A multi-org human mints into B by being switched to B, which the dashboard already does.

Folding the first key into org creation removes an unauthenticated write from the surface rather than relocating it, and inherits `POST /v1/orgs`'s existing controls for free — `ALLOW_ORG_CREATION`, so a self-hosted operator can lock the surface after setup, and a hard refusal under `cloud_billing` — neither of which the old branch had. The branch was already unreachable in cloud: signup provisioning (`routes/auth/provisioning.rs`) creates the org, the admin identity and the membership together, so `count_identities() > 0` from the org's first instant. What kept it alive was the no-session branch of `POST /v1/orgs`, which deliberately left an org with zero identities for self-hosted first-run and the test harness — and that is exactly the window the old branch was exposed in. It was narrow rather than theoretical: reaching it needed an org's UUIDv4, which is unguessable and returned only to its creator, and any org with a member already had identities. It is now closed by construction.

The key is returned **exactly once**, on the credential-less path only. A creator who came in with a session gets `None` and uses that session; no endpoint reads a key back, and `GET /v1/orgs/{id}` serializes the same `OrgResponse` with the field absent.

The composite foreign key is the layer that survives a future handler regression, which is why it is here rather than left to the two code checks. `identities.id` is already the primary key, so `(org_id, id)` is unique by construction and the added constraint only gives Postgres the index a composite reference demands. The migration **reports** pre-existing mismatched rows through a `RAISE EXCEPTION` naming them rather than healing them: a key bound across tenants is an incident, and deleting the evidence is the wrong default.

## D92: The outbound transport owns its client, and the SSRF hatch opens loopback only

**Date**: 2026-09
**Decision**: `services/http_caller` no longer *accepts* a `reqwest::Client`. Its three entry points — `call`, `call_streaming`, `call_streaming_upload` — build one per request from the URL via `ssrf_guard::outbound_client`. Every action-execution path (Mode A raw HTTP, Mode B/C, replay, deferred download, proxied upload) reaches the wire through those three functions, so "a call cannot dial 169.254.169.254" is a property of the transport rather than a rule five call sites have to remember, and a sixth one added later inherits it. `webhook_dispatcher::deliver` does the same for the registrant's URL on every attempt, first try and retry alike. `state.http_client` survives only for destinations the *deployment* chose (Stripe, the short-URL service, the mailer) and for OAuth/OIDC endpoints that come from a provider row — the residual issuer-discovery surface is tracked in TODO §1.6, not blessed.

A refusal is `CallError::Blocked`, mapped to a **400**, not a 502: nothing left the process, and the caller asked for something we will not do. It writes the same `action.executed` audit row every other transport failure writes, with `detail.error.kind = "blocked"` and the guard's reason — which names a scheme, a host or a resolved IP and never the resolved URL, because on this path the URL carries injected secrets. For the same reason the guard's parse error stopped echoing its input.

**The guard pools its clients.** Per-call construction measures at **~13 ms** on this hardware — `reqwest` loads the system trust store per client — on top of losing keep-alive, which is a fresh TCP + TLS handshake to every upstream on every proxied call. So `outbound_client` runs the full guard (parse, resolve, check *every* returned address) on every call and then reuses a client pinned to the address this call just validated, keyed by `(host, port, ip)` with a 5-minute idle TTL and a 512-entry ceiling. Caching cannot re-open the rebinding window the pin closes, because the validated IP is *in* the key: a hit means this call resolved to exactly what the cached client is pinned to, and a host that moves misses the cache and gets a fresh pin. The per-call deadline stays on the `RequestBuilder`, never on the pooled client, which is what lets calls with different budgets share one.

**One way past the deny-list: `OVERSLASH_SSRF_ALLOWED_CIDRS`, an operator allow-list of CIDR blocks.** The boolean `OVERSLASH_SSRF_ALLOW_PRIVATE` is **gone**. It had to go for two reasons that turn out to be the same reason. A boolean cannot tell "my GitLab on 10.42.0.7" from "the instance-metadata endpoint", so a self-hoster who legitimately needs the first has to grant the second — and Overslash self-hosted beside internal services does have that need, which the deny-list alone refuses outright. And because it was the *test* bypass, the integration suite could never have proven the guard refuses the addresses that matter: the one variable that makes the loopback fakes reachable would have made the metadata endpoint reachable too.

The allow-list answers both. It is read only from the process environment, so no org, user, template or request can widen its own egress and the multi-tenant deployment simply never sets it. It is checked against the **resolved address**, so a hostname that resolves outside every listed range is refused like any other and a rebind cannot smuggle an address in under an allow-listed name. It is specific: allowing one private range does not re-open link-local, CGNAT or the rest of RFC1918. An allowed address is still pinned, and a redirect away from it is still re-checked from scratch. A malformed entry is dropped with a warning rather than widening anything, the accepted set is logged at WARN because an operator deserves to see that this control was loosened and by how much, and an entry overlapping `169.254.0.0/16` earns a second, pointed warning.

**The metadata ranges are denied before the allow-list is consulted.** `169.254.0.0/16` and AWS's IPv6 spelling `fd00:ec2::/32` are refused by `policy_with` *first*, so no `OVERSLASH_SSRF_ALLOWED_CIDRS` entry reaches them — not `169.254.169.254/32`, not `0.0.0.0/0` — and neither do the v4-mapped or v4-compatible IPv6 forms of the same address. The asymmetry is deliberate: every other private range is one internal service, while metadata hands out credentials for the instance's own service account, so a token minted there is the whole deployment. Ordering it ahead of the allow-list rather than subtracting it afterwards means the rule cannot be outranked by a broader entry. The single gate past it, `OVERSLASH_DANGER_ALLOW_METADATA_CIDR`, opens nothing on its own — it only stops the first rule short-circuiting, leaving the allow-list to decide — so reaching metadata takes two separate deliberate acts, and neither reads like a typo. `fd00:ec2::/32` is called out explicitly because it sits inside ULA, so a self-hoster allowing their own `fd00::/8` prefix would otherwise open it by accident. Startup warns on any overlap between the allow-list and those ranges **whether or not** the override is set, and the warning names the variable and says which way it is set, because "is this blocked" is a question about two variables and an operator should not have to hold both in their head.

The suite and `scripts/e2e-up.sh` use that same mechanism — `127.0.0.0/8,::1/128` — rather than a test-only branch, so the tests exercise the code path a real deployment runs. `tests/ssrf_guard.rs` then asserts the refusals *while that is set*, and keeps two loopback positive controls, so widening the list fails a test rather than quietly disarming the file. `OVERSLASH_SERVICE_BASE_OVERRIDES` reads the same allow-list through the same parser, which also closes a smaller hole: under the old boolean, the bypass made *every* override apply, including one pointing at an arbitrary public host.

**Rationale**: The guard was already correct and already used by three subsystems; the vulnerability was that the hot path didn't call it (CASA 5.1.5 / 7.3.1, finding V1 in `docs/compliance/casa/gap-assessment.md`). Wiring it in at each call site would have fixed today's five and left the sixth to chance, which is the shape the bug had in the first place. Whether `Everyone` should hold `admin` on the `http` pseudo-service by default — the grant that makes raw HTTP reachable by every member on day one — is a behaviour change for new orgs and is deliberately left open.

## D93: An empty env var means unset, and one crate owns every read

**Date**: 2026-09
**Decision**: `crates/overslash-env` is the only place the process environment is read. Its accessors trim, and treat an empty or whitespace-only value exactly as they treat a variable that was never exported. `flag()` is the single truthiness rule — `true`/`1`/`yes`/`on` on, `false`/`0`/`no`/`off` off, anything else falls back to the caller's declared default with a warning. A scoped guard test bans `env::var` in the config boundary and the security-relevant lazy readers.

**Rationale**: The convention already existed — D44 said a template variable is "never an empty string", `Config::validate_env` already treated an empty required var as missing — but there was no implementation, so ~130 call sites each decided for themselves. About half filtered empties and half did not, and `validate_env` and `from_env` read the environment twice through different predicates, which is a drift waiting to happen rather than a hypothetical.

The rule is not a style preference. Deployment substrates hand empty strings to processes as a matter of course: Compose renders `${FOO:-}` as `""` for an unset `FOO`, a Secret Manager version can hold an empty payload, a shell pipeline leaves a trailing newline on a key. A presence check — `env::var(..).is_ok()`, or a bare `.ok()` kept as `Some("")` — reads every one of those as "the operator configured this".

Three live consequences, all closed here. `docker-compose.prod.yml` shipped `GOOGLE_AUTH_CLIENT_ID: ${GOOGLE_AUTH_CLIENT_ID:-}`, so a deployment that never configured Google sign-in got a client id of `""`, and per SPEC.md §7 an env-configured IdP outranks DB config and renders read-only — an unset variable broke login *and* removed the dashboard's way to fix it. `DEV_AUTH` was a presence check, so `DEV_AUTH=""`, `DEV_AUTH=0` and `DEV_AUTH=false` all enabled the passwordless-login bypass. And an empty `OAUTH_<P>_CLIENT_ID` short-circuited the BYOC → org-secret → env cascade with a credential of two empty strings, while telling the dashboard `has_system_credential: true`.

Falling back to the *declared default* rather than to `false` on an unrecognised flag value is deliberate: security gates declare `false` and stay closed, while a default-on flag like `MAGIC_LINK_ENABLED` is not silently switched off for a whole deployment by a typo. Either way the operator gets a log line naming the variable and the value.

`OVERSLASH_DANGER_ALLOW_METADATA_CIDR` (D92) already had exactly these semantics; this generalises them rather than inventing them. The crate is a leaf with `tracing` as its only dependency, so `oversla-sh` and `overslash-metrics-exporter` — neither of which depends on `overslash-core` — can use it without paying for a heavy dependency tree in their images.

The guard test is scoped to the modules where a raw read has actually produced a bug, not applied workspace-wide. `template_vars` is the deliberate exclusion: it *discovers* names by scanning `env::vars()` rather than reading one, so no named accessor applies, and it reimplements the rule locally with a comment saying so.
## D94: A template declares alternative auth modes, and an instance picks one at creation

**Date**: 2026-09-22
**Decision**: A template may declare `components.x-overslash-auth-modes`: a map of mode key to `{label, description, schemes, default}`, each naming the `securitySchemes` entries that mode activates. The alternatives are exclusive — an instance picks exactly one, at creation, via `auth_mode` on `POST /v1/services`, and it is stored on `service_instances.auth_mode` (migration 121, nullable, no backfill). Omitted resolves to the mode marked `default: true`; an unknown key is a `400` naming the valid ones. Absent, the block means what every template meant before it existed: one implicit mode holding every scheme, all required together. `ServiceDefinition` grows `auth_for_mode` / `all_slots_for_mode` / `oauth_provider_for_mode` / `resolve_auth_mode`, and every surface that branched on "does this template have *any* OAuth scheme" now reads the template through the instance's mode instead — `resolve_instance_auth`, `derive_credentials_status`, `resolve_effective_scopes`, the auto-connect gate, the setup-link mint, and the principal/badge prefetches. `services/figma.yaml`, `services/github.yaml` and `services/notion.yaml` each gain a token mode, and `services/github_legacy_oauth.yaml` is deleted.

**Rationale**: Figma, GitHub and Notion all accept either an OAuth token or a long-lived token against the same host and the same paths, and the gateway had no way to say so. The data model already tolerated the mix — `auth` is a `Vec<ServiceAuth>` and `check_auth` validates entries independently — but nothing recorded *which* credential an instance used, so every surface guessed, and they all guessed "OAuth" because the test was `template.auth.iter().any(is_oauth)`. The shipped answer was therefore a second template file, which is what `github_legacy_oauth` was.

**The gap was never coexistence; it was that "which one" had nowhere to live.** `resolve_instance_auth` would already have resolved a token-bound Figma instance correctly — its ladder tries the bound slots before the default OAuth connection. What broke was everything around it. `derive_credentials_status` returned `NeedsAuthentication` the moment a template had an OAuth scheme and the instance had no connection, without ever looking at the bound secret; since [D86](#d86-a-service-does-not-go-live-until-its-credential-probe-passes) gates go-live on the credential probe, that instance could never become callable. `create_service` fired auto-connect whenever `template_oauth_provider` was `Some`, so creation always minted an OAuth link and never surfaced the token slot. And the two mint blocks are independent, so a mixed template would have returned *both* `connect.auth_url` and `setup.setup_url` — two handshakes for one credential, with nothing saying which to hand over.

**Stored, not inferred from whichever credential is bound.** Inference is tempting and has exactly one blind spot, which happens to be the only state that matters: a *freshly created* instance has neither credential bound. That is precisely when the badge must say what is still owed and when `create_service` must choose which handshake to mint. Inference has no answer there, and a wrong guess produces an instance whose probe can never pass — the failure D86 exists to prevent, reintroduced one layer up. Nullable with no backfill because every pre-existing row means "the default", which is what `NULL` already says, and a template declaring no modes has only one mode anyway.

**Modes, not OpenAPI's `security:` array**, although a requirement-object array genuinely does mean OR and `services/email.yaml` already leans on the AND reading of a single object. Two reasons. `security:` is consumed in this gateway purely as a *scope* source — `scopes_from_security` takes the first non-empty list, per-operation overriding root — so overloading it would fuse two unrelated meanings into one key, and a token mode has no scopes to contribute. And a requirement object is a bare `{scheme: [scopes]}` map with nowhere to hang a stable key, a display label or a description, all three of which the dashboard picker and the stored column need. What we kept from OpenAPI is the semantics, not the syntax.

**A scheme may belong to several modes; a scheme belonging to none is an error.** The first is what lets a credential shared by every alternative — an org-wide gateway key in front of the real upstream, the shape `email.yaml`'s `gateway` scheme has — ride along with whichever mode was picked, rather than being duplicated per mode. The second is the dual of the existing "a secret nothing reads is dead config" rule: a scheme in no mode is a credential the dashboard will collect and no request will ever carry.

**Binding is template-wide; owing is mode-scoped.** `all_instance_slots` (what a caller may legitimately bind) deliberately spans every mode, while `instance_slots` (what *this* instance still owes) does not. Binding the credential for the mode you are about to switch to is a reasonable thing to do, and a binding for an inactive mode injects nothing because `auth_for_mode` never returns its scheme — so refusing it would buy no safety and make switching a two-step dance. The distinction is why the two functions exist separately rather than one taking an `Option` whose `None` quietly means two different things.

**A token mode never falls back to an ambient connection.** Rungs 3 and 4 of `resolve_instance_auth` — the `use_default_connection` opt-out and the default-connection lookup — are now gated on the mode holding OAuth, and a token mode with unresolved slots returns its missing keys instead. Without that, an instance whose operator deliberately chose a token would silently authenticate as whatever Google or GitHub account that owner happened to have connected, which is worse than failing: it is a call succeeding as the wrong principal. The same narrowing applies to a stale `connection_id` left behind by a previous mode.

**Switching is supported and destroys nothing.** `PUT /v1/services/{id}/manage` takes a new `auth_mode`, keeps both the bound credentials and the connection, drops the instance to `pending_setup` and re-mints the matching handshake; it goes live again only when the probe passes. Keeping both is the same reasoning [D85](#d85-a-setup-link-never-silently-replaces-a-credential) gives for refusing to overwrite a vault secret and D86 gives for leaving secrets behind on a purge — a credential a human typed is not recoverable, and an unused binding costs nothing. It also makes switching back free, which matters because the first reason anyone switches is to find out whether the other mode works.

**`github_legacy_oauth` is deleted rather than kept as a third mode.** This supersedes the retention half of [D17](#d17-builtin-github-service-uses-github-app-user-to-server-oauth): nobody is on it, verified before removal. Folding it in as a mode was the tempting option and is wrong — the two GitHub templates never differed in auth *mechanism*, only in which OAuth client type the org had configured, so they would have been two modes that resolve identically and differ by a scope list. That is a deployment fact about the org, not a choice an operator makes per instance. What the removal costs is the repo's only `x-overslash-hidden` fixture with an OAuth scheme and its only shipped `icon: builtin:<other>` example; the hidden-template tests repoint to `test_email`, and the icon override stays covered by the derived-layer test.

**MCP-runtime templates are deliberately untouched.** `x-overslash-mcp.auth` is a single `kind` discriminator, a separate vocabulary from `securitySchemes` with no notion of alternatives. It still contributes to `has_oauth` exactly as before. Extending modes to it is a clean follow-up and blocks nothing here, because every template that motivated this is an HTTP one.

## D95: An unanswered elicitation is not a denial, and elicitation is on by default

**Date**: 2026-09
**Decision**: MCP approval elicitation ships on by default. Migration 123 replaces `mcp_client_agent_bindings.elicitation_enabled` with `elicitation_opted_out` — storage records only an explicit "no", the platform default lives in code, and the client-capability check moves entirely to request time; existing bindings carry over as opted out. The two negative MCP outcomes stop being synonyms: `decline` resolves the approval as `denied`, and *everything else* — `cancel`, a JSON-RPC error answer, a poll timeout, a disconnect, a sweeper reap — retires the elicitation row, leaves the approval `pending`, and closes the original `tools/call` with the same `pending_approval` envelope the non-elicitation path returns. Repeat prompting is bounded by a per-agent cooldown keyed on the last cancelled row, not by anything per-approval. A caller that did not send `Accept: text/event-stream` is never upgraded to SSE.

**Rationale**: [`docs/design/mcp-elicitation-approvals.md`](docs/design/mcp-elicitation-approvals.md) rejected elicitation as a default in April on the grounds that its failure modes are heterogeneous and one is invisible. The re-probe against Claude Code 2.1.278 (in that doc) shows the client side barely moved — form mode yes since 2.1.76, URL mode still undeclared, `tasks.requests.tools.call` still undeclared — so nothing about *client support* justifies revisiting. What justifies it is that the worst failure mode was ours, not theirs.

Headless and `--print` sessions auto-cancel an elicitation within milliseconds because there is no dialog to render; measured at 6ms. Mapping `cancel` to `deny` therefore resolved approvals as denied that no human ever saw, and the probe run ends with the model telling the user "the call was denied" when nobody denied anything. Default-on would have industrialised that. Separating the two outcomes removes it: a cancel now costs the agent exactly nothing, because it lands back on the URL-reject flow it would have had with elicitation switched off.

That the fallback is the *byte-identical* envelope, built by one shared constructor, is the property worth protecting. An "elicitation was skipped" marker was the obvious alternative and is worse on two counts — it lets the two paths drift, and it adds a field in the model's context that nothing reads and an upstream could try to influence.

The re-prompt bound is per-agent and time-windowed because the per-approval shape cannot work: `permission_gate` mints a fresh approval row per gated call with no dedupe, so a counter hung off an approval never binds, and the replay endpoint 409s unless the approval is already `allowed`, so it cannot re-promote either. A `cancelled` row is the only evidence the protocol offers that this peer cannot answer dialogs. It is predicated on `completed_at` rather than `created_at`, because a row retired by the 300s poll ceiling has an old `created_at` and that is precisely the case where re-eliciting would hang the next call for another 300s.

Distinguishing a headless auto-cancel from a human dismissal by latency was considered and rejected. The threshold does not exist — a focused user dismisses in ~150ms, a loaded client takes longer, and the measurement spans a network hop plus a 500ms poll interval — and it would buy nothing, since both cases want the same immediate behaviour and differ only in how long to back off.

**The column records only the opt-out, and the consent-time capability gate is gone.** `elicitation_enabled` conflated "the user turned this off" with "nobody has said anything yet", and the second is the common case, so migration 123 replaces it with `elicitation_opted_out` and moves the default into code. Dropping the gate matters more than it sounds: `oauth_mcp_clients.capabilities` is written only by `initialize`, which needs a token issued *after* consent, so a freshly-registered `client_id` always has NULL capabilities when consent resolves — and re-registration does not help, because consent reads the new `client_id`'s row. A default AND-ed with `elicitation_supported` is therefore false on every genuine first connect and true only in tests that inject capabilities by hand. The gate looked like defence in depth and was really a bug. The capability check that does the work now lives in exactly one place, `elicitation_eligible`, at request time, where the client has actually declared something.

**Existing bindings are deliberately not backfilled.** They carry over as `elicitation_opted_out = NOT elicitation_enabled`, which makes all of them opted out — none could have been true under the old capability gate. A stored `false` cannot be distinguished from a considered opt-out, and a migration should not turn a live connection's approval surface inside out on a guess; the installed base opts in from the dashboard. Conversely an explicit opt-out survives reauth — including reauth under a re-registered `client_id` — because consent reads the prior binding before the upsert and a missing field inherits it; only a first connect with no prior binding takes the platform default.

Flow B (task-augmented `tools/call`) stays rejected with its revisit condition unchanged. One thing did improve: forcing a `CreateTaskResult` at 2.1.278 is rejected with a clear client-side validation error rather than being silently swallowed, so the original analysis's worst case is gone — but the capability is still not declared, so there is still nothing to build against.

## D96: Outbound service requests require TLS, and the SSRF allow-list is the only exception

**Date**: 2026-09-23
**Decision**: Every request the gateway sends on an action call — Mode A raw HTTP, an HTTP-runtime service, an MCP server — goes over `https`. Plain `http` is refused by `services/outbound_tls.rs` in three places: at the boundary where an endpoint is written (instance `url` on create/update, an org layer's `instance_defaults.url`, a template's `mcp.url`, reported as `endpoint_requires_https`), when a call is resolved, and in the transport on every hop against the address the SSRF guard pinned. The one exception is an address inside `OVERSLASH_SSRF_ALLOWED_CIDRS`, the operator allow-list of D92; there is no separate knob. Uncredentialed Mode A is refused too.

**Rationale**: CASA 4.1.1, and the gap was concrete: `effective_base` used an instance or org `http://` endpoint verbatim, with the vault credential injected into the request.

**Uncredentialed Mode A is not carved out.** It is the one case with nothing to leak today, but "does this call carry a credential" is a question the resolver answers in several places (secrets, a bound connection, a platform gateway credential, a template header) and would have to keep answering correctly as those grow. A single rule is one that cannot drift. An agent that wants a plaintext page can fetch it itself.

**The exception reuses the SSRF allow-list rather than adding a flag.** The deployment that needs plain `http` is the self-hosted one beside its own internal services, and it has already declared that network with `OVERSLASH_SSRF_ALLOWED_CIDRS`. Tying the two together means plaintext is only ever possible to ranges an operator explicitly opened, never to the public internet, and the multi-tenant deployment — which never sets the variable — never speaks plain `http` at all. It also means the integration suite and `scripts/e2e-up.sh`, which allow loopback that way, keep their `http://127.0.0.1` fakes without a test-only bypass. A boolean "allow http" would have been exactly the kind of knob D92 refused.

**The write-time check is a string check, so it defers hostnames.** Without DNS it can only decide an IP literal or `localhost`; a hostname under a non-empty allow-list is accepted and left to the transport, which decides on the resolved address. With no allow-list every `http://` is refused outright, which is the only case the hosted product sees.

**Template `servers[]` are not checked.** They reduce to bare hosts that `effective_base` always dials over `https`, so an `http://` server entry never produces a plaintext request.

**Out of scope, tracked in TODO §1.6:** the MCP OAuth upstream discovery/token endpoints. Webhook delivery is HTTPS-only separately (#664, `services/https_policy.rs`), with a stricter exception — plain `http` to loopback only, not to any allow-listed range. The two rules should converge on one module; which exception wins is a review question.

## D97: A webhook endpoint proves ownership by echoing a challenge, events wait for it, and existing subscriptions are grandfathered

**Date**: 2026-09-23
**Decision**: A new webhook subscription starts `pending_verification`. Registration POSTs a signed `webhook.verification` envelope carrying a random `data.challenge` and waits for the answer (10s); a 2xx with the challenge echoed, as the whole body or as `{"challenge": …}`, makes it `verified`. `POST /v1/webhooks/{id}/verify` re-runs the handshake. Only verified subscriptions are dialed. An event for a pending one is written as a delivery with `held_reason = pending_verification` and released to the retry sweep when it verifies. Every subscription that existed before this was marked `verified` with `grandfathered = true`.

**Rationale**: CASA 7.1.2 — a registrant must not be able to point signed events at an endpoint it does not control.

**Echo, Slack/Dropbox style, not a token the receiver posts back.** An echo in the response needs no second channel and no state on our side between two requests, and it is what receivers already know how to write. The challenge travels in the normal envelope with the normal signature, so a receiver routes it like any other event type.

**The handshake runs inline at registration.** The registrant gets the outcome — and the reason, if it failed — in the same response, and the dashboard can show it without polling. The cost is up to 10s on `POST /v1/webhooks`; the request holds no DB connection across it, the same rule as `deliver`.

**The signature cannot be checked on the first challenge.** The secret is minted by the same `POST` that sends the challenge, so a receiver that insists on a valid signature fails the first handshake; it stores the secret and calls `/verify`. We did not mint the secret in a separate step, or sign the challenge with a key the receiver cannot hold: the echo proves control of the URL, which is the requirement, and the signature is still there for receivers that verify later.

**The challenge names who is asking.** It carries `data.org_id` and `data.subscription_id`, and every request (challenges and events) carries `X-Overslash-Org`. Without that, a receiver answering the challenge unsigned — the path the previous paragraph leaves strict receivers — would verify a subscription any tenant pointed at it; the events that followed would fail its signature check, but Overslash would still be relaying traffic to a site that never agreed to it. With the org id, a receiver echoes only for orgs it knows. This beat a registrant-chosen verify token (Meta's `hub.verify_token`): the receiver already knows its org id, so it needs no new secret, and the value cannot be spoofed in a way that matters, since only a challenge Overslash sends can verify anything.

**Held, not dropped.** The alternatives were to skip the event (it vanishes silently, which a registrant debugging a new endpoint cannot see) or to refuse to enqueue (same thing). A held row shows up in the delivery history, and a receiver that verifies a minute late gets what it missed. Held rows keep `next_retry_at = now()` and the sweep filters on the subscription's status, so a row written in the instant a verification lands is picked up by the next sweep instead of being stranded.

**A failed re-check does not downgrade a verified subscription.** Re-verification is a confirmation, not a probe; a deploy blip on the receiver while someone clicks Verify must not cut a working consumer off. The error is recorded and shown.

**Grandfathering is the compensating control for the existing rows.** Forcing every live consumer to re-verify on deploy would be a flag day for integrations we do not operate. Every grandfathered row was created by an org admin, and the flag is visible in the API and the dashboard until a real handshake clears it. There is no update endpoint, so a URL can never change under a verified row; a new URL is a new subscription and starts pending.

## D98: Webhook signatures cover a per-attempt timestamp, in a new header next to the unchanged legacy one

**Date**: 2026-09-25
**Decision**: Every outbound webhook attempt — first delivery, each retry, the verification challenge — carries `X-Overslash-Timestamp: <unix seconds>` and `X-Overslash-Signature-V1: v1=<hex>`, HMAC-SHA256 with the subscription secret over `"<timestamp>.<raw body>"`. The existing `X-Overslash-Signature: sha256=<hex>` (body only) is still sent, byte-for-byte as before, and is deprecated. Consumers verify `v1`: reject a missing timestamp, reject one more than 5 minutes off, compare in constant time.

**Rationale**: CASA 7.2.3 — a body-only signature lets a captured delivery replay forever. The shape is Stripe's (`<t>.<body>`, `v1=` scheme prefix), which is also what our own Stripe consumer verifies, so receivers already know it.

**A new header, not a new value in the old one.** Stripe puts `t=…,v1=…` in one header; doing that to `X-Overslash-Signature` would break every verifier that expects `sha256=<hex>` there — including our own SDK's, which refuses anything without that prefix. A separate `X-Overslash-Signature-V1` leaves old verifiers working untouched, and is also the permanent home of the new scheme, so dropping the legacy header later is a deletion, not a second migration. The `v1=` prefix stays inside the value so a secret rotation can send two comma-separated `v1` entries without another header.

**The timestamp is its own header, not a `t=` inside the signature header.** One place for it; a verifier that logs deliveries can read it without parsing. It is only meaningful together with the `v1` MAC, which covers it.

**Signed per attempt, not per delivery.** The body stays byte-identical across retries (stable `id`/`created_at` for dedupe), but each attempt is signed with the time it is sent. Otherwise a delivery retried 20 minutes later would fall outside the receiver's window and fail forever, and the tolerance would have to grow to the whole retry horizon — defeating it.

**Grandfathering by keeping the old header, not by a per-subscription flag.** Every receiver keeps working with no migration and no state on our side; the cost is that replay protection is opt-in for a receiver until the legacy header is removed. That removal — announced date, then one deleted line in `send_signed` and a major SDK version — is tracked in TECH_DEBT.md.

## D99: "Allow & remember" over MCP elicitation asks scope and duration in a second dialog

**Date**: 2026-09
**Decision**: The approval elicitation form asks only for the decision (Allow once / Allow & remember / Deny / Ask my parent). Choosing "Allow & remember" raises a follow-up `elicitation/create` on the same SSE response, under an `elicit_remember_<uuid>` id, asking which suggested tier to remember (narrowest by default) and for how long. The first row moves to a new `follow_up` status naming the second; the second row is inserted first so the approval never stops reading as mid-elicitation. Accepting the follow-up resolves `allow_remember` with the picked tier's keys and TTL. Declining or dismissing it retires the row as `withdrawn` and leaves the approval `pending`, as D95 does for an unanswered dialog, but it does not start D95's per-agent cooldown: that cooldown is evidence that a client cannot render dialogs, and a human reaching the second dialog proves this one can.
**Rationale**: MCP form schemas are flat, so the single form showed "If remembering, for how long" next to Deny, and it had no way to pick a scope at all: remembering always saved the exact keys, while the dashboard offers the whole broadening ladder. Merging duration into the decision list would have fixed the first problem but not the second, since a scope field would still show next to Deny. A second dialog costs one extra round trip, and only for the choice that needs it. Tier keys travel as a JSON-encoded string because MCP enum values must be strings and a tier can hold several keys. The value is not trusted: `/resolve` validates it exactly as it does a dashboard pick. Declining the follow-up is not a denial, because the user already said allow and only backed out of the details.

## D100: Boot interlocks key off a parsed `OVERSLASH_ENV`, which the container image defaults to `prod`

**Date**: 2026-09-25
**Decision**: `Config::boot_policy` (`config/boot_policy.rs`) runs after `Config::from_env` and before anything serves. It is keyed off `DeploymentEnv`, parsed from `OVERSLASH_ENV`: unset or `local` is `Local`, and `dev`, `staging`, `prod` and any other marker are deployments. `DEV_AUTH` set to anything that is not a recognised boolean stops the boot in every environment, and `DEV_AUTH` on in `Prod` stops it too. A weak `SECRETS_ENCRYPTION_KEY` or `SIGNING_KEY` (a placeholder, one repeated byte, fewer than 32 bytes, or fewer than 8 distinct byte values) stops the boot in every environment except `Local`, where it only warns. In `Prod`, a `RUST_LOG` that turns on `debug` or `trace` is replaced by `info` and a warning is logged. The production image sets `ENV OVERSLASH_ENV=prod`.

**Rationale**: CASA 6.2.1 / 1.2.1. A check that has to be switched on protects nobody who forgot to switch it on, so the shipped artifact starts out in production mode, and only a deployment that says otherwise (the dev Cloud Run service sets `dev`) runs without the production checks. A source checkout with no `OVERSLASH_ENV` is a developer's machine. Refusing weak keys there too would lock every existing local database behind a re-key, and it would protect nothing that is exposed.

**A weak key warns locally instead of failing.** The alternative was to refuse weak keys everywhere and remove the working values from `.env.example`. That would have broken every existing developer `.env` and every worktree that symlinks one. Removing the values from `.env.example` was done anyway, so a new checkout has to generate keys, and a copied example cannot start a deployment.

**`SECRETS_ENCRYPTION_KEY_PREVIOUS` is not checked.** Moving off a weak key is how you fix one, and that rotation needs the weak key in the previous slot.

**`RUST_LOG` is clamped rather than refused.** An operator who raises verbosity during an incident should see a warning, not a crash loop. The log level is not worth an outage. `DEV_AUTH` and weak keys are the opposite case: running with either one is itself the vulnerability.

**`DEV_AUTH` typos are fatal everywhere.** `overslash_env::flag` already fails closed. The added check exists so that someone who typed `DEV_AUTH=ture` meaning to turn it on, or `DEV_AUTH=of` meaning to turn it off, finds out at boot, rather than getting whichever side the default picks.

## D101: Dependency advisories gate the PRs that change dependencies, and a daily scan owns the rest

**Date**: 2026-09-23
**Decision**: Three scanners run from `.github/workflows/deps-audit.yml` over every lockfile: `cargo-deny` with `deny.toml` (advisories, yanked, licenses, sources), `npm audit --audit-level=high` for `dashboard/` and `sdk/`, and OSV (`osv-scanner.toml`) at every severity. `ci.yml` calls the workflow only when a manifest, lockfile or scanner config changes, and the call rolls into `ci-ok`. A daily schedule runs the same jobs against `dev` and `master`, and a failure opens a `needs-triage` issue via `deps-audit-report.yml`. An advisory may be ignored only with a written reason and a review date at most 90 days out. For `deny.toml` the date sits inside the `reason` and `scripts/check-deny-reviews.sh` enforces it; for OSV it is the native `ignoreUntil`. Security fixes are bumped by hand to the oldest release that carries the fix, so D30's 7-day window still holds. Only a Critical whose sole fix is younger than that may skip it, and the PR must say so. SLAs, ownership and the exception register are in `docs/compliance/casa/dependency-vulnerability-policy.md`. CASA 6.1.1.
**Rationale**: Path-gating keeps an advisory published against an unchanged lockfile from freezing every unrelated merge. It gets an SLA and an issue instead of a repo-wide block, and the daily scan guarantees it is seen within a day. npm audit gates at `high` because it has no per-advisory ignore, so anything it fails on can only be fixed. A no-fix moderate would otherwise leave CI red with no legitimate exit. OSV covers the moderate and low tail, and it does support time-boxed exceptions. It also overlaps the other two on purpose: on its first run it caught a dashboard `devalue` advisory that npm audit had not reported. The 90-day cap exists because cargo-deny has no expiry of its own, and an ignore that is never re-read silently outlives its justification. Tradeoff accepted: a PR can merge while a known advisory sits in an untouched lockfile, for up to its SLA.

**Numbering**: allocated D95 by #661, then #657's merge indented this heading, so the allocator stopped seeing it and gave #657's decision D95 as well. This entry moved instead of that one because every other citation of D95 means the elicitation decision.

## D102: Client IP is the rightmost untrusted address; the Vercel hop is trusted by a shared secret, not by address

**Date**: 2026-09-26
**Decision**: `ClientIp` walks `[socket peer, X-Forwarded-For right to left]` and returns the first address it has no reason to trust. An address is trusted by position (`OVERSLASH_TRUSTED_PROXY_HOPS`, which is 1 on Cloud Run), by range (`OVERSLASH_TRUSTED_PROXIES`, the GCLB address), or, for exactly one hop, because the request carries `OVERSLASH_TRUSTED_PROXY_SECRET` in `x-overslash-proxy-secret`, which the dashboard's Vercel Routing Middleware stamps on every rewrite to the API. With nothing configured, the header is ignored and the socket peer is the client. `X-Real-IP` is not read. All three variables are parsed at boot, and a malformed one refuses the boot.

**Rationale**: CASA gap. The extractor took the leftmost XFF entry, so any caller could pick the address written to audit rows and mint a fresh per-IP throttle bucket per request. Only the right-hand end of the list is written by infrastructure we run.

**Hops and CIDRs, not one or the other.** Cloud Run's frontend has no fixed address but always appends the client, so it can only be trusted by position. The GCLB has a fixed address, and trusting it by CIDR rather than as a second positional hop keeps a caller who reaches `*.run.app` directly (prod ingress is ALL) from having their own forged entry promoted: through the LB the chain is `<client>, <lb>`, and direct it is `<client>`. Either way the first non-LB address is the one Google appended.

**The secret buys one hop, not a trusted range.** Vercel publishes no egress ranges, so without the secret every dashboard request would record a Vercel address and share one magic-link bucket per egress IP. Vercel overwrites XFF with the browser's address, so the one entry behind a vouched hop is trustworthy. The one after it is not, which is why a valid secret skips exactly one untrusted address. The middleware overwrites any client-supplied value and strips the header when unset, so a browser cannot forward its own. We didn't use a Vercel-specific header: `x-vercel-*` request headers can be forged by anyone who calls the API directly.

**Correction (2026-09-28): the vouched hop names the client in its own header; XFF past it is never read.** The paragraph above assumed Vercel overwrites `X-Forwarded-For` with the browser's address, so the entry behind the vouched hop would be Vercel's observation. It isn't. Measured on dev with the secret live: a browser sending `X-Forwarded-For: 203.0.113.66` through `app.dev` had `203.0.113.66` recorded. On an external rewrite Vercel forwards the browser's header and only appends its egress. A middleware override of `X-Forwarded-For` doesn't fix it: the same forged header was replaced on one request and passed through on the next. The request the middleware *sees* is sanitized, though (`x-real-ip` is always the connecting address), and overrides of our own headers were applied in 40 of 40 forged attempts. So the middleware sends that address in `x-overslash-client-ip` next to the secret, and on a secret match the API takes the client from that header and stops walking. With the secret but no parseable name, the client is the vouching hop's own address. Nothing left of a vouching proxy is read, so no forged entry can ride along behind a valid secret.

**Fail-closed on parse, fail-safe on absence.** A dropped CIDR would silently collapse every client behind that proxy into one bucket, so a typo refuses the boot rather than warning. An unset config is the safe direction, since nothing forged is ever believed, so prod only warns about it.

## D103: `/mcp` also speaks MCP 2026-07-28, and its approval dialogs are multi round-trip requests with a signed `requestState` over the existing row

**Date**: 2026-09-26
**Decision**: `POST /mcp` is dual-era.
- **Which era a request uses.** A request that carries `_meta["io.modelcontextprotocol/protocolVersion"]`, or is `server/discover`, is served as 2026-07-28 (`routes/mcp/modern.rs`). Everything else, `initialize` included, takes the unchanged `2025-06-18` path.
- **What a modern request must carry.** The version must be `2026-07-28` (otherwise 400 `-32022`), and `MCP-Protocol-Version` / `Mcp-Method` / `Mcp-Name` must mirror the body (otherwise 400 `-32020`).
- **What a modern request gets back.**
  - `server/discover` advertises `["2026-07-28", "2025-06-18"]`.
  - Every result carries `resultType` and `serverInfo`.
  - `tools/list` and `server/discover` carry `ttlMs` plus `cacheScope: "private"`, because both are per caller.
  - An unknown method is a 404 `-32601`.
  - No session id is minted.
- **Approval dialogs on a modern request.** The dialog is a multi round-trip request, not an SSE `elicitation/create`:
  - The gated `tools/call` returns `input_required`, with the D99 decision form under `inputRequests.decision` and a `requestState`.
  - The client retries with `inputResponses`.
  - The retry runs the same `complete_from_elicitation` the legacy receiver runs, and answers with the result, the `isError` denial, the D99 follow-up (a second `input_required` under `remember`), or the D95 `pending_approval` envelope.
- **What `requestState` is.** An HS256 token (`kind: "mcp_request_state"`) holding:
  - the agent, and the MCP client;
  - the elicitation row id and the step;
  - a SHA-256 of the tool name plus key-sorted arguments;
  - the `pending_approval` envelope;
  - an expiry at the legacy 300s poll ceiling.
- **What the retry checks.** The signature, `kind`, expiry, principal and digest, then that the row still belongs to the agent. The retry never dispatches the call a second time.
- **Capabilities.** Eligibility reads the request's own `_meta` capabilities, and they are also recorded on `oauth_mcp_clients` for the dashboard. A client that lists elicitation modes gets a form only if it lists `form`, in both eras.

**Rationale**: Claude Code (2.1.282+) declares `elicitation: { form, url }` only on a 2026-07-28 connection. It reaches that by probing `server/discover` first, and falls back to `initialize` on any non-modern answer. So URL-mode elicitation for Claude Code starts with speaking this era. That era has no server-to-client requests, which means the approval dialogs had to move onto the multi round-trip request (MRTR) shape before anything else could.

**The dialogs keep the `pending_mcp_elicitations` row rather than going fully stateless.** The row already does jobs a `requestState` cannot:
- it suppresses the approval's auto-call while a dialog is open;
- a `cancel` on it starts D95's cooldown;
- disconnect retires it;
- it makes a duplicate retry idempotent, since `claim` lets only one retry resolve.

The token adds what the retry needs to be served by any replica: the principal binding the spec requires, the envelope for the fallback and the follow-up, and the request digest. The digest stops a genuine state from being pasted onto a different call.

**A modern row nobody retries is left to the existing sweeper.** Until it is reaped, the approval's auto-call stays suppressed for up to the same 360s a dead legacy originator already costs.

**Verified against the real client.** Claude Code 2.1.283 negotiated 2026-07-28 against a local build. In headless mode it cancelled the dialog and got the envelope. Driven as an SDK host answering "Allow once", its retry executed the call. Codex 0.157.0 still negotiates `2025-06-18`, where nothing changed.

## D104: Links the user must open become URL-mode elicitations that wait for the browser flow, and a declined link is never an answer

**Date**: 2026-09-28
**Decision**: When the client declares `elicitation.url`, every tool result that ends with a human opening a browser link is handed to the user as a URL-mode elicitation (`routes/mcp/url_elicitation.rs`), and the call answers only once that browser flow finishes. This is on by default wherever the client can do it. It does not depend on the "Approve in your client" toggle, because that toggle is about answering approvals *inside* the client, and URL mode sends the user out of it.

| Link | Source | Done when | Then |
|---|---|---|---|
| `auth_url` | `needs_authentication`, `reauth_required`, `missing_scopes` | the OAuth callback stamps the flow `completed_at` (migration 126) | the call is **replayed** |
| `provide_url` / setup `requests[]` | `request_secret`, `create_service` | the secret request is fulfilled | the original result is **reported**, marked `url_elicitation: "completed"` |
| `connect.auth_url` | `create_service`, `create_connection` | the flow completes | reported |
| `approval_url` | a permission gap whose form dialog is unavailable (opted out, form not declared) | the approval leaves `pending` | the approved action is **called** |

- **Multiple links.** A multi-slot setup bundle hands over its links one at a time.
- **Which links count.** Auth links count only when they are this server's own `/connect-authorize` URL. Setup and connect links count only from `service: "overslash"` platform results, so upstream data is never mistaken for one.
- **When a hand-off does not complete.** A declined, dismissed, failed or timed-out hand-off (300s, the elicitation ceiling) returns the original body with a `url_elicitation` note: `declined`, `cancelled`, `failed` or `timed_out`.
- **Nothing is resolved by a URL elicitation itself.** A declined approval link leaves the approval `pending`.
- **Approval links and the form dialog.** An approval link holds the approval's auto-call off with the same `pending_mcp_elicitations` row a form dialog uses. It retires that row as `withdrawn` rather than `cancelled`, so it never starts the form cooldown. The cooldown does hold off the approval link, though.

**On a 2025-era connection** the tool call's response is one SSE stream:
- one `elicitation/create { mode: "url", elicitationId }` per link;
- `notifications/elicitation/complete` after each;
- then the result.

The client's accept or decline arrives on a separate POST and crosses replicas through the `mcp_url_elicitations` table (migration 126, purged on the existing elicitation sweep).

**On 2026-07-28** the call answers `input_required` with the link under `inputRequests.url` (no `elicitationId`, which that revision removed), and the plan rides in the signed `requestState` (`url_plan`). The client's retry after accepting waits for the flow, rendered as an SSE response with keep-alives, and answers with the next link or the result.

**Rationale**: Every one of these envelopes already ended with the agent relaying a link and the user coming back to say "done". MCP forbids credentials and OAuth in a form dialog, so URL mode is the only in-client path for them.

**Why the retry waits instead of answering at once.** Answering immediately with "link opened, call again" keeps no connection open. But the model tends to retry at once, and would mint a fresh link and a second prompt. That is what the prompt is meant to prevent. Instead, a connection is held only while a human is actively in the browser flow, bounded by the same ceiling the form dialogs use.

**Why the fallback carries a note.** It is the original envelope rather than an error, so the agent keeps its link, and the note tells it that the user already saw the prompt. Only a real answer (a denial on the dashboard, a failed OAuth callback) ends the call as anything other than that fallback.

**Verified against the real client.** Claude Code 2.1.283, driven as an SDK host on a local build, received the approval as a `mode: "url"` elicitation with no `elicitationId`. Its retry waited on the keep-alive stream until the approval was granted on the dashboard. The call then executed exactly once, even with auto-call on.

## D105: BI is terraform-owned queries, federated into BigQuery, read as a column-allow-listed `bi` role

**Date**: 2026-09-28
**Decision**: Business-intelligence queries over prod data run in BigQuery, against the `overslash_bi` dataset. Each view there is an `EXTERNAL_QUERY` whose inner SQL is a file in `infra/modules/bi/sql/`, run live against Cloud SQL as the Postgres role `bi`. The API creates that role at boot, using a terraform-generated password mounted as `OVERSLASH_BI_DB_PASSWORD`, and replaces its grants with column-level SELECT on `overslash_db::bi::READABLE_COLUMNS`. `bi` belongs to no role. There is no migration, schema or view in Postgres. `tests/bi_views.rs` runs every BI query as `bi` in CI. Dashboards are built in Looker Studio. The whole surface is gated by `enable_bi`. Runbook: `docs/runbooks/bi.md`.
**Rationale**: Cloud Monitoring stores time series, not rows. Putting org names or emails into it would mean log-based metrics that carry personal data, and it still could not show a table. Federation needs no pipeline and no extra service, reads live data, and is controlled by IAM.

**Queries in terraform, not migrations.** A report change should not need an app release. Postgres views would also make every app migration that touches a referenced column drop and recreate them. And views created outside migrations would be worse still: CI never has them, so a migration could pass CI and then fail in prod.

**The allow-list in Rust, applied at boot.** Nothing that runs `tofu` can reach the private-IP instance, so terraform can't issue grants. A `google_sql_user` always joins `cloudsqlsuperuser`, and revoking that needs ADMIN OPTION the app's user doesn't hold. The API already holds a privileged connection at boot, and keeping the list in code puts every widening through review. Revoking the table privilege first also revokes its column privileges, so shrinking the list takes effect on the next boot.

**Tradeoff accepted:** every BI query runs on the primary instance. That is fine at current volume, and Datastream replication is the exit when it stops being fine.

## D107: A directory group is a membership source, not a ceiling

**Date**: 2026-09
**Decision**: An org's own IdP may assert group membership, and that assertion lands in three new tables of its own rather than in `groups`. `directory_groups` records what the directory says exists; `identity_directory_groups` records what it says about one human and is owned outright by sync; `group_directory_sources` is the admin-drawn edge that turns the second into Layer 1 membership. A new view, `effective_identity_groups`, is the single definition of "which groups is this identity in" — `identity_groups` UNION one hop through that edge — and all eight membership read sites go through it. Sync runs only on an enabled `org_idp_configs` row with `group_sync_enabled`, only for `kind = 'user'` identities, and only at sign-in. `org_idp_configs` gains `group_sync_enabled` (default false) and `group_claim` (default `groups`). System groups refuse a directory source. Full design at [docs/design/directory-group-sync.md](docs/design/directory-group-sync.md).

**Rationale**: The obvious shape is to make an external group a fourth `system_kind` under a reserved name prefix, and it is wrong for a reason that only shows up once sync is authoritative. **Authoritative sync has to delete.** If derived membership lives in `identity_groups`, the delete runs against the same table that holds every assignment an admin made by hand, and correctness rests on every current and future writer respecting a `source` discriminator. Split the tables and the same guarantee is structural: `replace_memberships_for_identity` writes one table, that table contains nothing an admin authored, and no bug in it can reach a manual assignment. That is the whole argument — the rest is downstream of it.

Downstream, the split pays for itself twice more. **Name prefixes stop being necessary**: `google:engineering` exists only to dodge `groups_org_id_name_key`, a collision that cannot occur once the two live apart. And **`GET /v1/groups` stays about ceilings**: every surface that lists groups — the picker on service creation, `GroupSearch`, `IdentityPickerModal`, the group list — would otherwise need to learn to exclude a fourth class, which is the tax `system_kind = 'self'` already charges once (`?include_self=`, and the `!= 'self'` filters through `routes/groups.rs`). An org with two hundred Okta groups would bury the three that carry grants.

**Discovery is not granting.** A discovered directory group has no grants and no way to acquire them; it confers access only where an admin has drawn the edge. This keeps the privilege decision where D12 puts every other one — with the org admin — while letting the IdP own the part it is actually authoritative about, which is who belongs together. It also makes many-to-many free: two directory groups can feed one ceiling, and one can feed several.

**A directory group is keyed on its reporter.** `(org_id, source, idp_config_id, external_id)`, not on the name alone. Two IdPs are two trust domains, so a name they both report is two groups; merging them would let one IdP's claim place people in a group the other's users hold, and — because membership is reconciled per `(idp_config_id, source)` — would strand the first IdP's memberships outside its own `DELETE` the moment the second login rewrote the shared row, so a revocation could never land. `NULLS NOT DISTINCT` keeps the future non-login sources collapsing onto one row each.

**An absent claim is not an empty claim.** `None` (key missing, JSON null, or a shape we do not parse) changes nothing; `Some([])` revokes. Collapsing the two would mean an admin renaming a claim in Okta, or an IdP dropping it from a release policy, silently strips every user's derived access at their next sign-in — an org-wide outage triggered by an upstream edit nobody connected to Overslash. This is why the claim is modelled `Option<Vec<String>>` and why a malformed element is skipped rather than voiding the list.

**Only a dedicated `org_idp_configs` row may sync.** A dedicated row already wins over managed sign-in in `org_signin::resolve_org_signin_credentials`, so its presence *is* the statement that this login came through the org's own IdP. A `groups` claim arriving on the Overslash-managed path comes from the operator's shared Google or GitHub OAuth app and says nothing about this org — admitting it would let one tenant's IdP name another tenant's groups, which is exactly what D12 forbids.

**System groups refuse the edge.** Admins is the sharp case: its membership is held in lockstep with `identities.is_org_admin` by `sync_admins_group_tx`, so a mapping would confer org-admin without ever setting the flag and leave the two views disagreeing — admin becomes a thing an IdP hands out. Myself has exactly one member by construction and Everyone already holds the whole org, so a mapping onto either is incoherent or a no-op. `is_identity_in_admins` is deliberately left reading the base table rather than the view, so the guarantee survives even a bypassed handler guard.

**One hop, and a view rather than a copied CTE.** Directory groups cannot contain each other, so the expansion is not recursive and the Layer 1 ceiling query stays a flat join. A view is the single definition; the alternative is the same CTE pasted into eight `sqlx::query!` literals, where one that forgets the second arm produces access that works on one screen and 404s on another. General group-in-group nesting is not built and not blocked.

**Login-time only, and never fatal.** No sweeper: the stale window is a session lifetime, and a periodic re-sync needs a stored org-level directory credential that the OIDC path does not require at all. A sync failure is logged and the sign-in proceeds — being unable to reach the dashboard because an IdP changed a claim shape is a worse outcome than a stale ceiling, which the next login repairs. The ID token is read alongside `/userinfo` because Entra will not release `groups` on the v2 userinfo endpoint; its signature is unverified, which OIDC Core §3.1.3.7 permits for a token fetched directly from the token endpoint over TLS against our own PKCE-bound code, and its `nonce` is checked against the one this login minted. Hardening to `jwks_uri` verification is in TECH_DEBT.md.

## D106: A URL hand-off always ends in an answer that says why, and never hands back a link that is already used up

**Date**: 2026-09-28
**Decision**: This refines D104. Every way a URL-mode hand-off can end now reaches the waiting tool call promptly and is reported.

**Refusals recorded in the browser end the wait at once and are reported as `declined`,** with the reason in `url_elicitation_error`:
- `access_denied`: the provider's own Deny. The callback now accepts an `error=` redirect with no `code` instead of rejecting it at the query extractor, which used to leave the call waiting out its timeout.
- `cancelled_by_user`: the consent interstitial's Cancel, now a `POST /connect-authorize/cancel`. It runs the same connect-gate check as confirm, so only someone who could have continued the flow can cancel it.
- `declined_on_page`: the provide page's Deny, now `POST /public/secrets/provide/{id}/decline`. It uses the link's own token and is advisory: a later submission still fulfils the request.

Other callback failures are reported as `failed` with a coarse, allow-listed reason, stored on the flow (migration 127). A provider error code is relayed only if it fits RFC 6749's character set.

**An auth link is re-run rather than handed back** when it can no longer be opened: it was refused, it failed, or it was opened and then abandoned. The flow was consumed when the user opened it, so the original `auth_url` is dead. Re-running mints a fresh one, and the note rides on the new envelope. A link that is still openable goes back as it is: the client declined it, or it timed out without anyone opening it. That way no second flow is minted and no first one is orphaned.

**Old-protocol clients get `notifications/elicitation/complete` whenever the out-of-band part ended**, whether it succeeded, was refused, failed or timed out. Previously this happened only on success.

**A new-protocol retry that arrives after its `requestState` expired gets an answer rather than a JSON-RPC error.** The signature and binding are still checked, and states more than a day past expiry are rejected. The answer is the D95 envelope for a form dialog, or the plan's fallback marked `timed_out` for a URL hand-off. Nothing is resolved, executed or advanced on the strength of a stale state.

**A new-protocol wait runs on its own task.** A client that drops mid-wait no longer cancels it: the approval's auto-call hold is always released, and an approval granted meanwhile still runs.

**Rationale**: The fallback is only useful if it arrives, and only honest if it is live. A refusal that left the call waiting 300s told the agent nothing for five minutes, and "failed" without a reason cannot be told apart from "the user said no". Handing back a consumed `auth_url` gave the agent a link that could only fail, and with it a loop.

**A stale state is answered, but never acted on.** Its signature proves the server issued it to this caller for this call, so returning the fallback it carries leaks nothing. Acting on it would let an answer outlive the window the spec requires the state to be bounded by.

## D108: Every credential is metered where it authenticates; the pre-credential OAuth surface is metered per IP

**Date**: 2026-09
**Decision**: The `/v1` rate-limit middleware now charges the same principal the auth extractors resolve, in the same order — session cookie, then bearer — not just `osk_` keys. An **MCP access token** is charged exactly like an agent key: the owner-user bucket plus the agent's identity cap. A **dashboard session** is charged to a bucket of its own, `rl:{org}:session:{identity}`, sized by the same user-budget resolution chain (per-user → group → org → `DEFAULT_RATE_LIMIT`) and exempt from the identity cap. The `/oauth/*` + `/.well-known/oauth-*` + `/mcp` subrouter gets a separate layer (`middleware/ingress_rate_limit.rs`): per client IP on the OAuth handshake (`OAUTH_RATE_LIMIT`, 120/60s), a stricter per-IP cap on `POST /oauth/register` (`OAUTH_REGISTER_RATE_LIMIT`, 20/3600s), and per MCP client on `/mcp` (`MCP_RATE_LIMIT`, 600/60s), falling back to the IP bucket when `/mcp` carries no attributable credential. Those three are instance-wide env settings, `0` turns one off, and an unparseable value stops the boot.

**Rationale**: The session is a separate bucket, not the user's shared one, because the shared bucket is the one a runaway agent drains, and the dashboard is where its owner goes to stop it. The session still gets a ceiling, just not one an agent can exhaust. MCP tool calls are charged at `/v1` and not at `/mcp` because `routes::mcp::forward` re-issues each one as a loopback `/v1` request carrying the client's own bearer. Charging there counts each call once, against the same budget as that user's other agents. The advisory `x-overslash-transport` header can't be used to skip the second count, because any caller can set it. The `/mcp` bucket is therefore a transport ceiling on top, and it is what bounds `tools/list`, `ping` and `initialize`, which never reach `/v1`. The OAuth limits are instance-level rather than org settings because the traffic mostly arrives before the caller has proven an org: DCR in particular is anonymous, and every success writes a row. They key on `ClientIp`, so behind a configured trusted proxy a forged `X-Forwarded-For` does not buy a fresh bucket. DCR is checked before the handshake bucket so that a refused registration doesn't spend the budget the rest of that client's flow needs.

## D110: Google Workspace groups are pulled with a delegated service account, bounded by domain, and a partial pull never revokes

**Date**: 2026-09
**Decision**: This refines D107 for a second source. Google releases no group claim, so a Workspace org's groups are read from the Admin SDK Directory API and written to the same `directory_groups` / `identity_directory_groups` tables under `source = 'google_directory'`, `idp_config_id = NULL`. The credential is a service account with domain-wide delegation for `admin.directory.group.readonly` alone, impersonating an admin the org names. It is stored encrypted in `org_google_directory_configs` (migration 129), one row per org, and never returned. Sync runs three ways: a per-user pull spawned at sign-in that the callback never waits on, a sweep every `sync_interval_hours` (default 8), and an admin's *Sync now*, of which at most one can be queued. Mapping is unchanged: a Google group grants nothing until an admin draws the edge. Full design in [docs/design/directory-group-sync.md](docs/design/directory-group-sync.md).

**Rationale**: D107's "login-time only" held because the claim path had no credential to sweep with; this source does, so the stale window no longer has to be a session lifetime, and removals in Google land without the removed person signing in. Everything else follows from keeping D107's guarantees under a writer that pulls instead of being told.

**A service account, not an admin's OAuth consent.** Consent binds sync to one person: it stops when they leave or lose the admin role, and a sweep has nobody signed in to refresh as. Delegation is granted by the org's Workspace admin, scoped to one read-only scope, and outlives any individual.

**The key's `token_uri` is ignored.** Assertions are exchanged only at `https://oauth2.googleapis.com/token`. Honouring the field would let whoever uploads a key send a signed, replayable assertion for the org's Workspace to a host of their choosing.

**Domains, not sign-in path, bound whom it speaks about.** D107 limits the claim path to an org's own IdP because the claim rides a login. A delegated credential is already the org's own, so it may speak about the org's humans whichever IdP they signed in through — but only those whose email falls under a configured domain. Anyone else is never touched.

**A partial listing never revokes.** The sweep is authoritative, so it must distinguish "Google says no" from "Google did not answer" exactly as D107 distinguishes an empty claim from an absent one. Every page of every listing must succeed before any membership row changes; otherwise the run records its error and revokes nothing.

**Direct membership only.** The per-user endpoint reports direct groups; expanding nesting in the sweep alone would make membership flap between sign-in and sweep. It also keeps D107's single hop.

**At most one queued manual run, structurally.** The queue is one nullable column that a click sets only if unset and a claim clears. Repeated clicks cannot pile up sweeps against Google's quota, and a click during a run still gets its follow-up.

## D109: A rate-limit deny is logged once per bucket per window, under a global budget

**Date**: 2026-09
**Decision**: Every deny is counted in `overslash_rate_limit_decisions_total`. It is logged only when it is the request that takes its bucket over the limit (`RateLimitResult::first_denied`, `count == max + 1`), and then only while a fleet-wide budget of 60 lines a minute lasts. The budget is `rl:deny-log-budget` in the same store. A line dropped for budget increments `overslash_rate_limit_deny_log_suppressed_total{scope}`. Per-IP throttles key an IPv6 client on its /64.

**Rationale**: A log line per deny lets whoever is being throttled decide how much we log, which turns the limiter into a log-flooding tool. The metric can count every deny because a counter costs the same at any volume, but it can't say *who*: an org or IP label would create one series per org or IP. The crossing request is the natural "once": both stores increment and then compare, so exactly one request per window sees `max + 1`. That holds across instances, because Valkey's `INCR` is atomic, and it needs no state of its own and no eviction. It bounds the logs only as far as buckets are bounded, though. Credential buckets exist only for credentials that verified, but IP buckets can be minted at will. The global budget closes that, and the suppressed counter makes the closing visible. The /64 is the IPv6 unit because one subscriber is handed a whole /64 and can source from any address in it, so a per-address key limits neither the requests nor the log lines.

## D111: A dashboard session is a server-side row; the cookie only names it, and is checked before anything meters or reads it

**Date**: 2026-09
**Decision**: The session JWT keeps its 7-day lifetime but carries a `jti` naming a `user_sessions` row (migration 130). `middleware/session_gate.rs` runs outside every router layer and, on each request with a session cookie, checks the row: revoked, expired or missing → the cookie is removed from the request and cleared on the response; a row since re-scoped to another identity (an older copy of a cookie the browser has already replaced) → removed but not cleared. Revocation happens on logout, on every new sign-in in the same browser, on identity change (the IdP reporting a different email at sign-in revokes all the human's sessions; an admin rewriting a member's email revokes that member's), on admin removal and archive (sessions scoped to that org only), and self-service from Account → Sessions. Switch-org, OAuth-consent org switch, the connect gate's auto-switch and org creation *re-scope* the same row instead of minting another; the connect gate defers its re-scope until the flow is actually won. A session JWT without a `jti` is honoured only if `exp - iat` ≤ 24 h. Checks are cached in Valkey (live 30 s, dead 1 h, `DEL` on revoke); with no `REDIS_URL` there is no cache at all.

**Rationale**: CASA 2.2.1/2.2.3 fail any 7-day token that logout cannot kill, and a per-request primary-key lookup is the cheapest thing that makes it killable while keeping the UX. The gate strips rather than rejects so that the dozen existing cookie readers — extractors, both rate limiters, the "is anyone signed in?" checks on public pages — needed no change and cannot disagree. It sits *before* the D108 limiters on purpose: a stolen cookie its owner has since signed out must not be able to drain the owner's session bucket, so a dead session is anonymous by the time anything meters it. That leaves the gate's own lookup unmetered, which is why dead verdicts are cached (death is terminal and a `jti` is never reissued). A process-local cache is refused in production because one replica cannot evict another's copy, turning "logout works" into "logout works within the TTL on whichever replica you hit". The 24-hour stateless allowance is CASA 2.2.3 verbatim; the only token that uses it is the 10-minute loopback session `mcp_session` mints for itself, and it is also what turned away every pre-`jti` cookie — a one-time sign-out on deploy. Re-scoping keeps one row per browser, so the sessions list reads as devices, not org hops.

## D112: Secret reads are audit-logged to a 400-day bucket that is locked in prod, and every non-runtime read notifies

**Date**: 2026-09-28
**Decision**: Data Access audit logs (`ADMIN_READ`, `DATA_READ`, `DATA_WRITE`) are on for Secret Manager, Cloud SQL and Cloud Run. Cloud SQL is keyed `cloudsql.googleapis.com`, the name its audit logs carry, not the `sqladmin` API endpoint. Every Cloud Audit Log in the project is sunk to `overslash-<env>-audit`, retained 400 days. The bucket is locked in prod (`audit_log_bucket_locked = true` in `prod.tfvars`) and left unlocked in dev. A log-based metric counts `AccessSecretVersion` by any principal outside `expected_secret_accessors`, which today is only the run service account. The module refuses a non-service-account entry. A P1 email alert fires on any non-zero minute. `infra/modules/audit-logging/`; policy in `docs/compliance/casa/secrets-access-policy.md`. CASA 6.7.1.
**Rationale**: 400 days is one 12-month CASA cycle plus slack, and it equals GCP's `_Required` bucket, so Admin Activity and Data Access age out together. A lock can never be undone, and a locked retention can never change. So the floor was picked deliberately, and the lock goes only where the log is evidence. Humans are never exempt from the alert, because a person reading the vault master key is exactly the event 6.7.1 wants seen. The price is one email for each operator `tofu plan`, since the provider reads every secret version on refresh. The alert is therefore P1 email, not a P0 page. `_Default` stays at 30 days because it holds application logs, not evidence.

## D113: Google Workspace sync uses one service account per instance, and an org proves its Workspace by signing in with Google

**Date**: 2026-09
**Decision**: This supersedes D110's credential. There is no per-org service-account key: the per-org upload, its encrypted column, and the typed admin email and domains are gone (migration 131 drops them and the existing configs). The instance has one service account, supplied by the operator through `OVERSLASH_GOOGLE_DIRECTORY_SA_KEY` (the JSON key) or `OVERSLASH_GOOGLE_DIRECTORY_SA_KEY_FILE` (a path to it), parsed at boot. A customer's Workspace admin authorises that account's client ID in admin.google.com — the dashboard shows the client ID and scope — and then connects by signing in with Google: the `hd` Google reports becomes the org's `domain`, the verified email becomes the impersonated admin, and `domain` is unique per instance. Everything else in D110 — the triggers, the queue, direct-only membership, the partial-listing and domain rules — is unchanged. Operator setup: [docs/runbooks/google-directory.md](docs/runbooks/google-directory.md).

**Rationale**: Per-org keys made every customer create a Google Cloud project, enable the Admin SDK, download a key and hand it to us — a setup most Workspace admins cannot do and should not have to. The vendor pattern is one account the customer grants delegation to, and the setup collapses to one screen in their own admin console.

**Sharing the account moves tenant isolation from Google into Overslash.** With per-org keys, a key could only read Workspaces that had delegated to *that* key. With one account, every connected Workspace has delegated to the same client ID, so an org that could type an admin email could read any of them. The sign-in is the replacement boundary: Google, not the org, says which Workspace this is, and the service account can only act as the admin who proved it. The connect is single-use and bound to the browser session that started it, or an org admin could send the Google link to another Workspace's admin and attach that directory to their own org. One org per Workspace per instance closes the last gap.

**Why sign-in rather than a DNS TXT record.** It proves the right thing — an *admin of the Workspace*, not merely someone who controls DNS — and the same sign-in supplies the admin to impersonate, so nothing is typed that could be wrong. It costs self-hosters a Google sign-in client, which a Google Workspace integration already implies.

**Why the key comes in through env, not a keyless `signJwt`.** One mechanism for hosted and self-hosted alike, and a file path for platforms where the JSON should not sit in the environment. On Cloud Run the value comes from Secret Manager, created by Terraform with a placeholder and filled with `gcloud`, so the private key never enters Terraform state.

## D114: HTTP-action attachments are gateway-staged bytes, referenced by id and inlined only at send time

**Date**: 2026-09-30
**Decision**: A request-body property marked `x-overslash-staged-upload: {inline_as: base64}` takes a list of `{upload_id}` references to bytes Overslash itself holds. `overslash:upload_file` (a platform action, `risk: write`) takes the file's `filename`, exact `size_bytes`, and optionally `content_type` and `sha256`, and mints a single-use URL. The caller PUTs the bytes to the existing `POST|PUT /v1/uploads/{token}` route, which now falls through to a new `staged_uploads` table (migration 132) when no `upload_tokens` row holds the token. The bytes are measured and hashed, held to the declared size and digest, encrypted with the AES-256-GCM keyring and stored for `STAGED_UPLOAD_TTL_SECS` (24h). Sending is two steps:
- **At resolution** (`staged_upload::describe`, in `resolve.rs` where every Mode C body is built), each `{upload_id}` is replaced with the stored descriptor: `{upload_id, filename, content_type, size_bytes, sha256}`. That lookup is scoped to the org and the caller's owner user. The approval disclosure, the replay payload and the audit row therefore name the real file, and none of them holds a byte of it.
- **At send time** (`staged_upload::wire_body`, next to credential injection in both `call.rs` and `action_caller::call_action_request`, and so on the inline, approval-replay, async and hybrid paths alike), the descriptors become `{filename, content_type, content_base64}`. That is overfwd ≥ 0.6.0's shape.

The request carries only `ActionRequest.staged_uploads`, a list of field names set from the template. It rides approvals and replay payloads the way `SecretRef` does. `deliver: "url"` is refused for such an action, because the deferred replay would not inline anything. `services/email.yaml` `send` gains `attachments` and an `Attachments` disclosure row.

Abuse bounds, all in this change:
- **Size**: `STAGED_UPLOAD_MAX_BYTES` (10 MiB, hard-clamped at 20 MiB) applies to one upload and to one call's total. At most 20 attachments per call.
- **Quotas**: per identity (50 MiB, 50 live uploads) and per org (200 MiB). Quotas count from the mint, which writes the row with the declared size reserved, so a burst of mints cannot outrun them. The check runs in one transaction under a per-org advisory lock.
- **Concurrency**: `STAGED_UPLOAD_CONCURRENCY` (4) is one process-wide semaphore held while a body is buffered on redemption and while it is inlined and in flight on send. A saturated replica answers 503 before a token is spent.
- **Rows**: a failed push deletes its row instead of re-arming it.
- **Key rotation**: `staged_uploads.body_ciphertext` joins `key_rotation::TARGETS` with a per-target batch cap of 4 rows.

Over quota, a mint is refused with 429 `staged_upload_quota_exceeded`, carrying the live usage and `evictable_bytes`/`evictable_count`. `force: true` evicts the **caller's own** oldest uploads until the new one fits. It never touches another identity's uploads, an upload mid-push, or one **pinned** by a pending approval or queued call (`pinned_until`, set when the approval, async row or hybrid job is written). Eviction is all or nothing: if what is evictable cannot make room, nothing is deleted. The sweeper and the liveness checks treat a pinned row as alive past its TTL.

**Rationale**: The Mailbox Gateway is stateless by design: it holds no credentials or mail at rest. So D76's shape, which streams the bytes into the service's own storage and hands back its reference, has nowhere to point. There were three options:
- **overfwd stores them.** That breaks overfwd's defining property, and it needs shared storage behind a multi-instance Cloud Run service.
- **The agent inlines base64 itself.** That puts every byte of every attachment through a context window and into the approval payload, which is the problem D51/D61/D76 exist to avoid.
- **Overslash stages them.** This keeps D76's capability model: a single-use token, the anonymous redeemer contributes only bytes, and everything a reviewer sees is fixed or verified before the send.

Splitting descriptor from bytes, and swapping them at the same point credentials are injected, is what keeps a 10 MB file out of `approvals.replay_payload`. It also makes the reviewer's view authoritative: the descriptor comes from our table, and whatever else the caller wrote beside `upload_id` is discarded. The dial re-checks the stored digest against the approved one.

Bytes at rest are a new cost, so every bound above is enforced here rather than left to a follow-up. The mint rate is bounded by the existing per-key rate limiter and the push by the per-IP redemption throttle. Eviction is limited to the caller's own uploads, so one agent cannot delete a colleague's attachment out from under a send; pins exist so that a human reviewing an approval cannot have its attachment expire or be evicted mid-review. Postgres `BYTEA` rather than object storage: there is no bucket in this deployment yet, the quotas bound the table, and D61 already stores encrypted blobs the same way.

`upload_file` stays an ordinary gated write for agents. It is not added to the four seeded self-setup anchors, because widening those is a separate call. A user who wants it frictionless grants `overslash:upload_file:*` once, or answers "Allow & Remember".

## D115: Every instance endpoint and config field is overridable; a template only decides which ones the form shows up front

**Date**: 2026-09
**Decision**: `configurable_url` on the template detail is true for every template except the `http` pseudo-service and `runtime: platform`. It is no longer tied to being host-less, MCP, or carrying a `secret_source: org` scheme. The detail also reports `default_url`, which is `mcp.url` or `ServiceDefinition::default_base_url()` (the same function `effective_base` falls back to), and `url_promoted`. Each `instance_config_params` entry gains `default` and `promoted`. A new extension, `x-overslash-promoted` (alias `promoted`), is read on `servers[]` (only `servers[0]` counts) and wherever `x-overslash-instance-config` is read. An `x-overslash-config` var takes a plain `promoted: true`. The instance form shows a field in its main section when the instance cannot work without it (required, and neither the template nor an org layer supplies a default) or when it is promoted. Everything else goes behind "Show more options", and every field with a default names that default. Shipped promotions: Langfuse's endpoint, and email's `X-Mailbox-Imap`/`X-Mailbox-Smtp`.
**Rationale**: The executor already took `service_instances.url` ahead of the template host for every template, and `POST /v1/services` already accepted it. The old `configurable_url` rule hid a working capability from the dashboard: a Langfuse org in the US region had to call the API directly. Promotion had to be an explicit author choice. The count of `servers[]` entries is not a signal, because `x.yaml` lists two domains of one service. Prominence is decided per field, by whether more than about a third of operators would change it, and not per template. That keeps single-endpoint SaaS forms short while no default is ever invisible. This adds no capability: pointing an instance at another host was already possible through the API, and `check_endpoint`'s TLS/SSRF rules still apply to every override.

## D116: The Live Map is on in production too

**Date**: 2026-10
**Decision**: `enable_live_map = true` in `infra/env/prod.tfvars`, so prod sets `OVERSLASH_LIVE_MAP` and emits the per-call `action.called` / `action.completed` events. This reverses D58's "never in production"; the rest of D58 (topic, emission site, audience, the flag itself) stands.
**Rationale**: D58 gated the events on volume, not correctness — one durable `events` row per action call on the hottest path. That cost is bounded: `events` is pruned after 7 days (`RETENTION_DAYS` in `services/events/bus.rs`), so the table holds a rolling week of calls rather than growing without limit. The flag stays, so another deployment can still leave it off.

## D117: Named operators' Terraform reads of secrets do not alert

**Date**: 2026-10
**Decision**: The audit-logging module takes `terraform_operators`, a per-environment list of principals (humans or service accounts). A secret read by one of them whose user agent carries `terraform-provider-google/` is left out of the unexpected-secret-access metric. Their Console, `gcloud` and `db-shell.sh` reads still count. Both environments list the owner's account and the factory agent's service account. The alert now groups by principal only, so one read session opens one incident instead of one per secret. This narrows D112's "humans are never exempt"; the rest of D112 stands.
**Rationale**: Every plan reads every secret, so under D112 each routine apply raised about 20 P1 emails. An alert that fires on every apply teaches operators to close it unread, which defeats it for the reads that matter. The exemption is limited to the one client that reads routinely. The trade-off is explicit: the user agent is caller-supplied, so a stolen operator credential could read quietly by imitating the provider. Every read still lands in the 400-day audit bucket, so it remains attributable after the fact.

## D118: Langfuse carries its Cloud and self-hosted read surfaces in one template

**Date**: 2026-10
**Decision**: `services/langfuse.yaml` models both read surfaces. The Cloud v4 actions keep their names (`list_observations`, `get_metrics`, `list_scores`, `list_experiments`, `list_experiment_items`). Twelve self-hosted reads sit beside them, on the older paths: `list_traces`, `get_trace`, `list_sessions`, `get_session`, `list_observations_self_hosted`, `get_observation`, `list_scores_self_hosted`, `get_score`, `get_metrics_self_hosted`, `list_dataset_runs`, `get_dataset_run` and `list_dataset_run_items`. Each self-hosted description opens with "Self-hosted Langfuse read API.", and each Cloud read names its self-hosted counterpart. `tests/langfuse_self_hosted.rs` requires every action on an old path to be a GET carrying the marker, and no Cloud action may carry it. Writes on the old surface (`POST /ingestion`, dataset-run-item creation) stay out. `list_traces` defaults `fields` to `core,metrics`, because Langfuse returns every field group, whole prompts and completions included, when `fields` is absent.
**Rationale**: Self-hosted Langfuse ships the v4 handlers but gates them. Checked against v3.225.11: v2 observations, v2 metrics and experiments answer 404 or 501 unless the instance opted into a v4 write mode, and v3 scores 404 on older releases. A self-hosted user therefore could not read a single trace. A separate `langfuse_self_hosted` template would have duplicated about 15 shared actions (prompts, datasets, score writes, the probe) and made operators pick the right one. A per-instance version switch needs a conditional-action mechanism that does not exist. One template with description routing costs some dead actions per deployment. TECH_DEBT.md records the principled replacement: versioned template families (`langfuse:v1`, `langfuse:v4`, `langfuse:latest`) with an instance-level pin. This supersedes the template's original "no action may target a sunset path" guard.

## D119: Secrets live in per-user vaults, and a binding is a path that names the vault

**Date**: 2026-10
**Decision**: Each user has a vault, and the org has one more. A secret is unique by `(org_id, owner_identity_id, name)` with `NULLS NOT DISTINCT`, where NULL means the org vault (migration `133_secret_namespaces`). An agent's vault is its owner user's. Every binding (`service_instances.credentials` values, the legacy `secret_name`, MCP bearer names, and inline `SecretRef` bindings) is a path: `org/<name>` or `<user identity id>/<name>` (`overslash_core::types::SecretPath`). On input the API also accepts `<handle>/<name>` (a user's email, email local part or name, accepted when exactly one user matches), `user:<handle>/<name>` (the escape for a user called `org`), and a bare name, which means the vault being written.

**Write rule** (`services::secret_paths::BindingWriter`, used by both create and update):
- A binding the request *changes* must name the writer's own vault: the instance owner's for a user-level service, the editing caller's own for an org-level one.
- Org admins may also name the org vault: on an org-level service, or on a `secret_source: org` slot of a user-level one.
- Unchanged bindings are kept verbatim. So a shared org service stays bound to the configuring admin's secret when another admin edits it.

**Read rule** (`readable_instance_binding`):
- A user-level instance resolves only its owner's vault and the org vault.
- An org-level instance resolves its stored path.
- An unbound `secret_source: org` slot tries the owner's copy of its default, then the org vault's.
- `OAUTH_*` app credentials come from the org vault only.

**Inline secrets** (Mode A, and explicit `secrets` on a call) resolve only in the caller's own vault. The org vault is refused as well, admins included.

**Conflicts and secret requests**: the setup-link conflict check (D85) and `overwrites_version` look only in the vault the link fills (`service_setup::fill_namespace`). `POST /v1/secrets/requests` may target only the caller's own user unless the caller is an admin.

**The `secrets` REST API**: it addresses the caller's own vault by default; admins select another with `?owner=` or `?scope=org`.

**Migration**:
- Re-homes agent-owned secrets to their owner user.
- Moves `OAUTH_*`, `overfwd_gateway_key` and DB templates' org-source defaults to the org vault.
- Qualifies every existing binding against the current owner of its then org-unique name.
- `RAISE NOTICE`s each user-level instance bound into another user's vault and leaves it in place; the read rule refuses it at runtime as a missing credential.
- Switches the owner FK to `ON DELETE CASCADE`. With `SET NULL`, deleting a user would have promoted their secrets into the org vault.

This amends D32 (map values are paths, not names in "the org vault") and D85 (reusing a name is a feature *within your own vault*).

**Rationale**: Names were org-unique, and every lookup, at bind time and at call time, went by org and name. `owner_identity_id` (migration 064) only decided visibility. So any member could bind, and then execute with, a colleague's credential just by naming it: in one org a user's `shortcut` service ran on another user's `shortcut_api_token`. D85's 409 hint even suggested binding the existing name. Checking ownership on top of org-unique names would have closed the read, but the collision would remain: the second user still could not hold a `shortcut_api_token` of their own. Vaults fix both. The namespace has to travel with the binding rather than be inferred from the instance: an org-level service has no owner, and the vault it reads is whichever admin configured it. A stored path also makes approval and token replays self-describing. A bare name in a payload persisted before this change resolves in the requester's vault and, for a template-compiled ref (whose host the template pins), then the org vault where the migration moved org defaults; a raw-HTTP ref never reaches the org vault. Paths are stored by identity id, not by handle, because names are not unique and emails change. The dashboard and the handle input give people the readable form. Mode A never reaches the org vault because it dials any host: allowing it would let an admin's agent send the org's OAuth client secret anywhere.

## D120: A service instance can only pin — and only ever uses — its owner's own OAuth connection

**Date**: 2026-10
**Decision**: A pinned `service_instances.connection_id` must be a connection whose `identity_id` is the instance's owner — or one of that owner's own agents (a legacy shape D23 re-homed; still the same user) — for the provider the template authenticates with; an org-level instance cannot pin one. `platform_services::connection_binding::validate_connection_binding` enforces this on create *and* update (`PUT /v1/services/{id}/manage`, MCP `update_service`), for admins too. At call time `pinned_connection_usable` applies the same rule in both resolvers (`resolve_instance_auth`, `mcp_resolve::resolve_instance_connection`, which also feeds the scope gate): a pin that fails it is treated as absent — the call falls back to the owner's default connection or `needs_authentication`, never to the pinned token. Alongside: `create_connection` only inherits `login_hint` from an `upgrade_connection_id` the flow identity owns; `caller_has_group_access_to_connection` only counts pins the instance owner owns; and `UpdateServiceInput` distinguishes `null` from absent for `connection_id`, `secret_name` and `url` (`null` used to be silently ignored, so a pin could not be removed). Amends D22's "explicit bindings resolve org-scoped".
**Rationale**: The twin of D119 for connections. Create checked a pin's owner; update did not, and the resolvers loaded the pin org-wide — so a member could re-pin their own service onto a colleague's connection and act as that account, and on an MCP-OAuth instance (whose `url` the same update sets) receive the colleague's bearer token at a host of their choosing. Connection ids are not secret (they appear on group-shared instances), so the check has to be on ownership, at write and at read; the read-side rule also neutralises any pin written before the fix. Cross-org was already closed (every lookup filters `org_id`).


## D122: Every stored reference to an owned resource has one binding policy, and owner-blind getters are named and fenced

**Date**: 2026-10
**Decision**: Each kind of reference that one owned resource stores to another has exactly one **binding-policy module**, and it owns both the write check and the read check. Every create, update, import, setup-link, callback, replay and view path goes through it:

| Reference | Policy | Write | Read |
|---|---|---|---|
| Secret path (`credentials`, `secret_name`, MCP bearer) | `services::secret_paths` | `BindingWriter` (D119) | `readable_slot_binding` = vault rule + `OrgVaultGate` |
| Pinned `connection_id` | `platform_services::connection_binding` | `validate_connection_binding`, `check_pin` (callback, import) | `pinned_connection` (calls), `usable_pins` (views) |
| Pinned BYOC client (`byoc_credential_id`) | `services::byoc_binding` | tier 1 of `client_credentials::resolve` (create, import, MCP, upgrade) | `usable_byoc_pin` (tier 1a, every exchange/refresh) |
| Instance → template | `platform_services::instance_template` | instance create resolves the owner's tiers | every path holding an instance row |

Three rules are new:
- **An instance's template is its owner's.** The template is resolved in the instance owner's tiers, or org → global for an org-level instance, and never in the caller's. That covers the call path, approval replay, and update validation. Creating an org-level instance no longer finds the creating admin's own user tier.
- **The org vault follows only the org's endpoint.** A user-level instance reads the org vault only when its request lands on the base the org/global tier of its template declares (`effective_base` for HTTP, the MCP URL for MCP). It then reads only that tier's org-source slots, under that tier's `default_secret_name`. An instance `url` override, a user-tier template or a user layer moves the destination, and the org secret stays behind: the slot falls back to the owner's own copy, or reports missing. The exception is a host the platform holds a key for (D39), which still binds the org path, because the platform rung re-checks the host at send time. Org-level instances are unaffected.
- **A BYOC pin must be the connection owner's own app, for the same provider.** This means the same user, or one of that user's own agents. It is checked when a pin enters and at every use. A failing stored pin falls through the cascade, and a failing explicit pin is a 400. Admins are not exempt.

The org-wide getters are renamed for what they do: `get_connection_any_owner`, `get_connections_by_ids_any_owner`, `list_all_connections_any_owner`, `get_byoc_credential_any_owner` and `list_byoc_credentials_any_owner`. The `binding_guard` test (`crates/overslash-api/src/binding_guard.rs`) fails when one of them, `get_current_secret_value`, `get_secret_value_at_version` or the bare vault rule is called from a file outside its allowlist; each allowlist entry carries a reason. It also fails when an instance's `template_key` is resolved without `instance_template`, and when a new `OrgScope` getter returns connection or BYOC rows without saying `_any_owner`. Views read pins through `usable_pins`, so a foreign pin shows as "not connected", which matches what the call path does, and never shows a colleague's `account_email`.

This amends D115 (an endpoint override no longer carries org-vault credentials), D119's read rule (the org vault is gated by destination) and D120 (pins written by the callback and by import get the same owner-or-own-agent and provider check).

**Rationale**: D119 and D120 were the same bug twice. A reference on A's resource pointed at B's resource because one write path checked ownership and another didn't, the call-time read trusted the stored value, and the DB API made the org-wide lookup the easy one. An audit after them found three more cases of the same class: the template shadow, the org-vault exfiltration through `url` (or through a user template naming `overfwd_gateway_key` as its default), and an unchecked BYOC pin. Fixing each by hand leaves the next one to be found by luck. Putting both halves of the rule in one module per reference makes a new path pick the policy up by construction. Naming the owner-blind getters makes misuse visible in review, and the guard turns "remember to check" into a failing test. Gating the org vault by destination rather than refusing it outright keeps the shipped case working: a personal `email` instance on the org's overfwd still gets the gateway key.

## D121: Behind the GCLB, the client IP comes from a header the LB stamps, and the API is reachable only through the LB

**Date**: 2026-10
**Decision**: When `enable_api_lb` is on (prod), the LB backend adds `X-Overslash-Edge-Client-Ip: {client_ip_address}`, the API reads it via `OVERSLASH_TRUSTED_CLIENT_IP_HEADER`, and the API's Cloud Run ingress is `INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER`. The header names the first untrusted hop; the D102 proxy secret still swaps a vouching Vercel hop for the browser it names. XFF is walked (hops=2, LB by CIDR) only when the header is absent. Without the LB (dev), ingress stays open, no header is trusted, and hops stays 1. Both the header setting and the ingress are derived from `enable_api_lb` in `infra/main.tf`, so they can't drift apart.
**Rationale**: Behind the global external Application Load Balancer, `X-Forwarded-For` carries Google addresses from unpublished ranges. Prod recorded 34.96.62.132 for every agent and MCP call at hops=1, and 34.96.62.181 at hops=2, so neither CIDRs nor positional counting locate the client. The LB overwrites a custom request header of the same name a client sends, so its `{client_ip_address}` can be believed — provided nothing reaches Cloud Run except through the LB; a direct `*.run.app` caller could otherwise send the header itself. Prod `*.run.app` traffic was only manual curls, so closing it costs nothing. Amends D102.

## D123: Approval, permission-rule and service-instance reads are gated by relationship, not by org membership

**Date**: 2026-10
**Decision**: A non-admin may read an approval — list row, `GET /v1/approvals/{id}`, and the 404/403 split on `/execution` — only when they are self-or-ancestor of its **requester** or of its **current resolver** (`services/approval_access.rs::may_read_approval`); org admins (`OrgAcl` level `Admin`) read everything. `GET /v1/approvals` with no `scope` is now that set for a non-admin (one recursive-CTE query, `list_visible_pending`) and the full org only for an admin — narrowed silently, not refused, like `include_user_level`. `?identity_id=` keeps answering but drops rows the caller may not see. A row in the org the caller is unrelated to answers **404**, exactly like a cross-tenant id, so a stranger cannot confirm an id exists; `/execution` checks the approval first (404) and only then the narrower execution ladder (403). `GET /v1/services/{id}/groups` and the by-UUID branch of `GET /v1/services/{uuid}/actions` now apply the same reach as `GET /v1/services/{uuid}` (`require_readable_by_caller`: owner, ceiling owner, group grant, or org admin), 404 otherwise. "Org admin" on every one of these gates means `OrgAcl` level `Admin` — the `is_org_admin` flag *or* an admin-level `overslash` grant — never the flag alone: the first cut checked only the flag on the service routes and locked the Admins-group admin (the dev `admin` profile's shape) out, which the dashboard therefore learns from the API's 404 rather than guessing from the flag. `GET /v1/permissions?identity_id=` answers only an org admin or the target itself or one of its ancestors, 404 otherwise — the rule set is the read-side twin of the approvals it remembers. Amends D50.
**Rationale**: D50 recorded that `GET /v1/approvals` had no ACL gate — any identity in an org could enumerate every pending approval and read its `action_detail` (up to 100 KB of request payload) and disclosure — and pinned widget tokens to `mine|assigned|actionable` so a browser credential would not inherit that. The pin stays, but it is no longer the only thing standing between a credential and someone else's payloads. The rule is the SSE approval audience (`events/audience.rs::for_approval`) restated at the endpoint, so the stream is no longer deliberately narrower than REST. It has no `Write` floor, unlike `may_read_execution`: a Read-level owner must still see what its own agents asked for in order to decide on it, while the upstream *response body* stays behind the stricter ladder — every caller that may read the execution may read the approval, never the reverse. The service routes were the same org-only `get_service_instance` lookup the detail route had already fenced; leaving them open handed another user's private group grants, action list and scope coverage to anyone who had the UUID. A permission rule set was the remaining same-org read of that kind: it names exactly what an identity may do unattended (whose mailbox, which repos, which hosts), and the detail panel fetched it for any node a viewer clicked. Its gate is the node's own chain only — unlike an approval, a rule has no resolver to widen it. In the dashboard a non-admin's notification bell and agents-tree badges now count only approvals they are involved in, and the agents detail panel says why a node outside their tree shows no approvals and no rules (it does not fetch the rules at all there).

## D124: MCP tool calls loop back to the local process and carry the caller's address

**Date**: 2026-10
**Decision**: `POST /mcp` re-issues tool calls to its own REST API at `http://127.0.0.1:<port>` (`services::loopback`, set by the CLI from the bind address) instead of `PUBLIC_URL`. The loopback carries the client address `/mcp` resolved in `x-overslash-loopback-client-ip`, vouched for by `x-overslash-loopback-token`: 32 random bytes generated per process at boot. `ClientIp` takes the named address only on a constant-time token match, and otherwise resolves as usual. The in-process test harness, whose `PUBLIC_URL` is its bind address, keeps dialing that. Amends D121's rationale.
**Rationale**: The 34.96.x addresses on prod's agent audit rows, which D121 attributed to Google hops behind the GCLB, were Cloud Run's own egress: every MCP tool call went out through Vercel and the LB and back in, so the REST side correctly named this service as the client. No trust setting on the receiving side can recover an address the request never carried. A per-process token, not a shared secret, is enough because a direct dial never leaves the host and always lands on the process that minted it; it also removes two internet hops (and their failure modes) from every tool call. D121's edge header and LB-only ingress still hold for direct REST callers.

## D125: Webhooks carry only the timestamped signature

**Date**: 2026-10-13
**Decision**: Outbound webhooks no longer send `X-Overslash-Signature: sha256=<hex>`. Every attempt — handshake, first delivery, each retry — carries `X-Overslash-Timestamp` and `X-Overslash-Signature-V1: v1=<hmac("<timestamp>.<raw body>")>` and nothing else that signs it. `@overslash/sdk/node` drops `verifyWebhookSignature` (and its `VerifyWebhookOptions`) with it; `verifyWebhook` is the only verifier. Amends D98's last paragraph: the grandfathering it describes is over.
**Rationale**: As long as the body-only header was on the wire, CASA 7.2.3's replay protection was opt-in — a receiver checking only it accepted a captured delivery forever, and we cannot see which receivers do (it is their code). Removing the header is the only change on our side that makes the protection hold for everyone.

**Breaking, and meant to fail closed.** A receiver still verifying `X-Overslash-Signature` now finds it missing; any correct verifier rejects a delivery without its signature, so the failure is refused deliveries (visible in the delivery log and retried), never accepted forgeries. The fix on their side is the documented `v1` check, which they could already run — both headers were sent side by side since D98. The SDK function is removed rather than left deprecated so a TypeScript consumer gets a compile error instead of a verifier that returns `false` on every delivery; the package is 0.x and unpublished by CI, so no major bump is involved.

**We did not wait out D98's announcement window.** D98 planned a dated announcement before removal; we chose to remove now because the window bought compatibility at the cost of every receiver's replay exposure, with no measurement to tell us when it would be safe. The overslash-docs webhook guide gets the `v1` section as a follow-up (TODO.md).

## D126: Search rows are one per (template, action) with an `instances` list; catalog templates collapse to one row; naming a service boosts it

**Date**: 2026-10
**Decision**: `GET /v1/search` (and so MCP `overslash_search`) changes shape and ranking in three ways. **(1) Instances collapse.** A row is one action of one template, and it carries `instances: [{service, account_email?, secret_name?, scope_coverage?, missing_scopes?}]` — always present, sorted by `service`, empty on a catalog row. The top-level `service`, `account_email`, `secret_name`, `scope_coverage` and `missing_scopes` are gone; scope coverage is per instance because two instances of one template can be bound to different grants. Browse mode is one row per template on the same shape. `limit` now counts distinct (template, action) rows. Instance-only MCP tools discovered on several instances merge into one row the same way. **(2) One catalog row per template.** Under `include_catalog=true` an un-connected template contributes only its best-scoring action, with up to three runner-up action keys in `more_actions`. **(3) Service-name boost.** `service_name_bonus` (0.25 × the fraction of the template's display-name ∪ key tokens that some query token hits exactly or as a prefix) is added after the keyword/embedding blend and before the connected/read bonuses. Fuzzy matches do not count. This supersedes §10's "one row per instance" fan-out, which replaced the earlier nested `auth.instances`.
**Rationale**: All three came from the same failure: the `limit` window (default 20) filled with rows that told the agent nothing new. Five Gmail accounts meant five byte-identical copies of every Gmail action — description, params and all — and one un-connected catalog template could take a dozen slots, each repeating its `auth.setup` chain. Meanwhile, a query that named the service it wanted ("hubspot deals") lost to other services whose action prose matched better, because the service name is 3.0 of the keyword scorer's 10.5 field weight and the whole keyword score is then scaled by 0.4 against embeddings. Collapsing instances keeps every callable name and its disambiguators (the fan-out's reason for being) while paying for the shared definition once. An always-present `instances` array (rather than a top-level `service` plus an optional "others" list) means a caller reads a single-instance row and a five-instance row the same way. The cost: `template` is now the only top-level identifier, and agents already reach for it as if it were callable (D77). D77's `available_instances` error covers that misstep, and every tool description now names `instances[].service`. A catalog row shows one action instead of none because the agent's next move is setup, and the best action's params tell it whether that setup is worth doing. Breaking change, accepted knowingly: there is no dashboard, CLI or SDK-typed consumer in this repo, and the known downstream mirror (overfolder's `SearchResult` structs) has `#[serde(default)]` fields, so it deserializes the new payload silently as instance-less rather than failing — it needs a matching update.

## D127: Injected credentials are scrubbed out of every buffered upstream response

**Date**: 2026-10
**Decision**: Before a buffered upstream response reaches the calling agent, a response filter, or the D18 audit capture, every literal value Overslash injected into that request is replaced with `[REDACTED]` (`services::credential_scrub`). This covers HTTP inline calls, approval replays, and MCP tool results. The values come from the send path itself: each vault credential's finished value (`resolve_credential_values`), the live OAuth header, and every header the MCP client attaches. They are matched together with the forms an echo is likely to use: without the auth scheme, the decoded password of a `Basic` credential, URL-encoded, and JSON-escaped. HTTP bodies and response header values are scrubbed as text. MCP `structured`/`content` are scrubbed as parsed JSON, so the envelope stays valid. Values shorter than 8 bytes are not matched. Streamed responses are not scrubbed, because they are never buffered (and never captured, per D18). Transport failures are unaffected, since D18 already writes them as fixed strings.
**Rationale**: Upstreams quote requests back in their errors (`"invalid key sk-…"`, a 400 repeating a query string that carries `?api_key=`, a debug route reflecting `Authorization`). D18 made those bodies durable on audit rows that org admins read, and they always reached the agent, which by design never holds the credential. Either path breaks "secrets never leave the vault." The scrub matches exact known values rather than secret-looking patterns, so it has no false positives on ordinary data beyond a literal collision with a credential of 8+ bytes. Its cost is a substring pass per needle over at most `max_response_body_bytes`. It applies to successes too: `audit_response_body_mode = all` captures 200s, and an echoing 200 leaks to the agent the same way. As a consequence, tests can no longer read the injected token off an echo. They now read the fake's own `/__received_requests` log (`common::last_received`).

## D128: A staged upload can go out as a `multipart/form-data` file part

**Date**: 2026-10-13
**Decision**: D114 gains a second encoding, `x-overslash-staged-upload: {inline_as: multipart}`. Its sole user so far is Holded's attachment and inbox endpoints. An action may now declare a `multipart/form-data` `requestBody`. Its properties are extracted exactly like a JSON body's (`RequestBodySpec::is_multipart`). The request travels as **JSON** from resolution through disclosure, approval, replay and audit, just as D114's does. Only `staged_upload::wire_body` re-encodes it, at the dial. Each described item in a `multipart` field becomes one file part named after the field, carrying the decrypted bytes and the stored filename and type. Every other field becomes a text part. The `Content-Type` comes out as `multipart/form-data; boundary=…`. The boundary is minted with the body, so the override rides on the body value (`http_caller::Payload`) rather than in the headers resolved earlier. `http_caller`'s buffered bodies are now bytes, not `&str`. Four validation rules apply:
- The encoding must fit the body: `base64` on JSON, `multipart` on a form. An omitted `inline_as` defaults to whichever fits.
- A form body must declare at least one staged field. `wire_body` recognises a template's form by that field, so a text-only form would go out as JSON under a form header.
- An unmarked `format: binary` part is an error.
- Non-file form fields must be scalars.

The disclosure input parses a form's body as JSON, as it does for a JSON body.
**Rationale**: Keeping the body JSON until the dial means no new shape exists anywhere a reviewer or an audit row reads, and no byte reaches `approvals.replay_payload`. D114's split between descriptor and bytes holds unchanged. Multipart is only another way of writing the bytes in step two. The form is built by hand rather than with `reqwest::multipart::Form` because a `Form` is a one-shot stream, while a buffered body has to survive the 307/308 replays in `send_following_redirects`. Whether to build a form is decided by the request's `staged_uploads` list, which only a template can set, and never by the `Content-Type` header. A raw HTTP call carrying its own multipart body therefore passes through untouched. `describe` lists a form's file fields even when the file was omitted, so such a form still goes out as one. The file field stays a list of `{upload_id}`, the same as `email.send`'s `attachments`, so an agent learns one shape. `maxItems: 1` documents an upstream that reads a single part, but nothing enforces it: a second item goes out as a second part, and the upstream decides what to do with it.

## D129: Users are addressed by UUID or email, never by display name

**Date**: 2026-10-14
**Decision**: A user's display name (`identities.name`, the IdP's `name` claim) no longer serves as an address anywhere.
- The `user` unit of a SPIFFE `identity_path` is the user's email: `spiffe://acme/user/alice@acme.com/agent/henry`. A user with no email falls back to the identity UUID. Agents keep their names. The path is built at read time, so existing audit and approval rows render the new form with no migration.
- The dashboard's user page is `/users/<uuid>`, and `/users/<email>` also resolves. Old name-keyed links show "User not found". Redirecting them would land on whoever holds that name today.
- API path segments and query args that name an identity also accept a user's email (`IdentityRef`, `overslash_core::identity_path`). These are `/v1/identities/{id}` and its children, chain, archive and restore routes; `/v1/org-members/{id}`; `/v1/groups/{id}/members/{id}`; and `?identity_id=` on audit, permissions and approvals, plus `?owner=` on secrets. An email resolves among the caller's org's *live* users only, matched case-insensitively. An unknown email gets the same answer as an unknown UUID. Agent-only routes and JSON bodies still take UUIDs.

**Rationale**: A display name is editable and not unique. It can also contain `/`, which corrupts the path. A name-keyed URL can therefore point at a different person after a rename. The email is the handle the IdP verified, and it is the same root `X-Overslash-As` already accepts. Shortening it for display (`alice`) stays a dashboard concern (`shortEmail`). The path keeps the full, unambiguous form.

## D130: The cache is Memorystore for Valkey, authenticated by IAM

**Date**: 2026-10-14
**Decision**: `infra/modules/memorystore` provisions Memorystore **for Valkey** (`google_memorystore_instance`, `VALKEY_9_1`, `CLUSTER_DISABLED`, one `SHARED_CORE_NANO` node) in place of Memorystore for Redis 7.2. It is reached over Private Service Connect, and runs `authorization_mode = IAM_AUTH` with `transit_encryption_mode = SERVER_AUTHENTICATION`. Clients set `REDIS_AUTH=gcp-iam` (API) or `VALKEY_AUTH=gcp-iam` (oversla-sh). They then authenticate as user `default` with an access token for the runtime service account, taken from the metadata server, cached until five minutes before expiry, and re-sent on open connections every 30 minutes. The service account holds `roles/memorystore.dbConnectionUser`, conditioned on that instance. The client builder both binaries share moves into a new crate, `overslash-valkey`. `*_PASSWORD` keeps working for a Valkey with a static AUTH string. The instance is named `<base_prefix>-cache` unless `TF_VAR_cache_instance_name` says otherwise, and the instance, its IAM binding and its CA secret are `create_before_destroy`. Renaming it therefore stands up a second instance, moves Cloud Run, then deletes the first.
**Rationale**: Memorystore for Valkey has no static AUTH string. Its token auth is Preview, beta-provider only, and has no Terraform way to read the token back. IAM auth is GA and leaves no password to store, leak through Terraform state, or rotate, which is a strict improvement for CASA 6.7.1 over the AUTH string it replaces. The cost is client code: a credentials provider rather than a static password, and a dependency on the metadata server at connect time. The name is `-cache` rather than `-valkey` so it names the role, not the engine, and so it doesn't collide with the old instance's Secret Manager IDs while both exist during the cutover ([memorystore-valkey.md](docs/runbooks/memorystore-valkey.md)). The rename override is an environment variable, not a tfvars entry, so a one-off swap does not quietly become configuration.

## D131: oversla.sh only redirects to Overslash domains

**Date**: 2026-10-15
**Decision**: The shortener accepts a target only if it is `https`, carries no userinfo, and its host is a domain in `ALLOWED_REDIRECT_DOMAINS` or a subdomain of one (`oversla_sh::target`). Matching is on a label boundary, so `evil-overslash.com` and `overslash.com.evil.net` fail, and IP literals never match. The variable is comma-separated and defaults to `overslash.com`, which covers every link the API mints (`app[.dev].overslash.com`, `<slug>.app.overslash.com`, `<slug>.api[.dev].overslash.com`). `POST /api/links` rejects anything else with `422 disallowed_target`; the response names the allow-list, never the URL. `GET /{slug}` re-checks the stored target and 404s one that fails. `ROOT_REDIRECT_URL` must pass the same check, or the binary refuses to boot.
**Rationale**: The shortener sits on a public domain and redirects anywhere one shared API key says. A leaked key, or a bug in any minting path, would make `oversla.sh` an open redirector with Overslash's name on it, which is exactly what phishing wants. Its only legitimate callers hand out links to Overslash's own surfaces, so a domain allow-list costs nothing. The default lives in the code rather than in tfvars because infra is applied by hand: a required variable would crash-loop the first image deployed before someone ran `tofu apply`. The variable still lets a self-hosted deployment point the shortener at its own domain. The redirect-side check covers links minted before the allow-list existed (TTL is at most seven days) and any later narrowing of it. Plain `http` is dropped because no minted link uses it.

## D132: The GitHub template requests classic OAuth scopes and works with either kind of GitHub client

**Date**: 2026-10-19
**Decision**: `services/github.yaml` declares the classic OAuth App scopes `repo` and `read:org`, and the configured GitHub client (`OAUTH_GITHUB_*` or BYOC) may be either a classic OAuth App or a GitHub App. An OAuth App grants those scopes. A GitHub App ignores `scope`, so its access stays the app's permissions on its installations, and its token comes back with an empty scope list. No GitHub action declares `required_scopes`, so that empty list never gates a call, and the dashboard does not offer a scope upgrade for a GitHub connection with no scopes. This amends [D17](#d17-builtin-github-service-uses-github-app-user-to-server-oauth), which required a GitHub App and declared no scopes.
**Rationale**: Under D17 an OAuth App client failed silently. Dev's services client was the login OAuth App, so connections got only the identity scopes `read:user user:email` and saw public repos only. Re-authorizing could not help, because the template asked for nothing more. [D94](#d94-a-template-declares-alternative-auth-modes-and-an-instance-picks-one-at-creation) already observed that the two client types differ only by a scope list and that the type is a deployment fact, not a per-instance choice. Declaring scopes that a GitHub App ignores serves both from one template with no mode switch. The OAuth App path also has no installation step: the user approves each org on the consent screen. The cost is `repo`'s reach: it is the only scope for private repositories, and it is read/write on every repository the user can access. Overslash holds the token and gates every call through permission rules, risk classes and approvals, so the scope is a ceiling rather than what an agent can do. An operator who wants fine-grained, expiring access configures a GitHub App, and an org that wants neither picks the PAT mode.

## D133: A reconnect re-authorizes the existing connection; the callback never duplicates an account

**Date**: 2026-10-19
**Decision**: Every re-authorization lands on the connection row it is fixing. `create_connection` takes `service` — an active instance first (an archived one is refused, never shadowing a live one of the same name), and only one the caller's ceiling user owns or an org-level one (another user's instance is a 403: its connection is that owner's to re-authorize) — (the instance's connection — usable pin, else the owner's default for its provider — becomes `upgrade_connection_id`; with none, the instance joins `pin_service_ids`) and an explicit `upgrade_connection_id`, which is checked against the caller's ceiling user at create time (404) and inherits the row's scopes (union) and BYOC client (a different explicit one is a 400). As a backstop, the OAuth callback for a flow with no upgrade target looks up a connection with the same identity, provider, `account_email` and `byoc_credential_id` (`find_same_account`; a missing email never matches) and upgrades it in place instead of inserting — only on providers whose `oauth_providers.email_identifies_account` is true (migration 136: Google, GitHub, LinkedIn, Spotify, Eventbrite, X). Where one email spans separately-granted tenants (Microsoft tenants, Slack and Notion workspaces, HubSpot portals) and on every custom provider it is false, and each connect is a new row. The account match is taken only when this flow's granted scopes cover every scope already on the row: its request carried no union, and a provider that does not accumulate grants (GitHub OAuth Apps) issues a token with just this flow's scopes, so swapping it in would strip the broader token the row's services use. A narrower grant gets a new row instead, and so does a row with unknown (`NULL`) scopes, which the scope gate treats as possibly broad. Explicit upgrade targets keep the union, since their flows request it. Extends the import path's idempotence (D21) to orchestrated flows. `list_connections` is a platform read action.
**Rationale**: A second row for the same account is never what anyone wants: it is not the default (the old one is), no service is bound to it, and before `list_connections` an agent could not even see it — so an agent "fixing" missing scopes changed nothing. Targeting by service puts the fix where the agent's intent is; the callback backstop covers every other entry point (dashboard, REST, older agents). Matching on the BYOC client keeps tokens on the row whose refresh runs against the client that minted them. Two different accounts of one provider remain two connections, as before. The per-provider flag defaults to false because the failure modes are asymmetric: a duplicate row is recoverable, a second workspace's tokens written over the first are not.

## D134: Slack goes through its Web API, not its MCP server; templates can judge success from the body

**Date**: 2026-10-22
**Decision**: `services/slack.yaml` is a plain HTTP template against `https://slack.com/api/*` on the existing `slack` OAuth provider, which already issues **user** tokens (migration 134). It keeps the operationIds the MCP tools had (`send_message`, `list_channels`, `read_channel_history`, `get_user`, `search_messages`), so existing `slack:<action>` grants still match. It adds `update_message`, `add_reaction`, `get_thread_replies` and `list_users`. Each operation declares its own user scopes through `security`, so a connection that lacks a newly added scope only has to reconnect for the actions that need it. A new extension, `x-overslash-success` (alias `success`), is a jq predicate over the parsed response body. It is set under `info` as a service-wide default, which an operation can override, and it applies to HTTP operations only. On a status below 400 with a JSON body, any output other than `true`, including no output or a runtime error, marks the result `body_failed`. That makes the call an upstream error for `is_error`, the audit row, response capture and paging. The status code stays the real one, and the body reaches the agent unchanged. A body that is not JSON, or a predicate that times out, leaves the status-only verdict. The predicate is snapshotted onto the stored replay payload, as `pagination` is, so gated and async calls are judged the same way. Its jq syntax is checked at the template register gate (`success_invalid_jq`).
**Rationale**: Slack admits only Marketplace-listed or internal apps to `mcp.slack.com`, and a Marketplace listing needs at least 10 active workspace installs. So D24's template could not work for Overslash's own Slack app, which is distributed but not listed. The Web API has no such gate. A narrower, hand-maintained surface was the cost D24 avoided, and it is now the price of the integration working at all. The success predicate exists because Slack answers nearly every failure with `200 {"ok": false, "error": …}`. Judged by status alone, a `channel_not_found` would be audited as a success and a paged read would keep walking. A Slack-specific check would break the no-platform-specific-logic rule, while a predicate is a general statement any in-band-error API can use. It fails closed on a body that answered wrongly and open on a body that cannot be judged. The author said what success looks like, so a body that contradicts it is a failure, but an HTML error page or a slow filter says nothing about the upstream. **Caveat**: since 3 March 2026, Slack has capped `conversations.history` and `conversations.replies` for commercially distributed **non-Marketplace** apps at 1 request per minute and 15 objects per call. `read_channel_history` and `get_thread_replies` on Overslash's shared Slack app are therefore barely usable. An org that registers its own Slack app as a BYOC client counts as an internal app and is exempt, and that is the supported route for history-heavy use.

## D135: TLS/PKI crates are exempt from the 7-day Dependabot cooldown

**Date**: 2026-10-23
**Decision**: The cargo entry in `.github/dependabot.yml` lists the PKI set (rustls*, webpki*, ring, aws-lc-*, openssl*, native-tls, jsonwebtoken, pem/der/spki/pkcs*/sec1/simple_asn1, and the tokio/hyper TLS adapters) in `cooldown.exclude`, so new versions are proposed on the next weekly run. Nearly all of them are transitive, so each pattern also gets an `allow` entry with `dependency-type: "all"`, since the default `allow` covers direct dependencies only and would never touch them. A `pki` group, listed first, gives these bumps their own PR. Other crates keep D30's cooldown, and the schedule stays weekly. Mirrors overfolder PR #812.
**Rationale**: D30's cooldown blocks a malicious publish from landing in its first week, but for trust roots and certificate validation the delay itself is the risk. The emSign distrust (RUSTSEC-2026-0381/0382/0383) is the case that proved it: unscored, so outside the Critical-only exception, and taken by hand under the TLS-trust waiver in `docs/compliance/casa/dependency-vulnerability-policy.md`. That waiver now runs automatically. These are narrow, well-maintained crates, which is why the supply-chain trade comes out the other way here.

## D136: Admin-class mutations need a fresh IdP sign-in; Overslash delegates MFA to the IdP instead of growing its own

**Date**: 2026-10-23
**Decision**: `user_sessions` records how each session was signed in (migration 137): `auth_method` (`idp`, `magic_link`, `dev`, or NULL when not recorded), `auth_provider`, `authenticated_at`, and the ID token's `amr` / `acr` as asserted. A switch-org re-scope keeps them, because it is not a sign-in. `AdminAcl` and `InstanceAdminAuth` then refuse a **non-GET** request from a **dashboard session** unless all three hold: the session is an `idp` sign-in (`dev` counts only while `DEV_AUTH` is on); for an org admin, its provider is one the org signs in with (`org_signin::list_org_signin_providers`, or any IdP when the org has none configured); and `authenticated_at` is within `ADMIN_STEP_UP_MAX_AGE_SECS` (default 1 h). The refusal is a 403 `step_up_required`, not a 401, because the session is still fine for everything else and the dashboard treats a 401 as a sign-out. It names the reason (`idp_required`, `provider_not_allowed`, `stale`) and gives each provider a `login_path`. The dashboard's root-layout `StepUpModal` sends the human through `/auth/login/{key}?step_up=true`, which adds OIDC `max_age=0` (and `prompt=login` for IdPs other than Google, which rejects it) so the IdP re-authenticates and runs its MFA rather than answering from its own session, then returns them to the page. When the ID token carries `auth_time`, that is the sign-in time recorded, not the callback time. An IdP that ignores `max_age` and answers from an old session therefore yields a stale session rather than a pass. A root step-up for an org with no IdP of its own carries the org (bound to the login's nonce), and the callback re-scopes the new session back into it when the human is a member. One fallback: a deployment with no IdP at all (no root Google/GitHub credentials, and none the org configured), which in practice means a self-hosted, magic-link-only install, accepts a magic link under the same freshness window and offers an email link as the step-up. Out of scope: personal orgs, API keys and MCP tokens, safe methods, and server-minted stateless session JWTs (no `jti`, ≤ 24 h, never given to a browser). `amr` is recorded and shown in Account → Sessions, never enforced. The same change puts `/v1/org-idp-configs` create, update, delete and discover behind `AdminAcl`. They previously took any credential in the org, including an agent key. `services/admin_step_up.rs`; tests in `tests/admin_step_up.rs`. CASA 3.3.1, 2.4.1.
**Rationale**: Overslash has no passwords. Every human arrives through an IdP or a magic link, and the IdP (Workspace 2-Step Verification, Entra / Okta policy, GitHub's org 2FA requirement) is already where MFA is configured and audited. A TOTP or WebAuthn factor of our own would be a second enrolment, recovery and lost-device story, and it would be weaker than the corporate one it duplicates. The hole was the paths that bypass the IdP. A magic link lands in the personal org, but the same session can be re-scoped into a shared org the human administers. A 7-day session also leaves the IdP's challenge days in the past. So the gate checks provenance and freshness on the operations that change other people's access. Reads are not gated: nothing is changed, and gating them would put a prompt on every settings page. Personal orgs are exempt because their only member is their admin. Bearer credentials are exempt because minting one is itself an `AdminAcl` mutation (an admin key) or is scoped to an agent. The org's own provider list is the rule because "the IdP's MFA is the only path" must mean *that org's* IdP: a Google sign-in should not satisfy an org that signs in only through Okta. `amr` is not enforced because Google and GitHub do not reliably send it, so requiring it would lock out the most common IdPs. It is recorded as evidence and could become a per-org toggle later. The no-IdP fallback exists because the alternative is a deadlock: adding the first IdP is itself an admin mutation, and there is no IdP MFA to defer to anyway. Production always has root IdPs configured, so the fallback never applies there. An org whose only IdP is misconfigured is not covered by it. The break-glass is an operator disabling that `org_idp_configs` row, which turns the rule back into "any IdP" (runbook). The step-up is an ordinary sign-in (a new session, the old one revoked as `replaced`) rather than a session-mutating re-auth endpoint, which keeps one place where sessions are minted.

## D137: Enrolling an MCP client as an org admin needs the admin step-up

**Date**: 2026-10-25
**Decision**: `POST /v1/oauth/consent/{request_id}/finish` runs the D136 step-up (`admin_step_up::require`, `Target::Org`) whenever the enrolling session's identity resolves to `Admin` in the org (`resolve_access_level`, the same rule `AdminAcl` applies). It does this for both `new` and `reauth`, and it checks before the pending request is consumed, so a refused human can step up and finish the same request within `CONSENT_TTL`. A 403 `step_up_required` raises the dashboard's root-layout `StepUpModal`, as any admin mutation does, and the consent page says why. Members and personal orgs enroll as before. `AdminAcl` itself still does not step bearer credentials up. Tests in `tests/mcp_consent_step_up.rs`.
**Rationale**: D136 exempted bearer credentials because minting one "is itself an `AdminAcl` mutation (an admin key) or is scoped to an agent". The second half is false for an admin's agent. An agent resolves its overslash ACL through its owner's groups, so an org admin's MCP token passes `AdminAcl` on admin mutations, including `POST /v1/api-keys`, which mints a durable admin key. Consent was the one place a bearer was minted outside `AdminAcl`, and it took any session. A magic link re-scoped into a shared org the human administers could therefore do through an MCP token everything D136 refuses it directly. Gating the mint keeps D136's model ("every admin-capable bearer was minted by a session that passed the step-up"), so it holds for MCP tokens the same way it holds for API keys. Gating `AdminAcl` on MCP tokens instead would break agents that legitimately call the `overslash` platform service, and a bearer has no session whose freshness could be checked. Residual: a member's MCP token becomes admin-capable if the member is later promoted. Promotion is itself a stepped-up admin act aimed at that human, so this is accepted. Tokens minted before this change are not re-checked.

## D138: An IdP sign-in's freshness is its `auth_time`, never the callback time; GitHub is the named exception

**Date**: 2026-10-25
**Decision**: Amends D136. An IdP session's `authenticated_at` is the ID token's `auth_time`, parsed as an integer, a fractional number or a numeric string, and clamped to now. When an OIDC IdP sends no usable `auth_time`, `authenticated_at` stays NULL. It no longer falls back to the callback time. The admin step-up then refuses with the new reason `auth_time_missing`, and the dashboard's *Confirm it's you* prompt says the provider can't confirm a recent sign-in and names the operator fix. This holds on every sign-in, not just step-ups. A step-up sends `max_age=0`, and OIDC Core §3.1.2.1 then makes `auth_time` REQUIRED, so an IdP that omits it has not shown that it re-authenticated. An ordinary sign-in that omits it may have been answered from a days-old IdP session. Google sends `auth_time` only when the request asks for it and the OAuth client has *Session age claims* enabled. So every Google login now sends `claims={"id_token":{"auth_time":{"essential":true}}}`, and enabling the setting is an operator step (runbook). `ADMIN_STEP_UP_CALLBACK_TIME_PROVIDERS` (comma-separated provider keys; default `github`; `none` for no exceptions) lists the providers whose callback time stands in when they send no `auth_time`. `providers.rs` `authn_time`; tests in `tests/admin_step_up_auth_time.rs`.
**Rationale**: The callback time says when Overslash got a code back, not when the IdP last checked a credential. Under silent SSO those can be days apart, and the fallback made any such session look fresh for the whole step-up window. GitHub is exempt because it is not OIDC. It has no `auth_time`, no `max_age` and no way to force a re-authentication. Refusing it would lock an org that signs in only through GitHub out of every admin change, including the one that would add a second IdP. Its step-up therefore stays what D136 already said it was: a fresh round-trip, with MFA left to the org's GitHub 2FA requirement. Making that an operator-visible setting means the exception is written down and can be removed (`none`), not hidden in a provider check. The same setting is the break-glass for an IdP that cannot be made to send `auth_time`. Adding its key restores the old behaviour for that provider alone, with the weaker guarantee on record.

## D140: Overloaded actions split into content-classified subactions; a parent grant covers its variants

**Date**: 2026-10-27
**Decision**: An operation or MCP tool may declare `x-overslash-subactions`: variants classified per call by jq over the call's own params. `each` splits a call into items, and each item takes the first variant whose `match` is truthy. A call needs the keys of every matched variant, keyed `{service}:{parent}/{variant}:{arg}`. An unclaimed item keeps the parent's key, and a classifier failure gates the whole call as the parent. The call's risk is the highest of its items' risks. Its description is composed per item. A key's parent form is one of its match forms, so a rule on the parent covers every variant. A variant can opt into being callable with `input_schema` + `transform`. The call is then rewritten into the parent before anything reads its metadata, and it must classify entirely as that variant. This replaces the draft `x-overslash-transform` (hubspot-resty-tools.md Tier 2).
**Rationale**: HubSpot's `manage_crm_objects` writes any CRM object in batches, so its approval read "Create or update CRM records" whatever it wrote, and a single key covered every type. Classifying the call itself, rather than only adding wrapper actions, fixes the call agents already make. Doing it per item is the only reading that is honest about a mixed batch: whole-call matching leaves exactly the mixed calls opaque. Failing coarse rather than open means a gap in the variant list, or a jq error, reverts to the pre-subaction gate rather than dropping an item from it. Parent coverage keeps every existing grant and remembered approval working. Making callable variants classify through the same path is what keeps their keys identical to the raw call's, so one grant covers both ways in.

## D139: Org OAuth App Credentials don't take over built-in Google/GitHub sign-in unless the admin opts the provider in

**Date**: 2026-10-27
**Decision**: For Overslash-managed sign-in (no `org_idp_configs` row claims the provider), login uses the deployment's `{PROVIDER}_AUTH_*` app even when the org has saved OAuth App Credentials (`OAUTH_{PROVIDER}_CLIENT_ID/SECRET` org secrets) for that provider. Those credentials still override env for service connections (SPEC §7). An admin can opt a provider in: a row in `org_oauth_signin_overrides (org_id, provider_key)`, off by default, makes the org's credentials serve sign-in too. It is set from the *Use for sign-in* action on a Google/GitHub row in Org Settings → OAuth App Credentials (`PATCH /v1/org-oauth-credentials/{provider} {override_signin}`), shown only when the org override exists and the env sign-in app is configured, or from the same checkbox on the save form (`PUT … {override_signin}`). Deleting the credentials clears the opt-in. Dedicated IdP rows, including those with `use_org_credentials`, are unchanged: they are already an explicit sign-in choice. There is no backfill, so orgs that had saved Google/GitHub credentials go back to the built-in sign-in app until an admin opts in. `services::org_signin::resolve_org_signin_credentials`; tests in `tests/org_oauth_credentials.rs`.
**Rationale**: Admins save org OAuth credentials to brand or scope service connections, and the old precedence quietly moved every member's login onto that app as well. That app may have a narrower consent screen, test-user limits or unverified status, so login could break for reasons unrelated to sign-in. Making the sign-in takeover a separate, visible opt-in keeps "configure connections" from changing "how people log in".

## D141: `/health` fails when Postgres is down; Cloud Run probes are TCP

**Date**: 2026-10-27
**Decision**: `GET /health` returns 503 `status: degraded` when its bounded `SELECT 1` fails, and 200 `status: ok` otherwise. `/ready` keeps the same gate. The Cloud Run startup and liveness probes on the API are `tcp_socket` probes on the container port, not HTTP probes on `/health`. The GCM uptime check behind `[P0] API Down` and the Better Stack monitor stay on `/health`, so a database outage pages in prod. Dev's nightly Cloud SQL stop therefore fires dev's `API Down` every night, and that is accepted: it emails only, and it proves the path end to end. `routes/health.rs`, `infra/modules/cloud-run/main.tf`.
**Rationale**: `/health` was always-200 so that a Cloud SQL blip would not make the probes restart containers. That never worked. The probe's default 1 s timeout is shorter than `/health`'s 2 s database timeout, so with the database gone the liveness probe failed anyway. Dev's instance was shut down about 90 s after every nightly stop, and a replacement cannot boot without the database (`create_app` connects and migrates eagerly), so Cloud Run answered 500 until morning. The design gave neither a surviving container nor an honest status. Splitting the two questions fixes both. Whether the process is up is a TCP connect, which nothing upstream can fail. Whether the API can serve is `/health`, which the monitors read and which no longer restarts anything. A TCP startup probe gives up nothing, because the listener binds only after `create_app` has connected, migrated and preflighted. No new endpoint was added, since a TCP probe needs none.

## D142: "Allow & Remember" expires after an org-set default, 7 days out of the box; an omitted `ttl` means that default, not forever

**Date**: 2026-10-28
**Decision**: Orgs have a `default_remember_ttl_secs` setting (migration 139). It is nullable, NULL means forever, it is bounded to 60 s to 365 d, and the column default is 604800 (7 days). The column default also backfills every existing org. Admins set it on `PATCH /v1/orgs/{id}/execution-settings`, and Org Settings shows it as a select below the call timeouts. When `POST /v1/approvals/{id}/resolve` gets `allow_remember` with no `ttl`, the rule expires `now + default`. A permanent rule now needs an explicit `ttl: "forever"`, which `/resolve` accepts (it used to 400 on it). The dashboard's Allow split button still starts on Once (#844), tags the org default "· default" in its duration menu, and always sends `ttl`. The MCP remember dialog preselects the org default; if that default is not one of the dialog's menu values, it is added as a `"{n}s"` option, and the dialog forwards `forever` verbatim. The SDK approval card gets an "Org default" choice, selected by default, that leaves `ttl` out. One parser, `overslash_core::types::duration::parse_rule_ttl`, serves `/resolve` and `PATCH /v1/permissions/{id}`.
**Rationale**: Before this, a remembered rule was permanent unless the reviewer changed the picker. "Never" was the preselection, and leaving the field out meant forever. So the cheapest action created the longest-lived grant. The org default had to be applied on the server, when `ttl` is missing, rather than only preselected in the dashboard, because API, MCP and SDK resolvers never see the dashboard. This changes behaviour for API callers that relied on omitting `ttl` to get forever. That trade is deliberate: any caller that wants a permanent grant can still ask for one, and now has to ask explicitly. Backfilling existing orgs instead of grandfathering them to forever is also deliberate, because the safer default should reach the orgs that never chose. Rules already written keep the expiry they were written with.