docs(metadata): the metadata.mutated receipt now retires the overlay-read cache too

#13609's bumpWriteEpoch call in applyRemoteMetadataMutation retires the
sys_metadata overlay-row cache directly, on the same shared engine write
epoch the authz.invalidated bridge already bumps. Two doc claims dated from
before that fix and named authz.invalidated as the only non-local retirement
path, with OS_METADATA_OVERLAY_CACHE_TTL_MS as the sole floor otherwise:

- content/docs/concepts/metadata-lifecycle.mdx's cross-replica-sync note
- content/docs/deployment/environment-variables.mdx's OS_METADATA_OVERLAY_CACHE_TTL_MS
  and OS_LOCALIZATION_CACHE_TTL_MS rows (the localization cache in
  packages/core/src/security/resolve-authz-context.ts reads the identical
  engine.writeEpoch seam, so it is retired by the same bump)

Narrowed the lag claim to match: the TTL is now the floor only on a
deployment with no cluster bridge attached at all (in-process `memory`
driver), not on every deployment lacking the authz.invalidated bridge
specifically. content/docs/kernel/cluster.mdx was flagged by the PR's own
docs-drift-check bot (it names applyRemoteMetadataMutation) but makes no
claim about the overlay-cache/write-epoch bound at all — left unchanged.

No code, test, or changeset touched — the patch changeset already on this
branch covers the behavior change; this is a documentation-only correction
on top of it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0112hMx9hjJ9BgB28X97DS68

Author: claude

content/docs/concepts/metadata-lifecycle.mdx

@@ -190,11 +190,17 @@ The hash is `sha256:` + 64-hex of a canonical (sorted-keys, no-undefined) JSON s
 > before its own middleware chain runs, so read-your-writes is exact on the node
 > that made the write. A **peer's** write does not: `metadata.changed` invalidates
 > the MetadataManager caches this note is about, but it does not retire the
