Merge remote-tracking branch 'origin/main' into claude/app-metadata-validation-midr20

# Conflicts:
#	scripts/i18n-coverage-baseline.json

Author: claude

.changeset/aggregate-temporal-output.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/driver-sql": patch
+"@objectstack/service-analytics": patch
+---
+
+fix(driver-sql,analytics): stop `aggregate()` / `distinct()` leaking SQLite's raw epoch storage (#3797)
+
+Both returned `await builder` directly, without the `formatOutput` pass every
+`find()` row gets. On SQLite — the one dialect where a `Field.datetime` is
+stored as INTEGER epoch milliseconds rather than a native timestamp — that raw
+storage form went straight to the caller:
+
+| call | before | after |
+| --- | --- | --- |
+| `find()` | `"2026-01-10T09:00:00.000Z"` | unchanged |
+| `distinct('closed_at')` | `[1768035600000]` | `["2026-01-10T09:00:00.000Z"]` |
+| `aggregate()` `max(closed_at)` | `1768035600000` | `"2026-01-10T09:00:00.000Z"` |
+| `aggregate()` `groupBy: ['closed_at']` | key `1768035600000` | key `"2026-01-10T09:00:00.000Z"` |
+
+Same root cause as #3773, different exit. `Field.date` was never affected — it
+is ISO TEXT on every dialect, so its storage form already equals its
+presentation.
+
+The visible surfaces were a `_max`/`_min` measure over a datetime (a "last
+closed" KPI tile rendered `1768035600000`) and a `groupBy` on a raw datetime
+dimension, which also disagreed with the in-memory `applyInMemoryAggregation`
+fallback — that one consumes already-formatted `find()` rows, so the same
+dataset changed key type depending on which path served it.
+
+Which columns hold an instant is now recorded while the statement is built,
+because that is the only point where a column name and its meaning are both
+known: a `min()` lands under its alias and never under the field name, while a
+date-BUCKETED column lands under the field name but holds a label (`'2026-01'`)
+rather than an instant. Matching on names afterwards gets both backwards.
+
+`distinct()` additionally re-deduplicates after presenting: SQL `DISTINCT`
+compares STORED values, and one SQLite datetime column holds both INTEGER and
+TEXT forms, so two rows recording the same instant survived as two and then
+presented identically. It has no in-repo callers today; this keeps it honest
+rather than leaving a second convention in the driver.
+
+**`cross-object-rebucket` was fixed alongside it, because presenting min/max
+correctly is what exposed it.** `recombine()` coerced every operand with
+`Number()`, which silently depended on receiving an epoch: handed the ISO string
+the driver now returns it produced `NaN`, and on Postgres/MySQL (where knex
+returns a `Date`) it had always flattened the value back to an epoch integer one
+layer above the driver. `min`/`max` now order by the instant and return the
+winning value in the shape it arrived in; `sum`/`count` stay numeric.

.changeset/attachment-read-visibility-real-filter-semantics.md

@@ -0,0 +1,30 @@
+---
+---
+
+test(service-storage): give the attachment read-visibility harness real Filter Protocol semantics
+
+Test-only — releases nothing.
+
+`attachment-read-visibility.test.ts` faked its engine with a matcher that
+understood implicit equality and `$in` and nothing else: no `$and`, no `$or`,
+no `$not`. Every assertion in the file could therefore only check the *shape*
+of the filter `computeParentVisibilityFilter` emits, never the rows that filter
+selects — a poor bargain for a predicate whose whole job is narrowing.
+
+Changes:
+
+- The harness matcher now implements the protocol for real, mirroring
+  `driver-memory/memory-matcher.ts` and `formula/matches-filter.ts`: every key
+  in a filter object ANDs, `$or` ORs its branches, and a branch's own contents
+  still AND. Operators it does not implement now **throw** instead of being
+  ignored — a silently under-implemented test double is the failure mode this
+  change exists to close.
+- A new case asserts the **rows** a multi-parent-type scope returns, not just
+  its shape: rows whose discriminator matches a branch but whose id is absent
+  from that branch's id list (including one that borrows the sibling branch's
+  id) are excluded, so the per-branch pairing itself is pinned.
+- A conformance block pins the harness matcher against the same 2x2 fixture and
+  expectations as `memory-matcher-or-semantics.test.ts`,
+  `matches-filter-or-semantics.test.ts` and `sql-driver-or-filter.test.ts`, so
+  the four cannot drift apart, plus a case proving the matcher actually
+  distinguishes a correctly paired scope from a widened one.

