Merge origin/main into the #4439 branch

#4453 landed the same class of fix from the other end: `evaluateCondition`
now sniffs the dialect from the source instead of from the caller, so a bare
string is CEL unless it holds a `{var}` hole. Three overlaps to reconcile:

- The flows guide's "Expressions in flows" section was rewritten on both
  sides. Kept main's — it is more complete about what the `{var}` dialect
  now does — and folded in the one fact it cannot know: a decision's
  `conditions[].expression` is on the expression ledger as a predicate, so a
  braced spelling there is a build failure, not the `{var}` dialect. Main's
  "the `{var}` form still works" is true of a start node's plain-string
  condition and would have been wrong for a decision.

- `FlowNodeSchema`'s `@example` likewise. Kept both branches from main and
  dropped its `// default` annotation on the `true` catch-all: since #4414
  the default path is the `isDefault` out-edge, not a catch-all branch.

- The decision executor's explicit `dialect: 'cel'` envelope is now
  redundant for the case it was added for, but it is what keeps run time
  agreeing with the validators: the sniff would route a braced predicate to
  the template dialect and run it, while `registerFlow` / `objectstack
  validate` reject exactly that spelling. Comment rewritten to say so —
  the old one described a path that no longer exists.

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

Author: claude

.changeset/aggregate-bulk-dispatch-selected-ids.md

