Merge origin/main into claude/approval-handler-value-lookup-xytdsd

# Conflicts:
#	packages/spec/src/automation/approval.zod.ts

Author: claude

.changeset/adr-0104-d3w2-pr3-file-ownership.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/service-storage": minor
+"@objectstack/spec": minor
+---
+
+feat(storage): exclusive field-reference file ownership — ADR-0104 D3 wave 2 (PR-3)
+
+A `file`/`image`/`avatar`/`video`/`audio` field that holds a `sys_file` id now
+records its owner on the file: `sys_file.ref_object` / `ref_id` / `ref_field`
+name the single `(object, record, field)` slot that references it, maintained on
+the engine write path — claimed on insert, reconciled on update, released when
+the owning record is deleted.
+
+**Field references are exclusive, unlike attachments.** The attachments surface
+deliberately shares one file across many `sys_attachment` join rows; a field
+reference is owned by at most one slot, and writing an already-owned id into a
+second slot **copies the bytes into a fresh `sys_file`** rather than sharing the
+row. That keeps a file's read authorisation derived from exactly one parent
+record instead of the union of every referrer's — so copying a private record's
+file id into a world-readable one cannot silently widen access — and it removes
+reference counting from the lifecycle entirely: a file is released because its
+one owner let go, never because a count came back zero.
+
+**Deletes nothing.** This records and releases ownership; it never tombstones,
+and the `scope === 'attachments'` guardrail that keeps field-referenced files
+out of the reap is untouched. Collection is a separate, gated change that must
+also extend the reap guard's sweep-time re-verify in the same commit.
+
+Also exports `isFileIdToken` from `@objectstack/spec/data` as the single arbiter
+of "is this stored string an opaque file id, or a legacy/external URL?", now
+shared by the read resolver and the write claimer so the two cannot drift.
+
+Dormant until a field actually holds an id token: objects without file-class
+fields, inline-blob values and URL-shaped values all exit before any I/O.

.changeset/adr-0104-d3w2-pr4-governed-download.md

@@ -0,0 +1,52 @@
+---
+"@objectstack/service-storage": minor
+---
+
+feat(storage): governed download for field-owned files — ADR-0104 D3 wave 2 (PR-4)
+
+A file owned by a record's field (`sys_file.ref_object` / `ref_id`, set by
+PR-3) is now authorized on download the same way an attachment is: the caller
+must be able to READ the file's parent record, or be its uploader. Previously
+only `attachments`-scope files were gated and every field file kept an
+anonymous capability URL.
+
+**Parent resolution differs by surface, and that asymmetry is the point.** An
+attachment may hang off many records, so its readable-by set is the union over
+its `sys_attachment` join rows. A field-owned file belongs to exactly one
+record, so its readable-by set is that one record's — nothing more. Under a
+shared reference model the field case would have had to union too, which is
+what makes copying a file id into a more public record silently widen access.
+
+Denials are reported as `FILE_DOWNLOAD_DENIED` (403), distinct from the
+attachments path's `ATTACHMENT_DOWNLOAD_DENIED`, since the file *belongs to* one
+record rather than being *attached to* several.
+
+**`acl: 'public_read'` is the opt-out**, and now an explicit declaration rather
+than the silent default every field file used to get. Genuinely public images —
+anything embedded in an `<img src>`, which cannot carry a bearer token — must
+declare it.
+
+**Dual-mode safe, gates nothing that is open today.** A pre-cutover field holds
+an inline blob or an external URL, never a `sys_file` id, so no existing file
+has an owner recorded and none of them start being gated. The gate engages only
+for files a record's field has actually claimed, and disengages again when
+ownership is released.
+
+---
+
+Also adds `verifyFileReferences()` — the executable form of ADR-0104's R4
+acceptance gate. It compares ground truth (what records' file fields actually
+hold) against recorded ownership, and classifies disagreements by whether they
+could cause data loss once collection is enabled:
+
+- **blocking** — `unowned_reference` (a held file nothing owns), `foreign_owner`
+  (a record holds a file owned by another slot), `shared_reference` (one file
+  held by two slots, i.e. exclusivity was violated). Each would let a later reap
+  delete bytes a record still points at.
+- **advisory** — `stale_owner` (owned but no longer held; fails toward
+  retention) and `unreferenced_file` (storage cost, not a correctness problem).
+
+The scan is read-only — it never writes, tombstones, or deletes. A ledger may
+not be given authority over irreversible deletes until it has been shown to
+agree with reality, so this must report zero blocking discrepancies on real
+tenant data, on consecutive runs, before the gated collection change may merge.