.changeset/cli-json-pipe-truncation-sweep.md

@@ -0,0 +1,55 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): finish the `--json` truncation fix — every command, and the second document it was hiding (#3780 follow-up)
+
+#3780 routed three commands through `emitJson`. The other ~100 emission sites
+still wrote machine output with `console.log`, which on a **pipe** is cut off
+at one 64 KiB buffer when the command exits right after: Node buffers pipe
+writes asynchronously and the exit tears the process down mid-drain. It is
+invisible to whoever writes it — stdout to a TTY is synchronous, so every
+interactive run looks perfect while every scripted consumer, the only audience
+`--json` has, gets invalid JSON.
+
+The exit does not have to be an explicit `process.exit`. oclif ends failing
+commands with `handle()` → `Exit.exit()` → `process.exit()` and flushes
+nothing on that path (`flush()` runs only on `execute()`'s success path), so a
+plain `this.exit(1)` — or any thrown error — truncates identically. 73 of the
+104 sites had exactly that shape. Even `lint` was only half fixed: `--eval
+--json` writes a whole corpus report and was still on `console.log`.
+
+All 104 sites now go through `emitJson`, `formatOutput`'s `json`/`yaml`
+branches through the same drain-aware write (`--format yaml` truncated too),
+and an ESLint rule keeps the pattern from growing back one command at a time.
+Control flow is untouched — a following `this.exit(1)` stays, it is simply
+safe once the buffer has drained. Output bytes are unchanged: roughly half the
+sites emitted compact and half indented, and each keeps whichever it had.
+
+**Draining the write exposed a second defect underneath it.** Because
+`this.exit(1)` *throws*, a command whose body sits in one `try` unwinds its
+inner "report and stop" into the outer `catch`, which reports again — so
+`os validate --json` on a failing config printed **two** JSON documents, which
+is neither valid JSON nor valid JSONL. Truncation had been hiding the second
+one. Nine commands had this shape; their catch clauses now re-throw the exit
+signal (`isExitSignal`) instead of describing it as a failure.
+
+Measured on `os validate --json` against a config with 900 schema errors,
+piped:
+
+| | bytes | parses |
+|---|---:|---|
+| before | 131072 (exactly two buffers, cut mid-string) | no |
+| truncation fix alone | 1514711 (two documents) | no |
+| both fixes | 1514648 (one document, 900 errors) | **yes** |
+
+Pinned end to end: a real command, a real pipe, a payload past several
+buffers — plus a control case asserting the `console.log` pattern it replaced
+genuinely truncates, so the gate cannot quietly stop testing anything.
+
+Not covered: the ~30 human-facing `console.log` paths, which are unaffected,
+and `os serve` / `os dev` logging. This is deliberately not fixed by forcing
+stdout into blocking mode process-wide, which would be one line and cover
+everything — the same binary runs the dev server, and a blocking write to a
+pipe with a slow reader blocks the event loop, trading truncated JSON for a
+server that stalls on its own logs.

.changeset/platform-objects-app-i18n-phantom-debt.md

@@ -0,0 +1,62 @@
+---
+"@objectstack/platform-objects": patch
+---
+
+fix(i18n): platform-objects' 231 untranslated strings were 1 — close the real gap and stop the phantom (#3762)
+
+Closes the rest of #3762. The remaining item was recorded as "platform-objects
+is 77 strings short per locale, in `apps.*` / `dashboards.*`, and its
+`--objects-only` extract cannot scaffold them — needs an emit decision (drop
+`--objects-only`, or a companion `.apps.generated.ts`) before any translating."
+
+Measured, the premise did not hold. Of the 77 declared keys per locale, **76
+were already translated** in the hand-authored `<locale>.ts` files and had been
+for months. Exactly one was genuinely missing —
+`apps.studio.navigation.nav_app_builder.label`, absent in all four locales
+including `en`. The 231 was a measurement artifact: this config declares
+SETUP_APP / STUDIO_APP / ACCOUNT_APP and SystemOverviewDashboard, but its
+`translations` merge baseline listed only the two GENERATED subtrees
+(`objects`, `metadataForms`), so coverage counted every hand-authored
+app/dashboard key as untranslated.
+
+**Neither proposed emit is right, and the second would have caused damage.**
+The Setup app is a shell of empty group anchors; its ~25 menu entries are
+contributed at runtime by `SETUP_NAV_CONTRIBUTIONS` and by capability plugins
+(ADR-0029 D7). A bundle generated from a static walk of `SETUP_APP` is
+therefore structurally incomplete, and regenerating over the hand-authored
+files would have **deleted 40 live nav translations per locale**. Dropping
+`--objects-only` fails differently: `kind: 'full'` folds all 803 metadata-form
+keys into `<locale>.objects.generated.ts` and renames the export the baseline
+imports.
+
+The split is correct as it stands and is now written down: `objects` /
+`metadataForms` are generated and gated by the bundle-drift check; `apps` /
+`dashboards` / `pages` are hand-authored and gated by the coverage ratchet.
+What was wrong was only that the baseline omitted the hand-authored half.
+
+- Extract config's `translations` now carries the per-locale assemblers, with
+  `objects`/`metadataForms` still pinned to the committed generated files.
+  Safe for the emit — `--objects-only` writes `data.objects` alone, so nothing
+  added here can reach a generated bundle, and `check:i18n` stays in sync
+  across all nine packages.
+- `nav_app_builder` translated in all four locales, wording taken from the
+  repo's own precedent for "builder" (`构建器` / `ビルダー` / `generador`).
+- `nav_workflows` removed from all four: its menu entry is gone from
+  `STUDIO_APP` and nothing contributes to that app, so the translation was
+  dead.
+- Coverage ratchet baselined 231 → **0**, making platform-objects the ninth
+  package where the ratchet is a strict gate — verified to go red on a single
+  removed translation.
+- A local, CLI-independent parity test walks the statically declared Studio and
+  Account navigation plus the dashboard's widgets and asserts a translation in
+  every locale — and the reverse, that no translation survives its nav item.
+  Both directions verified to fail before passing.
+
+An untranslated nav id is invisible in the UI — it falls back to the app's
+English label, so a Chinese Studio menu just shows one English entry among
+thirty. That is why this needed a gate rather than a one-time sweep.
+
+Still out of scope: the ~25 Setup entries contributed at runtime. Bringing them
+under a static gate needs either an objectql dependency in this package (it
+depends only on spec and metadata-core) or extractor support for
+`navigationContributions` — a real follow-up, not something to half-do here.

.changeset/sql-driver-dialect-connect-timeout.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/driver-sql": minor
+---
+
+fix(driver-sql): give the bounded connection attempt an accurate error message (#3769)
+
+#3781 bounded a connection attempt at 10s via `pool.createTimeoutMillis`, which
+stopped the 30s hang but kept knex's own wording: `Timeout acquiring a
+connection. The pool is probably full`. The pool is not full — the server never
+completed the handshake — so that message sends an operator to tune `pool.max`
+while the network is what is broken. This is the same defect class the boot
+guard in #3741 was about: an error that reads nothing like its cause.
+
+`SqlDriver` now also sets the **dialect's own** connect timeout, which fails with
+a message that names what happened:
+
+| client | key | message |
+|---|---|---|
+| `pg` / `postgres` / `postgresql` / `cockroachdb` | `connectionTimeoutMillis` | `timeout expired` |
+| `mysql` / `mysql2` | `connectTimeout` | `connect ETIMEDOUT` |
+
+Carrying the timeout requires `connection` to be an object, so a URL string is
+moved into the dialect's URL slot (`connectionString` for pg, `uri` for mysql2).
+Verified against a black-holing listener that both forms still reach the URL's
+own host/port and still honour `?sslmode=require`. SQLite is untouched — opening
+a file has no handshake to time out.
+
+**The two bounds are deliberately unequal.** They race and knex wins a tie, so
+equal values would let the pool timeout fire first and the accurate message would
+never be seen. The dialect timeout is the effective bound at **10s**; the pool
+timeout is a strictly looser backstop, raised from 10s to **15s**, reached only
+by a dialect with no connect-timeout knob or one that ignores the one we set.
+
+`driver.config` keeps the shape the author passed — the rewrite applies only to
+what knex receives. Two existing readers depend on that: `serve.ts`'s startup
+banner and `createDatabase()`, which parses the URL to swap in the maintenance
+database. A test pins it.
+
+`createDatabase()`'s own admin connection now gets the same bound; it is opened
+during boot against the very server we already suspect is unreachable, so it must
+not be the one place that still waits 30s.
+
+**Migration.** None for a healthy datasource. A deployment that deliberately
+needs longer than 10s to establish a connection (a slow cross-region replica)
+sets `connection.connectionTimeoutMillis` (pg) or `connection.connectTimeout`
+(mysql2) explicitly, and it is left alone.

.changeset/validate-runs-build-authoring-lints.md

@@ -0,0 +1,45 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `os validate` runs the four authoring lints `os build` runs — "validate clean, build fails" is gone (#3782)
+
+`os validate` is documented, and used in CI, as the **read-only superset** of the
+gates `os build` runs: same checks, no artifact. It wasn't. Four authoring lints
+were wired into `compile.ts` only, and **two of them already fail the build**:
+
+| Lint | Emits `error` | `os build` | `os validate` (before) |
+|---|---|---|---|
+| `lintAutonumberFormats` | yes | ✓ | — |
+| `lintViewRefs` (#2554) | yes | ✓ | — |
+| `lintFlowPatterns` (#1874) | not yet | ✓ | — |
+| `lintLivenessProperties` | no | ✓ | — |
+
+So an autonumber format naming a field that doesn't exist, or a form action
+target naming a LIST view, passed `os validate` cleanly and then failed
+`os build`. Reproduced verbatim on `main` against `examples/app-todo`:
+`os validate` → "✓ Validation passed"; `os build` → "✗ Autonumber format
+validation failed". Worst for the CI setups that gate on `validate` and only
+discover the break at deploy time.
+
+The drift was invisible for a structural reason worth naming: every *other* gate
+on both commands is a shared `@objectstack/lint` import, while these four are
+CLI-local `../utils/lint-*` modules that only `compile.ts` ever imported. Nothing
+made adding a gate to the build also add it to validate.
+
+**The fix is two parts.** `validate.ts` now runs all four, mirroring
+`compile.ts`'s per-lint severity handling (`error` → exit 1, everything else →
+advisory, and into the `warnings` array under `--json`). And a new source-level
+test asserts that every `lintFoo(`/`validateFoo(` call site in `compile.ts` also
+appears in `validate.ts`, failing with the list of missing gates. That test is
+the actual fix for the class of bug — the wiring is just today's instance.
+
+**What you may newly see.** `os validate` now surfaces every rule these lints
+carry, including the advisory ones, so existing projects can see new warnings.
+Only `autonumber-*` and view-reference `error` findings change the exit code —
+and any project they now fail was already failing `os build`.
+
+`FlowLintFinding` also gains an optional `severity`, honoured by both surfaces.
+No rule sets it today, so flow findings stay advisory; it is the seam that lets
+#3760's blocking `flow-runas-unscoped` gate `os validate` and `os build`
+together the moment it lands, with no further wiring.

content/docs/data-modeling/drivers.mdx

@@ -127,7 +127,9 @@ even earlier — that is where `MongoDBDriver` puts its
 pnpm add @objectstack/driver-sql pg
 ```
 
-`SqlDriver`'s constructor accepts a [Knex `Knex.Config`](https://knexjs.org/guide/#configuration-options) object verbatim.
+`SqlDriver`'s constructor accepts a [Knex `Knex.Config`](https://knexjs.org/guide/#configuration-options)
+object, passing it through unchanged except for two connect-timeout defaults
+described [below](#connect-timeouts).
 
 ```typescript
 import { SqlDriver } from '@objectstack/driver-sql';
@@ -152,6 +154,29 @@ Or via env var alone (driver inferred from `postgres://` scheme):
 export OS_DATABASE_URL=postgres://admin:secret@db.example.com:5432/myapp
 ```
 
+### Connect timeouts
+
+A database endpoint that accepts the TCP connection but never completes the
+handshake — an overloaded instance, a half-open firewall, a load balancer
+mid-failover — makes every query *wait* rather than fail. Left to Knex's own
+defaults that wait is 30 seconds per query on the request path, and with a small
+`pool.max` a handful of them saturate the pool. So `SqlDriver` supplies two
+defaults ([#3769](https://github.com/objectstack-ai/objectstack/issues/3769)):
+
+| Setting | Default | Purpose |
+| :--- | :--- | :--- |
+| `connection.connectionTimeoutMillis` (pg) / `connection.connectTimeout` (mysql2) | `10_000` | The effective bound. Fails with the driver's own wording — `timeout expired` / `connect ETIMEDOUT` — which names the network. |
+| `pool.createTimeoutMillis` | `15_000` | Backstop, only reached by a client that has no connect-timeout option or ignores it. Deliberately looser: the two race, and Knex wins a tie, so an equal value would mask the accurate message with Knex's misleading "the pool is probably full". |
+
+Set either explicitly and it is left untouched — do that when a datasource
+legitimately takes longer to connect (a distant cross-region replica). SQLite
+gets neither: opening a file has no handshake to time out.
+
+Carrying a connect timeout requires `connection` to be an object, so a URL string
+is moved into the client's URL slot (`connectionString` for pg, `uri` for
+mysql2) before reaching Knex. This affects only what Knex receives — the config
+you passed is preserved as-is on the driver.
+
 ## MongoDB
 
 Configuration properties for the MongoDB driver.

content/docs/deployment/validating-metadata.mdx

@@ -223,11 +223,17 @@ another package defines.
 | Chart bindings outside dashboards (#3583) | ✓ | ✓ |
 | Navigation vs. granted access (ADR-0090 D6) | ✓ | ✓ |
 | Security posture (ADR-0090 — e.g. every custom object declares `sharingModel`) | ✓ | ✓ |
+| Autonumber `{field}` interpolation | ✓ | ✓ |
+| View references — form targets, view-key collisions (#2554) | ✓ | ✓ |
+| Flow authoring anti-patterns (#1874) | ✓ | ✓ |
+| Liveness author-warnings | ✓ | ✓ |
 | Emits `dist/objectstack.json` | — | ✓ |
 
 So `os validate` is the fast inner-loop check (no artifact); `os build` is what
 you run when you need the deployable artifact. A config that passes `os validate`
-will not fail `os build` on schema/predicate/binding grounds. Both entry points
+will not fail `os build` on schema/predicate/binding grounds — a test in the CLI
+asserts that every gate `os build` runs is also run by `os validate`, so the two
+cannot drift apart again (#3782). Both entry points
 also check SDUI styling (ADR-0065), and `os validate` additionally runs a set of
 view- and page-shape checks — list-view navigation modes (ADR-0053), view
 container shape, and JSX/React page sources (ADR-0080/0081) — that catch UI
@@ -254,6 +260,7 @@ A clean run walks each gate and reports timing:
   → Checking source-page styling (ADR-0065)...
   → Checking capability references (ADR-0066)...
   → Checking flow trigger wiring...
+  → Running authoring lints (#3782)...
   → Checking security posture (ADR-0090 D7)...
 
   ✓ Validation passed (64ms)