[finding] mergeObjectDefinitions docblock promises 'other props: later value wins' but the implementation silently drops every non-enumerated prop

[os-zhuang]

Found while resolving cloud#1653's named unknown (can a host override a framework object's tenancy declaration through the extension seam?).

packages/objectql/src/registry.ts — mergeObjectDefinitions's docblock says:

Fields are merged additively. Other props: later value wins.

The implementation does not do the second half. It merges exactly: fields (additive), validations (additive), indexes (additive), and the three guarded scalars label/pluralLabel/description. Every other top-level prop on an extension is silently dropped — merged = { ...base } and nothing else is copied.

Why it matters: anyone who reads the docblock and ships an objectExtensions entry carrying, say, tenancy: { enabled: false } (the exact thing cloud#1653's investigation considered) gets a silent no-op — the ADR-0078 valid-but-inert shape, on a security-relevant key. The docstring nearly steered a real architecture decision this week.

Two candidate remedies (implementer/triage judges): fix the docblock to state the real (closed) merge set — cheap and honest; or implement the documented semantics — a much bigger decision, since "any extender may override any prop" would make security-relevant keys (tenancy, permissions) extender-writable, which is almost certainly NOT wanted. The docblock fix looks right; the prop-carrying question, if ever wanted, should be per-key and deliberate.

[os-litant]

Triage (finding grading — first-time verdict): promote to pm:queue + domain:engine + type:Bug. Lands in packages/objectql/src/registry.ts (mergeObjectDefinitions), which is squarely domain:engine per the lane table. This is a restore-the-invariant fix (declared≠enforced docblock: the comment claims "other props: later value wins" but the implementation only merges fields/validations/indexes additively plus three guarded scalars, silently dropping everything else) — falls under the standing no-escalation class, so it does not need a needs-user-decision detour.

Scope for the dispatched fix: correct the docblock to state the real (closed) merge set, per the issue author's own recommendation. ⛔ Do not implement "any extender may override any prop" — the author correctly flags that as a separate, much bigger decision (security-relevant keys like tenancy/permissions becoming extender-writable), which is out of scope here and would need its own needs-user-decision card if ever wanted.

---

Generated by Claude Code

[os-zhuang]

Claim: domain:engine PM seat (#6367), session session_01LZbWd2jNV1FErXTPSS4Dry, branch claude/issue-12680-merge-object-definitions-docblock.

Dispatching at triage's scope: correct the docblock to the real, closed merge set. ⛔ Do not implement "later value wins" — making tenancy / permissions extender-writable is a separate decision and would need its own card.

Two things for the dev beyond the docblock edit:

A docblock fix with no pin is the same defect one release later. The reason this card exists is that prose and behaviour disagreed and nothing noticed. Rewriting the prose restores the invariant today and leaves it unguarded tomorrow. The merge set is small, closed and enumerable — fields, validations, indexes, plus the three guarded scalars — so a test that hands mergeObjectDefinitions an extension carrying a non-enumerated prop and asserts the merged result does not carry it pins the closed set as a fact rather than a promise. Pick a prop with no security weight for the pin; tenancy is the motivating example, not necessarily the right fixture.

Name the silence in the prose, not just the set. The failure mode this card is about is not "the list was wrong" — it is that a non-enumerated prop is dropped silently, which is the ADR-0078 valid-but-inert shape on a key an author had every reason to think was doing something. A docblock that lists the merge set but does not say "anything else on an extension is discarded without warning" leaves the next reader making the same inference cloud#1653 nearly made. Say the discard out loud.

Whether the drop should also warn at runtime is a real question and out of scope — if you find yourself wanting it, report it as an out-of-scope finding rather than adding it.

---

Generated by Claude Code

[os-zhuang]

os-dev-report

{
 "issue": 12680,
 "status": "done",
 "branch": "claude/issue-12680-merge-object-definitions-docblock",
 "head": "3e23512e7a44ef8f5817ede58ddc026c8b6e803c",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/12742",
 "pr_state": "draft, open, not armed for merge queue, no auto-merge",
 "clause2": "Docs-only correction plus a regression pin. Zero runtime behaviour changed by this PR -- mergeObjectDefinitions's logic is byte-identical to origin/main. mergeObjectDefinitions is NOT exported (module-private to registry.ts); the new pin exercises it indirectly through the existing public SchemaRegistry.registerObject/getObject API. Verified, not merely asserted: grepped for an 'export' on mergeObjectDefinitions (none), and confirmed the test file imports only { SchemaRegistry } from './registry.js'. No public surface is widened or narrowed; no new export was needed for the pin.",
 "merge_set_measured": "Read directly from packages/objectql/src/registry.ts on origin/main (a65db765) before editing: merged = { ...base }; then only fields (additive spread), validations (additive concat via [...(base.validations||[]), ...extension.validations]), indexes (additive concat), and the three OBJECT_FOLD_SCALAR_KEYS (label, pluralLabel, description -- last-writer-wins, yielding to tenantAuthored) are ever copied onto merged. This matches the card's claim (and the PM dispatch comment's restatement) exactly -- no drift found between the card's premise and the code on the branch's base commit.",
 "ablation": {
 "prediction_commit": "3e23512e7a44ef8f5817ede58ddc026c8b6e803c (empty commit, full prediction text in the commit message, committed BEFORE any mutation)",
 "predicted": "Exactly 2 failing tests, both in the new pin file: 'discards a non-enumerated top-level prop (icon) from an extend contributor silently' and 'discards a non-enumerated prop the BASE never declared, rather than materializing it from the extension'. Named positive control (different test, same mechanism): registry-object-overlay-layer.test.ts > 'extenders still fold on top of whichever layer is the base', predicted green.",
 "observed": "3 failing tests, not 2 -- a genuine deviation from the written prediction, reported honestly rather than smoothed over. The 2 predicted pin failures occurred exactly as named. PLUS one unpredicted collateral failure: registry-object-overlay-layer.test.ts > 'ADR-0029 D9.3 -- priority orders peers; the KIND selects the base > an extender declaring priority 140 does not become the base layer', failing because merged._provenance flipped from 'org' to 'package' -- that test's extend contributor carries `_provenance` as a top-level prop, a SECOND real-world case (beyond the pin's own `icon` fixture) that the closed merge set silently protects. The named positive control test itself stayed green exactly as predicted (it is a different test in the same file/describe-adjacent, unaffected because it only asserts on `fields`). Mutation mechanism: an anchored Object.keys(extension) pass-through loop inserted into mergeObjectDefinitions, skipping fields/validations/indexes/the three guarded scalars and copying everything else last-writer-wins -- i.e. literally what the old, false docblock promised.",
 "mutation_proof": "Anchored via node script (mutate.cjs) against the literal string ' return merged;\\n}\\n\\n/**\\n * [#8027] Key-order-insensitive JSON' in registry.ts -- refuses (exit 1, no write) if the anchor is not found or the replace is a no-op. grep -c for the marker 'ABLATION #12680 BEGIN' read 0 before, 1 after (both begin/end markers), with the injected block printed in context (grep -n -A10) before any test ran.",
 "restore_proof": "git checkout HEAD -- packages/objectql/src/registry.ts, then verified: git hash-object of the worktree file == git rev-parse HEAD:packages/objectql/src/registry.ts (5f061cd8...bbadbbb19, exact match), git diff HEAD --stat empty, git status --short clean, grep for the marker returns 0. Then the full registry*.test.ts suite (27 files, 393 tests) was re-run post-restore: 393/393 passed, confirming the tree is functionally back to baseline, not just byte-identical.",
 "positive_control": "registry-object-overlay-layer.test.ts > 'ADR-0029 D9.2 -- the overlay REPLACES the base layer, bit for bit > extenders still fold on top of whichever layer is the base' -- exercises the same extend-fold machinery (asserts an extend contributor's `fields` merge: ext_field appears, packaged_only does not) but is untouched by the mutation, which only adds pass-through for keys OUTSIDE {fields, validations, indexes, label, pluralLabel, description}. Stayed green under mutation, exactly as predicted -- confirms the mutation cut the intended thing rather than the whole suite.",
 "process_note": "The first ablation run attempt used the shared verify-lock but the pnpm command executed from the wrong cwd (the shell's default /home/user/objectstack, i.e. the shared main checkout, not the worktree) because the script never `cd`'d into REPO_ROOT before invoking the lock-guarded command -- it hit ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL / 'Command vitest not found' in the wrong tree (a NOT-MEASURED artifact, not a real result, and reported here for transparency). TaskStop was used to end that run; since it did not run the script's EXIT trap, the mutation was still present in the worktree file afterward -- reconfirmed present via grep, then the test run was redone correctly with an explicit cd into the worktree, and the restore + verification above were performed manually with the same rigor the trap would have applied."
 },
 "gates": {
 "green": [
 "objectql full registry*.test.ts suite (27 files, 393 tests) -- both pre- and post-ablation-restore",
 "pnpm --filter @objectstack/objectql exec vitest run (new pin file) -- 2/2",
 "pnpm --filter @objectstack/objectql typecheck (tsc --noEmit x2) -- passes but see NOT MEASURED note on test-file coverage",
 "check:engine-double-contract (re-run against freshly-fetched origin/main baseline)",
 "check:where-matcher",
 "check:objectql-double-limit",
 "check:query-options-erasure",
 "check:cross-package-test-inputs",
 "check:test-source-alias",
 "check:type-source-resolution",
 "check:durability-log-level",
 "check:page-declaration-shape",
 "check:published-files",
 "check:slot-lookup",
 "check:changeset-gate-self-tests (check-empty-changeset/check-adr-0087-registration/check-changeset-no-major self-tests)",
 "check:objectui-changeset",
 "check-ci-filter-parity.mjs",
 "check-comment-mask-adoption.mjs",
 "check-engine-split-ratio.mjs (required deepening the shallow clone via the gate's own printed remedy: git fetch --shallow-since=2026-05-22)",
 "check-plugin-teardown-shape.mjs",
 "release-rehearsal-clone.mjs --self-test",
 "docs-audit/check-affected-docs.mjs",
 "docs-audit/check-drift-comment.mjs",
 "check-adr-0087-registration.mjs (individual re-run, no declared-breaking changeset -- correctly not triggered since this changeset is patch-level)",
 "check-changeset-no-major.mjs",
 "check-empty-changeset.mjs",
 "check:type-check-coverage (structural half, no --re-measure) -- OK, no new debt introduced by the new hidden test file",
 "node scripts/check-nul-bytes.mjs (repo-wide)"
 ],
 "red": [],
 "not_measured": [
 "check:pm-half-states -- exit 3, PREREQUISITE NOT MET: no usable GITHUB_TOKEN in this container (proxy placeholder token, 401/exhausted-anonymous). Says nothing about the board's half-state cleanliness one way or the other.",
 "check:type-check-debt (the --re-measure ratchet half specifically) -- refuses outright (its own thrown Error) without the full packages/* + packages/*/* workspace closure built (42 dependency packages named as missing built type entry points). That build is CI's lint.yml preamble (turbo run build --filter='./packages/*' --filter='./packages/*/*' across 78 workspace packages) and was judged out of scope for a 2-file, 1-package docs+test diff per AGENTS.md's local-verification-scope guidance (whole-farm/whole-workspace builds belong to CI). The cheap structural half of the same script (check:type-check-coverage, no --re-measure) DID run and passed clean, so the new test file's classification (already inside objectql's existing TEST_DEBT hidden-tests bucket) is not new debt structurally; only the exact re-measured raw error count is unmeasured locally.",
 "Full type-check of the new test file itself -- packages/objectql/tsconfig.json excludes **/*.test.ts, so `pnpm typecheck` never reads it. vitest's esbuild transform ran it successfully but esbuild does not type-check. An ad-hoc tsc invocation via a scratch tsconfig was attempted but hit a 2-minute tool timeout waiting on the shared verify lock and was not retried, given the file's low type-risk (simple literal object casts with `as any`, matching the pattern used throughout this suite's ~30 sibling test files)."
 ]
 },
 "deviations": [
 "Ablation observed 3 failing tests, not the predicted 2 -- see ablation.observed above. The extra failure is a genuine, previously-unknown collateral finding (a second real-world top-level prop, `_provenance`, that the closed merge set protects), not a flaw in the pin or the prediction methodology; reported rather than silently reconciled.",
 "The first ablation test-run attempt executed pnpm from the wrong cwd (shared main checkout instead of the worktree) due to a script bug (missing `cd` before the lock-guarded command) -- caught before drawing any conclusion from it, and the run was redone correctly. Recorded in ablation.process_note for transparency.",
 "check:type-check-debt's --re-measure half and check:pm-half-states are NOT MEASURED for reasons outside this PR's control (full-workspace-build cost and missing GITHUB_TOKEN respectively) -- both are named explicitly rather than folded into a blanket 'gates passed'."
 ],
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code