Repository navigation
Commit 8aaa69f
feat(cloud-connection)!: refuse marketplace install-local when replicas are declared on the Redis driver (#31712)
<!-- claude-projects-attribution: {"github_login":"os-steve"} -->
_Requested by **Steve** · [project
thread](https://claude.ai/code/project/chan_01FdL1XeUyvVNxLreh3F4Qi9?thread=cmsg_01FdL1XeUyvVNxLreh3F4Qi968N7B64dDN7Noq8Fj3QSME)_
Fixes #31602
Maintainer ruling R6 on cloud#3814 (2026-11-08 14:16 UTC): 「多副本时拒绝」.
Claim 6727409308 (`domain:server#4`, card-thread
session_01ADHkmPnqZD15YnBkNbm1jJ).
Clause-②: yes (narrowing) — narrowed, measured on head `6f4c42d9` and,
for base, by the ablation that removes the new guard (equivalent to
`main` `5d1382a5` on these doors): with `OS_CLUSTER_REPLICAS=3` (or
`OS_EXPECT_MULTI_NODE=true`) and a composed `cluster` service on the
`redis` driver, `POST /api/v1/marketplace/install-local` answered `200`
with `hotLoaded: true` and wrote the ledger on base, and `DELETE
/api/v1/marketplace/install-local/:manifestId` answered `200` and
withdrew the package; on head both answer `409
MULTI_REPLICA_PACKAGE_CHANGE_REFUSED` and nothing is written, registered
or withdrawn. Every other topology is unchanged. Widened: two published
faces gain members, `ERROR_CODE_LEDGER` (`@objectstack/spec`) registers
`MULTI_REPLICA_PACKAGE_CHANGE_REFUSED` under
`@objectstack/cloud-connection` (the ledger header's "Registering a new
code" rule), and the `@objectstack/service-cluster` root exports
`declaresMultiReplicaOnRedis`, `composedClusterDriver`,
`MULTI_REPLICA_CLUSTER_DRIVER` and
`MULTI_REPLICA_PACKAGE_CHANGE_REFUSED`; nothing is removed or renamed.
This PR takes a `CONTRACT_REVIEW_TIER` review (PASS, 6728523407).
Metadata-protocol: none
**Shared predicate (card item 4, for #31599):**
`declaresMultiReplicaOnRedis(env, clusterDriver)` in
`@objectstack/service-cluster`
(`packages/services/service-cluster/src/multi-replica.ts`), with
`composedClusterDriver(services)` to read the driver from a kernel
context and the code constant `MULTI_REPLICA_PACKAGE_CHANGE_REFUSED`.
`@objectstack/runtime` already depends on
`@objectstack/service-cluster`, so the runtime package doors import it
from there.
## 维护者速读
- 改了什么:部署声明了多副本(`OS_CLUSTER_REPLICAS` 大于 1 或
`OS_EXPECT_MULTI_NODE=true`)且集群驱动是 Redis 时,市场 install-local
的安装(POST)和卸载(DELETE)直接拒绝,返回 409
`MULTI_REPLICA_PACKAGE_CHANGE_REFUSED`,提示在维护窗口里跑安装脚本、再重启所有副本;不写账本、不热加载、不撤包。
- 为什么改:这两个门只改处理请求的那一个副本(它自己 `OS_HOME`
下的账本和它自己的内核),其他副本永远看不到,而且每个副本启动时只读自己的账本,所以分叉是永久的。维护者 R6 裁决「多副本时拒绝」。
- 风险与回滚:只在"声明多副本 + Redis 驱动"时生效;单节点、内存驱动、其他驱动、没有集群服务时字节不变,split-brain
守卫没动。回滚即 revert 本 PR。
- 先看:`packages/cloud-connection/src/marketplace-install-local-plugin.ts`
的 `refuseMultiReplicaPackageChange`
及两个门里的调用点;`packages/services/service-cluster/src/multi-replica.ts`(共享谓词);`error-code-ledger.zod.ts`
新增的一行和一条 provenance 豁免。
- 两分钟验证:`pnpm --filter @objectstack/cloud-connection exec vitest run
src/marketplace-install-local-register-refusal.test.ts` —— 预期 27
passed,其中 R6 一组 8 个(4 个拒绝、4 个对照)。
- 需要你做的:无,席位落地(新错误码一行走 CONTRACT_REVIEW_TIER 复核)。
## What changes
- **`packages/services/service-cluster/src/multi-replica.ts`** (new) —
the one condition every cloud#3814 card keys on:
`declaresMultiReplicaOnRedis(env, clusterDriver)` =
`declaresMultiNode(env)` (the split-brain guard's own reading,
untouched) AND the driver is `MULTI_REPLICA_CLUSTER_DRIVER` (`'redis'`).
`composedClusterDriver(services)` reads the composed `cluster` service's
`driver` (the `IClusterService.driver` contract field) and never throws.
`MULTI_REPLICA_PACKAGE_CHANGE_REFUSED` spells the code once, so every
door refusing a package change under the condition answers the same
code. Exported from the package root; unit pins in
`multi-replica.test.ts` (new file: no harness exists for this module).
-
**`packages/cloud-connection/src/marketplace-install-local-plugin.ts`**
— `refuseMultiReplicaPackageChange(c, ctx, subject)` answers `409` with
the code and the recipe ("run the install script, then restart every
replica"). Called in `handleInstall` right after
`requireInstallCapability` (before the body is read, so before the cloud
fetch, the ledger, `manifest.register` and `syncSchemas`) and in
`handleUninstall` right after admission (before the ledger lookup, the
guards and the withdrawal). The driver is read per request, where it is
used. The grant path (`installForGrant`) calls `handleInstall`, so it is
covered too.
- **`packages/cloud-connection/src/connection-credential-ledger.ts`** —
`sharesCloudBindingCredential` now delegates to
`declaresMultiReplicaOnRedis` and `CLOUD_BINDING_SHARED_CLUSTER_DRIVER`
aliases `MULTI_REPLICA_CLUSTER_DRIVER`: same answers (its suite is green
unchanged), one predicate for the epic.
- **`packages/spec/src/api/error-code-ledger.zod.ts`** —
`MULTI_REPLICA_PACKAGE_CHANGE_REFUSED` registered under
`@objectstack/cloud-connection` (the door), plus one
`PROVENANCE_WAIVERS` entry for `@objectstack/service-cluster` (the
shared constant one package over, the
`UNIQUE_SCOPE_CONFIRMATION_REQUIRED` precedent). The claim's surface
says "one row"; the waiver is the provenance gate's required companion
for a constant defined one package over the door.
-
**`content/docs/references/api/{contract,automation-api,error-code-ledger}.mdx`**
— regenerated (`gen:schema && gen:docs`) for the new enum member.
-
**`packages/cloud-connection/src/marketplace-install-local-register-refusal.test.ts`**
— the shared real-engine install-local harness (AGENTS.md shared-harness
rule): `bootPlugin` takes an optional `clusterDriver` that composes a
`cluster` service; a new top-level `describe` pins the refusal. No
existing test was changed.
- **`.changeset/31602-install-local-multi-replica-refusal.md`** —
`patch` for `@objectstack/cloud-connection`,
`@objectstack/service-cluster`, `@objectstack/spec`; both declaration
lines; `adr-0087: not-required (no-migration-prescription)`; who sees
it.
## Tests
The new describe, on a real `ObjectKernel` + `ObjectQLPlugin` and a real
on-disk ledger:
- for each declaration (`OS_CLUSTER_REPLICAS=3`,
`OS_EXPECT_MULTI_NODE=true`) on the `redis` driver: `POST` (inline
branch and cloud branch) answers `409
MULTI_REPLICA_PACKAGE_CHANGE_REFUSED` in the declared envelope, the
ledger stays empty, the registry holds neither package, and the cloud
leg is never fetched; `DELETE` of a package installed on a single node
and rehydrated after a restart with replicas declared answers the same
`409`, the ledger still holds it and the registry still serves it;
- CONTROLs, install then uninstall both `200` with the ledger and
registry moving as before: a single node on `redis`,
`OS_CLUSTER_REPLICAS=1` on `redis`, declared replicas on the in-process
driver (with the split-brain guard's escape hatch), declared replicas
with no cluster service composed.
## Acceptance notes
- **The recipe's wording.** The message names the ruling's recipe
verbatim ("run the install script, then restart every replica"). This
repository has no deployment install script to point at by name; if the
seat wants a concrete command, the wording is one line in
`refuseMultiReplicaPackageChange`.
- **Dry run is refused too.** `POST` with `dryRun: true` writes nothing,
but the guard sits before the body is read, so it is refused like any
install: its plan reads the serving replica's own ledger, which is the
per-replica state the refusal is about.
- **Sibling doors not in this card.** `POST …/:manifestId/reseed` and
`…/purge-sample-data` write rows to the shared database (every replica
sees them) and are not refused. The runtime package doors (create/ensure
customization, enable, disable, runtime install/uninstall) are #31599,
which imports this predicate.
- **A second reader of the same condition stays separate.**
`@objectstack/service-cache` (`cache-service-plugin.ts`) reads
`declaresMultiNode()` plus its own driver check for the shared Redis
cache; it is not moved onto the new predicate here.
## Verification
All on `6f4c42d9` unless stated (the feature commits were cut on
`5d1382a5`; `origin/main` merged once at `03fed7a5`, 5 commits, none in
these packages; `6f4c42d9` adds only the regenerated references; head
`485e8f99` changes only the changeset's prose, after the contract
review: the `Clause-②:` line now reads `yes (narrowing)` and names both
halves, and the Now bullet says a dry run is refused too. On `485e8f99`
the changeset gates were re-run, each exit 0:
`check-adr-0087-registration`, `check-changeset-no-major`,
`check-empty-changeset`, `check:changeset-gate-self-tests`,
`check:nul-bytes`):
<details><summary>Suites (os-verify-lock, every VERDICT command-exit
0)</summary>
- `pnpm --filter @objectstack/service-cluster test` + `typecheck`: 9
files / 120 tests (`03fed7a5`).
- `pnpm --filter @objectstack/cloud-connection test`: 80 files / 1116
tests; `typecheck` exit 0 (`03fed7a5`).
- `pnpm --filter @objectstack/spec test`: 822 files / 26034 passed, 1
todo; `typecheck` exit 0 (`03fed7a5`).
- `pnpm --filter @objectstack/dogfood test` (full battery, narrowing
arm): 440 passed, 3 skipped files / 3652 passed, 41 skipped tests
(`03fed7a5`).
- Lint (`eslint --no-inline-config`) on `service-cluster`,
`cloud-connection`, `spec` sources: exit 0 each.
</details>
<details><summary>Ablation (negative pins)</summary>
`scripts/ablation-replace.mjs` on `51cac0fe` (fix committed first),
marker `ABLATED_31602`: the guard's condition `|| 'ABLATED_31602'`, so
`refuseMultiReplicaPackageChange` always returns `null` (the base
behaviour). The test file imports the plugin from `src`, so no rebuild
leg. Result: **4 of 27 red** — exactly the four refusal cases (POST and
DELETE, both declarations), each `expected 200 to be 409` with the base
answer in the message
(`{"success":true,"data":{"manifestId":"com.acme.dispatch",…,"hotLoaded":true,…}}`
for POST; the withdrawal answer for DELETE); the four CONTROLs and the
19 existing cases green. Restored: blob `4f8e111f` == HEAD, `git diff
HEAD` empty.
</details>
<details><summary>Derived gates</summary>
`node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` on `6f4c42d9`: 120 families, each run and
recorded with its exit code; `--ran` reconciliation: "120 derived
famil(ies) accounted for — 120 run, 0 NOT-MEASURED". All 120 exit 0,
among them `check:error-code-provenance`, `check:error-code-casing`,
`check:dispatcher-error-vocabulary`, `check:error-status-conformance`,
`check:route-envelope`, `check:startup-registry-verdict`,
`check:api-surface`, `check:generated` and `check:docs`. A first pass on
`03fed7a5` had `check:docs` red (the three references above were stale,
now regenerated) and two exit-3 prerequisites
(`check:plugin-teardown-shape --self-test` needed its pinned fixture
commit fetched; `check:dual-build-cjs-loads` needed every package's
dist, built with `turbo run build --filter='./packages/**'`); both are
green on `6f4c42d9`. `pnpm --filter @objectstack/spec check:generated`:
exit 0.
</details>
---
_Generated by [Claude
Code](https://claude.ai/code/session_01ADHkmPnqZD15YnBkNbm1jJ)_
<!-- signed: domain:server#4 · os-steve ·
session_01ADHkmP8JJo4zF2sjTBRwnX -->
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent d655caf commit 8aaa69f
11 files changed
Lines changed: 329 additions & 10 deletions
File tree
- .changeset
- content/docs/references/api
- packages
- cloud-connection/src
- services/service-cluster/src
- spec/src/api
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
417 | 417 | | |
418 | 418 | | |
419 | 419 | | |
420 | | - | |
| 420 | + | |
421 | 421 | | |
422 | 422 | | |
423 | 423 | | |
| |||
640 | 640 | | |
641 | 641 | | |
642 | 642 | | |
| 643 | + | |
643 | 644 | | |
644 | 645 | | |
645 | 646 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
28 | 28 | | |
29 | 29 | | |
30 | 30 | | |
31 | | - | |
| 31 | + | |
32 | 32 | | |
33 | 33 | | |
34 | 34 | | |
| |||
258 | 258 | | |
259 | 259 | | |
260 | 260 | | |
| 261 | + | |
261 | 262 | | |
262 | 263 | | |
263 | 264 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
425 | 425 | | |
426 | 426 | | |
427 | 427 | | |
| 428 | + | |
428 | 429 | | |
429 | 430 | | |
430 | 431 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
50 | 50 | | |
51 | 51 | | |
52 | 52 | | |
53 | | - | |
| 53 | + | |
54 | 54 | | |
55 | 55 | | |
56 | 56 | | |
57 | 57 | | |
58 | | - | |
| 58 | + | |
| 59 | + | |
59 | 60 | | |
60 | | - | |
| 61 | + | |
61 | 62 | | |
62 | 63 | | |
63 | 64 | | |
64 | 65 | | |
65 | 66 | | |
66 | | - | |
67 | | - | |
68 | | - | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
69 | 72 | | |
70 | 73 | | |
71 | 74 | | |
72 | 75 | | |
73 | 76 | | |
74 | | - | |
| 77 | + | |
75 | 78 | | |
76 | 79 | | |
77 | 80 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
396 | 396 | | |
397 | 397 | | |
398 | 398 | | |
| 399 | + | |
399 | 400 | | |
400 | 401 | | |
401 | 402 | | |
| |||
1364 | 1365 | | |
1365 | 1366 | | |
1366 | 1367 | | |
| 1368 | + | |
| 1369 | + | |
| 1370 | + | |
| 1371 | + | |
| 1372 | + | |
| 1373 | + | |
| 1374 | + | |
| 1375 | + | |
| 1376 | + | |
| 1377 | + | |
| 1378 | + | |
| 1379 | + | |
| 1380 | + | |
| 1381 | + | |
| 1382 | + | |
| 1383 | + | |
| 1384 | + | |
| 1385 | + | |
| 1386 | + | |
| 1387 | + | |
| 1388 | + | |
| 1389 | + | |
| 1390 | + | |
| 1391 | + | |
| 1392 | + | |
| 1393 | + | |
| 1394 | + | |
| 1395 | + | |
| 1396 | + | |
| 1397 | + | |
| 1398 | + | |
| 1399 | + | |
| 1400 | + | |
| 1401 | + | |
1367 | 1402 | | |
1368 | 1403 | | |
1369 | 1404 | | |
| |||
2094 | 2129 | | |
2095 | 2130 | | |
2096 | 2131 | | |
| 2132 | + | |
| 2133 | + | |
| 2134 | + | |
| 2135 | + | |
| 2136 | + | |
| 2137 | + | |
| 2138 | + | |
2097 | 2139 | | |
2098 | 2140 | | |
2099 | 2141 | | |
| |||
3433 | 3475 | | |
3434 | 3476 | | |
3435 | 3477 | | |
| 3478 | + | |
| 3479 | + | |
| 3480 | + | |
| 3481 | + | |
| 3482 | + | |
| 3483 | + | |
| 3484 | + | |
3436 | 3485 | | |
3437 | 3486 | | |
3438 | 3487 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
45 | 45 | | |
46 | 46 | | |
47 | 47 | | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
48 | 52 | | |
49 | 53 | | |
50 | 54 | | |
| |||
185 | 189 | | |
186 | 190 | | |
187 | 191 | | |
188 | | - | |
| 192 | + | |
189 | 193 | | |
190 | 194 | | |
191 | 195 | | |
| |||
213 | 217 | | |
214 | 218 | | |
215 | 219 | | |
| 220 | + | |
| 221 | + | |
216 | 222 | | |
217 | 223 | | |
218 | 224 | | |
| |||
559 | 565 | | |
560 | 566 | | |
561 | 567 | | |
| 568 | + | |
| 569 | + | |
| 570 | + | |
| 571 | + | |
| 572 | + | |
| 573 | + | |
| 574 | + | |
| 575 | + | |
| 576 | + | |
| 577 | + | |
| 578 | + | |
| 579 | + | |
| 580 | + | |
| 581 | + | |
| 582 | + | |
| 583 | + | |
| 584 | + | |
| 585 | + | |
| 586 | + | |
| 587 | + | |
| 588 | + | |
| 589 | + | |
| 590 | + | |
| 591 | + | |
| 592 | + | |
| 593 | + | |
| 594 | + | |
| 595 | + | |
| 596 | + | |
| 597 | + | |
| 598 | + | |
| 599 | + | |
| 600 | + | |
| 601 | + | |
| 602 | + | |
| 603 | + | |
| 604 | + | |
| 605 | + | |
| 606 | + | |
| 607 | + | |
| 608 | + | |
| 609 | + | |
| 610 | + | |
| 611 | + | |
| 612 | + | |
| 613 | + | |
| 614 | + | |
| 615 | + | |
| 616 | + | |
| 617 | + | |
| 618 | + | |
| 619 | + | |
| 620 | + | |
| 621 | + | |
| 622 | + | |
| 623 | + | |
| 624 | + | |
| 625 | + | |
| 626 | + | |
| 627 | + | |
| 628 | + | |
| 629 | + | |
| 630 | + | |
| 631 | + | |
| 632 | + | |
| 633 | + | |
| 634 | + | |
| 635 | + | |
| 636 | + | |
| 637 | + | |
| 638 | + | |
| 639 | + | |
| 640 | + | |
| 641 | + | |
| 642 | + | |
| 643 | + | |
| 644 | + | |
| 645 | + | |
| 646 | + | |
0 commit comments