Repository navigation
On a base package upgrade, list each <base>.custom override whose base item the upgrade changed — an override that now hides a vendor change (advisory; epic cloud#3652 D2, after the ADR-0146 amendment, card 06) #30886
Description
repo:cloud#3 · hotlong · session_01Q4EjjRhUZjdy8VXs6Kkur2
Blocked-by: #30881
Blocked-by: #30884
Filing gate: ③ a task on the maintainer's word. Epic objectstack-ai/cloud#3652, coordinator session 2026-11-06, verbatim: 「我觉得先把受管软件包的开发循环走顺了」, then 「同意，然后第一步先解决我本地开发的软件包怎么能够方便地发布到云端」. Phase 2 lists: ".custom drift: on a base upgrade, check each override's basedOn and list overrides that now hide a vendor change." Ruling Q1 on cloud#3652, verbatim: 「a 本地 os dev（推荐）」. Decision D2 on the epic (2026-11-06), the maintainer's selection verbatim: 「修订为允许只提示（推荐）」. ADR-0146 is amended (card 06) to allow this advisory finding, with no blocking and no auto-merge. Q3 does not apply: an override is not a field rename.
Carrier: objectstack. The .custom pair, the override declaration, the served-override read and the customizations read are all framework code. The check runs in the framework, inside 01a's environment-aware half. Cloud shows it through 01c's preview and adds nothing of its own. (「平台的问题应该在平台处理」, #30765)
维护者速读
管理员在 <base>.custom 里覆盖了某个视图之后，厂商升级基础包时改了同一个视图，管理员不会知道：他的覆盖继续生效，把厂商的改动整个挡住。ADR-0146 当时规定「basedOn 只记录、不判断」，你已裁决修订为允许只提示（卡 06 改 ADR）。等 06 由你合并后，这张卡在平台的升级预览里加上这一类提示：「这些覆盖挡住了这次升级的改动」。只提示，不拒绝，不自动合并，云端和私有部署都能看到。
Today (objectstack origin/main c50e0dfa)
basedOnis recorded and never judged, by ADR. (measured)- ADR-0146 D2: "
basedOnis recorded, not judged: no door compares it with the installed base's version, no upgrade diff is produced, and nothing is refused on it" (docs/adr/0146-…-paired-customize-package.md:210-212). - "Diff-vs-base and the upgrade skip-report stay deferred" (
:262); merge question 2 restates it (:679-681). - The Consequences name the cost: "an overridden item shadows the vendor's later change to that one item until the customer re-bases it, and the platform computes no diff to help" (
:598-601).
- ADR-0146 D2: "
- The code follows the ADR. (measured)
OverrideDeclaration.basedOnis a plain string, "recorded and never judged" (packages/spec/src/kernel/override-declaration.zod.ts:93,:137,:141).- The customizations read copies it "as recorded", with "⛔ No diff against the base's document and no
basedOnverdict" (packages/metadata-protocol/src/protocol-served-overrides.ts:45-47,:120-128). The spec response carries it (packages/spec/src/api/package-lifecycle.zod.ts:525).
- What an upgrade has to work with. (measured)
- Self-hosted install-local keeps the installed manifest on disk (
<cwd>/.objectstack/installed-packages/<id>.jsonholdsmanifest,marketplace-install-local-plugin.ts:130-132). Cloud keeps every version'smanifest_jsonon the control plane. - So at upgrade time both the installed and the new base are available. The
basedOnversion's own artifact is not necessarily available (inferred: no store of older artifacts on self-hosted).
- Self-hosted install-local keeps the installed manifest on disk (
- The boot upgrade-impact report covers overlay orphans (a removed base item), not an override that still matches a base item the vendor changed (
packages/plugins/plugin-security/src/upgrade-impact-report.ts, class O item 6). (measured)
Expected (after card 06 merges)
- In 01a's environment-aware half, for a base package upgrade: each item of
<base>.customthat declaresoverrides: { package: <base> }and whose same-named base item differs between the installed and the new version is listed as "this override hides a change in this upgrade", with type, name,basedOn, and the installed and new base versions. - An override whose
basedOnis not the installed version is listed as already stale. A second, quieter finding. - Advisory only. Nothing is refused, no token is needed, and no write follows. Card 06 fixes that wording in ADR-0146.
- The finding names the next step in Studio: open the item, compare, re-base or restore the package original (ADR-0146's revert).
Acceptance
- Tests: base v1 → v2 changes view
x, and.customoverridesx→ one finding; v2 leavesxunchanged → no finding; an override withbasedOn≠ the installed version → the stale finding; the install proceeds in every case. - The finding appears in install-local's dry run and, through 01c, in cloud's preview read.
Serial: after 06 is merged by the maintainer (Tier H) and after 01a. No Phase 1 dependency. In the same PR, change the "recorded and never judged" sentences in code to match the amendment: packages/spec/src/kernel/override-declaration.zod.ts:137, :141 and packages/metadata-protocol/src/protocol-served-overrides.ts:46.
Dedupe (2026-11-06), run as gh api -X GET search/issues -f q=…:
repo:objectstack-ai/objectstack basedOn is:issue→ 47 hits; the only open ones are QA runs QA run · adr-0146-new-items (7/7) · 322cf906 · 2026-11-02 · 6 PASS / 0 PARTIAL / 1 FAIL / 0 BLOCKED / 0 NOT-RUN #29648 and QA run · adr-0146-new-items (7/7) · 128681f4 · 2026-11-02 · 4 PASS / 0 PARTIAL / 3 FAIL / 0 BLOCKED / 0 NOT-RUN #29560.repo:objectstack-ai/objectstack ".custom" drift base upgrade is:issue→ 130 hits; open QA run · release-18.3.0-w5-studio (38/38) · 589049b0 · 2026-11-03 · 37 PASS / 0 PARTIAL / 1 FAIL / 0 BLOCKED / 0 NOT-RUN #29893 (QA run) and [epic] ADR-0131 — total organization ownership: no NULL organization_id (v18 line) #15194 (epic). None.repo:objectstack-ai/objectstack override hides vendor change upgrade is:issue→ 21 hits, none.repo:objectstack-ai/objectstack upgrade skip-report is:issue→ 259 hits (broad); no open card on it.repo:objectstack-ai/objectstack "N-09" is:issue→ 115 hits. All the ones shown are the closed ADR-0146 epic [Epic] Package-level override: every customization of an installed package lives in its paired <base>.custom package, one declared override shared by code and Studio (supersedes #28130) #28236 family (docs(adr): ADR-0146 amendment — only the paired<base>.customdeclares an override; a dependent package adds under its own names (ruled A, withdraws rider 3) #28390, metadata-protocol: one effective read — package-less, base-named, layered, the env-wide list and export serve the.customdeclared override, and a withdrawn public form stays withdrawn #28409, metadata-protocol: the override write gate — only the base's paired.custommay declare; undeclared same names and a dependent'soverridesare refused at publish,os validateand install #28410, cli + metadata-protocol:os migratemoves package-less overlay rows into <base>.custom as declared overrides — the migration ceremony only (the close is N-16b) #28413 …). ADR-0146 gives N-09 the name collisions a base upgrade causes (:612-616), not a changed base item under a declared override.
Suggested-grade: p3 · advisory, blocked on a ruling; the change preview (01a/01c) stands without it.
Clause-②: yes (widening) · a new finding kind in the upgrade plan's response. It refuses nothing. Card 06 (the ADR-0146 amendment) is the governing change.
🤖 Generated with Claude Code
Activity
objectstack-fleet commentedon Nov 6, 2026
triage#1 · os-zhuang · session_01AavokzJ5DndAwitDXvKy4U
Path: none
Triage: audit · grade kept ·
domain:server·pm:blocked· 2026-11-06T10:00Z⛔ Not a claim.
domain:server, andrepo:cloud#3follows it. The grade the filer set is kept.Blocked-byholds.Generated by Claude Code
objectstack-fleet commentedon Nov 6, 2026
repo:cloud#3 · hotlong · session_01Q4EjjRhUZjdy8VXs6Kkur2
Scope addition (not a claim), from contract review 6682453235 on PR #30899 (the ADR-0146 amendment this card waits on). When this card's code lands, its PR must also correct these texts, which state today's "no upgrade diff" runtime and become false once the advisory finding ships:
packages/spec/src/kernel/override-declaration.zod.ts(the.describe()around:93-99, plus:137,:141) and the generatedcontent/docs/references/**pages built from it;packages/metadata-protocol/src/served-override.ts:35;packages/metadata-protocol/src/protocol-packaged-base-refusal.ts(the matching sentence; line numbers drift);content/docs/api/metadata-api.mdx:105,content/docs/concepts/metadata-lifecycle.mdx:121.Governed quotes stay with the maintainer, so do not edit them here:
docs/adr/0126-packaged-metadata-customization-model.md:3andskills/objectstack-platform/evals/config-plugins-ops.json:169. The review judged both still true under the amended vocabulary.objectstack-fleet commentedon Nov 8, 2026
domain:server#3 · os-project-manager · session_01FEkQ5pXkgNXVpCn2GZDjyy
Unblocked · 2026-11-08T04:21Z · Every
Blocked-by:is closed: #30881 at 2026-11-06T15:26:31Z and #30884 at 2026-11-08T01:26:55Z, both completed. The card declaresClause-②: yes (widening)and editspackages/specprose, so the claiming seat checks the spec-seat red line before taking it. Movedpm:blocked→pm:queueby the server seats' unblock scan (execution-duties.mdidle chore ①). ⛔ Not a claim.objectstack-fleet commentedon Nov 8, 2026
domain:server#4 · os-steve · session_01ADHkmP8JJo4zF2sjTBRwnX
Claim: PM loop round 1 · #30886 · 2026-11-08T16:03Z
Session:
session_01ADHkmP8JJo4zF2sjTBRwnX(seat); dev = card threadsession_01ADHkmQcUzUoY658CkxoPfnAccount:
os-steveBranch:
claude/project-thread-88ans5Worktree: the card thread's checkout of
objectstack-ai/objectstackDomain:
domain:serverSeat:
domain:server#4File surface:
packages/metadata-core/src/package-upgrade-plan.ts,packages/objectql/src/package-upgrade-environment.ts,packages/cloud-connection/src/marketplace-install-local-plugin.ts(the dry-run / upgrade-plan region only),packages/cli/src/commands/{diff.ts,package/install.ts}if the finding is printed there, their tests; prose only:packages/spec/src/kernel/override-declaration.zod.ts(.describe()/ JSDoc),packages/metadata-protocol/src/{served-override.ts,protocol-packaged-base-refusal.ts},content/docs/api/metadata-api.mdx,content/docs/concepts/metadata-lifecycle.mdx, generatedcontent/docs/references/**;.changeset/30886-*.md(stop on breach; a new finding kind in apackages/speczod response is NOT prose: stop with needs_decision)Container & model:
M,mode:thread,model: default tier (dispatch-gates --tier: no path-derived mandate; floor/default/ceiling left to the seat). The Clause-② widening is reviewed at CONTRACT_REVIEW_TIER before the queue (--tier: "a card that WIDENS … owes a REVIEW"),effort: highClause-②: yes (widening)
Metadata-protocol: none
Responsibility: n/a — not a defect card
Thread-read: 6717182698
Premise: holds (both
Blocked-by:closed: #30881 via PR #30899, #30884 via PR #309838847e09d22; scope addition 6683318926 carried into the order)Serial constraints cleared:
marketplace-install-local-plugin.tsis shared with open PR #31570 (#31530,domain:server, unmanaged-copy region) and #31564 (domain:server#2, register-refusal region, branchclaude/project-thread-1gwtt5); regions disjoint, ordinary concurrency: mergeorigin/mainbefore the PR and again after either lands.objectstack-fleet commentedon Nov 8, 2026
domain:server#4 · os-steve · session_01ADHkmP8JJo4zF2sjTBRwnX
Claim amendment · #30886 · 2026-11-08T16:04Z · amends claim 6723742292 · File surface only (Branch, Clause-②, Metadata-protocol unchanged)
packages/objectql/src/plugin.ts, the manifest service'splanUpgradeclosure only (pass a lazy override reader, from the protocol'slistServedOverrides, intoplanPackageUpgrade). No open PR touches this file today.PackageUpgradePlanReading,packages/objectql/src/package-upgrade-environment.ts); nopackages/speczod carries it, so the spec red line does not apply to the new finding kind.objectstack-fleet commentedon Nov 8, 2026
domain:server#4 · os-steve · session_01ADHkmQcUzUoY658CkxoPfn
os-dev-report
{ "issue": 30886, "status": "done", "branch": "claude/project-thread-88ans5", "pr": "https://github.com/objectstack-ai/objectstack/pull/31627", "session": "session_01ADHkmQcUzUoY658CkxoPfn", "premise_still_valid": true, "summary": "planPackageUpgrade (objectql, 01a's environment half) gains an advisory class environment.overrides = { hidesChange, stale } | null: for each base package the installed artifact delivers, the protocol's listServedOverrides (resolved lazily in the manifest service's planUpgrade closure) is read against the installed and incoming bodies, items enumerated as the engine registers them, compared canonically without loader stamps. Advice only: the schema refusal and its token are untouched (pinned + ablated); null when unread. os package install --dry-run prints both lists; the basedOn 'recorded and never judged' prose (spec describe + 18 regenerated reference pages, metadata-protocol, two docs pages) now says it never gates and the upgrade plan reads it as advice. On main 645ed3d1 the same input answers planEmpty:true and an environment with no override key (measured).", "tests": "head a4cbe87c92. objectql package-upgrade-environment.test.ts 14/14 (7 new); cloud-connection marketplace-install-local-upgrade-plan.test.ts 24/24 (3 new); cli package-install-dry-run.test.ts 8/8 (1 new); spec override-declaration.test.ts 62/62. Full pre-merge: objectql 570 files/11578 tests, cloud-connection 78/1068, metadata-protocol 327(+4 skipped)/22591, cli unit 405/5721, spec 822 files with 1 forced pin of the old wording updated then green; typecheck exit 0 for all five. Ablations (ablation-replace.mjs, src-resolved, no dist leg): A1 unchanged-as-changed 3 red; A2 stamps first run GREEN (vacuous pin, fixed) then 1 red; A3 failed-read-as-empty 1 red; A4 no-reader-as-empty 2 red; A5 door refuses on advice 4 red; each restored blob==HEAD, git diff HEAD empty.", "gates": "dispatch-gates --commands at a4cbe87c: 122 families; 118 exit 0 first pass, 4 exit 3 prerequisites (teardown fixture 621a4876, client-react dist, a package dist, connector-slack dist) re-run exit 0 after fetch + cache-hit build; --ran: 122 derived, 122 run, 0 NOT-MEASURED, 0 UNRUN. lint (root eslint --no-inline-config, no package lint script): packages/{objectql,cli,cloud-connection,metadata-protocol,spec}/src exit 0 each. spec check:generated: all 14 up to date post-merge. CI check-runs: in_progress at report time.", "dogfood_battery": "n/a — no `!` in the PR title and no (narrowing) arm", "mcp_calls": "4 — mcp__github__issue_read x3 (card get, comments x2), mcp__github__pull_request_read x1 (PR read-back); no write tool", "api_writes": "2 — relay pr_create objectstack-ai/objectstack#31627; relay os-dev-report comment on #30886 (git push is not a REST write)", "open_questions": [ { "question": "Is an override whose stored body records no basedOn listed as stale?", "options": [ "A not listed (schema requires basedOn; residue the advice cannot date)", "B listed as stale with basedOn absent" ], "recommendation": "A, as implemented: listing it would date nothing, and the declaration schema requires basedOn (not measured at a door)" }, { "question": "Does hidesChange also list base items the upgrade removes or newly adds under an overridden name?", "options": [ "A yes, change: removed | added beside changed", "B only changed" ], "recommendation": "A, as implemented: both mean the override now shadows a different base answer; the boot orphan report covers removal only after the fact" }, { "question": "Field name of the advisory class in the response", "options": [ "A environment.overrides (rides every reader that forwards environment whole, incl. the dry run and 01c)", "B a new top-level key beside plan and environment" ], "recommendation": "A, as implemented: no door or cloud change needed; the refusal reads only environment.columns" } ], "security_findings": "none", "out_of_scope_findings": [ "carrier: none · noted in PR Acceptance notes 3: protocol-served-overrides.ts:45-47 and spec package-lifecycle.zod.ts:536 describe the customizations read, still true, not edited" ], "files_changed": [ "packages/objectql/src/package-upgrade-environment.ts", "packages/objectql/src/package-upgrade-environment.test.ts", "packages/objectql/src/plugin.ts", "packages/cli/src/commands/package/install.ts", "packages/cli/test/package-install-dry-run.test.ts", "packages/cloud-connection/src/marketplace-install-local-upgrade-plan.test.ts", "packages/spec/src/kernel/override-declaration.zod.ts", "packages/spec/src/kernel/override-declaration.test.ts", "packages/metadata-protocol/src/served-override.ts", "packages/metadata-protocol/src/protocol-packaged-base-refusal.ts", "content/docs/api/metadata-api.mdx", "content/docs/concepts/metadata-lifecycle.mdx", "content/docs/references/** (18 generated pages)", ".changeset/30886-upgrade-plan-override-advisories.md" ], "line_budget": "31 files, +537/-63 = 600 changed lines (generated included) vs the 3000 human-merge threshold: under", "deviations": [ "packages/objectql/src/plugin.ts edited under claim amendment 6723756312 (planUpgrade closure only)", "packages/spec/src/kernel/override-declaration.test.ts edited: a forced pin of the old basedOn wording the card orders changed (surface listed spec prose only)", "ablation A2 first run was a no-op on the pin (the pin overrode only an expanded view item, which carries no stamps): pin fixed, ablation re-run red; declared, not silently re-run", "PR assignee/reviewer not set: the standard order forbids MCP writes; the claim's Account rides pr_create (relay read-back: assignees none)", "test:repo not run locally (no repo-project test changed)" ] }Stamped 2026-11-08T17:35Z.
objectstack-fleet commentedon Nov 8, 2026
domain:server#4 · os-steve · session_01ADHkmP8JJo4zF2sjTBRwnX
Claim amendment · #30886 · 2026-11-08T18:45Z · amends claim 6723742292 (as amended by 6723756312) · File surface only (Branch, Clause-②, Metadata-protocol unchanged)
packages/objectql/src/engine-top-level.ts(one exported predicate,registersManifestAsApp, lifted from the engine's inline condition) andpackages/objectql/src/engine-registration.ts(its two inline uses replaced by that predicate, behaviour unchanged). The seat ordered the condition read from the engine rather than re-derived.'@objectstack/metadata-protocol': patch(the exportedjudgeOverrideWriteJSDoc ships indist/index.d.ts).objectstack-fleet commentedon Nov 8, 2026
domain:server#4 · os-steve · session_01ADHkmP8JJo4zF2sjTBRwnX
Landed · #30886 · 2026-11-08T19:52Z
b2ce2503c6; heade73f5c2c17(ACCEPT 6725620953; contract review PASS 6724918203 + delta PASS 6725590527)completedbyFixes #30886State change:
pm:dispatchedremoved andos-steveunassigned in this stroke. Accepted nits stay as recorded in the ACCEPT; no follow-up card is owed.objectstack-fleet commentedon Nov 8, 2026
domain:server#4 · os-steve · session_01ADHkmP8JJo4zF2sjTBRwnX
Duplicate of 6726306223 (the landing tool was re-run after a silent exit); that comment is the landing record.
objectstack-fleet commentedon Nov 8, 2026
domain:server#4 · os-steve · session_01ADHkmP8JJo4zF2sjTBRwnX
Duplicate of 6726306223 (the landing tool was re-run after a silent exit); that comment is the landing record.