Merge remote-tracking branch 'origin/main' into claude/issue-15546-all-null-sum-zero

Author: claude

.changeset/aggregate-field-type-compatibility.md

@@ -0,0 +1,25 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): declare the aggregate × field-type compatibility matrix a dataset measure is judged against — `AGGREGATE_FIELD_TYPE_COMPATIBILITY` and `isAggregateCompatibleWithFieldType` (#16353, spec half of #16099)
+
+A dataset measure pairs an `aggregate` with a `field`, and nothing between author and driver correlated the two: `avg` over a `Field.datetime` compiled to `AVG(col)` and reached the backend, where one SQL family averages the column's storage form and another rejects the call — one metadata document, two answers. Which pairs are accepted is a contract, so it is now declared once in `@objectstack/spec/data`:
+
+| Aggregate | Accepted field types |
+|---|---|
+| `count`, `count_distinct` | every `FieldType` |
+| `sum` | `number`, `currency`, `rating`, `slider`, `progress`, `summary` — the numeric class EXCEPT `percent` (a rate does not add; `isIncoherentAggregate` already says so) |
+| `avg` | the numeric class, `percent` included |
+| `min`, `max` | the numeric class plus `date`, `datetime`, `time` — both return a value of the field's own type |
+| every other pair | refused |
+
+The ruling (director, decision batch #59, 2026-09-06) named its buckets by category; the table resolves them against the real `FieldType` membership through the `field-value.zod` semantic classes: "numeric" is `NUMERIC_VALUE_TYPES` (`integer` is a driver-internal column alias, not a `FieldType` — the integer-valued authorable members are `rating` / `slider` / `progress`); "temporal" is the three temporal classes, `time` included because its stored form is a dialect question exactly like `date` / `datetime` (native TIME on Postgres and MySQL, canonical `HH:MM:SS[.fff]` TEXT on SQLite), the canonical form orders chronologically on every dialect, and `AnalyticsResult.fields[].type` already describes `min` / `max` over it as temporal (#15768). `formula` is refused for arithmetic aggregates whatever its declared `returnType`: it is virtual in SQL storage, no column exists to aggregate.
+
+Two refused rows override existing opinions and are recorded as such, not presented as agreement. **Booleans** are refused for `sum` / `avg` / `min` / `max` by the ruling's "every other pair: refused", while maintainer ruling #11152 already has every backend answer them as numbers (`sum(flag)=3`, `avg(flag)=0.5`, `min(flag)=0`, `max(flag)=1`, pinned in the spec's `AGGREGATION_CASES`; `driver-sql` casts the aggregand on Postgres to make it hold). That refusal is therefore not grounded in backend divergence; whether booleans belong in those rows is a collision between two rulings and is referred to the maintainer as its own decision — the row ships exactly as batch #59 stated it. **The string classes** are refused for `min` / `max` here, while `service-analytics` (#15768) already types `min` / `max` over them as a supported `'string'` result; the refusal is defensible (string order is collation-dependent) but it overrides that opinion.
+
+**The narrowing, stated plainly.** Every pair outside the table — `avg` × `datetime`, `sum` × `boolean`, `min` × `text`, `sum` × `percent`, and so on — is an authoring shape `DatasetMeasureSchema` accepts today and will be REFUSED once the two consumer legs land: the compile-time refusal in the dataset compiler (#16099) and the authoring-time lint rule (its devx sub-card). A measure whose pair is refused is fixed by changing the aggregate to one the field's type supports (`min` / `max` for a temporal field; `avg` for a `percent`; `count` for anything), never by widening the table.
+
+**Not breaking in this release, `minor` on purpose.** This changeset ships a table and a predicate that nothing yet enforces: `DatasetMeasureSchema` accepts byte-for-byte what it accepted before, no export is removed or narrowed, and no runtime path reads the table yet. It is an additive widening of the published surface — two new exports in `dist/*.d.ts` — which the maintainer ruling of 2026-09-04 (decision batch #35) puts at `minor`. The refusal itself arrives with the consumer legs, whose changesets carry the breaking declaration, its migration prescription and the ADR-0087 disposition; this one names the narrowing so an upgrading author can read the contract before it is executed.
+
+`isIncoherentAggregate` is unchanged and stays the semantic opinion beside this table. The two diverge on exactly one pair: `count_distinct` × `percent` is flagged there and accepted here (the ruling reads `count_distinct` as "any type"). That divergence is pinned in the table's test and reported on #16353 rather than resolved silently.

.changeset/duration-unit-in-key-name.md

@@ -2,7 +2,7 @@
 "@objectstack/spec": minor
 ---
 
-feat(spec)!: a duration-shaped `z.number()` key carries its unit in the key name — `hook.timeout` / `job.timeout` / `DriverOptions.timeout` → `timeoutMs`, `MetadataManagerConfig.cache.ttl` → `ttlSeconds`, `cache.databaseLoader.ttl` → `ttlMs`, tenant `idleTimeout` / `sessionTimeout` → `*Seconds`; new gate `check:duration-unit-keys` (#14478, #14519)
+feat(spec)!: a duration-shaped `z.number()` key carries its unit in the key name — `hook.timeout` / `job.timeout` / `DriverOptions.timeout` → `timeoutMs`, `MetadataManagerConfig.cache.databaseLoader.ttl` → `ttlMs` (the outer `cache.ttl` leaves outright under #15624 — nothing read it), tenant `idleTimeout` / `sessionTimeout` → `*Seconds`; new gate `check:duration-unit-keys` (#14478, #14519)
 
 <!-- adr-0087: registered hook-timeout-to-timeout-ms, job-timeout-to-timeout-ms, metadata-manager-config-cache-ttl-unit-in-key, driver-options-timeout-to-timeout-ms, tenant-timeouts-unit-in-key -->
 
@@ -38,7 +38,7 @@ comment and published a bare `300` / `3600` to the reference page (#14519).
 | `HookSchema` (`hooks[]`) | `timeout` | `timeoutMs` | unchanged (ms) |
 | `JobSchema` (`jobs[]`) | `timeout` | `timeoutMs` | unchanged (ms) |
 | `DriverOptionsSchema` | `timeout` | `timeoutMs` | unchanged (ms) |
-| `MetadataManagerConfigSchema` | `cache.ttl` | `cache.ttlSeconds` | unchanged (s, default 3600) |
+| `MetadataManagerConfigSchema` | `cache.ttl` | *(deleted — its respelling `ttlSeconds` was retired before it shipped, #15624; the outer `cache` block was read by nothing, and the live TTL is `cache.databaseLoader.ttlMs`)* | — |
 | `MetadataManagerConfigSchema` | `cache.databaseLoader.ttl` | `cache.databaseLoader.ttlMs` | unchanged (ms, default 60000) |
 | `DatabaseLevelIsolationStrategySchema` | `connectionPool.idleTimeout` | `connectionPool.idleTimeoutSeconds` | unchanged (s, default 300) |
 | `TenantSecurityPolicySchema` | `accessControl.sessionTimeout` | `accessControl.sessionTimeoutSeconds` | unchanged (s, default 3600) |
@@ -52,10 +52,13 @@ new MetadataManager({ cache: { ttl: 3600, databaseLoader: { ttl: 60_000 } } });
 // after — rename the key; the number is unchanged
 defineHook({ name: 'audit_order', object: 'order', events: ['afterInsert'], handler: 'auditOrder', timeoutMs: 5000 });
 defineJob({ name: 'nightly_sweep', schedule: { type: 'cron', expression: '0 1 * * *' }, handler: 'sweep', timeoutMs: 300000 });
-new MetadataManager({ cache: { ttlSeconds: 3600, databaseLoader: { ttlMs: 60_000 } } });
+new MetadataManager({ cache: { databaseLoader: { ttlMs: 60_000 } } }); // the outer `ttl` is deleted, not renamed (#15624)
 ```
 
-**Migration.** Rename each key; no value changes. Authoring an old spelling
+**Migration.** Rename each key; no value changes — with one exception: the outer
+`MetadataManagerConfig.cache.ttl` is DELETED, not renamed (its respelling `ttlSeconds`
+was retired before it shipped, #15624; nothing ever read the outer `cache` block, and
+the nested `cache.databaseLoader.ttl → ttlMs` rename above is unchanged). Authoring an old spelling
 fails to compile (`tsc`: the input type is `never`) and fails to parse with a
 prescription naming the new key. For `hooks[]` / `jobs[]` the rename is a
 mechanical D2 conversion (`hook-timeout-to-timeout-ms`,

.changeset/execution-step-metrics-failure-slot.md

@@ -0,0 +1,71 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec): `ExecutionStepMetrics` gains an optional `failures` slot, and `FlowRunSummary.failed` is declared as the fold INCLUDING what a delegating node rolled up from its child (maintainer ruling 2026-09-06 on #15617, spec half)
+
+Additive. Nothing an author writes is renamed, retired or narrowed; no accept
+set shrinks. One optional key is declared on a runtime-produced schema and the
+prose of a published contract is reconciled with itself.
+
+**What was wrong.** `FlowRunSummary` said two things about `failed`. Its
+header paragraph declared that a `subflow` node rolls its child run's totals
+up into the parent — "this summary answers *what did this run cause*" — while
+the field itself declared `failed = Σ nodes[].failures`, a fold over the
+parent's own node executions. For a parent that delegates its rows to a
+`subflow` (or a `map` item) those give different answers, and the engine could
+only satisfy the second one: `ExecutionStepMetrics` carried `selected` /
+`acted` / `unmeasuredEffect` and no failure slot, so a child's contained
+failures had no path into the parent's fold. Measured on the real engine by
+the services seat (#15617): parent `loop { subflow(child) }` → parent
+`failed=0` while the five child summaries carried `failed=[0,0,0,0,1]` —
+`acted` rolled up, `failed` did not.
+
+**What this declares.**
+
+- `ExecutionStepMetrics.failures` (optional, integer ≥ 0): node executions
+  that failed inside a child run this execution delegated to and went on from
+  — a `subflow` child or a `map` item whose run COMPLETED while containing
+  failures, i.e. the child's `summary.failed`, rolled up. It folds into the
+  delegating node's `nodes[].failures` and so into the run-level `failed` —
+  the same fold shape `acted` has, but not the same rule at the failed-child
+  boundary (next bullet). Absent means the step delegated nothing, or its
+  child tracked no count, or the producer did not track it (every step the
+  engine emits between this release and the engine half) — never zero.
+- It is NOT the step's own outcome. A step that failed is `status: 'failure'`
+  and counts once through `nodes[].failures`, as before; a child that FAILED
+  — whether or not it also contained failures before it failed — is
+  precisely that step failure: its own `failed`, contained and fatal alike,
+  stays on the child's run row and nothing rides up, so one failure is never
+  counted twice. This is where the rule parts from `acted`, which does carry
+  a failed child's writes up to the parent. The control the card measured (a
+  failing child → parent `failed=1`) keeps counting exactly as today.
+- `FlowRunSummary.failed` is declared, at the field, as the fold of
+  `nodes[].failures` INCLUDING what a delegating node rolled up; the
+  `FlowRunNodeSummary.failures` describe names the roll-up path, and its
+  `status` describe states that a delegating node whose child contained
+  failures reads `success` beside `failures > 0` — status is judged on the
+  node's own executions.
+
+**What this does not do yet.** This is the contract half of a two-lane
+landing (contract first). No producer populates `failures` in this release:
+`subflow-node.ts` and the `map` node roll the child's contained failures into
+the slot in the services half, #16314, and only then does a parent's
+`failed` start counting them. Until that lands, every `ExecutionStepMetrics`
+the engine emits is byte-identical to today's, `failed` is numerically what it
+was, and the flow-run reference page keeps the narrowed wording PR #15609
+shipped ("node executions **of this run**") on purpose — it is widened when
+both halves are in.
+
+**Consumers.** A reader of `ExecutionStepMetrics` sees one more optional
+number and nothing else changes shape; a consumer that already sums
+`nodes[].failures` to cross-check `failed` keeps agreeing with it, because the
+fold is unchanged — the roll-up enters the per-node array, not beside it. Two
+consequences of that placement are part of the contract from this release,
+even though no producer populates the slot yet: on a delegating node
+`nodes[].failures` may exceed `runs` (`runs: 5, failures: 15` is a legal
+shape — five subflow executions whose children each contained three), and it
+is no longer only that node's own failed executions, so a reader that derived
+"this node's executions that failed" or a failure RATE from `failures / runs`
+must read a delegating node's number as "failures this node caused, its
+child's contained ones included".

.changeset/metadata-manager-inert-cache-keys-retired.md

@@ -0,0 +1,85 @@
+---
+"@objectstack/spec": minor
+"@objectstack/metadata": patch
+---
+
+feat(spec)!: retire the three inert outer keys of `MetadataManagerConfig.cache` — `enabled`, `ttlSeconds` (formerly `ttl`) and `maxSize` — read by nothing; `cache.databaseLoader` is the only live half (#15624, ADR-0049)
+
+<!-- adr-0087: registered metadata-manager-config-inert-cache-keys-retired -->
+
+**BREAKING** accept-set narrowing, landing after the v17.0.0 cut (the lockstep
+launch-window convention ships it as `minor`; the migration prescription is
+registered under protocol major 18, where `os migrate meta` users will look).
+ADR-0049 enforce-or-remove decides it: a declared-but-unenforced key with zero
+measured readers comes off, and the published reference page stops teaching it.
+
+`MetadataManagerConfig.cache` declared three outer knobs — `enabled` (default
+`true`), `ttlSeconds` (default 3600; spelled `ttl` until #14478) and `maxSize`
+("Max cache size in bytes") — beside the nested `databaseLoader` block, and
+**nothing read the outer three**. The only runtime consumer of the block is
+`MetadataManager` (`packages/metadata`), which hands `cache.databaseLoader` and
+nothing else to `new DatabaseLoader({ cache })`; a reader census over
+`packages/**` (tests and changelogs excluded) found no runtime reader of any
+outer key, while the same grep shape found the nested `cache?.databaseLoader`
+read twice — the control that makes the zero a measurement. An author writing
+`cache: { enabled: false }` or `cache: { ttlSeconds: 60 }` got a clean parse
+and a cache that behaved exactly as before, with no error and no warning, and
+the published reference page (`references/kernel/metadata-loader`) documented
+all three as if they configured something.
+
+**What is refused:** authoring `cache.enabled`, `cache.ttlSeconds`, `cache.ttl`
+or `cache.maxSize` on `MetadataManagerConfig`, with any value — directly, through
+`MetadataManagerOptions`, or through `MetadataPluginConfig.storage`. The nested
+object is not `.strict()`, so each key is a `retiredKey()` tombstone rather than
+a bare deletion (a deletion would have stripped it in silence — the same no-op
+one layer down): authoring it is a `tsc` error (`never`) and a parse error
+carrying the prescription, which names the live nested knob.
+
+**What stays, byte-identical:** the DatabaseLoader read-through cache under
+`cache.databaseLoader` — `enabled` (default `true`), `maxSize` (an entry count,
+default 500) and `ttlMs` (milliseconds, default 60000) — and every runtime
+path. Parsed configs no longer carry the two former defaults (`enabled: true`,
+`ttlSeconds: 3600`) that were materialized and never consulted.
+
+**The #14478 rename is folded in.** `cache.ttl` → `cache.ttlSeconds` was
+registered under this same unreleased major and never reached a published
+release, so it is absorbed by the removal: `cache.ttl`'s tombstone now
+prescribes deletion (naming `cache.databaseLoader.ttlMs`) instead of a rename to
+a key that is itself retired — an author upgrading from a published 17.x sees
+one hop. The nested `cache.databaseLoader.ttl` → `ttlMs` half of that rename is
+unchanged.
+
+## FROM → TO
+
+```ts
+// before — parsed green; no runtime ever read the three outer numbers
+new MetadataManager({
+  datasource: 'default',
+  cache: { enabled: true, ttlSeconds: 3600, maxSize: 10_485_760, databaseLoader: { ttlMs: 60_000 } },
+});
+
+// after — delete the outer keys; the nested block is the cache that runs
+new MetadataManager({
+  datasource: 'default',
+  cache: { databaseLoader: { enabled: true, maxSize: 500, ttlMs: 60_000 } },
+});
+```
+
+**Migration.** Delete `cache.enabled`, `cache.ttlSeconds` / `cache.ttl` and
+`cache.maxSize`; nothing replaces them, because nothing ever consumed them. If
+you meant to switch the cache off, cap it or set its TTL, write
+`cache.databaseLoader.enabled` / `.maxSize` (entries) / `.ttlMs` (milliseconds)
+— those are honoured. No `os migrate meta` conversion runs on this surface: a
+`MetadataManager` config is not a stack collection member and never a stored
+row, so the chain has no seam for it; the D3 semantic entry
+`metadata-manager-config-inert-cache-keys-retired` carries the prescription
+into `spec-changes.json`, the upgrade guide and the `spec_changes` MCP tool.
+
+The retirement kit: `retiredKey()` tombstones on all three (and the absorbed
+`ttl`), `RETIRED_KEYS_BY_MAJOR[18]` entries for each, the D3 semantic entry
+above (the #14478 entry's outer half is re-worded from a rename to a deletion),
+negative pins asserting each prescription and a positive pin asserting the
+parse output no longer materializes the retired defaults, the published
+reference pages regenerated, and the hand-written docs page and this package's
+README (`@objectstack/metadata` ships `README.md`, hence its `patch`) no longer
+authoring `cache.enabled`.