Merge remote-tracking branch 'origin/main' into claude/rest-read-path-field-degradation-4240d5

Author: os-zhuang

.changeset/console-pin-pr-gate.md

@@ -0,0 +1,48 @@
+---
+---
+
+ci: build the pinned objectui SHA on the PR that moves it (#4290)
+
+`.objectui-sha` is the single source of truth for the vendored Console SPA —
+release.yml reads it, clones objectui at that commit, builds
+`@object-ui/console` and copies the dist into `packages/console/`. Editing that
+one line replaces the entire frontend the platform ships, and nothing on the PR
+side ever built it.
+
+The pin appeared in exactly two workflows, neither a gate: release.yml
+(post-merge, on the main push) and showcase-smoke.yml (manual + nightly, whose
+own header says "it never gates PRs"). It is also a root dotfile, so it matched
+neither of ci.yml's `core` and `docs` filters — #4288 moved the pin 76 commits
+with six of fourteen checks skipped, including Build Core, Test Core, Build Docs
+and the Dogfood gate. A SHA that cannot build — a typo, a commit that was
+force-pushed away, a broken objectui, a dead bundle canary — reached `main`
+green and would have surfaced at publish time. The only thing between the two
+was the author remembering to run `scripts/build-console.sh` locally.
+
+Adds ci.yml's `Console Pin Gate`: a `console` paths filter over `.objectui-sha`,
+`scripts/build-console.sh` and the two files that gate them, and a job that
+builds `@object-ui/console` at the pin against this tree's `@objectstack/client`
+and then runs `pnpm check:console-sha`.
+
+Two details that keep it honest rather than merely green:
+
+- It restores `packages/console/dist` under **release.yml's existing cache key**
+  (`hashFiles('.objectui-sha', 'scripts/build-console.sh')`), so only a pin the
+  repo has never built misses — and a miss is exactly when the gate has work to
+  do. Watching the workflow and the drift guard therefore costs about a minute,
+  not a full vite build.
+- The restore/save pair is **split**, where release.yml uses the combined
+  action, because the combined post-step saves even when the job failed.
+  `build-console.sh` writes the SHA stamp before it asserts the bundle canary,
+  so a canary failure leaves a stamped-but-broken dist that would be cached,
+  restored, and then waved through the stamp check. Saving only once every
+  assertion is green is what lets a restored dist carry the same guarantees as a
+  freshly built one. A separate step asserts a real dist is on disk first, since
+  `check:console-sha` deliberately exits 0 when there is no dist at all.
+
+Scope, stated plainly: this proves the pinned SHA builds. It does not cover a
+`packages/client` change breaking the injected-client bundle — that input lives
+under `packages/**`, and watching it here would rebuild the console on a large
+fraction of every PR. release.yml remains the only check for that direction.
+
+CI and docs only; this releases nothing.

.changeset/d12-fake-inventory-gate.md

@@ -0,0 +1,7 @@
+---
+---
+
+test-only: the D12 honesty gate iterates the known-fake inventory — every
+`CORE_FALLBACK_FACTORIES` product registered slot-by-slot must come out of
+both discovery builders as `degraded`, never `available` (#3898 suggestion 4;
+`cache`/`queue`/`job` had no per-slot pin before). Releases nothing.

.changeset/datasource-routes-catch-service-throws.md

@@ -0,0 +1,38 @@
+---
+"@objectstack/service-datasource": patch
+"@objectstack/rest": patch
+---
+
+fix(service-datasource,rest): the last three uncovered datasource routes answer their registered refusal code (#4264)
+
+#4249 (fixed in #4263) gave the rest surface's two introspection routes a
+failure contract; this closes the same gap on the three sibling routes it left
+uncovered. Each had no `catch` around its service call, so a service throw was
+swallowed by the adapter and surfaced as the pre-#3675 non-envelope
+`500 { error: 'No response from handler' }` — no `success` flag, no
+`error.message`, no code to switch on, real cause lost.
+
+Wire-visible changes — each route now answers `400` in the declared envelope,
+under the refusal code registered (ADR-0112) for the service it dispatches to,
+with the service's own message at `error.message`:
+
+- `GET /api/v1/datasources` (`listDatasources` throw) →
+  `400 DATASOURCE_ADMIN_ERROR` — matching its eight siblings in
+  `service-datasource/admin-routes.ts`, which already answer their catches this
+  way.
+- `POST /api/v1/datasources/:name/external/refresh-catalog` (`refreshCatalog`
+  throw) and `POST /api/v1/datasources/:name/external/validate` (`validateAll`
+  throw) → `400 EXTERNAL_DATASOURCE_ERROR` — the same code #4249 gave the two
+  introspection routes one block above them.
+
+The issue left the code choice open (`INTERNAL_ERROR` was the alternative);
+the registered per-service codes win on consistency: every other catch in both
+modules — including pure reads — already answers 400 with the service-attributed
+code, and `refreshCatalog`'s dominant throw class (unknown datasource,
+unreachable remote, no such schema) is the one #4249 already adjudicated as a
+400 refusal on `listRemoteTables`. A 500 here would fork the failure contract
+within a module — the drift #4249 removed.
+
+No new codes: both were registered in the error-code ledger by #4263. The
+envelope-conformance suites and the `REFUSALS` pin table gain one row per
+route.

.changeset/dev-plugin-production-hatch-brands.md

@@ -0,0 +1,61 @@
+---
+"@objectstack/plugin-dev": patch
+"@objectstack/types": minor
+---
+
+fix(plugin-dev,types): the production escape hatch stops being silent (#3900)
+
+`DevPlugin.init()` refuses to run under `NODE_ENV=production` (ADR-0115 D6), and
+`OS_ALLOW_DEV_PLUGIN` overrides that refusal. As shipped, the override returned
+early with **no output at all**: the process ran the development assembly while
+every log line and the ready banner read like an ordinary production start.
+
+That reproduces, one level up, the defect the guard exists to close. The guard's
+own precedent says so — `OS_ALLOW_DEGRADED_TENANCY` boots degraded *and brands
+it everywhere an operator looks*, and `OS_ALLOW_DRIVER_CONNECT_FAILURE`'s
+contract is "logged loudly at startup". An escape hatch that says nothing leaves
+the operator's only evidence of a degraded state in an env var they may not have
+set themselves.
+
+**The override now brands itself, twice.** A warning at `init()` — emitted
+before any assembly work, so it survives an assembly step that later throws —
+and a repeat on the ready banner, which is the surface an operator actually
+reads:
+
+```
+⚠ DEV ASSEMBLY UNDER NODE_ENV=production (OS_ALLOW_DEV_PLUGIN is set) — the boot
+  guard was explicitly overridden. This process is running the DEVELOPMENT
+  assembly, which is not hardened for production traffic (ADR-0115 D6).
+    • Auth secret is the default published inside @objectstack/plugin-dev. It is
+      public, so anyone can mint a session this stack accepts. Pass `authSecret`
+      explicitly.
+    • Data goes to the in-memory driver with persistence disabled — every record
+      is lost when this process exits.
+```
+
+Only hazards that are live for *that* configuration are named: the secret line
+is suppressed when the operator passed their own `authSecret`, and the driver
+line when the `driver` toggle is off. The dev-admin seed is deliberately absent
+— `plugin-auth`'s `maybeSeedDevAdmin` is hard-gated to
+`NODE_ENV === 'development'` and cannot fire on this path, so warning about it
+would spend the attention the real hazards need.
+
+**New export — `resolveAllowDevPlugin()` (`@objectstack/types`).** The flag moves
+off a bare `process.env['OS_ALLOW_DEV_PLUGIN'] === '1'` and joins the
+`OS_ALLOW_*` family's shared truthy vocabulary, next to
+`resolveAllowDegradedTenancy` / `resolveAllowDriverConnectFailure`.
+
+FROM → TO for operators: `OS_ALLOW_DEV_PLUGIN=1` keeps working unchanged.
+`OS_ALLOW_DEV_PLUGIN=true` (and `on` / `yes`, case-insensitive, surrounding
+whitespace ignored) **now takes effect** where the strict comparison previously
+ignored it and failed the boot. That is a widening, in the direction an operator
+setting the flag already intended; falsy and unrecognised values still refuse to
+boot, and unset still means "fail fast". If you were relying on
+`OS_ALLOW_DEV_PLUGIN=true` being inert as a way to keep the guard armed, unset
+the variable instead.
+
+No change to the refusal path, which this issue re-verified end to end:
+`kernel.use()` only registers, `initPluginWithTimeout` does not catch,
+`bootstrap()` rethrows, and `os serve`'s outer handler prints the message and
+exits `1`. The `throw` is genuinely fatal here, so it needs none of the
+`process.exit(1)` the tenancy guard required for sitting inside a broad `catch`.

.changeset/drop-per-package-lint-scripts.md

@@ -0,0 +1,4 @@
+---
+---
+
+fix(dx): remove the per-package `lint` scripts (`eslint src`) from `@objectstack/verify`, `@objectstack/cli` and `@objectstack/lint` (#4276). A standalone run resolves the root flat config but honors the inline directives the root gate's `--no-inline-config` exists to ignore, so it fails on rules the config never registers — verify was red on a clean HEAD. Lint only from the root; the scoped recipe is documented in `eslint.config.mjs`. Dev scripts only; releases nothing.

.changeset/hono-retire-standard-endpoints.md

@@ -0,0 +1,40 @@
+---
+"@objectstack/plugin-hono-server": major
+---
+
+feat(plugin-hono-server)!: delete the CRUD/discovery convenience surface and the `registerStandardEndpoints` flag — the plugin is a transport adapter (#4073)
+
+Completes the retirement. `HonoServerPlugin` now owns the socket, the middleware
+and the three current-user endpoints, and nothing else. The data and discovery
+APIs have one owner each: `@objectstack/rest` and the runtime dispatcher
+(ADR-0076 D11).
+
+**Removed**
+
+- `POST/GET /api/v1/data/:object` and `GET /api/v1/data/:object/:id` — the raw
+  C+R surface that delegated straight to ObjectQL.
+- `GET /api/v1/discovery` and `GET /.well-known/objectstack` — this plugin's
+  third discovery payload, which predated `DiscoverySchema` and could not
+  satisfy it (no `services`, the ADR-0076 D12 source of truth).
+- The `registerStandardEndpoints` option. It is gone, not defaulted off: passing
+  it is now a type error, and passing it via `as never` mounts nothing.
+
+**Unaffected**
+
+- `/auth/me/permissions`, `/auth/me/localization` and `/me/apps` — this plugin
+  is the platform's only supply and they register unconditionally (#4144).
+- Every composed host: `os serve`, `objectstack dev`, cloud's objectos and every
+  documented composition mount REST and/or the dispatcher, which already served
+  these routes and answered byte-identically with the flag on or off (#4260).
+
+**Migration** — only a host that mounts `HonoServerPlugin` with neither owner is
+affected. It now has no data or discovery API, and the boot warns once naming
+both remedies. Mount `createRestApiPlugin` from `@objectstack/rest` for full
+CRUD behind the gate stack, or `createDispatcherPlugin` from
+`@objectstack/runtime`. There is no flag to opt back in.
+
+**Why** — the surface was duplicate and lesser supply (C+R only, a subset of the
+gates, a non-conforming discovery payload), and it charged rent: #2567, #3298
+and #4018 each had to re-implement a platform invariant on it after the fact,
+because a second implementation of a route is a second place every future
+invariant must be remembered.

.changeset/query-cursor-removed.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": major
+"@objectstack/client": major
+---
+
+refactor(data)!: `query.cursor` is removed — no driver ever implemented keyset pagination (#4286 step 4)
+
+`cursor` promised keyset pagination and nothing served it: the key was accepted
+and ignored, so every page came back identical — a caller looping "until
+`hasMore` is false" never terminated. It was Tier A of the #4286 inventory: a
+shipped public producer (`QueryBuilder.cursor()`) minting a key no executor
+read.
+
+**FROM → TO**
+
+| Was | Now |
+| :--- | :--- |
+| `cursor: { created_at: last.created_at }` | `where: { created_at: { $gt: last.created_at } }` + the matching `orderBy` |
+| `QueryBuilder.cursor({...})` | `.where({ created_at: { $gt: ... } }).orderBy('created_at')` |
+
+The one-line fix: **delete the key and seek with `where` on your sort key** —
+every driver already executes that, with canonicalised temporal comparands.
+
+Mechanics: `retiredKey()` tombstones on both declaration sites
+(`QuerySchema.cursor` and `EngineQueryOptionsSchema.cursor`, one shared
+prescription), so authoring the key fails `tsc` and a query still carrying it
+fails to parse with the fix. `QueryBuilder.cursor()` is deleted. Registered as
+the protocol-18 semantic migration `query-cursor-retired` (request surface —
+nothing stored to rewrite). The caller-built `Record<string, unknown>` shape
+would not survive a real keyset design anyway: a first-class cursor, if ever
+built, will be a response-minted opaque token (the pattern the
+metadata-revision / flow-run / notification list endpoints already use — those
+`cursor` params are unrelated and unchanged).

.changeset/query-distinct-removed.md

@@ -0,0 +1,37 @@
+---
+"@objectstack/spec": major
+"@objectstack/client": major
+"@objectstack/metadata-protocol": minor
+---
+
+refactor(data)!: `query.distinct` is removed, and with it the mis-wired REST count suppression (#4286 step 4)
+
+`distinct` promised `SELECT DISTINCT` and no driver ever rendered it — but it
+was **mis-wired rather than merely dead** (#4286 finding 2, the harsher
+ADR-0078 class): its only observable effect platform-wide was that the REST
+list path treated a distinct query as *not countable*, silently degrading
+`total`/`hasMore` to a page-local estimate while still returning duplicate
+rows. A caller — or a self-verifying agent — saw the response change and
+concluded the flag worked. It had a shipped public producer
+(`QueryBuilder.distinct()`).
+
+**FROM → TO**
+
+| Was | Now |
+| :--- | :--- |
+| `distinct: true` for unique combinations | `groupBy: ['category']` |
+| `distinct: true` + count | `aggregations: [{ function: 'count_distinct', field: 'category', alias: '...' }]` |
+| one column's distinct values | the SQL/memory drivers' `distinct(object, field)` door (driver-level) |
+
+The one-line fix: **delete the key**; deduplicate with `groupBy` /
+`count_distinct`.
+
+Mechanics: `retiredKey()` tombstones on both declaration sites
+(`QuerySchema.distinct` and `EngineQueryOptionsSchema.distinct`, one shared
+prescription); `QueryBuilder.distinct()` is deleted; registered as the
+protocol-18 semantic migration `query-distinct-retired`. **Observable REST
+change (`@objectstack/metadata-protocol`):** the count-suppression branch is
+deleted — a list request that used to carry `distinct` now gets a real
+`total`/`hasMore` again (that restoration is the point, not a side effect).
+The per-aggregation `distinct` flag (`AggregationNode.distinct`) is a
+different, live member and is untouched.

.changeset/query-having-enforced.md

@@ -0,0 +1,39 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": minor
+"@objectstack/metadata-protocol": minor
+---
+
+feat(objectql)!: `query.having` is enforced — the engine applies it after aggregation (#4286 step 3, ADR-0049 resolved to enforce)
+
+`having` had been declared on the request surface since AST v2 and executed by
+nothing. #4286 finding 1 showed the gap was structural: `engine.aggregate()`
+rebuilt the driver AST with exactly `object`/`where`/`groupBy`/`aggregations`,
+so even a driver that *did* implement HAVING could never have received it, and
+the one wire path (`findData`'s aggregate branch) dropped the clause too. It
+was the strongest enforce candidate of the #4286 set — the clause every
+SQL-literate author (human or model) expects to work next to
+`groupBy`/`aggregations` — and it is now live end to end:
+
+- **Engine-owned, both paths.** `applyHaving()`
+  (`packages/objectql/src/having-filter.ts`) runs AFTER aggregation on the
+  native-driver path and the in-memory fallback alike — the same
+  correct-first / optimize-later two-tier shape date bucketing uses. Native
+  SQL `HAVING` pushdown can come later behind a driver capability flag without
+  changing semantics.
+- **Namespace: the aggregated row's own columns** — aggregation aliases
+  (`order_count`, `total`) and groupBy projections — with the ordinary
+  FilterCondition operators plus `$and`/`$or`/`$not`.
+- **An unknown operator rejects loudly.** Ignoring one (as tolerant matchers
+  do) would silently return unfiltered aggregates — the exact ADR-0078
+  silently-inert failure enforcement exists to end.
+- **The wire path forwards it.** `findData`'s aggregate branch passes
+  `having` through, and `EngineAggregateOptionsSchema` now declares it.
+- The FLS predicate guard already walked `having` references
+  (`predicate-guard.ts`), which is what made enforcement safe to turn on.
+
+No migration needed: queries that carried `having` before were silently
+returning every group; they now filter as written. A caller who depended on
+the clause being *ignored* (sending `having` and expecting unfiltered
+results) sees the corrected behavior — that is the enforcement, not a
+regression.

.changeset/sort-dotted-path-rejected.md

@@ -0,0 +1,37 @@
+---
+"@objectstack/metadata-protocol": patch
+---
+
+fix(data): a dotted-path `sort` (`?sort=account.company_name`) is rejected with `400 INVALID_SORT`, not silently unapplied (#4256)
+
+The one sort shape #4226 deliberately left open is now closed. A dotted path
+passed the sort gate on its head segment (`account` is a real field) and was
+then unusable by every driver: `SqlDriver` handed it to Knex, which rendered
+`"account"."company_name"` against a table that was never joined, and the
+#3821 unknown-column backstop retried **without the sort**; Mongo and the
+memory driver resolved the path against the row itself, where a foreign key is
+a scalar id. Result: `200`, every row present, arbitrary order — and since
+`sort` + `top` is how a caller asks for "the latest N", an arbitrary N with
+nothing in the response to reveal it.
+
+The rejection distinguishes the two mistakes a dotted path can be:
+
+- a head that IS a relationship (`project_id.name`) — the message names the
+  relationship it tried to cross and prescribes the supported alternative:
+  denormalise the value onto the queried object (formula or rollup field) and
+  sort by that;
+- a head that is not (`title.length`) — the message states the contract: sort
+  reaches only whole columns of the queried object, not values inside them.
+
+An unknown head (`no_such.title`) keeps the existing typo-shaped answer, and a
+list carrying both mistakes reports the typo first — the same precedence the
+expand gate uses.
+
+**What changes for callers:** requests whose sort crosses a relationship now
+fail loudly instead of receiving an ordinary-looking 200 over unordered rows.
+A survey of framework, objectui and cloud found zero callers emitting a dotted
+sort (objectui's column-header sort keys lookup columns by their flat field
+name and loads relations via `$expand`), so the practical blast radius is
+hand-authored requests — exactly the callers the silent degradation was
+misleading. Internal callers reaching `engine.find()` directly are unaffected,
+the same tiering every #4226 gate uses.