Merge remote-tracking branch 'origin/main' into claude/issue-16019-driver-declared-fault

Author: claude

.changeset/analytics-daterange-closed-vocabulary.md

@@ -0,0 +1,69 @@
+---
+"@objectstack/spec": minor
+"@objectstack/runtime": minor
+---
+
+feat(spec)!: `timeDimensions[].dateRange`'s string arm closes to the date-range preset vocabulary; any other string is refused with `400 ANALYTICS_DATE_RANGE_UNRECOGNIZED` (#16041)
+
+<!-- adr-0087: registered analytics-time-dimension-date-range-vocabulary-closed -->
+
+**BREAKING** — an accept-set narrowing on a published analytics contract.
+`AnalyticsQuerySchema.timeDimensions[].dateRange` (and with it the
+`POST /analytics/query` / `/analytics/sql` bodies, `AnalyticsQueryRequestSchema`,
+and the `AnalyticsQuery` type every driver and `AnalyticsService.query` caller is
+typed against) used to accept ANY string. It now accepts exactly the thirteen
+dashboard date-range preset names, derived from `data/date-range-presets.ts`
+(`z.enum(DATE_RANGE_PRESETS)` — the vocabulary's single source of truth since
+#4614, so the two cannot drift), or the unchanged `[start, end]` array arm.
+Shipped as `minor` under the repo's launch-window convention for breaking
+changes; the hand-migration prescription is registered under protocol major 18.
+Maintainer ruling on #16041 (2026-09-06, decision batch #57, option A —
+contract first, 「同意」): 「本项目以协议为基准。所以开发应该对其协议，协议有问题应该立卡修改协议」.
+
+## What was wrong
+
+The arm was a bare `z.string()` whose only documented example — `"Last 7 days"`,
+in the schema's own comment — was a value no driver could parse. `driver-memory`
+recognised exactly `today` and a case-sensitive `last N <unit>` and fell every
+other string through to a `[range, range]` pseudo-window that (measured through
+mingo, 2026-09-05) matched **every `Date`-typed row**, 2099 included, because a
+`Date` compares above a `String` under BSON cross-type ordering. The SQL
+strategies read the same bare string as a single ISO day. A dashboard asking for
+one week silently got all of history on one backend and one day on the other,
+at HTTP 200 on both.
+
+## What it does now
+
+- The string arm is `AnalyticsDateRangePresetSchema = z.enum(DATE_RANGE_PRESETS)`
+  (`today`, `yesterday`, `this_week`, `last_week`, `this_month`, `last_month`,
+  `this_quarter`, `last_quarter`, `this_year`, `last_year`, `last_7_days`,
+  `last_30_days`, `last_90_days`); the schema example is corrected to
+  `'last_7_days'`.
+- Any other value raises ONE prescriptive issue at `timeDimensions.N.dateRange`
+  (`analyticsDateRangeRefusalMessage`: the value, the vocabulary, the array
+  spelling for an explicit window). `@objectstack/spec/data` exports the
+  structural predicate `isAnalyticsDateRangeRefusalIssue` for doors.
+- `POST /analytics/query` and `/analytics/sql` answer the ADR-0112 envelope
+  **`400 ANALYTICS_DATE_RANGE_UNRECOGNIZED`** — a new `ERROR_CODE_LEDGER` member
+  registered under `@objectstack/runtime` — and the analytics service is never
+  reached. A body wrong in more places than the `dateRange` stays the generic
+  `400 VALIDATION_FAILED` + `details.fields[]`.
+
+## FROM → TO
+
+| you wrote | write instead |
+|:--|:--|
+| `dateRange: 'Last 7 days'` / `'last 7 days'` | `dateRange: 'last_7_days'` |
+| `dateRange: 'Last 30 days'` / `'last 30 days'` | `dateRange: 'last_30_days'` |
+| `dateRange: 'last 3 months'` | `dateRange: 'last_90_days'`, or an explicit `['{90_days_ago}', '{today}']` |
+| `dateRange: '2026-01-20'` (the SQL single-day dialect) | `dateRange: ['2026-01-20', '2026-01-20']` |
+| `dateRange: 'This week'` | `dateRange: 'this_week'` |
+| `dateRange: ['2026-01-01', '2026-01-31']` | unchanged |
+
+Measured in this repository at the ruling: three authored `'Last 7 days'`, all
+in `packages/spec` tests (re-spelled here), and no published dashboard authors
+the string arm at all — the shipped console lowers presets to the array arm
+before querying. The drivers' own refusal of a non-conforming value that reaches
+them in-process (past the schema) is the sibling card #16322, blocked by this
+one; the fenced `service-analytics` fixture that authors the retired bare-ISO
+spelling is that card's to re-triage.

