Merge remote-tracking branch 'origin/main' into wt-19658-merge2

Author: claude

.changeset/15184-list-view-field-order-composition.md

@@ -0,0 +1,19 @@
+---
+'@objectstack/spec': patch
+---
+
+`ListViewSchema` declares the `columns` x `hiddenFields` x `fieldOrder` composition instead of leaving it to be inferred from a renderer (#15184)
+
+The three keys that together build a list view's field list now say how they compose, in their own `.describe()` text — the string that ships into `json-schema/` and into the generated `content/docs/references/ui/view.mdx`:
+
+- `columns` is the **projection**: the candidate set and the baseline order, and neither other key can add a field it omits. An **empty** `columns` declares no projection, so neither other key applies: which columns show is left to the renderer (objectui's `ListView` grid derives the object's default columns).
+- `hiddenFields` **subtracts** from that projection, before any ordering runs. A name `columns` never projected subtracts nothing.
+- `fieldOrder` **orders what survives** and never adds a field. A surviving column absent from `fieldOrder` sorts **last**, after every listed one, keeping its `columns`-relative order; a name listed there that did not survive orders nothing.
+
+**Why this is a declaration and not a precedence rule.** `fieldOrder` was proposed for retirement as a second spelling of `columns` with no contract deciding who wins. They never compete: one selects, the other sorts. Maintainer decision batch #115 (2026-09-11) kept the key and ruled the composition into the contract, which is what this change lands.
+
+⛔ **No accept set moves.** No key is added, removed, narrowed or widened; no parse verdict changes; the four `@objectstack/lint` list-view validators are untouched. What changes is the published description of three keys that were already there, plus one ledger row's evidence.
+
+**`packages/spec/liveness/view.json` — the `/props/list/children/fieldOrder` row is re-cited**, `verifiedAt: 2026-09-21`. The ledger ships in this package's `files[]`, so the pointers an upgrading reader follows are these, and both halves of the 2026-08-10 citation had rotted: its first path (`objectui packages/react/src/spec-bridge/bridges/list-view.ts`) no longer exists, and its second had drifted in range through three sets of line numbers. The row now anchors both pointers on symbols, splits the relay rung out into `producer`, and names the measurement it was taken at.
+
+The declaration and the accept set are held together by `packages/spec/src/ui/view-field-order-composition.pin.test.ts`: it reads the three descriptions off the live schema and parses a document carrying all three keys through the page-list, object-views, `defineView` and registered-metadata doors, asserting the arrays come back verbatim — the spec declares the composition, it does not perform it.

.changeset/17212-find-failure-log-level-warn.md

@@ -0,0 +1,25 @@
+---
+"@objectstack/objectql": patch
+---
+
+fix(objectql): a failed `find` reports at `warn`, not `error` — the caller was already told (#17212)
+
+`find` ends its `catch` with `throw e`, and one frame down `reportFindFailure`
+logged every failure it did not classify as a missing table at ERROR. AGENTS.md
+→ *Degradation log levels* names that exact shape and forbids it: "a failure
+handed to the CALLER is not a degradation at all … Do not bolt a `logger.error`
+onto such a site." It is the read-door twin of the write doors' move to `warn`
+(#17052).
+
+**Nothing else about the entry moved.** Same message (`Find operation failed`),
+same `object` meta, and the message and stack still travel with it: the `Logger`
+contract gives an `Error` slot to `error`/`fatal` only, so the engine builds the
+`{ error: { message, stack } }` meta that slot used to build — handing the Error
+to `warn` as meta would have serialised `{}`, because those two fields are
+non-enumerable. The throw is unchanged, and so is the missing-table branch,
+which stays at `debug` without a stack. On the SQL read path the fault is also
+reported one frame down on the driver's own `warn` line, as before.
+
+If you grep your logs for this message, keep the message and drop the level
+from the pattern. If you alert on error-level lines from `@objectstack/objectql`,
+a failed read no longer raises one — the read's exception still does.

.changeset/19580-retire-connector-connection-timeout-ms.md

@@ -0,0 +1,133 @@
+---
+'@objectstack/spec': minor
+'@objectstack/connector-rest': patch
+'@objectstack/connector-openapi': patch
+'@objectstack/connector-mcp': patch
+'@objectstack/connector-slack': patch
+'@objectstack/service-automation': patch
+---
+
+feat(spec)!: retire `connector.connectionTimeoutMs` — declared, bounded, defaulted, served back, and never applied as a deadline
+
+**BREAKING** — `connector.connectionTimeoutMs` is removed. ADR-0049
+enforce-or-remove; maintainer ruling 2026-09-22, letter A. It is the narrower
+**second** decision this key was owed: the earlier ruling that made its nine
+liveness siblings live (`retryConfig.*`, `requestTimeoutMs`) left this one dead
+on a stated reason rather than by oversight, and `packages/spec/liveness/connector.json`
+has been asking for this decision since.
+
+The key was bounded (`min(1000).max(300000)`), defaulted (`30000`),
+`.describe()`d, authorable on both carriers and served back by
+`/meta/connector`. Every signal an authoring surface can give said it worked.
+
+### FROM → TO
+
+| removed | what to write instead |
+| --- | --- |
+| `connector.connectionTimeoutMs` (on `Connector` and on `DeclarativeConnectorEntry`, so `stack.connectors[]` and `PUT /meta/connector/:name`) | `requestTimeoutMs` — the deadline the platform keeps, applied as `resilientFetch`'s per-attempt timeout. For a connect-only bound, configure it at a connector provider or upstream gateway on a transport that can separate the phases. |
+| `ConnectorProviderContext.connectionTimeoutMs` (handed to every `ConnectorProviderFactory`) | `ctx.requestTimeoutMs`, or the factory's own `providerConfig` where the provider owns the vocabulary. |
+| The `ZodObject` combinators on `ConnectorSchema` and `DeclarativeConnectorEntrySchema` — `.extend()`, `.omit()`, `.pick()`, `.partial()`, `.merge()`, `.strict()`, `.keyof()`, `.safeExtend()` | Both exports are now `z.preprocess` **pipes** (the residue stage below), so those methods no longer exist on them. **Build on the object and re-wrap:** `acceptRetiredDefaultResidue(<your extended object>, { connectionTimeoutMs: 30000 })`, the `EffectiveObjectPermissionSchema` route. ⚠️ `.superRefine()` still *exists* on a pipe but returns a schema with no read-through `shape`, so refine before wrapping, not after. Parsing, `z.input` / `z.infer`, and the read-through `.shape` are unchanged. |
+
+**The one-line fix: delete the key** — and, for a custom provider factory, stop
+reading `ctx.connectionTimeoutMs`. `os migrate meta --from 17` lists the
+mechanical edits for existing sources; apply them by hand.
+
+⚠️ Runtime behaviour is **unchanged for every shipped provider**, because none
+ever applied the value: a connector that authored `connectionTimeoutMs: 1000`
+made exactly the same calls, with exactly the same deadlines, as one that did
+not. What does change is observable and intended: the def served by
+`GET /connectors` no longer echoes a connect deadline nobody keeps.
+
+### ⭐ This is NOT the zero-mention retirement shape
+
+Measured with `git grep -n connectionTimeoutMs SHA -- . ':!packages/spec'` at
+`origin/main`: **thirteen** non-test source occurrences over seven files in five
+packages — **six reads** (`openapi-connector.ts:242`, `openapi-provider.ts:193`,
+`rest-connector.ts:134`, `rest-provider.ts:64`, `plugin.ts:307`,
+`plugin.ts:1589`), **four type declarations**, and **three** surviving hardcoded
+`30000` writes. Reading the retirement as "nothing referenced it" loses the
+finding. Measured across all six reads, every one is a **pass-through**: the
+value's only termini were the def `GET /connectors` echoes and the fingerprint
+that decides whether to re-materialize. `connectorFetchOptions()` — the one
+mapping from authored policy onto the platform's outbound `fetch` — was handed
+`{ retryConfig, requestTimeoutMs }` only. Carrying a number is not honouring it,
+and ADR-0049 forbids the parsed-unmarked-unenforced state whether the inert
+value travels or sits still.
+
+Nor was the `实现` arm available. A connector's outbound call is a WHATWG
+`fetch`, whose only cancellation surface is ONE `AbortSignal` covering the whole
+operation; nothing in that interface observes the connection phase. Bounding
+"time until the response arrives" with this key would kill a slow-but-connected
+upstream the author meant to allow with a large `requestTimeoutMs` — breaking
+the very promise the key makes. (undici's `connectTimeout` needs a custom
+dispatcher: Node-only, and a new subsystem underneath every connector, which the
+ruling that made the siblings live forbids.)
+
+### The retirement kit
+
+- The **authorable key** is a `retiredKey()` tombstone on `ConnectorSchema`,
+  registered as `integration/Connector:connectionTimeoutMs` and
+  `integration/DeclarativeConnectorEntry:connectionTimeoutMs` in
+  `RETIRED_KEYS_BY_MAJOR[18]`. The schema is not `.strict()`, so a bare deletion
+  would strip an authored key in silence (ADR-0104): the tombstone is audible in
+  both channels — `tsc` (input type `never`) and the parse, which raises the
+  prescription itself. `DeclarativeConnectorEntrySchema` carries it too — both
+  published carriers wrap the same private `ConnectorBaseSchema` — so
+  `stack.connectors[]` and the `/meta/connector` door refuse it too.
+- **A D2 conversion, `connector-connection-timeout-ms-removed`** — one strip per
+  `connectors[]` entry, a pure lossless delete. ⭐ The ruling left whether one was
+  owed to be **measured** ("a D2 conversion only if a stored connector row can
+  carry the key"). It can, and both legs were measured before the tombstone
+  landed: `getMetadataTypeSchema('connector')` — what `PUT /meta/connector/:name`
+  validates against — parsed a body carrying the key and its output **retained**
+  the authored value, so the number reached `sys_metadata`; and
+  `applyConversionsToStoredItem('connector', …)` is live for this type. Rows
+  written on 17.x therefore replay clean.
+- **A D3 semantic entry,
+  `connector-provider-context-connection-timeout-ms-retired`**, for the withdrawn
+  `ConnectorProviderContext` member. A provider factory is code: there is no
+  authored source and no `sys_metadata` row for a conversion to rewrite, so the
+  removal reaches a factory author as a `tsc` error and as that entry.
+- **No def leaves.** The key was a bare `z.number()`, never a `ConfigSchema`
+  shape, so `RETIRED_DEFS_BY_MAJOR[18]` gains nothing — and `api-surface/` and
+  `json-schema.manifest/` are byte-identical, which is the correct reading for a
+  key-only tombstone rather than a missed regeneration.
+- `authorable-surface/integration.json` gains two `[RETIRED]` rows;
+  `authorable-defaults/integration.json` loses the two `= 30000` rows.
+- The liveness row **stays** `dead` with a `REMOVED` note, because `retiredKey()`
+  keeps the key in the walked shape. Its previous note claimed "every occurrence
+  outside `packages/spec` is a WRITE". That reading was **correct at the SHA the
+  card cited and dated** (`0870fb5418` — exactly five non-spec source hits, all
+  five `connectionTimeoutMs: 30000,`) and was superseded by `b929e0a662`, the PR
+  the card itself flagged as pending. It is **stale, not false**, and the row now
+  carries both readings with their trees rather than one undated claim.
+- **An `acceptRetiredDefaultResidue` stage** (#12840), `{ connectionTimeoutMs: 30000 }`
+  on both carriers. The key was `.optional().default(30000)`, so a 17.x parse
+  materialized it into **every** connector — measured across two builds: the base
+  build emits it for an entry that authored only `name`/`label`/`type`, and the
+  tombstoned build refuses that exact object at `connectors.0.connectionTimeoutMs`.
+  The D2 does **not** discharge the obligation, and the precedent shows it:
+  `ObjectPermission:allowPurge` carries a D2 **and** the residue stage, for its
+  own reason (a released toolchain materialized its default into every built
+  artifact's entries). The reason *here* is a different one — this schema has a
+  second door: `AutomationEngine.registerConnector` parses `ConnectorSchema` for
+  a def a plugin or provider factory builds **in code**, where no conversion
+  ever runs, and all four shipped connector packages put the materialized value
+  straight into that def literal. So the emitted `30000`
+  is accepted-and-stripped while `15000` keeps the tombstone's refusal, and
+  nothing is un-retired: `z.input` stays `never` and the `[RETIRED]` row stays.
+- **No deprecation window** (maintainer 2026-08-27: 「项目在创业阶段，用户也很少，短期不考虑渐进」),
+  and no staged retirement.
+
+⚠️ **The out-of-repo consumer population is NOT MEASURED.** `@objectstack/spec`
+is published, so this is breaking for consumers no download, dependent or source
+telemetry was consulted for. The pinned sibling checkout **was** measured: zero
+occurrences of the name at objectui `87af769e`, against a lit control on the same
+command and scope, so no sibling fix or pin bump rides with this.
+
+`Clause-②: yes (narrowing)` — a published authorable key is removed on two
+carriers and a published interface member leaves `ConnectorProviderContext`, so
+the accept set a consumer writes against narrows. Nothing is widened and nothing
+is renamed. Contract-review tier.
+
+<!-- adr-0087: registered connector-connection-timeout-ms-removed, connector-provider-context-connection-timeout-ms-retired -->

.changeset/19592-item-key-discriminator-stale-quote.md

@@ -0,0 +1,32 @@
+---
+'@objectstack/metadata-core': patch
+---
+
+docs(metadata-core): the `item-key-discriminators` module docblock quoted a spec sentence that no longer exists and that the contract denies ("best match") (#19592)
+
+Clause-②: no — no accept set moves, no published payload key changes, no
+export is added or removed. The corrected prose ships as TSDoc in
+`@objectstack/metadata-core`'s `dist/index.d.ts` and `dist/index.d.cts` (the
+package publishes `dist`), which is why this is a changeset rather than
+`skip-changeset`.
+
+The module docblock of `packages/metadata-core/src/item-key-discriminators.ts`
+put a sentence inside quotation marks and attributed it to
+`EmailTemplateDefinitionSchema` in `packages/spec/src/system/email-template.zod.ts`:
+that the service "picks the best match for the recipient's locale". That
+sentence occurs nowhere in `packages/spec/src` today, and it states the opposite
+of the contract: `SendTemplateInput.template` in
+`packages/spec/src/contracts/email-service.ts` says there is no "best match" and
+no language-subtag folding.
+
+The docblock now cites the spec by file and symbol instead of quoting it. It
+says the `locale` key is the second half of the bundle key, that resolution is
+exact, and that `SendTemplateInput.locale` holds the ladder: the named tag matched
+exactly, then the literal `en-US`, then, only for a call that named no locale and
+only when the bundle has no `en-US` row, the bundle's lowest locale tag. The one
+quotation left in the docblock ("is resolved by `(name, locale)`", from the
+schema's header) still exists verbatim in the spec.
+
+No behaviour changes: the edit is prose. `ITEM_KEY_DISCRIMINATORS`,
+`readDiscriminatorValue`, `itemDiscriminator` and the `en-US` canonical are
+untouched.

.changeset/19724-typescript-serializer-readme-shape.md

@@ -0,0 +1,10 @@
+---
+"@objectstack/metadata": patch
+---
+
+`README.md` — the `TypeScriptSerializer` line now says what the serializer emits and what it is for, instead of claiming it exists "for `ObjectSchema.create()`, `defineView()`, etc." (#19724).
+
+The serializer has never written a factory call. It writes a JSON document wrapped in a module — `export const metadata = { …JSON… };` then `export default metadata;`, with the `typescript` format adding an `import type { ServiceObject }` and annotating the constant with it — and it reads back only a JSON body (double-quoted keys and strings, no comments, no trailing commas), so an authored `ObjectSchema.create({ … })` file with ordinary unquoted keys is refused with `Failed to parse object literal as JSON`. It is the file format `FilesystemLoader` uses for the `typescript` / `javascript` formats: `MetadataManager.save('object', 'account', data)` routed to the filesystem loader writes `{rootDir}/object/account.ts`, never a `*.object.ts`.
+
+- **No behaviour moves.** The emitter, the parser and every published export are byte-identical; only the README text shipped in this package's `files[]` changes.
+- ⚠️ **Not an authoring shape.** Authored metadata — a `*.object.ts` written `ObjectSchema.create({ … })`, a view written `defineView({ … })` — is not produced by, and in its usual TypeScript spelling not readable by, this serializer; do not point it at authored source files.

.changeset/19823-turso-remote-deferred-ddl-refusal.md

@@ -0,0 +1,20 @@
+---
+'@objectstack/driver-turso': minor
+---
+
+fix(driver-turso): a REMOTE `TursoDriver` refuses to arm deferred schema DDL instead of accepting it and running the DDL anyway (#19823)
+
+Clause-②: no (narrowing)
+
+**BREAKING for callers that arm DDL deferral on a remote Turso datasource** — `TursoDriver.setDeferredDdl(true)` in `remote` transport mode (a `libsql://`, `https://`, `http://`, `wss://` or `ws://` URL with no `syncUrl`) now throws a `NOT_IMPLEMENTED` / `501` error, where it used to be accepted and then ignored. The five `os migrate` commands that arm it — `plan`, `apply`, `duplicates`, `account-issuer` and `multi-value-columns` — therefore exit non-zero against a remote Turso database, where they used to exit 0 after changing it. Disarming (`setDeferredDdl(false)`) is accepted, and the `local` and `replica` modes defer exactly as before.
+
+What the refusal replaces, measured on the transport's SQLite-backed test double: arming was accepted, but none of the remote schema doors reads the flag. The engine's boot sync (`syncSchemasBatch`) ran `CREATE TABLE` and `ALTER TABLE … ADD COLUMN` through `RemoteTransport`; the `syncSchema` / `initObjects` doors ran the same DDL plus the canonical temporal backfill, rewriting stored `datetime` / `time` values in place; and `previewDeferredSchemaWork()` and `flushDeferredSchemaDdl()` both answered `[]`. So `os migrate plan` changed the database and then reported no pending work, and `os migrate apply` asked for confirmation after the schema work had already run.
+
+- **Refused at the setter.** Every deferring caller passes through `setDeferredDdl`, and it runs before any schema work: a refused arm sends nothing to the database and leaves the driver un-armed.
+- **The driver's message is what the operator reads.** The CLI prints it verbatim. It names the `remote` transport mode, says why the promise cannot be kept, and says what to do instead.
+- **No new error code.** `NOT_IMPLEMENTED` / `501` is a standard code, the envelope this transport already uses for its remote transaction and auto-number refusals.
+- **Ordinary boots are unchanged.** A boot that does not arm the deferral (`os serve`, `os start`, `os dev`) syncs a remote schema exactly as before.
+
+**If you are refused:** to preview schema work, run the command against a local SQLite copy of the database (a `file:` URL); the local and embedded-replica faces defer DDL. To perform the additive schema work, let an ordinary boot against the remote datasource (`os serve` / `os start`) run it directly.
+
+<!-- adr-0087: not-required (no-migration-prescription) Nothing authorable is removed, renamed or reshaped: no spec key, no export, no stored row and no config key — `setDeferredDdl` keeps its name and its signature. There is no old spelling that maps to a new one: the refused call asked the remote transport for a capability it never delivered, and the refusal itself carries the remedy. -->