Merge remote-tracking branch 'origin/main' into claude/issue-6619-fold-error-maps

Author: claude

.changeset/bulk-write-before-hooks-per-row.md

@@ -0,0 +1,95 @@
+---
+"@objectstack/objectql": minor
+"@objectstack/spec": patch
+---
+
+feat(objectql): dispatch `before*` hooks per matched row on a predicate bulk write (#5574, #5846)
+
+A `multi: true` update or delete now dispatches `beforeUpdate` / `beforeDelete`
+**once per matched row**, on a single-record-shaped context carrying that row's
+`id` and `previous` — the same move #5038 made for the `after*` phase, held to
+the same yardstick. ADR-0058 Addendum II (maintainer ruling B, 2026-08-06) is
+the contract; `packages/spec/src/data/bulk-write-hook-conformance.ts` states it
+as clauses D1–D7, and its `delivered` flags flip with this change.
+
+**The harm this fixes.** `ctx.previous` was never bound in the before phase of a
+predicate write, so every guard written the way guards are written —
+`if (ctx.previous?.locked) throw` — passed **silently** on every batch. The
+failure direction is fail-OPEN and the optional chaining that makes it silent is
+exactly what an AI writes. One measured deployment had all 15 of its guard hooks
+bypassed by a single batch edit, including writing `null` into a `readonly: true`
+field that the single-id path refuses.
+
+**Two visible behaviour changes, both loud.**
+
+- **Guards now fire per row on predicate writes.** A `beforeUpdate` /
+  `beforeDelete` hook on an object targeted by a `multi: true` write runs N times
+  instead of once, each time with that row's `previous` bound. Zero matched rows
+  is zero dispatches. A hook that throws refuses the whole batch before anything
+  is written. The payload stays **batch-scoped** (D3): every per-row context
+  carries the one payload, so a rewrite applies to every matched row whichever
+  row's dispatch made it, rewrites accumulate in dispatch order, and no predicate
+  write is ever split into N single-row writes — one `updateMany`, one affected
+  count (#4639), one aggregate event. A rewrite *conditioned* on the row is
+  therefore out of contract: it widens to the whole batch rather than scoping
+  itself. Per-row `previous` is supplied so a guard can REFUSE, not so a rewrite
+  can be aimed.
+- **The `input.id` reroute lever is retired and now refuses.** The dispatch
+  ladder is resolved **before** the before phase — it has to be, since per-row
+  contexts are built from the matched row set — so the id slot can no longer
+  steer the write. Rather than ignore an assignment (a silent no-op) or honour
+  it blindly, the write is rejected with `HookTargetRebindError`
+  (`ERR_HOOK_TARGET_REBIND`), whose message names the retired capability and the
+  three supported replacements. Recorded as ADR-0058 Amendment II.1. Precisely:
+
+  | | CLEARED id | REBOUND to another id |
+  |---|---|---|
+  | `update()` by-id | refused | refused |
+  | `delete()` by-id | refused | **honoured, unchanged** (#5272's re-read) |
+  | either, per-row | refused (D4) | refused (D4) |
+
+  Clearing is uniform because it worked by falling through to the predicate
+  branch, and that branch is now chosen before any handler runs. Rebinding is
+  not uniform, deliberately: the case against honouring it is that the write
+  lands on a row whose pre-image and rules were never evaluated, and on
+  `delete()` that is simply not true — #5272 already re-resolves the new target
+  before `afterDelete` or the summary recompute sees it. `update()` has no such
+  mechanism and building one would be the "silently pick re-resolution instead"
+  the ruling forbids. Retiring the delete-side repoint is its own question,
+  filed as #6752 rather than ridden in on an ordering change.
+
+**Also in this change.**
+
+- **One read, reused (D7).** The matched row set is read ONCE per predicate
+  write, with the write's own composed AST, and serves per-row validation
+  (#3106), the `readonlyWhen` strip (#3042) and both per-row dispatches.
+- **One ceiling, both phases (D6).** `MAX_BULK_PER_ROW_HOOK_ROWS` (10 000) now
+  governs `before*` as well as `after*`, checked **before the first dispatch**, so
+  an over-ceiling batch runs zero handlers and writes nothing — a refusal, never
+  a downgrade to one dispatch. The engine's open-coded ceiling and refusal
+  message are replaced by the spec module's `resolveBulkPerRowHookBudget`, so the
+  number and the wording have one definition again.
+- **`update()` binds `previous` before the before phase (#5846 (a)).** The by-id
+  path reads its prior row ahead of the dispatch, matching `delete()`'s shape
+  since #5272, so both phases share one read. objectql's
+  `sys_fetch_previous_update` builtin is **retired**: it existed to bind
+  `previous` for the before phase behind `if (input.id && !ctx.previous)`, and
+  that guard is now permanently false. A by-id update on a kernel used to read
+  the same row three times; this removes one and makes the engine's read the
+  single producer.
+- **`HookConditionLimitation` is retired** (ADR-0049 enforce-or-remove), with
+  `isPredicateBulkWrite` and the `predicateBulkWrite` flag. Both members
+  (`bulk_write_previous_unbound`, `bulk_write_stored_state_unavailable`)
+  described a batch-scoped `before*` dispatch that no longer exists, leaving them
+  with neither producer nor reachable consumer. A `previous`-reading `before*`
+  condition on a bulk write now **evaluates as authored**, per row, instead of
+  rejecting the batch. `HookConditionError` itself is unchanged — an unevaluable
+  condition still aborts the operation (#4775).
+
+**Migrating.** A handler that cleared `ctx.input.id` — or rebound it on an
+`update()` — must instead write through `ctx.api` / `ctx.ql` for the row it
+means, have the caller pass `{ multi: true, where: … }`, or throw to refuse the
+write. A `beforeDelete` handler that repoints the target is unaffected. A `beforeUpdate` hook
+with side effects on an object that receives bulk writes should expect to run
+per row; a batch-wide effect belongs in a payload rewrite, which is still
+batch-scoped.

.changeset/cel-pushdown-limits-converge.md

@@ -0,0 +1,88 @@
+---
+"@objectstack/formula": minor
+---
+
+fix(formula): the CEL pushdown compiler parses through the canonical front end, so `DEFAULT_LIMITS` finally apply to RLS/sharing predicates (#6132)
+
+`cel-to-filter.ts` — the ONE canonical CEL → `FilterCondition` pushdown compiler
+(ADR-0058 D1/D2/D6), consumed by the RLS path (`plugin-security`'s
+`RLSCompiler`), the sharing seeder (`plugin-sharing`), and the analytics SQL
+backend — kept a **private, limitless** parse environment of its own:
+
+```ts
+new Environment({ unlistedVariablesAreDyn: true, enableOptionalTypes: true })
+```
+
+no `limits`, no stdlib, no `rewriteNullableTernary`. That made the pushdown path
+the one place on the platform that answered a *different* question from
+`celEngine.compile()` about what parses. Measured: a 300-term addition, a
+60-level parenthesis nest and a 200-element list literal all parsed there while
+the interpreter refused each one outright (`Exceeded maxAstNodes (256)` /
+`maxDepth (32)` / `maxListElements (64)`). Escalated: an 80-term conjunction, a
+40-level nest and a 200-element `$in` all reached **real pushdown SQL**,
+silently — and `isSupportedRlsExpression`, the ADR-0056 D4 authoring gate, was a
+thin wrapper over the same limitless environment, so it was no independent check
+either.
+
+It now parses through `parseCelToAstWithReason` — #4812's canonical entry, with
+`DEFAULT_LIMITS`, the stdlib and the #3306 null-guard rewrite. "What parses" has
+one answer again.
+
+**Within the limits nothing moves, and that is measured, not asserted.** Across
+the 710 sources of the pushdown corpus that both front ends accept, the only AST
+difference is `rewriteNullableTernary`'s `dyn(…)` wrap on the three null-guard
+ternaries — and a ternary faults on its own `?:` node before the lowerer
+descends into a branch, so verdict *and* detail come out byte-identical. Pinned
+in `cel-to-filter-parse-convergence.test.ts`, which rebuilds the old environment
+to compare against.
+
+**Over the limits, behaviour changes — in two dated steps.**
+
+- **Now, during `17.0.0-rc.x` (`rc-grace`):** an over-limit predicate **still
+  compiles** — nothing that enforces today stops enforcing on this upgrade — and
+  emits one WARN per predicate naming the bound that was exceeded
+  (`maxAstNodes` / `maxDepth` / `maxListElements` / …), the platform's value for
+  it, and what the predicate itself measures (cel-js's own accounting: the
+  smallest bound it parses under), plus what will happen at GA.
+- **At v17.0.0 GA (`fail-closed`):** the same predicate is **refused** —
+  `{ ok: false, reason: 'parse-error', detail: 'Exceeded maxAstNodes (256)' }` —
+  and the RLS path turns that into `RLS_DENY_FILTER`, i.e. zero rows, fail
+  closed. A sharing rule with such a condition is not seeded.
+
+**The flip is one line.** `CEL_PUSHDOWN_LIMITS_MODE` in
+`packages/formula/src/cel-pushdown-limits.ts` — the single dated switch,
+shipping as `'rc-grace'`, to be set to `'fail-closed'` at the v17.0.0 GA release
+(i.e. when this package's version leaves `17.0.0-rc.x`). Both positions are
+exercised in CI today, in `@objectstack/formula` and in
+`@objectstack/plugin-security` (where the `RLS_DENY_FILTER` outcome lives), so
+the GA half is proven before it ships rather than after. Two tests are written
+to go red on that line so the flip cannot be silent.
+
+**If you author RLS or sharing predicates:** a predicate over any of these
+bounds is already refused everywhere else on the platform (`os build`,
+`os validate`, the interpreter). Split it, or move the logic into a hook/action
+body (`ScriptBody { language: 'js' }`), before upgrading past the rc line. The
+WARN names the predicate and its measure so you can find them.
+
+**New public surface**, for consumers that must *report* a refusal rather than
+merely react to one:
+
+- `parseCelToAstWithReason(source, opts?)` — the reason-carrying sister entrance
+  to `parseCelToAst`. Same front end, same verdict, but it distinguishes
+  `'parse'` (not valid CEL) from `'bounds'` (valid CEL, over budget) and names
+  the exceeded limit, its platform value, and the source's measure. Graded by
+  the same by-class/by-code classifier `celEngine.compile` uses (#6223) — never
+  by error prose. `parseCelToAst` is unchanged and still collapses every refusal
+  to `null`.
+- `CelParseResult`, `CelBoundsOverrun`, `CelLimitKey`, `ParseCelToAstOptions`.
+- `CEL_PUSHDOWN_LIMITS_MODE`, `celPushdownLimitsMode()`,
+  `setCelPushdownLimitsModeForTests()`, `CelPushdownLimitsMode`.
+
+`@objectstack/lint` needs no change, at either position of the switch. Its two
+enforceability gates read `isSupportedRlsExpression` and `compileCelToFilter`,
+both downstream of this switch, and both suites pin "the lint verdict IS the
+consumer's verdict" in both directions — so authoring-time reporting flips with
+the runtime by construction. An over-limit sharing `condition` is in fact
+already an authoring **error** today (`expression-invalid`, from the general
+expression rule, quoting `Exceeded maxAstNodes (256)`), because that rule has
+always gone through the canonical front end.

.changeset/doctor-ledger-failure-dir.md

@@ -0,0 +1,12 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `os doctor`'s ledger-failure row names the directory it actually read (#6643)
+
+Removes divergence surface; not a live defect. `DEFAULT_INSTALLED_PACKAGES_DIR` — `@objectstack/cloud-connection`'s export, the single authority on what the installed-package ledger directory is called — exists in every version ever shipped and has never changed value, so the literal this change deletes currently agrees with it. What it buys is that the agreement stops being a coincidence nobody would notice breaking.
+
+The residue of #5996, which fixed the same restatement one row over (`installedPackageLedgerSkippedEntriesCheck`) and enumerated the rest rather than widening in place:
+
+- `installedPackageLedgerFailureCheck` takes the resolved `dir` — already carried on the reading since #5996 — and quotes it. Its `fix` used to open with a re-hardcoded ``.objectstack/installed-packages/`` "under the project root", which was the consumer restating a value only the producer decides, and a vaguer answer than the one doctor was holding: the reading's `dir` is `cwd`-joined and absolute. Under `--verbose` the row now reads ``The ledger is `/srv/app/.objectstack/installed-packages`;`` and drops the now-redundant project-root hedge. The parameter is required, so the row cannot quietly fall back to a guess.
+- `os package install`'s post-install hint keeps its literal, now with the reasons written down. That sentence describes the **remote** runtime host's directory: the CLI never touches that disk, the host's directory is configurable (`MarketplaceInstallLocalPlugin` builds `new LocalManifestSource(config.storageDir)`, so the export is only its default), and the install response carries no `storageDir` to quote. Resolving it locally would state this machine's default as an observed fact about another one — so the literal stays, marked as the description of a convention rather than a consumer read.

.changeset/eighty-donuts-tickle.md

@@ -0,0 +1,34 @@
+---
+'@objectstack/cli': patch
+---
+
+fix(cli): `os login --json` is a parseable NDJSON stream (#6531)
+
+`os login --json` produced output that no consumer could read in any shape. The
+device flow wrote its RFC 8628 device-authorization payload compact and, once
+the token poll resolved, the result payload 2-space indented — two JSON
+documents on one stdout. Driven against a live device endpoint, that stream
+failed `JSON.parse(<entire stdout>)` with `Unexpected non-whitespace character
+after JSON at position 200`, and read as NDJSON it failed on 5 of its 6 lines,
+because the second document spanned five of them. The same two-document shape
+appeared on the failure path, where an error payload could follow a
+device-authorization record that had already been written.
+
+`os login --json` is now a **newline-delimited JSON stream**: one compact
+document per line, on every path — the device-authorization record, the
+`--email`/`--password` result, the already-logged-in notice, and the
+`{"success":false,"error":"…"}` failure record alike. Every line parses on its
+own, and the verification-URL record still arrives *before* the user
+authorizes, which is what makes the device flow usable from a script at all.
+
+This is the CLI's **one declared exception** to "`--json` means exactly one JSON
+document on stdout" (#6217), and it is declared rather than silent: the
+`--json` flag's `--help` text says so, and so do the CLI reference page and the
+device-flow section of the authentication docs. Parse this command's stdout
+line by line.
+
+Bumped as a patch: no interface is added or removed and nothing that previously
+worked stops working. The device-flow output was unparseable before, so it had
+no consumers to break; the only other observable change is that the
+email/password result is compact rather than indented, which `JSON.parse` reads
+identically. Human-mode output is untouched.

.changeset/enforce-supports-pause-at-runtime.md

@@ -0,0 +1,24 @@
+---
+'@objectstack/service-automation': patch
+---
+
+Enforce `ActionDescriptor.supportsPause` at the engine boundary: an executor whose
+`execute()` returns `suspend: true` while its descriptor declares `supportsPause: false`
+is now refused instead of pausing the run (#6667, from #5703).
+
+`supportsPause` used to be read only at authoring time — the designer palette, the
+registration warning, and the `check:resume-authority-declared` CI gate, all of which key
+on `supportsPause: true` and so were silent on exactly this mismatch. The pause it let
+through was already broken, just later and elsewhere: a type that declares no pause
+declares no `resumeAuthority` either, and since #5561 an unclaimed pause is fail-closed,
+so the run parked on a durable continuation that the generic resume route then refused
+with `PERMISSION_DENIED` — a message naming `resumeAuthority`, not the `supportsPause`
+that actually caused it. The refusal fails the run where the mistake was made, writes no
+continuation, and names the one-line fix.
+
+Behaviour change for third-party executors in that state (no built-in is: all six pausing
+built-ins declare `supportsPause: true`). The refusal is guard-class, so a `fault` edge
+does not route it — a wrong declaration is not a condition a re-run can fix. Two shapes
+are deliberately untouched: declaring `supportsPause: true` and never suspending is legal
+(a capability, not an obligation), and an executor that publishes no descriptor at all
+declares nothing to enforce — its pauses stay governed by the #5561 resume gate.

.changeset/explain-context-single-authz-aggregation.md

@@ -0,0 +1,45 @@
+---
+'@objectstack/plugin-security': minor
+---
+
+Explain and enforcement now resolve ONE authorization aggregation (#6352).
+
+`buildContextForUser()` — the explain API's reconstruction of an arbitrary user's
+context, behind `explain(request, callerContext)` and the `userId` parameter — was
+a hand-written second implementation of `@objectstack/core`'s `resolveAuthzContext`
+aggregation. Its agreement with enforcement was guaranteed by two comments saying
+it mirrored the resolver ("mirroring the runtime resolver's semantics", "we compute
+it here with the IDENTICAL rule") and by nothing else: no assertion anywhere in the
+repo compared the two.
+
+It did not agree. Measured over identical rows, the mirror dropped:
+
+| input | resolver | explain mirror |
+|---|---|---|
+| `sys_member` role positions (ADR-0095 D3) | `org_admin`, … | — |
+| position-bound permission sets (`sys_position_permission_set`) | resolved | — |
+| the `everyone` anchor's bound sets (ADR-0090 D5) | resolved | — |
+| `platform_admin` position projection (ADR-0068 D2) | projected | — |
+| `systemPermissions` / `posture` / `email` / `ai_seat` | resolved | — |
+
+The user-visible consequence: permission sets are resolved BY NAME from
+`context.positions ∪ context.permissions`, and a set carried by a POSITION only
+becomes a name inside the resolver. So for any user whose grants arrive through a
+position — the ordinary way an org grants access — the explain panel resolved fewer
+sets than enforcement and reported a denial the runtime never made. A security UI
+that says "you have no access" about access you have is worse than no panel.
+
+`buildContextForUser` now calls `resolveUserAuthzGrants` (core's userId-driven
+resolver core, already the same entry point `runAs:'user'` automation runs use) and
+adds presentation only: the ADR-0091 expired-grant and `delegated_from` annotations
+the resolver correctly discards, and `hasPlatformAdminGrant`, which is now read
+back off the resolver's own posture verdict instead of recomputed. The returned
+context additionally carries `systemPermissions`, `org_user_ids`, `posture`,
+`tabPermissions` and `email` — additive; no field was removed or renamed.
+
+Pinned by a parity suite that runs both implementations over the same fixture rows
+(org role projection, position-bound sets, the `everyone` anchor, both
+`platform_admin` polarities, `organization_admin` → `TENANT_ADMIN`, ADR-0091
+windows) and asserts each case's concrete expected output, so the pin cannot pass
+by both sides resolving to nothing. Restoring the mirror turns 9 of those cases
+red.