Merge remote-tracking branch 'origin/main' into fix/3426-followups

# Conflicts:
#	packages/cli/src/commands/validate.ts
#	packages/lint/src/index.ts

Author: os-zhuang

.changeset/adr-0104-d3w2-pr1-upload-complete-fileid.md

@@ -0,0 +1,18 @@
+---
+"@objectstack/spec": patch
+"@objectstack/service-storage": patch
+"@objectstack/client": patch
+---
+
+feat(storage): surface the sys_file id on upload-complete — ADR-0104 D3 wave 2 (PR-1)
+
+`POST /api/v1/storage/upload/complete` now returns the opaque `sys_file` id
+(`data.fileId`), and `client.storage.upload()` surfaces it on the returned
+`FileMetadata`. Previously the commit response omitted the id — the caller
+could not learn which id to persist after committing an upload, so a file
+field could never store a reference.
+
+Additive and non-breaking (new optional `fileId` on `FileMetadataSchema`; the
+client falls back to the presigned id when talking to an older server). This is
+the enabling foundation for file-as-reference; the storage model itself is
+unchanged in this PR.

.changeset/adr-0104-d3w2-pr2-file-read-resolution.md

@@ -0,0 +1,22 @@
+---
+"@objectstack/objectql": minor
+---
+
+feat(objectql): resolve file-field id references on read — ADR-0104 D3 wave 2 (PR-2)
+
+The engine read path now resolves a `file`/`image`/`avatar`/`video`/`audio`
+value stored as an opaque `sys_file` id string into its expanded
+`FileValueSchema` form — `{ id, name, size, mimeType, url }`, with `url` derived
+from the stable `/api/v1/storage/files/:fileId` resolver (never stored). One
+batched `sys_file` `id $in […]` read per query (no N+1), mirroring the
+lookup-`$expand` batch pattern.
+
+**Dual-mode safe.** An inline-blob value (an object) passes through unchanged,
+and only an **opaque id token** (uuid/nanoid-shaped) is treated as a reference —
+a URL-shaped value (`https://…`, `/api/…`, `data:…`, `blob:…`), which a file
+field legitimately holds in the legacy world, is never looked up. The step
+fires zero reads unless a file field actually holds an id token (the blob/URL
+case is free), and it no-ops entirely when `sys_file` is not registered.
+
+This makes a stored `fileId` (surfaced by PR-1) actually usable on read, ahead
+of the v17 cutover that narrows the stored form to an id.

