May a hook-input record payload carry a SYMBOL key — and if so must enumeration publish it? (the half #12578 deliberately left open)

[os-warren]

Filed by the domain:engine PM seat before PR #12602 merges, because that PR carries the closing keyword on #12578 — so without this card the question closes with it and evaporates. The measurement below is the #12578 dev's; the filing decision is mine.

The card's own premise was wrong, and measuring it is what produced this question

#12578 assumed — and my dispatch brief repeated — that publishing symbol keys "would newly expose" them, i.e. that a symbol on a record payload was unreachable today and enumeration would be the door.

Measured, symbols are already reachable and already persist. input[sym] = 'symvalue' routes through the set trap into data; the descriptor trap reports it own and enumerable; hasOwnProperty is true; the persisted row holds it. Only Object.getOwnPropertySymbols(input) returns [].

So this is the same three-instrument disagreement #12578 just closed for string keys, still open for symbols — not a new capability anyone is proposing to add. The question is not "may a hook put a symbol on the row" (it already can, and the engine already stores it). The question is what enumeration should publish, and behind it, whether that shape should exist at all.

Why #12578 did not settle it

That PR took Object.getOwnPropertyNames(data) rather than Reflect.ownKeys(data) — the status-quo-preserving half of its own fork — precisely so the symbol delta stayed a payload-contract question rather than being decided as a side effect of a string-key repair. The omission is declared in the trap's comment and pinned in the test in its open state, so it cannot later be mistaken for a decision nobody made. That is the right call, and it is why this needs a card rather than a follow-up commit.

The options, with the measured cost of each

• A — as shipped: symbols stay unenumerated. The string half is closed; the symbol half stays open and pinned open. Costs nothing today, and leaves one instrument disagreeing with the other two on exactly one key kind.
• B — Reflect.ownKeys(data): closes the symbol half the same way the string half just closed. Cost: enumerable symbol keys become newly copied by spread / Object.assign and reported by getOwnPropertySymbols. ⭐ The sandbox snapshot is unaffected either way — unwrapProxyToPlain is an Object.entries over this proxy, which applies the enumerable filter itself — so body-runner does not block it.
• C — decide the contract first: establish whether a payload may carry a symbol key at all, and if not, refuse it at the set / defineProperty traps rather than hiding it from enumeration.

The dev's recommendation is C, with B falling out of it, and the reasoning is the one this family keeps arriving at: hiding a key the engine nonetheless persists is the failure shape #12277, #12397 and #12578 exist to abolish. A shipped only because it is the one option that does not decide the payload contract.

Either way it is one word of code once answered — the cost is entirely in the decision, not the implementation.

Why it is a maintainer floor

"What a record payload may hold" is a contract question about stored data, not about a proxy trap. This seat has applied that boundary three times today (#12397, #12578, #12166) and it applies here in its purest form: option C is only a contract decision.

Dedup

Searched 2026-08-26; the control fired on the flat-input / hook-payload vocabulary and returned the #12277 / #12397 / #12578 family. No existing card covers the symbol half — #12578 names it and explicitly defers it. The adjacent #12601 (a payload field named id/options/ast/data reading back the wrapper's value) is a different mechanism and separately filed.

Not claimed, not dispatched.

[os-zhuang]

Maintainer ruling recorded — Option C, refusal arm: a record payload may NOT carry a symbol key

Provenance: maintainer, 2026-08-27, PM chat decision-inbox batch 6 (adjudication session session_01DKWDdUJ2XNRESVVWUvcpnh), verbatim: 「其他同意」 — adopting the dev's recommendation C with the contract question answered in the refusal direction, ruled together with #12601 as one family.

Ruled: a record payload is a declarable, string-keyed field set — no metadata schema can declare a symbol field, so a symbol key on a hook-input payload is a JS-runtime artifact leaking toward storage. The set and defineProperty traps REFUSE a symbol key loudly (a clear error naming the key kind and the surface) instead of hiding it from enumeration while persisting it — hiding-what-you-persist is the exact shape this family (#12277/#12397/#12578) exists to abolish. ⛔ B (enumerate symbols via Reflect.ownKeys) declined — it would publish an undeclarable key kind as contract; ⛔ A (leave the instrument disagreement pinned open) superseded by this ruling.

Dispatch notes: one-word-plus-guard implementation per the card's own sizing; the #12578 pin that holds the omission open flips to a refusal pin (red-before-fix: a symbol write throws, nothing persists); serialize behind #12578's landed fix; may fold with #12601's alignment under the family gates (same trap set, both ruled).

State: needs-user-decision → pm:queue.

---

Generated by Claude Code

[os-zhuang]

Claim: domain:engine PM seat (#6367), session session_01LZbWd2jNV1FErXTPSS4Dry, branch claude/issue-12603-hook-input-symbol-key-refusal.

Serial constraints cleared: both prerequisites the ruling named are landed, verified by content on origin/main rather than by their closed state.

• [finding] The flat-input Proxy's ownKeys lists only data's ENUMERABLE keys — an own non-enumerable key is invisible to getOwnPropertyNames while hasOwnProperty and the descriptor trap both report it #12578 (ownKeys → Object.getOwnPropertyNames) — landed via PR fix(objectql): flat-input ownKeys reports the payload's own key set, not its enumerable subset #12602; the ruling says this card serialises behind it.
• [finding] A record payload field named id/options/ast/data reads back the WRAPPER's value through the flat-input proxy while its descriptor reports the PAYLOAD's — get and getOwnPropertyDescriptor disagree on the same key #12601 (descriptor/get envelope-first alignment) — landed as 86df0c99, marker RESERVED-NAME PRECEDENCE present, control fired. The ruling allows folding with it "under the family gates"; that fold is moot now that it has shipped, so this goes out on its own.

packages/objectql/src/hook-wrappers.ts should therefore be free. If you find another open PR touching it, stop and report rather than racing — the repo enforces this with No other open PR may claim the same single-writer path, and a second claim turns that check red for both.

Two things the ruling makes load-bearing

This one throws. Unlike the rest of this family, the ruled behaviour is a refusal: set and defineProperty must reject a symbol key loudly, with an error naming the key kind and the surface. Code that today silently accepts a symbol write will now fail. That is the intent — the ruling is explicit that hiding-what-you-persist is the shape #12277 / #12397 / #12578 exist to abolish — but it means the error message is part of the deliverable, not decoration. It has to tell an author what they did and where.

The pin is an inversion, not an addition. The ruling says the #12578 pin that currently holds the omission open "flips to a refusal pin." So: find that pin and turn it around; do not leave the old assertion standing next to a new one. A pin asserting the key is absent from enumeration and a pin asserting the write throws cannot both describe the same code, and leaving both is how a suite starts documenting two behaviours at once.

⛔ Out of scope: option B (Reflect.ownKeys) is declined by the ruling — it would publish an undeclarable key kind as contract. Option A (leave the disagreement pinned open) is superseded. Do not touch ownKeys itself; #12578 landed getOwnPropertyNames deliberately.

---

Generated by Claude Code