fix(service-analytics): both filter faces answer $empty by the field's declared type (#20445)

[objectstack-fleet]

Fixes #20445

Clause-②: yes (widening)

The domain:services lane's arms for the $empty operator, under ruling A on #20399 (5865693155). Both service-analytics filter faces now answer { f: { $empty: true | false } } by the field's DECLARED row of the ruled per-type table. They reach it through the spec's one expansion, expandEmptyOperator(fieldDef) from @objectstack/spec/data (PR #20442), and keep no copy of the table:

declared row	$empty: true matches	$empty: false
text-like	null or ''	the complement
multi-value (incl. multiple: true on a multi-capable type)	null or []	the complement
every other type	null only	the complement

The staging does not move (「照 $like 先例分阶段」): $empty is not added to FILTER_OPERATORS, and the is_empty / is_not_empty lowering still emits $null. There is no $eq: [] comparand anywhere (ruling 乙 on #19757 stands).

What changed

• empty-operator-sql.ts (new). The SQL for one $empty predicate per declared row. Null-only: col IS NULL. Text: (col IS NULL OR col = ''), with the empty string bound. Multi-value: (col IS NULL OR L), where L is the dialect's empty-JSON-list test: SQLite json_valid guard inside a CASE, then json_type(col) = 'array' AND json_array_length(col) = 0; Postgres a jsonb equality with '[]'; MySQL JSON_TYPE = 'ARRAY' and JSON_LENGTH = 0. $empty: false is the exact complement of each. Every predicate is TOTAL (never UNKNOWN), so a $not over $empty needs no NULL guard.
• Read-scope face (compileScopedFilterToSql). A new $empty arm in compileOperator. It asks the caller for the field's declaration (new optional declaredValueShape option; both callers pass it from the context), calls expandEmptyOperator, and compiles the row. The flag joins the existing boolean-domain gate with $null / $exists. Both NULL-polarity tables gain the row (null satisfies $empty: true; the arm is total).
• where face (lowerAnalyticsWhere / normalizeAnalyticsFilterTree). fieldLeaves stops refusing $empty and lowers it to a valueless empty / notEmpty leaf. The normalizer sees no field declaration, and the multi-value row cannot be spelled in the lowered vocabulary, so the row is resolved by each consumer of the tree:
  • NativeSQLStrategy.buildFilterClause (the executed statement) and the ObjectQLStrategy echo both call whereEmptyLeafSql: the host's declared shape, then the spec's expansion, then the row's SQL.
  • ObjectQLStrategy.convertFilter (the engine path) hands { $empty } to the engine as written. Its arm is the engine lane's (filter: the engine's compile surfaces answer $empty by the field's declared type (driver-sql and heirs, turso remote, driver-memory, driver-mongodb, formula, objectql having) — ruling A on #20399 #20444).
  • The flag joins assertBooleanNullFlags with $null / $exists. Both polarity tables gain the row.
• Where the declaration comes from. A new context hook, DatasetScopedStrategyContext.declaredValueShape(object, field). AnalyticsService answers it from the existing sourceFieldMeta hook (type, and now multiple). AnalyticsServicePlugin relays multiple from the field definition.

The field's declaration is never guessed. A face that cannot name it refuses, before anything binds. On the where face that is INVALID_FILTER / 400; on the read-scope face it is READ_SCOPE_COMPILE_FAILED / 500. The same holds for a multi-value field on the 'unknown' dialect, where no JSON test parses everywhere; the text and null-only rows need no dialect. Why a guess is not possible: the "no declaration" reading the spec gives the JS faces (null, '' and [] all empty) has no SQL form without the type. amount = '' is a type error on Postgres, and an empty list is only recognisable as JSON. Both refusals are pinned with code + status.

The question the card asked: should the read-scope face answer an unknown operator with 400?

No. It keeps READ_SCOPE_COMPILE_FAILED / 500 with the message withheld, and this PR says so in code at compileOperator's default: arm. The triage reading ("an authoring mistake answered as a server error is the wrong class") assumes the caller authored the input. Measured, the caller does not:

• Who writes what reaches compileScopedFilterToSql. Its only two in-package callers are NativeSQLStrategy.applyReadScope and the ObjectQLStrategy.generateSql echo. Both pass ctx.getReadScope(object). AnalyticsServicePlugin answers that hook either from the security service's getReadFilter, which compiles admin-authored sharing rules and permission sets, or from the host's own getReadScope plugin option. The analytics caller's own filter takes the other road, filter-normalizer.ts, and that road answers INVALID_FILTER / 400 for an unknown operator.
• The ruling already on file. The read-scope module header records the analytics dataset 路由的 message 正则兜底没有退休时间表:六族拒收仍靠措辞分类,改一个字就换一个 HTTP 码 #5367 maintainer ruling (2026-08-06, re-affirmed as [spec] service-analytics' read-scope / Cube filter compilers still refuse $field, so a CEL field-to-field RLS rule 400s on those faces #7598 Q2 = A). A read-scope refusal is a server fault: a 400 "told them to fix a request that was never the problem, and hid the fault from the 5xx alerting". A 4xx body also relayed "THE FIELD NAMES AND COMPARANDS OF THE RLS POLICY". The header states that the envelope "is not to be rewritten". security: the analytics ObjectQL execute face answers a row-level read scope it cannot run with INVALID_FILTER / 400 whose message echoes the policy's field name and comparands — the disclosure #5367 closed for the native / echo faces #19995 (60fdaa9e, PR fix(service-analytics): the ObjectQL face refuses a read scope carrying a placeholder the engine cannot resolve in the withheld READ_SCOPE_COMPILE_FAILED / 500 envelope (#19995) #20072) extended the same withheld 500 to the ObjectQL engine door for exactly that disclosure reason.
• Pinned: $bogus in a read scope still answers READ_SCOPE_COMPILE_FAILED / 500 (read-scope-empty-operator.test.ts, last case). The existing envelope suites stay green unchanged.

Filter-semantics compile-surface declaration

Roster re-grepped on fc0db22b (grep -rn 'matchesFilterCondition\|buildWhereSQL\|compileScopedFilterToSql' packages --include=*.ts).

#	face	conclusion
1	driver-sql applyFilterCondition (and its extends SqlDriver heirs)	out of scope: sibling #20444 (domain:engine). Measured today: it refuses $empty with INVALID_FILTER / 400, operator and field withheld. Untouched here.
2	turso RemoteTransport buildWhereSQL	out of scope: sibling #20444. Untouched.
3	service-analytics read-scope-sql compileScopedFilterToSql	changed: the $empty arm above, and the boolean gate.
4	service-analytics filter-normalizer lowerAnalyticsWhere / normalizeAnalyticsFilterTree	changed: the empty / notEmpty leaf, answered by NativeSQL and the ObjectQL echo, and handed to the engine by ObjectQL execute.
5	formula matchesFilterCondition	out of scope: sibling #20444. Untouched.
half-face	objectql having-filter (applyHaving / matchesHaving)	out of scope: sibling #20444. Untouched.
unfrozen	driver-memory checkCondition, driver-mongodb translateFieldOperators	out of scope: sibling #20444. Untouched.

Two package-local consumers of face 4's tree, named so they don't read as missed:

• ObjectQL execute. It hands { $empty } to the engine. Until filter: the engine's compile surfaces answer $empty by the field's declared type (driver-sql and heirs, turso remote, driver-memory, driver-mongodb, formula, objectql having) — ruling A on #20399 #20444's driver-sql arm lands, the engine refuses it, so this query is refused on this strategy, while the echo prints the declared arm and the native statement answers it. No face drops it.
• Draft preview (preview-evaluator.ts). Unchanged. It already refuses $empty (INVALID_FILTER / 400) with its other unevaluated operators, $null among them.

Evidence (HEAD 6a07f8cc; the suite ran at 20994c10, and HEAD adds only the changeset on top of it)

• Premise, re-measured on fc0db22b before editing. lowerAnalyticsWhere passed { f: { $empty: true } } through, and normalizeAnalyticsFilterTree refused it INVALID_FILTER / 400. compileScopedFilterToSql refused it READ_SCOPE_COMPILE_FAILED / 500, and $bogus got the same answer. git grep -c '$empty' over service-analytics/src read 0 hits; the control word $null read 10+ files.
• New pins.
  • read-scope-empty-operator.test.ts: 31 tests, executed on sql.js.
  • where-empty-operator.test.ts: 27 tests. NativeSQL executes on sql.js, the ObjectQL echo runs on the same database and must return the same rows, and the condition handed to the engine is pinned.
  • Fixture: a text, a tags, a lookup with multiple: true, a select and a number field. Rows: null, '', [], a non-list JSON value, and a value.
  • Covered: $empty: false as the complement; nesting under $and / $or / $not; beside another operator on the same field. Refusals assert code + status.
  • Postgres / MySQL SQL strings are pinned as compiled, NOT MEASURED as executed: there is no live server here.
• Package suite. pnpm --filter @objectstack/service-analytics exec vitest run --maxWorkers=2: Test Files 134 passed (134) · Tests 3151 passed (3151).
• Typecheck. pnpm --filter @objectstack/service-analytics exec tsc --noEmit --listFiles exits 0, and its file list contains all three new files.
• Gates. node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derived 62 commands; all 62 ran. --ran reconciliation: "62 derived famil(ies) accounted for — 60 run, 2 NOT-MEASURED".
  • NOT MEASURED: check:dual-build-cjs-loads and check:type-check-debt. Both exit 3 with PREREQUISITE NOT MET, because they need the whole workspace built. Narrowed probe instead: this package's built dist/index.cjs and dist/index.js both load and export compileScopedFilterToSql.
• Lint, narrowed.
  • Population: eslint.config.mjs lints packages/**/*.{ts,tsx,mts,cts} with no type-aware parsing (no parserOptions.project). A verdict on an untouched file therefore cannot move with this diff.
  • pnpm exec eslint --no-inline-config --format json over the 10 changed .ts files: the JSON has 10 file entries, 0 errors, 0 warnings.

Ablation: the negative pins can fail

Committed first; each leg ran through scripts/ablation-replace.mjs, which applies the mutation, runs, and restores. Restore was proven blob == HEAD (05d539c76470) with git diff HEAD empty.

• A1: the null-only row counts ''. The null_only arm falls through to the text arm. 9 red across both files, including "the null-only row does NOT count the empty string": AssertionError: expected [ 'n', 's' ] to not include 's'.
• A2: $empty: false stops being the complement. The text arm's false branch becomes an OR. 7 red, including "name: $empty: false is the exact complement": expected [ 'l', 'o', 's', 'v' ] to deeply equal [ 'l', 'o', 'v' ].

Acceptance notes (observations, not filed)

• The spec's staging prose goes stale here. The FILTER_OPERATORS TSDoc table in packages/spec/src/data/filter.zod.ts still lists both service-analytics rows as REFUSES. Carrier: the flip card, which rewrites that table. No packages/spec edit here.
• Shared conformance cases belong in the spec. A shared $empty conformance table (per-type rows × stored states, the way FILTER_LOGIC_CASES works) would let every face run one standard. That is the spec lane's to add, with the flip card, and is not added here.
• The flip card will need $empty rows in objectql-echo-operator-coverage.test.ts (OPERATOR_CASES) and objectql-icontains-arm.test.ts (SAMPLES). Both assert their tables equal FILTER_OPERATORS, so they go red on the flip until the rows exist.
• A read scope carrying $empty on the ObjectQL execute face is refused by the engine's driver as INVALID_FILTER / 400 with the operator and field withheld, not the read-scope 500. judgeFilter admits the operator because it stops before the driver. This predates the PR and closes when filter: the engine's compile surfaces answer $empty by the field's declared type (driver-sql and heirs, turso remote, driver-memory, driver-mongodb, formula, objectql having) — ruling A on #20399 #20444 lands the driver arm. No in-repo producer emits $empty in a read scope (the CEL lowering's is_empty emits $null).

