Merge remote-tracking branch 'origin/main' into claude/showcase-action-visible-matrix

Author: baozhoutao

.changeset/action-session-positions-runtime-dual-emit.md

@@ -0,0 +1,58 @@
+---
+"@objectstack/runtime": major
+---
+
+feat(runtime)!: action body `ctx.session` emits `positions` (canonical) alongside the deprecated `roles` (#5613)
+
+`buildActionSession()` — the one producer of the action-body `ctx.session` — now
+emits the caller's position names under **both** `positions` (canonical) and
+`roles` (deprecated alias), with the same array under both names. This is the
+**runtime half** of #5613 phase 2 under the maintainer's contract-first ruling
+("C skeleton + A semantics"); the spec half (#5779) declared the shape this now
+produces, and phase 1 (#5697) declared the shape it produced before.
+
+**What was wrong.** The builder copied `ExecutionContext.positions` into a key
+spelled `roles` — the one spelling ADR-0090 D3 bans — while its own docblock
+claimed it "mirrors the hook `ctx.session` shape". That sentence stopped being
+true at #5050, which retired `HookContext.session.roles` outright: a body author
+met two different answers to one key name on one platform, and the comment
+pointed at the wrong one. The key set reached no schema and no gate until #5697,
+so nothing could see it drift.
+
+**Migration prescription — do this now.**
+
+- Read `ctx.session.positions`. It carries exactly the array `ctx.session.roles`
+  carried (`ExecutionContext.positions` — the rename is a rename, not a semantic
+  change), and it is the spelling the platform now uses everywhere: the
+  execution context, the sharing service, `ctx.user.positions`, and the hook
+  `ctx.session.positions` (#5605).
+- `ctx.session.roles` still resolves for the length of the deprecation window
+  announced by the ADR-0087 semantic migration
+  `action-session-roles-to-positions`, and is then removed on the path
+  `session.tenantId` already walked (#3280 deprecated → #3290 removed in v11). A
+  body still reading it at that point sees `undefined` with nothing to catch the
+  change — which is why the read moves **inside** the window, not at its close.
+- Do **not** migrate an access check by renaming it. `roles.includes('admin')`
+  rewritten as `positions.includes('admin')` migrates the defect: neither array
+  is an authorization input. Privilege is judged by the security service, which
+  evaluates capability grants, placements and the derived posture (ADR-0095).
+- Presence semantics are unchanged: a context with no positions (or a non-array
+  `positions`) yields **neither** key — `'positions' in ctx.session` answers
+  `false` exactly when `'roles' in ctx.session` does — and a call with no
+  identity envelope still yields no session at all rather than `{}` (#3712).
+
+**Also breaking, for TypeScript consumers of the sandbox seam.**
+`ScriptContext.session` (`@objectstack/runtime`, `sandbox/script-runner.ts`) was
+`unknown` and is now the exported union `ScriptSession = ActionSession |
+HookContext['session']` — the two declared producer shapes this one seam
+actually carries. Code that read an arbitrary property off it must now
+discriminate the body kind (or read one of the keys both shapes declare:
+`userId`, `organizationId`, `positions`). It is deliberately **not** narrowed to
+`ActionSession` alone: the seam really does carry hook sessions, and declaring
+otherwise would re-create the "one key, two realities" defect this change
+closes.
+
+The consistency between what the producer builds and what `ActionSessionSchema`
+declares stays pinned in
+`packages/runtime/src/action-session-shape-contract.test.ts`, and the observed
+shape is verified through a real dispatch in `http-dispatcher.test.ts`.

.changeset/analytics-dataset-degradation-envelope-first.md

@@ -0,0 +1,66 @@
+---
+"@objectstack/service-analytics": patch
+---
+
+fix(analytics): a dataset refusal that declares an ADR-0112 envelope is never degraded to an empty result (#5717)
+
+`queryDataset` wraps execution in a catch that exists for one deliberate reason
+(#5033): a widget whose backing object is not mounted in this kernel renders
+"no data" instead of failing with a 500. The criterion for "not mounted" was
+`isMissingSourceError` — a substring match over the error MESSAGE. So the
+leniency was available to any error that happened to phrase itself like a
+driver, and #5352 / #5367's finding on the REST face — "the wire shape of an
+error family must not be a property of its wording" — applied here one level
+worse: the outcome was not a wrong status code but a **silent empty result**.
+No exception, no 4xx, no 5xx; one `warn` line and a confident empty chart, which
+is the "populated table, Total Spend: 0" symptom #5033 was filed about.
+
+One refusal already matched. `dataset-compiler.ts` refuses an `include` naming a
+relationship the object graph does not have with
+
+> `[dataset-compiler] dataset "X" includes relationship "R" which does not exist on object "O".`
+
+which carries both `relation` (inside "relationship") and `does not exist` — and
+that conjunction was the postgres limb. It has never gone off for one reason:
+`queryDataset` compiles **before** the try, so that throw has never been inside
+the catch's reach. A mine, wired and unarmed.
+
+**Two independent defences, so the disarming does not depend on either one.**
+
+- **The criterion (main change).** An error carrying an ADR-0112 envelope —
+  numeric `status` + non-empty `code`, the same structural fact
+  `rest-server.ts`'s `/analytics/dataset/query` catch reads — is re-thrown
+  untouched, ahead of any message inspection. Its producer already answered the
+  classification question. The status RANGE is deliberately not part of the
+  test: a `DATASET_INVALID` / 400 rendered as an empty grid is the loud case,
+  but a declared 5xx (`READ_SCOPE_COMPILE_FAILED` — an RLS lowering that failed
+  closed) is if anything worse to swallow, since nobody is told at all.
+- **The sniffer.** Its postgres limb is now anchored to postgres's actual
+  wording (`relation "x" does not exist`) instead of "any sentence containing
+  both words" — the same pattern the sibling `missingSourceRelation` already
+  used, so "is something missing" and "what is missing" can no longer disagree.
+
+**Observable behaviour change — read this if you alert on empty widgets.** The
+guarantee is new, not the status of any shipped message: measured over the 13
+real wordings this repo carries (three driver families including sql-prefixed
+and schema-qualified forms, the framework's not-registered signals, and this
+package's own refusals), exactly one verdict moves — the compiler refusal above,
+which reaches callers as `400 DATASET_INVALID` either way because its throw site
+sits outside the try. What changes is that a caller-shaped refusal raised
+**during execution** can no longer become `{rows: [], fields: [], totals: []}`
+by phrasing alone: it now propagates and the route answers its declared code
+(4xx as itself, declared 5xx through `ANALYTICS_QUERY_FAILED`). A dashboard that
+silently rendered an empty chart for such a refusal will now surface the error.
+
+**#5033's leniency is untouched, and that is asserted rather than claimed.** A
+bare driver error is still classified by its words and still degrades: `no such
+table` (sqlite/libsql), postgres's real `relation "x" does not exist`, mysql's
+`doesn't exist`, the framework's not-registered signals — and a bare error
+naming a JOINED table still fails loudly as a cross-datasource dataset. Those
+cases are green in all four states of the reverse verification
+(`dataset-degradation-envelope.test.ts`), including with both defences reverted.
+
+The compile point deliberately stays outside the try. Moving it in would newly
+expose the compiler's own bare invariants and the host-supplied relationship
+resolver to this degradation path — widening leniency in the opposite direction
+from the fix.

.changeset/analytics-filter-normalizer-null-safe-negation.md

@@ -0,0 +1,40 @@
+---
+'@objectstack/service-analytics': patch
+'@objectstack/spec': patch
+---
+
+analytics: `$ne` / `$nin` / `$notContains` in a dashboard `where` keep the rows that have no value
+
+Second batch of the #5298 ruling, after PR #5962 landed it on `driver-sql`,
+`read-scope-sql` and `formula`. An analytics filter meaning "not this" now
+returns the rows whose column is empty, the same answer every other backend
+gives — a `stage != 'won'` widget shows the deals with no stage set.
+
+The Cube face was the last surface still splitting on it, and it split three
+ways for one filter. Measured on the package's own fixture before the change,
+for `{stage: {$ne: 'won'}}` with rows 3-4 carrying a NULL `stage`:
+
+| compiler | was | now |
+|---|---|---|
+| `NativeSQLStrategy` raw SQL | `2` | `2,3,4` |
+| `ObjectQLStrategy` display-SQL echo | `2` | `2,3,4` |
+| `ObjectQLStrategy` engine condition | `2,3,4` | `2,3,4` |
+
+The engine column was already right — because `driver-sql` guards for itself
+since #5962, not because the analytics layer did — so which rows a widget drew
+depended on which compiler downstream caught the leaf, and the `/analytics/sql`
+echo described a narrower query than the one that ran.
+
+`filter-normalizer` now emits the guard as tree STRUCTURE (an `or` of the null
+predicate with the comparison) rather than as a SQL trick in one strategy, so
+all three compilers of that tree produce one predicate and none of them needs
+to know the rule. Which operators are guarded is decided by the polarity table
+the `$not` rewrite already consults, not by a second list of operator names:
+positive comparisons (`$eq`, `$in`, `$contains`, the ordering family) compile
+byte-identically to before, `$ne: null` stays `IS NOT NULL`, an empty `$nin`
+stays the TRUE constant, and `{$not: {stage: {$ne: 'won'}}}` still means
+"stage is won" rather than widening.
+
+`FILTER_LOGIC_CASES` is unchanged: the `$ne` and `$not` null rows enrol in
+#5903's PR, which clears the last backend (`driver-turso` remote). The spec
+table's measured blocker matrix drops the Cube row it no longer describes.

.changeset/analytics-query-declared-fault-withhold.md

@@ -0,0 +1,87 @@
+---
+"@objectstack/types": minor
+"@objectstack/runtime": minor
+"@objectstack/rest": patch
+---
+
+fix(runtime,types)!: `/analytics/query` no longer echoes RLS policy field names — the declared-server-fault withhold is shared by both HTTP boundaries (#5811)
+
+**Observable behaviour change — read this if you read, log, or assert on
+`error.message` from a dispatcher-plugin route.** An error that **declares a
+server fault** in the ADR-0112 envelope (`status >= 500` *and* a non-empty
+`code`) now leaves `dispatcher-plugin.errorResponseBase` with its message
+replaced by `"Internal server error"`. It previously reached the caller verbatim
+unless it happened to *sound* like a SQL/driver dump. This applies to every route
+that plugin mounts — `/analytics`, `/packages`, `/i18n`, `/automation`, `/auth`,
+`/notifications`, `/mcp`, … — not only the one that motivated it. Nothing a
+machine reads changed: the producer's `code` still arrives in the response
+(`error.code`, promoted there from `details` by the shared envelope builder,
+#3842), the status is untouched, and the full original text still goes to the
+server log and `errorReporter` via `__obsRecordedError`.
+
+## What was wrong
+
+#5367 (maintainer ruling 2026-08-06) made `read-scope-sql.ts`'s ten fail-closed
+RLS lowering refusals `READ_SCOPE_COMPILE_FAILED` / 500 and taught
+`POST /analytics/dataset/query` to withhold their message, because those messages
+name the field names and comparands of an **administrator's** sharing rule:
+
+```
+[read-scope-sql] unsafe field identifier "secret_policy_field" — refusing to
+build read scope (fail-closed).
+```
+
+The caller never wrote that field name and must not be able to read it out of an
+error body. But the **sibling** analytics face was never closed.
+`compileScopedFilterToSql` runs on both `NativeSQLStrategy.applyReadScope` and
+`ObjectQLStrategy`'s echoed SQL, both of which serve `POST /analytics/query`,
+which exits through `dispatcher-plugin.errorResponseBase`. That exit's only
+message guard was `looksLikeInternalErrorLeak` — a heuristic over SQL/driver
+*phrasing* — and all eleven read-scope message shapes return `false` from it.
+Measured at that boundary: **11 of 11 echoed verbatim**, at 500, with the policy
+content in `error.message`. A real reachable disclosure, not a theoretical one.
+
+## What changed
+
+- **`@objectstack/types` gains `declaresServerFault(err)`**, exported from
+  `error-leak.ts` beside `looksLikeInternalErrorLeak`. The heuristic asks whether
+  a message *sounds* internal; the declaration asks whether the producer *said
+  so*. `error-leak.ts`'s own file header already states the principle — "do not
+  ship driver internals to clients" is a property of the HTTP boundary, not of
+  one router — and this is the second predicate that principle asks for.
+- **Both boundaries read it.** `dispatcher-plugin.errorResponseBase` gains the
+  withhold (the fix); `rest-server.ts`'s `/analytics/dataset/query` catch drops
+  its in-line copy of the same test in favour of the shared one. #5808 wrote that
+  rule in-line on purpose — promoting a rule with one consumer is a speculative
+  surface — and this is the second consumer, so it was promoted rather than
+  duplicated (`#3843`/`#3867` paid for the two-implementations shape twice).
+  The REST face's verdict is unchanged in every case: same `status >= 500` plus
+  non-empty `code` test, over the same two fields.
+
+## What deliberately did NOT change
+
+- ⛔ **This is not "withhold every 5xx".** #5667 kept **undeclared** 5xx errors
+  legible on purpose: a bare `Error` from our own code ("no strategy can handle
+  query …") is the operator's own bug report, names nothing tenant-sensitive, and
+  still falls to `looksLikeInternalErrorLeak` alone. A 5xx carrying only half an
+  envelope (a status with no code) is likewise still readable — inventing the
+  withhold for it would be the consumer-side leniency Prime Directive #12 removes.
+- **4xx is untouched.** `declaresServerFault` requires `status >= 500`, so a
+  deliberate business/validation answer can never be swallowed by it.
+- **`statusCode` is not accepted as a substitute for `status`.** `status` is the
+  channel ADR-0112 declares; making a disclosure rule depend on which spelling a
+  producer reached for would be the same leniency in a different place.
+- **The heuristic was not taught to recognise `[read-scope-sql]`.** That would be
+  more prose sniffing — the mechanism #5352/#5367 exist to remove — and would only
+  ever cover the family someone remembered to add.
+
+Coverage: `analytics-query-read-scope-withhold.test.ts` (runtime) drives six RLS
+policy shapes end-to-end through a **real** `AnalyticsService` on the real
+native-SQL path and the real mounted route, asserting the 500, that the whole
+serialized body contains no policy detail, that `error.code` still carries
+`READ_SCOPE_COMPILE_FAILED`, and that the full text is still on the
+`__obsRecordedError` side-channel — plus a positive control and both sides of the
+declared-vs-undeclared tiering. `error-leak.test.ts` (types) pins the predicate
+directly, including that all eleven read-scope shapes stay invisible to the
+heuristic. The REST face's existing `analytics-read-scope-refusal-envelope.test.ts`
+is green before and after, unchanged, which is the pin on the refactor.