Merge remote-tracking branch 'origin/main' into claude/issue-6394-date-bucket-options-cast

Author: claude

.changeset/discovery-direct-mount-route-keys.md

@@ -0,0 +1,41 @@
+---
+"@objectstack/spec": minor
+"@objectstack/metadata-protocol": minor
+"@objectstack/rest": minor
+"@objectstack/client": patch
+---
+
+feat(spec,metadata-protocol,rest,client): the direct-mount surfaces (`packages`, `datasources/:name/external/*`) become discoverable, and the SDK follows the advertised base (#6633)
+
+The rest surface's `/discovery` never advertised `routes.packages` — routes
+mounted but not advertised, the unstated half of ADR-0076 D12 — so the SDK's
+`packages.*` always fell back to the hard-coded `/api/v1/packages`; and the
+SDK's `datasources.external.*` had no discovery mechanism at all, hard-coding
+`/api/v1/datasources/...` in each of its five methods. On any deployment with a
+non-default API base, both families built wrong URLs (measured in #6633).
+Maintainer ruling 2026-08-08 (route B, prerequisite for #6306):
+
+- **spec** (minor, additive): `ApiRoutesSchema` declares a `datasources` key —
+  the base of the federation-admin family. Optional like `mcp`: absent = not
+  mounted.
+- **metadata-protocol** (minor, additive): `getDiscovery()` advertises
+  `routes.packages: '/api/v1/packages'` iff the `package` service is
+  registered (`serviceToRouteKey` gains the mapping; the route flows through a
+  non-slot table because `package` is not a `CoreServiceName`). `datasources`
+  is deliberately NOT advertised by this builder — the mount belongs to the
+  REST host it cannot see (same disposition as `mcp`).
+- **rest** (minor): `/discovery` advertises `routes.packages` and
+  `routes.datasources` as projections of the RECORDED direct mounts (#5822) —
+  advertisement and mounting derive from one fact, so #6306's later mount-base
+  move carries the advertisement along by construction. Not mounted ⇒ not
+  advertised. An end-to-end parity pin (`discovery-advertised-direct-mounts.
+  parity.test.ts`) drives the composed surface and goes red on any change that
+  moves only one side.
+- **client** (patch, behavior fix): the five `datasources.external.*` methods
+  derive their base via `getRoute('datasources')` — connected clients follow
+  the advertised base; unconnected clients (or servers that advertise no
+  `datasources` key) keep building byte-identical `/api/v1/...` URLs.
+
+No key is removed and no wire shape changes for existing deployments: servers
+gain two advertised keys, and the SDK changes URLs only when a server
+advertises the new keys with a non-default base.

.changeset/field-when-user-root-aliases.md

@@ -0,0 +1,45 @@
+---
+"@objectstack/lint": patch
+---
+
+fix(lint): the field-level user-root rejection covers all three ADR-0068 spellings, not just `current_user` (#6585)
+
+#6290 gave field-level `visibleWhen` / `readonlyWhen` / `requiredWhen` a
+surface-level rejection when the predicate reaches for the signed-in user, with
+a prescription that names surfaces which actually bind one. That check matched a
+single spelling — `current_user` — while ADR-0068 D1 makes `user` and `ctx.user`
+**the same object under different names**: `buildScope` hangs one `EvalUser`
+reference on `current_user` / `user` / `ctx.user` / `os.user`. So the identical
+semantic error produced an error under one spelling and **total silence** under
+the other two (both have always been in `SCOPE_ROOTS`, so the bare-reference
+check never fired on them either). Which of three ADR-equivalent spellings the
+author happened to pick decided whether they got a build-time diagnostic at all.
+
+The failure direction is the one #6146 named: an unbound root faults, the fault
+falls back, and visibility's fallback is `true` — so a predicate written to HIDE
+a field by role left it visible to everyone, silently.
+
+All three roots now share one verdict, one prescription and one message; only
+the root named in the message varies. Nothing about the option level changes:
+per-option `visibleWhen` resolves against the host's predicate scope, which
+binds the user under every spelling, so the showcase's role-gated option
+(`'admin' in current_user.positions`) stays legal — under the aliases too.
+
+**`ctx` is judged as a whole root, not only in `ctx.user` form.** At this
+surface that is simply what is true: `buildScope` creates the `ctx` root *only*
+when the evaluation carries a user, and no field-level site passes one — the
+server binds `record` + `previous` (+ `parent`) and the client's
+`evalFieldPredicate` binds `record` + `previous` + a caller scope that is only
+ever `{ parent }`. `ctx.locale` therefore faults exactly like `ctx.user.id`
+here. The narrower reading was rejected because it needs a source-level spelling
+match, which would re-open this very fork one level down (`ctx["user"].id`
+silent, `ctx.user.id` rejected) while leaving a real fail-open fault
+unreported. `ctx` remains ActionEngine's predicate root elsewhere and is
+untouched there — the platform's own `ctx.user` predicates all sit on action
+`visible` (`sys-user.object.ts`, `sys-invitation.object.ts`), a surface this
+rule never reads, and that acceptance is pinned.
+
+Sweep: field-level `*When` predicates reading any user root measure **zero**
+across `examples/`, `packages/` and the downstream `objectui` repo, by both a
+slot-keyed scan and an alias-keyed one — so no shipping metadata is refused by
+the widening. `objectstack validate` stays clean on all three example apps.

.changeset/import-dryrun-hook-boundary-docs.md

@@ -0,0 +1,28 @@
+---
+"@objectstack/spec": patch
+---
+
+docs(spec): `ImportRequest.dryRun` states the boundary an import preview has — no automations run (#6537)
+
+An import dry run routes through the engine's own write-path validation
+(`DataProtocol.validateData`, #6037 / #4633 ruling D) and applies no
+`runAutomations` gate, because gating it would leave the common dry run with no
+validation at all — the false all-clear that work set out to close. The engine's
+validate-only path deliberately runs **no hooks**: a preview that fired
+user-authored side effects (mail, outbound calls, writes to other objects) would
+be the retired `BatchOptions.validateOnly` defect (#4052) in a new spelling.
+
+The consequence an author can meet is narrow and, until now, written down only in
+the engine's and the import runner's source comments: on an object whose
+`beforeInsert` hook derives a **required business field**, a dry run with
+`runAutomations: true` can report `required` for a row the real import would have
+created. Audit and ownership stamps (`created_by`, `owner_id`,
+`organization_id`, …) are `system`/`readonly` and skipped by validation anyway, so
+they cannot produce this.
+
+`ImportRequest.dryRun`'s description now says so, which puts it on the reference
+page an author reads before sending the request — the same schema backs
+`CreateImportJobRequest`, so the synchronous route and the async import job both
+carry it. **Zero behaviour change**: one description string, and the
+`content/docs/references/api/export.mdx` cells regenerated from it by
+`gen:schema && gen:docs` (no hand edits).

.changeset/patch-path-id-wins-over-body-id.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/metadata-protocol": patch
+---
+
+fix(metadata-protocol): a single-record update binds the row the CALLER named, not the row the body names (#6479)
+
+`PATCH /data/:object/:id` decided which row to write **twice, differently**. The
+protocol's `updateData` probed existence and validated `If-Match` /
+`expectedVersion` against the path `:id`, built `{ where: { id: request.id } }`,
+and then handed the request body to the engine verbatim — where the dispatch
+reads the payload first, so a truthy scalar `data.id` outranks `where.id`.
+
+So `PATCH /data/task/rec_1` with a body of `{"id":"rec_2","title":"x"}`:
+
+- probed **rec_1** for existence (404 gate, #4435);
+- version-checked **rec_1** against the caller's `If-Match`;
+- **wrote rec_2**; and
+- answered `{ id: "rec_1", record: <rec_2's readback> }` — a receipt whose two
+  halves name different rows.
+
+rec_2 was never probed and never version-checked, so the most common client
+shape there is — GET a record, edit a field, PUT the whole body back — performed
+a **silent cross-row write straight past its own optimistic-concurrency check**
+whenever the body carried another row's id (a mis-clicked list row, a stale
+refresh, a generated client that copied the wrong field).
+
+`updateData` now merges the path id over the payload before dispatch
+(`{ ...request.data, id: request.id }`) — the same shape the **bulk** ingress has
+always used for this question (`ql.update(op.object, { ...data, id }, …)`), so the
+two ingresses give one answer instead of two. The probed row, the OCC-checked
+row, the written row and the receipt's `id`/`record` are now the same row: the
+one in the URL.
+
+Nothing else moves:
+
+- **The engine is untouched.** ObjectQL's payload-first dispatch (#5748) and its
+  by-id payload strip (#6435) are unchanged and still correct for a caller who
+  hands ObjectQL a payload and nothing else; this was a gap at the REST/protocol
+  ingress, which had already named the row.
+- **No new rejection, no request-shape change.** A body `id` equal to the path
+  id behaves exactly as before, and a differing one is now simply overridden
+  rather than refused — `UpdateDataRequestSchema` still accepts the same bodies.
+- **Non-record payloads pass through untouched** (`undefined`, `null`, an array),
+  so the engine's own diagnostics for a malformed call still surface unchanged.
+
+Callers that deliberately relied on the body's `id` redirecting a
+single-record PATCH must address the intended row in the URL instead — the bulk
+endpoint has never honoured a body id either.

.changeset/platform-schedule-create-record-org-gate.md

@@ -0,0 +1,67 @@
+---
+"@objectstack/metadata-protocol": patch
+---
+
+feat(metadata-protocol): publishing a platform-level scheduled `create_record` flow is refused on a multi-organization deployment unless it declares `organization_id` (#6285)
+
+A scheduled flow that creates records now has to say which organization those
+records belong to — but only where the answer matters, and only where nothing
+else can supply it.
+
+## What was open
+
+`ScheduleTrigger` builds its context as
+`{ event: 'schedule', params: { jobId, flowName, schedule } }` — no `tenantId`.
+PR #6153 closed the engine half of #5494 on the rule "stamp what the engine
+KNOWS": a run whose trigger resolved an organization carries it through, and the
+driver's tenant machinery fills `organization_id` on rows that omit it. A
+schedule resolves none, so nothing fills anything — and the dominant production
+shape of the whole issue is a nightly sweep, which fires on a schedule and not
+by hand. Every row it created was born `organization_id` NULL.
+
+That is not a cosmetic NULL. A `(organization_id, …)` unique index does not
+constrain across NULL and an org-scoped query does not see the row, so the
+damage is duplicate and invisible records — hotcrm#698's duplicate numbering —
+in a stored shape no later fix can retroactively repartition.
+
+## What now happens
+
+At the runtime publish gate, this exact combination is refused with the existing
+422 `INVALID_METADATA` envelope (`code` + `status` + `issues[]`, ADR-0112):
+
+- the deployment enforces an organization wall
+  (`postureEnforcesWall(resolveTenancyPosture())` — `group` or `isolated`,
+  ADR-0105 D1), **and**
+- the flow is platform-level (the write carries no organization), **and**
+- it binds to the **schedule** trigger, **and**
+- it contains a `create_record` node, **and**
+- that node declares no `fields.organization_id`.
+
+Every limb's negation still publishes: a single-organization deployment, an
+org-scoped write, any other trigger, a flow that creates nothing, and — the
+fix an author actually applies — a node that declares
+`config.fields.organization_id`. That key is not new: `CreateRecordConfigSchema`
+has always carried `fields`, and #6153's fill-only stamping already guarantees
+an author-supplied value wins over any engine fill. One issue is reported per
+offending node, including nodes nested inside `loop` / `try_catch` / `parallel`
+regions, each addressed at the key the author must write.
+
+Drafts are never gated (#4463 D1) and the draft to active promotion is, so the
+draft door is not a bypass. `OS_ALLOW_UNLINTED_METADATA_WRITES=1` degrades the
+refusal to a loud log exactly as it does for the 26 shared rules, and
+`os migrate meta --stored` stays carved out.
+
+## Where the judgement lives, and why
+
+Runtime publish gate only; `os validate` / `os build` / `os lint` do **not**
+judge this. Both inputs the rule needs are facts about the **deployment**, and
+the CLI runs on a build machine — a shared rule would sentence every
+single-organization repository on whatever `OS_TENANCY_POSTURE` happened to be
+exported in CI. The gate's caller performs the two readings and passes them as
+arguments, so the judgement itself stays a pure function of its inputs.
+
+Migration note for a multi-organization deployment: an existing scheduled flow
+keeps running untouched — the gate blocks new writes only, never stored rows —
+but the next time one is republished it will be refused until the
+`organization_id` is declared, which is the same edit that stops it writing
+outside the organization partition.

.changeset/retry-policy-etl-tombstone-enumeration.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): the `retryDelayMs` tombstone no longer points an upgrading author at the retired ETL surface (#6630)
+
+#6414 retired the whole L2 ETL layer (`automation/etl.zod.ts`: `ETLPipeline`,
+`ETLPipelineRun`, their source/destination/transformation vocabulary, four enums
+and the `ETL` factory — 9 defs, 27 exported names). `shared/retry-policy.zod.ts`
+was updated in exactly one stanza and left every other mention of
+`ETLPipeline.retry` in the present tense — including the one string that is not
+documentation.
+
+**The author-visible half.** `retryDelayMs`'s `retiredKey()` guidance is the
+upgrade channel `shared/retired-key.ts` describes in its own words ("an agent
+bumping `@objectstack/spec` sees THIS string, not our docs site"). It enumerated
+four surfaces on which the converged spelling applies, and the fourth — "an ETL
+pipeline's `retry`" — had been deleted in the same major. An author or agent
+migrating `retryDelayMs` → `backoffMs` was therefore told, by the platform's own
+upgrade prescription, that a surface exists where `tsc` now reports TS2724/TS2305.
+The message now names exactly the three surfaces that still carry the policy:
+
+```
+… the retry policy now has ONE spelling for its base delay across every surface
+that carries it: `job.retryPolicy`, a `try_catch` node's `retry` and
+`flow.errorHandling`. Rename the key to `backoffMs`; …
+```
+
+The prescription itself is unchanged — same rename, same value semantics, same
+`os migrate meta --from 16` pointer — and a new pin in
+`shared/retry-policy.test.ts` now asserts the enumeration in both directions
+(every live surface named, no retired one named) so the string cannot drift wide
+again unobserved.
+
+**No acceptance change.** `retryPolicyShape()` and `RetryPolicySchema` keep their
+exact key sets, bounds and defaults; `retryDelayMs` is still rejected, still with
+a prescription. Everything else in this change is comment text: the module TSDoc
+in `shared/retry-policy.zod.ts` (the four-surfaces arithmetic, the strict-surface
+counts, and the paragraph that claimed a `maxAttempts` tombstone carries the ETL
+migration — it does not; the tombstone went with the shape that carried it, and
+`RETIRED_DEFS_BY_MAJOR` plus the D3 `etl-pipeline-layer-retired` entry are the
+declaration) and the matching stanza in `conversions/registry.ts`.

.changeset/share-links-denial-status-passthrough.md

@@ -0,0 +1,59 @@
+---
+"@objectstack/runtime": minor
+---
+
+fix(runtime): a `/share-links` permission denial answers 403, not 500 (#6649)
+
+The dispatcher's `/share-links` domain ended in a hand-written catch that read
+one status channel:
+
+```
+return sendErr(err?.status ?? 500, err?.code ?? 'INTERNAL', err?.message ?? '…');
+```
+
+Every refusal `ShareLinkService` raises itself carries `status` (its `makeError`
+sets `status` + `code`), which is why the 403 `FORBIDDEN` and 422
+`SHARING_NOT_ENABLED` answers were always correct. But the refusals that come
+out of the **security middleware** do not come from that service. Creating a
+link performs a visibility read — `svc.createLink` calls
+`engine.find(object, { context })` — and when the caller's permission sets grant
+no `allowRead` on the object, the CRUD gate throws
+`PermissionDeniedError { code = 'PERMISSION_DENIED'; statusCode = 403 }`, a class
+with **no `status` field at all** (`plugin-security/src/errors.ts`; runtime's own
+mirror in `security/resolve-execution-context.ts` has the same shape).
+`ShareLinkService` does not catch it, so it reached the domain catch, `err?.status`
+was `undefined`, and a 403-class refusal left as **HTTP 500** while `error.code`
+faithfully read `PERMISSION_DENIED`.
+
+That envelope contradicted itself, and the contradiction is load-bearing on the
+client: 5xx is retryable to many SDKs and browser clients, so a permanent
+authorization answer was being retried, and a caller branching on the status saw
+"the server is broken" where the truth was "you may not read this record". It is
+reproducible on either tenancy posture, and — because `registerShareLinkRoutes:
+false` makes this domain the ONLY share-link surface on cloud's per-environment
+kernels — it is the primary surface there, not a fallback one.
+
+The catch now exits through `deps.errorFromThrown`, the dispatcher's shared
+thrown-error mapper that `/meta`, `/actions` and `/mcp` already use. It reads
+`status` **or** `statusCode`, and it carries a thrown error's structured
+`issues` / `fields` details through instead of collapsing them to a message.
+Reaching for the shared mapper — rather than widening the hand-written chain to
+`err?.status ?? err?.statusCode ?? 500` — is the part that stops this exit
+re-diverging: a second hand-written copy is how the two drifted apart in the
+first place.
+
+Two wire-visible consequences, both corrections:
+
+- A permission denial on `POST` / `GET` / `DELETE /share-links` answers **403
+  `PERMISSION_DENIED`** where it answered 500 `PERMISSION_DENIED`. Clients
+  treating 5xx as retryable stop retrying a permanent refusal.
+- A throw carrying neither status channel nor a code answers **500
+  `INTERNAL_ERROR`** where it answered 500 `INTERNAL`. `'INTERNAL'` was never
+  registered for `@objectstack/runtime` in `ERROR_CODE_LEDGER` (only `rest`,
+  `service-storage`, `service-i18n` and `plugin-sharing` register it, and the
+  ledger's per-package rows are provenance) — so this domain was emitting a code
+  it had not registered, and the required field is now filled by the catalogued
+  derivation every other dispatcher exit uses (ADR-0112).
+
+Refusals that already carried `status` are untouched: the mapper reads that
+channel on the same first branch the old chain did.