Repository navigation
Commit f3fe660
fix(spec): composeStacks says why a top-level connector beside a package body's same-named entry is ambiguous (#28026)
epic:#27261#1 · marchtian · session_017ihL2c5z3q4h8inrn5kwqV
<!-- claude-projects-attribution: {"github_login":"marchtian"} -->
_Requested by **田騏** · [project
thread](https://claude.ai/code/project/chan_01VmuUhXU9SSUzqJYyXSmYSi?thread=cmsg_01VmuUhXU9SSUzqJYyXSmYSiAgqyfAMFoGxrddntu1VW4z)_
**Full review owed at the reviewer tier.** Developed on the default tier
while the reviewer tier's quota is out. This PR touches the published
spec (`packages/spec/src/**`), so it lands only after a full review at
the reviewer tier and a `CONTRACT_REVIEW_TIER` contract review record
PASS on the current head.
Fixes #28006
Clause-②: no
Metadata-protocol: none
## 维护者速读
- **改了什么:** #27939
的合成检查里,有一种情形的拒收理由不对:包体里的连接器和产物顶层的同名连接器一个能出借、一个不能。原提示说「运行时每个包各留一条,先注册的出借」。实际上,开机时顶层那条不注册,由包体那条出借;开发态重载时,顶层那条会替换包体那条。现在提示写明这一点;`slot`
文档和 `providedCollectionEntries` 的说明也写清了。另外改了一个测试名,并补了 `preserve`
下混合嵌套输入的测试。
- **为什么改:** 结论正确但理由错误,会误导作者判断该改哪一条声明。
- **风险与回滚:** 接受集不变:原来拒收的仍拒收,原来通过的仍通过,只改提示文字。两个包体之间冲突的提示一字未改。回滚即 revert。
- **先看:** `packages/spec/src/stack.zod.ts` 中
`collectComposedDatasourceConnectorErrors` 的歧义分支,以及
`ProvidedCollectionEntry.inBody` 的文档。
- **两分钟验证:** `pnpm --filter @objectstack/spec exec vitest run
src/stack-datasource-connector.test.ts`,预期 30 个测试全过。
- **需要您做的:** 无(需审阅档全量复审与合约复审 PASS)。
## What changes
- **`packages/spec/src/stack.zod.ts`:**
- `ProvidedCollectionEntry` gains `inBody`: whether the entry boots as a
package body's own item. That covers an entry of a `packages[]` body,
and, under `preserve`, the top level of an input that
`preservePackageEntries` folds into a body of its own id. Its doc states
the mechanism for every other top-level entry beside package bodies. The
residual rule (`unclaimedTopLevel`) does not register such an entry when
a body declares its name. When no body declares the name, the rule
registers it under the composed artifact's `manifest.id` (the last
input's). A dev reload replaces the booted entries of the name with the
artifact's top-level list (`mergeDeclaredConnectorSources`). So its
`slot` (`'artifact'`, or a mixed `preserve` input's own `package:${id}`)
is a stand-in. It stays a stand-in because keeping it apart from the
bodies is what refuses the boot-or-reload split as ambiguous.
- The ambiguity finding now names the mechanism that applies:
- **Two package bodies:** unchanged, byte for byte ("the runtime keeps
one entry per package and lends from whichever registers first").
- **A package body and a top-level entry:** "which the composed artifact
declares both in a package body and at its top level, … The boot does
not register a top-level entry whose name a package body declares, so
the body's entry lends, and a dev reload replaces it with the artifact's
top-level entries of the name, the first of which lends, so the entry
the datasource borrows depends on whether the artifact was booted or
reloaded and on the order of its inputs."
- **Top-level entries of two inputs, beside bodies that do not declare
the name:** a sentence of its own: no door registers either as a package
body's entry, and a dev reload lends from the first top-level entry of
the name.
- `providedCollectionEntries`' docblock and
`collectComposedDatasourceConnectorErrors`' docblock say the same.
- **`packages/spec/src/stack-datasource-connector.test.ts`:**
- "treats a package body and another input's top level as two slots" is
renamed to "refuses as ambiguous a top-level entry beside a package
body's same-named entry, and names the body". It now asserts the new
sentence and the absence of "one entry per package".
- A new group pins the `preserve` reading of an input that carries
`packages` beside its own top-level `connectors`. With a descriptor at
its top level and another package's lending instance, it is refused as
ambiguous, with the beside-a-body sentence, in both input orders. With
two lending instances it composes in both orders. The composed artifact
keeps that top level beside the inner and plain bodies only, under the
last input's `manifest.id`, and the whole flattened `connectors` list in
input order (pinned both ways, since a dev reload lends from the first).
Two such inputs whose top-level entries disagree, beside bodies silent
on the name, are refused with the top-level-only sentence in both
orders.
- **`.changeset/28006-composed-connector-ambiguity-reason.md`:**
`@objectstack/spec` `patch` (the message text ships), both declaration
lines, and an ADR-0087 `not-required (no-migration-prescription)`
marker.
## Why
Should-fix 1 of contract record 6516406275 on PR #27939: the refusal was
right for a reason the message, the slot doc and the test name did not
give.
## Verification
All on head `541d7f5b3d` (should-fixes 1 and 2 of contract record
6519281283 in 1580237, then a merge of `origin/main`).
- **Verdicts unchanged:** the 30 tests were run against `origin/main`'s
`stack.zod.ts`. The 25 that do not assert the new wording passed. The 5
that do failed only on that wording: each first asserted the envelope
(`STACK_CROSS_REFERENCE_INVALID`, 422) and exactly one finding for the
datasource, and those assertions passed. So every composition this file
covers is refused or accepted exactly as before.
- **Ablation:** with the mixed input's top level judged in the composed
artifact's slot instead of its own, both orders of the mixed `preserve`
refusal go red, and the mixed-first order is accepted. The 26 other
cases stay green. Restored, 28/28 pass (measured on `55b0c85641`, before
the two cases should-fix 2 added).
- **Package:** `pnpm --filter @objectstack/spec build`, `test` and
`typecheck` under the verify lock: build exit 0; 756 test files passed,
22505 tests passed (1 todo); typecheck passed (`check:test-typecheck:
OK`).
- **Local gates:** `node scripts/pm/dispatch-gates.mjs --commands`,
derived after merging `origin/main`, named 80 families (re-derived after
the second merge of `origin/main`). All were run, with exit codes
recorded before any pipe, and every one exited 0. `dispatch-gates
--ran`: "80 derived famil(ies) accounted for — 80 run, 0 NOT-MEASURED (a
DERIVED zero)". The tree was clean after the gate run, so no generated
reference moved. The full gate battery is CI's. Dogfood was not run:
`Clause-②: no` does not owe it, and no verdict moves.
## Acceptance notes
- **The slot stays a stand-in on purpose.** Judging a mixed input's top
level in the composed artifact's `manifest.id` slot, where the residual
rule registers it, would move a verdict: with the plain input last, a
descriptor at the mixed input's top level would be judged last-wins
against the plain body's instance and accepted. The card forbids that,
so the doc states the mechanism instead.
- **Worktree:** `objectstack-issue-28006` on the claimed branch, as the
Claim names.
## Human Minimum
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
(Message wording of a build-time collector and one module-private field;
no schema changed.)
- [x] 2. Every name I added uses the casing for its kind.
- [x] 3. No formatter ran; `pnpm lint` is CI's.
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset, and both
declaration lines are filled in here and in the changeset.
- [x] 6. `packages/spec` touched: no generated artifact changes (only
JSDoc and a refusal's text; the gate run left the tree clean).
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English (the 维护者速读 block is the
repo's own Chinese reader section).
- [x] The *Before Submitting* list in CONTRIBUTING.md is done.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_017ihL2cLiZUHvCtV2YGRWAd
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 3e0fd7a commit f3fe660
3 files changed
Lines changed: 186 additions & 24 deletions
File tree
- .changeset
- packages/spec/src
| 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 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
31 | 31 | | |
32 | 32 | | |
33 | 33 | | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
34 | 42 | | |
35 | 43 | | |
36 | 44 | | |
| |||
162 | 170 | | |
163 | 171 | | |
164 | 172 | | |
| 173 | + | |
| 174 | + | |
| 175 | + | |
| 176 | + | |
165 | 177 | | |
166 | 178 | | |
167 | 179 | | |
| |||
275 | 287 | | |
276 | 288 | | |
277 | 289 | | |
278 | | - | |
| 290 | + | |
279 | 291 | | |
280 | 292 | | |
281 | 293 | | |
282 | 294 | | |
283 | 295 | | |
284 | 296 | | |
285 | | - | |
286 | | - | |
287 | | - | |
| 297 | + | |
| 298 | + | |
| 299 | + | |
| 300 | + | |
| 301 | + | |
288 | 302 | | |
| 303 | + | |
| 304 | + | |
289 | 305 | | |
290 | 306 | | |
291 | 307 | | |
| |||
306 | 322 | | |
307 | 323 | | |
308 | 324 | | |
| 325 | + | |
| 326 | + | |
| 327 | + | |
| 328 | + | |
| 329 | + | |
| 330 | + | |
| 331 | + | |
| 332 | + | |
| 333 | + | |
| 334 | + | |
| 335 | + | |
| 336 | + | |
| 337 | + | |
| 338 | + | |
| 339 | + | |
| 340 | + | |
| 341 | + | |
| 342 | + | |
| 343 | + | |
| 344 | + | |
| 345 | + | |
| 346 | + | |
| 347 | + | |
| 348 | + | |
| 349 | + | |
| 350 | + | |
| 351 | + | |
| 352 | + | |
| 353 | + | |
| 354 | + | |
| 355 | + | |
| 356 | + | |
| 357 | + | |
| 358 | + | |
| 359 | + | |
| 360 | + | |
| 361 | + | |
| 362 | + | |
| 363 | + | |
| 364 | + | |
| 365 | + | |
| 366 | + | |
| 367 | + | |
| 368 | + | |
| 369 | + | |
| 370 | + | |
| 371 | + | |
| 372 | + | |
| 373 | + | |
| 374 | + | |
| 375 | + | |
| 376 | + | |
| 377 | + | |
| 378 | + | |
| 379 | + | |
| 380 | + | |
| 381 | + | |
| 382 | + | |
| 383 | + | |
| 384 | + | |
| 385 | + | |
| 386 | + | |
| 387 | + | |
| 388 | + | |
| 389 | + | |
| 390 | + | |
| 391 | + | |
| 392 | + | |
| 393 | + | |
| 394 | + | |
| 395 | + | |
| 396 | + | |
| 397 | + | |
| 398 | + | |
| 399 | + | |
309 | 400 | | |
310 | 401 | | |
311 | 402 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
4514 | 4514 | | |
4515 | 4515 | | |
4516 | 4516 | | |
4517 | | - | |
| 4517 | + | |
4518 | 4518 | | |
4519 | 4519 | | |
| 4520 | + | |
| 4521 | + | |
| 4522 | + | |
4520 | 4523 | | |
4521 | 4524 | | |
| 4525 | + | |
| 4526 | + | |
| 4527 | + | |
| 4528 | + | |
| 4529 | + | |
| 4530 | + | |
| 4531 | + | |
| 4532 | + | |
| 4533 | + | |
| 4534 | + | |
| 4535 | + | |
| 4536 | + | |
| 4537 | + | |
| 4538 | + | |
| 4539 | + | |
| 4540 | + | |
| 4541 | + | |
| 4542 | + | |
| 4543 | + | |
| 4544 | + | |
| 4545 | + | |
4522 | 4546 | | |
4523 | 4547 | | |
4524 | 4548 | | |
| |||
4532 | 4556 | | |
4533 | 4557 | | |
4534 | 4558 | | |
4535 | | - | |
4536 | | - | |
4537 | | - | |
| 4559 | + | |
| 4560 | + | |
| 4561 | + | |
| 4562 | + | |
| 4563 | + | |
| 4564 | + | |
| 4565 | + | |
4538 | 4566 | | |
4539 | 4567 | | |
4540 | 4568 | | |
| |||
4545 | 4573 | | |
4546 | 4574 | | |
4547 | 4575 | | |
4548 | | - | |
| 4576 | + | |
4549 | 4577 | | |
4550 | 4578 | | |
4551 | 4579 | | |
4552 | 4580 | | |
4553 | | - | |
| 4581 | + | |
4554 | 4582 | | |
4555 | 4583 | | |
4556 | 4584 | | |
4557 | 4585 | | |
4558 | 4586 | | |
4559 | 4587 | | |
4560 | 4588 | | |
4561 | | - | |
4562 | | - | |
| 4589 | + | |
| 4590 | + | |
4563 | 4591 | | |
4564 | 4592 | | |
4565 | 4593 | | |
4566 | | - | |
| 4594 | + | |
| 4595 | + | |
4567 | 4596 | | |
4568 | 4597 | | |
4569 | 4598 | | |
| |||
4592 | 4621 | | |
4593 | 4622 | | |
4594 | 4623 | | |
4595 | | - | |
4596 | | - | |
4597 | | - | |
4598 | | - | |
4599 | | - | |
4600 | | - | |
| 4624 | + | |
| 4625 | + | |
| 4626 | + | |
| 4627 | + | |
| 4628 | + | |
| 4629 | + | |
| 4630 | + | |
| 4631 | + | |
| 4632 | + | |
| 4633 | + | |
| 4634 | + | |
| 4635 | + | |
| 4636 | + | |
| 4637 | + | |
| 4638 | + | |
| 4639 | + | |
| 4640 | + | |
4601 | 4641 | | |
4602 | 4642 | | |
4603 | 4643 | | |
| |||
4626 | 4666 | | |
4627 | 4667 | | |
4628 | 4668 | | |
| 4669 | + | |
| 4670 | + | |
| 4671 | + | |
| 4672 | + | |
| 4673 | + | |
| 4674 | + | |
| 4675 | + | |
| 4676 | + | |
| 4677 | + | |
| 4678 | + | |
| 4679 | + | |
| 4680 | + | |
| 4681 | + | |
| 4682 | + | |
| 4683 | + | |
| 4684 | + | |
| 4685 | + | |
| 4686 | + | |
| 4687 | + | |
4629 | 4688 | | |
4630 | 4689 | | |
4631 | | - | |
4632 | | - | |
4633 | | - | |
4634 | | - | |
4635 | | - | |
| 4690 | + | |
4636 | 4691 | | |
4637 | 4692 | | |
4638 | 4693 | | |
| |||
0 commit comments