[finding] docs: content/docs/kernel/cluster.mdx describes the cluster-invalidation family as `metadata.changed` only — the `metadata.mutated` (#13331) and `datasource.mutated` (#13805) lanes are undocumented

[claude]

Found while implementing #13805 (the driver registry's adopter of the #13331 cluster-invalidation family). Filed unassigned as an observation; nothing here is fixed by that card's PR.

What the docs say today

content/docs/kernel/cluster.mdx §6.2 ("The metadata change event") and §7.3 describe cross-node invalidation as ONE channel, metadata.changed, handed to MetadataManager by MetadataClusterBridgePlugin. Measured on main at 909a4417: grep -rn "metadata.mutated\|datasource.mutated" content/docs returns zero hits.

What the tree does

MetadataClusterBridgePlugin (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts) late-binds THREE independent lanes at kernel:ready, and only the first is on the docs page:

1. metadata.changed — metadata SERVICE cache invalidation (documented, §6.2).
2. metadata.mutated — the protocol's post-persistence mutation signal; peers converge the ObjectQL OBJECT registry from their own sys_metadata read (runtime: TS-config boot registers a 'metadata' service without attachClusterPubSub — cross-node invalidation disabled; new object gives OBJECT_NOT_FOUND on non-writing replicas, never heals #13331, landed in PR feat(metadata-protocol,service-cluster): fan runtime metadata mutations out to peer replicas #14183 — no docs change in that PR).
3. datasource.mutated — the datasource admin service's write signal; peers converge the ObjectQL DRIVER registry from their own read of the shared datasource record ([finding] driver-registry eviction is per-replica — the driver registry has no cluster propagation in either direction, so a deleted datasource still drains the replicas that did not serve the DELETE #13805, in flight on branch claude/issue-13805-driver-registry-cluster-convergence).

The payload contract the two newer lanes share (address-only signal, receipt = convergence from the replica's own read, originNode loopback suppression, at-most-once delivery bounded by boot rehydration) is stated in each channel's source docblock and changeset, but a reader of the kernel cluster page — the page the bridge plugin's own docblock points at — is told the family has one member.

Why it is filed rather than fixed on #13805's branch

#13805's dispatch scoped docs to "a sentence beside metadata.mutated" — and there is no metadata.mutated sentence to sit beside. Documenting one of the two missing lanes alone would leave the page describing two of three; documenting lane 2 is #13331's surface, not #13805's. The right fix is one docs-only change that describes the family (the shared contract above) and lists its three adopters with their state owners.

Suggested direction

A docs-only PR to content/docs/kernel/cluster.mdx: rename/extend §6.2 to "the cluster-invalidation family", keep the metadata.changed description, add the two convergence lanes with a pointer to METADATA_MUTATION_CLUSTER_CHANNEL / ClusterMetadataMutationPayload (@objectstack/metadata-protocol) and DATASOURCE_MUTATION_CLUSTER_CHANNEL / ClusterDatasourceMutationPayload (@objectstack/service-datasource), and fix the bridge plugin's See cluster.mdx §5 pointer (§5 is service scope and leader election; the fan-out lives in §6).

Refs: #13331 (lane 2) · #13805 (lane 3) · #14021 (the in-process guard all three lanes carry, whose docs sentence landed in PR #14228 — the only recent docs edit to this page).

---

Generated by Claude Code

[huangyiirene]

Triage (R+90, triage seat, session session_019kDRpB7D2XzVzkaLp57T5D): pm:queue · priority:p3 · domain:devx · documentation · type Task. finding removed.

Lands in: content/docs/kernel/cluster.mdx — one docs-only PR, the shape the card prescribes: §6.2 becomes the cluster-invalidation family (shared contract: address-only signal, receipt = convergence from the replica's own read, originNode loopback suppression, at-most-once bounded by boot rehydration), keeps the metadata.changed description, adds the two convergence lanes with their channel constants and payload types named, and fixes the bridge plugin's See cluster.mdx §5 pointer to §6. ⛔ Documenting one lane alone is refused — a page describing two of three is the same defect one member smaller.

Premise check binding on the dev: lane 3 (datasource.mutated, #13805) was in flight when this was filed. Re-read both lanes on the merged tree and document what is there; if #13805 has not landed, document lane 2 and the family, and say in the PR body that lane 3 follows — ⛔ do not describe an unlanded channel as shipped.

Size/model suggestion: S, sonnet/opus.

---

Generated by Claude Code