feat(service-datasource,service-cluster): fan datasource record writes out to peer replicas so a deleted datasource stops draining every replica (#13805)

[claude]

Fixes #13805

What this does

The ObjectQL driver registry had no cluster propagation in either direction: each replica filled it at boot from the shared datasource records and mutated it only for the writes it served. After DELETE /api/v1/datasources/:name only the replica that served the DELETE evicted the stuck driver (#13578's door, unchanged here); the other N-1 kept it — and /api/v1/ready kept answering 503 there — until restart. A create through one replica likewise had no pool anywhere else until restart.

Ruled shape (maintainer, 2026-09-01, director batch A — quoted verbatim in the card): the driver registry reuses the cluster-invalidation family #13331-A established; datasource writes (create and delete, symmetric) emit the signal through the same bridge shape; each replica converges by re-reading the shared datasource records; no second propagation mechanism. This PR builds exactly that and nothing beside it:

• Symmetric publisher at the three write doors (packages/services/service-datasource/src/datasource-admin-service.ts): after createDatasource, updateDatasource and removeDatasource, DatasourceAdminService publishes the record's ADDRESS — { originNode, name } — on a new cluster channel datasource.mutated (DATASOURCE_MUTATION_CLUSTER_CHANNEL, payload ClusterDatasourceMutationPayload). Fire-and-forget; a publish failure never fails the write. migrateCredential does not publish (it leaves the live pool alone by design, on every replica alike). A delete-only broadcast was deliberately not built — the triage constraint on symmetry.
• Peers converge from their OWN read of the SHARED record (datasource-admin-plugin.ts, new convergePool seam on DatasourceAdminServiceConfig): on receipt a replica re-reads the durable sys_metadata row for that name — the store its boot rehydration reads, NOT its per-replica metadata registry (which on the host-config boot has no cluster seam and is exactly the stale read a peer must not converge from) — and drives its pool through the seams it already owns: build what is missing, rebuild in place what changed (reregisterPool, keeping the old pool on failure exactly as the serving replica's update path does, datasource update never rebuilds its driver — already-registered short-circuits the reconfigure path, so the OLD pool stays live and the admin UI reports success #13804), evict what is gone (unregisterPool, the datasource DELETE does not evict the stuck driver from the data-engine driver registry — /ready keeps naming a datasource that no longer exists, recoverable only by process restart #13578 door), leave a matching pool untouched. The record each live pool was built from is remembered by the pool seams themselves (livePoolRecords), which is what makes a duplicate delivery a measured no-op and a stray name harmless: only pools this plugin built are ever touched, so a code-defined pool survives a stray signal. This answers the triage's third question — a replayed create is safe because receipt is convergence, not replay; no new idempotency machinery.
• Attach seam mirrored from the shipped bridges: DatasourceAdminService.attachDatasourceMutationPubSub(pubsub, nodeId) — idempotent on the (pubsub, nodeId) pair, originNode loopback suppression, per-name ordered convergence, shaped after ObjectStackProtocolImplementation.attachMetadataMutationPubSub(). Only IPubSub from @objectstack/spec/contracts crosses it: @objectstack/service-datasource takes no dependency on the cluster service, and @objectstack/objectql is handed no bus (the layering line triage drew — measured: service-cluster depends on core + spec only; service-datasource on core/spec/types/drivers; neither on the other).
• Third lane in MetadataClusterBridgePlugin (packages/services/service-cluster/src/metadata-cluster-bridge-plugin.ts): late-binds the seam at kernel:ready beside the metadata-service and protocol lanes, duck-typed on the datasource-admin service, guarded off the in-process memory driver from birth. A lane rather than a fourth plugin because that is how 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-A itself adopted the family (lane 2 was added to this plugin), it needs no Runtime wiring change, and it adds no exported symbol to service-cluster.

Not touched, per the card's constraints: the /api/v1/meta/datasource metadata registry (#13609 / #13405 — different sink; the peer's metadata registry is deliberately NOT written by convergence, pinned) and #13578's eviction primitive itself. Log levels follow the exemplars' sites one-for-one (debug for skips, info for the bridged/attached lines, warn for publish/converge failures, the exemplar's error for attach/detach exceptions); no new error sink.

Verification

Base: 909a4417 (origin/main at claim). Final head: 6be669f6. Dependency closure built in the worktree first (pnpm --filter '@objectstack/service-datasource^...' build, VERDICT command-exit 0), then both packages built.

• pnpm --filter @objectstack/service-datasource typecheck at 6be669f6: exit 0, 0 error TS; tsc --listFiles counts the new test file once (its tsconfig includes tests).
• pnpm --filter @objectstack/service-cluster exec tsc --noEmit: the package's single pre-existing error (src/memory/memory.contract.test.ts:26, untouched by this branch, on origin/main since skills(pm): give sweep disjunct ① the drain clauses the finding box already has #14152) and nothing else — its DEBT ledger count holds.
• Tests at 6be669f6, both full suites under the shared verify lock (os-verify-lock.sh VERDICT command-exit 0): @objectstack/service-cluster 7 files / 105 tests passed; @objectstack/service-datasource 30 files / 635 tests passed.
  • New src/__tests__/datasource-cluster-convergence.test.ts (21 cases): two REAL DatasourceAdminServicePlugin boots over one shared sys_metadata store, own driver registries, joined by a remote-shaped bus. Arm B: DELETE on the writer evicts on the peer; create builds on the peer from the peer's own read; connectivity change rebuilds in place; active:false / active:true. Arm A controls (no attach): the identical DELETE leaves the peer's driver in place, the identical create leaves it pool-less. Payload address-only for all three doors (symmetric); duplicate delivery no-op by instance identity; label-only edit no churn; ordered convergence for a create chased by an update; stray signal touches nothing (code-defined pool survives); peer rebuild failure keeps the old pool; unreadable row is not spent as "gone"; publish failure never fails the write; detach; late-booting replica converges via rehydration; loopback; malformed payload; idempotent attach; no-convergePool host; migrateCredential does not publish.
  • metadata-cluster-bridge-plugin.test.ts gains 8 lane-3 cases: attaches on a cross-process driver and logs the "bridged datasource.mutated" line verbatim, independently of lanes 1 and 2; memory driver skips (in-process guard, nothing above debug); absent / bare service skip; no cluster service skips; throwing attach reported without taking the other lanes down; shutdown detaches lane 3 even when lane 2's detach throws.
• Reverse verification (ablation, committed tree, direction declared in the test header): removed the publishDatasourceMutation call from removeDatasource via perl -0pi and PROVED it on disk (grep -c of the call: 2 → 1; marker: 0 → 1), ran the convergence file under the lock: exactly the two declared cases red — "Arm B — DELETE on the writer evicts the driver on the PEER" and the symmetric-payload case — 19 green (VERDICT command-exit 1). Restored with git checkout HEAD -- ABSOLUTE_PATH under a trap … EXIT INT TERM; restore proved by git hash-object equal to the HEAD: blob and git diff HEAD empty. No dist involved: the test imports the package's own src directly.
• Gates derived from the real change set (node scripts/pm/dispatch-gates.mjs --commands, 42 commands, 35 families), every one run unlocked with the exit captured before any pipe. Green (exit 0): adr-0087-registration, changeset-no-major, ci-filter-parity, comment-mask-adoption, cross-package-test-inputs (both spellings), empty-changeset, keyed-text-bounds, plugin-teardown-shape, shard-attestation, tenant-audit-census, undeclared-dep-imports, docs-audit affected-docs + drift-comment, release-rehearsal-clone self-test, agent-test-spelling, bash32-floor, changeset-gate-self-tests, cli-command-ids, dispatcher-error-vocabulary, doc-authoring, engine-double-contract (the new test's findOne/update/delete doubles route through the metadata-core asserts and were recorded via the gate's own --write, +3 rows, 0 lost), entry-guard, logger-receiver-detach, objectql-double-limit, objectui-changeset, page-declaration-shape, parse-guard, pm-half-states, pnpm-filter-targets, published-files, query-options-erasure, slot-lookup, test-source-alias, type-check-coverage, type-source-resolution, watch-hint-literal, where-matcher, nul-bytes. NOT MEASURED locally (their own exit 3 / prerequisite text, not red): check:type-check-debt and check:dual-build-cjs-loads need the whole workspace built (the closure build alone took 4 minutes under the lock; the full one does not fit the container's foreground cap), check-test-completeness parses a CI vitest summary, scripts/pm/check-half-states.mjs is the PM patrol (network, timed out). CI runs all four.
• ESLint, narrowed and measured: pnpm exec eslint --no-inline-config --format json over the 6 changed TypeScript files → 6 files, 0 errors, 0 warnings. Population evidence from the config itself: the only global ignores are NEVER_LINTED (node_modules/dist/build/.next/.turbo), none of which contain these paths; invariance: eslint.config.mjs states it never enables type-aware linting (no parserOptions.project, no typed rules) for any file, so this diff cannot move any untouched file's verdict.

Contract review (Clause ②)

New exported symbols, from git diff -U0 origin/main...HEAD | grep export: DATASOURCE_MUTATION_CLUSTER_CHANNEL, ClusterDatasourceMutationPayload (both from @objectstack/service-datasource), plus two public methods on the exported DatasourceAdminService class (attachDatasourceMutationPubSub / detachDatasourceMutationPubSub) and one optional key on the exported DatasourceAdminServiceConfig (convergePool). @objectstack/service-cluster exports nothing new (a lane, not a plugin). Changeset: minor for both packages.

Out of scope, filed unassigned: #14339 (docs: content/docs/kernel/cluster.mdx describes the invalidation family as metadata.changed only; metadata.mutated and datasource.mutated are undocumented — one docs-only change for the family, not a rider here).

Session: https://claude.ai/code/session_01AUF1NoViznQK32gqpK8wS8

Generated by Claude Code

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/service-cluster, @objectstack/service-datasource, touching 30 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/services/service-datasource/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

9 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/api/wire-format.mdx (via /api/v1/meta/* (route, a path literal on a changed line))
• content/docs/concepts/metadata-lifecycle.mdx (via MetadataClusterBridgePlugin (symbol, a top-level class), originNode (symbol, a field of interface ClusterDatasourceMutationPayload))
• content/docs/data-modeling/drivers.mdx (via /api/v1/datasources/:name (route, a path literal on a changed line))
• content/docs/data-modeling/external-datasources.mdx (via DatasourceAdminServicePlugin (symbol, a top-level class), /api/v1/meta/datasource (route, a path literal in DatasourceAdminServicePlugin))
• content/docs/deployment/backup-restore.mdx (via /api/v1/ready (route, a path literal on a changed line))
• content/docs/deployment/self-hosting.mdx (via /api/v1/ready (route, a path literal on a changed line))
• content/docs/deployment/validating-metadata.mdx (via /api/v1/meta/* (route, a path literal on a changed line))
• content/docs/kernel/cluster.mdx (via MetadataClusterBridgePlugin (symbol, a top-level class), originNode (symbol, a field of interface ClusterDatasourceMutationPayload))
• content/docs/kernel/services-checklist.mdx (via MetadataClusterBridgePlugin (symbol, a top-level class))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v15.mdx (via /api/v1/meta/* (route, a path literal on a changed line))
• content/docs/releases/v17.mdx (via /api/v1/datasources/:name (route, a path literal on a changed line))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/services/service-datasource/src/index.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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 72adb7fcb6b6f48b656047835ed3852f314d9de1 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 177460340ecec87f3d9c6271651f88fd10f89ad8 — the merge of head 6be669f67747210071d0d03fda58ef8b7921b537 into base 72adb7fcb6b6f48b656047835ed3852f314d9de1, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 177460340ecec87f3d9c6271651f88fd10f89ad8 && git checkout 177460340ecec87f3d9c6271651f88fd10f89ad8
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 72adb7fcb6b6f48b656047835ed3852f314d9de1 6be669f67747210071d0d03fda58ef8b7921b537 && git checkout -B drift-repro 72adb7fcb6b6f48b656047835ed3852f314d9de1 && git merge --no-ff 6be669f67747210071d0d03fda58ef8b7921b537

node scripts/docs-audit/affected-docs.mjs --json 72adb7fcb6b6f48b656047835ed3852f314d9de1

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 72adb7fcb6b6f48b656047835ed3852f314d9de1 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[os-sales]

Landing provenance (PM seat, domain:services, session_01AUF1NoViznQK32gqpK8wS8)

• In-seat Clause-② contract review: PASS on the card — [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 (comment) — an isolated fable second opinion, transcript-verified (47 of 47 harness stamps at tier), adopted verbatim. needs:contract-review was cleared on both carriers in that stroke, per the maintainer's 2026-08-31 ruling that a PASS is cleared and landed by the dispatching seat.
• Landing checks on head 6be669f6: every check green — Lint & Repo Gates completed 03:11:45Z success, TypeScript Type Check success, all Test Core shards, Dogfood, Temporal Conformance, guards and changeset checks success; the remainder skipped by path filter. Closing keyword: Fixes #13805 is the only one in the body.
• Marked ready for review; auto-merge armed for the merge queue in the same stroke. The reviewer's four non-blocking follow-ups stay on the card for triage; none was required for merge.

---

Generated by Claude Code