Seat append (domain:services seat #6021, session_017B6YKCGu8CTY2KBWgwaHAs)

• The Clause-② line changed from no to yes (widening), per contract review FAIL 5876996555. The PR adds two published members, multiple? on AnalyticsServiceConfig.sourceFieldMeta's return shape and declaredValueShape? on compileScopedFilterToSql's options. The changeset moves to minor in the patch round on this PR.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-analytics, touching 34 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/plugins/packages.mdx (via AnalyticsServicePlugin (symbol, a top-level class))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v14.mdx (via generateSql (symbol, a method of class ObjectQLStrategy))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 9 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• 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 — 9 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 9bf5e67affab69ce740037f33b003f5faf45d205 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 42cf8389c22991a0bc417f213f399b09e3247245 — the merge of head 611daa435f9947e1e13cb85b8b4121a8a4123e76 into base 9bf5e67affab69ce740037f33b003f5faf45d205, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 42cf8389c22991a0bc417f213f399b09e3247245 && git checkout 42cf8389c22991a0bc417f213f399b09e3247245
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 9bf5e67affab69ce740037f33b003f5faf45d205 611daa435f9947e1e13cb85b8b4121a8a4123e76 && git checkout -B drift-repro 9bf5e67affab69ce740037f33b003f5faf45d205 && git merge --no-ff 611daa435f9947e1e13cb85b8b4121a8a4123e76

node scripts/docs-audit/affected-docs.mjs --json 9bf5e67affab69ce740037f33b003f5faf45d205

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 9bf5e67affab69ce740037f33b003f5faf45d205 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 6a07f8ccbd7a68757cae7bebb37e41c32be1aa8a
Local-runs: none

Inputs read: card #20445 (body and all 5 comments, the claim 5875970963 and the ACCEPT 5876774357 included), PR #20498 (body, 11-file list, net diff against main at 45f428d, the PR's base), file contents at the head and on origin/main, and the head's check-runs (read 2026-09-28T19:25Z: 34 names, 31 success, 3 skipped, 0 failure, 0 in progress). Nothing was built, run or re-run.

① Derived judgments

The spec as it stands on main, which every judgment below is read against: FieldOperatorsSchema and SpecialOperatorSchema (packages/spec/src/data/filter.zod.ts) declare $empty: z.boolean() whose describe() IS the ruled per-type table (ruling B on #20311, spelled by ruling A on #20399) and says in its own text "STAGED: declared ahead of its backends and absent from FILTER_OPERATORS. Until each face has its arm, the query executors refuse it"; filter-empty-operator.ts exports the one expansion (expandEmptyOperator, EMPTY_OPERATOR_ARMS); FILTER_OPERATORS deliberately omits $empty (「照 $like 先例分阶段」) and its docblock's "no face answers it yet" table lists both service-analytics rows as REFUSES with the flip card as the closer.

1. Accept set, the where face (POST /api/v1/analytics/query, /analytics/sql, dataset filters). $empty: true | false is lowered to a valueless empty / notEmpty leaf and answered by the field's declared row; before the diff normalizeAnalyticsFilterTree refused it INVALID_FILTER / 400. Reading: a runtime face honouring an already-declared key, not a widening of a published accept set. RIGHT. The key, its boolean domain and its per-type meaning are all published by the spec on main; the refusal the diff removes is the spec's own stated interim ("until each face has its arm"), and ruling A orders exactly one arm per compile surface. Absence from FILTER_OPERATORS is the staging mechanism for driver-memory's gate, not this package's accept set, and the $like precedent (Filter AST: like is folded to $contains at the wire — wildcards bind as literals and driver-sql's like/ilike arm is unreachable #7536) landed per-face arms ahead of that array the same way. Under execution-duties ("条款②只指已发布契约面,拉回已声明契约不触它") this arm on its own reads no.
2. Accept set, the read-scope compiler (compileScopedFilterToSql). $empty now compiles; before the diff it fell into the default: arm as an unsupported operator, READ_SCOPE_COMPILE_FAILED / 500. Same reading as 1: RIGHT. The default: arm itself is unchanged (500, message withheld) and pinned with $bogus — right under the analytics dataset 路由的 message 正则兜底没有退休时间表:六族拒收仍靠措辞分类,改一个字就换一个 HTTP 码 #5367 ruling the module header records (re-affirmed [spec] service-analytics' read-scope / Cube filter compilers still refuse $field, so a CEL field-to-field RLS rule 400s on those faces #7598 Q2 = A, extended by security: the analytics ObjectQL execute face answers a row-level read scope it cannot run with INVALID_FILTER / 400 whose message echoes the policy's field name and comparands — the disclosure #5367 closed for the native / echo faces #19995): the scope is ctx.getReadScope(object) output (the security service's compiled sharing rules or the host's getReadScope option), never the query caller's input. This is the card's named question, answered in code and in the PR, not changed silently.
3. Boolean-domain gate. $empty joins $null / $exists in both faces' non-boolean refusal (assertBooleanFlagComparands, assertBooleanNullFlags) and in assertDefinedComparands' skip list, so an undefined flag still reaches the boolean gate. A narrowing relative to reading === true on anything, matching z.boolean(). RIGHT, pinned on both faces including under $not.
4. RLS over-admission audit — can any arm make a read scope admit MORE rows than its declared semantics (a dropped or TRUE-reading predicate), on every strategy and dialect the diff compiles for?
   • null_only: col IS NULL / col IS NOT NULL. Total.
   • text: (col IS NULL OR col = '') and its complement (IS NOT NULL AND not-equal ''), the '' bound, dialect-free. Total.
   • multi_value: (col IS NULL OR L) / (col IS NOT NULL AND NOT L). SQLite: L is a CASE guarded by json_valid with ELSE 0, so a malformed text, '', or a non-array JSON value reads FALSE, never NULL, never TRUE. Postgres: jsonb equality with '[]' — TRUE/FALSE for any JSON value; a malformed text column errors (a database error, fail-closed) rather than reading TRUE. MySQL: JSON_TYPE = 'ARRAY' AND JSON_LENGTH = 0 — same. Unknown dialect: L has no construct, the compiler answers null and BOTH callers refuse (whereEmptyLeafSql throws INVALID_FILTER / 400; compileEmptyOperator throws READ_SCOPE_COMPILE_FAILED / 500) — null is never read as "no constraint".
   • NULL column: TRUE OR x / FALSE AND x, so both polarities are total; operatorIsNullTotal('$empty') = true is therefore exact and NOT (…) is the exact complement; nullValueSatisfiesOperator('$empty') = (value === true) is right (null is empty on every row).
   • No declaration for the field, or no hook at all (a caller of the exported compiler that passes no declaredValueShape, a bare spec StrategyContext): refused before anything binds, params stays aligned — the same refusal class as before the diff.
   • Every consumer of the lowered tree on the head, enumerated by reading: NativeSQLStrategy.buildFilterClause compiles the leaf BEFORE its values.length === 0 drop; ObjectQLStrategy.buildFilterClauseSql (the echo) the same, via the same function; ObjectQLStrategy.convertFilter hands { $empty: true | false } to the engine verbatim, and every engine driver refuses it loudly per the spec's measured table (driver-sql measured by the dev today; driver-memory's Unsupported filter operator; driver-mongodb). No fourth walker reads operator. Nothing drops, nothing reads TRUE.
     Verdict on the RLS question: no arm admits more rows than the declared semantics on any strategy or dialect this diff compiles for. RIGHT. One host-composition residue is in ③.6.
5. Public surface, symbol by symbol, against the package's exports map (only .) and src/index.ts on the head:
   • StrategyContext — UNTOUCHED. It is the spec's interface (packages/spec/src/contracts/analytics-service.ts:265), re-exported unchanged. The brief's premise that the diff adds declaredValueShape? to it is not what the diff does; the member is added to DatasetScopedStrategyContext (strategies/types.ts).
   • DatasetScopedStrategyContext.declaredValueShape? — NOT PUBLISHED, no trigger. RIGHT. The entry re-exports only AnalyticsStrategy, StrategyContext, AnalyticsDriverCapabilities from ./strategies/types.js; the interface's only typed uses are AnalyticsService's private baseCtx field and private callCtx method (private members are emitted typeless), and the strategies cast to it internally while their public methods take the spec's StrategyContext. Under contract-review.md ("从入口类型图不可达、且 exports 不可寻址的 .d.ts 是出货字节,⛔ 不是已发布接受集") it is shipped bytes. The same holds for empty-operator-sql.ts's exports (declaredValueShapeResolver, emptyOperatorPredicateSql, whereEmptyLeafSql, EmptyOperatorSqlRequest): package-internal, unreachable from the entry.
   • AnalyticsServiceConfig.sourceFieldMeta — PUBLISHED and WIDENED. AnalyticsServiceConfig is exported by name from the entry (export type { AnalyticsServiceConfig }). The hook's return shape gains multiple?: boolean, a key a host may now write and that the runtime now reads (AnalyticsService.declaredValueShape, AnalyticsServicePlugin relays it). Before the diff a contextually-typed return literal carrying multiple was an excess-property error; after it, it is the way a host declares a list-valued field. The public surface grows by one authorable member. The claim of no is WRONG on this symbol.
   • compileScopedFilterToSql — PUBLISHED and WIDENED. Exported by name; its third parameter is ReadScopeCompileOptions, reachable from the entry type graph through that signature, and it gains declaredValueShape?. The accept set of an exported function grows by one option. WRONG on this symbol too. The changeset's own prose names both under "Host API".
   • AnalyticsServicePluginOptions — unchanged (plugin.ts changes the hook body only). NativeSQLStrategy / ObjectQLStrategy public signatures — unchanged. FILTER_OPERATORS, the is_empty / is_not_empty lowering, packages/spec — untouched; the staging is honoured. RIGHT.
   • The mechanical tell family (T1–T4, check-widening-tells.mjs) polices packages/spec shapes and the spec api-surface only, and the live --pair sweep is retired, so nothing mechanical would have flagged these two members: this seat-level reading is the live control the rules name for the direction claim.
6. Prose. The where face's unsupported-operator refusal now lists $empty among the supported names; the read-scope non-boolean refusal names three flags. Consistent with the arms. RIGHT.

② Semver level

• Declared: .changeset/20445-analytics-empty-operator-arms.md front matter '@objectstack/service-analytics': patch, its body, the PR body (line 3) and the claim 5875970963 all carry the line Clause-②: no.
• Ruling: WRONG. The runtime $empty behaviour alone would have read no (①.1–2), but the diff also adds two entry-reachable published members (①.5): multiple? on AnalyticsServiceConfig.sourceFieldMeta's return shape and declaredValueShape? on compileScopedFilterToSql's options. Rules that decide it: AGENTS.md Post-Task Checklist — the declaration is yes|no plus at most one arm from the closed pair, and "yes takes at least minor"; execution-duties — the criterion is "本卡放宽接受集或扩大公开面吗"; lanes/spec.md — "放宽接受集或扩大公开面的卡,不论多小,即条款②" and "公开导出面增删" is one of the five contract-surface shapes; contract-review.md — the published surface is judged by the package's exports map, and both members are reachable from .. Landing-operations names a wrong no an auditable false declaration ("错误的 no 是可审计的假申报"), which is why this is FAIL and not a note.
• Precedent in this very package: CHANGELOG 17.4.0 "Minor Changes" carries 54bb2f1 (new optional AnalyticsServiceConfig.sqlDialect, service-analytics: all three SQL compilers emit a plain LIKE for the case-sensitive $contains family, which folds ASCII case on SQLite — the read scope and the native where admit rows the #4706 contract excludes #15684) and a646120 (new optional nonTextColumn on compileScopedFilterToSql's options, driver-memory's reference matcher answers $notContains NO for every valued NON-STRING row — the live mingo path answers YES #14079) — the identical two shapes, leveled minor.
• Exact correction (one patch round):
  1. changeset front matter → '@objectstack/service-analytics': minor;
  2. the Clause-② line on all three carriers — the changeset body, the PR body's line-start line, and the claim comment (corrected by the seat, as the ACCEPT record already provides) — → yes (widening), arm (widening) from the closed pair;
  3. nothing else: not breaking, so no ADR-0087 marker; no skip-changeset; no spec edit; no api-surface baseline (this package carries none); the fix: title may stay — the level follows the published-surface delta, not the verb.

③ Boundary flags

1. deviations[0] — file surface beyond the claim's two faces (six more service-analytics files). Answered, RIGHT to extend: the where face's leaf has three consumers and an unhandled leaf answers null = no clause = TRUE, the exact widening the RLS note asks about; the declared-shape channel (multiple) did not exist. The claim's prohibited items (packages/spec, FILTER_OPERATORS, the lowering flip) are untouched and the ACCEPT amends the surface on record. No escalation.
2. deviations[1] / open_questions[0] — ObjectQL echo renders the declared $empty arm while ObjectQL execute is refused by the engine until filter: the engine's compile surfaces answer $empty by the field's declared type (driver-sql and heirs, turso remote, driver-memory, driver-mongodb, formula, objectql having) — ruling A on #20399 #20444. The seat answered A. Concur: no row is served wrong (execute refuses INVALID_FILTER / 400 loudly, measured on driver-sql; the spec's table has every engine driver refusing), and under B the divergence would outlive filter: the engine's compile surfaces answer $empty by the field's declared type (driver-sql and heirs, turso remote, driver-memory, driver-mongodb, formula, objectql having) — ruling A on #20399 #20444 with nothing turning red to prompt the flip. The window closes when the sibling lands; the carrier is already knocked to filter: the engine's compile surfaces answer $empty by the field's declared type (driver-sql and heirs, turso remote, driver-memory, driver-mongodb, formula, objectql having) — ruling A on #20399 #20444. No escalation.
3. deviations[2] — attribution trailer choice. No contract bearing; not judged here.
4. The card's 400-vs-500 question (read-scope unknown operator). Stated in code at compileOperator's default: arm and in the PR: 500 kept. RIGHT: an accepted ruling binds until superseded (Prime Directive [WIP] Add Chinese version of the documentation #13); analytics dataset 路由的 message 正则兜底没有退休时间表:六族拒收仍靠措辞分类,改一个字就换一个 HTTP 码 #5367 closed 400 on this face for misattribution and policy disclosure, and the triage reading's premise ("the caller authored it") does not hold here — the scope's producer is the security service or the host's getReadScope. Pinned with $bogus. No escalation.
5. NOT MEASURED — Postgres / MySQL execution of the multi-value arm (compiled strings pinned only; no live analytics job). Stated honestly. Read here (①.4): neither string can read TRUE for a non-empty value; the failure mode on malformed storage is a database error, fail-closed. One dialect note, not new to this diff: the text arm's bound '' inherits MySQL's PAD SPACE equality on collations that have it, exactly as $eq: '' already does there. Accepted as a stated gap. No escalation.
6. Residual population (this review's, not a dev flag). A host whose sourceFieldMeta answers type without multiple has a multi-capable field declared multiple: true (select / radio / lookup / user / file / image) read as null-only, so { f: { $empty: false } } in a read scope admits rows holding [] on that field. The changeset discloses the mechanism ("read as single-valued") but not its read-scope direction. Reading: not a FAIL ground. The spec's own isMultiValueField requires multiple === true, so an absent flag reads as the field's default; the compiler reads the declaration the host hands it, and a host that strips a declared multiple hands a false declaration — the producer to fix (Prime Directive Add comprehensive test suite for Zod schema validation #12). The in-repo composition (AnalyticsServicePlugin) relays it. Recommended for the same patch round, not required: one clause in the changeset naming that on a host omitting multiple, a read scope's $empty: false over such a field admits the empty list.
7. Out-of-scope findings (4) — carriers assigned in the ACCEPT (the flip card for three, filter: the engine's compile surfaces answer $empty by the field's declared type (driver-sql and heirs, turso remote, driver-memory, driver-mongodb, formula, objectql having) — ruling A on #20399 #20444 for one). Nothing here changes them.
8. Checks on the head at 2026-09-28T19:25Z: 34 names, 31 success, 3 skipped (Build Docs, Console Pin Gate, Packed-tarball smoke — path-skipped / opt-in), 0 failure, 0 in progress. All green; the FAIL rests on ② alone.

Implemented-by: claude/issue-20445-analytics-empty-operator-arms
Reviewed-by: session_017B6YKCGu8CTY2KBWgwaHAs

VERDICT: FAIL

_{Rendered by an isolated contract-review subagent and adopted by the domain:services seat (#6021, session_017B6YKCGu8CTY2KBWgwaHAs) at 2026-09-28T19:30Z after a transcript check: 85 harness model stamps, all at CONTRACT_REVIEW_TIER, zero fallbacks; reads only, one Write confined to its own scratch record, zero GitHub writes. The seat takes the correction as ruled: a patch round on this PR moves the changeset to minor and every Clause-② carrier to yes (widening), and carries the recommended residual clause. The seat corrects the claim line and the PR body line itself.}

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 611daa435f9947e1e13cb85b8b4121a8a4123e76
Local-runs: none

Inputs read: card #20445 (body and all 6 comments — the claim 5875970963 as it stands after the seat's 2026-09-28T19:31:28Z edit, the ACCEPT 5876774357, the dev reports 5876735617 and 5877331052, the two triage records), PR #20498 (body as it stands, the 11-file list, both PR comments — the prior ## Contract review record 5876996555, FAIL on 6a07f8cc, included — and the net diff against main: merge base fc0db22b on both the PR's recorded base 45f428d8 and origin/main 2b24b8b8, 11 files, +1089 / −18), file contents at the head through a fetched review ref and the spec on origin/main, and the head's check-runs (read 2026-09-28T19:53Z: 34 names, 31 success, 3 skipped, 0 failure, 0 in progress, every run on 611daa43). Nothing was built, run or re-run.

Delta since the prior record, proven from git. git diff --name-status 6a07f8cc 611daa43 names exactly one path, .changeset/20445-analytics-empty-operator-arms.md, +3 / −3; git log 6a07f8cc..611daa43 is one commit, 611daa43 (chore(changeset): …), whose sole parent is 6a07f8cc. No source, test, spec or entry file moved: packages/services/service-analytics/src/index.ts and package.json are byte-identical to the merge base, and the net diff against main is the same 11 files the prior record judged. Hence the prior record's ① judgments carry to this head unchanged; they are restated below with what was re-read here.

① Derived judgments

The spec on main, which every judgment is read against: FieldOperatorsSchema / SpecialOperatorSchema declare $empty: z.boolean() with the ruled per-type table as its meaning and say the executors refuse it until each face has its arm; filter-empty-operator.ts exports the one expansion (expandEmptyOperator, EMPTY_OPERATOR_ARMS), keyed on isMultiValueField (MULTI_OPTION_TYPES always; MULTI_CAPABLE_TYPES = select / radio / lookup / user / file / image only with multiple === true) and STRING_VALUE_TYPES; FILTER_OPERATORS deliberately omits $empty (「照 $like 先例分阶段」).

1. Accept set, the where face (/analytics/query, /analytics/sql, dataset filters). fieldLeaves lowers $empty: true | false to a valueless empty / notEmpty leaf where it used to refuse INVALID_FILTER / 400; the leaf is answered by the field's declared row. RIGHT, and on its own not a Clause-② widening: the key, its boolean domain and its per-type meaning are already published by the spec; the refusal removed is the spec's own stated interim, and ruling A on [Decision] How does a filter say 「is empty」 on a multi-value field? A declared $empty operator, or reopen the empty-list refusal (ruling B on #20311, its third arm) #20399 orders one arm per compile surface. Carries.
2. Accept set, the read-scope compiler (compileScopedFilterToSql). A $empty arm in compileOperator → compileEmptyOperator, where the operator used to fall into default: (READ_SCOPE_COMPILE_FAILED / 500). The default: arm itself is unchanged — 500, message withheld, per the analytics dataset 路由的 message 正则兜底没有退休时间表:六族拒收仍靠措辞分类,改一个字就换一个 HTTP 码 #5367 ruling the module header records (re-affirmed [spec] service-analytics' read-scope / Cube filter compilers still refuse $field, so a CEL field-to-field RLS rule 400s on those faces #7598 Q2 = A, extended by security: the analytics ObjectQL execute face answers a row-level read scope it cannot run with INVALID_FILTER / 400 whose message echoes the policy's field name and comparands — the disclosure #5367 closed for the native / echo faces #19995) — and pinned with $bogus. RIGHT. Carries.
3. Boolean-domain gate. $empty joins $null / $exists on both faces (BOOLEAN_FLAG_OPERATORS in read-scope-sql.ts; FLAG_MEANINGS / isBooleanFlagOperator in filter-normalizer.ts) and in both assertDefinedComparands skip lists, so a non-boolean flag — the string "true" included — is refused rather than compiled to the false arm. A narrowing to the declared z.boolean(). RIGHT. Carries.
4. RLS over-admission audit — does any arm admit more rows than the declared semantics on any strategy or dialect the diff compiles for? Re-read at this head, empty-operator-sql.ts and both callers:
   • null_only: col IS NULL / col IS NOT NULL. Total.
   • text: (col IS NULL OR col = '') and its complement (IS NOT NULL AND not-equal ''), the '' bound. Total, dialect-free.
   • multi_value: (col IS NULL OR L) / (col IS NOT NULL AND NOT L). SQLite L is a CASE guarded by json_valid with ELSE 0, so malformed text, '' and a non-array JSON value read FALSE, never NULL or TRUE; Postgres jsonb equality with '[]'; MySQL JSON_TYPE = 'ARRAY' AND JSON_LENGTH = 0. On the 'unknown' dialect L has no construct, emptyOperatorPredicateSql answers null having bound nothing, and BOTH callers refuse (whereEmptyLeafSql → INVALID_FILTER / 400; compileEmptyOperator → READ_SCOPE_COMPILE_FAILED / 500) — null is never read as "no constraint".
   • NULL column: both polarities spell their NULL case out, so operatorIsNullTotal('$empty') = true is exact on both faces and NOT (…) is the exact complement; nullValueSatisfiesOperator('$empty') = (value === true) is right on every row.
   • No declaration (no declaredValueShape option, a bare spec StrategyContext, an unknown field): refused before anything binds, params aligned — the refusal class the face had before the diff.
   • Every consumer of the lowered tree: NativeSQLStrategy.buildFilterClause answers the leaf ahead of its empty-values drop; ObjectQLStrategy.buildFilterClauseSql (the echo) through the same function; ObjectQLStrategy.convertFilter hands { $empty: true | false } to the engine verbatim, where every engine driver refuses it until filter: the engine's compile surfaces answer $empty by the field's declared type (driver-sql and heirs, turso remote, driver-memory, driver-mongodb, formula, objectql having) — ruling A on #20399 #20444. Nothing drops, nothing reads TRUE.
     No arm admits more than the declared semantics. RIGHT. Carries. The one host-composition residue is ③.6, now disclosed in the changeset.
5. Public surface, against the package's exports map (only .) and src/index.ts at the head, both unchanged:
   • StrategyContext — the spec's interface, re-exported untouched. UNTOUCHED.
   • DatasetScopedStrategyContext.declaredValueShape? (strategies/types.ts) and the exports of empty-operator-sql.ts (declaredValueShapeResolver, emptyOperatorPredicateSql, whereEmptyLeafSql, EmptyOperatorSqlRequest) — not re-exported from the entry, unreachable from its type graph (private baseCtx / callCtx; the strategies cast internally). Shipped bytes, not a published accept set. NOT PUBLISHED, no trigger. RIGHT.
   • AnalyticsServiceConfig.sourceFieldMeta — exported by name; its return shape gains multiple?: boolean, a key a host may now write and the runtime reads. PUBLISHED and WIDENED.
   • compileScopedFilterToSql — exported by name; ReadScopeCompileOptions (its third parameter, reachable through the signature) gains declaredValueShape?. PUBLISHED and WIDENED.
   • AnalyticsServicePluginOptions, the strategies' public signatures, FILTER_OPERATORS, the is_empty / is_not_empty lowering and packages/spec — unchanged; the staging is honoured. RIGHT.
     Two published optional members added ⇒ the declaration must read yes (widening) and the level at least minor. At 6a07f8cc it read no / patch (WRONG, the prior FAIL); at this head it reads yes (widening) / minor on every carrier (②). Now RIGHT.
6. Prose. The where refusal's supported-operator list now names $empty; the read-scope non-boolean refusal names three flags; the changeset (a contract-review face) names both published members and the host-omission residue. Consistent with the arms; the residue's accuracy is judged in ③.6. RIGHT.

② Semver level

• Declared at this head. Changeset front matter '@objectstack/service-analytics': minor; the changeset body's line-start declaration reads yes (widening); the PR body's line 3 (its only line-start declaration; the "Seat append" mentions it inline only) reads yes (widening); the claim comment 5875970963, edited by the seat at 19:31:28Z, carries one line-start declaration reading yes (widening) and quotes it inline in a sub-note. All three carriers agree with the front matter.
• Ruling: RIGHT. Two entry-reachable optional published members (①.5) make the diff a widening of the public surface: the declaration is yes with the arm (widening) from the closed pair, and yes takes at least minor (AGENTS.md Post-Task Checklist 3; execution-duties 「本卡放宽接受集或扩大公开面吗」; lanes/spec.md 「不论多小,即条款②」). Not breaking — both members optional, nothing removed, renamed or narrowed — so minor is the exact level, no ADR-0087 disposition marker is owed and none is present, and skip-changeset is neither owed nor on the PR (labels: documentation, size/xl, tests, tooling, needs:contract-review). Precedent in this package's own CHANGELOG 17.4.0 "Minor Changes": 54bb2f1 (new optional AnalyticsServiceConfig.sqlDialect) and the new optional nonTextColumn option on compileScopedFilterToSql — the identical two shapes, levelled minor.
• The prior record's "Exact correction", item by item. (1) front matter patch → minor: DONE. (2) the declaration line on all three carriers → yes (widening): DONE on the changeset body (the one commit), the PR body and the claim comment (both corrected in place by the seat). (3) nothing else: no ADR-0087 marker (none), no skip-changeset (absent), no spec edit (file list unchanged), no api-surface baseline (this package carries none), the fix: title kept — DONE, nothing beyond the order was touched. The recommended residual clause: PRESENT (③.6).
• Check Changeset on this head: success — the gate's level axis (a PR declaring yes must grade at least one package whose published source it moves minor or above) is satisfied by the front matter, and check-adr-0087-registration inside the green lint job reads a non-breaking changeset. The mechanical read and this seat-level read agree.

③ Boundary flags

1. Round-1 deviations[0] — six service-analytics files beyond the claim's two faces. Carries: RIGHT to extend (an unhandled leaf would answer null = no clause = TRUE, the exact RLS widening; the multiple channel did not exist); the prohibited items (packages/spec, FILTER_OPERATORS, the lowering flip) are untouched; the ACCEPT amended the surface on record. No escalation.
2. Round-1 open_questions[0] / deviations[1] — the ObjectQL echo renders the declared $empty arm while ObjectQL execute is refused by the engine until filter: the engine's compile surfaces answer $empty by the field's declared type (driver-sql and heirs, turso remote, driver-memory, driver-mongodb, formula, objectql having) — ruling A on #20399 #20444. The seat answered A; concur: no row is served wrong, and under B the divergence would outlive filter: the engine's compile surfaces answer $empty by the field's declared type (driver-sql and heirs, turso remote, driver-memory, driver-mongodb, formula, objectql having) — ruling A on #20399 #20444 with nothing turning red. Carrier knocked to filter: the engine's compile surfaces answer $empty by the field's declared type (driver-sql and heirs, turso remote, driver-memory, driver-mongodb, formula, objectql having) — ruling A on #20399 #20444. No escalation.
3. Round-1 deviations[2] — attribution trailer choice. No contract bearing.
4. The card's 400-vs-500 question. 500 kept, stated in code at compileOperator's default: arm and in the PR; RIGHT under Prime Directive [WIP] Add Chinese version of the documentation #13 (analytics dataset 路由的 message 正则兜底没有退休时间表:六族拒收仍靠措辞分类,改一个字就换一个 HTTP 码 #5367 binds until superseded; the scope's producer is the security service or the host's getReadScope, never the query caller); pinned with $bogus. No escalation.
5. NOT MEASURED — Postgres / MySQL execution of the multi-value arm. Unchanged since round 1 (no live analytics job in the PG + MySQL lane); compiled strings pinned; neither string can read TRUE for a non-empty value, and malformed storage fails as a database error, fail-closed. Accepted as a stated gap. No escalation.
6. The recommended residual clause, judged against the code at this head. The changeset now says: a host whose sourceFieldMeta answers type but not multiple has every multi-capable field it declared multiple: true (select / radio / lookup / user / file / image) read as single-valued, the null-only row; on such a field a read scope's $empty: false admits rows holding [] and $empty: true misses them; relay the field's multiple to get the list row. ACCURATE on every clause: AnalyticsService.declaredValueShape maps the hook's answer to { type, multiple: meta.multiple === true }, so an omitted flag is false; expandEmptyOperator reaches multi_value only through isMultiValueField, which for the multi-capable set requires multiple === true, and that set on main is exactly the six types the clause lists, none of them text-like, so the field lands on null_only; that row compiles col IS NULL / col IS NOT NULL, under which a stored [] is admitted by $empty: false and missed by $empty: true. The multi-option types (multiselect, checkboxes, tags) are unaffected by the omission, and the clause correctly scopes itself to the multi-capable ones. The in-repo composition (AnalyticsServicePlugin) relays multiple: f.multiple === true. Not a FAIL ground, as ruled before: the compiler reads the declaration it is handed, and a host that strips a declared multiple hands a false declaration — the producer to fix (Prime Directive Add comprehensive test suite for Zod schema validation #12); the residue is now disclosed with its read-scope direction and its remedy. No escalation.
7. Round-2 report 5877331052 carries deviations: [] and open_questions: []; its claim that only the changeset moved is what git shows. Nothing new to answer.
8. Out-of-scope findings (4) — carriers assigned in the ACCEPT (the flip card for three, filter: the engine's compile surfaces answer $empty by the field's declared type (driver-sql and heirs, turso remote, driver-memory, driver-mongodb, formula, objectql having) — ruling A on #20399 #20444 for one). Unchanged.
9. Checks on this head at 2026-09-28T19:53Z: 34 names, 31 success, 3 skipped, 0 failure, 0 in progress. The seven required contexts — Lint & Repo Gates, TypeScript Type Check, Test Core, Dogfood Regression Gate, Build Core, Temporal Conformance (live PG + MySQL), Governed Surface Queue Guard — are all success; Check Changeset is success. The three skips are expected by construction: Build Docs and Console Pin Gate are gated on the filter job's docs / console outputs, whose path lists (apps/docs/**, content/**, pnpm-lock.yaml, ci.yml; .objectui-sha, five console scripts, ci.yml) match none of the 11 changed paths; Packed-tarball smoke (opt-in) runs only under the needs:pack-smoke label, which the PR does not carry.
10. needs:contract-review is on the PR. Per contract-review.md a PASS record for the current head lifts it by the seat that writes the record — a seat write; none is made here.

Implemented-by: claude/issue-20445-analytics-empty-operator-arms
Reviewed-by: session_017B6YKCGu8CTY2KBWgwaHAs

VERDICT: PASS

_{Rendered by an isolated contract-review subagent and adopted by the domain:services seat (#6021, session_017B6YKCGu8CTY2KBWgwaHAs) at 2026-09-28T20:00Z after a transcript check: 71 harness model stamps, all at CONTRACT_REVIEW_TIER, zero fallbacks; reads only, one Write confined to its own scratch record, zero GitHub writes. This PASS on head 611daa43 supersedes FAIL 5876996555 (head 6a07f8cc). The seat lifts needs:contract-review in this round.}

---

Generated by Claude Code