Merge remote-tracking branch 'origin/main' into claude/issue-15591-seed-apply-decorated-envelope

Author: claude

.changeset/analytics-measure-result-type-temporal.md

@@ -0,0 +1,24 @@
+---
+"@objectstack/service-analytics": minor
+"@objectstack/spec": patch
+---
+
+A dataset measure's `fields[].type` stops contradicting the value beside it: a `min`/`max` over a temporal field is described as `time`, not `number` (#15768)
+
+`POST /api/v1/analytics/dataset/query` described **every** measure column as `type: "number"`, including a `min`/`max` over a `date` / `datetime` / `time` field whose value in the same response is an ISO instant. Measured on a real boot (`@objectstack/cli` 17.3.0, SQLite dev datasource):
+
+```json
+{"rows":[{"oldest_last_update_at":"2026-07-04T07:00:00.000Z"}],
+ "fields":[{"name":"oldest_last_update_at","type":"number","label":"Oldest touch","format":"relative"}]}
+```
+
+`min` and `max` return a value **of the aggregated field's own type**, so that column carries an instant and the metadata denied it — which is enough on its own to keep a formatter that branches on the declared type from ever reaching a temporal branch.
+
+What changed:
+
+- **The measure column's type is resolved from the authored measure plus the source field's declared type**, in `AnalyticsService.queryDataset`'s ADR-0021 result-column enrichment — the same block that already resolves `label` / `format` / `currency` / `percentScale`, and the one seam every producer of the shape passes through on the way to the route, which relays that method's return verbatim. The rule itself is `measureResultType` in the new `measure-result-type.ts`, so the per-aggregate verdict has one home instead of four copies.
+- **The corrected spelling is `time`**, the `DimensionType` word a temporal DIMENSION column in the same response has always carried. A second temporal word in one wire position would have left every existing consumer branch unreached.
+- **Only `min` and `max` move.** `count` and `count_distinct` are numeric however temporal the column they read is; `sum` / `avg` over a temporal column are refused by no layer and answered by the backend (an epoch mean on SQLite, an error on Postgres), so there is no single value for a type to describe and none is invented; a derived measure is numeric by construction, because `computeDerived` coerces its operands with `Number()`. Row values are untouched on every path.
+- **Tiered "cannot answer, do not block".** A host with no source-field metadata wired, and a measure over a relationship PATH (which the source-field lookup resolves against the base object and therefore cannot answer), both leave the column exactly as the query layer produced it.
+
+`AnalyticsResult.fields[].type` and the `AnalyticsResultResponse` schema now state the vocabulary this position speaks and what each aggregate answers; neither declaration widens — the wire type was, and remains, a string.

.changeset/api-duration-keys-unit-in-key-name.md

