Merge origin/main into claude/issue-16483-retire-os-create-example

Brings in #16654 (scripts/sync-scaffold-emission-policy.mjs and its
`check:scaffold-emission-policy` gate), which landed while this PR was in
contract review. Merged rather than left to the queue because that gate's
declared inputs include packages/cli/src/commands/init.ts and the bundled
templates, and this PR touches init.ts (comment-only) and removes a template
— close enough that it should be measured on the PR instead of first
discovered in a dequeue.

⛔ No code change for the `allSixManifests()` drift this merge creates
(#16654's helper is named for five CLI emissions plus the on-ramp, and this
PR takes the CLI side to four). It is main's code now, a card of its own, and
repairing it here would widen this PR past its own.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YFY46JydE1gMxQG1TqBcMZ

Author: os-sales

.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/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,

content/docs/references/api/analytics.mdx

@@ -83,14 +83,22 @@ const result = AnalyticsEndpoint.parse(data);
 | **measures** | `string[]` | ✅ | List of metrics to calculate |
 | **dimensions** | `string[]` | optional | List of dimensions to group by |
 | **where** | `any` | optional | Filtering criteria (canonical Query DSL FilterCondition). An authored `FilterArray` is lowered by `parseFilterAST` on the client before the wire; this field admits only the lowered `FilterCondition` (see `FilterArray` in `data/filter.zod.ts`). |
-| **timeDimensions** | `{ dimension: string; granularity?: Enum<'second' \| 'minute' \| 'hour' \| 'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>; dateRange?: string \| string[] }[]` | optional |  |
+| **timeDimensions** | `{ dimension: string; granularity?: Enum<'second' \| 'minute' \| 'hour' \| 'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>; dateRange?: Enum<'today' \| 'yesterday' \| 'this_week' \| 'last_week' \| 'this_month' \| 'last_month' \| …> \| string[] }[]` | optional | Time-bucketed dimensions. Each entry names a dimension, an optional bucket `granularity`, and an optional `dateRange` — a preset name from the closed date-range vocabulary (e.g. `'last_7_days'`) or an explicit `[start, end]` window; an unrecognised string answers `400 ANALYTICS_DATE_RANGE_UNRECOGNIZED` instead of silently widening. |
 | **order** | `Record<string, Enum<'asc' \| 'desc'>>` | optional |  |
 | **limit** | `number` | optional |  |
 | **offset** | `number` | optional |  |
 | **timezone** | `string` | optional |  |
 | **query** | `never` | optional | [REMOVED] `query` was removed from AnalyticsQueryRequest in @objectstack/spec 17.0.0. The `{ cube, query: {...} }` envelope was the dialect of the retired degraded analytics shim — the real engine never understood it. Move the query.* fields to the body top level: `{ cube, measures, dimensions?, where?, timeDimensions?, order?, limit?, offset?, timezone? }`. |
 | **format** | `never` | optional | [REMOVED] `format` was removed from AnalyticsQueryRequest in @objectstack/spec 17.0.0. It was never implemented — every response is the JSON envelope. Delete the key; for CSV/XLSX use the export surface instead. |
 
+### Nested Shape: `AnalyticsQueryRequest.timeDimensions[number]`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **dimension** | `string` | ✅ |  |
+| **granularity** | `Enum<'second' \| 'minute' \| 'hour' \| 'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>` | optional |  |
+| **dateRange** | `Enum<'today' \| 'yesterday' \| 'this_week' \| 'last_week' \| 'this_month' \| 'last_month' \| …> \| string[]` | optional | Time window for this dimension: a date-range PRESET name from the closed vocabulary in `data/date-range-presets.ts` (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 — e.g. `'last_7_days'`), or an explicit `[start, end]` array of ISO dates / `{date-macro}` tokens (e.g. `["2023-01-01", "2023-01-31"]`). Any other string is refused at the schema with `400 ANALYTICS_DATE_RANGE_UNRECOGNIZED`. |
+
 
 ---
 

content/docs/references/api/contract.mdx

@@ -27,7 +27,7 @@ const result = ApiErrorSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +298 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
+| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +299 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
 | **declaredCode** | `string` | optional | The producer-declared code, verbatim, when it is not a member of the closed `code` vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
 | **message** | `string` | ✅ | Readable error message |
 | **userMessage** | `string` | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces `message`. |
@@ -93,6 +93,7 @@ const result = ApiErrorSchema.parse(data);
 * `ACTION_DISABLED`
 * `ALREADY_REVERTED`
 * `AMBIGUOUS_MATCH`
+* `ANALYTICS_DATE_RANGE_UNRECOGNIZED`
 * `ANALYTICS_QUERY_FAILED`
 * `APPROVAL_ACTIONS_FAILED`
 * `APPROVAL_APPROVE_FAILED`

