Merge remote-tracking branch 'origin/main' into claude/issue-25234-pr2

Author: claude

.changeset/25233-external-org-role.md

@@ -0,0 +1,26 @@
+---
+'@objectstack/spec': minor
+'@objectstack/core': minor
+'@objectstack/plugin-security': minor
+'@objectstack/plugin-auth': minor
+'@objectstack/platform-objects': minor
+---
+
+feat: an `external` organization role for portal users, who read their own identity rows and reach data only through explicit grants
+
+Clause-②: yes (widening)
+Metadata-protocol: added
+
+A supplier's or a customer's portal user can now be added to an organization with the `external` role. It is a member of the organization (it has a `sys_member` row) but a separate population: before this change such a user had to be a plain `member`, and the member baseline's fellow-member scope let it read every employee and every other supplier's users through `GET /data/sys_user`.
+
+- **`@objectstack/spec`:** `MEMBERSHIP_ROLE_EXTERNAL` (`'external'`) joins the closed membership-role vocabulary, with an `External` option. It projects to the new reserved identity `BUILTIN_IDENTITY_ORG_EXTERNAL` (`'org_external'`), and its invitation grant row is `'any'`, because it confers less than `member`.
+- **`@objectstack/core`:** the authorization resolver reads the stamp from `sys_member.role` in the active organization. An `external` holder holds `org_external` and not the `everyone` anchor, so the deployment's defaults bound there (`member_default`, an app's `isDefault` set, accepted package defaults) do not reach it. The stamp is per organization, and with no active organization an external membership withholds the anchor.
+- **`@objectstack/plugin-security`:** a new shipped set, `external_default`, is bound by the `org_external` position. It carries `member_default`'s own-row self-service grants without the fellow-member directory scope, plus the holder's own `sys_member` row. The plugin's additive baseline is swapped for it on an external context.
+- **`@objectstack/plugin-auth`:**
+  - better-auth registers `external` beside owner/admin/member, with no organization statement.
+  - A role list carrying `external` with another role is refused at write on `sys_member` and `sys_invitation` (`400 VALIDATION_FAILED`, `invalid_value` on `role`).
+  - An external is never placed in the organization's business units. A business-unit membership, a position anchored at one of its units, an invitation conferring `external` with a `business_unit_id`, and a change to `external` while a placement stands are all refused. An organization-wide position or a permission set is how an external gets access.
+  - `GET /organization/list-members` and `GET /organization/get-full-organization` answer an external caller its own member row and the invitations addressed to its own email only.
+- **`@objectstack/platform-objects`:** the `External` option label on the membership role pickers, translated.
+
+`org_external` is a reserved name from this release on, so a position can no longer be named `org_external`.

.changeset/25501-approval-timeline-step-label.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/plugin-approvals': patch
+---
+
+fix: the approval request page's Timeline shows each action's step by its label, not the node's machine id
+
+Clause-②: no
+Metadata-protocol: none
+
+The Timeline tab of the `sys_approval_request` record page lists the request's `sys_approval_action` rows. Its step column asked for `step_name`, which holds the Approval node's id (for example `dual_signoff`), so every row showed that id. The column is now `step_label`, the step's label that the service writes on every row and the boot backfill fills on older rows. The strip's step chip (`current_step_label`) and the object's own lists already show this label.

.changeset/25502-ai-reset-action-translation.md

@@ -0,0 +1,12 @@
+---
+'@objectstack/service-settings': patch
+---
+
+fix: Setup → AI's "Reset to environment defaults" button is now translated in zh-CN, ja-JP and es-ES
+
+Clause-②: no
+Metadata-protocol: none
+
+The `ai` settings manifest declares an `action_button` with id `reset`, but no locale bundle carried `settings.ai.actions.reset.label`, so the button rendered in English beside its translated siblings. The bundles now carry it (en, zh-CN, ja-JP, es-ES).
+
+The settings translation coverage test now reads every manifest's `action_button` labels: each shipped non-English locale must carry `settings.<namespace>.actions.<id>.label` for every action button, and no bundle may carry action copy for a button no manifest declares.