.changeset/adr-0104-d3w2-pr6-backfill.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/service-storage": minor
+---
+
+feat(storage): legacy file-value backfill — ADR-0104 D3 wave 2 (PR-6)
+
+`backfillFileReferences()` converts the pre-reference forms a `file`/`image`/
+`avatar`/`video`/`audio` field may hold — an inline metadata blob
+(`{url, name, size, …}`) or a bare URL string — into the reference form: an
+opaque `sys_file` id, owned by the record's field.
+
+What it will and will not convert:
+
+- **A URL naming this platform's own resolver** (`…/storage/files/:id`) already
+  identifies a `sys_file`; the field is rewritten to the bare id and no bytes
+  move.
+- **A `data:` URI** carries its bytes inline; they are uploaded, a `sys_file` is
+  registered, and the field is rewritten to its id.
+- **An external URL** is reported, never converted. Re-hosting third-party
+  content is a bandwidth, licensing and privacy decision that is not a
+  migration's to make — ADR-0104 R7 retires these toward an explicit `url`
+  field, which under AI authoring is the point: it stops "managed file" and
+  "external link" being the same declaration.
+
+**Dry run by default** — nothing is written unless `apply` is set, and the
+dry-run report has the same shape as the applied one so the plan can be reviewed
+and diffed. **Idempotent** — a value already in reference form is recorded and
+left alone, so a partially-completed run is safe to repeat.
+
+The backfill never writes the ownership columns itself: it rewrites the record,
+and the claim hooks observe that write and record ownership. One claiming path,
+so there is nothing that can disagree with itself. Run
+`verifyFileReferences()` afterwards to confirm the two agree — that
+reconciliation is the gate the irreversible collection change must pass.

.changeset/decision-outputs-surface-3447.md

@@ -0,0 +1,6 @@
+---
+"@objectstack/spec": patch
+"@objectstack/plugin-approvals": patch
+---
+
+Surface the approval node's author-declared `decisionOutputs` keys on the request read as `ApprovalRequestRow.decision_outputs` (#3447 P2 UI enablement). The set varies per request (each node declares its own), so it rides the row rather than the object's static action params — a decision UI renders one input per key and POSTs `outputs` with the decision.

.changeset/expression-approvers-3447-p2.md

