From 5b7780b712d8b4f7df7d82c7b61fb661b0f706fb Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 20:46:17 +0000 Subject: [PATCH] =?UTF-8?q?docs(scripts):=20=E5=9B=9B=E6=9D=A1=20metadata-?= =?UTF-8?q?protocol=20=E5=9F=BA=E7=BA=BF=E6=9D=A1=E7=9B=AE=E7=9A=84?= =?UTF-8?q?=E5=A4=84=E6=96=B9=E6=8C=87=E5=90=91=E4=B8=80=E4=B8=AA=E4=B8=8D?= =?UTF-8?q?=E5=AD=98=E5=9C=A8=E7=9A=84=E5=8A=A8=E4=BD=9C=20(#4987)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `scripts/engine-double-contract.baseline.json` 是 shrink-only 手写台账,一条条目的 `closes` 就是给下一个作者的处方。四条 metadata-protocol 条目写的是「add @objectstack/objectql to devDependencies」—— 这个动作**做不到**: `@objectstack/objectql` 的 `dependencies` 已含 `@objectstack/metadata-protocol` (`workspace:*`),反向加边按构造即成环。 不是引用旧测量,而是在本分支重测:把边加进 metadata-protocol 的 devDependencies, turbo 2.10.7 对 `build` 与 `test` 两个 task graph 都直接拒绝(exit 1),随后回退: WARNING Circular package dependency detected: @objectstack/objectql, @objectstack/metadata-protocol x Cyclic dependency detected: | @objectstack/objectql#build, @objectstack/metadata-protocol#build 判据本来就在同一个文件里 —— `packages/spec/src/contracts/data-engine.test.ts` 那条 EXEMPT 早就写了「it cannot be pinned even in principle ... the import would invert the dependency」,只是从没套用到 metadata-protocol 这四条上。 - `why` 改成实测的环,并写明**不能**因此升级成 EXEMPT:不存在的是 devDependency 这条**路线**,条目本身靠下沉谓词仍可关闭,所以按台账自己的规则保持 DEBT。 - `closes` 改成唯一存在的路线:把 `assertEngineDeleteDispatch` 下沉到两边都已依赖 的包。已静态核实其可行:objectql 与 metadata-protocol 都已依赖 `@objectstack/metadata-core`,而后者 `dependencies` 只有 spec + zod、不含 objectql,故不引入新环;生产者 `packages/objectql/src/engine-delete-dispatch.ts` **没有任何 import**,下沉是一次搬移而非重构。`spec/contracts` 作为另一候选保留, 但注明仅当谓词属于契约层才对,不要默认选它。 - 措辞与 #4867 / #4981 / #5206 三条早先已改好的同族条目对齐,但**不写硬编码的 sibling 计数** —— 那三条写的「four/five sibling」在同族增至 7 条后已经漂移, 本次改用免计数措辞,避免再漂。 未做也未声称做的事:本 PR 文件面只是台账文字,四个文件各自的 fake delete 当前是否被 驱动**没有探测**,`why` 里如实写明。按台账自己的规则这不改变结论 —— 那是关于单个 文件的论证,不是关于契约的论证。 下沉代码本身属 engine-core 域,不在本 PR 文件面,已另开 #5619 承接(三条同族条目 `closes` 里「tracked as #4987」的引用也在那里改指)。 验证:`pnpm check:engine-double-contract` 改动前后输出**逐字节一致** —— 仍是 24 pinned / 34 baseline、仅 1 个 problem(#5604 的 action-execution-calldata-not-found, cli 座位在修,与本改动无关)。JSON round-trip 字节一致,故 diff 恰好 8 增 8 删; 条目数、`file`/`lines`/`unguarded`/`kind` 与 `$comment` 由脚本断言未变。 Fixes #4987 Claude-Session: https://claude.ai/code/session_01GX3sL71LFq8m2usg6VqTSE Co-authored-by: Claude --- scripts/engine-double-contract.baseline.json | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/scripts/engine-double-contract.baseline.json b/scripts/engine-double-contract.baseline.json index 32938c004a..af52f9afcd 100644 --- a/scripts/engine-double-contract.baseline.json +++ b/scripts/engine-double-contract.baseline.json @@ -35,22 +35,22 @@ "file": "packages/metadata-protocol/src/protocol-publish-drafts-org-scope.test.ts", "unguarded": 1, "kind": "DEBT", - "why": "@objectstack/metadata-protocol does not depend on @objectstack/objectql. Pinning needs a devDependency + lockfile change, which is a separate reviewable act.", - "closes": "add @objectstack/objectql to devDependencies, then open the fake's delete with assertEngineDeleteDispatch(opts)" + "why": "MEASURED (#4987): the devDependency route this entry used to prescribe DOES NOT EXIST — it is cyclic, not merely unreviewed. @objectstack/objectql depends on @objectstack/metadata-protocol in `dependencies` (`workspace:*`), so any reverse edge closes a cycle by construction. Re-measured on #4987's branch rather than cited: the edge was added to metadata-protocol's devDependencies and turbo 2.10.7 refused BOTH task graphs outright — `WARNING Circular package dependency detected: @objectstack/objectql, @objectstack/metadata-protocol` / `x Cyclic dependency detected: @objectstack/objectql#build, @objectstack/metadata-protocol#build`, exit 1 from `turbo run build --filter=@objectstack/metadata-protocol --dry` and from the same command with `test` — then the edge was reverted. This is exactly the criterion the `packages/spec/src/contracts/data-engine.test.ts` EXEMPT entry below already states ('it cannot be pinned even in principle ... the import would invert the dependency'); it was simply never applied to the metadata-protocol entries. The entry stays DEBT and not EXEMPT because what cannot exist is the devDependency ROUTE, while the entry itself is closable by sinking the predicate — see `closes`. Whether this file's own fake delete is currently exercised was NOT probed: #4987's file face is this ledger's text only. Per this ledger's own rule that changes nothing, since it would be an argument about this file rather than about the contract.", + "closes": "sink assertEngineDeleteDispatch into a package BOTH sides already depend on — tracked as #5619 — then open the fake's delete with it. Verified available on #4987's branch: @objectstack/objectql and @objectstack/metadata-protocol both already depend on @objectstack/metadata-core (`workspace:*`), whose own `dependencies` are just @objectstack/spec + zod and do NOT include objectql, so the sink adds no new edge; the producer `packages/objectql/src/engine-delete-dispatch.ts` has zero imports, so this is a move and not a refactor. @objectstack/spec/contracts is the other candidate, but only if the predicate belongs to the contract layer — do not pick it by default. The devDependency route is closed by the cycle recorded in `why`, for this file and for every other metadata-protocol entry in this ledger alike." }, { "file": "packages/metadata-protocol/src/protocol.runtime-authoring-gate.test.ts", "unguarded": 1, "kind": "DEBT", - "why": "@objectstack/metadata-protocol does not depend on @objectstack/objectql. Pinning needs a devDependency + lockfile change, which is a separate reviewable act.", - "closes": "add @objectstack/objectql to devDependencies, then open the fake's delete with assertEngineDeleteDispatch(opts)" + "why": "MEASURED (#4987): the devDependency route this entry used to prescribe DOES NOT EXIST — it is cyclic, not merely unreviewed. @objectstack/objectql depends on @objectstack/metadata-protocol in `dependencies` (`workspace:*`), so any reverse edge closes a cycle by construction. Re-measured on #4987's branch rather than cited: the edge was added to metadata-protocol's devDependencies and turbo 2.10.7 refused BOTH task graphs outright — `WARNING Circular package dependency detected: @objectstack/objectql, @objectstack/metadata-protocol` / `x Cyclic dependency detected: @objectstack/objectql#build, @objectstack/metadata-protocol#build`, exit 1 from `turbo run build --filter=@objectstack/metadata-protocol --dry` and from the same command with `test` — then the edge was reverted. This is exactly the criterion the `packages/spec/src/contracts/data-engine.test.ts` EXEMPT entry below already states ('it cannot be pinned even in principle ... the import would invert the dependency'); it was simply never applied to the metadata-protocol entries. The entry stays DEBT and not EXEMPT because what cannot exist is the devDependency ROUTE, while the entry itself is closable by sinking the predicate — see `closes`. Whether this file's own fake delete is currently exercised was NOT probed: #4987's file face is this ledger's text only. Per this ledger's own rule that changes nothing, since it would be an argument about this file rather than about the contract.", + "closes": "sink assertEngineDeleteDispatch into a package BOTH sides already depend on — tracked as #5619 — then open the fake's delete with it. Verified available on #4987's branch: @objectstack/objectql and @objectstack/metadata-protocol both already depend on @objectstack/metadata-core (`workspace:*`), whose own `dependencies` are just @objectstack/spec + zod and do NOT include objectql, so the sink adds no new edge; the producer `packages/objectql/src/engine-delete-dispatch.ts` has zero imports, so this is a move and not a refactor. @objectstack/spec/contracts is the other candidate, but only if the predicate belongs to the contract layer — do not pick it by default. The devDependency route is closed by the cycle recorded in `why`, for this file and for every other metadata-protocol entry in this ledger alike." }, { "file": "packages/metadata-protocol/src/protocol.save-flow-canonicalization.test.ts", "unguarded": 1, "kind": "DEBT", - "why": "@objectstack/metadata-protocol does not depend on @objectstack/objectql. Pinning needs a devDependency + lockfile change, which is a separate reviewable act.", - "closes": "add @objectstack/objectql to devDependencies, then open the fake's delete with assertEngineDeleteDispatch(opts)" + "why": "MEASURED (#4987): the devDependency route this entry used to prescribe DOES NOT EXIST — it is cyclic, not merely unreviewed. @objectstack/objectql depends on @objectstack/metadata-protocol in `dependencies` (`workspace:*`), so any reverse edge closes a cycle by construction. Re-measured on #4987's branch rather than cited: the edge was added to metadata-protocol's devDependencies and turbo 2.10.7 refused BOTH task graphs outright — `WARNING Circular package dependency detected: @objectstack/objectql, @objectstack/metadata-protocol` / `x Cyclic dependency detected: @objectstack/objectql#build, @objectstack/metadata-protocol#build`, exit 1 from `turbo run build --filter=@objectstack/metadata-protocol --dry` and from the same command with `test` — then the edge was reverted. This is exactly the criterion the `packages/spec/src/contracts/data-engine.test.ts` EXEMPT entry below already states ('it cannot be pinned even in principle ... the import would invert the dependency'); it was simply never applied to the metadata-protocol entries. The entry stays DEBT and not EXEMPT because what cannot exist is the devDependency ROUTE, while the entry itself is closable by sinking the predicate — see `closes`. Whether this file's own fake delete is currently exercised was NOT probed: #4987's file face is this ledger's text only. Per this ledger's own rule that changes nothing, since it would be an argument about this file rather than about the contract.", + "closes": "sink assertEngineDeleteDispatch into a package BOTH sides already depend on — tracked as #5619 — then open the fake's delete with it. Verified available on #4987's branch: @objectstack/objectql and @objectstack/metadata-protocol both already depend on @objectstack/metadata-core (`workspace:*`), whose own `dependencies` are just @objectstack/spec + zod and do NOT include objectql, so the sink adds no new edge; the producer `packages/objectql/src/engine-delete-dispatch.ts` has zero imports, so this is a move and not a refactor. @objectstack/spec/contracts is the other candidate, but only if the predicate belongs to the contract layer — do not pick it by default. The devDependency route is closed by the cycle recorded in `why`, for this file and for every other metadata-protocol entry in this ledger alike." }, { "file": "packages/metadata-protocol/src/sys-metadata-repository.draft-drain.test.ts", @@ -70,8 +70,8 @@ "file": "packages/metadata-protocol/src/sys-metadata-repository.recorded-by.test.ts", "unguarded": 1, "kind": "DEBT", - "why": "@objectstack/metadata-protocol does not depend on @objectstack/objectql. Pinning needs a devDependency + lockfile change, which is a separate reviewable act.", - "closes": "add @objectstack/objectql to devDependencies, then open the fake's delete with assertEngineDeleteDispatch(opts)" + "why": "MEASURED (#4987): the devDependency route this entry used to prescribe DOES NOT EXIST — it is cyclic, not merely unreviewed. @objectstack/objectql depends on @objectstack/metadata-protocol in `dependencies` (`workspace:*`), so any reverse edge closes a cycle by construction. Re-measured on #4987's branch rather than cited: the edge was added to metadata-protocol's devDependencies and turbo 2.10.7 refused BOTH task graphs outright — `WARNING Circular package dependency detected: @objectstack/objectql, @objectstack/metadata-protocol` / `x Cyclic dependency detected: @objectstack/objectql#build, @objectstack/metadata-protocol#build`, exit 1 from `turbo run build --filter=@objectstack/metadata-protocol --dry` and from the same command with `test` — then the edge was reverted. This is exactly the criterion the `packages/spec/src/contracts/data-engine.test.ts` EXEMPT entry below already states ('it cannot be pinned even in principle ... the import would invert the dependency'); it was simply never applied to the metadata-protocol entries. The entry stays DEBT and not EXEMPT because what cannot exist is the devDependency ROUTE, while the entry itself is closable by sinking the predicate — see `closes`. Whether this file's own fake delete is currently exercised was NOT probed: #4987's file face is this ledger's text only. Per this ledger's own rule that changes nothing, since it would be an argument about this file rather than about the contract.", + "closes": "sink assertEngineDeleteDispatch into a package BOTH sides already depend on — tracked as #5619 — then open the fake's delete with it. Verified available on #4987's branch: @objectstack/objectql and @objectstack/metadata-protocol both already depend on @objectstack/metadata-core (`workspace:*`), whose own `dependencies` are just @objectstack/spec + zod and do NOT include objectql, so the sink adds no new edge; the producer `packages/objectql/src/engine-delete-dispatch.ts` has zero imports, so this is a move and not a refactor. @objectstack/spec/contracts is the other candidate, but only if the predicate belongs to the contract layer — do not pick it by default. The devDependency route is closed by the cycle recorded in `why`, for this file and for every other metadata-protocol entry in this ledger alike." }, { "file": "packages/plugins/plugin-approvals/src/approval-actor-impersonation.test.ts",