fix(service-analytics): queryDataset compiles into a request scope and never writes the shared registries

[objectstack-fleet]

Fixes #20356

Clause-②: no

What this changes

AnalyticsService.queryDataset no longer writes the service-wide CubeRegistry or the compiled-dataset registry. It used to register the dataset's compiled cube under the dataset's name before running the selection and before any admission was asked, so that name then meant one request's definition for every later reader until restart.

• Pure compile. A new private compile(dataset) binds this service's probes and registers nothing. registerDataset (the configuration door: AnalyticsServiceConfig.datasets and embedders) is compile + register, unchanged in behaviour. queryDataset calls only compile.
• A request scope for every name-keyed read. A small internal CubeScope (getCube, getCompiledDataset, register) is threaded through the query path. The shared scope reads and writes the registries. A queryDataset call gets a request scope: its own compiled dataset answers its name, every other name reads the shared scope read-only, and register writes only to the request scope.
• One body for both. query() is now queryIn(sharedScope, …), and the DatasetExecutor of a dataset call queries through a face whose query() is queryIn(requestScope, …). Every gate is the same code; only the answer to "which cube does this name mean" differs.
• Comments that described queryDataset as a registration door are corrected in cube-registry.ts and dataset-compiler.ts.

No new refusal is added. A dataset whose name matches a configured cube is served from its own definition and no longer meets that cube (triage note 3).

Mechanism assumptions, measured

1. Other registry writes. registerDataset was not the only request-time write reachable from queryDataset. ensureCube's measure augmentation also registered into the shared registry, through DatasetExecutor → query(), when a selection named an undeclared suffix measure. It now writes into the request scope, which is pinned. The same two ensureCube writes (inference and augmentation) remain request-time shared writes on the /analytics/query and /analytics/sql doors. They are not the dataset door, and they are reported, not changed (see Acceptance notes). The boot-time writes are unchanged: config.cubes and config.datasets in the constructor.

2. Name-keyed reads on the query path. Each of these reads the compiled cube by name, and each now resolves through the call's scope:

   • ensureCube's existence and source-field gates;
   • queryObjects, which is both the object-level admission set and the read-scope set;
   • the strategy context's getCube (both strategies' canHandle, execute and generateSql);
   • getAllowedRelationships (the NativeSQL join allowlist) and getDatasetScope (both strategies), which read the compiled-dataset registry.

   ObjectQL's resolveFkAttr reads no registry, and queryCapabilities(cube) is a config hook. DatasetExecutor itself reads compiled.cube directly, but it issues query({ cube: name }), which is why it needs the scoped face.

3. Doors. POST /api/v1/analytics/dataset/query (rest-server.ts) calls queryDataset. GET /api/v1/analytics/meta (runtime/src/domains/analytics.ts) calls getMeta(), which reads cubeRegistry.getAll(), the shared registry.

4. Hidden cube. On main nothing reads Cube.public: three producers write it and no reader exists in service-analytics, runtime or rest. So "stays hidden from meta" is NOT MEASURABLE on this tree. What is pinned is that the registry entry keeps the author's public: false definition (unit test) and that member B's whole meta answer equals B's baseline (route test). Once analytics_cube.public enforcement lands, that same equality asserts that the cube stays omitted.

Tests (all on 15e21b98)

• src/__tests__/query-dataset-request-scope.test.ts (new, both strategy paths, 12 cases). A second caller's getMeta() and the exact driver calls its queries of the configured cube and of the boot-registered dataset are snapshotted before and after each of these requests:

  • a refused dataset under a configured cube's name (asserts PERMISSION_DENIED / 403, and that the driver never saw the walled object);
  • an admitted one, served from its own object;
  • a public: false name;
  • fresh names, one refused and one admitted with an augmented measure.

  The control is the dataset registered at construction, which still serves and keeps its compiled filter.