@@ -0,0 +1,18 @@
+---
+"@objectstack/spec": minor
+"@objectstack/formula": minor
+"@objectstack/lint": minor
+"@objectstack/service-automation": minor
+"@objectstack/plugin-approvals": minor
+"@objectstack/rest": minor
+---
+
+Dynamic approver routing for approval nodes (#3447 P2) — three new declarative capabilities:
+
+**`expression` approvers.** A new approver type whose CEL expression resolves WHO approves at node entry, over exactly three roots: `current.*` (the record's live state), `trigger.*` (the submit-time snapshot) and `vars.*` (flow variables, incl. upstream node outputs). `record` and bare field names are rejected before evaluation — on this platform `record` always means "the record at event time", which is ambiguous at an approval node — with error messages that prescribe the correct spelling. The optional `resolveAs: 'user' | 'department' | 'position' | 'team'` re-expands each resolved id through the same graph lookups the static types use; with `behavior: 'per_group'` each intermediate value (e.g. each returned department) forms its own sign-off group. A missing key fails the node loudly; only a present-but-empty result counts as an empty slate.
+
+**`onEmptyApprovers` policy.** What an empty resolved slate does, node-level, for all approver types: `admin_rescue` (default — request opens for privileged takeover, the #3424 behaviour), `fail` (node fails), or `auto_approve` (skip the request, continue down the `approve` edge with `output.autoApproved = true`). To support auto-approve, the automation engine now honours `NodeExecutionResult.branchLabel` on the synchronous completion path — the field existed but was only ever consumed via resume signals.
+
+**Decision outputs.** `decide(..., { outputs })` hands structured data from the approver to the flow: the author declares allowed keys on the node (`decisionOutputs`), approvers fill values only, and accepted outputs resume the run as `<nodeId>.<key>` variables — a later approval node's expression can read `vars.<nodeId>.picked_departments`, closing "the previous approver picks the next step's approvers" without a record-field detour. Undeclared keys reject the decision; `decision`/`requestId` are reserved. Multi-approver tallies now always pin to the open-time approver snapshot (previously unanimous re-resolved at each decision against the payload snapshot).
+
+Also: `collectCelRootIdentifiers` is exported from `@objectstack/formula` (shared by the new `os lint` rules and the runtime pre-check, so they can never drift), resolution inputs are audited on the request snapshot as `__resolvedFrom`, and three new lint rules gate expressions, empty-slate policies and reserved output keys at author time.

.changeset/field-readonly-doc-preserveaudit.md

@@ -0,0 +1,4 @@
+---
+---
+
+docs(spec): correct the `field.readonly` describe re: import exemption (#3493). It listed "import" as a system-context exemption, but a normal data import is non-system and still strips; the strip is bypassed only by `isSystem` writes (seed replay, migration) and by an opt-in "historical" import (`preserveAudit`), which admits a whitelist. Describe-string only — regenerates `references/data/field.mdx`, releases nothing.

.changeset/i18n-sso-scim-userposition-importjob-coverage.md

@@ -0,0 +1,24 @@
+---
+"@objectstack/platform-objects": patch
+"@objectstack/plugin-security": patch
+---
+
+fix(i18n): translate the SSO / SCIM / user-position / import-job admin objects
+
+Four live, UI-facing system objects were registered but never added to their
+package's i18n extract config, so non-English admins saw raw English `label`
+metadata:
+
+- `sys_sso_provider`, `sys_scim_provider` (platform-objects) — identity-provider
+  admin grids plus the register / verify-domain actions.
+- `sys_user_position` (plugin-security) — delegated position assignment
+  (`userActions` create/edit/delete); its sibling `sys_user_permission_set` was
+  already translated, so this closes an inconsistency.
+- `sys_import_job` (platform-objects) — import history / progress, alongside the
+  already-translated `sys_job` / `sys_job_run`.
+
+Adds each object to its package's `scripts/i18n-extract.config.ts` and supplies
+real zh-CN / ja-JP / es-ES translations across all four locale bundles, and
+extends the bundle-ownership guards' `OWNED_OBJECTS` to cover them. The
+orphan-only guards from #3502 could not catch this "owned-and-live-but-never-
+extracted" gap.

.changeset/import-undo-preserveaudit.md

@@ -0,0 +1,17 @@
+---
+"@objectstack/rest": patch
+---
+
+fix(rest): undo of a historical import now preserves the audit timeline (#3549)
+
+A `treatAsHistorical` import writes with `preserveAudit` (#3493), keeping the
+original `updated_at`/`updated_by` and business `readonly` fields instead of
+stamping-now / stripping them. Its undo route, however, restored the captured
+pre-import snapshot with a plain write context — so the audit auto-stamp
+re-wrote `updated_at`/`updated_by` to "now", silently corrupting the very
+timeline the historical import had preserved.
+
+The undo write context now mirrors the import's own: it carries
+`preserveAudit` iff the job row is flagged `treat_as_historical`, so restoring
+`u.before` re-writes the snapshotted audit/timestamp values verbatim. A normal
+import's undo is unchanged (default stamp/strip).

.changeset/job-retry-timeout-3494.md

@@ -0,0 +1,32 @@
+---
+"@objectstack/spec": minor
+"@objectstack/service-job": minor
+"@objectstack/runtime": minor
+---
+
+feat(job): honor the authored `retryPolicy` / `timeout` in the job scheduler (#3494)
+
+`JobSchema.retryPolicy` and `JobSchema.timeout` used to be parsed-but-ignored
+(the 2026-06 liveness audit's aspirational-config cluster). They are now
+enforced end to end — built rather than pruned, since retry/backoff and
+per-run time limits are semantics job authors reasonably expect:
+
+- **spec**: `IJobService.schedule` gains an optional 4th `options` argument
+  (`JobScheduleOptions` with `retryPolicy` / `timeout`, mirroring the
+  authorable schema); new `JobRetryPolicy` type. Backward compatible —
+  existing 3-arg implementations and callers are unaffected.
+- **service-job**: new `runWithPolicy` helper (exported, with
+  `JobTimeoutError`) wraps every handler invocation in `CronJobAdapter` and
+  `IntervalJobAdapter`; `DbJobAdapter` threads options through to its inner
+  adapters. Failed attempts (including timeouts) retry with exponential
+  backoff `backoffMs * backoffMultiplier^(retry-1)` up to `maxRetries`;
+  an attempt exceeding `timeout` is recorded with execution status
+  `'timeout'`. No `options` → exactly the legacy single-attempt behavior.
+- **runtime**: declarative-jobs registration in AppPlugin forwards the
+  authored `retryPolicy` / `timeout` to the scheduler.
+
+Note: JavaScript cannot forcibly cancel an in-flight handler — a timed-out
+attempt is abandoned, not killed. The retry delay caps only via the
+multiplier arithmetic (no maxDelay knob yet).
+
+Refs #3494, #1878, #1893.

.changeset/prune-aspirational-config-3494.md

@@ -0,0 +1,56 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec)!: prune the still-dead aspirational config from Theme / Translation / Webhook (#3494)
+
+Removes the authorable-but-never-consumed props confirmed dead by the 2026-06
+liveness audit (follow-up to #1878/#1893; same treatment as the #2377 and
+#3464 prunes). Authoring any of these was a silent no-op.
+
+## Removed
+
+**Theme** (`ThemeSchema`) — the theme engine (objectui `generateThemeVars`)
+never emitted or consumed them:
+- Props: `spacing`, `breakpoints`, `logo`, `density`, `wcagContrast`, `rtl`,
+  `touchTarget`, `keyboardNavigation`
+- Exports: `SpacingSchema`, `BreakpointsSchema`, `DensityModeSchema` (+
+  deprecated `DensityMode` alias), `WcagContrastLevelSchema` (+ deprecated
+  `WcagContrastLevel` alias), and the `Spacing` / `Breakpoints` /
+  `DensityMode` / `WcagContrastLevel` types
+
+**Translation** (`TranslationConfigSchema`) — no runtime reader; there is no
+ICU engine and interpolation is always simple `{variable}` substitution:
+- Props: `fileOrganization`, `messageFormat`, `lazyLoad`, `cache`
+- Exports: `MessageFormatSchema`, `TranslationFileOrganizationSchema`, and the
+  `MessageFormat` / `TranslationFileOrganization` types
+
+**Webhook** (`WebhookSchema`) — the delivery path always sends its own fixed
+envelope and only applies HMAC signing via `secret`; delivery retries are owned
+by the messaging outbox's fixed schedule:
+- Props: `body`, `payloadFields`, `includeSession`, `authentication`
+  (bearer/basic/api-key were never attached; HMAC via `secret` stays),
+  `retryPolicy`, `tags`
+- Exports: the entire inbound `WebhookReceiverSchema` + `WebhookReceiver` type
+  (never consumed by any runtime)
+
+## Migration
+
+Delete these keys from your configs — they never did anything, so removing
+them changes no behavior. Parsed output no longer contains the previously
+defaulted keys (`includeSession: false`, `fileOrganization: 'per_locale'`,
+`messageFormat: 'simple'`, `lazyLoad: false`, `cache: true`). Webhook HMAC
+signing (`secret`), `headers`, and `timeoutMs` are unaffected. File layout for
+translations remains a pure authoring convention — no config knob needed.
+
+## Deliberately NOT removed
+
+- Translation `supportedLocales` — it has a live reader (pinyin-search
+  capability toggle in `serve.ts`).
+- Job `retryPolicy` / `timeout` — being implemented (built, not pruned) in the
+  #3494 follow-up PR.
+- The materialized webhook props (`name`, `object`, `triggers`, `url`,
+  `method`, `headers`, `timeoutMs`, `secret`, `isActive`, `description`,
+  `label`) — live via the #3489 bridge; ledger flip tracked in #3490.
+
+Refs #3494, #1878, #1893.