Merge remote-tracking branch 'origin/main' into claude/issue-14451-duplicate-non-base-refusal

Author: claude

.changeset/summary-backfill-recompute-undefined-on-empty.md

@@ -0,0 +1,57 @@
+---
+"@objectstack/objectql": minor
+"@objectstack/cli": minor
+---
+
+feat(objectql,cli): `backfillSummaryNulls` accepts `recomputeUndefinedOnEmpty` — a caller who KNOWS a `min`/`max`/`avg` roll-up column was just declared can have it filled; `os migrate summary-nulls --recompute-undefined-on-empty object.field` surfaces it (#15064)
+
+A roll-up value has three producers — the insert-time seed, the child-write
+recompute, and the one-off backfill — and **declaring a summary field on an
+object that already has rows reaches none of them**. For `count`/`sum` the
+backfill repairs that as a side effect (every `NULL` is a hole to it). For
+`min`/`max`/`avg` it could not: `summaryNullIsBackfillable` decides on the
+function alone, so "never computed" and "no child rows" were indistinguishable,
+the column stayed `NULL` on every pre-existing parent, and the report said
+`filled: 0` — a false all-clear that a timed flow built on the column then
+turned into "matches nothing" (the customer case behind cloud#1908).
+
+**What changes** — maintainer ruling on #15064, option A: the caller who holds
+the fact gets a way to say it; the predicate and the default run do not move.
+
+- `SummaryBackfillOptions.recomputeUndefinedOnEmpty?: string[]` — `object.field`
+  roll-ups the caller knows were never computed. A named `min`/`max`/`avg` is
+  walked like a `count`: every `NULL` parent is recomputed through the same
+  `aggregateSummaryValue` the engine writes. A parent whose aggregate is the
+  empty-set reading (`null` — no child rows) already holds the engine's own
+  value, so it is neither counted as a hole nor written; the scoped run is
+  therefore idempotent in the same "re-run until it reports zero" sense.
+  Naming a `count`/`sum` is accepted and changes nothing, so a publish path can
+  pass every column it just declared without knowing the empty-set list.
+- A name that resolves to no roll-up owned by an object the run walks — a typo,
+  a plain field, or an object `objects` left out — is **refused before any row
+  is read**, dry run or apply, with an ADR-0112 envelope (`code:
+  'INVALID_FIELD'`, `status: 400` — the code the projection and write axes
+  that name a field already answer, while sorting keeps `INVALID_SORT`;
+  `field` names the first unresolved entry, `fields` all of them). A silent
+  no-op there would be the same false all-clear this option exists to end.
+- `SummaryBackfillReport.recomputedUndefinedOnEmpty: string[]` — the complement
+  of `skippedUndefinedOnEmpty`, same `object.field (fn)` spelling; `[]` on an
+  unscoped run. `SummaryBackfillFieldOutcome.fn` widens from `'count' | 'sum'`
+  to every roll-up function, since a named `max` now appears in `fields`.
+- `os migrate summary-nulls --recompute-undefined-on-empty object.field`
+  (repeatable) passes the scope through; the confirmation prompt names the
+  columns; `formatSummaryBackfillReport` lists them under "Recomputed on
+  request" and explains a `NULL` that remains.
+
+**What does not change:** without the option the walk, the writes, every
+counter and the human-readable report are byte-for-byte what they were (pinned
+against output captured on `main` before this change); `min`/`max`/`avg` stay
+out of scope and keep being reported under `skippedUndefinedOnEmpty`; the
+predicate `summaryNullIsBackfillable` is untouched, so `os migrate
+summary-nulls` keeps its meaning on every deployment. The only visible delta on
+an unscoped run is the one additive report key, `recomputedUndefinedOnEmpty: []`.
+
+`minor` for both packages: an optional parameter on a published exported
+function, a new report key, and a new CLI flag are each a purely additive
+widening of a published surface, which takes at least `minor` (bump-level rule,
+2026-09-04); the `fix`-shaped motivation does not lower it.

.changeset/today-offset-one-calendar.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/service-automation": patch
+---
+
+Flow templates: `{TODAY() + n}` and `{TODAY() - n}` now do their day arithmetic on the same calendar they render on (UTC), so the resolved date no longer lands a day off across a DST transition.
+
+The offset branch of the template resolver shifted the day on the **local** calendar (`getDate` / `setDate`) and then rendered the result on the **UTC** one (`toISOString`). `setDate` preserves wall-clock time, so a local day shift moves the underlying instant by exactly n x 24 hours only while every local day in the window is 24 hours long. Across a spring-forward the window is 23 hours and across a fall-back 25, and when that one hour of slack crosses a UTC midnight the rendered date comes out a day early (spring-forward) or a day late (fall-back).
+
+The window is narrow — roughly one hour per DST-observing zone, twice a year — but the values written through it persist: a quote expiration, a follow-up date, a close date. Measured across 34 zones at every 30 minutes of 2026 for offsets `+1` and `-1` (1,191,360 instant-offset pairs), the old spelling disagreed with the UTC day in 190 of them, spread over 24 DST-observing zones; the new spelling disagrees in none.
+
+The same branch serves `{NOW() + n}`, which likewise now moves the instant by exactly n x 24 hours instead of preserving a wall-clock time across the transition.
+
+Nothing else moves. The bare `{TODAY()}` and `{NOW()}` forms never entered this branch and are byte-for-byte unchanged — they already resolved on UTC, and the offset forms now agree with them. This is not a timezone feature: these tokens remain timezone-unaware by design, and whether they should be is a separate question.

.gitignore

@@ -1,5 +1,7 @@
 # Dependencies
 node_modules/
+# also without the slash: in a linked worktree node_modules can be a symlink, which is not a directory to git and so escapes the line above; the repo tracks node_modules in no shape (#15763)
+node_modules
 package-lock.json
 
 # Build output

content/docs/api/error-catalog.mdx

@@ -75,7 +75,13 @@ reads those as field filters, so one naming no field could only match zero
 records and is rejected rather than answered with an empty page — plus every
 other read axis that names a field: `select`, `expand` (a real field that holds
 no reference gets its own message), `searchFields` (a real field outside the
-searchable set gets its own message), `groupBy`, and `aggregations[].field`.  
+searchable set gets its own message), `groupBy`, and `aggregations[].field`.
+Off the request path the same code answers `backfillSummaryNulls`'s
+`recomputeUndefinedOnEmpty` (`os migrate summary-nulls
+--recompute-undefined-on-empty object.field`) when an entry is not a roll-up
+owned by an object the run walks — a typo, a real non-summary field, or a
+roll-up on an object `--object` left out are refused alike, one message naming
+every unresolved entry and how many objects the run walked.  
 **Fix:** Check the object schema for valid field names. Use `os meta get object <name>` to inspect the object's fields. If the name was meant as a
 *parameter* rather than a field, use the real one — page size is `top` / `$top`
 / `limit`, not `pageSize` / `perPage`; the response's `error` names the

content/docs/deployment/cli.mdx

@@ -912,6 +912,8 @@ os migrate summary-nulls                    # Dry run: full report, writes nothi
 os migrate summary-nulls --apply            # Recompute and write (prompts)
 os migrate summary-nulls --apply --yes --json   # CI / scripts
 os migrate summary-nulls --object project       # Restrict to one object (repeatable)
+os migrate summary-nulls --apply --recompute-undefined-on-empty customer.last_follow_up_at
+                                                # Also fill a min/max/avg column you know was never computed
 ```
 
 **Each affected row is recomputed, not set to 0.** A pre-upgrade parent that
@@ -920,9 +922,25 @@ them — writing 0 there would replace a missing value with a wrong one, and the
 next child write would change it back. The report separates the two: `N NULL
 row(s), M with real child data`.
 
-`min` / `max` / `avg` are **never touched**. They are undefined on an empty set,
-so a `null` there is the correct reading of "no child rows"; the report lists
-them as deliberately skipped.
+`min` / `max` / `avg` are **never touched by default**. They are undefined on an
+empty set, so a `null` there is the correct reading of "no child rows"; the
+report lists them as deliberately skipped.
+
+The one case that reading gets wrong is a summary field **declared after its
+parent rows already existed**: nothing has ever computed it — the insert-time
+seed is create-time, the recompute runs only on a child write — so every
+pre-existing parent reads `NULL` whether or not it has children, and a flow
+built on the column matches nothing. The migration cannot tell that `NULL`
+from a legitimate one; the operator (or the publish path) who just declared
+the column can. Name it with `--recompute-undefined-on-empty object.field`
+(repeatable) and it is walked like a `count`: every `NULL` parent is recomputed
+through the same aggregate the engine writes, a parent with no child rows keeps
+`NULL` (that is the aggregate's own value, and it is neither counted nor
+written), and the report lists the column under "recomputed on request". A
+name that is not a roll-up this run walks — a typo, a plain field, or an object
+`--object` left out — is refused before any row is read. Naming a `count` /
+`sum` is accepted and changes nothing, so a caller can pass every column it
+just declared.
 
 Idempotent — every write turns a `NULL` into a number, so a second run finds
 nothing and writes nothing. Re-running until the report says zero *is* the

docs/adr/0087-metadata-protocol-upgrade-contract.md

@@ -585,6 +585,7 @@ gate's log and its `--list` output.
 <!-- adr-0087: not-required (no-migration-prescription) <why> -->
 <!-- adr-0087: not-required (runtime-interface-only <path>#<Symbol>[, ...]) <why> -->
 <!-- adr-0087: not-required (type-surface-only <path>#<Symbol>[, ...]) <why> -->
+<!-- adr-0087: not-required (type-surface-only <path>#<a>.<b>.<member>[, ...]) <why> -->
 ```
 
 **The vocabulary is closed, and every exemption is re-verified on every run** — an
@@ -676,6 +677,7 @@ The vocabulary above gained a sixth answer:
 
 ```text
 <!-- adr-0087: not-required (type-surface-only <path>#<Symbol>[, ...]) <why> -->
+<!-- adr-0087: not-required (type-surface-only <path>#<a>.<b>.<member>[, ...]) <why> -->
 ```
 
 ### The dead end it closes
@@ -748,6 +750,23 @@ checks all four by name (`published`, `no-spec-diff`, `no-metadata-surface-diff`
    *both* revs and requires `any` / `unknown` / no annotation at base, and a
    concrete type at HEAD.
 
+   ⭐ **The reference is a bare symbol OR a dotted member path.** `<path>#<Symbol>`
+   resolves a bare name to the **first same-named definition in the file**, and on a
+   real SDK module that is not a symbol identity: `packages/client/src/index.ts`
+   declares `get` 14 times and `delete` 10 times, so the members PR #15445 and PR
+   #15451 actually narrowed had **no addressable spelling at all** — the category
+   was closed to them by the grammar rather than by any judgement about the claim,
+   and the gate answered a true sentence about a member the diff never touched
+   (#15627). A reference may therefore also be written `<path>#<a>.<b>.<member>`:
+   the object-literal nesting the member sits in, walked **structurally** from the
+   top of the file over a comment- and literal-masked projection, with the member's
+   definition taken from inside the resolved body. Bare references keep their exact
+   previous meaning. ⛔ A line number is never the disambiguator — this file's line
+   numbers were measured to rot within one day. A dotted path that resolves to
+   **zero** candidates, or to **more than one**, is reported by name and refused,
+   never guessed at: a reference that silently landed on the wrong same-named member
+   would be writable but wrong, which is worse than the refusal it replaces.
+
 ### ⭐ Predicate 4 is what makes this a narrowing rather than a hole
 
 This is the **only** category exempt from the `no-migration-prescription` refusal.