docs(kernel): document the cluster-invalidation family (#14339)

[claude]

Fixes#14339

What

content/docs/kernel/cluster.mdx §6.2 described cross-node metadata
invalidation as one channel, metadata.changed. Two more convergence lanes
exist in the tree and were undocumented: metadata.mutated (#13331, the
ObjectQL object registry) and datasource.mutated (#13805, the ObjectQL
driver registry).

Both lanes are landed on main:

• METADATA_MUTATION_CLUSTER_CHANNEL = 'metadata.mutated' —
  packages/metadata-protocol/src/protocol.ts:4010, ClusterMetadataMutationPayload
  at :4023 (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, closed).
• DATASOURCE_MUTATION_CLUSTER_CHANNEL = 'datasource.mutated' —
  packages/services/service-datasource/src/datasource-admin-service.ts:71,
  ClusterDatasourceMutationPayload at :86 ([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, closed).
• MetadataClusterBridgePlugin (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts)
  binds all three lanes at kernel:ready (:80-82) and its header docblock
  (:18-58) already describes all three — the source of truth this PR turns
  into reader-facing docs.

git grep -n "metadata\.mutated\|datasource\.mutated" -- content/docs was
zero hits before this PR.

Docs change

content/docs/kernel/cluster.mdx §6.2 retitled "The cluster-invalidation
family": a summary table (channel · payload type · package · what it
converges) plus the shared contract the two newer lanes carry (address-only
signal, receipt = convergence from the replica's own read, originNode
loopback suppression, at-most-once bounded by boot rehydration — quoting
protocol.ts:5020-5027 and datasource-admin-service.ts:331-337 verbatim).
The existing metadata.changed description is kept, unchanged in substance,
as "Lane 1"; two new subsections, "Lane 2" and "Lane 3", document the two
missing channels with their channel constants, payload types and receipt
logic. Section numbering is unchanged — §6.3/§7.x are untouched, and the new
content lives inside §6.2 as ####-level sub-parts.

Also added: one cross-reference sentence in §7.3 ("I want to read metadata
in a long-lived cache") noting that a cache of ObjectQL's object/driver
registry state is already converged by lanes 2/3 and does not need its own
metadata.changed subscription.

packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts:58
— the docblock's See content/docs/kernel/cluster.mdx §5. pointer was wrong
(§5 is service scope/leader election; the fan-out lives in §6) — fixed to
§6.2. Comment text only, no code change.

Left untouched, per the card's scope: services-checklist.mdx:150's
"Multi-instance Sync" row and concepts/metadata-lifecycle.mdx:179 both
describe metadata.changed specifically (lane 1's own mechanism), in their
own scoped context — neither claims to be the complete cluster-invalidation
story, so neither reads as misleading after this PR.

Out of scope

content/docs/kernel/cluster.mdx §6.1/§6.3/§7.1/§7.2 (version
widening, the planned reader contract, event-firing/service-registration
guidance) are untouched — none of it is about the invalidation family.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 4 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 93940d4928b2a49c3adff5f9f82dda4215b6f696 → packageMentionDocs.

[claude]

Fixes#14339

What

content/docs/kernel/cluster.mdx §6.2 described cross-node metadata
invalidation as one channel, metadata.changed. Two more convergence lanes
exist in the tree and were undocumented: metadata.mutated (#13331, the
ObjectQL object registry) and datasource.mutated (#13805, the ObjectQL
driver registry).

Both lanes are landed on main:

• METADATA_MUTATION_CLUSTER_CHANNEL = 'metadata.mutated' —
  packages/metadata-protocol/src/protocol.ts:4010, ClusterMetadataMutationPayload
  at :4023 (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, closed).
• DATASOURCE_MUTATION_CLUSTER_CHANNEL = 'datasource.mutated' —
  packages/services/service-datasource/src/datasource-admin-service.ts:71,
  ClusterDatasourceMutationPayload at :86 ([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, closed).
• MetadataClusterBridgePlugin (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts)
  binds all three lanes at kernel:ready (:80-82) and its header docblock
  (:18-58) already describes all three — the source of truth this PR turns
  into reader-facing docs.

git grep -n "metadata\.mutated\|datasource\.mutated" -- content/docs was
zero hits before this PR.

Docs change

content/docs/kernel/cluster.mdx §6.2 retitled "The cluster-invalidation
family": a summary table (channel · payload type · package · what it
converges) plus the shared contract the two newer lanes carry (address-only
signal, receipt = convergence from the replica's own read, originNode
loopback suppression, at-most-once bounded by boot rehydration — quoting
protocol.ts:5020-5027 and datasource-admin-service.ts:331-337 verbatim).
The existing metadata.changed description is kept, unchanged in substance,
as "Lane 1"; two new subsections, "Lane 2" and "Lane 3", document the two
missing channels with their channel constants, payload types and receipt
logic. Section numbering is unchanged — §6.3/§7.x are untouched, and the new
content lives inside §6.2 as ####-level sub-parts.

Also added: one cross-reference sentence in §7.3 ("I want to read metadata
in a long-lived cache") noting that a cache of ObjectQL's object/driver
registry state is already converged by lanes 2/3 and does not need its own
metadata.changed subscription.

packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts:58
— the docblock's See content/docs/kernel/cluster.mdx §5. pointer was wrong
(§5 is service scope/leader election; the fan-out lives in §6) — fixed to
§6.2. Comment text only, no code change.

Left untouched, per the card's scope: services-checklist.mdx:150's
"Multi-instance Sync" row and concepts/metadata-lifecycle.mdx:179 both
describe metadata.changed specifically (lane 1's own mechanism), in their
own scoped context — neither claims to be the complete cluster-invalidation
story, so neither reads as misleading after this PR.

Out of scope

content/docs/kernel/cluster.mdx §6.1/§6.3/§7.1/§7.2 (version
widening, the planned reader contract, event-firing/service-registration
guidance) are untouched — none of it is about the invalidation family.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 4 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 93940d4928b2a49c3adff5f9f82dda4215b6f696 → packageMentionDocs.

[claude]

Fixes#14339

What

content/docs/kernel/cluster.mdx §6.2 described cross-node metadata
invalidation as one channel, metadata.changed. Two more convergence lanes
exist in the tree and were undocumented: metadata.mutated (#13331, the
ObjectQL object registry) and datasource.mutated (#13805, the ObjectQL
driver registry).

Both lanes are landed on main:

• METADATA_MUTATION_CLUSTER_CHANNEL = 'metadata.mutated' —
  packages/metadata-protocol/src/protocol.ts:4010, ClusterMetadataMutationPayload
  at :4023 (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, closed).
• DATASOURCE_MUTATION_CLUSTER_CHANNEL = 'datasource.mutated' —
  packages/services/service-datasource/src/datasource-admin-service.ts:71,
  ClusterDatasourceMutationPayload at :86 ([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, closed).
• MetadataClusterBridgePlugin (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts)
  binds all three lanes at kernel:ready (:80-82) and its header docblock
  (:18-58) already describes all three — the source of truth this PR turns
  into reader-facing docs.

git grep -n "metadata\.mutated\|datasource\.mutated" -- content/docs was
zero hits before this PR.

Docs change

content/docs/kernel/cluster.mdx §6.2 retitled "The cluster-invalidation
family": a summary table (channel · payload type · package · what it
converges) plus the shared contract the two newer lanes carry (address-only
signal, receipt = convergence from the replica's own read, originNode
loopback suppression, at-most-once bounded by boot rehydration — quoting
protocol.ts:5020-5027 and datasource-admin-service.ts:331-337 verbatim).
The existing metadata.changed description is kept, unchanged in substance,
as "Lane 1"; two new subsections, "Lane 2" and "Lane 3", document the two
missing channels with their channel constants, payload types and receipt
logic. Section numbering is unchanged — §6.3/§7.x are untouched, and the new
content lives inside §6.2 as ####-level sub-parts.

Also added: one cross-reference sentence in §7.3 ("I want to read metadata
in a long-lived cache") noting that a cache of ObjectQL's object/driver
registry state is already converged by lanes 2/3 and does not need its own
metadata.changed subscription.

packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts:58
— the docblock's See content/docs/kernel/cluster.mdx §5. pointer was wrong
(§5 is service scope/leader election; the fan-out lives in §6) — fixed to
§6.2. Comment text only, no code change.

Left untouched, per the card's scope: services-checklist.mdx:150's
"Multi-instance Sync" row and concepts/metadata-lifecycle.mdx:179 both
describe metadata.changed specifically (lane 1's own mechanism), in their
own scoped context — neither claims to be the complete cluster-invalidation
story, so neither reads as misleading after this PR.

Out of scope

content/docs/kernel/cluster.mdx §6.1/§6.3/§7.1/§7.2 (version
widening, the planned reader contract, event-firing/service-registration
guidance) are untouched — none of it is about the invalidation family.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 4 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 93940d4928b2a49c3adff5f9f82dda4215b6f696 → packageMentionDocs.

[claude]

Fixes#14339

What

content/docs/kernel/cluster.mdx §6.2 described cross-node metadata
invalidation as one channel, metadata.changed. Two more convergence lanes
exist in the tree and were undocumented: metadata.mutated (#13331, the
ObjectQL object registry) and datasource.mutated (#13805, the ObjectQL
driver registry).

Both lanes are landed on main:

• METADATA_MUTATION_CLUSTER_CHANNEL = 'metadata.mutated' —
  packages/metadata-protocol/src/protocol.ts:4010, ClusterMetadataMutationPayload
  at :4023 (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, closed).
• DATASOURCE_MUTATION_CLUSTER_CHANNEL = 'datasource.mutated' —
  packages/services/service-datasource/src/datasource-admin-service.ts:71,
  ClusterDatasourceMutationPayload at :86 ([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, closed).
• MetadataClusterBridgePlugin (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts)
  binds all three lanes at kernel:ready (:80-82) and its header docblock
  (:18-58) already describes all three — the source of truth this PR turns
  into reader-facing docs.

git grep -n "metadata\.mutated\|datasource\.mutated" -- content/docs was
zero hits before this PR.

Docs change

content/docs/kernel/cluster.mdx §6.2 retitled "The cluster-invalidation
family": a summary table (channel · payload type · package · what it
converges) plus the shared contract the two newer lanes carry (address-only
signal, receipt = convergence from the replica's own read, originNode
loopback suppression, at-most-once bounded by boot rehydration — quoting
protocol.ts:5020-5027 and datasource-admin-service.ts:331-337 verbatim).
The existing metadata.changed description is kept, unchanged in substance,
as "Lane 1"; two new subsections, "Lane 2" and "Lane 3", document the two
missing channels with their channel constants, payload types and receipt
logic. Section numbering is unchanged — §6.3/§7.x are untouched, and the new
content lives inside §6.2 as ####-level sub-parts.

Also added: one cross-reference sentence in §7.3 ("I want to read metadata
in a long-lived cache") noting that a cache of ObjectQL's object/driver
registry state is already converged by lanes 2/3 and does not need its own
metadata.changed subscription.

packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts:58
— the docblock's See content/docs/kernel/cluster.mdx §5. pointer was wrong
(§5 is service scope/leader election; the fan-out lives in §6) — fixed to
§6.2. Comment text only, no code change.

Left untouched, per the card's scope: services-checklist.mdx:150's
"Multi-instance Sync" row and concepts/metadata-lifecycle.mdx:179 both
describe metadata.changed specifically (lane 1's own mechanism), in their
own scoped context — neither claims to be the complete cluster-invalidation
story, so neither reads as misleading after this PR.

Out of scope

content/docs/kernel/cluster.mdx §6.1/§6.3/§7.1/§7.2 (version
widening, the planned reader contract, event-firing/service-registration
guidance) are untouched — none of it is about the invalidation family.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 4 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 93940d4928b2a49c3adff5f9f82dda4215b6f696 → packageMentionDocs.

[claude]

Fixes#14339

What

content/docs/kernel/cluster.mdx §6.2 described cross-node metadata
invalidation as one channel, metadata.changed. Two more convergence lanes
exist in the tree and were undocumented: metadata.mutated (#13331, the
ObjectQL object registry) and datasource.mutated (#13805, the ObjectQL
driver registry).

Both lanes are landed on main:

• METADATA_MUTATION_CLUSTER_CHANNEL = 'metadata.mutated' —
  packages/metadata-protocol/src/protocol.ts:4010, ClusterMetadataMutationPayload
  at :4023 (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, closed).
• DATASOURCE_MUTATION_CLUSTER_CHANNEL = 'datasource.mutated' —
  packages/services/service-datasource/src/datasource-admin-service.ts:71,
  ClusterDatasourceMutationPayload at :86 ([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, closed).
• MetadataClusterBridgePlugin (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts)
  binds all three lanes at kernel:ready (:80-82) and its header docblock
  (:18-58) already describes all three — the source of truth this PR turns
  into reader-facing docs.

git grep -n "metadata\.mutated\|datasource\.mutated" -- content/docs was
zero hits before this PR.

Docs change

content/docs/kernel/cluster.mdx §6.2 retitled "The cluster-invalidation
family": a summary table (channel · payload type · package · what it
converges) plus the shared contract the two newer lanes carry (address-only
signal, receipt = convergence from the replica's own read, originNode
loopback suppression, at-most-once bounded by boot rehydration — quoting
protocol.ts:5020-5027 and datasource-admin-service.ts:331-337 verbatim).
The existing metadata.changed description is kept, unchanged in substance,
as "Lane 1"; two new subsections, "Lane 2" and "Lane 3", document the two
missing channels with their channel constants, payload types and receipt
logic. Section numbering is unchanged — §6.3/§7.x are untouched, and the new
content lives inside §6.2 as ####-level sub-parts.

Also added: one cross-reference sentence in §7.3 ("I want to read metadata
in a long-lived cache") noting that a cache of ObjectQL's object/driver
registry state is already converged by lanes 2/3 and does not need its own
metadata.changed subscription.

packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts:58
— the docblock's See content/docs/kernel/cluster.mdx §5. pointer was wrong
(§5 is service scope/leader election; the fan-out lives in §6) — fixed to
§6.2. Comment text only, no code change.

Left untouched, per the card's scope: services-checklist.mdx:150's
"Multi-instance Sync" row and concepts/metadata-lifecycle.mdx:179 both
describe metadata.changed specifically (lane 1's own mechanism), in their
own scoped context — neither claims to be the complete cluster-invalidation
story, so neither reads as misleading after this PR.

Out of scope

content/docs/kernel/cluster.mdx §6.1/§6.3/§7.1/§7.2 (version
widening, the planned reader contract, event-firing/service-registration
guidance) are untouched — none of it is about the invalidation family.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 4 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 93940d4928b2a49c3adff5f9f82dda4215b6f696 → packageMentionDocs.

[claude]

Fixes#14339

What

content/docs/kernel/cluster.mdx §6.2 described cross-node metadata
invalidation as one channel, metadata.changed. Two more convergence lanes
exist in the tree and were undocumented: metadata.mutated (#13331, the
ObjectQL object registry) and datasource.mutated (#13805, the ObjectQL
driver registry).

Both lanes are landed on main:

• METADATA_MUTATION_CLUSTER_CHANNEL = 'metadata.mutated' —
  packages/metadata-protocol/src/protocol.ts:4010, ClusterMetadataMutationPayload
  at :4023 (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, closed).
• DATASOURCE_MUTATION_CLUSTER_CHANNEL = 'datasource.mutated' —
  packages/services/service-datasource/src/datasource-admin-service.ts:71,
  ClusterDatasourceMutationPayload at :86 ([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, closed).
• MetadataClusterBridgePlugin (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts)
  binds all three lanes at kernel:ready (:80-82) and its header docblock
  (:18-58) already describes all three — the source of truth this PR turns
  into reader-facing docs.

git grep -n "metadata\.mutated\|datasource\.mutated" -- content/docs was
zero hits before this PR.

Docs change

content/docs/kernel/cluster.mdx §6.2 retitled "The cluster-invalidation
family": a summary table (channel · payload type · package · what it
converges) plus the shared contract the two newer lanes carry (address-only
signal, receipt = convergence from the replica's own read, originNode
loopback suppression, at-most-once bounded by boot rehydration — quoting
protocol.ts:5020-5027 and datasource-admin-service.ts:331-337 verbatim).
The existing metadata.changed description is kept, unchanged in substance,
as "Lane 1"; two new subsections, "Lane 2" and "Lane 3", document the two
missing channels with their channel constants, payload types and receipt
logic. Section numbering is unchanged — §6.3/§7.x are untouched, and the new
content lives inside §6.2 as ####-level sub-parts.

Also added: one cross-reference sentence in §7.3 ("I want to read metadata
in a long-lived cache") noting that a cache of ObjectQL's object/driver
registry state is already converged by lanes 2/3 and does not need its own
metadata.changed subscription.

packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts:58
— the docblock's See content/docs/kernel/cluster.mdx §5. pointer was wrong
(§5 is service scope/leader election; the fan-out lives in §6) — fixed to
§6.2. Comment text only, no code change.

Left untouched, per the card's scope: services-checklist.mdx:150's
"Multi-instance Sync" row and concepts/metadata-lifecycle.mdx:179 both
describe metadata.changed specifically (lane 1's own mechanism), in their
own scoped context — neither claims to be the complete cluster-invalidation
story, so neither reads as misleading after this PR.

Out of scope

content/docs/kernel/cluster.mdx §6.1/§6.3/§7.1/§7.2 (version
widening, the planned reader contract, event-firing/service-registration
guidance) are untouched — none of it is about the invalidation family.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 4 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 93940d4928b2a49c3adff5f9f82dda4215b6f696 → packageMentionDocs.

[claude]

Fixes#14339

What

content/docs/kernel/cluster.mdx §6.2 described cross-node metadata
invalidation as one channel, metadata.changed. Two more convergence lanes
exist in the tree and were undocumented: metadata.mutated (#13331, the
ObjectQL object registry) and datasource.mutated (#13805, the ObjectQL
driver registry).

Both lanes are landed on main:

• METADATA_MUTATION_CLUSTER_CHANNEL = 'metadata.mutated' —
  packages/metadata-protocol/src/protocol.ts:4010, ClusterMetadataMutationPayload
  at :4023 (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, closed).
• DATASOURCE_MUTATION_CLUSTER_CHANNEL = 'datasource.mutated' —
  packages/services/service-datasource/src/datasource-admin-service.ts:71,
  ClusterDatasourceMutationPayload at :86 ([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, closed).
• MetadataClusterBridgePlugin (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts)
  binds all three lanes at kernel:ready (:80-82) and its header docblock
  (:18-58) already describes all three — the source of truth this PR turns
  into reader-facing docs.

git grep -n "metadata\.mutated\|datasource\.mutated" -- content/docs was
zero hits before this PR.

Docs change

content/docs/kernel/cluster.mdx §6.2 retitled "The cluster-invalidation
family": a summary table (channel · payload type · package · what it
converges) plus the shared contract the two newer lanes carry (address-only
signal, receipt = convergence from the replica's own read, originNode
loopback suppression, at-most-once bounded by boot rehydration — quoting
protocol.ts:5020-5027 and datasource-admin-service.ts:331-337 verbatim).
The existing metadata.changed description is kept, unchanged in substance,
as "Lane 1"; two new subsections, "Lane 2" and "Lane 3", document the two
missing channels with their channel constants, payload types and receipt
logic. Section numbering is unchanged — §6.3/§7.x are untouched, and the new
content lives inside §6.2 as ####-level sub-parts.

Also added: one cross-reference sentence in §7.3 ("I want to read metadata
in a long-lived cache") noting that a cache of ObjectQL's object/driver
registry state is already converged by lanes 2/3 and does not need its own
metadata.changed subscription.

packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts:58
— the docblock's See content/docs/kernel/cluster.mdx §5. pointer was wrong
(§5 is service scope/leader election; the fan-out lives in §6) — fixed to
§6.2. Comment text only, no code change.

Left untouched, per the card's scope: services-checklist.mdx:150's
"Multi-instance Sync" row and concepts/metadata-lifecycle.mdx:179 both
describe metadata.changed specifically (lane 1's own mechanism), in their
own scoped context — neither claims to be the complete cluster-invalidation
story, so neither reads as misleading after this PR.

Out of scope

content/docs/kernel/cluster.mdx §6.1/§6.3/§7.1/§7.2 (version
widening, the planned reader contract, event-firing/service-registration
guidance) are untouched — none of it is about the invalidation family.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 4 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 93940d4928b2a49c3adff5f9f82dda4215b6f696 → packageMentionDocs.

[claude]

Fixes#14339

What

content/docs/kernel/cluster.mdx §6.2 described cross-node metadata
invalidation as one channel, metadata.changed. Two more convergence lanes
exist in the tree and were undocumented: metadata.mutated (#13331, the
ObjectQL object registry) and datasource.mutated (#13805, the ObjectQL
driver registry).

Both lanes are landed on main:

• METADATA_MUTATION_CLUSTER_CHANNEL = 'metadata.mutated' —
  packages/metadata-protocol/src/protocol.ts:4010, ClusterMetadataMutationPayload
  at :4023 (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, closed).
• DATASOURCE_MUTATION_CLUSTER_CHANNEL = 'datasource.mutated' —
  packages/services/service-datasource/src/datasource-admin-service.ts:71,
  ClusterDatasourceMutationPayload at :86 ([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, closed).
• MetadataClusterBridgePlugin (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts)
  binds all three lanes at kernel:ready (:80-82) and its header docblock
  (:18-58) already describes all three — the source of truth this PR turns
  into reader-facing docs.

git grep -n "metadata\.mutated\|datasource\.mutated" -- content/docs was
zero hits before this PR.

Docs change

content/docs/kernel/cluster.mdx §6.2 retitled "The cluster-invalidation
family": a summary table (channel · payload type · package · what it
converges) plus the shared contract the two newer lanes carry (address-only
signal, receipt = convergence from the replica's own read, originNode
loopback suppression, at-most-once bounded by boot rehydration — quoting
protocol.ts:5020-5027 and datasource-admin-service.ts:331-337 verbatim).
The existing metadata.changed description is kept, unchanged in substance,
as "Lane 1"; two new subsections, "Lane 2" and "Lane 3", document the two
missing channels with their channel constants, payload types and receipt
logic. Section numbering is unchanged — §6.3/§7.x are untouched, and the new
content lives inside §6.2 as ####-level sub-parts.

Also added: one cross-reference sentence in §7.3 ("I want to read metadata
in a long-lived cache") noting that a cache of ObjectQL's object/driver
registry state is already converged by lanes 2/3 and does not need its own
metadata.changed subscription.

packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts:58
— the docblock's See content/docs/kernel/cluster.mdx §5. pointer was wrong
(§5 is service scope/leader election; the fan-out lives in §6) — fixed to
§6.2. Comment text only, no code change.

Left untouched, per the card's scope: services-checklist.mdx:150's
"Multi-instance Sync" row and concepts/metadata-lifecycle.mdx:179 both
describe metadata.changed specifically (lane 1's own mechanism), in their
own scoped context — neither claims to be the complete cluster-invalidation
story, so neither reads as misleading after this PR.

Out of scope

content/docs/kernel/cluster.mdx §6.1/§6.3/§7.1/§7.2 (version
widening, the planned reader contract, event-firing/service-registration
guidance) are untouched — none of it is about the invalidation family.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 4 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 93940d4928b2a49c3adff5f9f82dda4215b6f696 → packageMentionDocs.