fix(service-analytics): the ObjectQL execute face refuses an unrunnable read scope in the withheld READ_SCOPE_COMPILE_FAILED / 500 envelope

[objectstack-fleet]

Part of #19995 — this PR closes the comparand half of the card: every scope shape the engine's two SHARED comparand faces refuse. The card stays open for the residue: scope shapes refused by engine doors that read the object's schema or the request's context, and by driver-sql, still answer a relayed 400. Why that half is not done here, and the decision it needs, is under "Residue" below.

Clause-②: no

What changed

The ObjectQL execute face composed a row-level read scope into the engine's where without judging it. A scope carrying a comparand the engine refuses came back as the engine's INVALID_FILTER / 400. The HTTP doors relay a 4xx's message, and that message named the policy's field and comparand. The NativeSQL face and the /analytics/sql echo refuse the same scope as READ_SCOPE_COMPILE_FAILED / 500 with the message withheld (the #5367 ruling, re-affirmed as #7598 Q2 = A). So one scope got two envelopes, depending on which analytics face served it.

• read-scope-sql.ts: new assertReadScopeComparandsRunnable(scope, objectName), next to the analytics: a non-RLS getReadScope scope bypasses read-scope-sql on the ObjectQL engine path — driver-sql lowers $nin: [] to constant TRUE (whole table), so a lowering-site refusal cannot guard this route #13640 vacancy guard. It runs the two faces the engine itself runs on every object-form where (assertListComparandShapes and normalizeFilterComparandTypes from @objectstack/spec/data) on the scope alone. It re-raises any refusal through the module's one envelope helper, readScopeCompileError, keeping the walk's sentence for the operator's log. It is exported from the file only, not from the package entry, so the published surface is unchanged.
• objectql-strategy.ts: called at both engine-bound merges.
  • withReadScope covers the direct path and the cross-object base aggregate.
  • resolveFkAttr covers the referenced object's own scope.
  • It runs after the vacancy guard and before the 'policy' mark.

Why at the merge boundary, on the scope alone. At that point the scope is still a distinguishable object. One line later it is $and-composed with the caller's filter, and then nothing downstream can tell whose clause a refusal came from.

Why the refusal set does not move. The engine's comparand-shape refusal does not read the 'policy' provenance mark (measured below). Both faces are pure walks whose verdict on a subtree depends neither on the rest of the tree nor on any schema. So the scope alone answers exactly as the scope inside { $and: [userFilter, scope] } does, and nothing the engine serves is refused. A { $field } scope (served on this path under #7598 Q1 = B) is stepped around by both faces, as the engine steps around it.

⛔ This is not a catch around executeAggregate. The caller's own where still reaches the engine's doors for some shapes, and those keep their INVALID_FILTER / 400 with the message. This is pinned, and ablation A5 below shows that pin going red under misattribution.

Measurement: recorded before the fix

Measured on base 14add487b4, using a scratch probe that is not committed: AnalyticsService (ObjectQL only) over a real ObjectQL, run twice, once over SqlDriver (better-sqlite3) and once over SqliteWasmDriver. The two drivers gave the same answer in every row. The HTTP leg went through the real routes: @objectstack/runtime's dispatcher POST /api/v1/analytics/query and @objectstack/rest's POST /analytics/dataset/query. The read scopes are the getReadScope contract filled by hand. The same probe was re-run after the fix, against a rebuilt dist.

Read-scope shape class	Layer that answers on the ObjectQL face	Before (ObjectQL face and both HTTP doors)	Refusal text names policy content	After
List in the implicit equality slot	Engine, shared list-shape face	INVALID_FILTER / 400, relayed	yes	READ_SCOPE_COMPILE_FAILED / 500, withheld
List under $eq	Engine, shared list-shape face	400, relayed	yes	500, withheld
Scalar under $in or $nin	Engine, shared list-shape face	400, relayed	yes	500, withheld
One-bound $between	Engine, shared list-shape face	400, relayed	yes	500, withheld
Null member in $in	Engine, shared list-shape face	400, relayed	yes	500, withheld
Plain-object member in $in; plain-object comparand under $eq; undefined comparand	Engine, shared comparand-type face	400, relayed	yes	500, withheld
Emptied $nin (control)	Analytics vacancy guard (#13640)	500, withheld	no (withheld)	unchanged
List under $ne or $gt; nested relation value; cross-field reference	driver-sql, which reads the mark	400, message withheld	no	unchanged
Column the object does not have	driver-sql, missing column	400, relayed	yes	unchanged (residue)
Retired or unknown operator	driver-sql operator vocabulary	400, relayed	yes (the field)	unchanged (residue)
Text operator on a non-text field	Engine, declared-type door	400, relayed	yes	unchanged (residue)
Temporal comparand the platform cannot read	Engine, temporal door	400, relayed	yes	unchanged (residue)
Combinator with a non-array operand	driver-sql	400, relayed	yes	unchanged (residue)
Non-boolean $null or $exists	driver-sql	400, relayed	yes (the field)	unchanged (residue)
Unknown filter placeholder	Engine token resolver	FILTER_TOKEN_UNKNOWN / 400, relayed	yes	unchanged (residue)
Well-formed scope (control)	—	200, scoped rows	—	unchanged

• Hypothesis 2 (does the engine refusal read the mark?): confirmed. The scope reached the engine stamped 'policy' by withReadScope, and the comparand-shape refusal still returned its full text. Of the refusals in the table, only driver-sql's bind and cross-field refusals read the mark.
• Hypothesis 3 (does the ObjectQL face reach the read-scope compiler?): confirmed. The ObjectQL execute face never reaches compileScopedFilterToSql. The NativeSQL face and the echo answered READ_SCOPE_COMPILE_FAILED / 500 for every fixed class except two: a plain-object comparand under $eq and a null member in $in. That compiler compiles both of those (see Acceptance notes).
• Scope reads quoted. The strategy has four:
  • generateSql's echo merge compiles through compileScopedFilterToSql, is already withheld, and is untouched.
  • withReadScope and resolveFkAttr are the two engine-bound merges, and both are now guarded.
  • NativeSQLStrategy.applyReadScope compiles and is untouched.

Tests

The new file is packages/services/service-analytics/src/__tests__/objectql-read-scope-refusal-envelope.test.ts, with 19 cases over a real ObjectQL and SqliteWasmDriver.

• Refusal cases. Each refused shape class asserts:
  • code READ_SCOPE_COMPILE_FAILED and status 500;
  • that the reads every analytics HTTP door takes before relaying prose (serverFaultProvenance(resolveThrownHttpError(err, 500)) is 'declared', declaredRefusalMessage(err) is undefined) mean the prose is withheld;
  • that the thrown message, which is the operator's log channel, still carries the detail.
• Paths covered: the direct path, a well-formed caller where beside a refused scope, the cross-object base scope, and the referenced-object scope.
• Controls:
  • a well-formed scope is served with its rows;
  • a cross-field scope is served;
  • an emptied $in beside an own-rows grant is served;
  • a well-formed referenced-object scope buckets what it hides as (restricted);
  • the caller's own where refused by the ENGINE stays INVALID_FILTER / 400 with its message;
  • the caller's own where in the scope's refused shape stays 400 with its message.

Results:

• Measurement commit e4908254bc (test only, before the fix): Tests 13 failed | 6 passed (19). Every refusal case received INVALID_FILTER, and every control was green.
• At 9a40317b15:
  • the new file gives Tests 19 passed (19);
  • the whole package gives Test Files 118 passed (118), Tests 2560 passed (2560);
  • pnpm --filter @objectstack/service-analytics typecheck exits 0, and tsc --listFiles includes the new test.

Ablations. Each leg ran through scripts/ablation-replace.mjs (the anchor must hit exactly once, and the blob must change) with a trap. Each restore was proven: the blob equals HEAD, and git diff HEAD is empty.

Leg	Mutation	Result
A1	Delete the withReadScope call	12 failed, 7 passed. Every direct and cross-object-base refusal case received INVALID_FILTER.
A2	Delete the resolveFkAttr call	1 failed (the referenced-object case), 18 passed
A3	Delete the comparand-type face call	3 failed (the three type-face rows)
A4	Delete the list-shape face call	10 failed (the shape rows, the composed case, both cross-object cases)
A5	Judge the COMPOSED tree instead of the scope alone	1 failed: the caller's engine-refused where received READ_SCOPE_COMPILE_FAILED instead of INVALID_FILTER

Gates

• Derived gates. Derived at 9a40317b15 with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands: 72 families, a superset of the dispatch-time list. All 72 exited 0.
  • check:dual-build-cjs-loads and check:type-check-debt first answered PREREQUISITE NOT MET (exit 3). I built the ./packages/* closure and re-ran both, and both exited 0.
  • The --ran reconciliation reported 72 derived, 72 run, 0 unrun.
• Issue citations. GITHUB_TOKEN=… node scripts/check-issue-citations.mjs exited 0: 10 citations judged, 10 resolve.
• Lint, narrowed to the four touched TypeScript files. eslint --no-inline-config --format json read 4 files and reported 0 errors and 0 warnings. eslint.config.mjs enables no type-aware linting (no parserOptions.project, no projectService), so this diff cannot move a verdict on an untouched file. pnpm lint itself is CI's.

Acceptance notes

• @objectstack/objectql is a new devDependency, aliased to source in the package's vitest.config.ts with an anchored regex. This is the repair check:test-source-alias prescribes; the ledger does not grow, and the gate is green. The refusal under test is the engine's own, so a stub bridge would only have tested the stub.
• Envelope reuse. The guard lives in read-scope-sql.ts because readScopeCompileError is module-local by design. A guard in the strategy file would have needed a second spelling of the envelope.
• A host with its own executeAggregate bridge: the scope is now judged against the spec's shared comparand faces whichever bridge executes, the same posture as the vacancy guard. A custom bridge that used to tolerate one of these off-contract scope shapes now gets the withheld 500. The engine bridge refused all of them already.
• Precedence. When the caller's where and the scope are both refused, and only the engine would refuse the caller's clause, the scope's 500 now answers first. A caller clause refused by the analytics where door still answers first, with its 400.
• NativeSQL face and echo: unchanged. They compile two shapes (a plain-object comparand under $eq, a null member in $in) that the shared faces and the ObjectQL face refuse. This was measured with a stubbed executeRawSql, so the database-level outcome is unmeasured. It is reported to the seat and not touched here.
• origin/main has moved on by one commit (fc6ddb87a4, driver-sqlite-wasm text round-trip). It shares no path with this diff and is not merged.
• Files not touched: filter-normalizer.ts, packages/spec, packages/objectql, packages/rest, packages/runtime.

Residue: why "Part of"

These classes still answer the engine's or the driver's 400 with the message relayed:

• a column the object does not have;
• a retired or unknown operator;
• a text operator on a non-text field;
• a temporal comparand the platform cannot read;
• a combinator with a non-array operand;
• a non-boolean $null or $exists;
• an unknown filter placeholder.

They are refused by engine doors that read the object's schema or the request's context, and by driver-sql's own compile. This package cannot judge them without a second copy of those rules. The sound fix is at the refusing layer: the refusal reads the 'policy' provenance mark (#8220), as driver-sql's bind and cross-field refusals already do. That change is in the engine and driver lanes, and it opens an envelope question between the #5367 and #7929 rulings. It is handed back to the seat as a decision.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-analytics, touching 4 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/services/service-analytics/vitest.config.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/permissions/access-recipes.mdx (via readScope (literal, a string literal in assertReadScopeComparandsRunnable))
• content/docs/permissions/index.mdx (via readScope (literal, a string literal in assertReadScopeComparandsRunnable))
• content/docs/permissions/permission-sets.mdx (via readScope (literal, a string literal in assertReadScopeComparandsRunnable))
• content/docs/permissions/permissions-matrix.mdx (via readScope (literal, a string literal in assertReadScopeComparandsRunnable))
• content/docs/permissions/positions.mdx (via readScope (literal, a string literal in assertReadScopeComparandsRunnable))
• content/docs/permissions/rls.mdx (via readScope (literal, a string literal in assertReadScopeComparandsRunnable))
• content/docs/permissions/sharing-rules.mdx (via readScope (literal, a string literal in assertReadScopeComparandsRunnable))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/services/service-analytics/vitest.config.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 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; 100 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 a0920b42dc33efadc483f5112da36cfa53124cbb → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 4687452427a9942d0f0817997ed3b3403ad743c9 — the merge of head 9a40317b15ed67c01ea5d7eaca0a8fb9afdfb938 into base a0920b42dc33efadc483f5112da36cfa53124cbb, 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 4687452427a9942d0f0817997ed3b3403ad743c9 && git checkout 4687452427a9942d0f0817997ed3b3403ad743c9
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin a0920b42dc33efadc483f5112da36cfa53124cbb 9a40317b15ed67c01ea5d7eaca0a8fb9afdfb938 && git checkout -B drift-repro a0920b42dc33efadc483f5112da36cfa53124cbb && git merge --no-ff 9a40317b15ed67c01ea5d7eaca0a8fb9afdfb938

node scripts/docs-audit/affected-docs.mjs --json a0920b42dc33efadc483f5112da36cfa53124cbb

⚠️ 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 a0920b42dc33efadc483f5112da36cfa53124cbb → pass the list as
args.docs, on the commit named under Which tree this was computed on.