Merge remote-tracking branch 'origin/main' into claude/issue-15832-claim-probe-before-mutate

Author: claude

.changeset/compose-merge-refuses-object-collections.md

@@ -0,0 +1,65 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec)!: `composeStacks` `objectConflict: 'merge'` refuses object pairs whose object-level collections cannot be merged (#14848)
+
+<!-- adr-0087: not-required (no-migration-prescription) Nothing authorable is renamed, retired or re-typed: every object key, every `composeStacks` option and the `ConflictStrategySchema` enum (`'error' | 'override' | 'merge'`) parse exactly as before, so `objectstack migrate meta` has nothing to rewrite. What narrows is the ACCEPT SET of one option value at composition time — two stacks whose same-name objects both declare an object-level collection with different values are now refused under `'merge'` where they used to compose with the earlier stack's entries silently dropped. The refusal text carries the whole prescription (declare the collection in one stack, make the declarations identical, or use `'override'`), and the repository measures zero non-test call sites passing `objectConflict` at all (see below), so there is no stored artifact and no authored file for a migration to act on. -->
+
+**BREAKING** accept-set narrowing on `composeStacks({ objectConflict: 'merge' })`
+— shipped as `minor` under the repo's launch-window convention for breaking
+changes. Maintainer ruling 2026-09-04 on #14848 (director decision batch #38
+item 5, verbatim 「同意」): option 4, `'merge'` **refuses** what it cannot merge
+instead of dropping it.
+
+**What changed.** `'merge'` was implemented as
+`{ ...existing, ...obj, fields: { ...existing.fields, ...obj.fields } }`:
+`fields` was the only key merged, and every other key the later object carried
+— `actions`, `indexes`, `listViews`, `validations`, … — replaced the earlier
+package's value wholesale, with nothing at compose, build or boot saying so.
+Two packages each embedding an action on one shared object composed to the
+later package's array alone; the earlier package's action was gone.
+
+Now, when both objects declare an object-level **collection** other than
+`fields` with different values, `composeStacks` throws — the refusal shape
+`'error'` uses — naming the object, the colliding collection and both stacks
+by manifest id:
+
+```
+composeStacks conflict: object 'shared' is defined in multiple stacks and its 'actions' is declared with different values by 'com.example.a' (stack #0) and 'com.example.b' (stack #1).
+objectConflict: 'merge' shallow-merges 'fields' only. Any other object-level collection (indexes, fieldGroups, requiredPermissions, validations, activityMilestones, highlightFields, listViews, searchableFields, actions) is not merged: the later declaration would replace the earlier one wholesale, silently dropping every entry 'com.example.a' (stack #0) wrote.
+Fix: declare 'actions' on 'shared' in exactly one of the two stacks, make the two declarations identical, or use { objectConflict: 'override' } to hand the whole object to the later stack.
+```
+
+The refusal set is **derived from `ObjectSchema`'s shape** — every key whose
+declared type is an array or a record (through optional/default wrappers and
+into a union's members), except `fields` — not hand-listed, so a collection key
+added to the object schema joins the refusal without an edit to the composer.
+Today that set is `actions`, `activityMilestones`, `fieldGroups`,
+`highlightFields`, `indexes`, `listViews`, `requiredPermissions`,
+`searchableFields`, `validations`.
+
+**What did not change.**
+
+- `fields` keeps its documented shallow merge (later fields win, earlier
+  fields kept).
+- **Identical** declarations on both sides pass through and are carried once
+  — the same reading `composeStacks` already gives identical top-level values
+  — so two built stacks that each bind one standalone action to the same
+  object (identical copies) still reach the cross-stack action-key check
+  (#14662) and are refused there, by name, as before.
+- A scalar or fixed-shape config object the later object declares (`label`,
+  `sharingModel`, `enable`, `access`, …) still replaces the earlier one: the
+  ruling narrows collections only, and the docblock now says so.
+- The default `'error'` and `'override'` are untouched, message for message.
+- An explicit `undefined` on the later object is read as no declaration — it
+  neither counts as a differing value nor erases what the earlier stack
+  declared (the bare spread used to let it).
+
+**Who is affected.** Measured on `origin/main` @ `53cbad9f7`: **zero** non-test
+call sites in `packages/**`, `examples/**`, `apps/**` pass `objectConflict` at
+all — every real caller takes the default `'error'`. An external author who
+opted into `'merge'` and relied on the later package's collection winning
+silently now gets the refusal above; the fix is the one it names.
+
+The `ConflictStrategySchema` docblock for `'merge'` states the rule.

.changeset/rest-data-doors-compiled-against-protocol.md

@@ -0,0 +1,11 @@
+---
+"@objectstack/rest": patch
+---
+
+The REST data doors' protocol requests are compiled against the declared contract again, so a field added to a data request schema reddens the build instead of going silently unsent.
+
+No runtime behaviour changes — every door assembles and forwards exactly the object it did before. What changes is what the compiler is allowed to see. `packages/rest/src/rest-server.ts` dispatched to the protocol through two erasing forms: `p.deleteData({ … } as any)` on the argument, and the stronger `(p as any).updateData({ … })` on the protocol object itself, which erases the check on *every* member — a misspelled method name would not have errored. Across the file that was 22 dispatch sites spanning `findData` / `getData` / `createData` / `updateData` / `deleteData`, their `*Many` and batch siblings, and `getUiView`.
+
+The casts were load-bearing rather than lazy: these call sites pass `environmentId` and `context`, and neither is a member of any data request schema. Neither should become one. `environmentId` is the transport routing key that selects the kernel *before* the protocol call and is already ruled out of the request shape; `context` is the server-derived execution context, and a caller-supplied `context` is a privilege escalation the ingress deletes unconditionally — putting it in the published request schema would re-open that door. Both are now declared on a typed envelope alongside the request type, so they stay server-side *and* compiled, and every other member of every literal is checked against the spec.
+
+One slot stays deliberately untyped and is now named rather than diffuse: `findData`'s `query` accepts both the declared AST and an undeclared wire dialect (`$top`, `$orderby`, `filters`, …) that the protocol normalizer folds. Three server-built literals speak that dialect; the erasure there is confined to the query slot alone, and the declared-versus-shipped mismatch is filed as its own question.

.changeset/sys-email-highlight-fields-to-addresses.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/platform-objects": patch
+---
+
+`sys_email.highlightFields` names the recipient column that exists, so the platform's own email log stops rendering one column short (#15629)
+
+The list read `['subject', 'to', 'status', 'sent_at']`. Three of those four resolve; `to` does not — `sys_email`'s recipient column is `to_addresses`. It now reads `['subject', 'to_addresses', 'status', 'sent_at']`, and nothing else about the object moved.
+
+`highlightFields` is the object's ordered "most important fields" pointer (ADR-0085): it drives the default list columns, record cards, previews and the detail highlight strip. Every consumer **silently skips** an entry it cannot resolve — nothing throws and nothing logs — so each of those surfaces rendered one field short, and the field missing from the platform's own outbound-email log was the recipient.
+
+There was a second, louder consequence that nobody could reach by accident. Since `object-field-ref-unknown` crossed onto the object write door (#15254), this body could not be republished through `PUT /api/v1/meta/object` or a package publish: the door answers `422 INVALID_METADATA`. `sys_email` reaches the runtime as a code-shipped registry object instead — `EmailServicePlugin` hands it to the manifest service, a path that runs no authoring gate — so boot was never affected and no deployment was failing. It was a trap laid for whoever next edited the object through a door rather than the file.
+
+`sys-email.highlight-fields-resolve.test.ts` pins it through that real door rather than by comparing the array against `Object.keys(fields)`: it runs `runRuntimeAuthoringRules({ type: 'object' })` over the shipped declaration with the audit module's other objects as resolution context, and a control case restores the old entry and requires the same call to refuse it — so a green result means the door read this object and accepted it, never that nothing looked.

.changeset/value-shape-detail-prefers-unrecognized-keys.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/objectql": patch
+---
+
+`os migrate value-shapes` now prescribes the key rename on a legacy `{latitude, longitude}` location, instead of reporting the missing-pair type error.
+
+A value-shape rejection was read positionally — `parse.error.issues[0]` — at both places the value-shape detail is produced: the write path's warn-first / strict branch, and the exported `valueShapeViolation` the scan imports. zod reports per-member issues before the object-level `unrecognized_keys` one, so on a value whose keys were **renamed** the actionable message sorts last and was discarded. A `location` stored as `{latitude, longitude}` — the exact legacy shape the scan's own header names as one it exists to find — reported `Invalid input: expected number, received undefined`, leaving an operator to derive a rename that edit distance cannot reach (`latitude` -> `lat`), while `LocationValueSchema` had built the prescription and thrown it away.
+
+Both readers now prefer the undeclared-key issue when the rejection carries one, through a single shared helper — two readings of the same rejection drifting by one clause is how one path prescribes the rename and the other does not. The affected strings are the `os migrate value-shapes` finding `detail`, the warn-first `[value-shape]` log line, and the `invalid_value_shape` error's `detail` under strict enforcement.
+
+⛔ No verdict moves. The same values are flagged, the same writes are rejected or admitted, and the deployment gate opens on exactly the same evidence — only the operator-facing text changes.
+
+Scoped by measurement rather than by assumption: of the sixteen types these readers cover, only `location` and `address` are backed by a key-closed object schema, so only they can emit `unrecognized_keys` at all — for the other fourteen the preference cannot change a single character. Both classes it does reach curate the alias map that makes the undeclared key the more actionable half. The defect reaches `address` as well as `location`: every address member being optional rules out a *missing*-member type error, but not a *wrong-typed* declared one, which still sorts ahead of the undeclared-key issue.

.github/workflows/docker-publish.yml

@@ -97,8 +97,29 @@ jobs:
         # `os --version` proves the CLI resolved, installed, and runs on the
         # pushed image; a boot test needs an artifact + DB and belongs to the
         # examples/e2e suites, not here.
+        #
+        # The `require()` line proves the SQL drivers are actually IN the built
+        # image. `check:docs-image-tag` cannot see that: it compares the
+        # Dockerfile install line against README.md's published table, and both
+        # would still agree if the drivers vanished from the image. The class
+        # has already cost a boot once -- docker/Dockerfile records that a tree
+        # without `pg` "died at boot on `Cannot find module 'pg'`", which is why
+        # the install line exists. `require()` needs no artifact and no
+        # database, so it stays on the right side of the same line drawn above.
+        #
+        # `-w` is load-bearing, not incidental. `npm install -g` puts the
+        # drivers in /usr/local/lib/node_modules, which is NOT on `require()`'s
+        # search path from this image's WORKDIR (/srv/app): node's global
+        # folders are $PREFIX/lib/node, and the node:22-slim base sets no
+        # NODE_PATH. Run from /srv/app the probe fails on a CORRECT image, so
+        # it would be a constant red rather than a check. Resolving from inside
+        # the global tree is also how the real boot path resolves them --
+        # driver-sql lives there too. Do not "simplify" this to a bare
+        # `docker run`; verified in both directions before it landed.
         env:
           VERSION: ${{ steps.version.outputs.version }}
         run: |
           docker pull "$IMAGE:$VERSION"
           docker run --rm "$IMAGE:$VERSION" os --version
+          docker run --rm -w /usr/local/lib/node_modules "$IMAGE:$VERSION" \
+            node -e "require('pg'); require('mysql2')"

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:1565`, `:1594`), and neither
+cannot set it (`packages/rest/src/rest-server.ts:1651`, `:1680`), 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:250` |
 | 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:1597` |
+| 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:1683` |
 
 ### 2. Write pipeline and data integrity
 
@@ -158,7 +158,7 @@ The largest single consumer — **17 of the 105 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:5145`, `:6571`, `:6819`, `:7250`, `:7443` |
+| 50 | `manage_metadata` bypassed on metadata writes | runtime, rest | Get: schema writes without the capability | `domains/meta.ts:471`, `:874`, `rest-server.ts:5231`, `:6657`, `:6905`, `:7336`, `:7529` |
 | 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:535`, `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:1590` (#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:1565`, `:1594`; `domains/actions.ts:414` |
+| "A client can request it" | **No.** Never settable from inbound HTTP or from an action body | `rest-server.ts:1651`, `:1680`; `domains/actions.ts:414` |
 
 ---