Merge remote-tracking branch 'origin/main' into claude/discovery-cache-queue-route-conflict-8fwmfc

Author: claude

.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/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`.

.changeset/react-tier-record-blocks-withdrawn.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/spec": minor
+"@objectstack/lint": minor
+---
+
+fix(spec,lint): withdraw the `record:*` blocks from the react tier — no renderer read the props it published (#4413)
+
+The react-tier contract published `objectName` / `recordId` on
+`<RecordDetails>`, `<RecordHighlights>`, `<RecordRelatedList>` and
+`<RecordPath>`, and no renderer read either prop. All ten `record:*` renderers
+take their record from `useRecordContext()`, which only the record route
+(`RecordDetailView`) and the metadata editor's preview (`PagePreview`) ever
+mount; the `kind:'react'` page renderer wraps the page in a
+`SchemaRendererProvider` alone. So the blocks rendered their "bind a record to
+preview" placeholder — or, for `record:related_list` (the one that does read
+`schema.objectName`), refused to fetch because the parent id never arrived. A
+page authored exactly to contract came back EMPTY with nothing reported
+anywhere, including by `os validate`, which resolved those props' field names
+against the object they named: lint standing guard over a binding that never
+ran.
+
+Withdrawn rather than implemented. The contract was not merely unimplemented,
+it was the wrong SHAPE: per-block bindings describe four independent fetches of
+one record, which is exactly the coupling the shared record context exists to
+prevent (`record:details` drops the fields a mounted `record:highlights`
+registered; one inline-edit save bar commits them all under a single
+`ifMatch`). Honoring the props would have fossilized that (Prime Directive
+#12). The naming of that primitive — a record SCOPE an author wraps around the
+family, one fetch, shared context — is the open design question, filed as #4444.
+
+`@objectstack/spec` drops the four blocks from `REACT_BLOCKS` and gains the
+ledger for why, plus the working replacement per type. The family is derived
+from `ComponentPropsMap`, so a record component added later is gated the day it
+lands — including the six that were never in the contract but are just as
+reachable through the registry-built react scope.
+
+`@objectstack/lint` gains `react-block-needs-record-context` (error), which
+rejects them on a react page by tag and through `<Block type="record:…">`
+alike, quoting the block that does work: `<ListView filters={['<lookup>', '=',
+parentId]}>` for a related list, `<ObjectForm mode="view" recordId={…}>` for a
+field panel. A locally-declared component of the same name shadows the injected
+scope and is left alone.

content/docs/automation/flows.mdx

@@ -31,10 +31,10 @@ const approvalFlow = {
       type: 'decision',
       label: 'Check Amount',
       config: {
-        // decision expressions use {braces} around variables — see Expressions in flows
+        // decision expressions are bare CEL, like every other condition — no braces
         conditions: [
-          { label: 'High Value', expression: '{order_amount} > 10000' },
-          { label: 'Standard', expression: '{order_amount} <= 10000' },
+          { label: 'High Value', expression: 'order_amount > 10000' },
+          { label: 'Standard', expression: 'order_amount <= 10000' },
         ],
       },
     },
@@ -169,8 +169,8 @@ or missing-`required` violation (#4277). A node type that publishes no
   label: 'Check Status',
   config: {
     conditions: [
-      { label: 'Approved', expression: "{status} == 'approved'" },
-      { label: 'Rejected', expression: "{status} == 'rejected'" },
+      { label: 'Approved', expression: "status == 'approved'" },
+      { label: 'Rejected', expression: "status == 'rejected'" },
     ],
   },
 }
@@ -972,30 +972,40 @@ failures so one broken flow does not abort startup.
 
 ## Expressions in flows
 
-A flow mixes **three expression dialects**, and using the wrong one is the
-single most common way a flow silently misbehaves. Which dialect applies is
-decided by *where* the expression sits — not by what it looks like:
+A flow mixes **two expression dialects**, and the rule is short: **every
+condition is CEL; braces are for values.**
 
 | Where | Dialect | Write it like | Bindings |
 |:---|:---|:---|:---|
 | Start-node `condition` | **CEL** (bare, no braces) | `record.amount > 500` | `record.*`, `previous.*`, bare field names, `vars.*` |
 | Edge `condition` | **CEL** (bare, no braces) | `record.status == 'open'` | same as above |
-| Decision-node `conditions[].expression` | **Template compare** (braces required) | `{order_amount} > 10000` | flow variables by name, in `{…}` |
+| Decision-node `conditions[].expression` | **CEL** (bare, no braces) | `order_amount > 10000` | same as above |
 | Field values in `create_record` / `update_record` | **Interpolation** (braces required) | `'Follow up on {record.name}'`, `'{TODAY() + 7}'` | `{var}`, `{var.path}`, `{$User.Id}`, `{$User.Email}`, `{NOW()}`, `{TODAY()}`, `{TODAY() + 90}` (whole days) |
 
 <Callout type="warn">
-**The two failure modes to memorize:**
+**The failure modes to memorize:**
 
-1. **Braces missing in a decision expression** — `'order_amount > 10000'` isn't
-   evaluated as a variable at all. It compares the *string* `"order_amount"`
-   against `"10000"`, which is **always true**, so the flow always takes the
-   first branch and never tells you. Write `'{order_amount} > 10000'`.
-2. **Braces missing in a field value** — `due_date: 'TODAY() + 7'` writes the
+1. **Braces missing in a field value** — `due_date: 'TODAY() + 7'` writes the
    literal text `TODAY() + 7` into the field. Write `'{TODAY() + 7}'`.
+2. **Braces put *into* a condition** — `'{record.amount} > 500'`. Conditions
+   fail loudly rather than silently, with an error that tells you to drop the
+   braces.
+</Callout>
 
-The mirror mistake is putting braces *into* a CEL condition
-(`'{record.amount} > 500'`) — CEL conditions fail loudly rather than silently,
-with an error that tells you to drop the braces.
+<Callout type="info">
+**Decision-node expressions used to be compared as text** (#4414, #4336), so
+`'order_amount > 10000'` compared the string `"order_amount"` against `"10000"`
+and was **always true**, while `'{lead_record.status} == "converted"'` was
+**always false** — the brace form substitutes a whole flow variable by name, and
+a field access on an object variable is not one. Both reported `success`. They
+are bare CEL now, so the spellings in the table above are the correct ones and
+`lead_record.status == 'converted'` resolves the field.
+
+The `{var}` form still works where it always did — `{amount} > 100`,
+`{status} == 'active'` — but the two ways it used to answer `false` without
+saying so are now **loud errors** naming the reference: a `{…}` hole that
+matches no flow variable, and a substituted value that is neither a boolean, a
+number, nor part of a comparison (#4336).
 </Callout>
 
 CEL conditions that fail to evaluate raise an error and stop the run — they