.changeset/approval-empty-position-admin-override.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/plugin-approvals": patch
+"@objectstack/spec": patch
+---
+
+fix(approvals): admin override for a request routed to an unstaffed approver (#3424)
+
+An `approval` node routed to a `position` (or `team`/`department`) with **no
+holders** resolved to only the unresolvable `position:<name>` literal in
+`pending_approvers` — no concrete user was in the slate. Every normal
+`decide` / `reassign` / `recall` then returned `FORBIDDEN` (not a pending
+approver) and, with `lockRecord`, the target record stayed `RECORD_LOCKED`
+forever: a data-availability dead-end with no in-product recovery (the only exit
+was editing the DB by hand). Very easy to hit in fresh/demo orgs (positions
+seeded, holders not) and whenever a role is vacated in production.
+
+A **platform or tenant admin** — the same posture the engine's superuser bypass
+already trusts — may now act on any *pending* request to release it: **approve,
+reject, reassign** it to a real approver, or **recall** it. The override finalizes
+the request (which releases the record lock, keyed on a pending request); a
+tenant admin's authority is org-scoped, a platform admin's is not, and the
+decision is audited under the admin's own id. An admin approval is authoritative,
+finalizing the node even under `unanimous` / `quorum` / `per_group` rather than
+counting as one vote among the (empty) slate.
+
+- `sys_approval_request.viewer` gains `can_override` (server-computed): true for a
+  privileged admin on a pending request. The `approve` / `reject` / `reassign`
+  declared actions OR it into their `visible` gate, so the console surfaces the
+  recovery path without a hand-wired button. Existing approver/submitter gating is
+  unchanged.
+- `openNodeRequest` now logs a loud warning when a node resolves to **no concrete
+  approver**, so the misconfiguration is visible instead of silently locking the
+  record. The literal-fallback behavior (kept for 15.x slot back-compat) is
+  otherwise unchanged.

.changeset/approval-pending-approver-groups.md

@@ -0,0 +1,22 @@
+---
+"@objectstack/spec": patch
+"@objectstack/plugin-approvals": patch
+---
+
+feat(plugin-approvals): expose per-group membership of pending approvers (objectui#2807)
+
+`per_group` (会签) requests now carry `pending_approver_groups` on the
+enriched row — a map from each still-pending approver id to the group key(s)
+it fills (e.g. `{ "u_devadmin": ["finance", "legal"] }`). A client can label
+each "waiting on" chip with the group it represents instead of showing
+duplicate, context-free names.
+
+- Resolved in `attachDecisionProgress` from the same open-time
+  `__approverGroups` snapshot the `decision_progress` groups already use, so
+  the two never disagree.
+- Only the **pending** slots are mapped (a resolved approver has left
+  `pending_approvers`), and **synthetic** (unnamed, `#N`) group keys are
+  dropped — a `· #0` sub-tag would be noise.
+- Absent for non-`per_group` behaviors. Display-only; the engine's
+  finalization tally stays authoritative.
+- Added to the `ApprovalRequestRow` contract in `@objectstack/spec`.

.changeset/flow-trigger-unknown-event-lint.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/lint": minor
+---
+
+feat(lint): flag never-firing record trigger tokens at authoring time (#3427)
+
+New `flow-trigger-unknown-event` rule in `validateFlowTriggerReadiness`: a flow
+start node whose `triggerType` is record-lifecycle-shaped
+(`record-before|after-<op>`) but names an op the record-change trigger cannot map
+— e.g. a typo like `record-after-updated` — binds to the record-change trigger
+yet maps to no ObjectQL hook and never fires, with only a runtime warning. The
+rule surfaces that never-fire defect at `os validate` time. Warning severity;
+bare `record-<noun>` shapes (e.g. `record-change`) are out of scope.

.changeset/lint-flag-record-change-trap.md

@@ -0,0 +1,14 @@
+---
+"@objectstack/lint": patch
+---
+
+fix(lint): flag every never-firing `record-`-prefixed trigger token, incl. `record-change` (#3427)
+
+Generalizes the `flow-trigger-unknown-event` rule: it now flags ANY `record-`-prefixed
+`triggerType` that is not a valid firing token
+(`record-{before,after}-{create,insert,update,delete,write}`) — not just
+`record-(before|after)-<bad-op>` typos. This closes the `record-change` trap: the
+engine routes `record-change` ("Record changed (any)") to the record-change trigger,
+which maps it to no hook so it never fires — now caught at `os validate` time instead
+of only a runtime warn. Also covers bad-phase tokens like `record-during-update`.
+Warning severity, unchanged.

.changeset/previous-null-on-create-leg.md

@@ -0,0 +1,18 @@
+---
+"@objectstack/service-automation": patch
+---
+
+fix(service-automation): bind `previous` (as null) on the create leg so start conditions can discriminate create vs update (#3427)
+
+The engine bound `previous` into the flow condition scope only when it was
+truthy, so on a record insert (`record-after-create`, and the create leg of
+`record-after-write`) `previous` was an **unknown** CEL variable. Any reference to
+it — including the documented `previous == null` create-discrimination — threw
+`condition failed to evaluate as CEL: Unknown variable: previous`, failing the
+whole start condition and dropping the run.
+
+`previous` is now always bound, to `null` when there is no prior row. So
+`previous == null` is the create leg and `previous != null` / `previous.<field>`
+the update leg — the pattern the `record-after-write` docs and the Studio flow
+designer advertise. Update-triggered flows are unaffected (`previous` was, and
+stays, the prior row there).

.changeset/readonly-flow-write-lint.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/lint": minor
+"@objectstack/cli": minor
+---
+
+feat(lint,cli): flag flow `update_record` writes to readonly fields at design time (#3425)
+
+A flow `update_record` node that writes a field the target object declares
+`readonly: true`, under the default `runAs: 'user'` identity, is a **silent
+no-op**: the objectql engine strips static-`readonly` fields from a non-system
+UPDATE payload (#2948), so the intended write never lands — yet the step still
+reports `success`. #3407/#3413 surfaced the strip as a run-time step warning;
+this moves the discovery **left** to `os validate` / `os build` so an author
+finds the mismatch at design time instead of by reading server WARN logs days
+later.
+
+- New `@objectstack/lint` rule `validateReadonlyFlowWrites(stack)` — a pure
+  `(stack) => Finding[]` check (ADR-0019). A static `readonly:true` field
+  written by a literal `update_record` under `runAs !== 'system'` is a
+  100%-certain no-op → **error** (gates the build). A `readonlyWhen` field is
+  per-record-state → **warning** (advisory). Deliberately narrow to stay
+  false-positive-free: `create_record` (INSERT is engine-exempt from the strip),
+  `runAs: 'system'` flows (the intended "automation maintains it" channel),
+  templated object names, and non-literal `fields` maps are all skipped.
+- Wired into `os validate` and `os compile`/`os build`, mirroring the existing
+  security-posture gate (errors fail; advisories print dimmed).
+
+The formal contract, unchanged in behavior: `readonly` governs the end-user /
+API surface (REST/UI and `runAs:'user'` flows strip it); trusted system writers
+(`runAs:'system'`, system hooks, seeds) maintain it. To let a flow maintain a
+readonly field, declare `runAs: 'system'`.

.changeset/seed-insert-replay-lint.md

@@ -0,0 +1,19 @@
+---
+"@objectstack/lint": patch
+"@objectstack/cli": patch
+---
+
+feat(lint): warn on replay-unsafe `mode: 'insert'` seed datasets (#3434 follow-up)
+
+Seeds are replayed — they re-load on every dev-server boot and every package
+re-publish, not applied once — so `mode: 'insert'` (the loader's one mode with
+no existing-row check) duplicates its table on every restart. That footgun
+shipped undetected until #3434 (showcase memberships grew 3 → 6 → 9).
+
+Adds `validateSeedReplaySafety` to `@objectstack/lint` (a pure `(stack) => Finding[]`
+rule, ADR-0019) and wires it into `os validate` / `os lint`. Every `data[]` seed
+declared with `mode: 'insert'` now gets an advisory warning that points at the
+idempotent modes (`ignore` / `upsert`) and the `externalId` to match on — a
+single natural-key field, or a COMPOSITE list of fields for a join / junction
+table with no single key (`['team', 'project']`, the support #3434 added). It
+catches the mistake at authoring time instead of on the second boot.

.changeset/seed-state-machine-lint.md

@@ -0,0 +1,21 @@
+---
+"@objectstack/lint": patch
+"@objectstack/cli": patch
+---
+
+feat(lint): warn on seed values outside an object's declared state machine (#3433 follow-up)
+
+#3433 exempts seed writes from the `state_machine` validation rule, so a seeded
+status the FSM does not declare is no longer rejected at write time. A field-level
+`select` still catches a value outside its `options`, but a `state_machine` on a
+free-text field — or a value that is a valid option yet not a declared FSM state —
+now sails through silently: the exemption is a deliberate but blind back door.
+
+`validateSeedStateMachine` (a pure `(stack) => Finding[]` rule, run from
+`os validate` / `os lint`, symmetric with the replay-safety rule from #3434)
+re-adds that safety net at author time. It flags any seed record whose
+`state_machine`-governed field carries a value outside the machine's declared
+states — the union of `initialStates`, the transition-map keys, and the transition
+targets. Advisory (`warning`): the exemption itself is legitimate, so the fix-it
+points at either adding the state to the machine or correcting the typo, not a hard
+build failure. New rule id: `seed-value-outside-state-machine`.