Merge remote-tracking branch 'origin/main' into claude/issue-18163-export-hook-api-types

Author: claude

.changeset/15811-evaluated-expression-slots-source-required.md

@@ -0,0 +1,112 @@
+---
+"@objectstack/spec": minor
+"@objectstack/formula": minor
+---
+
+feat(spec)!: every engine-evaluated expression slot requires a non-blank `source` — the #15430 rule generalised from the flow-node ledger to the other 36 declaring positions (#15811, decision batch #122 item 2)
+
+<!-- adr-0087: registered evaluated-expression-slots-source-required -->
+
+**BREAKING** accept-set narrowing on 36 published metadata slots. Each of them
+composed `ExpressionInputSchema` and now composes `EvaluatedExpressionInputSchema`,
+so an envelope carrying only `ast` (`{ dialect: 'cel', ast: … }` with no `source`)
+and a `source` that is blank after trimming — through the envelope key or through
+the bare-string shorthand — are refused at the door instead of parsing and then
+faulting at run time. The prescription is registered under protocol major 18 as
+the semantic migration `evaluated-expression-slots-source-required`.
+
+**⚠️ Graded `minor`, not `major`, and the ruling said `major`.** Decision batch
+#122 item 3 ordered a 「`major` changeset」. This repo's launch-window convention
+ships breaking changes as `minor` while the fixed group versions in lockstep, and
+`scripts/check-changeset-no-major.mjs` enforces it: a `major` marker here would
+promote all ~70 packages to a whole-stack major release, which is a release act.
+The convention's own written carriers for breaking-ness are used instead and both
+are present — this **BREAKING** banner and the ADR-0087 disposition above. The
+ruling's substance (a breaking narrowing, carried by an ADR-0087 semantic
+migration entry) is delivered; only the marker differs, and it differs because a
+repo gate forbids the marker.
+
+**What is NOT narrowed.** `ExpressionSchema` / `ExpressionInputSchema` remain the
+persistence contract (`source` OR `ast`), by item 2 of the same ruling, and so
+does `PredicateInputSchema`, which is a plain alias of the latter. A slot that
+only PERSISTS an envelope is untouched; the narrowing is at the slots an engine
+EVALUATES. An `ast` carried BESIDE a string `source` stays admitted everywhere.
+
+**The population was re-derived, not inherited.** By identity — a negative
+lookaround on identifier characters, so `CronExpressionInputSchema` and
+`TemplateExpressionInputSchema` cannot leak in as substrings — over
+`packages/spec/src`, non-test: 34 declaring source lines, two of which are
+file-local alias consts (`ui/action.zod.ts` `ActionConditionInputSchema`,
+`system/settings-manifest.zod.ts` `SettingsVisibilityInputSchema`) that mount two
+slots each, giving **36 declaring positions**. Three of them reach the schema as a
+union member rather than head-of-declaration (`RecordAlertProps.visible`,
+`ServiceLevelIndicator.successCriteria`, `TraceSamplingConfig.composite[].condition`).
+
+On **two of those three the sibling arm is untouched**: `RecordAlertProps.visible`
+still takes a boolean literal, and `ServiceLevelIndicator.successCriteria` still
+takes its structured `{ threshold, operator, percentile? }` object — including one
+that happens to carry a `dialect` key.
+
+⚠️ **On the third, `TraceSamplingConfig.composite[].condition`, the sibling arm
+narrows too, and deliberately.** Its structured-filter arm is a bare
+`z.record(z.string(), z.unknown())`, which accepted `{ dialect: 'cel', ast }` as an
+ordinary filter — so swapping the expression arm changed nothing at all there. That
+arm now declines any object carrying a `dialect` key, and six shapes the base
+accepted THROUGH THAT ARM ALONE (measured: the base's `ExpressionInputSchema`
+refused every one of them) are refused at this slot:
+
+| authored `condition` | base | now |
+|---|---|---|
+| `{ dialect: 'cel' }` | accepted | refused |
+| `{ dialect: 'js', source: 'x' }` | accepted | refused |
+| `{ dialect: 'nope', source: 'x' }` | accepted | refused |
+| `{ dialect: 'cel', source: 5 }` | accepted | refused |
+| `{ dialect: 'cel', source: 'x', meta: { rationale: 5 } }` | accepted | refused |
+| `{ dialect: 'zzz', foo: 1 }` | accepted | refused |
+
+FROM → TO at that slot: if the value really is a **structured filter**, drop the
+`dialect` key (`{ dialect: 'cel', service: 'api' }` → `{ service: 'api' }`); if it is
+an **expression**, give it a dialect this platform evaluates and a non-blank `source`
+(`{ dialect: 'js', source: 'x' }` → `{ dialect: 'cel', source: 'x' }`). A structured
+filter that carries no `dialect` key — `{}`, `{ service: 'api' }`,
+`{ attributes: { 'http.route': '/v1/orders' } }` — is accepted exactly as before.
+
+**Why an authoring-time refusal and not a run-time one.** Measured at the
+chokepoint, `celEngine.evaluate` never silently succeeds on either shape — it
+returns a `parse` fault — so what happened next was decided entirely by the
+slot's fail policy, and the two halves of that population fail in opposite
+directions: fail-CLOSED slots (`ObjectFieldGroup.visibleWhen`,
+`RowCrudActionOverride.visibleWhen`, `BulkActionDef.visible`, the two
+settings-manifest `visible` slots) hid a group, a row button, or silently excluded
+every selected record from a bulk run and reported them as *skipped*; fail-SOFT
+slots left a gate that had stopped gating. Nothing in between said a word: the
+authoring lint `validateVisibilityPredicates` measured 0 findings on an `ast`-only
+envelope and 0 on a blank `source`, against two control legs that each measured 1.
+
+**`@objectstack/formula` gains `printCelAst(ast)`** — the inverse of
+`parseCelToAst`, and the lossless half of the migration: an `ast`-only CEL
+envelope is printed back to surface syntax mechanically, with no judgment asked of
+the author. It is lossless about MEANING, not bytes (the printer re-renders from
+the parse tree, so `'x'` comes back as `"x"`), and it answers `null` — never a
+guess — for anything it cannot round-trip through the platform's own bounded
+parser. That `null`, and every blank `source`, are what the semantic migration
+entry's structured TODO covers.
+
+**The published TypeScript interface `RowCrudPredicates` narrows with it**
+(`Expression | ExpressionInput` → `EvaluatedExpression | EvaluatedExpressionInput`),
+because it mirrors the two `RowCrudActionOverride` slots and a type that still
+promised an `ast`-only envelope would advertise what the schema now refuses.
+
+**So do the four expression constructors — `expression()`, `cel`, `tmpl`, `cron`
+(and therefore the `F` / `P` aliases) — which now return `EvaluatedExpression`
+instead of `Expression`.** Each one assigns a `string` to `source`
+unconditionally, so the wider return type described none of them; it was slop
+that cost nothing until an evaluated slot began requiring `source`, at which
+point ``visibleWhen: P`…` `` — the spelling the spec's own docblock teaches —
+stopped type-checking, and `@objectstack/platform-objects` failed its DTS build
+on exactly that. `EvaluatedExpression` is assignable to `Expression`, so every
+persistence-contract slot keeps accepting these values unchanged; what the
+narrower return type adds is that an evaluated slot accepts them too. An author
+who genuinely has no `source` was never calling these constructors — an
+`ast`-only envelope is an object literal, and an evaluated slot refuses it on
+purpose.

