Merge remote-tracking branch 'origin/main' into claude/issue-20534-parse-date-cell-family

Author: hotlong

.changeset/20288-realtime-event-type-emitted-vocabulary.md

@@ -0,0 +1,75 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec)!: `RealtimeEventType` names the realtime events the runtime emits — `data.record.*` and `data.records.*`; `record.created` / `record.updated` / `record.deleted` / `field.changed` retired (#20288)
+
+Clause-②: yes (narrowing)
+
+**BREAKING** — shipped as `minor` under the launch-window convention
+(`check-changeset-no-major` refuses `major` until GA; breaking-ness is carried by
+this banner, the `(narrowing)` arm above and the ADR-0087 disposition below,
+never by the level). The enum both gains and loses values: it gains the five
+names the runtime emits and loses the four it never emitted.
+
+`RealtimeEventType` (`@objectstack/spec/api`) types `SubscriptionEvent.type`, so
+it is the event vocabulary of `Subscription.events[]` and
+`RealtimeConfig.subscriptions[].events[]`, and the generated API reference
+published it as such. None of its four values was ever emitted by anything. The
+ObjectQL engine publishes `data.record.created` / `data.record.updated` /
+`data.record.deleted` for each written record and `data.records.updated` /
+`data.records.deleted` for a predicate write (`multi: true`), and it parses every
+event through `DataEventSchema` / `BulkDataEventSchema` before publishing. A
+subscription written with the names the reference showed could never fire.
+The runtime's published event names do not change; the enum moves to them.
+
+- **Accepted now:** exactly `DataEventType` + `BulkDataEventType` —
+  `data.record.created`, `data.record.updated`, `data.record.deleted`,
+  `data.records.updated`, `data.records.deleted`. Metadata change events
+  (`metadata.{type}.{action}`) are not members: a subscription event is
+  record-shaped, and metadata events keep their own `MetadataEventType` contract
+  and `subscribeMetadata` client primitive.
+- **Refused now:** `record.created`, `record.updated`, `record.deleted` and
+  `field.changed`, each with its own prescription. Any other unknown value keeps
+  zod's own message, which lists the legal names.
+
+```
+FROM  SubscriptionSchema.parse({ id, transport: 'websocket', events: [{ type: 'record.created', object: 'account' }] })
+      -> parsed; nothing ever published 'record.created', so the subscription never fired
+TO    -> ZodError at events[0].type (invalid_value): `record.created` was removed from
+         `RealtimeEventType` in @objectstack/spec 17.5.0 (ADR-0049 enforce-or-remove) — … Write
+         `data.record.created` — the same event, spelled the way the engine publishes it.
+
+FROM  { type: 'record.updated' }   ->  TO  { type: 'data.record.updated' }
+      (add { type: 'data.records.updated' } to also hear predicate writes, which carry a count, not records)
+FROM  { type: 'record.deleted' }   ->  TO  { type: 'data.record.deleted' }
+      (add { type: 'data.records.deleted' } to also hear predicate writes)
+FROM  { type: 'field.changed' }    ->  TO  { type: 'data.record.updated' }
+      (read the field from the DataEvent payload's `changes`; no event is published per field)
+```
+
+**Fix.** Rename each value as mapped above. `tsc` refuses the old values at a
+`RealtimeEventType` / `SubscriptionEvent` position (the type no longer contains
+them), and a `SubscriptionSchema`, `SubscriptionEventSchema` or
+`RealtimeConfigSchema` parse refuses them with the prescription. A handler keyed
+on an old name never ran, so the rename changes behaviour only by making it fire.
+Nothing in the open framework parses a subscription today — it mounts no realtime
+transport — so no running deployment changes behaviour.
+
+### The kit
+
+- **Schema.** `RealtimeEventType` lists the five emitted names; its error map
+  gives each retired value its own prescription (the `HookBodyCapability`
+  precedent for a removed enum value). `realtime.test.ts` pins the enum equal to
+  `DataEventType` + `BulkDataEventType`, and pins each refusal's code, path and
+  first sentence through `SubscriptionSchema`.
+- **ADR-0087.** The D3 entry `realtime-event-type-unemitted-values-retired`
+  carries the prescription to `os migrate meta` and the upgrade guide. No D2
+  conversion and no `RETIRED_KEYS_BY_MAJOR` row: an enum value is not a key, and
+  a subscription is neither a stack collection member nor a stored row, so no
+  conversion seam would ever see one.
+- **Docs.** The `realtime` reference page is regenerated; the
+  `RealtimeEventPayload.type` and `RealtimeEvent.type` examples name emitted
+  events.
+
+<!-- adr-0087: registered realtime-event-type-unemitted-values-retired -->

.changeset/20288-service-realtime-emitted-event-examples.md

@@ -0,0 +1,14 @@
+---
+'@objectstack/service-realtime': patch
+---
+
+docs(service-realtime): the README and `InMemoryRealtimeAdapter` examples name the events the ObjectQL engine actually publishes (#20288)
+
+The usage example subscribed to and published `record.created`, and the security
+posture section said the engine publishes `record.created` / `record.updated`.
+The engine publishes `data.record.created` / `data.record.updated` /
+`data.record.deleted` (and `data.records.updated` / `data.records.deleted` for a
+predicate write), with the spec's `DataEvent` as the envelope's `payload` — the row
+is `payload.after`, not the payload itself. Both examples now subscribe to
+`data.record.created` and publish that shape. No code changes: the adapter matches
+whatever event type a subscription names, exactly as before.

.changeset/20476-define-stack-conversions-reach-doors.md

@@ -0,0 +1,15 @@
+---
+"@objectstack/spec": minor
+"@objectstack/cli": minor
+---
+
+**`objectstack validate` and `objectstack build` now report the ADR-0087 conversions `defineStack` applied, and `objectstack validate --strict` fails on them.**
+
+`defineStack` rewrites a deprecated metadata spelling to its canonical shape when the config loads, in either mode, and prints one `defineStack: PATH: 'OLD' → 'NEW' (converted at load; conversion 'ID', retires in protocol N)` line on stderr. The two commands received that already-converted stack, so their own conversion pass found nothing to convert: `--json` answered `conversions: []` for every `defineStack` config, and `objectstack validate --strict` exited 0 on a spelling that stops loading in a named protocol major. A CI job gating on either could not see the retirement coming.
+
+- `@objectstack/spec`: `defineStack` (both modes) records every conversion notice it applied on the stack it returns, beside the provenance mark and stamped in the same act. The record is non-enumerable and frozen, so the schema, `Object.keys` and `JSON.stringify` never see it and no compiled artifact changes. `composeStacks` records its inputs' records in input order, counting the same built stack passed twice once. **New export:** `stackConversionsOf(value)` returns the `ConversionNotice[]` a producer recorded, the same element the commands' `conversions` field publishes, and `[]` for a value no producer returned. Like the mark, the record does not survive a spread or JSON copy.
+- `@objectstack/cli`: the config loader reads the record off the default export before it merges named exports into it (that merge is a spread, which drops the record as it drops the mark). `objectstack validate` and `objectstack build` add it to their `conversions` list right after the config loads. Their own conversion pass still runs, and still reports what it converts on a key merged in from a named export of the config module, which `defineStack` never saw. The `--json` envelope keeps its shape (`valid` / `success`, `errors`, `warnings`, `conversions`): `conversions` now lists each conversion once.
+
+**What a CI job sees:** `objectstack validate --strict` and `objectstack validate --json --strict` now exit 1 for a config whose only advisory is a live conversion, which is what `--strict` ("treat warnings as errors") documents. Without `--strict` the exit stays 0. The fix is the one the notice names: author the canonical spelling it prints, for example `subtitle` instead of `description` on a `page:header` component. The text face lists the conversion in its warning block. The stderr line from `defineStack` is unchanged and still printed once per conversion.
+
+Clause-②: yes (widening) — one new export, `stackConversionsOf`, on the spec package root. Nothing `objectstack build`, or `objectstack validate` without `--strict`, accepted before is refused. `--strict` now applies its documented meaning to the conversions a `defineStack` config carries. It does not add a new rule.

content/docs/references/api/realtime.mdx

@@ -37,7 +37,7 @@ const result = RealtimeConfigSchema.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **id** | `string` | ✅ | Unique subscription identifier |
-| **events** | `{ type: Enum<'record.created' \| 'record.updated' \| 'record.deleted' \| 'field.changed'>; object?: string; filters?: any }[]` | ✅ | Array of events to subscribe to |
+| **events** | `{ type: Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted' \| …>; object?: string; filters?: any }[]` | ✅ | Array of events to subscribe to |
 | **transport** | `Enum<'websocket' \| 'sse' \| 'polling'>` | ✅ | Transport protocol to use |
 | **channel** | `string` | optional | Optional channel name for grouping subscriptions |
 
@@ -51,7 +51,7 @@ const result = RealtimeConfigSchema.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **id** | `string` | ✅ | Unique event identifier |
-| **type** | `string` | ✅ | Event type (e.g., record.created, record.updated) |
+| **type** | `string` | ✅ | Event type (e.g., data.record.created, data.records.updated) |
 | **object** | `string` | optional | Object name the event relates to |
 | **action** | `Enum<'created' \| 'updated' \| 'deleted'>` | optional | Action performed |
 | **payload** | `Record<string, any>` | ✅ | Event payload data |
@@ -64,14 +64,15 @@ const result = RealtimeConfigSchema.parse(data);
 
 ## RealtimeEventType
 
-Realtime event type 
+Realtime event type: a record-change event name the runtime emits
 
 ### Allowed Values
 
-* `record.created`
-* `record.updated`
-* `record.deleted`
-* `field.changed`
+* `data.record.created`
+* `data.record.updated`
+* `data.record.deleted`
+* `data.records.updated`
+* `data.records.deleted`
 
 
 ---
@@ -97,15 +98,15 @@ Realtime event type
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **id** | `string` | ✅ | Unique subscription identifier |
-| **events** | `{ type: Enum<'record.created' \| 'record.updated' \| 'record.deleted' \| 'field.changed'>; object?: string; filters?: any }[]` | ✅ | Array of events to subscribe to |
+| **events** | `{ type: Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted' \| …>; object?: string; filters?: any }[]` | ✅ | Array of events to subscribe to |
 | **transport** | `Enum<'websocket' \| 'sse' \| 'polling'>` | ✅ | Transport protocol to use |
 | **channel** | `string` | optional | Optional channel name for grouping subscriptions |
 
 ### Nested Shape: `Subscription.events[number]`
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `Enum<'record.created' \| 'record.updated' \| 'record.deleted' \| 'field.changed'>` | ✅ | Type of event to subscribe to |
+| **type** | `Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted' \| …>` | ✅ | Type of event to subscribe to |
 | **object** | `string` | optional | Object name to subscribe to |
 | **filters** | `any` | optional | Filter conditions |
 
@@ -118,7 +119,7 @@ Realtime event type
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `Enum<'record.created' \| 'record.updated' \| 'record.deleted' \| 'field.changed'>` | ✅ | Type of event to subscribe to |
+| **type** | `Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted' \| 'data.records.updated' \| 'data.records.deleted'>` | ✅ | Type of event to subscribe to |
 | **object** | `string` | optional | Object name to subscribe to |
 | **filters** | `any` | optional | Filter conditions |
 

packages/cli/src/commands/compile.ts

@@ -262,6 +262,15 @@ export default class Compile extends Command {
       //     catch-all below (`--json`: `error` + `code`, exit 1), the same
       //     envelope a `defineStack` refusal raised at load reaches.
       refuseUnbuiltStack(loaded);
+      // 1b. The ADR-0087 D2 conversions the PRODUCER applied — the same fold
+      //     `os validate` makes at its step 1b, for the same reason: `defineStack`
+      //     converts at load, so step 2's pass below finds nothing of the
+      //     default export left to convert, and `conversions` read `[]` on every
+      //     `defineStack` config. Read by `loadConfig` off the default export
+      //     before its named-export merge (`stackConversionsOf`). ⛔ Folded,
+      //     never recomputed. Rendered on the text face at step 2 with the
+      //     pass's own findings, in this one list.
+      conversionNotices.push(...loaded.stackConversions);
 
       if (!flags.json) {
         printKV('Config', path.relative(process.cwd(), absolutePath));
@@ -277,7 +286,10 @@ export default class Compile extends Command {
       //    bites harder than it reads, because the notice is the ONLY warning an
       //    old-shape author gets before the conversion retires and their metadata
       //    stops loading. Five conversions are live today (protocol 11 and 15),
-      //    so the gap is real, not hypothetical.
+      //    so the gap is real, not hypothetical. After step 1b the pass can still
+      //    find what the producer never saw — a key `loadConfig` merged onto the
+      //    stack from a NAMED export of the config module — and appends it to
+      //    the same list.
       if (!flags.json) printStep('Normalizing stack definition...');
       // The sink is declared above the `try` (see its note there); the CALL that
       // fills it stays right here, at the step that owns it.