Merge branch 'main' into claude/issue-19011-revert-declaration-text-snapshot

Resolves 13 modify/delete conflicts under packages/spec/api-surface-declarations/.

Every conflict has the same shape: this branch deletes the file (no stage 2),
main regenerated it (stage 3). Retiring that directory is the revert's whole
purpose, so each conflict resolves to the delete. All 17 shards are gone from
the merged tree -- the 4 main did not touch auto-resolved to delete already.
The one other overlapping path, scripts/pm/dispatch-gates.mjs, auto-merged:
main's hunk sits about 1600 lines from the reverted one.

Verified on the merged tree rather than assumed:

- no code, script, workflow, gitattributes or package.json entry references
  api-surface-declarations in any spelling; the only three mentions left are
  historical prose in .changeset release notes (17108, 18991, 19085), reported
  separately and deliberately not edited here.
- of the 31 paths the reverted commit touched, none still carries a line that
  commit added; the four that differ from its parent are later, unrelated work
  main landed (lint.yml keeps #18889's step; check-published-files,
  dispatch-gates and regen-artifacts carry post-revert commits).
- api-surface-signatures.json is back with its 27 hashes and, built from these
  merged sources, check:api-surface reports the public API surface and factory
  signatures unchanged -- so the restored pin is correct, not merely present.
- check:generated reports all 15 artifacts up to date; main's count is 16, and
  16 is what #18971 made it when it registered check:api-surface-declarations.

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

Author: claude

.changeset/15124-action-engine-facade-find-query-envelope.md

@@ -0,0 +1,93 @@
+---
+'@objectstack/spec': minor
+'@objectstack/runtime': minor
+---
+
+**BREAKING for action handlers** — `ActionEngineFacade.find` takes the engine's query ENVELOPE; the bare-filter parameter shape is withdrawn (#15124)
+
+Clause-②: yes (narrowing)
+
+`ctx.engine.find(object, query)` now takes `EngineQueryOptions` — the same
+options bag `IDataEngine.find` and ObjectQL's own `engine.find` take, named by
+identity rather than restated. **One platform, one query shape.**
+
+### Migration — FROM → TO
+
+| You wrote | Write instead |
+| --- | --- |
+| `ctx.engine.find('task', { status: 'open' })` | `ctx.engine.find('task', { where: { status: 'open' } })` |
+| `ctx.engine.find('task', { amount: { $gt: 100 } })` | `ctx.engine.find('task', { where: { amount: { $gt: 100 } } })` |
+| `ctx.engine.find('task', {})` | unchanged — an empty envelope is still the unfiltered read |
+
+The rewrite is lossless and mechanical: the filter moves under `where`, verbatim.
+`tsc --noEmit` over your handlers finds every unmigrated call — see below.
+
+### Why the shape was withdrawn rather than the bar closed
+
+Until now this parameter was the `where` HALF of a query while every other
+`find` on the platform took the whole envelope, and the runtime wrapped what it
+was given. That made the most natural spelling the wrong one, silently: an
+author who passed the engine's own envelope reached the engine as
+`{ where: { where: … } }` — a filter on a field named `where` — which matches no
+row and resolves to `[]` with **no error at all**. A handler that made the
+mistake ran to completion over zero rows for as long as it shipped, and its own
+hand-written test double, written to the same belief, passed every assertion.
+Because an empty `{}` skipped the wrap, one unfiltered read kept working under
+either belief, so a dead handler looked partially alive.
+
+Refusing `where` at the top level instead — intersecting the old parameter with
+`{ where?: never }` — was rejected: it asserts a vocabulary fact the spec
+declares nowhere, reserving the field name `where` across every customer's data
+model to buy one parameter's compile-time check. Aligning the parameter removes
+the ambiguity at its root and reserves nothing.
+
+### What the new declaration refuses, measured
+
+If your handler is typed with the published `ActionHandlerContext`, a bare filter
+no longer type-checks on **either** path you can reach it by:
+
+- an object literal (`{ status: 'completed' }`) fails the excess-property check —
+  a field name is not an envelope key;
+- a filter held in a `FilterCondition` variable fails **TS2559** — every envelope
+  key is optional, so a bag of field names has no property in common with it.
+
+The envelope's own keys are typed too: `where: 'a = b'`, `fields: 'id,subject'`
+and `limit: '50'` are each refused.
+
+**If your handler is NOT typed with it** — a handler in an `objectstack.config.js`
+/ `.mjs`, one annotated with your own copy of the context type, or a `(ctx: any)`
+handler — nothing above reaches you, so the facade refuses the withdrawn shape at
+**runtime** instead, before the engine, with the same prescription:
+
+```
+find('task') was given a key 'status' the query envelope does not carry.
+ctx.engine.find(object, query) takes the engine QUERY ENVELOPE, not a bare
+filter — move the filter under `where`: find(object, { where: { … } }).
+Envelope keys: context, cursor, distinct, expand, fields, limit, offset,
+orderBy, search, searchFields, top, where.
+```
+
+⚠️ **That refusal matters most for a filter whose value is `null`.** The engine's
+own unknown-option check exempts a `null` value, because on an option bag a
+`null` is a withdrawal. On a filter it is the "rows with no X" idiom, so
+`{ deleted_at: null }` would have been dropped unexecuted and the read would have
+widened to **every row** — including the ones you were excluding — with no error
+at all. It is refused instead.
+
+### What this opens
+
+`fields`, `orderBy`, `limit`, `offset` and `expand` are reachable from an action
+handler for the first time — under the old parameter there was nowhere to carry
+them. A caller-supplied `context` is **ignored**: this facade is trusted and
+context-less by design, and the runtime stamps its own elevated
+`ExecutionContext` last. Do not write one — it reads as authorization and is
+none.
+
+### Checking a migrated handler
+
+Do not settle for "it still resolves". A handler that had been passing the
+envelope was returning `[]` on **every** call, so a suite written against the
+mistake passes and the row count is the only witness. Re-run each migrated
+handler against seeded data and assert it returns the rows its filter selects.
+
+<!-- adr-0087: registered action-engine-facade-find-query-envelope -->

