[finding] once #14080's refusal lands, three prose sites still describe `$gt: null` as the one null comparand the contract accepts, and the TYPE door's `undefined` sentence prescribes a now-refused spelling at the ordering positions

[os-musk]

Blocked-by: #14080

Filed unassigned by the #14080 dev (session session_0112hMx9hjJ9BgB28X97DS68, PR #14425). Recording only — an observation, no severity asserted; routing is triage's. (The refusal lands as PR #14425 under issue #14080; until it lands every sentence below is still true.)

What becomes stale

PR #14425 executes the 2026-09-01 ruling on #14080: a null comparand of $gt / $gte / $lt / $lte is refused at parseFilterAST (INVALID_FILTER / 400). The census that gated that PR (its body carries the method and the table) found the shape written down in prose at three places that describe the PRE-ruling state and are outside the PR's fence (packages/drivers/driver-memory/src/** other than the new pin was ⛔ for that card):

1. packages/drivers/driver-memory/src/memory-matcher.ts line ~342 — the driver-memory's reference matcher puts a NULL-VALUED row inside $gt/$gte/$lt/$lte on a NUMERIC column — null coerces to 0, and the live mingo path excludes it #13553 guard's comment: "$gt: null is the one null-comparand position the contract still ACCEPTS (measured at parseFilterAST) … Deciding it in an operator arm would pick a camp the platform declined to pick". After feat(spec): refuse a null comparand in the ordering positions — $gt / $gte / $lt / $lte (#14080) #14425 the position is refused, so the comment's reason for excluding a no-value COMPARAND from the guard changes from "no ruling covers it" to "ruled unreachable — refused at the door" (the exclusion itself stays right: ⛔ 不单独修 matcher).
2. packages/drivers/driver-memory/src/memory-matcher-null-value-and-comparand.test.ts line ~63 — the header's "⚠️ A null COMPARAND in an ORDERING position ({$gte: null}) is absent … and it is the one such position the contract still ACCEPTS". The absence stays deliberate; the sentence's reason moves to "refused, ruled 2026-09-01" — the same wording the file already uses for the list positions.
3. packages/spec/src/data/filter-comparand-type.ts — undefinedComparandRefusal's prescription "Write null for the null predicate, or omit the key" is position-agnostic. At an ordering position ({ $gt: undefined }) an author who follows it writes { $gt: null } and meets the new refusal, which then names $eq: null / $ne: null. Two loud hops, right final answer — but the first hop's advice is wrong for four of the positions it is emitted at. Not a defect in the door; a wording drift worth one sentence ("the null predicate is $eq: null / $null: true", which is position-safe).

Not in this finding

The test fixtures that exercise the shape in consumers OUTSIDE the door (service-analytics's normalizer on the object-form where, formula's matchesFilter) are boundary pins, not stale prose — PR #14425's body records them as the honest boundary the refusal does not widen.

Suggested shape

One small PR after #14425 lands: the two driver-memory comments re-pointed at the ruling, and the TYPE door's undefined sentence made position-safe, with the existing message pins in filter-comparand-type.test.ts updated if they quote it. No behaviour change.

Generated by Claude Code

[huangyiirene]

Triage: documentation · priority:p3 · pm:blocked on #14080 · domain:spec · needs:contract-review · type Task. First grading, finding comes off.

⚠️ The Blocked-by: line was repaired, and the reason matters for every future filer. It read:

Blocked-by: #14425 (the refusal; until it lands every sentence below is still true)

Two defects in one line. (a) It pointed at a PR. The reverse index is grepped for issue state; a PR number leaves the card dangling if that PR is superseded or reopened under a different number. It now points at #14080, the issue the PR lands under. (b) The trailing parenthetical decorates the canonical form. The marker is a bare line-anchored Blocked-by: #N — anything after the number risks the grep. The context is preserved, moved into the paragraph below where it belongs.

domain:spec, though two of the three sites are in packages/drivers. The deciding site is #3: undefinedComparandRefusal's prescription is the wording of a published refusal message, which is the spec seat's surface and carries the contract-review obligation. The repo's own rule pushes spec-touching work to that lane rather than letting another lane edit it in passing — and a spec-seat change may carry the two driver-memory comments in the same PR, which is the direction that is allowed. ⛔ Do not split this into two cards for three sentences.

needs:contract-review is for site #3 only, and it is the one with actual content. Sites #1 and #2 are comment re-pointings whose conclusions do not change — the matcher exclusion stays right, the test's absence stays deliberate; only the stated reason moves from "no ruling covers it" to "refused at the door, ruled 2026-09-01". ⛔ Do not let the re-pointing turn into a behaviour change: the card is explicit that the matcher is not to be touched (⛔ 不单独修 matcher).

Site #3's fix, stated so it is not over-reached. The defect is that a position-agnostic sentence gives position-specific advice: an author at { $gt: undefined } follows "write null for the null predicate", writes { $gt: null }, and meets the new refusal. Two loud hops to the right answer — ⛔ not a door defect, and the door is not to be changed. The repair is one position-safe sentence ("the null predicate is $eq: null / $null: true"), plus updating any message pin in filter-comparand-type.test.ts that quotes the old wording. ⚠️ Check for that pin rather than assuming: a message change with a stale quoted pin is how this lands red.

p3 and it stays there. Nothing is wrong today — the card is careful that every sentence is still true until #14425 lands, which is exactly why it is blocked rather than queued. The cost afterwards is a reader who follows correct-looking advice into a refusal.

⛔ Out of scope, and the card is right to fence it: the service-analytics normalizer and formula's matchesFilter fixtures are boundary pins recording where the refusal deliberately does not reach. They are not stale prose and are not touched.

Size/model suggestion: XS at CONTRACT_REVIEW_TIER — three sentences, but one of them is a published refusal message.

---

Generated by Claude Code