• packages/qa/dogfood/test/analytics-inline-dataset-isolation.dogfood.test.ts (new, bootStack, two sign-ups, sqlite-wasm + memory, 10 cases). Member B's meta, B's authored-cube query and B's saved-dataset query equal B's baseline after member A's requests: refused (403 PERMISSION_DENIED), admitted (200 from A's definition, A's own row count), hidden-name (200, with no new refusal) and saved-name. The app's saved dataset is the control.

• dataset-i18n-label-resolution.test.ts: the zh-CN meta pin relied on queryDataset registering. It now registers through registerDataset first, and its intent is kept: a zh-CN query leaves the published titles in the source language.

• pnpm --filter @objectstack/service-analytics typecheck passes, and vitest run gives 130 files / 3053 tests, all passing. pnpm --filter @objectstack/dogfood typecheck passes, and the four analytics dogfood files give 28 tests, all passing.

Ablations (each run with the fix committed first, mutation landing proven on disk by scripts/ablation-replace.mjs, and restore proven by blob equal to HEAD plus an empty git diff HEAD):

• A, request-path registry write restored (unit). queryDataset calls registerDataset again. 10 of 12 go red. The two baselines stay green.
• B, admission set read from the shared registry (unit). The refused leg and the fresh-name leg go red, because the request resolved instead of rejecting. This shows that a scope applied to the strategy but not to the admission set would admit a read of the walled object.
• A, route level through dist/. Mutate, rebuild, then ablation-dist-preflight finds the marker present in 2 built files. 8 of 10 go red. In the first red leg, B's authored-cube query answers 400 INVALID_FIELD and B's meta lists the request's definition. The restore leg rebuilds, the marker is absent from all 6 built files, the tree is clean, and all 10 cases pass again.

