Skip to content

Commit 417089c

Browse files
committed
chore: regenerate the error reference, register the new registrar file, changeset and admin guide
Claude-Session: https://claude.ai/code/session_01Utp6CZavYYLh5k5r6jhgCF Co-authored-by: Claude <noreply@anthropic.com>
1 parent 09bab33 commit 417089c

6 files changed

Lines changed: 63 additions & 6 deletions

File tree

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
'@objectstack/spec': patch
3+
'@objectstack/core': patch
4+
'@objectstack/objectql': patch
5+
'@objectstack/rest': patch
6+
'@objectstack/client': patch
7+
---
8+
9+
feat(objectql,rest)!: a new assignment to a banned user is refused, and a banned user's records can be counted and handed over in bulk (#30205)
10+
11+
Clause-②: no (narrowing) — a non-system create or update that sets a user field (the owner field, a `user` field, or a `lookup` to `sys_user`) to a user whose ban is in force is refused `400 VALIDATION_FAILED` with the field code `reference_user_banned`, a write that answered `201` / `200` before. A value the row already stores is not judged, so a record that already holds the banned user stays editable. The two new routes and SDK methods are additions.
12+
Metadata-protocol: none
13+
Skills-docs: no move in `skills/**`, which teaches no user-assignment verdict; `content/docs/permissions/administrator-guide.mdx` gains "Handing over a banned user's work" and its offboarding quick path points at it.
14+
15+
<!-- adr-0087: not-required (no-migration-prescription) No key of any authorable schema is added, removed, renamed or re-shaped. What moves is the answer a data write gets when it names a banned user, and a record that already holds one is not judged, so nothing at rest needs rewriting. The new field code is a member of the response vocabulary FieldErrorCode, not of anything an author writes. -->
16+
17+
**BREAKING** accept-set narrowing at every data write door (`POST` / `PATCH /api/v1/data/OBJECT`, batch, import, and a flow's elevated record write, which keeps the reference check): banning a user signs them out, but the records they own and are assigned stay where they were, and new work could still be handed to them.
18+
19+
- **Before.** The Console's person picker hid a banned user, but `POST /api/v1/data/OBJECT` with `assignee` set to that user answered `201`, so new work landed on someone who cannot sign in.
20+
- **Now.** The write-time reference check also asks whether a referenced user's ban is in force (`banned` is true and `ban_expires` is empty or still ahead) and refuses such a value with `reference_user_banned`, beside `reference_not_found`. It is read the way the existence probe reads, so a caller who cannot read the user object is refused the same way. A ban whose expiry has passed is not in force.
21+
- **Unchanged.** A value every row of the write already stores (an edit form carries the whole record back), a system write the reference check already exempts (seed, install, restore), and a missing user (still `reference_not_found`).
22+
- **New: the count.** `GET /api/v1/security/users/ID/assigned-work` (`client.security.assignedWork.count`) answers, per object and user field, how many records hold the user, counted under the caller's own context. Platform tables (`sys_*`), `managedBy` objects and `readonly` / `system` fields such as `created_by` are not counted; objects the caller cannot read are listed in `unreadable`; at most 200 fields are counted (`truncated`).
23+
- **New: the hand-over.** `POST /api/v1/security/users/ID/assigned-work/transfer` (`client.security.assignedWork.transfer`) with `{ toUserId, objects? }` moves up to 500 records per call to an active user, each as an ordinary update under the caller's context, and answers per field what moved and what failed, plus how many remain. A banned, unknown or identical `toUserId` is refused before any write. Multi-valued user fields are counted but not transferred. Neither route touches the ban.
24+
- **`@objectstack/spec`.** `FieldErrorCode` gains `reference_user_banned`, with its message in `en`, `zh-CN`, `ja-JP` and `es-ES`.
25+
26+
**FROM → TO.** A write that sets `assignee: 'BANNED_USER_ID'` → set it to an active user, or hand the banned user's records over with the transfer route first. An integration that reassigns work after a ban → call the transfer route, then repeat while `remaining` is above 0.

‎content/docs/permissions/administrator-guide.mdx‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,26 @@ through this membership, so don't skip it.
9797
Endpoint-level detail (payloads, password policies, phone-only accounts):
9898
[Authentication → Admin User Management](/docs/permissions/authentication#admin-user-management).
9999

100+
### Handing over a banned user's work
101+
102+
A ban does not move the records the person owns or is assigned. Two calls do,
103+
both run as you, so they count and change only what you could read and edit by
104+
hand:
105+
106+
- `GET /api/v1/security/users/USER_ID/assigned-work` answers, per object and
107+
user field (the owner field and every app user field such as an assignee),
108+
how many records hold the user. Objects you cannot read are listed in
109+
`unreadable`.
110+
- `POST /api/v1/security/users/USER_ID/assigned-work/transfer` with
111+
`{ "toUserId": "...", "objects": ["..."] }` (`objects` optional) moves up to
112+
500 records per call to an active user, each as an ordinary edit, so sharing,
113+
validation rules and hooks apply. It answers what moved, what failed and how
114+
many remain; call it again until `remaining` is 0.
115+
116+
The hand-over is optional and never delays the ban. Once a user is banned, a
117+
new record or edit that sets a user field to them is refused with the field
118+
code `reference_user_banned`; a record that already holds them stays editable.
119+
100120
## Step 3 — Assign positions
101121

102122
This is the daily 90%. An assignment is one row: **User Position**
@@ -180,7 +200,7 @@ Full model: [Permission Sets](/docs/permissions/permission-sets).
180200
| I need to… | Do this |
181201
|:--|:--|
182202
| Onboard a new employee | Invite/Create the user → Business Unit Member row → assign their position ([2](#step-2--add-people-users)→[3](#step-3--assign-positions)) |
183-
| Offboard someone | **Ban User** (blocks sign-in immediately) — then remove assignments at leisure |
203+
| Offboard someone | **Ban User** (blocks sign-in immediately) — then hand over their records ([below](#handing-over-a-banned-users-work)) and remove assignments at leisure |
184204
| "I can't sign in" | User record → is it banned? locked? **Unlock Account** or **Set Password** (temporary, must-change) |
185205
| "Why can't I see X?" | Studio → Access → **Explain access** for that user + object |
186206
| Someone changed departments | Update their Business Unit Member row; re-anchor their User Position rows |

‎content/docs/references/api/errors.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,7 +186,7 @@ const result = EnhancedApiErrorSchema.parse(data);
186186
| Property | Type | Required | Description |
187187
| :--- | :--- | :--- | :--- |
188188
| **field** | `string` | ✅ | Field path (supports dot notation) |
189-
| **code** | `Enum<'required' \| 'invalid_type' \| 'invalid_shape' \| 'unknown_field' \| 'invalid_boolean' \| 'invalid_number' \| 'invalid_date' \| 'invalid_time' \| 'invalid_email' \| … +21 more>` | ✅ | Which constraint the value violated (field-level catalog, ADR-0114) |
189+
| **code** | `Enum<'required' \| 'invalid_type' \| 'invalid_shape' \| 'unknown_field' \| 'invalid_boolean' \| 'invalid_number' \| 'invalid_date' \| 'invalid_time' \| 'invalid_email' \| … +22 more>` | ✅ | Which constraint the value violated (field-level catalog, ADR-0114) |
190190
| **message** | `string` | ✅ | Human-readable error message, rendered in the caller’s locale |
191191
| **label** | `string` | optional | Field display label in the caller’s locale |
192192
| **value** | `any` | optional | The invalid value that was provided |
@@ -220,6 +220,7 @@ const result = EnhancedApiErrorSchema.parse(data);
220220
* `invalid_value`
221221
* `reference_not_found`
222222
* `reference_ambiguous`
223+
* `reference_user_banned`
223224
* `rule_violation`
224225
* `json_schema_violation`
225226
* `invalid_initial_state`
@@ -258,6 +259,7 @@ const result = EnhancedApiErrorSchema.parse(data);
258259
* `invalid_value`
259260
* `reference_not_found`
260261
* `reference_ambiguous`
262+
* `reference_user_banned`
261263
* `rule_violation`
262264
* `json_schema_violation`
263265
* `invalid_initial_state`

‎packages/rest/src/rest-server-canonical-query-ast.test.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,10 @@ interface CensusEntry {
211211
* the record page's stream reads (the discussion, its reactions, the activity
212212
* and the attachments) go through one server-built slot (`readStream`), so the
213213
* module's floor is 2.
214+
*
215+
* [#30205] 6, unchanged: a user's assigned work (`user-work-routes.ts`) hands
216+
* the engine no `query:` slot of its own (the counts and reads are built in
217+
* `@objectstack/core`), so the new module's floor is 0.
214218
*/
215219
const REGISTRAR_QUERY_SLOT_FLOORS: Readonly<Record<RestServerRegistrarFile, number>> = {
216220
'rest-server.ts': 0,
@@ -233,6 +237,7 @@ const REGISTRAR_QUERY_SLOT_FLOORS: Readonly<Record<RestServerRegistrarFile, numb
233237
'meta-object-state-routes.ts': 0,
234238
'record-page-routes.ts': 2,
235239
'meta-app-bundle-routes.ts': 0,
240+
'user-work-routes.ts': 0,
236241
};
237242

238243
const CENSUS: CensusEntry[] = [

‎packages/rest/src/rest-server-docblock-position.test.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -250,6 +250,7 @@ const MOVED_FILE_FLOORS: Readonly<Record<Exclude<RestServerRegistrarFile, typeof
250250
'meta-object-state-routes.ts': 3,
251251
'record-page-routes.ts': 10,
252252
'meta-app-bundle-routes.ts': 15,
253+
'user-work-routes.ts': 6,
253254
};
254255
const MOVED_FILES: ReadonlyArray<{ file: string; minBlocks: number }> = REST_SERVER_REGISTRAR_FILES
255256
.filter((file): file is Exclude<RestServerRegistrarFile, typeof FILE> => file !== FILE)
@@ -307,8 +308,11 @@ describe('[#23050 slice 3] the registrar list this pin reads', () => {
307308
// relationship types, the read policy, the host interface, the reach
308309
// interface, six module-level helpers' blocks, the function's, and the
309310
// two inner helpers' inside it).
311+
// [#30205] 95 + 6 = 101: `user-work-routes.ts`, a new registrar, carries six
312+
// (the module header, the host interface, the closed parameter set, the body
313+
// keys, the function's, and the engine resolver's inside it).
310314
expect(Object.keys(MOVED_FILE_FLOORS).sort())
311315
.toEqual(REST_SERVER_REGISTRAR_FILES.filter((file) => file !== FILE).sort());
312-
expect(MOVED_FILES.reduce((n, { minBlocks }) => n + minBlocks, 0)).toBe(95);
316+
expect(MOVED_FILES.reduce((n, { minBlocks }) => n + minBlocks, 0)).toBe(101);
313317
});
314318
});

‎packages/rest/src/rest-server-registrar-files.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,9 @@ export const REST_SERVER_REGISTRAR_FILES = [
7575
// [#27627] `registerMetaAppBundleRoute`' body, the app metadata bundle. New, not a
7676
// moved slice, and a `/meta` group — see {@link REST_SERVER_META_ROUTE_FILES}.
7777
'meta-app-bundle-routes.ts',
78+
// [#30205] `registerUserWorkEndpoints`' body, a user's assigned work: the counts and
79+
// the hand-over. New, not a moved slice.
80+
'user-work-routes.ts',
7881
] as const;
7982

8083
/** One file on {@link REST_SERVER_REGISTRAR_FILES}. */
@@ -123,9 +126,6 @@ export const REST_SERVER_META_ROUTE_FILES: readonly RestServerRegistrarFile[] =
123126
// moved slice; like the per-item writes it goes through the inner method's per-item
124127
// registrar, handed over in its scope.
125128
'meta-app-bundle-routes.ts',
126-
// [#30205] A user's assigned work: the counts and the hand-over. New, not a moved
127-
// slice; it registers on the route manager itself, from a host literal.
128-
'user-work-routes.ts',
129129
];
130130

131131
/**

0 commit comments

Comments
 (0)