Merge remote-tracking branch 'origin/main' into claude/issue-15325-ratify-hook-body-subpath-export

Author: claude

.changeset/assignment-value-cel-envelope-executor.md

@@ -0,0 +1,71 @@
+---
+"@objectstack/service-automation": minor
+"@objectstack/lint": minor
+---
+
+feat(service-automation): an `assignment` value may be a CEL envelope — evaluated at run time, validated at `registerFlow`, `objectstack validate` and the runtime publish gate (#15137, the executor half of #14149)
+
+<!-- adr-0087: not-required (no-migration-prescription) No authorable key is renamed, retired or re-typed: the `assignments` map and every value form it accepted still parse. The only newly refused shape is a malformed CEL value envelope, a spelling declared one day earlier in #15113 and offered by no authoring surface before it, so `objectstack migrate meta` has nothing to rewrite and this changeset carries no rewrite instructions for a consumer to follow. -->
+
+**BREAKING** in the accept-set sense, landing in the launch window as `minor`
+(the lockstep convention; the level also follows the 2026-09-04 bump ruling —
+this adds `AutomationEngine.evaluateValueEnvelope` to a published surface, and an
+additive widening is at least `minor`). No ADR-0087 conversion: no authorable key
+is renamed or retired, and the shape this refuses was never a shape any surface
+offered.
+
+The maintainer's 2026-09-02 ruling on #14149 made an assignment value able to be
+a CEL **value** expression, so the declared stdlib (`joinNonEmpty`, `map`, `size`
+…) is finally reachable from metadata — until now CEL was only ever asked for a
+boolean. The spec half landed the contract (PR #15113); this is the half that
+makes it do something.
+
+```yaml
+# before: written into the variable verbatim, and rendered by `notify` as
+#         {"dialect":"cel","source":"joinNonEmpty(...)"}
+# now:    evaluated — digest is "Renewal due\nInvoice overdue"
+assignments:
+  digest: { dialect: cel, source: 'joinNonEmpty(rows.map(r, r.subject), "\n")' }
+```
+
+- **Evaluated at run time.** The built-in `assignment` executor evaluates a
+  `value`-role envelope with the expression engine and assigns the result, in the
+  same CEL scope a flow predicate is evaluated in (one shared scope builder, so a
+  predicate and a value expression cannot disagree about what `rows` means). A
+  plain string keeps today's `{token}` interpolation, and every other literal is
+  still assigned as data.
+- **Refused at three doors.** A malformed envelope now stops the flow registering
+  (`registerFlow` throws, the severity a malformed predicate gets) and surfaces as
+  a located `error` finding naming the node and the author's own variable —
+  `config.assignments.digest` — both at `objectstack validate` and at the runtime
+  publish gate a Studio / REST / MCP flow write goes through
+  (`validateStackExpressions` is registered `CLI_AND_RUNTIME`, `runtimeTypes:
+  ['flow']`). Malformed is a composition, not a fixed list: whatever
+  `AssignmentValueSchema` refuses in the envelope's shape — among them a missing,
+  empty or non-string `source`, a dialect other than `cel`, a non-object `meta` —
+  and then CEL that does not parse. All three doors derive that set from the same
+  two published validators, so none refuses a shape the executor would have run,
+  and a registered flow never faults for a shape those validators judge malformed.
+  Two shapes sit outside what either validator can judge — an `ast`-only envelope
+  and a whitespace-only `source` (it passes `min(1)` and reads as "not authored"
+  to the validator, while the CEL engine parses it untrimmed) — and those fault
+  loudly at run time rather than assigning a value. Both are pinned and tracked in
+  #15430.
+- **Only the canonical map.** The ledger declares `assignment.assignments.*` and
+  nothing else, so the two legacy shapes the executor still normalizes — the
+  `assignments: [{ variable, value }]` array and the bare `{ <variable>: <value> }`
+  config — keep every meaning they had, envelope-shaped values included.
+  `AssignmentConfigSchema` is deliberately NOT wired into `parseNodeConfig` for the
+  array form: refusing it would break flows that register today, and that refusal
+  is a maintainer ruling rather than a lane's call (#15137 ask 3).
+
+**What changes silently, and how far it reaches.** A flow that today authors an
+envelope-shaped object *as data* in the canonical `assignments` map now evaluates
+it — no error on either side, a different value. The discriminator is the spec's
+own `isExpressionEnvelopeShaped`: a plain object naming a **string** `dialect`,
+in the declared map only. Data that names no `dialect`, names a non-string one,
+nests the envelope one level down, or sits in either legacy shape is untouched
+and byte-identical. The remaining overlap — a well-formed
+`{ dialect: 'cel', source: … }` written as data in the canonical map — is exactly
+the spelling the ruling reinterprets; every near-miss the two validators can
+judge now refuses loudly at registration instead of changing value in silence.

.changeset/truthful-stranded-decision-envelope.md

@@ -0,0 +1,17 @@
+---
+"@objectstack/types": minor
+"@objectstack/plugin-approvals": minor
+"@objectstack/rest": minor
+---
+
+An approval decision that lands while its flow run strands now says so in fields, not only in prose.
+
+`POST /api/v1/approvals/requests/{id}/reject` — and its sibling decision doors — could produce three coexisting outcomes from one call: the caller read HTTP 500, the request row **was** in its terminal status and had left the pending inbox, and the workflow run was stranded. A caller reading 500 has one honest inference available — "the rejection did not happen" — and it was the wrong one, so scripts and operators retried or escalated against a decision that was already durable. The only carrier of the truth was English prose in `error`, so finding the affected run meant regexing a run id out of a sentence, and nothing said whether that run could be repaired at all.
+
+The 500 stays. A recorded decision whose flow never advances is still a failure and is still reported as one; the door does not become atomic and no decision is ever rolled back. What changed is that it stops discarding what the engine already said:
+
+- **The `RESUME_FAILED` body gains four fields**, additively — `finalized` (always `true`: the decision stands), `decision`, `runId`, and `repairable`. Existing consumers see the same `code`, the same `error` and the same status.
+- **`repairable` carries the engine's own discriminator** — `AutomationResult.status === 'stranded'`, the state stamped on exactly the exit that journals a repair snapshot. `false` is the answer for every other failure, including a lost run: absence of the signal is not repairability, and a repair verb that would refuse is worse than no promise.
+- **`serviceResume` carries `status`** through to the door. It previously read only `success` / `code` / `error`, and the stranded exit reports a `status` and no `code` at all — so the platform's own repairability signal died one line before the envelope was built.
+
+`@objectstack/types` gains `strandedDecisionFailure` / `strandedDecisionDetails` and the `StrandedDecisionDetails` type — the constructor and its recogniser in one module, so the producing service and the REST door cannot drift. A `RESUME_FAILED` raised without that carrier answers exactly the body it always did; the door never synthesises the envelope.

content/docs/automation/flows.mdx

@@ -199,21 +199,30 @@ or missing-`required` violation (#4277). A node type that publishes no
 A value's **shape** selects its form — there is no mode key. A plain string is
 always `{token}` interpolation (a bare `a + b` is the literal text `a + b`, not
 CEL); an object that names a `dialect` is an expression envelope and must be a
-valid `cel` one — a missing or empty `source`, or a `template` / `cron`
-dialect, is refused at the variable's path. Numbers, booleans, arrays and plain
-objects are assigned as literals. A later `notify` node renders the variable as
-any other: `message: '{digest}'`.
-
-<Callout type="warn" title="The contract landed first; the executor half follows">
-
-The envelope form is what `@objectstack/spec` declares — the expression
-ledger's `value` entry and `AssignmentConfigSchema`, the half ruled in
-[#14149]. Until the matching `@objectstack/service-automation` change lands,
-the built-in `assignment` executor still writes an envelope object into the
-variable verbatim and `notify` renders it as JSON. For a digest body today,
-call a registered function from a `script` node.
-
-[#14149]: https://github.com/objectstack-ai/objectstack/issues/14149
+valid `cel` one — a missing, empty or non-string `source`, or a `template` /
+`cron` dialect, is refused at the variable's path. Numbers, booleans, arrays
+and plain objects are assigned as literals. A later `notify` node renders the
+variable as any other: `message: '{digest}'`, and it renders the **evaluated**
+value.
+
+<Callout type="info" title="Where a malformed envelope is refused">
+
+A malformed envelope never reaches run time silently: the same refusal runs at
+`objectstack validate` (a located finding naming the variable), at the runtime
+publish gate a Studio / REST / MCP flow write goes through, and at
+`registerFlow`, which refuses to register the flow. All three ask the same two
+questions in the same order — is it a valid `cel` envelope
+(`AssignmentValueSchema`), and does its source parse as CEL
+(`validateExpression`) — so a flow that registers is a flow whose envelopes
+those two validators accept.
+
+Two shapes sit outside what either validator can judge and fault loudly at run
+time instead of assigning a value: an `ast`-only envelope (no `source` — the
+CEL engine evaluates `source`), and a whitespace-only `source`, which passes
+`min(1)` and reads as "not authored" to the validator while the engine parses
+it untrimmed. Both are tracked in [#15430].
+
+[#15430]: https://github.com/objectstack-ai/objectstack/issues/15430
 
 </Callout>
 

content/docs/permissions/system-context.mdx

@@ -64,7 +64,7 @@ not on any flag.
 ## How the flag is set
 
 `isSystem` is **server-constructed and never client-supplied**. Inbound HTTP
-cannot set it (`packages/rest/src/rest-server.ts:1548`, `:1577`), and neither
+cannot set it (`packages/rest/src/rest-server.ts:1553`, `:1582`), and neither
 can an action body (`packages/runtime/src/domains/actions.ts:414`). It is
 written by internal callers only, as an option on the engine call:
 
@@ -103,7 +103,7 @@ that silently does not happen.
 | 14 | MCP stdio bridge skips the object API-exposure gate | mcp | Get: the bridge reaches objects whose `apiEnabled` / `apiMethods` would refuse an external caller | `stdio-data-bridge.ts:246` |
 | 15 | **Read-audit rows are not written** | plugin-audit | Lose: the "a person opened this record" trail. `sudo()` keeps the caller's `userId`, so this flag is the only thing separating a human read from a platform one | `read-audit.ts:556` |
 | 16 | Approval snapshot payload redaction skipped | plugin-approvals | Get: the whole snapshot on `find` / `findOne` — the audit/replay channel. Lose: field-visibility redaction over approval payloads | `payload-redaction-middleware.ts:115` |
-| 17 | REST anonymous-deny seam satisfied | rest | Get: `enforceAuth` passes with no `userId`. Not reachable from the wire — `isSystem` is never set on an inbound request | `rest-server.ts:1580` |
+| 17 | REST anonymous-deny seam satisfied | rest | Get: `enforceAuth` passes with no `userId`. Not reachable from the wire — `isSystem` is never set on an inbound request | `rest-server.ts:1585` |
 
 ### 2. Write pipeline and data integrity
 
@@ -145,7 +145,7 @@ The largest single consumer — **17 of the 106 sites**.
 |:--|:---|:---|:---|:---|
 | 40 | **Approval record lock released** — a locked record is writable | plugin-approvals | Get: engine self-writes (the status mirror) pass. Lose: the lock that stops edits while an approval is live. Note there is deliberately **no admin exemption** here — only `isSystem` | `lifecycle-hooks.ts:347` |
 | 41 | Delegation write guard bypassed | plugin-approvals | Get: service / seed / import may write delegation rows naming another delegator | `lifecycle-hooks.ts:570` |
-| 42 | Approval actor / submitter / pending-approver checks bypassed (8 sites) | plugin-approvals | Get: approve, reject, recall, reassign without being a pending approver or the submitter | `plugin-approvals/src/approval-service.ts:963`, `:1072`, `:3196`, `:3342`, `:3509`, `:3580`, `:3769`, `:3809` |
+| 42 | Approval actor / submitter / pending-approver checks bypassed (8 sites) | plugin-approvals | Get: approve, reject, recall, reassign without being a pending approver or the submitter | `plugin-approvals/src/approval-service.ts:963`, `:1072`, `:3248`, `:3396`, `:3564`, `:3635`, `:3824`, `:3864` |
 | 43 | Saved-report ownership is **assignable**, and an update may reassign it | plugin-reports | Get: `ownerId` from input is honoured. A non-system caller always owns what it creates and can never reassign | `plugin-reports/src/report-service.ts:404`, `:425` |
 | 44 | Saved-report access / export / mutation gates bypassed | plugin-reports | Get: read, bulk-export and overwrite any report | `plugin-reports/src/report-service.ts:343`, `:372`, `:447`, `:684` |
 | 45 | Attachment access hooks return early (insert + update + delete, and the read AST) | service-storage | Lose: attachment visibility scoping | `attachment-access-hooks.ts:300`, `:349`, `:448`, `:524` |
@@ -158,7 +158,7 @@ The largest single consumer — **17 of the 106 sites**.
 |:--|:---|:---|:---|:---|
 | 48 | Object API-exposure gate bypassed (`apiEnabled` / `apiMethods`) | runtime | Get: internal self-writes ignore exposure declarations — these govern **external** exposure, not engine self-writes | `action-execution.ts:138` |
 | 49 | Action `requiredPermissions` bypassed | runtime | Get: engine self-invocation runs any action | `action-execution.ts:401` |
-| 50 | `manage_metadata` bypassed on metadata writes | runtime, rest | Get: schema writes without the capability | `domains/meta.ts:471`, `:874`, `rest-server.ts:4967`, `:6381`, `:6629`, `:7060`, `:7253` |
+| 50 | `manage_metadata` bypassed on metadata writes | runtime, rest | Get: schema writes without the capability | `domains/meta.ts:471`, `:874`, `rest-server.ts:4972`, `:6386`, `:6634`, `:7065`, `:7258` |
 | 51 | The shared metadata-write verdict itself returns `allowed` | metadata-core | Get: the one function all of row 50's doors consult answers yes before any capability is examined | `meta-write-capability.ts:134` |
 | 52 | Anonymous-deny seam satisfied on the domain dispatchers and the package/federation routes | runtime, rest | Get: passes with no `userId` | `domains/actions.ts:421`, `domains/ai.ts:60`, `domains/automation.ts:989`, `domains/meta.ts:232`, `domains/security.ts:78`, `domains/packages.ts:422`, `external-datasource-routes.ts:302`, `package-routes.ts:97` |
 | 53 | MCP principal check satisfied | runtime | Get: MCP surface reachable with no user | `domains/mcp.ts:61` |
@@ -199,7 +199,7 @@ assuming `isSystem` covers it is a documented source of bugs.
 | "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1580` (#3493 / #6640) |
 | "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
 | "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:299` |
-| "A client can request it" | **No.** Never settable from inbound HTTP or from an action body | `rest-server.ts:1548`, `:1577`; `domains/actions.ts:414` |
+| "A client can request it" | **No.** Never settable from inbound HTTP or from an action body | `rest-server.ts:1553`, `:1582`; `domains/actions.ts:414` |
 
 ---