Gates. node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands over this branch's 7 changed paths gives 66 commands. All 66 exited 0, and the --ran reconciliation reports 66/66 with 0 NOT MEASURED. check:dual-build-cjs-loads first exited 3 (PREREQUISITE NOT MET: 8 packages had no dist/). It passed after those packages were built, all from the turbo cache. eslint --no-inline-config over the 6 changed TS files, all in the config's **/*.{ts,…} population, gives 6 files, 0 errors and 0 warnings. The config enables no type-aware linting (no parserOptions.project or projectService) and no cross-file rules, so this diff cannot change the verdict on an untouched file. The repo-wide pnpm lint is left to CI.

Merge note for the later lander (PR #20348, analytics_cube.public)

PR #20348 adds assertCubePublic(queryInput.cube) at the top of query(). It reads this.cubeRegistry.get(name). Here, query()'s body lives in queryIn(scope, …), so a textual merge lands that line in queryIn, still reading the shared registry. It should read scope.getCube(name). Read from the shared registry, a dataset request named like a hidden cube would be refused 404 CUBE_NOT_FOUND with the hidden-cube message, which is a new refusal on this door and an existence signal for hidden names. The dogfood HIDDEN leg asserts 200, so a merge that leaves it on the shared registry goes red there. getMeta's visibility filter correctly stays on the shared registry.

Acceptance notes

• The /analytics/query and /analytics/sql doors still write the shared registry at request time, before admission (ensureCube inference and augmentation). This is reported in the dev report as a separate finding. The CubeScope seam added here is the natural place to scope them, but that changes the ad-hoc door's documented registry source and overlaps PR feat(analytics): enforce analytics_cube.public and default it to visible #20348's inferCubeFromQuery edit, so it is not done here.
• strategies/native-sql-strategy.ts (the join-allowlist comment near the getAllowedRelationships refusal) still says queryDataset registers the compiled dataset first. The invariant it states still holds, through the request scope: the allowlist answers from the compiled dataset and never falls through to the hook. The file is outside this card's declared surface, so the wording is left for whoever next touches it.
• The draft-preview branch still reads the pending seed rows before its own admission check. This is a read, and nothing is returned on refusal. It is unchanged.
• The one observable difference is stated in the changeset: a cube that only a queryDataset call compiled is no longer listed by getMeta() or queryable by name afterwards. No in-repo caller relies on that. A search for runtime code querying a dataset name as a cube found none.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/releases/v14.mdx (via generateSql (symbol, a method of class AnalyticsService))
• content/docs/releases/v16.mdx (via queryDataset (symbol, a method of class AnalyticsService))
• content/docs/releases/v9.mdx (via queryDataset (symbol, a method of class AnalyticsService))

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

• 2 changed file(s) yielded no anchor (packages/services/service-analytics/src/cube-registry.ts, packages/services/service-analytics/src/dataset-compiler.ts) — pages documenting those are invisible to this run
• 4 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 b1cbd9277719a7c524ac83bc183db1b3a77d4139 → packageMentionDocs.

Which tree this was computed on

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

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

⚠️ 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 b1cbd9277719a7c524ac83bc183db1b3a77d4139 → 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: 15e21b984cb0ac455cab80f57b1593451b96f125
Local-runs: none

① Derived judgments

• The published surface of @objectstack/service-analytics is unchanged. RIGHT.
  • The exports map addresses . only (dist/index), and src/index.ts is not in the diff.
  • CubeScope and CubeReads are module-private interfaces. compile, queryIn, requestScope, scopedService and cubeReads are private methods, and sharedScope and configuredAllowedRelationships are private fields. None is reachable from the entry type graph.
  • The spec contract IAnalyticsService (packages/spec/src/contracts/analytics-service.ts:182-231) is untouched, and registerDataset and queryDataset keep their signatures.
  • StrategyContext (strategies/types.ts) is untouched; getCube, getAllowedRelationships and getDatasetScope pre-existed.
  • The dev's "no spec or public-surface change" holds.
• registerDataset behaves exactly as before. RIGHT.
  • At base, :1426-1444 compiled with compileDataset(dataset, resolver, options), then wrote cubeRegistry.register + datasetRegistry.set.
  • The head splits the same body into a private compile (with identical options: getObjectDatasource, isExternalObject, declaredFieldType) plus the same two writes, at :1548-1549.
  • The constructor's config.datasets loop (:994-998) still calls registerDataset, so boot registration is unchanged, as triage required.
• No request-time write into the shared registries remains reachable from queryDataset. RIGHT.
  • The base's first statement, this.registerDataset(dataset) at :1458, becomes this.compile(dataset) at head :1605.
  • Every this.cubeRegistry.register at head is one of:
    • :969, the shared scope's register, reached only by query / generateSql on sharedScope;
    • :974, the constructor's registerAll;
    • :1548, registerDataset.
  • The only this.datasetRegistry.set is at :1549.
  • On a dataset call, ensureCube's two mints (scope.register) go to the request scope's own Map. That is the second write the card's suggested shape missed, and the unit test's fresh-name/augmented leg pins it (cubeRegistry.names() unchanged after an amount_sum augmentation).
• Every name-keyed read on the dataset query path goes through the request scope. RIGHT.
  • ensureCube reads scope.getCube.
  • queryObjects(query, scope) feeds both the admission set (callCtx :1214, assertReadAdmitted) and the read-scope set (resolveReadScopes).
  • The strategy context's getCube / getAllowedRelationships / getDatasetScope are cubeReads(scope), spread into the per-call ctx. resolvedDatasetScopeGetter takes reads.getDatasetScope rather than this.baseCtx, and no this.baseCtx. member read remains.
  • Strategies read only ctx.getCube (native-sql :163 / :287 / :331 / :391 / :403; objectql :148 / :363) and ctx.getAllowedRelationships (native-sql :558). resolveFkAttr reads ctx.getReadScope and ctx.executeAggregate only.
  • DatasetExecutor reads compiled.cube directly, and issues service.query with the cube set to compiled.cube.name (:1351) through the scoped face. It never calls getMeta.
  • The request scope answers getCompiledDataset for the call's own name, so the join allowlist and the dataset scope come from the call's dataset, exactly as the pre-fix registration made them.
• Admission still runs before any side effect, and refuses the same set. RIGHT.
  • The queryIn order is ensureCube → callCtx (admission, read scopes) → strategy, identical to base. compile throws the same compile-time refusals registerDataset threw.
  • The added source lines contain zero throw, code = or status =, so there is no new refusal, honouring triage note 3 (no collision refusal).
  • The route pins assert that the refused leg is still 403 PERMISSION_DENIED.
• Concurrent requests are isolated. RIGHT. requestScope builds a fresh Map per call (:1559), scopedService a fresh face (:1580), and callCtx a fresh ctx object; no instance field is written on the dataset path.
• The POST /api/v1/analytics/dataset/query accept set is unchanged. It has the same admission, read scope and refusals. The datasetName branch resolves through the metadata protocol (rest-server :11252-11259), not the analytics registry, so saved datasets serve as before (the route CONTROL leg).
• POST /analytics/query, POST /analytics/sql and GET /analytics/meta behave identically to base on the shared scope (query :1426, generateSql :2161-2162, getMeta :2124-2128). The one exception is that a request-compiled dataset's name no longer becomes a registered cube afterwards. The ad-hoc doors' own ensureCube writes are, in effect and order, byte-for-byte the base's :2073 / :2141 writes: not made worse, and correctly filed as analytics: an ad-hoc /analytics/query or /analytics/sql request writes inferred and augmented cubes into the shared registry before admission, so a refused request still changes every member's meta #20381. Judged under ②.
• The hidden-cube leg: the NOT MEASURABLE claim is true, and the substitute pin is honest. RIGHT.
  • git grep -w public over the non-test src of service-analytics, runtime and rest at head finds no reader of Cube.public.
  • The positive control is the three writers (public: false at analytics-service.ts :2819, cube-registry.ts :165, dataset-compiler.ts :689) and the schema field (packages/spec/src/data/analytics.zod.ts:398).
  • assertCubePublic is absent at head, so feat(analytics): enforce analytics_cube.public and default it to visible #20348 has not landed.
  • What is pinned instead is declared as a substitute, not passed off as the hidden leg: the registry entry toBe(HIDDEN_SUMMARY) with public false (unit), and B's whole meta equal to baseline (route).
• In-repo reliance on the removed side effect: none. RIGHT.
  • The non-test .queryDataset( callers are the REST door (rest-server.ts :11319) and metadata-protocol/src/build-probes.ts:343, which reads rows and queries nothing by name afterwards.
  • The same pathspec finds .registerDataset( at analytics-service.ts :997 as the positive control.
  • No runtime code queries a dataset name as a cube, and Test Core plus the Dogfood Regression Gate are green on this head.
• The tests assert the ADR-0112 envelope on every refusal case.
  • Unit: rejects.toMatchObject with code PERMISSION_DENIED and status 403 (two legs × two strategies).
  • Route: status 403 and body code PERMISSION_DENIED (the REFUSED and CONTROL legs × two drivers).
  • The counts match the body: 6 legs × 2 strategies = 12; 5 legs × 2 drivers = 10.
• Check-runs on the head: 39 runs. The latest per name are all success or skipped, with no failure at any generation. All seven required contexts are success, including Check Changeset. No governed surface is among the 7 paths.
• Disclosure discipline holds. The PR body and the changeset describe the defect at the code-path level (which method wrote which registry before which gate), with no request recipe.

② Semver level

• The changeset .changeset/20356-query-dataset-request-scope.md is "@objectstack/service-analytics": patch, with Clause-②: no and no arm, and the PR body carries the same line. Nothing widens (no new export, config key, accepted key or value), so no is truthful, and the WHICH LEVEL rule (a fix( that changes no public surface stays patch) is met.
• The narrowing question, tested. The changeset's "one observable difference" is real at public doors: a cube that only a queryDataset call compiled is no longer listed by getMeta(), nor queryable by name via query() / POST /api/v1/analytics/query. It is NOT a narrowing of a published accept set:
  • the published statement of those doors (content/docs/api/data-api.mdx: "registered cubes ... explicitly defined via defineCube or the cubes config ... lazily auto-inferred") never admitted a dataset name registered by a query;
  • the spec contract's queryDataset declares compile-then-run, with no registration;
  • that acceptance existed only as process state written by the very defect this card names, and the card's triage ordered its removal.
    This is a pull-back to the declared contract, in line with this package's own precedent: the 17.3.0 patch entries b0d7d54, 967402a and 5c7cbe3 stop over-reach the platform previously accepted, and were graded patch without a BREAKING banner. It is unlike 17.2.0 57e4571, which refused an input the contract admitted.
    So patch, Clause-②: no with no (narrowing) arm, no BREAKING banner and no ADR-0087 marker is the RIGHT declaration. The changeset still names the difference and a remedy, which is the disclosure a reader needs. The Clause-②: line is judged RIGHT.
• The changeset prose, read sentence by sentence against the code: every "what changes" and "what does not change" sentence is true:
  • registration before run, at base :1458;
  • the request-local lookup for the cube, the admission and read-scope sets, the join allowlist, the dataset scope, and inferred measures;
  • the same admission and refusals;
  • registerDataset and configured cubes untouched;
  • no collision refusal.
    Two nits, below.

③ Boundary flags

• open_questions: empty; nothing to answer.
• Deviation 1 (the edited dataset-i18n-label-resolution.test.ts): the one case asserted the removed registration side effect. It now calls registerDataset first, and its intent (a zh-CN query leaves meta in the source language) is kept. Accepted.
• Deviation 2 (model-free commit trailers): all five non-merge commits carry Claude-Session + Co-authored-by: Claude with no model identifier. That is AGENTS.md compliance, not a deviation. Accepted.
• Deviation 3 (main advanced, not re-merged): the PR reads mergeable: true, state clean, and the queue rebuilds on the current main. Accepted.
• Deviation 4 (the scratch probe deleted): the file list is exactly the 7 declared paths. Accepted.
• Out of scope (a), the ad-hoc doors' shared writes before admission: the writes and their order are identical to base, and the seat filed them as analytics: an ad-hoc /analytics/query or /analytics/sql request writes inferred and augmented cubes into the shared registry before admission, so a refused request still changes every member's meta #20381. Accepted as out of scope; this PR does not worsen them.
• Out of scope (b): strategies/native-sql-strategy.ts:579-581 still says "queryDataset registers the compiled dataset first, so getAllowedRelationships answers from datasetRegistry". That is now false as a description of the mechanism, but the invariant it protects still holds through the request scope's getCompiledDataset: the legacy hook is unreachable from the dataset door. NIT: no behavioural consequence; a follow-up wording fix outside the claimed surface.
• Out of scope (c): the draft preview reads draftRowsResolver before its own assertReadAdmitted (head :1615-1629). It is pre-existing and unchanged, a read whose rows never leave on refusal. Accepted; noted.
• Cross-seat hazard with feat(analytics): enforce analytics_cube.public and default it to visible #20348 (assertCubePublic must read scope.getCube): posted on analytics: an authored cube's public, refreshKey, format, granularities and descriptions take effect (8 keys) #20282, and not this PR's defect. The dogfood HIDDEN leg, asserting 200, is the tripwire. Accepted.
• NIT (changeset prose): "queryable by name through query() / POST /api/v1/analytics/query". The same shared-scope lookup also serves generateSql() / POST /analytics/sql and getMeta(cubeName); the sentence names one query door. No reader would conclude differently.
• NIT (changeset prose): the remedy "register it through registerDataset or AnalyticsServiceConfig.datasets" is reachable only by an embedder constructing AnalyticsService. AnalyticsServicePlugin exposes cubes only (plugin.ts :146), and it holds the service in a private service? field (:287). This is not false, since the changeset scopes the door to "AnalyticsServiceConfig.datasets and embedders", but it is incomplete for the plugin composition. No in-repo consumer needs it.
• Not a finding: the PR body's ablation paragraphs are process claims, not re-run here (a read-only review). The head's check-runs are the gate verdicts.

Implemented-by: claude/issue-20356-inline-dataset-isolation
Reviewed-by: session_01TEah6PeJGjxJfbHaySJjLQ

VERDICT: PASS

---

Generated by Claude Code