Merge branch 'main' into claude/issue-18202-crossref-dependency-aware

Author: os-elon-musk

.changeset/14361-adr-0024-identity-citations.md

@@ -0,0 +1,59 @@
+---
+'@objectstack/plugin-auth': patch
+'@objectstack/platform-objects': patch
+'@objectstack/spec': patch
+'@objectstack/core': patch
+'@objectstack/cli': patch
+---
+
+docs(identity): re-point the cloud-identity `ADR-0024` citations at the records that decide them (#14361)
+
+From this repository's point of view `ADR-0024` names two unrelated decisions.
+`docs/adr/0024-mcp-connectors.md` is *MCP Servers as Connectors* — an open,
+vendor-neutral tool protocol, with a Decision section numbered §1–§5 and no
+D-lettered clauses at all. The identity surface's citations mean something else
+entirely: the identity-and-access decision taken in `objectstack-ai/cloud` as
+its own ADR-0024, whose open mechanism half has been mirrored into this repo
+since 2026-09-07 as
+[ADR-0135](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0135-identity-and-access-architecture.md).
+A reader following one of those citations landed on a real page about the wrong
+subject, which is worse than a dangling id: a plausible-looking record invites
+belief rather than a second question.
+
+79 citation lines were read one at a time and re-pointed. 73 mean a clause
+ADR-0135 restates and now name it with its letter — D4 (source-of-truth marking,
+managed vs env-native), D5.2 (the break-glass last-administrator invariant), D6
+(SSO per production environment, including the opt-in DNS domain-verification
+clause this tree spelled `ADR-0024 ②`) and D9 (environment users and
+organization membership). 6 mean a clause ADR-0135 deliberately leaves in the
+cloud record and now carry the anchors gate's cross-repo qualifier
+`cloud ADR-0024`: `V1` (the SSO default-role provisioning, the roadmap and
+commercial framing) and `§7` (the `ai_seat` synthesis, which ADR-0135 does not
+restate).
+
+What actually reaches a consumer of these packages:
+
+- `@objectstack/plugin-auth` — the **operator-facing break-glass refusal
+  detail** now reads `break-glass invariant, ADR-0135 D5.2 — an environment must
+  always keep at least one administrator who can sign in`. The condition that
+  raises it, its status, its error code and the rest of its wording are
+  unchanged; only the ADR number moves. ⚠️ A deployment that greps that message
+  for the literal `ADR-0024` should grep for `ADR-0135`. The guard's
+  registration log line moves the same way.
+- `@objectstack/platform-objects` — `sys_sso_provider`'s `domain_verified` field
+  help text, its `protection.reason`, and the matching leaf in all four shipped
+  locale bundles (`en`, `es-ES`, `ja-JP`, `zh-CN`).
+- `@objectstack/spec` — the doc comment above `AuthConfigSchema`'s
+  `ssoDomainVerification`, published both in `dist/` and as
+  `src/system/auth-config.zod.ts`.
+- `@objectstack/core`, `@objectstack/cli` — doc comments only, published in
+  `dist/`; no runtime string and no behaviour.
+
+No behaviour moves. No schema accepts or refuses anything it did not accept or
+refuse before, no security or permission semantics are touched, and no ADR
+record is written or edited. Bare `ADR-0024` still resolves exactly as it did:
+the 15 citations that mean the local MCP-connectors record are byte-identical to
+`main`, and `check:adr-anchors` reports the same resolving-citation totals before
+and after. Historical archives are deliberately untouched — 36 CHANGELOG lines
+across seven packages, and the 22 lines under `docs/adr/`, which is a governed
+surface this change does not enter.

.changeset/15669-try-catch-error-value-widening.md

@@ -0,0 +1,9 @@
+---
+"@objectstack/service-automation": patch
+---
+
+`try_catch`'s catch-region binding is annotated as the plain declared type. `TryCatchErrorValueSchema` declares `code: z.string().optional()`, so the local `TryCatchErrorValue & { code?: string }` intersection in `builtin/try-catch-node.ts` added nothing the exported `TryCatchErrorValue` did not already carry, and the comment paragraph beside it explained a spec/engine divergence that no longer exists (#15669).
+
+**No behaviour change, and nothing executable moves.** The object literal is untouched: `nodeId`, `message`, `code` and `iteration` / `item` are bound under exactly the same conditions as before, so a catch region still branches on `{$error.code}` and still reads an absent `code` as "no classified code", never as "nothing failed". Measured on the built package: `index.js`, `index.cjs`, `index.d.ts` and `index.d.cts` are **byte-identical** before and after; only `index.js.map` / `index.cjs.map` shift (by one byte each), because the replacement comment is two lines longer and the sourcemap encodes line positions.
+
+The annotation was proven redundant before it was removed — `TryCatchErrorValue` and `TryCatchErrorValue & { code?: string }` are mutually assignable, and `TryCatchErrorValue['code']` is exactly `string | undefined` — and the binding it describes is genuinely pinned: dropping `code` from the literal reddens the two `#14419` discriminator tests in `builtin/create-record-duplicate-code.test.ts`.

.changeset/17469-multiple-non-capable-type-refused.md

@@ -0,0 +1,111 @@
+---
+"@objectstack/spec": minor
+"@objectstack/driver-sql": minor
+---
+
+fix(spec)!: `multiple: true` is refused on every type outside the multi-capable set, and driver-sql derives JSON-column storage from the spec predicate (#17469)
+
+<!-- adr-0087: registered field-multiple-non-capable-type-refused -->
+
+**BREAKING** in the accept-set sense, landing in the launch window as `minor`
+(the lockstep convention: `major` is refused by `check-changeset-no-major`, and
+breaking-ness is carried by this banner plus the ADR-0087 disposition).
+
+Two definitions of "multi-valued" disagreed, and the user saw the disagreement as
+a `400`.
+
+- `FieldSchema` accepted `multiple: true` on **any** type.
+- `@objectstack/driver-sql`'s `isJsonField` read the flag raw —
+  `JSON_COLUMN_TYPES.has(type) || !!field.multiple` — and built a **JSON array
+  column** for it.
+- `isMultiValueField` — the published spec predicate consumers shape queries from
+  — answered **"not multi-value"** for that same field, because `master_detail` /
+  `tree` / `text` are outside `MULTI_CAPABLE_TYPES`.
+
+So a related list composed `=` against a JSON array column, and the driver refused
+the equality family there with a `400`.
+
+In business terms: `multiple` means "this cell holds several values at once", and
+that has meaning only on multi-select, multi-record / multi-user and multi-file
+fields — exactly what the spec already declares. A child record with several
+masters, a tree node with several parents, or a text box holding several texts has
+no meaning on any mainstream platform. The declaration was accepted silently, the
+UI rendered a single value, the database built a JSON array column, and the
+related list answered the user a 400.
+
+FROM → TO, for metadata that used to parse and now fails:
+
+```ts
+// FROM — parsed, stored a JSON array, rendered single, answered `=` with 400
+{ type: 'text',          label: 'Aliases',  multiple: true }
+{ type: 'master_detail', label: 'Parents',  reference: 'account', multiple: true }
+{ type: 'tree',          label: 'Parents',  reference: 'category', multiple: true }
+
+// TO — pick the type that actually holds several values…
+{ type: 'tags',   label: 'Aliases' }                                   // several free-form strings
+{ type: 'lookup', label: 'Parents', reference: 'account', multiple: true }  // several related records
+
+// …or drop the key, if the cell really holds one value.
+{ type: 'text',          label: 'Alias' }
+{ type: 'master_detail', label: 'Parent', reference: 'account' }
+```
+
+The refusal names the field, its type and the alternative, on the `multiple` path.
+`radio` keeps its own narrower 2026-08-22 message (#11437); the two never
+double-fire.
+
+**`MULTI_CAPABLE_TYPES` and `isMultiValueField` are untouched**, deliberately: a
+field that was already multi-valued by that predicate keeps its declaration, its
+storage and its read path byte-identically. What moved is which declarations can
+be newly authored, plus the storage decision for the shapes that are now refused.
+
+**Storage change (`@objectstack/driver-sql`)**: every site that asked
+`field.multiple` the question "is this value multi-valued" now asks
+`isMultiValueField` — **eighteen expressions across two files**, not one. The
+file's own header already called `JSON_COLUMN_TYPES` membership "owned by
+`@objectstack/spec`"; that sentence is now true for the `multiple` half too.
+
+- `sql-driver.ts` — the DDL writer (`createColumn`'s multi-value short-circuit),
+  the read-side deserializer (`isJsonField`, both limbs), the `varchar` width
+  mirror (`varcharColumnChars`), the cross-field comparison class
+  (`crossFieldComparisonClass`), the four scalar registries filled by BOTH
+  `registerObjectMetadata` and `registerExternalObject` (`mediaFields`,
+  `booleanFields`, `numericFields`, `numericValueFields`), and the two MySQL
+  temporal-widening candidate sets.
+- `schema-drift.ts` — the differ's `fieldHasColumn`, its `declaresJsonColumn`
+  disjunct and its `declaresArray` test, which #15771 bound to the writer's
+  predicate and which a pin test holds equal to it.
+
+Only one of those was named in the ruling; aligning it and leaving seventeen
+would have re-opened #11535 in reverse — the DDL writing a JSON column that the
+read-side deserializer no longer recognises. A column whose field is multi-valued
+by the spec predicate behaves exactly as before; the shapes that change are the
+ones the schema now refuses at the entrance.
+
+⛔ Three `field.multiple` reads are deliberately NOT aligned: the three that
+interpolate `', multiple'` into an `uncompilableFieldReferenceError` message.
+They echo what the author DECLARED back to them; they do not ask whether the
+value is multi-valued (the verdict there comes from `crossFieldComparisonClass`,
+which is aligned).
+
+⚠️ **Two consequences worth reading before you upgrade.**
+
+1. A **stored** field carrying `multiple: true` on a non-capable type has no
+   lossless conversion — its column was physically built as a JSON array. The
+   ADR-0087 semantic entry `field-multiple-non-capable-type-refused` emits the
+   structured TODO naming the object, field and type; migrating the data is the
+   author's judgment call, and the entry states how to prove it.
+2. `isMultiValueField` reads the **authorable** `FieldType` vocabulary. A driver
+   -internal column-type alias (`string` / `integer` / `int` / `float` — the
+   introspected-column spellings) is not a `FieldType`, so a hand-declared
+   external object that puts `multiple: true` on one of those no longer gets a
+   JSON column. Declare such a column as `object` or `array` (both are
+   `JSON_COLUMN_TYPES` members and unchanged), or as the authorable type it
+   really is.
+3. `multiple: true` on `boolean` / `toggle` / `number` / `currency` / `percent` /
+   `date` / `datetime` / `time` **ceases to be a supported shape end to end**, as
+   a consequence of the entrance refusal above. Such a column is no longer a JSON
+   column, so it is no longer excluded from the scalar read-coercion registries
+   and the declared-type text-operator gate (`isNonTextColumn`) applies to it: a
+   `$contains` against one answers the declared no-match rather than a JSON
+   membership test. Stored data in that shape is the ADR-0087 entry's subject.

.changeset/17598-analytics-date-range-two-bound-window.md

@@ -0,0 +1,90 @@
+---
+"@objectstack/spec": minor
+"@objectstack/core": minor
+"@objectstack/types": patch
+"@objectstack/rest": patch
+---
+
+fix(spec)!: `timeDimensions[].dateRange`'s array arm is exactly two string bounds, and each refusal ORIGIN gets a true sentence (#17598; ruling A, decision batch #117 item 3)
+
+<!-- adr-0087: registered analytics-date-range-array-two-bounds-required -->
+
+**BREAKING** accept-set narrowing at `timeDimensions[].dateRange` — shipped as
+`minor` under this repo's launch-window convention for breaking changes
+(`scripts/check-changeset-no-major.mjs`), above the `patch` floor the `fix`
+commit type sets, and the same grade the one comparable precedent took: the
+STRING-arm closing on this same schema is #16041, and it shipped
+`"@objectstack/spec": minor` (`packages/spec/CHANGELOG.md` 17.4.0, under Minor
+Changes). ⚠️ Its driver half #16322 declares `"@objectstack/spec": patch`, but
+that entry is — in that changeset's own words — "a `PROVENANCE_WAIVERS` row
+only", not an accept-set narrowing, so it is not a grade this one is measured
+against. The maintainer
+ruling calls it a "major changeset"; under the launch window that phrase maps to
+the protocol MAJOR the migration registers against (18), not to the changeset's
+bump level, which `scripts/check-changeset-no-major.mjs` reserves. The semantic
+prescription is registered under protocol major 18 as
+`analytics-date-range-array-two-bounds-required`.
+
+### What changed
+
+`AnalyticsDateRangeSchema`'s array arm was `z.array(z.string())` with **no length
+constraint**, so `['2026-01-01']`, `[]` and `['a', 'b', 'c']` were schema-valid.
+It is now `z.tuple([z.string(), z.string()])` — a tuple rather than a length
+refinement, so the arity is stated to the author's compiler before any parse runs.
+Preset names, two-bound windows and an absent `dateRange` parse byte-identically
+to before.
+
+`analyticsDateRangeRefusalMessage(input)` becomes
+`analyticsDateRangeRefusalMessage(input, origin)`, where `origin` is `'schema'` or
+`'runtime'` and is **required** — there is deliberately no default.
+
+### Migration: FROM → TO
+
+| You wrote | Write instead |
+| --- | --- |
+| `dateRange: ['2026-01-20']` | `dateRange: ['2026-01-20', '2026-01-20']` — a single day is that day as both bounds, the shape the shipped #16322 table already prescribes |
+| `dateRange: []` | no conversion. An empty array names no window: write the two bounds the widget was meant to show, or omit `dateRange` (it is optional, and absent means the query is not time-bounded) |
+| `dateRange: ['a', 'b', 'c']` | no conversion. Decide which two bounds you meant and write them |
+| `analyticsDateRangeRefusalMessage(value)` | `analyticsDateRangeRefusalMessage(value, 'schema')` at a parse door, `…(value, 'runtime')` past one |
+
+`os migrate meta --from 17` emits the first three as a structured TODO rather than
+rewriting them: rewriting a one-element array to the same day twice at load would
+be the platform deciding, silently, that the author meant one day rather than a
+window whose end they forgot, and for the other two shapes there is nothing to
+decide from.
+
+### Why it is not a new class of breakage
+
+Since PR #17593 all four analytics faces (`ObjectQLStrategy`, `NativeSQLStrategy`,
+the draft-preview evaluator, `DatasetExecutor.runCompare`) already refused anything
+that is not exactly two bounds with `400 ANALYTICS_DATE_RANGE_UNRECOGNIZED`, so
+every stored range this narrowing refuses was **already failing at query time**.
+The contract door was looser than every reader behind it; this moves the refusal
+to authoring time and states it accurately. Blast radius is the WIDGET, not the
+page: a stored dashboard carrying a now-refused range loses that widget with the
+refusal shown and still loads.
+
+### The wording half
+
+The shared sentence ended `"Refused at the schema"` and described every refused
+array as `"received an array with a non-string bound"`. For a one-element window
+refused by a face **both clauses were false** — every bound present is a string,
+and it was refused past the schema, not at it — which is why
+`@objectstack/service-analytics` had to overwrite the message rather than reuse it,
+leaving one condition with two wordings. The origin is now a parameter and the
+`received …` clause names the arity and the bad bound separately, so the sentence
+is true for each origin both before and after the arm narrows.
+
+The same rule reaches the WIRE. Narrowing the arm to a tuple gave the union a
+second voice: its arm answers `Too small: expected array to have >=2 items` for
+the very arity the prescription just prescribed, and the ADR-0114 union
+expansion emitted both as `fields[]` entries on `POST /analytics/query` and
+`POST /analytics/dataset/query`. `fieldsFromZodIssues` (`@objectstack/types`),
+the one mapper both doors report through, now drops the branch issues that land
+at the union's OWN path for this refusal — recognised structurally through
+`isAnalyticsDateRangeRefusalIssue`, never by message prose. A refusal that names
+a DEEPER position keeps it: `dateRange: ['2026-01-01', 3]` still reports
+`timeDimensions.0.dateRange.1`, because WHICH bound is not a string is a
+location the prescription does not carry. Every other union expands exactly as
+before. Client-visible effect: one `fields[]` entry for an arity refusal instead
+of two, with the prescriptive one kept.

.changeset/17818-prototype-fallthrough-lookups.md

@@ -0,0 +1,51 @@
+---
+'@objectstack/spec': minor
+---
+
+fix(spec): four lookup folds no longer hand out `Object.prototype` members for an off-vocabulary key (#17818)
+
+`normalizeFilterOperator` (`/ui`), `resolveDiscoveryEnvironment` (`/api`), and
+`pluralToSingular` / `singularToPlural` (`/meta-spelling`, re-exported from
+`/shared`) each read a module-level lookup table with a runtime key through a
+bare index. Every one of those tables is an ordinary object, so a key that is
+not in the vocabulary resolved a member of `Object.prototype` instead of
+falling through — and the `?? fallback` each function already writes never
+fired, because the inherited member is truthy.
+
+Measured on Node v22.22.2, before and after — each fold evaluated at this
+change's implementation and again at its merge base, against the TypeScript
+sources that the build and the test run both consume:
+
+| call | before | after |
+|:--|:--|:--|
+| `normalizeFilterOperator('constructor')` | the `Object` function | `'constructor'` |
+| `normalizeFilterOperator('toString')` | `Object.prototype.toString` | `'toString'` |
+| `normalizeFilterOperator('valueOf')` | `Object.prototype.valueOf` | `'valueOf'` |
+| `normalizeFilterOperator('__proto__')` | `Object.prototype` | `'__proto__'` |
+| `resolveDiscoveryEnvironment('constructor')` | the `Object` function | `'development'` |
+| `resolveDiscoveryEnvironment('__proto__')` | `Object.prototype` | `'development'` |
+| `pluralToSingular('constructor')` | the `Object` function | `'constructor'` |
+| `singularToPlural('__proto__')` | `Object.prototype` | `'__proto__'` |
+
+Each function's declared refusal value is what it now answers — the same value
+each already gave for an ordinary unknown word such as `nope`. ⛔ No new
+fallback was invented. `resolveDiscoveryEnvironment` is the sharpest case: its
+own docblock promises "a value guaranteed to satisfy
+`DiscoveryEnvironmentSchema`", and for `constructor` it returned a `Function`.
+
+⚠️ **Why `minor` and not `patch`.** The level is carried by this change's
+declared contract-review status, ⛔ not by a widening — the guard only NARROWS.
+An off-vocabulary key that previously resolved an inherited member now gets each
+function's own declared refusal value, and nothing that answered before answers
+differently. Nothing in the declared vocabulary moves: every canonical operator,
+every `EnvironmentType` bucket, both operator shorthands and every manifest
+collection spelling answers byte-identically to before, and the only inputs
+whose answer changes are the four prototype-member spellings above, which no
+signature ever admitted.
+
+The guard is the `Object.prototype.hasOwnProperty.call(table, key) && table[key]`
+shape already landed in `src/data/type-compat.ts`, and carries that site's two
+recorded rejections: ⛔ not a null-prototype table (it does not type-check
+against the `Record` annotation, and the spelling that does compile silently
+costs the exhaustiveness check), and ⛔ not a list of prototype member names
+(which the next prototype member defeats).