content/docs/references/api/error-code-ledger.mdx

@@ -209,6 +209,7 @@ const result = ErrorCode.parse(data);
 * `ACTION_DISABLED`
 * `ALREADY_REVERTED`
 * `AMBIGUOUS_MATCH`
+* `ANALYTICS_DATE_RANGE_UNRECOGNIZED`
 * `ANALYTICS_QUERY_FAILED`
 * `APPROVAL_ACTIONS_FAILED`
 * `APPROVAL_APPROVE_FAILED`

content/docs/references/data/analytics.mdx

@@ -20,8 +20,8 @@ This layer decouples the "Physical Data" (Tables/Columns) from the
 ## TypeScript Usage
 
 ```typescript
-import { AggregationMetricType, AnalyticsQuerySchema, CubeSchema, CubeJoinSchema, DimensionSchema, DimensionType, MetricSchema, TimeUpdateInterval } from '@objectstack/spec/data';
-import type { AggregationMetricType, AnalyticsQuery, Cube, CubeJoin, Dimension, DimensionType, Metric, TimeUpdateInterval } from '@objectstack/spec/data';
+import { AggregationMetricType, AnalyticsDateRangeSchema, AnalyticsDateRangePresetSchema, AnalyticsQuerySchema, CubeSchema, CubeJoinSchema, DimensionSchema, DimensionType, MetricSchema, TimeUpdateInterval } from '@objectstack/spec/data';
+import type { AggregationMetricType, AnalyticsDateRange, AnalyticsDateRangePreset, AnalyticsQuery, Cube, CubeJoin, Dimension, DimensionType, Metric, TimeUpdateInterval } from '@objectstack/spec/data';
 
 // Validate data
 const result = AggregationMetricType.parse(data);
@@ -44,6 +44,48 @@ const result = AggregationMetricType.parse(data);
 * `boolean`
 
 
+---
+
+## AnalyticsDateRange
+
+### Union Options
+
+This schema accepts one of the following structures:
+
+#### Option 1
+
+Allowed Values: `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`
+
+---
+
+#### Option 2
+
+Type: `string[]`
+
+---
+
+
+---
+
+## AnalyticsDateRangePreset
+
+### Allowed Values
+
+* `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`
+
+
 ---
 
 ## AnalyticsQuery
@@ -56,12 +98,20 @@ const result = AggregationMetricType.parse(data);
 | **measures** | `string[]` | ✅ | List of metrics to calculate |
 | **dimensions** | `string[]` | optional | List of dimensions to group by |
 | **where** | `any` | optional | Filtering criteria (canonical Query DSL FilterCondition). An authored `FilterArray` is lowered by `parseFilterAST` on the client before the wire; this field admits only the lowered `FilterCondition` (see `FilterArray` in `data/filter.zod.ts`). |
-| **timeDimensions** | `{ dimension: string; granularity?: Enum<'second' \| 'minute' \| 'hour' \| 'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>; dateRange?: string \| string[] }[]` | optional |  |
+| **timeDimensions** | `{ dimension: string; granularity?: Enum<'second' \| 'minute' \| 'hour' \| 'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>; dateRange?: Enum<'today' \| 'yesterday' \| 'this_week' \| 'last_week' \| 'this_month' \| 'last_month' \| …> \| string[] }[]` | optional | Time-bucketed dimensions. Each entry names a dimension, an optional bucket `granularity`, and an optional `dateRange` — a preset name from the closed date-range vocabulary (e.g. `'last_7_days'`) or an explicit `[start, end]` window; an unrecognised string answers `400 ANALYTICS_DATE_RANGE_UNRECOGNIZED` instead of silently widening. |
 | **order** | `Record<string, Enum<'asc' \| 'desc'>>` | optional |  |
 | **limit** | `number` | optional |  |
 | **offset** | `number` | optional |  |
 | **timezone** | `string` | optional |  |
 
+### Nested Shape: `AnalyticsQuery.timeDimensions[number]`
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **dimension** | `string` | ✅ |  |
+| **granularity** | `Enum<'second' \| 'minute' \| 'hour' \| 'day' \| 'week' \| 'month' \| 'quarter' \| 'year'>` | optional |  |
+| **dateRange** | `Enum<'today' \| 'yesterday' \| 'this_week' \| 'last_week' \| 'this_month' \| 'last_month' \| …> \| string[]` | optional | Time window for this dimension: a date-range PRESET name from the closed vocabulary in `data/date-range-presets.ts` (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 — e.g. `'last_7_days'`), or an explicit `[start, end]` array of ISO dates / `{date-macro}` tokens (e.g. `["2023-01-01", "2023-01-31"]`). Any other string is refused at the schema with `400 ANALYTICS_DATE_RANGE_UNRECOGNIZED`. |
+
 
 ---