Merge remote-tracking branch 'origin/main' into claude/issue-18670-refinement-projection-census

Author: claude

.changeset/17936-residue-rule-runtime-authoring-door.md

@@ -0,0 +1,16 @@
+---
+"@objectstack/lint": minor
+---
+
+`validateRetiredPermissionResidue` now runs at the runtime authoring door on `permission` writes, at advisory tier — so a Studio / REST `/meta` / MCP author who writes `allowRestore: false` or `allowPurge: false` and never runs `os lint` is told the line has no effect (#17936, out of #17425 ruling D).
+
+Clause-②: no
+
+The rule was registered `CLI_ONLY` on an open question its own `surfaceReason` recorded: does the gate's `body` reach it BEFORE the per-type `safeParse`, whose residue stage strips the only evidence it reads? Wiring it without that reading would have published a phantom check. **Measured: it does reach it.** `saveMetaItem` keeps the AUTHORED body verbatim on purpose — `parsed.data` would strip the Studio-only auxiliary fields an overlay rides with — and grafts back exactly two normalizations (filter `operator` spellings, the form `groups` → `sections` key move), each a walk over the authored keys that adds and removes nothing else. So `assertRuntimeAuthoringRules` is handed the raw document, the gate passes it through as `item`, and the residue is present in the snapshot the rule reads.
+
+What changes for a caller:
+
+- A `permission` publish carrying either retired key **still succeeds** and now returns one `advisories[]` entry per occurrence, in the door's existing six-key diagnostics envelope (`{severity, rule, where, path, message, hint}`) — the shape Studio and MCP already render for a 422's `issues[]`. `rule` is `permission-retired-lifecycle-residue`, `path` is the name-keyed `permissions.<set>.objects.<object>.<key>`, and `hint` is the tombstone's own prescription, read from the schema rather than retyped.
+- ⛔ **Never a refusal.** The rule is advisory tier; the accept set is untouched, and a value that is *not* the retired default (`true`, `0`, `null`) is still refused by the tombstone at the parse, with its prescription attached, exactly as before.
+- **Draft saves are unchanged** (#4463 D1), and so is every other metadata type: `permission` is the only declared `runtimeTypes` member, because `stack.permissions` is the only collection the rule reads.
+- **The CLI door is unchanged** — `os validate` / `os build` / `os lint` run the rule exactly as they did, with the same positional `permissions[i]…` path. The name-keying is the runtime gate's wire rewrite and does not reach the commands.

.changeset/18110-subflow-map-refused-rollup.md

@@ -0,0 +1,19 @@
+---
+"@objectstack/service-automation": minor
+---
+
+fix(service-automation): on the synchronous path, a child run that REFUSES stops its parent, in `subflow` and in `map` alike (#18110, #18555)
+
+**Clause-②: yes (widening)** — `NodeExecutionResult` is barrel-exported from this package's single entry point, and it gains two new optional members. Nothing previously accepted is refused and nothing is retired, so this is a widening of the published executor contract, not a narrowing. Contract-review tier.
+
+A child flow that runs to completion in one go and ends on an `end` node declaring `outcome: 'refused'` used to roll up to its parent as an ordinary success. `subflow-node.ts` branched only on `child.status === 'paused'` and `!child.success`; a refused child is neither (`{ success: true, status: 'refused' }` — *a refusal is a successful evaluation that says no*), so it fell through the success exit. The parent walked the node's out-edges, recorded `completed` and fired its **own** `successMessage` over the child's refusal — the author got the exact opposite of what they wrote, fail-open. `map-node.ts` had the identical branch set and the identical hole: a refusing row let every row after it through.
+
+- **New on `NodeExecutionResult`: `refuse?: boolean` and `refusalMessage?: string`.** The executor-facing half of the unwinding protocol `suspend?: boolean` already uses. A node that sets `refuse` terminates its run as `refused` — a terminal status this package has published since #15788, so **no new status value** and nothing authorable changes.
+- **`subflow` and `map` both set it** when their child run returns `status: 'refused'`. One channel, two call sites.
+- **The child's `selected` / `acted` / `unmeasuredEffect` rollup (#4354) survives the refusal**, because the engine throws the refusal signal from the same position it throws the suspend signal: after the node's success step is pushed, after its `childSteps` are folded and after its output is written back. A child that refused really can have written rows before it said no.
+- ⛔ **A refusal is still not a failure.** It does not consume retry budget, is not routable by a `fault` edge, and is not counted in `nodes[].failures`.
+- **Region-boundary diagnostic, text only**: the message a structured region raises when a refusal tries to cross it now names whichever node carried the refusal, instead of asserting it was an `end` node — which, for a refusing `subflow`/`map` inside a region, sent the author looking for a node that was not in their region. Region **semantics** are unchanged.
+
+**Scope — the RESUMED leg is not covered.** This fixes the path where the child run finishes inside the parent's own `engine.execute` call and its outcome is read from that return value. A child that durably PAUSES first — a nested `approval` / `screen` / `wait` — and only refuses when it is later resumed still reaches its parent through the resume machinery, which reads the child's outcome at different seams and does not consult `status: 'refused'` at any of them. Both of those seams pre-date this change and neither is a regression of it, but neither is closed by it either, and the resumed leg is the one a screen flow actually takes. A follow-up card covers it: #18714.
+
+For third-party node executors this is additive: an executor that never sets `refuse` behaves exactly as before.

.changeset/18153-record-lock-message-user-facing.md

@@ -0,0 +1,43 @@
+---
+'@objectstack/plugin-approvals': patch
+---
+
+fix(approvals): the record-lock refusal names the record, not its primary key (#18153)
+
+Clause-②: no
+
+A record held by a live approval refused the write with
+`record '<id>' of '<apiName>' is locked while an approval is in progress`. The
+console copies that sentence into a toast verbatim, so an end user read an
+opaque primary key and a machine identifier — neither of which tells them an
+approval has the record — and a deny-path toast is exactly the string that ends
+up in screenshots, screen recordings and support tickets.
+
+It now reads `Opportunity 'Acme renewal' is locked while an approval is in
+progress, and cannot be edited until that approval is complete`, degrading to
+`This Opportunity is locked …` when the object declares no resolvable title and
+to `This record is locked …` when the registry is unreachable — ⛔ never back to
+the id. The record id and the object's API name are not deleted: they move to
+the CONSOLE (`logger.info`, alongside the pending request's id), which is where
+a support path reads them and where a screen recording does not.
+
+**No read was added.** Both halves were already in hand at the refusal: the
+object's `label` and its ADR-0079 title pointer come from the engine's in-memory
+registry (`getSchema`), and the record itself is `ctx.previous`, the pre-image
+the engine has already read — measured on all four update shapes (by-id,
+`updateManyData`, predicate `multi`, unscoped `multi`), every one of which
+dispatches the hook per row with `previous` bound. Deliberately NOT used: a
+system-context read of the record on the deny path (it would title a row the
+caller may not be allowed to READ — the very state this lock exists to gate) and
+the `payload_json` snapshot (served redacted per reader).
+
+**Nothing else moved.** `RECORD_LOCKED` and its `409` are unchanged and pinned
+in both directions, the `CODE: message` envelope is unchanged, and the three
+OPERATOR-facing refusals in the same file — the two `PENDING_LOCK_LIMIT` cap
+messages and the unanswerable-intersection message — still name the object's API
+name, which is the useful thing to say to whoever has to rescope that write.
+They are pinned byte for byte so a later "harmonise the lock's messages" sweep
+cannot fold them into the end-user shape.
+
+A client asserting on the old sentence's text will need updating; a client
+branching on `error.code` or the 409 needs no change.

.changeset/18509-identity-image-logo-nullish.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/spec": minor
+---
+
+`UserSchema.image` and `OrganizationSchema.logo` are declared `z.string().url().nullish()` — a URL string, `null`, or the key absent are all accepted — so the user and organization bodies this platform serves parse against the schemas it publishes (#18509).
+
+Both were `z.string().url().optional()`: a URL string or the key's absence, and `null` refused. Both columns are better-auth-owned and nullable — `sys_user.image` and `sys_organization.logo` are each `Field.url({ required: false })`, reaching SQLite as `varchar(255)` with `notnull=0` — and better-auth SELECTs them and serialises them present-and-null for a user who never set an avatar and an organization created without a logo.
+
+Measured through a real `AuthManager` (better-auth 1.7.3) over a real `ObjectQL` on a real `SqliteWasmDriver`, with the platform's own `sys_user` / `sys_organization` object definitions:
+
+```
+/auth/sign-up/email            -> user.image  = null
+/auth/get-session              -> user.image  = null
+/auth/organization/create      -> logo        = null
+/auth/organization/list        -> [0].logo    = null
+/auth/organization/get-full-organization
+                               -> logo        = null
+                               -> members[].user.image = null
+
+UserSchema.safeParse(<the served session user>)
+  -> [{ path: ["image"], code: "invalid_type",
+        message: "Invalid input: expected string, received null" }]
+OrganizationSchema.safeParse(<the served organization>)
+  -> [{ path: ["logo"], code: "invalid_type",
+        message: "Invalid input: expected string, received null" }, … ]
+```
+
+Those two paths now parse.
+
+- **Measured, not inferred.** #18509 exists because PR #18501's contract review named these two siblings as *not measured* rather than folding them into the `SessionUserSchema.image` ruling it had. The verdict here comes from the probe above, run the way that ruling's own evidence was taken; the analogy was only ever a reason to look.
+- **The declaration was the thing that was wrong.** Prime Directive #12's default — fix the producer, never widen the consumer — rests on the premise it states out loud, that we own both ends. We do not: the nullable columns belong to a third-party model, so PD #12's own exit clause is the operative sentence.
+- **A pure widening.** `.nullish()`, not `.nullable()`: the key's ABSENCE is a legal shape today, so `.nullable()` would retire a live shape as the price of admitting `null`. Every body legal before this change is still legal.
+- **`.url()` is kept, and it does not fight `null`.** These two declarations carry `.url()`, which `SessionUserSchema.image` did not, so the question had to be answered rather than copied. `.nullish()` wraps the whole `z.string().url()`: `null` and `undefined` are separate branches the URL check never sees, while a present string is still required to be a well-formed URL. Of six inputs — absent, `null`, `''`, a URL, a non-URL, a number — exactly one row moves, and it is the ruled one. `''` and `'not-a-url'` are still refused.
+- **No key is added or removed** — both keys were already authored and already published, so no authorable surface moves and nothing is retired.
+- **`OrganizationSchema` is not made whole by this.** The same probe found `metadata` served present-and-null and `/auth/organization/create` omitting the required `updatedAt`. Those are separate defects with their own reasoning, filed separately rather than folded in; #18509 asked about `logo`.

.changeset/18616-turso-remote-transaction-refusal.md

@@ -0,0 +1,18 @@
+---
+"@objectstack/driver-turso": minor
+---
+
+`TursoDriver` in **remote** mode now **refuses** transactions with `NOT_IMPLEMENTED` / `501` instead of accepting them and silently doing nothing with them. Local and embedded-replica modes are unchanged — they inherit `SqlDriver`'s knex transactions and still honour `options.transaction`.
+
+**What was wrong.** `@objectstack/spec`'s `driver.zod.ts` states the delivery mechanism verbatim: *"A transaction handle to be passed to subsequent operations via `options.transaction`."* On the remote transport nothing could receive it. `RemoteTransport` names a transaction in exactly three members (`beginTransaction()`, `commit(t)`, `rollback(t)`) and **zero** of its data methods take an `options` argument at all — against 13 data methods present in the file, which is what makes that zero a reading. So a write issued between `beginTransaction()` and `rollback()` executed on the plain connection, was **already durable**, and the rollback resolved having undone nothing. Every step reported success.
+
+**What refuses now**, on the remote arm only:
+
+- `beginTransaction()`, `commit()` and `rollback()` — the capability is never handed out, so the sequence above cannot start.
+- Any driver method that arrives carrying `options.transaction` — `find`, `findOne`, `count`, `aggregate`, `create`, `update`, `upsert`, `delete`, the three bulk methods, `updateMany`, `deleteMany`, `execute`, `syncSchema`, `syncSchemasBatch`, `dropTable`. This second door is not redundant: the engine's `buildDriverOptions` reads `execCtx.transaction` **first**, so a handle threaded through `ExecutionContext` reaches a data method without ever passing through `beginTransaction()`.
+
+The refusal fires on the **handle**, not on remote mode: a remote call with no transaction in it is untouched, which is every call the platform makes today. It is raised before any statement is built, so a refused call costs no round trip and leaves no partial write.
+
+**If this refusal now fires for you, it is telling you that you never had the transaction.** The remedies, in order: use the **local or embedded-replica** transport for work that needs atomicity; or take the non-transactional path deliberately — `engine.transaction()` without `require: true` on a driver with no transactions runs the callback with no rollback and says so (ADR-0119 D1). `NOT_IMPLEMENTED` / `501` rather than a `400` because the request is spelled correctly and the spec declares the members: the gap is the backend's, the same two-class taxonomy this driver already applies to remote `auto_number`, aggregate functions and date buckets.
+
+Implementing real transactions on the remote transport is a separate, larger piece of work and is deliberately **not** part of this change.

content/docs/references/identity/identity.mdx

@@ -63,7 +63,7 @@ const result = AccountSchema.parse(data);
 | **email** | `string` | ✅ | User email address |
 | **emailVerified** | `boolean` | optional (default: `false`) | Whether email is verified |
 | **name** | `string` | optional | User display name |
-| **image** | `string` | optional | Profile image URL |
+| **image** | `string \| null` | optional | Profile image URL |
 | **createdAt** | `string` | ✅ | Account creation timestamp |
 | **updatedAt** | `string` | ✅ | Last update timestamp |
 

content/docs/references/identity/organization.mdx

@@ -85,7 +85,7 @@ const result = InvitationSchema.parse(data);
 | **id** | `string` | ✅ | Unique organization identifier |
 | **name** | `string` | ✅ | Organization display name |
 | **slug** | `string` | ✅ | Unique URL-friendly slug (lowercase alphanumeric, hyphens, underscores) |
-| **logo** | `string` | optional | Organization logo URL |
+| **logo** | `string \| null` | optional | Organization logo URL |
 | **metadata** | `Record<string, any>` | optional | Custom metadata |
 | **createdAt** | `string` | ✅ | Organization creation timestamp |
 | **updatedAt** | `string` | ✅ | Last update timestamp |