.changeset/client-honours-data-prefix.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/client": patch
+---
+
+The client SDK reads the CRUD data prefix off the discovery document instead of restating `/data` as a literal, so a deployment that sets a non-default `crud.dataPrefix` is reachable through the scoped surface.
+
+`crud.dataPrefix` moves two things together: REST mounts every CRUD route under `${basePath}${crud.dataPrefix}`, and the discovery handler advertises the same value as `routes.data = ${realBase}${crud.dataPrefix}`. The SDK is the third surface describing those same paths, and its scoped half was not reading the value — it wrote `/data` into all seventeen of its data methods. On a deployment that moved the prefix, that half called paths the server does not mount, while the unscoped half of the *same* SDK called the right ones: the unscoped methods build `${baseUrl}${getRoute('data')}` and `routes.data` already carries the prefix. One SDK disagreed with itself about where the data routes are.
+
+- **`_dataPrefix()` recovers the prefix from the advertised routes.** `routes.data` is one string carrying two unknowns (`{realBase}{dataPrefix}`) and no discovery key carries either half alone, so the split is recovered in two steps. A value that already ends with the conventional `/data` *is* the default prefix — taken first, which is what makes the change unable to regress any deployment that works today: every later rule can only run in the branch where the previous single-literal code was already wrong. Otherwise `routes.metadata` supplies the missing equation, being `{realBase}{metadata.prefix}` over the same base, so the two advertised routes share exactly `realBase` plus whatever their prefixes share; cutting that common run back to its last `/` lands on the boundary. This also covers a document served from the environment-scoped mount, where both routes carry the same `/environments/{id}` segment.
+- **It declines rather than guess.** Where the document does not determine the split — no advertised routes, no `routes.metadata`, or a derived prefix of `/` or empty — the derivation returns the conventional `/data`, which is byte-identical to the previous behaviour. This follows the rule the neighbouring `_apiBase()` already sets in this file, and it is why an unconnected client is unaffected.
+- **`_apiBase()` strips the advertised prefix instead of the literal `/data`.** It previously declined whenever the prefix was non-default, because the only suffix it knew how to strip was `/data`. It now strips whatever `_dataPrefix()` read, so the base and the prefix are derived by one rule and cannot disagree. On every default-prefix deployment the result is unchanged.
+
+No new client option and no new configuration: the value is read from the server that already publishes it. A client that never calls `connect()` builds exactly the URLs it built before.

.changeset/i18n-extract-check-json-compares.md

@@ -0,0 +1,20 @@
+---
+"@objectstack/cli": patch
+---
+
+`os i18n extract --check --json` now COMPARES. It used to exit 0 having compared nothing, on a tree whose bundles had provably drifted.
+
+The machine face returned before the comparison ran: `if (flags.json) { … return; }` sat ahead of both the `--check` needs-`--out` guard and the comparison block. Driven on one fixture, two invocations differing only by `--json` — the first exited 1 with `missing: OUT/zh-CN.objects.generated.ts` and `Translation bundles have drifted from the schema`, the second exited 0 with the ordinary extract payload. The first run is the second one's positive control: the drift was really there. Same shape as the `--dry-run` branch repaired one release earlier, and `--json` is if anything the more likely CI spelling of the two, because a pipeline that wants to parse the result reaches for it.
+
+⚠️ **A pipeline that runs `os i18n extract … --check --json` and was green may now go red, and that is this repair working.** The green was a comparison that never happened; the red is the drift that was already in the tree. The fix is the one the failure names — re-run the same command without `--check` **and without `--json`**, then commit what it writes. Neither of those two flags writes files, and the command the failure prints now has both taken out of it.
+
+What each invocation now does, with no new member on any published payload:
+
+- **drift found** — the run ends on this command's existing `{ "error": … }` envelope with exit 1, carrying the same sentence the console face prints, the regenerate-and-commit command included. Deliberately not a new `drift` / `missing` / `stale` payload member: every other way this command can fail already speaks that envelope, and naming the drifted files in the machine payload would widen a published output face.
+- **in sync** — unchanged: the ordinary extract payload, exit 0.
+- **`--check` with no `--out`** — the refusal is now reachable under `--json` too, in the same `{ "error": … }` envelope with exit 1. It used to exit 0 with a payload, having been asked for a comparison it could not make.
+- **`--json` without `--check`** — unchanged in every respect.
+
+The run leaves through exactly one of those faces, so stdout still parses as exactly one JSON document.
+
+One more thing moved with it: the command a drifted `--check` prints as its remedy now has `--json` taken out of it as well as `--check`. It used to keep `--json`, so the machine face named a command that emits a payload, writes zero files, and leaves the next run failing with the same advice.