.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/16292-cron-timezone-iana-domain.md

@@ -0,0 +1,38 @@
+---
+'@objectstack/spec': minor
+---
+
+fix(spec)!: `CronSchedule.timezone` is judged by the `iana_time_zone` membership predicate (#16292)
+
+**BREAKING** — an accept-set narrowing on a published authoring key.
+`CronScheduleSchema.timezone` was a bare `z.string().optional().default('UTC')`, so
+`defineJob` and `JobSchema.parse` took `timezone: 'UTC+8'` at authoring and build time
+and said nothing. It is now judged by `isValueDomainMember('iana_time_zone', …)` — the
+predicate `@objectstack/spec/shared` already exports, and the same judge the four
+`valueDomain: 'iana_time_zone'` columns (`sys_business_unit.timezone`,
+`sys_organization.timezone`, `sys_job.timezone`, `sys_report_schedule.timezone`) are
+written against. Shipped as `minor` under the repo's launch-window convention for
+accept-set narrowings.
+
+No job that ran yesterday stops running. The value was already carried unchanged to
+`CronJobAdapter.schedule`, where croner — constructed with a callback — throws on a
+non-member and `AppPlugin` records a per-job `FAILED TO SCHEDULE` at `error` level plus
+a `jobScheduleFailuresTotal` increment: the job was declared and never ran. What moves
+is WHEN its author is told, from the first environment that boots to `defineJob` /
+`os build`. So a stack whose job carries a zone the platform cannot honour now stops
+building instead of booting-and-not-running.
+
+Membership is the `Intl.DateTimeFormat` probe rather than a checked-in list, so the
+accepted set is the host's own tz database — deliberately, and identically to those four
+columns, the settings door and `resolveAuthzContext`. It is what every `Intl`-based
+consumer downstream accepts, so the parse-time answer and the schedule-time answer
+cannot disagree on one host. `UTC`, the key's own declared default, is a member on every
+conforming runtime, so an omitted key is untouched.
+
+`interval` and `once` schedules carry no zone and are unaffected. The boundary type
+`JobSchedule.timezone` on `@objectstack/spec/contracts` is a third, separate door and is
+deliberately left out of this change.
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) No key, export, config field or stored shape is added, removed, renamed or re-spelled, and no metadata document has to be rewritten into a different one. The narrowing is value-level and undecidable in the upgrade direction: an offset spelling such as `UTC+8` names no zone at all, so nothing can derive whether its author meant `Asia/Shanghai`, `Asia/Singapore` or `Australia/Perth` — the answer is a fact about the deployment, never about the refused string. `objectstack migrate meta` therefore has nothing mechanical it could apply, and a ledger row would carry an empty mapping. The sibling column-tier narrowing of the same concept is already recorded as `platform-timezone-columns-iana-domain-refused`; this authoring-tier door is a different door and is deliberately not filed under that id. -->

.changeset/17393-view-row-ceiling.md

@@ -0,0 +1,36 @@
+---
+'@objectstack/spec': minor
+---
+
+Gallery, kanban and timeline view configs declare an author-settable row ceiling.
+
+`GalleryConfigSchema`, `KanbanConfigSchema` and `TimelineConfigSchema` each gain a
+`limit` member — a positive integer, default **100** — saying how many records the
+view fetches. The default is APPLIED by the schema rather than only described, and
+the key's own text states the other half of the contract: when the ceiling applies,
+the renderer must show a visible truncation signal, because a bounded view that
+looks complete is worse than an unbounded one. `DEFAULT_VIEW_ROW_LIMIT` is exported
+so a consumer reads that number instead of re-declaring it.
+
+The knob belongs in the protocol because two renderers already cap by author choice
+off keys the protocol never declared: objectui's kanban board fetches
+`$top: schema.limit ?? DEFAULT_KANBAN_LIMIT` with `limit` declared in
+`@object-ui/types` alone, its timeline does the same off a component props
+interface, and its gallery caps not at all. `limit` is the name those consumers
+already read, so this declaration absorbs the consumer-local keys instead of
+introducing a second spelling of one concept.
+
+Nothing is removed, renamed or narrowed, and no document that parsed before is
+refused now. Two things to know when upgrading:
+
+- a parsed gallery / kanban / timeline config carries `limit: 100` where the author
+  wrote no ceiling, so code that compares a parsed config against a literal object
+  sees the new member;
+- `KanbanConfigParsed` is now declared (ADR-0122) because that schema has two shapes
+  for the first time; `KanbanConfig` is unchanged and remains the author state.
+
+The non-grid four — gantt, calendar, map and tree — are deliberately untouched:
+their rows stay bounded by a platform ceiling the renderer owns, because a gantt's
+range, a map's camera fit and a tree's parent chain are computed over the whole set.
+
+Clause-②: yes (widening)