@@ -0,0 +1,26 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): allow the aggregate bulk dispatch key `_selectedIds` through the action param gate (objectui#3139)
+
+A list view's `bulkActionDefs` entry can now opt into an aggregate single-call
+dispatch (`execution: 'aggregate'`, objectui 17.1): the renderer invokes the
+named object action ONCE for the whole selection, injecting every selected
+record id as `params._selectedIds: string[]`, so a single call can produce one
+aggregate artifact (zip of QR codes, merged PDF, batch print job).
+
+`ACTION_PARAM_BUILTIN_KEYS` gains `'_selectedIds'` so the ADR-0104 strict
+param gate does not 400 an aggregate dispatch against an action that declares
+params — like `recordId`/`objectName`, the key is dispatcher-injected and can
+never be authored as a declared param. Pure widening: actions declaring no
+params were never validated, and no authored bag legitimately carried this
+key. The `bulkActionDefs` describe now documents the aggregate contract
+(server reads `params._selectedIds`, results are all-or-nothing, `batchSize`
+does not apply, set `maxRecords` for expensive aggregates, and toolbar
+url/api actions can interpolate `${ctx.selection.ids}`).
+
+The showcase's Task → Bulk Actions view carries the specimen:
+`showcase_recalc_selection` dispatches the recalc endpoint once for the whole
+selection via the endpoint's new `_selectedIds` batch branch, next to the
+per-record fan-out fixtures.

.changeset/authoring-rule-command-coverage-registry.md

@@ -0,0 +1,68 @@
+---
+"@objectstack/cli": minor
+---
+
+fix(cli): every author-time rule that can gate runs on all three commands (#4409)
+
+`os validate`, `os build` and `os lint` each hand-wired their own subset of the
+author-time rules. Nothing connected the three lists, so "which rules run here?"
+was answerable only by diffing three 800-line files by eye — and the answer
+drifted every time a rule landed. The audit found 23 of 26 rules running on some
+strict subset, nine of them able to emit `error`.
+
+The worst direction was the least obvious. `os build` — the command that
+PUBLISHES — was the weakest gate of the three: a flow whose expression approver
+does not parse (`approval-expression-invalid`) built and published green, and
+only `os lint` stopped it, while CI usually runs the other two. `os lint`
+disagreed in *both* directions at once, running one gating rule neither other
+command ran and missing six that both of them ran, which is worse than no
+pre-flight — the remaining options are re-verifying everything or learning to
+distrust the signal.
+
+This is the same failure mode's fifth appearance (#3583, #3782, #4384/#4394,
+#4402). Each earlier repair removed an instance and left the MODE: a rule's
+command coverage was whatever its author remembered to type, and forgetting was
+silent. #4402's guard could not catch the rest — it filtered on the current
+member names of one suite, so a rule hand-wired into two commands from outside
+that suite passed it without a word. A name list only guards the names on it.
+
+**The registry.** `AUTHORING_RULES` declares all 26 rules as data: tier
+(`gating`/`advisory`), which stack tier they read (pre-parse `normalized` vs
+`parsed`), which commands run them, and a written reason for the one narrowing.
+All three commands consume it through `runAuthoringRules()`, so adding a rule is
+a one-line edit that reaches every command at once. The three command files
+shrink by ~1000 lines between them.
+
+**The ratchet.** The wiring guard is no longer a name list: a `gating` rule on
+fewer than three commands fails, a narrowed rule with no reason fails, a command
+that calls or imports a registry rule directly fails, and an `advisory` claim is
+checked against the rule's own source — so a gate cannot wear an advisory label
+to buy itself partial coverage. That last check is the one #3760 needed, having
+promoted a `lintFlowPatterns` rule from advisory to gating with nothing anywhere
+asking whether its coverage should follow. Remaining direct calls are listed
+with reasons, and a stale entry fails too, so the ratchet cannot rot into a
+permanent permission slip.
+
+**The verdict, not just the wiring.** A separate test plants one defect per
+previously-blind gating rule and asserts all three commands gate on it, plus the
+issue's own repro driven end-to-end through the real CLI: exit 1 on all three
+where it was 1/0/0.
+
+Two behaviour changes fall out of reporting every failing rule in one run
+instead of exiting at the first failing gate: an author with three unrelated
+problems now sees all three in one pass, and `--strict` covers every advisory
+rather than the roughly half that happened to be printed inline.
+
+Also closes the same hole one gate over: `collectAndLintDocs` failed `os build`
+and never ran on `os validate`, invisible because the parity guard keyed on the
+`lint*`/`validate*` naming convention and that gate is called `collect*`. The
+guard now names each shared non-registry gate explicitly instead of
+pattern-matching for them.
+
+Cost is not what argued against any of this. The heavy dependencies
+(`typescript` ~9 MB, `sucrase`) are already lazy and load only when a stack
+carries the metadata that needs them, and the heaviest rule of the set has run
+on all three commands as a reference-integrity suite member since #4340 without
+anyone noticing. The one narrowed rule, `lintUniqueDeclarations`, is scoped
+because `os lint` already reports it through `lintDataModel` — coverage
+recorded, not coverage missing.

.changeset/client-readme-retired-validate-only.md

@@ -0,0 +1,25 @@
+---
+'@objectstack/client': patch
+---
+
+docs(client): drop the retired `validateOnly` batch option from the README (#4052)
+
+The Batch Options section still documented `validateOnly` as a working dry-run —
+"validate records without persisting changes" — but the key was retired in #4052
+precisely because nothing ever read it. Every batch surface (`updateManyData` /
+`deleteManyData` / `batchData`) persisted regardless, so a caller who sent it to
+preview a mutation got that mutation **executed**.
+
+`BatchOptionsSchema` has carried a `retiredKey(...)` tombstone since #4052, so the
+schema already refuses the key loudly. The README was the last place still
+promising it — declared-but-not-enforced in prose rather than in code, aimed at
+exactly the readers who cannot see the tombstone.
+
+Released as a patch rather than declared release-nothing because `README.md` is in
+this package's `files`: the corrected text only reaches the people who hit the
+problem — readers on npmjs.com — if the package ships.
+
+Replaced with a pointer to `docs/protocol-upgrade-guide.md`
+(`batch-options-validate-only-retired`). No behaviour change; there is no batch
+dry-run today. Write-path validate-only was evaluated in #4372 and closed as not
+planned — no current consumer justifies the surface.

.changeset/datasource-config-driver-contract.md

@@ -0,0 +1,77 @@
+---
+'@objectstack/spec': minor
+'@objectstack/service-datasource': minor
+---
+
+`datasource.config` is now validated against its driver's contract (#4410)
+
+`config` was the one authorable slot on a datasource with no gate at all. The
+schema's own comment claimed "the driver's own `configSchema` is what validates
+it" — nothing did: both bundled driver specs set `configSchema: {}`, no code read
+the field, and the per-driver zod schemas were not even exported from the
+package. So `config: { hostname: 'db.internal' }` (the key is `host`) was
+accepted in silence and the datasource connected to `localhost` while the parse,
+the save and the connection probe all reported success.
+
+`DatasourceSchema` now parses `config` — and each `readReplicas` entry — against
+the contract for the declared driver, and `DatasourceAdminService`
+(create/update/test, the Setup wizard's path) applies the same check. Both read
+one registry in `@objectstack/spec/data`, which also projects each contract to
+JSON Schema for `DriverDefinitionSchema.configSchema` and the Studio connection
+form, so the form offers exactly the fields the validator accepts.
+
+New exports from `@objectstack/spec/data`: `PostgresConfigSchema`,
+`MysqlConfigSchema`, `SqliteConfigSchema`, `SqliteWasmConfigSchema`,
+`MongoConfigSchema`, `MemoryConfigSchema`, plus `resolveDriverId`,
+`getDriverConfigSchema`, `getDriverConfigJsonSchemaById` and
+`validateDriverConfig`. A driver the platform ships no contract for (a plugin's
+`com.vendor.snowflake`) keeps an unvalidated `config`.
+
+**Migration.** A config that was silently ignored now fails with the correction
+in the message. The renames:
+
+| Wrote | Write instead | Driver |
+| --- | --- | --- |
+| `user` | `username` | postgres, mysql, mongo |
+| `connectionString` / `dsn` | `url` | postgres, mysql, mongo |
+| `uri` | `url` | mongo |
+| `file` / `path` / `database` | `filename` | sqlite, sqlite-wasm |
+| `hostname` | `host` | postgres, mysql, mongo |
+| `searchPath` | `schema` | postgres |
+
+And the relocations — keys that were never driver config:
+
+| Wrote in `config` | Write instead |
+| --- | --- |
+| `min` / `max` / `idleTimeoutMillis` / `connectionTimeoutMillis` | the datasource's own `pool` block |
+| `schemaMode` | next to `driver`, on the datasource |
+| `readOnly` | `capabilities: { readOnly: true }` |
+| `ssl: { ca, cert, key, rejectUnauthorized }` | the datasource's own `ssl` block — inside `config`, `ssl` is the on/off boolean shorthand |
+
+Two memory-driver keys are **removed**: `indexes` and `maxRecordsPerObject`.
+`InMemoryDriverConfig` has no field for either — the driver keeps no indexes and
+evicts nothing — so both were inert. Drop them; for real indexing use a driver
+that indexes.
+
+A postgres, mysql or mongo datasource must now name a connection target
+(`database`, or a `url` that carries it). An empty `config` used to mean "the
+client's own localhost default", which is the same defect in its most complete
+form.
+
+**Also fixed, because the contract can only be enforced where it is honoured.**
+These keys were declared and read by nothing; they now reach the driver:
+
+- `datasource.pool` is honoured by every SQL driver (it was declared, carried
+  into the connection spec, then overwritten with a hardcoded `{ min: 0, max: 5 }`),
+  and maps onto the Mongo client's `minPoolSize` / `maxPoolSize`.
+- `datasource.schemaMode` reaches the driver. It was dropped between the
+  datasource record and the connection spec, so a `schemaMode: 'external'`
+  database — one ObjectStack must never run DDL against — was constructed as
+  `managed`.
+- `datasource.ssl` reaches the SQL clients, certificates and all. It stopped at
+  the record — nothing put it on the connection spec — so a TLS block configured
+  nothing, which is exactly what its own schema comment warns about ("a TLS
+  setting that never took effect looked identical to one that did").
+- postgres `schema` (knex `searchPath`), `applicationName` and `statementTimeout`.
+- mongo `password`, `authSource` and `options`. A mongo datasource carrying a
+  `config.password` previously composed its URL with an **empty** password.

.changeset/discovery-cache-queue-job-no-route.md

@@ -0,0 +1,25 @@
+---
+"@objectstack/spec": patch
+"@objectstack/metadata-protocol": patch
+"@objectstack/runtime": patch
+---
+
+fix(spec,metadata-protocol,runtime): discovery stops advertising routes for the kernel-internal cache/queue/job slots (#4318)
+
+The metadata-protocol discovery builder declared `/api/v1/cache`, `/api/v1/queue`
+and `/api/v1/jobs` — three paths that existed nowhere else in the repository: no
+dispatcher domain, no adapter mount, no plugin registration, and the shipped
+providers (`service-cache`/`-queue`/`-job`) are in-process contracts that will
+never mount one. Every default boot therefore advertised a route inside the same
+`ServiceInfo` whose `handlerReady: false` said the opposite — a single record
+contradicting itself (ADR-0076 D12).
+
+These slots are route-less now, like `realtime` — but unlike `realtime` an
+unmarked real implementation stays `available`: the slot's contract is
+in-process, so "no HTTP surface" is not reduced capability for it. `handlerReady`
+is reported `false` on both discovery builders — for a route-less slot it is not
+a proxy for anything, it is the fact itself (the dispatcher used to claim
+`handlerReady: true` here for an unmarked occupant, a handler that does not
+exist). The explanatory message is written once, as
+`inProcessServiceMessage(slot)` in `@objectstack/spec/system`, so the two
+builders cannot drift apart.

.changeset/findone-requires-a-predicate.md

@@ -0,0 +1,70 @@
+---
+"@objectstack/objectql": major
+"@objectstack/spec": patch
+"@objectstack/driver-mongodb": patch
+"@objectstack/driver-sql": patch
+---
+
+fix(objectql,driver-mongodb)!: `findOne` must say which record it wants, and executes every option it declares (#4419)
+
+`findOne` reads a single row, which makes its predicate the only thing between
+the caller and *an arbitrary record*. When the predicate is missing the result is
+not `null` — it is the object's **first row**: a real, plausible-looking record
+with nothing to do with the request, which the `if (!row)` check every call site
+already has cannot catch, and which then propagates into whatever is computed
+next. Reported downstream: line items defaulting their price from the first
+product in the catalog rather than the selected one, and "is this deal already
+closed?" answered against an unrelated record while the write that followed
+correctly targeted the intended id. A throw would have been caught in
+development; a `null` would have been caught by the null-check. A valid-looking
+wrong record defeats both.
+
+**Breaking — `findOne` now refuses a query that selects nothing in particular.**
+
+FROM → TO:
+
+| Was | Now write | Meaning |
+|---|---|---|
+| `findOne(o)`, `findOne(o, {})`, `findOne(o, { where: {} })` | `findOne(o, { where: … })` | the record matching this predicate |
+| | `findOne(o, { search: 'Acme' })` | the record this search finds |
+| | `findOne(o, { orderBy: [{ field: 'created_at', order: 'desc' }] })` | the FIRST record in this order — the newest |
+| | `find(o, { limit: 1 })` | any row will genuinely do, said at the call site |
+
+One-line fix: add the `where` you meant, or `orderBy` if you meant "the newest
+one", or switch to `find(o, { limit: 1 })` if any row will do. The error names
+all four. `find` and `count` are unchanged — returning or counting every row is
+an honest answer; only `findOne`'s implicit "just one of them" turns a missing
+predicate into a confidently wrong record. The guard reads the CALLER's
+predicate, before RLS/sharing middleware injects its own: a tenant filter
+narrows which rows are visible, it does not make "whichever comes first"
+something the caller asked for.
+
+**Two silent drops that produced the same wrong record are fixed with it.**
+
+- **`findOne({ search })` applies the search.** The ADR-0061 `search` →
+  cross-field `$contains` expansion lived inline in `find` and nowhere else,
+  while `find` and `findOne` are checked against the SAME legal-key set — so
+  `search` passed the gate, rode onto the AST, and reached a driver. No driver
+  reads `ast.search`. The read therefore ran with no predicate at all and
+  `limit: 1` did the rest. The expansion is now one method both call.
+- **`MongoDBDriver.findOne` applies `orderBy`, `fields` and `offset`.** It
+  translated `query.where` and dropped the rest, so `findOne({ orderBy })` did
+  not return the newest record — it returned whichever document the scan reached
+  first. `find` and `_findStream` in the same driver had always handled all
+  three. This one matters beyond Mongo: the guard above tells an unpredicated
+  caller to reach for `orderBy`, and an escape hatch one backend ignores is not
+  an escape hatch. No ordering is IMPOSED when the caller supplies none — both
+  drivers keep that carve-out (#4363), and `SqlDriver`'s comment about Mongo
+  "never sorting" is corrected, since it cited the dropped parameter as
+  agreement.
+
+**And a gate so the class does not come back.** A drift pin walks
+`ENGINE_OPTION_KEY_SETS.findOne` and requires each declared key to have an
+observable effect — on the AST the driver receives, on the driver options, or in
+an explicit "not executed, and here is why" entry (only `limit`, which the
+contract's `limit: 1` overrides). `search` sat declared-but-unexecuted through
+two rounds of hardening because nothing asked that question.
+
+Together with #4346 (`filter` → `where` folds on every entry point) and #4400
+(unknown option keys throw), a read parameter the engine does not execute now
+fails at the call site instead of quietly changing the answer.

.changeset/flow-condition-bare-string-is-cel.md

@@ -0,0 +1,53 @@
+---
+"@objectstack/service-automation": minor
+---
+
+fix(automation): `evaluateCondition` decides the dialect from the source, not from the caller (#4336)
+
+`AutomationEngine.evaluateCondition` picked its engine by asking whether an
+`{ dialect, source }` **envelope** was present. A condition handed to it as a
+plain string therefore never reached the CEL engine: it fell through to the
+legacy `{var}` template path, which substitutes brace holes and then compares
+whatever text is left — **as text**. Nothing errored, and the run was recorded
+as `success`, with the failure direction depending on the predicate:
+
+| Handed in | Actually evaluated | Result |
+|:---|:---|:---|
+| `existingTask == null` | `'existingTask' === 'null'` | always **false** — gate never opens |
+| `record.rating >= 4` | `'record.rating' >= '4'` → `'r' > '4'` | always **true** — branch pinned open |
+
+#4414 fixed the one built-in that was reaching this — the `decision` executor
+now wraps `conditions[].expression` in a CEL envelope before calling. This
+fixes the **evaluator**, so the next caller does not have to remember: the
+dialect is now read from the source, and a condition is CEL unless it actually
+contains a `{var}` hole. `evaluateCondition` is public API, so a
+plugin-registered node executor evaluating its own predicate was getting the
+table above with nothing to warn it.
+
+**The legacy `{var}` dialect keeps working** where it always did —
+`{amount} > 100`, `{status} == active`, `{a.b} == 7` — and gains the two things
+it was missing:
+
+- **A quoted literal compares as its contents.** `{status} == 'active'` used to
+  compare `active` against `'active'` — quotes included — and was false for
+  every value of `status`. It is the spelling the flow docs showed, and quoting
+  a string literal is what every other predicate surface requires.
+- **It no longer answers `false` when it could not resolve something.** A `{…}`
+  hole matching no flow variable (`{lead_record.status}` — `get_record` stores
+  the whole row under one name, so that key never exists) and a substituted
+  value that is neither a boolean, a number, nor part of a comparison are
+  refused with the source and the offending reference attached. Both used to be
+  a silent `false`, which ADR-0032 §1c forbids: a predicate that cannot be
+  evaluated is a fault, never a quiet branch decision.
+
+Braces inside an explicit `dialect: 'cel'` envelope remain the #1491 brace-trap
+and still throw — stating the dialect is the author saying "this is CEL". The
+sniff reads the source outside string literals, so `record.label == '{pending}'`
+stays CEL and compares the field.
+
+**Tightening to know about:** a bare string that is not valid CEL now raises
+where it previously string-compared to some answer. That includes the
+host-language payloads the safety tests use (`process.exit(1)`,
+`require("fs")…`) — nothing executed before and nothing executes now, since CEL
+has no `process`, no `require` and no arrow functions, but the failure is a
+reported fault instead of a silent `false`.