.changeset/public-picker-filter-lowering.md

@@ -0,0 +1,14 @@
+---
+"@objectstack/rest": patch
+---
+
+`GET /forms/:slug/lookup/:field` answers a search again: the public-form lookup picker no longer refuses every non-empty query with `400 INVALID_FILTER`.
+
+The route composed its filter list out of `ViewFilterRule` objects — the `{ field, operator, value }` dialect `FormFieldPublicPickerSchema.filter` declares in so many words ("Same `{ field, operator, value }` dialect as list-view filters") — and put them straight onto the `findData` filter slot. That slot accepts a `FilterCondition` object or a `FilterArray` (`[field, operator, value]`, a logical node, or a list of those) and refuses anything else. The refusal did not depend on an author declaring `publicPicker.filter`: the route's own `q` predicate is built in the same object shape, so **every** non-empty search was refused and only the degenerate empty-filter call could succeed — on an anonymous surface where a public-form applicant has no way around it.
+
+- **The route lowers; the parser is untouched.** The composed rows are translated to the array grammar the ingress parses, at the one door that speaks both dialects. ⛔ The repair deliberately NOT taken is teaching `findData` a second dialect: that maintains two filter grammars in the data layer permanently and spreads the object shape to every `findData` caller. The declaration already promises the object dialect on the authoring surface, so what changes is the side that failed to honour the promise. A test keeps the control that the object shape fed to the parser directly is still refused, so "the route lowers" cannot be confused with "the parser was loosened".
+- **Both branches.** The declared `publicPicker.filter` rows and the route's own `contains` search row are lowered together and ANDed explicitly; no declared filter still means no filter (`[]`), never an empty logical node the ingress would refuse.
+- **The operator fold is the spec's own.** Lowering reuses `normalizeFilterOperator` from `@objectstack/spec/ui` — the fold `ViewFilterRuleSchema.operator` itself runs — so a stored row carrying a legacy spelling (`notEquals`, `isNotEmpty`, `gt`) folds exactly as the schema folds it. No second alias table.
+- **A rule that cannot be read is forwarded, not dropped.** The request is then refused exactly as before. That direction is deliberate: a picker's static filter is often the only thing keeping an anonymous visitor's search inside the rows a form may expose, and silently skipping a row nobody understood would answer 200 over an unfiltered table.
+
+No authoring surface moves: `FormFieldPublicPickerSchema` already declared this dialect as accepted, and this makes the runtime honour it.

.changeset/rest-server-canonical-query-ast.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/rest": patch
+---
+
+The REST server's own `findData` calls now build the canonical QueryAST instead of an undeclared wire dialect, and the helper that erased the type on that one slot is gone.
+
+Four server-built query literals in `rest-server.ts` — the import-job loader, the import-job listing, the export chunk loop and the public reference picker — spelled their query in transport aliases (`$filter`, `$top`, `$skip`, `$orderby`, `$expand`, plus the bare `filters` / `select` / `sort`). None of those spellings is declared by `QuerySchema`, so three of them were routed through a `wireDialectQuery` helper that cast the `query` member to `FindDataRequest['query']`, and the fourth escaped the compiler entirely because its protocol handle was typed `any`. All four now spell `object` / `where` / `orderBy` / `limit` / `offset` / `fields` / `expand`, so the slot compiles against the declared contract like every other member of the request, and the helper is retired.
+
+**No behaviour moves, and that is measured rather than asserted.** `@objectstack/metadata-protocol`'s `findData` folds every alias onto its canonical key by the spec's own table (`RPC_QUERY_ALIAS_SLOTS`) and moves the value verbatim, so both spellings reach `engine.find` as the same option bag. `rest-server-canonical-query-ast.test.ts` drives all four before/after pairs through the real normalizer and asserts that equality, and reads the source to keep the erasure retired — a cast compiles, so a type-check alone could not hold this ground.
+
+**Nothing is removed from the published surface.** `wireDialectQuery` was a module-local `const` in `rest-server.ts`: it carried no `export` keyword, `packages/rest/src/index.ts` never named it, and it appeared in no other file in the tree. Deleting it moves no exported symbol, which is why this is a patch.
+
+**What this change deliberately does NOT do:** it does not touch how the HTTP door treats a *caller's* query. The wire aliases stay accepted on `GET /data/:object` exactly as before — declaring them in the spec's alias table is a separate piece of work — and `GET /data/:object` still forwards the caller's own querystring bag untouched.