-> overlay-read cache. What retires that on a peer is the `authz.invalidated`
-> channel — a hint from another node bumps the local write epoch — or, failing
-> that, `OS_METADATA_OVERLAY_CACHE_TTL_MS` (default 30s, `0` disables the cache
-> outright). So on a deployment with no distributed cluster driver attached, a
-> peer's overlay re-read can lag a remote publish by up to that TTL. See
+> overlay-read cache. What retires that on a peer is either of two receipt
+> paths that bump the same local write epoch: the `metadata.mutated`
+> channel's own — `protocol.ts`'s `applyRemoteMetadataMutation` calls
+> `bumpWriteEpoch(engine, 'remote')` right after its registry converges and
+> before local listeners run (#13609, 2026-09-03) — or the `authz.invalidated`
+> channel's bridge, which bumps the same epoch for the authorization cache
+> and retires this one too, as a side effect of sharing it. Failing both, the
+> floor is `OS_METADATA_OVERLAY_CACHE_TTL_MS` (default 30s, `0` disables the cache
+> outright). So only on a deployment with no cluster bridge attached at all —
+> the in-process `memory` driver, with no distributed driver behind it — does
+> a peer's overlay re-read still lag a remote publish by up to that TTL. See
 > [Environment variables](/docs/deployment/environment-variables).
 
 ---

content/docs/deployment/environment-variables.mdx

@@ -361,8 +361,8 @@ the hosted ObjectOS Cloud control plane.
 | `OS_SANDBOX_HOOK_TIMEOUT_MS` | number | `250` | Default **CPU-time** budget for a sandboxed **hook** body (QuickJS, ADR-0102): how much *VM-active* time a body may burn — idle host-await time and a nested hook's own run are NOT charged. A loaded/slow host rarely needs to raise this now (it is not wall-clock), but the knob remains. Only a positive integer is honored; unset / non-numeric / non-positive keeps the 250ms default. A hook body's own declared `timeoutMs` still wins over this. |
 | `OS_SANDBOX_ACTION_TIMEOUT_MS` | number | `5000` | Default **CPU-time** budget for a sandboxed **action** body (QuickJS). Same resolution rules as the hook variant above (positive integer only; an action body's own `timeoutMs` still wins). |
 | `OS_SANDBOX_WALL_CEILING_MS` | number | `30000` | Wall-clock ceiling (ADR-0102) — the backstop that cuts a hook/action body stuck on a host call that never settles (which burns no CPU, so the CPU budget alone would never fire). The effective ceiling is `max(this, cpuBudget)`, so it can never cut a body still inside its CPU budget. Positive integer only; unset keeps 30s. |
-| `OS_LOCALIZATION_CACHE_TTL_MS` | number | `30000` | Staleness bound, in milliseconds, for the cross-request cache of a workspace's reference localization (`timezone` / `locale` / `currency`, read from `sys_setting`) — leg C of #11633. `0` means **off**, a real path that restores the uncached query pattern exactly. Unlike `OS_AUTHZ_GRANTS_CACHE_TTL_MS` (which is off by default) this one ships **on**, because its invalidation is synchronous and in-process rather than TTL-bound: a `localization` settings change and any engine write both retire a cached answer immediately, so the TTL only bounds what neither seam can see — a write made on another replica with no `authz.invalidated` bridge attached. ⚠️ A malformed value reads as `0` (off), the opposite arm from the grants variable and deliberately so: there `0` is also the default, whereas here folding `3OOO` (letter O) into the default would hand you a **longer** window than the one you were setting. Deployment config only — never a settings row, because `sys_setting` is the table this cache caches. |
-| `OS_METADATA_OVERLAY_CACHE_TTL_MS` | number | `30000` | Staleness bound, in milliseconds, for the cross-request cache of the `sys_metadata` overlay read inside `getMetaItems` — leg D of #11633. `0` means **off**, a real path that restores the uncached query pattern exactly. Ships **on**, for the same reason as `OS_LOCALIZATION_CACHE_TTL_MS`: invalidation is synchronous and in-process, because every `sys_metadata` write goes through the engine and so advances the write epoch that retires the entry before the next read. What is cached is the overlay ROW SET only — never the merged answer — so the SchemaRegistry, the MetadataService and the artifact table are re-consulted on every call, cached or not, and the read-side registry hydration keeps running on a cache hit. The TTL therefore bounds one thing: a write made on **another replica** with no `authz.invalidated` bridge attached. ⚠️ A malformed value reads as `0` (off) — same arm and same reason as `OS_LOCALIZATION_CACHE_TTL_MS`. Deployment config only, never a settings row. |
+| `OS_LOCALIZATION_CACHE_TTL_MS` | number | `30000` | Staleness bound, in milliseconds, for the cross-request cache of a workspace's reference localization (`timezone` / `locale` / `currency`, read from `sys_setting`) — leg C of #11633. `0` means **off**, a real path that restores the uncached query pattern exactly. Unlike `OS_AUTHZ_GRANTS_CACHE_TTL_MS` (which is off by default) this one ships **on**, because its invalidation is synchronous and in-process rather than TTL-bound: a `localization` settings change and any engine write both retire a cached answer immediately, so the TTL only bounds what neither seam can see — a write made on another replica with no cluster bridge attached at all: neither the `metadata.mutated` channel's receipt path (`applyRemoteMetadataMutation` calls `bumpWriteEpoch`, #13609) nor the `authz.invalidated` bridge, both of which bump this same epoch when attached. ⚠️ A malformed value reads as `0` (off), the opposite arm from the grants variable and deliberately so: there `0` is also the default, whereas here folding `3OOO` (letter O) into the default would hand you a **longer** window than the one you were setting. Deployment config only — never a settings row, because `sys_setting` is the table this cache caches. |
+| `OS_METADATA_OVERLAY_CACHE_TTL_MS` | number | `30000` | Staleness bound, in milliseconds, for the cross-request cache of the `sys_metadata` overlay read inside `getMetaItems` — leg D of #11633. `0` means **off**, a real path that restores the uncached query pattern exactly. Ships **on**, for the same reason as `OS_LOCALIZATION_CACHE_TTL_MS`: invalidation is synchronous and in-process, because every `sys_metadata` write goes through the engine and so advances the write epoch that retires the entry before the next read. What is cached is the overlay ROW SET only — never the merged answer — so the SchemaRegistry, the MetadataService and the artifact table are re-consulted on every call, cached or not, and the read-side registry hydration keeps running on a cache hit. The TTL therefore bounds one thing: a write made on **another replica** with no cluster bridge attached at all — neither the `metadata.mutated` channel's own receipt path (`applyRemoteMetadataMutation` calls `bumpWriteEpoch` right after registry convergence, #13609) nor the `authz.invalidated` bridge, either of which retires this entry the moment it is attached and fires. ⚠️ A malformed value reads as `0` (off) — same arm and same reason as `OS_LOCALIZATION_CACHE_TTL_MS`. Deployment config only, never a settings row. |
 | `OS_INLINE_SEED_BUDGET_MS` | number | `8000` | Time budget for synchronous seed execution at boot before deferring to a worker. |
 | `OS_TENANT_AUDIT` | flag | `1` | Set to `0` to silence the tenant-isolation audit warnings emitted by the SQL driver. |