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)

[objectstack-fleet]

Part of #19995. This PR closes the placeholder class of the card's engine-door residue. The card stays open: two of the three engine-door classes still answer a relayed 400 on both analytics HTTP doors, and two more classes of the same kind were measured here. They are listed under "Residue" below, with the reason each is not fixed here.

Clause-②: no

What changed

The analytics ObjectQL execute face composes a row-level read scope into the where it hands engine.aggregate. The engine resolves {placeholder} filter values on that composed where. A scope carrying an unknown placeholder, or a known one the request has no value for, therefore came back as the engine's FILTER_TOKEN_UNKNOWN / FILTER_TOKEN_UNRESOLVED / 400. Both HTTP doors relay a 4xx's message, and this one named the policy's placeholder. The #5367 ruling (re-affirmed as #7598 Q2 = A) makes a read-scope refusal a withheld READ_SCOPE_COMPILE_FAILED / 500.

• read-scope-sql.ts: new assertReadScopePlaceholdersResolvable(scope, objectName, context), beside assertReadScopeComparandsRunnable (PR fix(service-analytics): the ObjectQL execute face refuses an unrunnable read scope in the withheld READ_SCOPE_COMPILE_FAILED / 500 envelope #20017).
  • It runs the engine's own placeholder resolver on the scope alone. That resolver is resolveFilterTokens from @objectstack/core, the function ObjectQL.resolveWhereTokens calls.
  • It builds the token context with filterTokenContextFrom, over the context the strategy forwards to executeAggregate.
  • Anything the resolver throws is re-raised through the module's one envelope helper, readScopeCompileError. The resolver's sentence stays in the operator's log.
  • It is exported from the file only. The package entry 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.

Order at each merge: after assertReadScopeCannotVacate and assertReadScopeComparandsRunnable, and before the 'policy' mark.

• After the comparand faces, because the engine resolves placeholders after its lowering doors: lowerWhereFilterArray runs the comparand faces on the unresolved where, and resolveWhereTokens runs next. A scope with both defects therefore logs the sentence the engine would have given. On the wire it is the same withheld 500 either way.
• Before the mark, like its two siblings, so a refused scope is never stamped as vouched-for policy content.

Why the set of served scopes does not move:

• Same function. The resolver's verdict on one string depends on nothing else in the tree. So the scope alone answers exactly as it does inside { $and: [userFilter, scope] }.
• Same inputs. The token context comes from the engine's own bridge over the context executeAggregate receives, which is the context the engine resolves with.
• Resolved scopes are still served. A placeholder the engine resolves is resolved here too, and the scope is served. The resolved tree is discarded, and the engine resolves the original as before. Ablation B3 below turns this control red by having the judgement read a different context.

⛔ This is not a catch around executeAggregate. The caller's own where never reaches the engine's resolver with a placeholder still in it: AnalyticsService resolves the query's own positions first and answers with its own 400 and message. The caller's text-operator and temporal refusals, which the engine answers, keep their 400 with the message. Ablation B5 shows those pins going red under a blanket catch.

Instrument. The dispatch named classifyFilterToken. The engine's door is resolveFilterTokens, which walks the tree and classifies each string with classifyFilterToken. Judging with the resolver reuses that walk instead of writing a second one. It also covers the resolver's second refusal, a known placeholder the context cannot resolve, with no extra code.

Measurement

How it was measured. A scratch probe (not committed; it lived in packages/runtime/src and was deleted) used a real ObjectQL over SqliteWasmDriver and AnalyticsService on the ObjectQL face only, with the scope taken from getReadScope. The HTTP legs went through the real routes:

• @objectstack/runtime's dispatcher, POST /api/v1/analytics/query;
• @objectstack/rest, POST /analytics/dataset/query.

Before: base 3557f85fa5, which is 980bc05e5b plus one driver-turso README commit. After: head df5caa9afa, with the service-analytics dist rebuilt; the new message is present once in each of dist/index.js and dist/index.cjs. AnalyticsService called directly gave the same code and status as the HTTP doors on every row. The before table is also recorded in the branch's first commit, eab6d874b9, which is test-only.

Close condition (5821737887): no policy content in any body on both HTTP doors, for the seven residue classes. Measured on the final head:

Read-scope class	Layer that answers	Both HTTP doors, before	Both HTTP doors, after	Policy content in the body, after
Text operator on a non-text field	Engine, declared-type door	INVALID_FILTER / 400	unchanged	yes: field and operator (residue)
Temporal comparand the platform cannot read	Engine, temporal door	INVALID_FILTER / 400	unchanged	yes: field and comparand (residue)
Unknown filter placeholder	Engine, placeholder resolver	FILTER_TOKEN_UNKNOWN / 400, token relayed	READ_SCOPE_COMPILE_FAILED / 500	no
Column the object does not have	driver-sql	INVALID_FILTER / 400, withheld	unchanged	no
Retired or unknown operator	driver-sql	INVALID_FILTER / 400, withheld	unchanged	no
Combinator with a non-array operand	driver-sql	INVALID_FILTER / 400, withheld	unchanged	no
Non-boolean $null or $exists	driver-sql	INVALID_FILTER / 400, withheld	unchanged	no

Also measured, beyond the card's seven:

Read-scope class	Layer that answers	Both HTTP doors, before	Both HTTP doors, after	Policy content in the body, after
A known placeholder the request context cannot resolve	Engine, placeholder resolver	FILTER_TOKEN_UNRESOLVED / 400, token relayed	READ_SCOPE_COMPILE_FAILED / 500	no
A filter on a virtual (formula) field	Engine, materializable-field door	INVALID_FIELD / 400	unchanged	yes: field (residue)
A dotted path through a lookup	Engine, materializable-field door	INVALID_FIELD / 400	unchanged	yes: field and path (residue)

Controls, identical before and after:

• A well-formed scope answers 200 with exactly its rows.
• The caller's own where, in each of the three card shapes (text operator, temporal comparand, placeholder), answers its 400 with its own message.

Tests

The new file is packages/services/service-analytics/src/__tests__/objectql-read-scope-placeholder-refusal.test.ts: 18 cases over a real ObjectQL and SqliteWasmDriver.

• Refusal cases assert code READ_SCOPE_COMPILE_FAILED and status 500, and the two reads every analytics HTTP door takes before relaying prose: serverFaultProvenance(resolveThrownHttpError(err, 500)) is 'declared', and declaredRefusalMessage(err) is undefined. The thrown message, the operator's log channel, still carries the detail.
  • Five scope shapes on the direct path: an unknown placeholder, a near-miss spelling, a brace-wrapped non-token, an unknown list member nested in an $or, and a known placeholder the context cannot resolve.
  • A well-formed caller where beside a refused scope.
  • The cross-object base scope, and the referenced-object scope.
• Controls:
  • A placeholder the context resolves is served with exactly its rows, on the direct path and on the referenced object.
  • A well-formed scope is served.
  • The caller's own where keeps its 400 with its message for an unknown placeholder, a text operator on a number field, and an uninterpretable temporal comparand.
  • The four driver-sql door classes keep INVALID_FILTER / 400 with no policy content in the message.

Results:

• Test-only commit eab6d874b9, before the fix: Tests 8 failed | 10 passed (18). Every refusal case received FILTER_TOKEN_UNKNOWN or FILTER_TOKEN_UNRESOLVED, and every control was green.
• Final head df5caa9afa:
  • pnpm --filter @objectstack/service-analytics test: Test Files 121 passed (121), Tests 2707 passed (2707).
  • pnpm --filter @objectstack/service-analytics typecheck exits 0, and tsc --listFiles includes the new test.

Ablations. Each leg ran from committed state, through scripts/ablation-replace.mjs with the file's restore armed. The anchor had to hit exactly once and the blob had to change. Every restore was proven: the blob equals HEAD, and git diff HEAD is empty. The subject is imported from src, so no dist is involved.

Leg	Mutation	Result
B1	Delete the withReadScope call	7 failed, 11 passed: every direct and cross-object-base refusal case received FILTER_TOKEN_*
B2	Delete the resolveFkAttr call	1 failed (the referenced-object case), 17 passed
B3	Judge with an empty token context instead of the forwarded one	2 failed: both "served" controls were refused
B4	Stamp the scope 'author' instead of 'policy'	4 failed: all four driver-sql controls disclosed. A first run found the retired-operator row's secret vacuous (3 of 4 went red), so that row was corrected before this run.
B5	Wrap the direct executeAggregate in a blanket catch that re-raises as the withheld 500	6 failed: the caller's text-operator and temporal controls, and the four driver-sql controls. The caller-placeholder control stays green, because AnalyticsService refuses that one before the strategy runs.

Gates

• Derived gates. Derived at df5caa9afa with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands: 61 families, a superset of the dispatch-time list. All 61 exited 0.
  • check:dual-build-cjs-loads and check:type-check-debt first answered PREREQUISITE NOT MET (exit 3). After a build of the ./packages/* closure, both exited 0. check:dts-closure, check:lean-entry-closure, check:published-files and check:sourcemap-no-sources-content were re-run on that full build and exited 0.
  • The --ran reconciliation reported 61 derived, 61 run, 0 NOT-MEASURED, 0 UNRUN.
• Issue citations. node scripts/check-issue-citations.mjs exited 0: 5 citations judged, 5 resolve.
• Lint, narrowed to the three touched TypeScript files. eslint --no-inline-config --format json read 3 files and reported 0 errors and 0 warnings. The resolved config for these files sets parserOptions to ecmaVersion and sourceType only: no project, no projectService. So this diff cannot move a verdict on an untouched file. pnpm lint itself is CI's.

Acceptance notes

• 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. PR fix(service-analytics): the ObjectQL execute face refuses an unrunnable read scope in the withheld READ_SCOPE_COMPILE_FAILED / 500 envelope #20017 records the same precedence for the comparand classes.
• No dependency change. The resolver was already reachable through @objectstack/core, a runtime dependency, so package.json and pnpm-lock.yaml are untouched.
• NativeSQL face and /analytics/sql echo: unchanged. Measured with a stubbed executeRawSql, they bind a read scope's placeholder as a literal string instead of resolving or refusing it. This is reported to the seat and not touched here.
• origin/main was merged once (5b9402d89b, currency scale retirement) and has since moved by one more commit (b76aad5f6f, packages/client). That commit shares no path with this diff and is not merged.
• Files not touched: filter-normalizer.ts, preview-evaluator.ts, text-match-sql.ts, packages/objectql, packages/spec, packages/rest, packages/drivers/*.

Residue: why "Part of"

These classes still answer an engine 400 on both HTTP doors, and the message names the policy:

• a text operator over a field that never holds a string (the card's);
• a temporal comparand the field's storage rule cannot read (the card's);
• a filter on a virtual field, or through a dotted path (measured here; the engine's materializable-field door).

Each is refused by an engine door that reads the object's schema. The doors' walks live in @objectstack/objectql, and neither of its package entries (. and ./core) exports them. @objectstack/service-analytics has no runtime dependency on the engine. So this package cannot run those walks without a copy of each, and none of the routes the dispatch listed stays inside this package:

• the engine instance exposes no filter-judging method today;
• a host-wired judge on the strategy context would still need the walks, or an engine method, to answer with.

The route needs an engine-lane change, and it is handed back to the seat as a decision.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

3 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• 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 b76aad5f6fac71cbbcd4ea6bfdf21a59e2fd4d56 → packageMentionDocs.

Which tree this was computed on

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

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

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