.changeset/scaffold-on-ramp-emission-policy-generated.md

@@ -0,0 +1,36 @@
+---
+"create-objectstack": minor
+---
+
+`npx create-objectstack` now declares the same TypeScript range as `os init` and
+`os create`, and the value is generated rather than restated.
+
+Three scaffolders write a new project's `package.json`, and the range that
+decides whether that project type-checks at all had split: `os init` and
+`os create` emitted `typescript: ^5.3.0` from a shared emission policy, while
+this package's bundled template carried `^6.0.0`. Two projects created the same
+day got different TypeScript **majors** depending on which documented entry
+point the reader followed.
+
+- **What changed for a scaffolded project.** Its declared `typescript`
+  devDependency floor moves from `^6.0.0` to `^5.3.0`. Both resolve to the same
+  installed compiler on a fresh install; what moves is the floor the project
+  **declares**, and a floor is a support promise. `^5.3.0` is the promise the
+  docs already make — "ObjectStack works with TypeScript 5.3+" on the getting
+  started page, "TypeScript 5.3.0 or later" in the deployment troubleshooting
+  page — and it is measured rather than assumed: TypeScript 5.3.3 type-checks
+  every shape these scaffolders emit with results identical to 6.0.3. The repo's
+  own `typescript@^6.0.3` devDependency is deliberately not this value; the same
+  doc sentence states both halves ("…but the project itself is built and tested
+  against TypeScript 6.x"). `engines.pnpm` was already in agreement and is now
+  held there by the same mechanism.
+- **Why the value is generated.** This package cannot import from
+  `@objectstack/cli`: the dependency edge runs the other way, and the `npx`
+  package must not pull the CLI's package closure. So the values are stamped
+  into the bundled template at build time by
+  `scripts/sync-scaffold-emission-policy.mjs`, read out of the same
+  `SCAFFOLD_*` constants the other two scaffolders import, and
+  `pnpm check:scaffold-emission-policy` reddens the moment the inlined values
+  disagree with that source. Editing the two into agreement by hand would have
+  left them free to diverge again on the next move, silently, for the same
+  structural reason — which is how they diverged the first time.

.github/workflows/lint.yml

@@ -2046,6 +2046,25 @@ jobs:
       - name: Template version-time rewriter self-test
         run: pnpm check:template-version-sync
 
+      # #16485 — the BUILD-time generator beside the version-time one above, and
+      # the only one of the two whose --check leg runs on a real corpus here.
+      # `create-objectstack` cannot import @objectstack/cli (the dependency edge
+      # runs the other way, and the npx package must not pull the CLI's closure),
+      # so its bundled template RESTATED the scaffold emission policy and the
+      # restatement decayed: `typescript` reached `^6.0.0` there while `os init`
+      # and `os create` emitted `^5.3.0` from the shared constants, so two
+      # projects created the same day got different TypeScript majors depending
+      # on which documented entry point the reader followed. The values are now
+      # generated into the template from `packages/cli/src/commands/init.ts`, and
+      # this is the leg that reddens on drift — a hand edit into agreement would
+      # have satisfied the acceptance box and diverged again on the next move.
+      # Both legs run: --self-test covers the red paths a green corpus cannot
+      # reach (a renamed policy constant, a template omitting a stamped key, an
+      # unparseable template, an empty templates directory), --check covers the
+      # live tree.
+      - name: Scaffold emission policy generated into the on-ramp
+        run: pnpm check:scaffold-emission-policy
+
       # #15332 — the THIRD version-time rewriter, and the third self-test beside
       # the two above. scripts/sync-release-index-currency.mjs joins the root
       # `version` chain and stamps the release index's "current series: X.Y.Z,