content/docs/permissions/authentication.mdx

@@ -837,8 +837,15 @@ new AuthPlugin({
 
 `sys_member.role` is better-auth's own column and the one place ObjectStack
 keeps that vocabulary (ADR-0090 D3's single boundary exception). It holds
-exactly four values — `owner`, `admin`, `delegated_admin`, `member` — and your
-stack cannot add to them.
+exactly five values — `owner`, `admin`, `delegated_admin`, `member`, `external` — and
+your stack cannot add to them.
+
+`external` is for a portal user (a supplier's or a customer's person) who joins
+the organization without joining its staff. It is held alone, never beside
+another tier. Its holder reads only its own identity rows, does not receive the
+member defaults (`member_default` or an app's `isDefault` set), is never placed
+in a business unit, and reaches application data only through the positions and
+permission sets granted to it explicitly.
 
 That is deliberate (ADR-0108). A membership tier answers *what is your standing
 in this organization*, which decides what you can **reach**: `delegated_admin`,

content/docs/permissions/positions.mdx

@@ -19,7 +19,7 @@ which sets*.
 > **permission set** = capability, **position** = distribution,
 > **business unit** = hierarchy. The single exception is better-auth's
 > internal `sys_member.role` — the org-membership tier, a **closed** list of
-> `owner`, `admin`, `delegated_admin`, `member` and nothing else (ADR-0108). A
+> `owner`, `admin`, `delegated_admin`, `member`, `external` and nothing else (ADR-0108). A
 > tier decides what you can *reach*; a position decides what you may *do*. To
 > invite someone straight into a position, use the invitation's `positions`
 > placement, not its membership tier — see

content/docs/permissions/system-context.mdx

@@ -108,7 +108,7 @@ that silently does not happen.
 | 7 | Write bypass = `true`, effective write scope = `org` | plugin-security | Get: widest write scope without holding any capability | `packages/plugins/plugin-security/src/security-plugin.ts#start` |
 | 8 | Metadata-plane schema masking exempt (ADR-0106 D4) | metadata-core | Get: unmasked object schema. Note: the exemption is a **caller** property — it short-circuits before the security service is consulted | `packages/metadata-core/src/object-schema-fls.ts#isObjectSchemaMaskExempt` |
 | 8b | Authoring-trail reads admitted | rest, runtime | Get: a metadata item's version history, audit rows and stored-version diff (`GET /meta/:type/:name/history`, `/audit`, `/diff`) without `studio.access` or `manage_metadata`, and a package's commit timeline (`GET /packages/:id/commits`) without `studio.access`. Note: narrower than the schema-mask exemption the draft switches ask (`isObjectSchemaMaskExempt`): neither door admits `setup.access`, which organization admins hold | `packages/rest/src/rest-server.ts#mayReadAuthoringTrail`, `packages/runtime/src/domains/packages.ts#requireCommitTrailReadCapability` |
-| 9 | `explain()` may target a principal other than the caller | plugin-security | Get: no `manage_users` / delegated-admin check | `packages/plugins/plugin-security/src/security-plugin.ts#explainAccessForCaller` |
+| 9 | `explain()` may target a principal other than the caller | plugin-security | Get: no `manage_users` / delegated-admin check | `packages/plugins/plugin-security/src/security-plugin-explain-access.ts#explainAccessForCaller` |
 | 9b | The master-detail write check the `security` service serves (`checkControlledByParentWrite`, ADR-0055) answers `allow` | plugin-security | Get: `allow` for any record, with no master judged — the write path's own first exit, so a gate composing it admits exactly what the record's own system-context update would. Lose: nothing a caller reaches today: its two consumers, the `sys_attachment` and `sys_comment` parent gates, return before they ask for a system session | `packages/plugins/plugin-security/src/security-plugin-cbp-write-gate.ts#checkControlledByParentWrite` |
 | 10 | Anonymous-deny treats the caller as authenticated | core | Get: passes the 401 seam with no `userId` | `packages/core/src/security/anonymous-deny.ts#shouldDenyAnonymous` |
 | 12 | Session-resolution middleware skipped | plugin-auth | Get: no session lookup attempted | `packages/plugins/plugin-auth/src/auth-plugin.ts#start` |

content/docs/references/identity/organization.mdx

@@ -38,7 +38,7 @@ const result = InvitationSchema.parse(data);
 | **id** | `string` | ✅ | Unique invitation identifier |
 | **organizationId** | `string` | ✅ | Organization ID |
 | **email** | `string` | ✅ | Invitee email address |
-| **role** | `string` | ✅ | Role to assign upon acceptance (owner, admin, delegated_admin, member — ADR-0108 closed vocabulary) |
+| **role** | `string` | ✅ | Role to assign upon acceptance (owner, admin, delegated_admin, member, external — ADR-0108 closed vocabulary) |
 | **status** | `Enum<'pending' \| 'accepted' \| 'rejected' \| 'expired' \| 'canceled'>` | optional (default: `"pending"`) | Invitation status |
 | **expiresAt** | `string` | ✅ | Invitation expiry timestamp |
 | **inviterId** | `string` | ✅ | User ID of the inviter |
@@ -70,7 +70,7 @@ const result = InvitationSchema.parse(data);
 | **id** | `string` | ✅ | Unique member identifier |
 | **organizationId** | `string` | ✅ | Organization ID |
 | **userId** | `string` | ✅ | User ID |
-| **role** | `string` | ✅ | Member role (owner, admin, delegated_admin, member — ADR-0108 closed vocabulary) |
+| **role** | `string` | ✅ | Member role (owner, admin, delegated_admin, member, external — ADR-0108 closed vocabulary) |
 | **createdAt** | `string` | ✅ | Member creation timestamp |
 | **updatedAt** | `string` | optional | Last update timestamp (no such column on sys_member; absent on the wire) |
 

examples/app-showcase/src/automation/flows/index.ts

@@ -1747,13 +1747,37 @@ export const InquiryPurgeFlow = defineFlow({
  * pattern (钉钉/Salesforce style) that needs no parallel branches. Set
  * `minApprovals` > 1 for "two from each group"; use `behavior: 'quorum'` +
  * `minApprovals` for M-of-N collective sign-off.
+ *
+ * **The decision is written back onto the report** — an explicit
+ * `update_record` on each outcome branch: approve → `status: 'approved'`,
+ * reject → `status: 'draft'` (back to the submitter, who can rework and
+ * resubmit — the same revert-on-reject {@link InvoiceDualSignoffFlow} does).
+ * Without these two nodes both outcomes were bare `end`s, so an expense report
+ * both groups had approved kept reading "Submitted" forever.
+ *
+ * Why not the approval node's `approvalStatusField` mirror instead: the mirror
+ * writes the REQUEST's status vocabulary verbatim (`pending` on open,
+ * `approved` / `rejected` on decide, `recalled`, `returned`), has no value
+ * mapping, and writes only values the target field declares among its options
+ * (anything else is skipped with a warn). `status` here is the report's own
+ * lifecycle select (`draft` / `submitted` / `approved` / `reimbursed`) — it
+ * declares neither `pending` nor `rejected`, so a mirror onto it would warn on
+ * every submit and leave a REJECTED report reading "Submitted", the very
+ * defect being fixed. The spec also advises a mirror target be readonly, and
+ * this one is the field the submitter edits. A business-lifecycle field
+ * driven by the decision is what `update_record` per branch is for.
+ *
+ * `runAs: 'system'` for the same reason as the invoice flow: the write-back is
+ * an outcome of the approval process, not an act of the submitter, so it must
+ * land whatever the submitter's edit rights on a submitted report are.
  */
 export const ExpenseSignoffFlow = defineFlow({
   name: 'showcase_expense_signoff',
   label: 'Expense Report Sign-off',
   description: 'Manager + finance per-group sign-off (会签) on a submitted expense report (#3266).',
   type: 'autolaunched',
   status: 'active',
+  runAs: 'system',
   nodes: [
     {
       id: 'start',
@@ -1779,13 +1803,35 @@ export const ExpenseSignoffFlow = defineFlow({
         lockRecord: true,
       },
     },
+    {
+      id: 'mark_approved',
+      type: 'update_record',
+      label: 'Mark Report Approved',
+      config: {
+        objectName: 'showcase_expense_report',
+        filter: { id: { dialect: 'cel', source: 'record.id' } },
+        fields: { status: 'approved' },
+      },
+    },
+    {
+      id: 'return_to_draft',
+      type: 'update_record',
+      label: 'Return Report to Draft',
+      config: {
+        objectName: 'showcase_expense_report',
+        filter: { id: { dialect: 'cel', source: 'record.id' } },
+        fields: { status: 'draft' },
+      },
+    },
     { id: 'approved', type: 'end', label: 'Approved' },
     { id: 'rejected', type: 'end', label: 'Rejected' },
   ],
   edges: [
     { id: 'e1', source: 'start', target: 'dual_signoff' },
-    { id: 'e2', source: 'dual_signoff', target: 'approved', label: 'approve' },
-    { id: 'e3', source: 'dual_signoff', target: 'rejected', label: 'reject' },
+    { id: 'e2', source: 'dual_signoff', target: 'mark_approved', label: 'approve' },
+    { id: 'e3', source: 'dual_signoff', target: 'return_to_draft', label: 'reject' },
+    { id: 'e4', source: 'mark_approved', target: 'approved' },
+    { id: 'e5', source: 'return_to_draft', target: 'rejected' },
   ],
 });
 
@@ -1797,13 +1843,19 @@ export const ExpenseSignoffFlow = defineFlow({
  * `minApprovals` clamps to the approver count so a misconfiguration can never
  * deadlock. Where `per_group` requires one from EACH group, `quorum` counts a
  * flat tally across all approvers.
+ *
+ * The decision is written back onto the report exactly as in
+ * {@link ExpenseSignoffFlow} (approve → `approved`, reject → `draft`), and for
+ * the same reasons — see that flow's docblock for why this is an
+ * `update_record` per branch and not an `approvalStatusField` mirror.
  */
 export const CommitteeQuorumFlow = defineFlow({
   name: 'showcase_committee_quorum',
   label: 'High-Value Expense — Committee Quorum',
   description: 'Any 2-of-3 committee members approve a high-value expense report (#3266 quorum / M-of-N).',
   type: 'autolaunched',
   status: 'active',
+  runAs: 'system',
   nodes: [
     {
       id: 'start',
@@ -1830,13 +1882,35 @@ export const CommitteeQuorumFlow = defineFlow({
         lockRecord: true,
       },
     },
+    {
+      id: 'mark_approved',
+      type: 'update_record',
+      label: 'Mark Report Approved',
+      config: {
+        objectName: 'showcase_expense_report',
+        filter: { id: { dialect: 'cel', source: 'record.id' } },
+        fields: { status: 'approved' },
+      },
+    },
+    {
+      id: 'return_to_draft',
+      type: 'update_record',
+      label: 'Return Report to Draft',
+      config: {
+        objectName: 'showcase_expense_report',
+        filter: { id: { dialect: 'cel', source: 'record.id' } },
+        fields: { status: 'draft' },
+      },
+    },
     { id: 'approved', type: 'end', label: 'Approved' },
     { id: 'rejected', type: 'end', label: 'Rejected' },
   ],
   edges: [
     { id: 'e1', source: 'start', target: 'committee' },
-    { id: 'e2', source: 'committee', target: 'approved', label: 'approve' },
-    { id: 'e3', source: 'committee', target: 'rejected', label: 'reject' },
+    { id: 'e2', source: 'committee', target: 'mark_approved', label: 'approve' },
+    { id: 'e3', source: 'committee', target: 'return_to_draft', label: 'reject' },
+    { id: 'e4', source: 'mark_approved', target: 'approved' },
+    { id: 'e5', source: 'return_to_draft', target: 'rejected' },
   ],
 });