@@ -0,0 +1,95 @@
+---
+"@objectstack/spec": minor
+"@objectstack/runtime": patch
+---
+
+feat(spec)!: the twelve `api/` duration keys carry their unit in the key name (#15677, ruling B on #14478)
+
+<!-- adr-0087: registered api-endpoint-cache-ttl-to-cache-ttl-seconds, api-error-retry-after-unit-in-key, api-runtime-config-durations-unit-in-key, device-request-response-interval-unit-in-key, rest-api-plugin-durations-unit-in-key, websocket-durations-unit-in-key -->
+
+**BREAKING** — twelve published `api/` duration keys are renamed and tombstoned.
+Shipped as `minor` under the repo's launch-window convention for breaking
+changes; the hand-migration prescriptions are registered under protocol major
+18. Maintainer ruling B on #14478 (2026-09-02, decision batch #43, 「同意」).
+
+`check:duration-unit-keys` makes a duration-shaped `z.number()` carry its unit
+in the key NAME, never only in its `.describe()` prose, and grandfathers no
+existing offender. Stack card 1/6 (#15676) landed the rule's two structural
+exemptions; this card clears the `api/` directory against it. Measured with the
+gate itself: `src/api/**` goes from 12 offenders to **0**, and the whole-tree
+count falls **48 → 36**.
+
+## FROM → TO
+
+| key | replacement | unit |
+|:--|:--|:--|
+| `ApiEndpoint.cacheTtl` | `cacheTtlSeconds` | seconds |
+| `DataLoaderConfig.cacheTtl` | `cacheTtlSeconds` | seconds |
+| `DeviceRequestResponse.interval` | `intervalSeconds` | seconds |
+| `EnhancedApiError.retryAfter` | `retryAfterSeconds` | seconds |
+| `RestApiEndpoint.timeout` | `timeoutMs` | milliseconds |
+| `RestApiEndpoint.cacheTtl` | `cacheTtlSeconds` | seconds |
+| `RestApiPluginConfig.performance.defaultCacheTtl` | `defaultCacheTtlSeconds` | seconds |
+| `RouteDefinition.timeout` | `timeoutMs` | milliseconds |
+| `WebSocketConfig.reconnectInterval` | `reconnectIntervalMs` | milliseconds |
+| `WebSocketConfig.pingInterval` | `pingIntervalMs` | milliseconds |
+| `WebSocketConfig.timeout` | `timeoutMs` | milliseconds |
+| `WebSocketServerConfig.heartbeatInterval` | `heartbeatIntervalMs` | milliseconds |
+
+**Every value is unchanged** — only key names move. Every old spelling is a
+`retiredKey()` tombstone, so it fails `tsc` at the authoring site (input type
+`never`) and fails the parse with the rename prescription rather than a bare
+unrecognized-key error.
+
+## ⚠️ `ApiError.retryAfter` — the wire envelope, and what it does NOT touch
+
+Ruling B put this key explicitly in scope with its own BREAKING note: the
+runtime-emitted measurements are read by humans and agents even though nobody
+authors them. A consumer meets two retry-after values on one 429 — this
+ADR-0112 envelope field, always delta-seconds, and the HTTP `Retry-After`
+header, which per RFC 9110 §10.2.3 may carry delta-seconds **or** an HTTP-date.
+Spelled identically they read as one value in two places.
+
+**The HTTP `Retry-After` response header is a separate, unchanged surface.** Its
+name is fixed outside this repo and nothing here touches it. Do not "fix" the
+header to match the envelope, and do not read a surviving `retry-after` in
+transport code as leftover work.
+
+## Dispositions — one D2 conversion, five semantic entries
+
+Justified per key rather than defaulted. **`ApiEndpoint.cacheTtl` is the only
+one of the twelve that gets an ADR-0087 D2 conversion**
+(`api-endpoint-cache-ttl-to-cache-ttl-seconds`), because `apis:` is a stack
+collection (`apis: z.array(ApiEndpointSchema)`) and `api` is a registered
+metadata kind stored as a row, so the conversion chain has a seam that sees it.
+`os migrate meta --from 17` lists the mechanical edits.
+
+The other eleven are wire payloads and construction arguments — a device-flow
+response body, an error envelope, REST-plugin route registration, a batch-loader
+config, a router registration, WebSocket client/server configuration. None is
+ever a stack collection member or a `sys_metadata` row, so no conversion seam
+runs on them and each carries a **semantic** entry instead: this is the
+disposition `api/RestApiEndpoint:handlerStatus` already holds on one of these
+very shapes, and what ruling B prescribes for a runtime-emitted key.
+
+## `DeviceRequestResponse.interval` is a rename, not an external-vocabulary mirror
+
+Attributed to RFC 8628 by the campaign card; the attribution fails against the
+schema's own evidence. `DeviceRequestResponseSchema` does not mirror RFC 8628 as
+a set — `code` is not `device_code`, `verificationUrl` is not
+`verification_uri`, `expiresAt` is not `expires_in` (a different name *and* a
+different type, an ISO-8601 instant where the RFC carries a relative lifetime).
+A schema that already renames every RFC field it carries into house style cannot
+claim the standard fixes the one name it left bare. Renamed rather than marked
+deliberately: a wrongly marked key is exempted permanently and silently, while a
+wrongly renamed one is visible.
+
+## Readers moved in the same PR, at the same magnitude
+
+`@objectstack/runtime`'s policy chain (`computeCacheControl` now reads
+`endpoint.cacheTtlSeconds`), the publish gate's issue path
+(`apis.N.cacheTtlSeconds`), the built-in REST route tables, the showcase
+example, dogfood fixtures, `liveness/api.json` (renamed row plus a `dead`
+tombstone row) and the `objectstack-api` skill. The `ApiEndpoint` alias table is
+retargeted onto the live key — an alias must point at a key the schema really
+accepts, and `cacheTtl` now accepts nothing.

.changeset/cast-blob-compile-option-claim.md

@@ -0,0 +1,14 @@
+---
+"@objectstack/spec": patch
+"@objectstack/driver-turso": patch
+"@objectstack/driver-sql": patch
+"@objectstack/service-analytics": patch
+---
+
+Correct the documented reason for rejecting `CAST(col AS BLOB) LIKE ?` as a portable case-exact construct.
+
+Four headers stated, as a universal fact about SQLite, that the construct "was measured to return NOTHING". That is not a property of SQLite: whether `LIKE` is false for a BLOB operand is fixed when SQLite is compiled, by `SQLITE_LIKE_DOESNT_MATCH_BLOBS`, and the two SQLite builds this project ships disagree about it. Measured over the shared `FILTER_TEXT_ROWS` fixture, `{ name: { $contains: 'acme' } }` compiled to that construct returns `[]` on better-sqlite3 13.0.3 (SQLite 3.53.4, flag compiled in) and `['1','2']` on sql.js 1.14.1 (SQLite 3.49.1, flag absent) — the latter being exactly the ASCII case-folding defect the construct was being considered to avoid.
+
+No behaviour changes and no conclusion changes: all four sites still reject the construct and still choose `GLOB`. The rejection is now stated in a form that does not depend on any particular return value — a construct whose meaning is decided by an upstream compile flag cannot carry a read scope, because it means two different things on the two builds shipped here. Two supporting readings are recorded alongside it: `typeof CAST(name AS BLOB)` is `'blob'` on both builds, so the CAST is not the part that differs, and `GLOB` answers identically on both.
+
+Documentation only. `@objectstack/spec` and `@objectstack/driver-turso` ship the corrected text in their published type declarations (and `spec` also publishes the corrected source file directly, via its `src/**/*.zod.ts` entry); for `@objectstack/driver-sql` and `@objectstack/service-analytics` the change reaches published output only through sourcemaps.

.changeset/cli-explain-dashboard-refresh-interval-seconds.md

@@ -0,0 +1,11 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `explain` names the renamed `dashboard.refreshIntervalSeconds` (#14478)
+
+The dashboard key catalogue `os explain` prints lists
+`refreshIntervalSeconds` instead of `refreshInterval`, following the
+`@objectstack/spec` rename of the authored key (the unit now lives in the key
+name). Same key, same seconds; no other command output and no public surface of
+this package changes.

.changeset/client-readme-analytics-automation-payload-reads.md

@@ -0,0 +1,9 @@
+---
+"@objectstack/client": patch
+---
+
+The README's analytics and automation examples read the resolved payload.
+
+`client.analytics.query` / `analytics.meta` and `client.automation.trigger` stopped handing back the dispatcher's `{ success, data }` envelope in 17.0.0: each resolves to the payload itself. The README's namespace tour still showed all three as bare `await` calls with nothing reading the resolved value, so the package's own front page taught nothing about which shape comes back — neither wrong nor useful. Each of the three now assigns its result and reads one member of it: `report.rows` / `report.fields[0].name` (`AnalyticsResult`), `cubes[0].name` (the bare `CubeMeta[]`), `run.status` (`AutomationResult`) — the members those contracts actually declare, read off the payload rather than off a `data` wrapper.
+
+No behaviour changes; this is the README that ships inside the package. The docs site's Client SDK and Data API pages take the same treatment in the same PR.

.changeset/data-ui-ai-integration-duration-keys-unit-in-key-name.md

@@ -0,0 +1,138 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec)!: the last seven `data/` · `ui/` · `ai/` · `integration/` duration keys carry their unit in the key name (#15680, ruling B on #14478)
+
+<!-- adr-0087: registered dashboard-refresh-interval-to-refresh-interval-seconds, connector-health-and-trigger-durations-unit-in-key, memory-persistence-auto-save-interval-to-ms, turso-config-timeout-to-timeout-ms, ai-conversation-analytics-duration-unit-in-key, data-nosql-query-options-timeout-unit-in-key -->
+
+**BREAKING** — eight published duration keys are renamed and tombstoned. Shipped
+as `minor` under the repo's launch-window convention for breaking changes; the
+hand-migration prescriptions are registered under protocol major 18. Maintainer
+ruling B on #14478 (2026-09-02, decision batch #43, 「同意」).
+
+`check:duration-unit-keys` makes a duration-shaped `z.number()` carry its unit in
+the key NAME, never only in its `.describe()` prose, and grandfathers no existing
+offender. Card 1/6 (#15676) landed the rule's two structural exemptions, card 2/6
+(#15677) cleared `api/`, card 3/6 (#15678) cleared `kernel/` and card 4/6
+(#15679) cleared `system/`. This card clears the remainder, and is the first
+where the gate itself reads **`zero offenders`** and exits `0`.
+
+⚠️ That is green **for the gate's currently declared population**
+(`packages/spec/src/**`), not for the epic. Card 6/6 widens the population and has
+already measured an offender outside this subtree, so the gate is expected to go
+red again by design. This changeset does not claim #14478 is finished.
+
+## FROM → TO
+
+| key | replacement | unit |
+|:--|:--|:--|
+| `dashboard.refreshInterval` | `refreshIntervalSeconds` | seconds |
+| `CircuitBreakerConfig.monitoringWindow` | `monitoringWindowMs` | milliseconds |
+| `ConnectorTrigger.interval` | `intervalSeconds` | seconds |
+| `FilePersistenceConfig.autoSaveInterval` | `autoSaveIntervalMs` | milliseconds |
+| `AutoPersistenceConfig.autoSaveInterval` | `autoSaveIntervalMs` | milliseconds |
+| `TursoConfig.timeout` | `timeoutMs` | milliseconds |
+| `NoSQLQueryOptions.timeout` | `timeoutMs` | milliseconds |
+| `ConversationAnalytics.duration` | `durationSeconds` | seconds |
+
+**Every value is unchanged** — only key names move. The two keys that carried a
+default keep it (`CircuitBreakerConfig.monitoringWindowMs` still defaults to
+60000, `FilePersistenceConfig.autoSaveIntervalMs` to 2000); the other six declare
+none. Bounds move with their keys, so `autoSaveIntervalMs` still refuses anything
+under 100 on both persistence arms, `NoSQLQueryOptions.timeoutMs` and
+`TursoConfig.timeoutMs` still refuse a zero or negative integer, and
+`ConversationAnalytics.durationSeconds` still refuses a negative length. Every old
+spelling is a `retiredKey()` tombstone, so it fails `tsc` at the authoring site
+(input type `never`) and fails the parse with the rename prescription rather than
+a bare unrecognized-key error.
+
+`dashboard`'s three rename-hint aliases — `refresh`, `autoRefresh`, `pollInterval`
+— were repointed to `refreshIntervalSeconds` in the same edit. A hint left naming
+the tombstone would have prescribed a key the shape refuses, which is the one
+failure this rename could have introduced silently; a pin asserts all three.
+
+## ⚠️ `dashboard.refreshInterval` crosses a repository boundary
+
+This is the only rename in the whole stack whose consumer is in **another
+repository**, so its reader could not move in this PR the way every other reader
+in this card did. objectui's dashboard renderer reads the key, multiplies by
+1000 to drive a `setInterval`, and republishes it as an authoring input the
+console offers. Those sites move in a follow-up objectui card, sequenced behind
+a release that actually ships this rename.
+
+Until that lands the renderer sees an absent key and simply does not start its
+refresh timer — a dashboard still renders, and still refreshes when the user
+asks. The ADR-0087 conversion in this changeset is what keeps stored dashboards
+and `os migrate meta` correct in the meantime.
+
+## ⚠️ An eighth key moves that the gate did not list
+
+`AutoPersistenceConfig.autoSaveInterval` is not a gate offender: its `.describe()`
+named no unit at all, and the predicate judges prose against name.
+
+It moves anyway because it is not a second key. `persistence: { type: 'auto' }`
+resolves to the same Node.js file adapter as `type: 'file'`, and this value is
+forwarded to the same `FileSystemPersistenceAdapter` field, in the same
+milliseconds, under the same `min(100)` bound. Renaming one arm and not the other
+would have left one value with two spellings across sibling arms of one union,
+and the driver reading both — the consumer-side dialect Prime Directive #12
+forbids. Its describe now names the unit too, and a pin asserts the refusal on
+the arm the gate never listed, so a later reader cannot "restore" the bare
+spelling as an over-application of the rule.
+
+## Dispositions — four D2 conversions, two semantic entries
+
+Judged per key from `stack.zod.ts`'s collection roots rather than defaulted, and
+unlike card 4/6 this card's answer is split.
+
+**D2 conversions** (six keys). `dashboards:`, `connectors:` and `datasources:`
+are each a stack collection whose members are stored whole as `sys_metadata`
+rows, so the conversion chain has a seam that sees them:
+`dashboard-refresh-interval-to-refresh-interval-seconds`,
+`connector-health-and-trigger-durations-unit-in-key` (both connector keys in one
+pass, emitting separately),
+`memory-persistence-auto-save-interval-to-ms` (both persistence arms) and
+`turso-config-timeout-to-timeout-ms`. The two datasource conversions are
+driver-aware for the reason `datasource-config-driver-key-aliases` records: a
+bare `config.timeout` under another driver is that driver's own key and must not
+be touched.
+
+**Semantic entries** (two keys). `ConversationAnalytics` is computed at runtime
+and handed to a consumer, and `NoSQLQueryOptions` is a per-call driver argument
+reached only through `AggregationPipeline.options`. Neither is a stack collection
+member or a stored row, so the chain has no seam — the disposition every
+runtime-emitted measurement in this stack has taken.
+
+All eight are registered by exact key in `RETIRED_KEYS_BY_MAJOR`.
+
+## A retirement tombstone is no longer read as a secret
+
+`refusedCredentialKeys` derives a driver's refused inline credentials by finding
+`z.never()` keys in its config contract. A `retiredKey()` tombstone is also a
+`z.never()`, and until this card no driver contract carried one — so "never ⇒
+credential" held by accident of population rather than by construction. The first
+tombstone to arrive (`TursoConfig.timeout`) made the derivation answer that a
+millisecond budget was a secret: it was redacted off the datasource read path and
+dragged a non-credential name into the fallback list every unrecognised driver is
+scrubbed by.
+
+The derivation now skips keys carrying the `[REMOVED] ` prefix `retiredKey()`
+itself stamps. The exclusion is deliberately **negative** — skip declared
+tombstones — rather than positive (keep only keys marked `format: 'password'`),
+even though every credential slot in every builtin contract does carry that
+marker today: under-redacting is the dangerous direction, so a future credential
+key whose author forgets the marker is still scrubbed, and only a key that has
+explicitly declared itself retired may drop out. Both directions are pinned.
+
+## Keys deliberately left alone
+
+`TursoConfig.sync.intervalSeconds` and `CircuitBreakerConfig.resetTimeoutMs`
+already carried their unit — they are the same-shape neighbours that made the
+bare `timeout` and `monitoringWindow` collisions visible, and pins assert they
+did not move. `NoSQLQueryOptions.batchSize` is a COUNT of documents and every
+number on `ConversationAnalytics` other than the duration is a count of messages,
+tokens or events: a count has no unit to carry. The turso schema shipped by
+`@objectstack/driver-turso` is a separate declaration outside this gate's
+declared population and is not touched here; card 6/6 owns it, so the two
+declarations disagree by design until that lands.