fix(objectql)!: route having through the shared comparand-shape face — having: { total: [5] } is refused like the same shape in where

[objectstack-fleet]

Fixes #19974
Clause-②: no (narrowing)

This routes the having clause of engine.aggregate through the shared comparand-shape face. It executes ruling 乙 (record 5793368540 on #19757, 「217 同意」) at the one position that ruling's face did not reach yet. The triage execution point, verbatim: 「钉子:having: { total: [5] } 和 having: { total: { $eq: [5] } } 被拒绝;标量照常通过。」

Session session_01Bvd69VPa6puiNzzPUroDBx, branch claude/issue-19974-having-array-equality. Base 9b8c74c6c5, head 5649560428. Every reading below was taken on one of those two commits, as stated.

1. Measured first, on the base 9b8c74c6c5

Every filter was run through the public engine.aggregate twice, once as a where and once as a having, with the same bytes each time. Two drivers were used: driver-memory and driver-sqlite-wasm. Both have a native aggregate(). Each having was run on both applyHaving doors. The native door is the driver.aggregate() path. The in-memory fallback door was forced by adding a per-aggregation filter. The data was grouped by customer: c1 has total 500 over 2 rows, c2 has 1250 over 3, and c3 has 20 over 1.

Both drivers and both doors gave the same answer in every row. Every where was refused with INVALID_FILTER / 400 and the aggregate('order'): prefix:

arm of the face	the shape, as a having	having answered
equality-slot array (the triage shape)	{ total: [500] }	c1, because JS 500 == [500] is true
equality-slot empty array	{ total: [] }	no group
$eq array (the triage shape)	{ total: { $eq: [500] } }	c1
equality-slot array under $or / $and	{ $or: [{ order_count: 99 }, { total: [500] }] }	c1
equality-slot array under $not	{ $not: { total: [500] } }	c2, c3
scalar $in / $nin	{ customer_id: { $in: 'c1' } }	$in: no group. $nin: every group
null list member	{ customer_id: { $in: ['c1', null] } }	$in: c1. $nin: c2, c3
null ordering comparand	{ total: { $gt: null } }	$gt / $gte: every group. $lt / $lte: none
malformed $between	{ total: { $between: 500 } }, [500]	the scalar kept every group; the one-bound list kept c1, c2
null / blank $between bound	[null, 1000], ['', 1000], [undefined, 1000]	c1, c3
{ $field } $between bound	[{ $field: 'order_count' }, 1000]	c1, c3

That is 20 rows, counting each operator spelling, and all 20 were refused on where and answered on having. Six controls gave the same rows on the base and at head: a scalar, $eq with a scalar, an $in list, a two-bound $between, $eq: null, and $ne with an array. The $ne row is not an arm of the face, see §4.

• H1 confirmed. having-filter.ts sends an array into its implicit-equality arm (value == condition), and its $eq arm compares with !=.
• H3 confirmed, and wider than the equality slot. The face refused 20 shapes on where, and having refused none of them.

2. What changed

• packages/objectql/src/engine.ts, ObjectQL.aggregate. One call was added: assertListComparandShapes(object, 'aggregate', query.having, 'having').
  • It sits after the per-aggregation filter loop and before getDriver, the middleware chain, and either door.
  • It is the same objectql wrapper that where (inside lowerWhereFilterArray) and aggregations[i].filter already call on this verb, and it delegates to @objectstack/spec/data's assertListComparandShapes.
  • ⛔ No second face was added, and having-filter.ts is untouched.
• packages/objectql/src/engine-aggregate-having-comparand-shape.test.ts, new, 37 tests.
• .changeset/19974-having-comparand-shape-face.md.

3. The doors that reach applyHaving (H2)

There are exactly two call sites in the repository. Both are inside ObjectQL.aggregate in engine.ts:

• the native door: return applyHaving(aggregated, ast.having) after drv.aggregate(...);
• the in-memory fallback door: return applyHaving(applyInMemoryAggregation(raw, ast, tz), ast.having).

The PM's "earlier fork" near the first door is having: query.having on opCtx.ast. That line puts the clause where plugin-security's predicate guard can walk its field references. It evaluates nothing, and nothing writes ast.having afterwards (git grep finds no .having = assignment in any package source).

applyHaving and matchesHaving are not exported from @objectstack/objectql's . or ./core entry, and no driver reads having. The REST aggregate query forwards having to engine.aggregate, in metadata-protocol's protocol.ts.

So one gate ahead of both doors covers every door. It also judges the FILTER rather than the rows. applyHaving evaluates per aggregated row, so a gate inside the walker would stay silent on an empty grouped set. A pin covers that case.

4. The refused set, where against having (H3)

	where	having
before (9b8c74c6c5)	20 of 20 refused	0 of 20 refused
after (5649560428)	20 of 20 refused	20 of 20 refused, with the face's own words; the only difference from where is having. in place of where. in the path

The test's parity table asserts both halves on every row, on both doors:

• havingErr.message === whereErr.message.replaceAll('where.', 'having.');
• whereErr.message equals the face's own refusal, so the row cannot be refused by some other gate;
• neither door asked the driver for a row.

$ne with an array is not an arm of the face. The ruling left it out, and #19886, which is ruled and dispatched, carries it. On where it is refused one layer down, by the drivers themselves: driver-memory gives the refusal without the aggregate('order'): prefix, and driver-sqlite-wasm withholds the detail. On having it still answers c2, c3 by == coercion. A test holds having to whatever the face answers for it. When the $ne arm lands on the face, having refuses it through this same call, and that pin stays green in both states.

5. Changeset (H4)

@objectstack/objectql: minor with **BREAKING**, fix(objectql)!:, Clause-②: no (narrowing) and one ADR-0087 marker: not-required (already-registered filter-equality-array-comparand-refused, filter-between-blank-endpoint-refused, filter-between-field-reference-endpoint-refused). The gates' own lines:

• check-adr-0087-registration: ✓ ... 1 declared-breaking changeset(s), each carrying an ADR-0087 disposition. and .changeset/19974-having-comparand-shape-face.md [BREAKING+bang+clause-②-narrowing] not-required (already-registered)
• check-changeset-no-major: ✓ This diff introduces no major bump. Its clause-② level axis prints NOT APPLICABLE locally, because there is no pull_request payload; CI reads it from this body.

6. Tests, ablation, gates

All counts below are on head 5649560428, except the objectql local project, which ran on 0052ce29c1. engine.ts has the same blob (7830b0cee3) at both commits, and the only later change is the new test file, which was re-run at head.

• @objectstack/objectql, vitest run --project local: 313 files, 5320 passed. --project repo: 1 file, 5 passed.
• @objectstack/objectql typecheck: exit 0. check:test-typecheck is OK with 40 files and 234 errors held, unchanged. tsc -p tsconfig.test.json --listFiles includes the new test file (1 hit, 314 test files in the program).
• New file alone: 37 passed. It sits beside the existing engine-aggregate-having.test.ts (5 passed).
• Consumer suites that assert having behaviour, found by grep:
  • metadata-protocol protocol.query-param-arity.test.ts: 46 passed;
  • plugin-security predicate-guard.test.ts: 10 passed;
  • rest list-view-grouping-query-door.test.ts: 33 passed, with the objectql dist rebuilt and rest's dependency closure built.
• The real-driver measurement of §1, repeated at head: every one of the 20 rows is refused on having on both drivers and both doors, and the six controls give byte-identical output to the base.

Ablation. The one gate line was replaced through scripts/ablation-replace.mjs:

• the anchor hit once, and the blob moved 7830b0cee3 → 380a8f6fd9;
• grep -c read the anchor 1 → 0 and the marker 0 → 1;
• an EXIT/INT/TERM trap restored the file with git checkout HEAD --, proven by the HEAD blob-hash match and an empty git diff HEAD.

The test imports ./engine.js from source, so no dist/ is on the resolution path and there was nothing to preflight. 24 red, 18 green, as expected:

• red: all 20 parity rows, the 3 shared-table door-refusal rows, and the empty-set pin;
• green: the 10 pass-through controls, the $ne pin that follows the face, the 2 partition checks, and the 5 existing having tests.

Gates. dispatch-gates --commands --repo objectstack-ai/objectstack, re-derived at head, printed 64 families. --ran reconciled them: 64 derived, 62 run with exit 0, 2 NOT MEASURED, 0 UNRUN.

• NOT MEASURED: check:dual-build-cjs-loads and check:type-check-debt, both exit 3 PREREQUISITE NOT MET. Both need the whole workspace built; CI runs them.
• check:query-options-erasure went red once on an earlier head, at 236 → 243 test sites, from as any casts in the new test. The options are typed now, and the off-contract bags are cast through unknown to EngineAggregateOptions. It holds at 236.
• node scripts/check-issue-citations.mjs --base 9b8c74c6c5: ✅ every citation this change adds resolves.

Lint, a declared narrowing (pnpm lint is CI's). eslint --no-inline-config --format json was run over the two changed .ts files:

• population: eslint --print-config returns a config for each file, so neither is ignored;
• count: 2 files, 0 errors, 0 warnings;
• invariance: eslint.config.mjs sets no parserOptions.project and no typed rule, so no rule is type-aware, and this diff cannot move a verdict on any untouched file.

7. Compile surfaces, face by face

This card is the having half-face.

face	conclusion
1 driver-sql (and driver-sqlite-wasm, local driver-turso)	not reached by having: no driver reads the clause, and the engine evaluates it after aggregation. Unchanged
2 turso RemoteTransport	not reached by having. Unchanged
3 read-scope-sql	not reached by having. Unchanged
4 analytics filter-normalizer	not reached by having; analytics sends no having to the engine. Unchanged
5 formula	not reached by having. Unchanged
half-face objectql having-filter	changed: behind the shared comparand-shape face on both applyHaving doors, with a where/having parity table and a leg driven from FILTER_COMPARAND_TYPE_CASES
driver-memory / driver-mongodb	not reached by having. Unchanged

compile-surfaces.md is governed (.claude/**), so it is not edited here. The row it should gain is in the report on #19974, and the seat routes it.

Acceptance notes

Observed and not fixed here. The report carries each one.

Four of them are reproducible defects, handed to the seat to file. All four were measured at head on driver-memory:

1. having resolves no { $field } reference.
   • Example: having: { total: { $gt: { $field: 'max_cap' } } } keeps no group, where c1 (500 against 50) should pass.
   • The face's { $field } $between refusal, which having now shows, suggests the two-bound { $field } spelling. having answers that spelling wrong, silently.
   • The changeset says so instead of prescribing it.
2. The comparand-TYPE door is not run on having. having: { total: { $eq: { v: 1 } } } answers 200 with no group, where the same shape in where is INVALID_FILTER / 400.
3. The FilterArray sugar in having answers no group. having: [['total', '>', 100]] gives 200 with no group, where where lowers the same sugar and answers c1, c2.
4. having's own walker refusals depend on the data. having: { total: { $median: 1 } } and an empty $icontains are refused on a populated grouped set, and answer 200 with no group on an empty one.

Noted only, not filed:

• $ne with an array still answers on having. [finding] $ne with an array comparand splits across backends: driver-sql and driver-memory refuse (400), driver-mongodb answers, formula matches every row — and both shared faces pass it #19886 remains open and carries it; see §4.
• The ADR-0087 entry filter-equality-array-comparand-refused lists the doors that refuse the shape "at this release", and having is not among them. The entry is in packages/spec, outside this claim. Carrier: none.
• having-filter.ts's header still calls HAVING "the only face no conformance table covers". That is still true of the logic axis. The comparand-shape axis now has one. The file is not edited, to keep the claim. Carrier: none.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 17 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json a8bcce69c83141b83b2d10724b428cd82f8aabd0 → packageMentionDocs.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 5649560428dd67bb919b5e0b5775d3f2994ce79f

Scope: 3 files (+400/−0) on merge base 9b8c74c6c5: engine.ts (+24), the new pin engine-aggregate-having-comparand-shape.test.ts (+346), and the changeset (+30). packages/spec is untouched, and having-filter.ts is byte-identical at base and head. No governed surface is touched. Review is owed for the .changeset prose.

Read: card #19974 and its comments, ruling 乙 on #19757 (5793368540), PR #19882 and its record 5808368753, the PR body, the diff, all 34 check-runs, AGENTS.md, contract-review.md, compile-surfaces.md, execution-duties.md, and the code at head.

main is 13 commits past the base, none touching this PR's files or the face files, and merge-tree is clean. Measured through the public engine.aggregate on a real InMemoryDriver and SqliteWasmDriver, on both applyHaving doors (native driver.aggregate(), and the fallback forced by a per-aggregation filter), each shape run as where and as having, 364 cells per tree. Base was measured with engine.ts at the base blob 277a986d82, and head with engine.ts restored by blob to 7830b0cee3, with a clean git status.

① Derived judgments

• Refused-set parity: RIGHT. 25 face shapes (the PR's 20 rows plus 5 more spellings of the same arms) × 2 drivers × 2 doors = 100 having cells.
  • Base: 0/100 refused. For example, { total: [500] } kept c1, $nin: 'c1' kept every group, and $lt: null kept none.
  • Head: 100/100 refused. The same shapes as where are 100/100 refused at base and at head.
  • At head, every having message equals the where message with where. replaced by having., with the same code and status: 0 mismatches.
  • The 20 rows reach every arm and operator spelling of the face (filter-comparand-shape.ts, nine refusal arms), so the table is the face's full refused set.
• Nothing outside the face started refusing: RIGHT. 41 non-face controls × 4 = 164 cells, 0 changed from base to head. They include scalars, $eq: null, $ne scalar and array, $in / $nin lists including [], a two-bound $between, { $field } whole comparands, $exists, text operators, combinators and FilterArray sugar. The refused control cells are the walker's own pre-existing refusals and are byte-identical at base.
• The gate runs once, ahead of the driver, the middleware chain and both doors: RIGHT.
  • assertListComparandShapes( has 2 sites at base and 3 at head, the new one on query.having. It precedes getDriver, the opCtx build and executeWithMiddleware.
  • applyHaving has exactly 2 call sites, the native door and the fallback.
  • The driver call count on every having refusal at head is 0 (aggregate and find), 100/100.
• The error: RIGHT.
  • On every face refusal the error's own keys are exactly code,status (INVALID_FILTER / 400).
  • No policy disclosure is possible: the gate judges the caller's own having before the middleware chain, no source assigns .having =, and plugin-security only reads ast.having.
• The pins: RIGHT.
  • At head the new file passes 37/37 and engine-aggregate-having.test.ts 5/5.
  • With engine.ts at the base blob: 24 failed / 18 passed. The red set is exactly the 20 parity rows, the 3 comparand-type shape rows and the empty-grouped-set pin.
  • Every refusal asserts code and status.
• Compile surfaces, face by face: declared correctly. The objectql having-filter half-face is CHANGED, behind the shared face on both doors. driver-sql (with driver-sqlite-wasm and local driver-turso), the turso RemoteTransport, read-scope-sql, filter-normalizer, formula, driver-memory and driver-mongodb carry no having token in non-test source and are unchanged. The PR body's §7 table matches.
• CI at this head: 34 runs, 31 success, 3 skipped, 0 failures, and all seven required contexts are success, Check Changeset included.

② Semver level

@objectstack/objectql: minor, fix(objectql)!:, one **BREAKING** banner, Clause-②: no (narrowing): CORRECT.

• An accept-set narrowing is BREAKING and ships minor in the launch window.
• The body carries the FROM → TO table a breaking changeset owes.
• ADR-0087 disposition not-required (already-registered …): all three ids resolve and predate the base. Each registers a data.FilterCondition transition at the shared face with the same FROM shape and prescription, and having is typed FilterConditionSchema, so no FROM → TO the ledger lacks is introduced.

③ Boundary flags

• Changeset: TRUE, except two table cells.
  • The last row's cell, "a { $field } reference in any having slot is compared as a value and keeps no group", is FALSE. It holds for the operator slots ($eq, ordering), but in the implicit slot { total: { $field: 'order_count' } } is REFUSED by the walker as an unsupported operator (INVALID_FILTER / 400).
  • The first row's "kept the 500 group … at any depth under $and / $or / $not" is inexact: under $not it kept the complement (c2, c3).
  • "Callers of engine.aggregate … in a deployment were NOT measured" is declared, and consistent.
• PR body: TRUE where measured. The §4 sentence on $ne with an array on where, the full-suite counts and the gate-family counts are UNMEASURED here (CI carries them).
• The dev's four out-of-scope defects are REAL (three reproduced here). They are already filed as one class, objectql having does not take the rest of where's filter doors: a $field reference is never resolved, the comparand-TYPE door does not run, FilterArray sugar answers no group, and its own refusals fire only on a non-empty grouped set #20099.
• Stale published prose, outside this claim: the ADR-0087 entry 18.filter-equality-array-comparand-refused.ts reason lists the doors that refuse at this release without having. That is dated wording, not false. A spec docs-only carrier is the fix.
• compile-surfaces.md (governed) is correctly not edited. The dev's proposed row checks out against the head line numbers, and the seat routes it.
• Pre-existing, not this PR's: face refusals carry code and status only, while objectql's own walker refusals also carry httpStatus.

Implemented-by: claude/issue-19974-having-array-equality
Reviewed-by: session_01Bvd69VPa6puiNzzPUroDBx

VERDICT: PASS

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 1a47a60ba263b4d629adc13b69f4fadd84568dd8

Scope: the delta over PASS 5826694842 (at 5649560428), after the seat's patch round on two changeset table cells.

Measured through the public engine.aggregate on a real InMemoryDriver and SqliteWasmDriver, on both applyHaving doors (native and fallback, each confirmed by driver call counters), with groups totalling 500, 1250 and 20. That is 20 shapes × 2 drivers × 2 doors = 80 cells per tree. Base was measured with engine.ts at blob 277a986d82, then restored by blob to 7830b0cee3 with a clean git status.

① Derived judgments

• The delta is one commit and one file: RIGHT. 5649560428..1a47a60ba2 is .changeset/19974-having-comparand-shape-face.md only, +2/−2, the two cells. engine.ts and having-filter.ts are byte-identical to the reviewed head. The <!-- adr-0087: … --> marker is byte-identical.
• Row 1, every sentence TRUE at base:
  • { total: [500] } and { total: { $eq: [500] } }, also under $and and $or, kept c1 (the 500 group) in 16/16 cells;
  • under $not, at depth 1 and 2, they kept the complement c2, c3 (the 1250 and 20 groups) in 16/16 cells.
  • At head all eight shapes are refused INVALID_FILTER / 400 with 0 driver calls (32/32).
• Row 8, every sentence TRUE at head:
  • under $eq, $gt, $gte, $lt or $lte, a { $field } reference keeps no group (20/20);
  • under $ne it keeps every group (4/4);
  • in the implicit slot it is refused as an unsupported operator, INVALID_FILTER / 400, on a populated set (4/4);
  • on a missing column, or on an empty grouped set, it comes back [] (4/4 each). The value === undefined exit in having-filter.ts sits before the operator switch whose default: refuses;
  • "That gap is not changed here": all 36 { $field } cells are identical at base and head.
• The face text the cell quotes is real: fieldReferenceRangeBoundError prescribes the two-bound { $field } spelling, and having answers both bounds [].
• CI at this head: 34 runs, 31 success, 3 skipped, 0 failures, 0 pending. All seven required contexts are success, and Check Changeset is success.

The judgments of PASS 5826694842 stand for everything outside this delta.

② Semver level

The delta moves no frontmatter, banner, Clause-② line or ADR-0087 disposition. minor, fix(objectql)!:, BREAKING and Clause-②: no (narrowing) stand, CORRECT as recorded.

③ Boundary flags

• The two cells PASS 5826694842 found inexact are now TRUE, every sentence measured on both drivers and both doors.
• No new flags. The prior record's other ③ items stand as written: objectql having does not take the rest of where's filter doors: a $field reference is never resolved, the comparand-TYPE door does not run, FilterArray sugar answers no group, and its own refusals fire only on a non-empty grouped set #20099, the dated ADR-0087 entry reason, compile-surfaces.md routed by the seat, and the pre-existing httpStatus asymmetry.

Implemented-by: claude/issue-19974-having-array-equality
Reviewed-by: session_01Bvd69VPa6puiNzzPUroDBx

VERDICT: PASS