.changeset/18012-between-blank-endpoint-refused.md

@@ -0,0 +1,51 @@
+---
+'@objectstack/spec': minor
+---
+
+**BREAKING for authored metadata** — a `$between` range now requires two endpoints that are present and non-empty. A blank bound (`''` or an absent `undefined` bound, at either side) is refused at the authoring door, and the refusal names the blank side (#18012).
+
+Clause-②: yes
+
+Maintainer ruling A on decision batch #146 item 5, 2026-09-17 「146 同意」.
+
+## What changed, and why it is a new rule rather than a repair
+
+`FieldOperatorsSchema.safeParse({ $between: [1, ''] })` answered `success: true` — measured on the card against spec 17.4.0 and re-measured on `main` before this change. That acceptance was **conformant**: the endpoint contract shared by both bounds says verbatim that "Each endpoint is a number, a Date, or a string", and the empty string is a string. So this narrows a published face by adding a rule to it, rather than pulling code back to a declaration it was already violating.
+
+What made the acceptance wrong is the other half of the same contract — "Closed interval [min, max]" — which no backend can honour against a blank. `driver-sql` binds the blank into `whereBetween`; the JS matchers compare it as a value. Either way the range stops bounding on that side **while still reading as a complete two-element range**, so the query runs with one meaningless boundary and no signal at any layer. The reference matcher was already taught to survive the `null` form of exactly this (a bounded range answered every valued row, because both of the arm's comparisons are false against a missing bound); the door that admitted it was never addressed.
+
+The only producer ever measured is a UI builder padding a **half-typed** pair so a length-based completeness check passes it. Nobody writes a blank bound on purpose — which is why it is refused rather than given a published meaning.
+
+```
+FROM  FieldOperatorsSchema.safeParse({ $between: [1, ''] })
+      -> { success: true }                       // a half-filled range, green all the way
+                                                 // to the driver
+
+TO    FieldOperatorsSchema.safeParse({ $between: [1, ''] })
+      -> { success: false,
+           issues: [{ code: 'custom', path: ['$between', 1],
+                      message: 'A blank value is not a valid $between endpoint at index 1
+                                (the MAX bound). …' }] }
+```
+
+## Migration — FROM → TO
+
+| You wrote | Write instead |
+| --- | --- |
+| `{ $between: [1, ''] }` | `{ $between: [1, 100] }` — the upper bound you meant, written out |
+| `{ $between: ['', '2026-12-31'] }` | `{ $between: ['2026-01-01', '2026-12-31'] }` — the lower bound you meant |
+| a range that was only ever bounded on ONE side | `{ "$gte": min }` or `{ "$lte": max }` — a one-sided bound is not a range |
+
+**The one-line fix: write the bound that is missing, or — if only one side was ever meant — drop `$between` and write that side as a scalar comparison.** ⛔ Not mechanically convertible: the bound the author did not type is not recoverable from the one they did, so this ships as an ADR-0087 D3 structured TODO and **no D2 conversion**. Both of the two readings a conversion could take are wrong — dropping the operator deletes a constraint the author wrote and silently WIDENS the result set, and treating the blank side as unbounded invents a filter nobody authored.
+
+<!-- adr-0087: registered filter-between-blank-endpoint-refused -->
+
+## What does NOT change
+
+- **Arity.** A one-element or three-element `$between` was already refused, and still is, by the tuple's own contract. This rule is about a two-element range one of whose elements means nothing.
+- **`null` bounds.** Already refused since 2026-08-31, and they keep **their own** message, which prescribes the null predicate — an author who wrote `null` was reaching for absence, not for a bound. Two blank spellings, two intents, two remedies.
+- **Falsiness.** `{ $between: [0, 100] }` and `{ $between: ['0', '9'] }` parse exactly as before. The rule is blankness, not falsiness.
+- **Whitespace-only endpoints** are deliberately **not** judged. The ruling is the empty string; widening the refusal past it would narrow a published face further than the ruling did.
+- **The set slots.** `{ $in: ['', 'won'] }`, `{ $nin: [''] }`, `{ $eq: '' }` and `{ $gte: '' }` are untouched — an empty string is a legitimate stored VALUE, and only an interval ENDPOINT is judged here.
+- **Stored documents.** The read path does not re-validate stored rows, and the stored-row conversion pass neither validates nor drops anything, so no stored view becomes unreadable. What changes is that **re-saving** one is refused, at the endpoint's own path, with the blank side named.
+- **The published export surface.** No export is added, removed or renamed; the refusal rides the existing endpoint factory that both the documentation copy (`RangeOperatorSchema`) and the enforced copy (`FieldOperatorsSchema`) already share, so the two cannot drift.

.changeset/18612-cubejoin-retire-sql-relationship.md

@@ -0,0 +1,85 @@
+---
+'@objectstack/spec': minor
+---
+
+**BREAKING** — retire `CubeJoin.sql` and `CubeJoin.relationship`. A cube join declares
+WHICH object it reaches; the ON clause is derived from the declared relationship between
+the two cubes' objects and is never authored.
+
+`CubeJoin.sql` was **required** and described itself as the `ON` clause, and nothing ever
+read it. Both analytics strategies synthesise the join: `NativeSQLStrategy` emits
+`LEFT JOIN <name> <alias> ON "<parent>"."<segment>" = "<alias>"."id"` from the dotted member
+path alone, and `ObjectQLStrategy` resolves the join through `cube.joins?.[alias]?.name` and
+lowers it to a relationship traversal with no `ON` clause at all. So an authored join
+condition was not ignored — it was **replaced**, under a `200`, by an equality the author had
+not asked for, with a plausible number attached. `relationship` is the same shape one key
+over: it carried a `.default('many_to_one')`, nothing dispatched on the cardinality, and
+`one_to_many` parsed, changed no SQL and kept the many-to-one arithmetic.
+
+ADR-0049 enforce-or-remove; maintainer ruling 2026-09-18 (director batch #154 item 4,
+letter 2). The ruling declined the other remedy — executing the author's SQL — as a new
+capability whose first design question is an injection boundary, for zero authors today. A
+custom join condition, if a customer needs one, is a capability card with that boundary
+decided first.
+
+## FROM → TO
+
+| you wrote (17.4 and earlier) | write instead |
+| --- | --- |
+| `joins: { account: { name: 'crm_account', relationship: 'many_to_one', sql: '${orders}.account = ${crm_account}.id' } }` | `joins: { account: { name: 'crm_account' } }` — delete both keys |
+| `joins: { a: { name: 'b', relationship: 'one_to_many' } }` | `joins: { a: { name: 'b' } }` — the cardinality was never read; declare it on the object's own relationship field |
+| `joins: { a: { name: 'b', on: '…' } }` | `joins: { a: { name: 'b' } }` — `on` was the curated alias for `sql` and is retired with it |
+
+**The one-line fix:** delete `sql` and `relationship` from every `joins` entry; keep `name`.
+
+Nothing regresses by deleting them: neither key ever reached a query. What decides the join
+is `name` (the joined object, which is also what the per-object RLS/tenant read scope is
+computed for) and the declared relationship the runtime derives the equality from.
+
+## The retirement kit
+
+- **Strict deletion plus a `guidance` prescription, not a `retiredKey()` tombstone.** Every
+  cube shape is a `strictObject`, so the key leaves the walked shape entirely and the
+  refusal carries the upgrade: writing `sql`, `relationship` or `on` on a join is an
+  `unrecognized_keys` rejection whose message names the key and states that the `ON` clause
+  is DERIVED from the declared relationship between the two cubes' objects. Same route
+  `MetricSchema.filters` took one shape over in this same file.
+- **`on` is no longer an alias.** It pointed at `sql`; an alias naming a key the shape
+  cannot accept answers an author with a second rejection, so it became a `guidance` entry
+  of its own and the rename suggestion is gone. Pinned in both directions.
+- **ADR-0087: a D2 conversion AND a D3 semantic entry**, plus the two exact-key
+  registrations `data/CubeJoin:sql` and `data/CubeJoin:relationship` in
+  `RETIRED_KEYS_BY_MAJOR[18]`. The conversion is
+  `cube-join-sql-and-relationship-removed` (`toMajor: 18`,
+  `retiredFromLoadPath: true`), chained into step 18: it strips both keys from every
+  `analyticsCubes[].joins.*` wherever the chain is replayed, one notice per stripped site,
+  each naming the cube that lost the key. It is owed because the removal is measured
+  against **metadata at rest**, not only against sources: `sql` was required and
+  `relationship` was defaulted, so every cube artifact ever written from the old schema's
+  own parse output carries both keys, and the boot door
+  (`ObjectStackDefinitionSchema` → `analyticsCubes: z.array(CubeSchema)`) would otherwise
+  refuse it with no remedy short of hand-editing JSON. The strip is lossless in the only
+  sense that applies: a key that never had an effect has none to lose. The D3 entry
+  `cube-join-sql-and-relationship-retired` stays as the human-facing record — the strip
+  removes the key, the entry says why an author who wrote a non-FK `sql` should re-read the
+  numbers that join produced.
+- **The `os migrate meta --from 17` sentence** closes all three prescriptions, which is what
+  a covered surface owes.
+- **The `joins` record KEY is documented.** `name`'s describe now states that the key a join
+  is declared under is the FOREIGN-KEY FIELD on the cube's own base object — the column the
+  derived `ON` reads — not a second spelling of the object the join reaches.
+- **The liveness ledger rows went WITH the keys** (`liveness/analytics_cube.json`), which is
+  the strict-deletion route's disposition — the opposite of the tombstone route, which keeps
+  the row because `retiredKey()` keeps the key in the walked shape. `analytics_cube` drops
+  from 12 `dead` to 10.
+- **The one in-repo producer is fixed in the same diff.** `examples/app-showcase`'s
+  `DeliveryCube` authored both keys, including an `ON` clause the runtime was replacing;
+  `dataset-compiler.ts` minted them as two constants no reader consulted. Its join was also
+  keyed `showcase_project` — the object it reaches — while `showcase_task`'s foreign key is
+  `project`, so the derived `ON` named a column the base object does not have and the join
+  never resolved. It is re-keyed `project` here and pinned against the object's own field
+  map.
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: registered cube-join-sql-and-relationship-retired -->