@sudoke/kernel 0.6.2 → 0.6.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +15 -19
- package/docs/domain-development-guide.md +251 -142
- package/docs/kernel-upgrade-guide.md +111 -84
- package/docs/surface-development-guide.md +184 -127
- package/docs/undo-scope-guide.md +99 -84
- package/package.json +1 -1
|
@@ -1,24 +1,33 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Surface development guide — UI pattern rules (admin screens · skeleton · tables)
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
Rules for the page skeleton and tables of admin CRUD·list screens (function management, client
|
|
4
|
+
management, …). Nothing here is domain-specific — a new app's surfaces start from this same bar.
|
|
5
5
|
|
|
6
|
-
## 0.
|
|
6
|
+
## 0. Contract — these 4 lines have no exceptions
|
|
7
7
|
|
|
8
|
-
1. **UI
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
8
|
+
1. **UI components are imported from `@/components/ui/*` only.** No raw `<button>` `<select>`
|
|
9
|
+
`<table>`, no hand-rolled modal `<div>`s.
|
|
10
|
+
2. **A missing component is never hand-built** — add it with `npx shadcn@latest add <name>`.
|
|
11
|
+
(Custom non-control widgets (matrix cells etc.) may be hand-built — with semantic tokens only for
|
|
12
|
+
color·type — R13·R12. When a raw element is truly required, mark the line with
|
|
13
|
+
`/* check:ui-allow: reason */`.)
|
|
14
|
+
3. **Looks·sizes·spacing follow the official shadcn docs** — this guide sets no numbers. A missing
|
|
15
|
+
component is added with `npx shadcn@latest add <name>`.
|
|
16
|
+
4. **A screen the planner specified starts from a one-page screen spec** (the planner's form) —
|
|
17
|
+
screens without a spec are the surface's discretion.
|
|
12
18
|
|
|
13
|
-
|
|
19
|
+
**Check**: `npm run check:ui` — the mechanical check of this contract. It must pass before you
|
|
20
|
+
commit (the same bar as "before you commit" below). The script lives in the shared package
|
|
21
|
+
**`@sudoke/dev-checks`** (`check-ui.mjs` — it scans `surface/main/src` outside `components/ui/`) —
|
|
22
|
+
copying·npm wiring follows domain guide §5-9.
|
|
14
23
|
|
|
15
|
-
## DO / DON'T —
|
|
24
|
+
## DO / DON'T — controls are standard components
|
|
16
25
|
|
|
17
26
|
```tsx
|
|
18
|
-
❌ <button className="h-6 px-2 text-xs"
|
|
19
|
-
✅ <Button size="sm"
|
|
27
|
+
❌ <button className="h-6 px-2 text-xs">Save</button>
|
|
28
|
+
✅ <Button size="sm">Save</Button>
|
|
20
29
|
|
|
21
|
-
❌ <button className="p-1 text-muted-foreground"><ChevronRight /></button> (
|
|
30
|
+
❌ <button className="p-1 text-muted-foreground"><ChevronRight /></button> (an icon toggle)
|
|
22
31
|
✅ <Button variant="ghost" size="icon"><ChevronRight /></Button>
|
|
23
32
|
|
|
24
33
|
❌ <select className="border rounded px-2">…</select>
|
|
@@ -27,139 +36,187 @@
|
|
|
27
36
|
❌ <table className="w-full"><thead>…</thead></table>
|
|
28
37
|
✅ <Table><TableHeader><TableRow><TableHead>…</TableHead></TableRow></TableHeader>…</Table>
|
|
29
38
|
|
|
30
|
-
❌ <div className="fixed inset-0 z-50 bg-black/50"
|
|
39
|
+
❌ <div className="fixed inset-0 z-50 bg-black/50">…a hand-rolled modal…</div>
|
|
31
40
|
✅ <Dialog open={open} onOpenChange={setOpen}><DialogContent>…</DialogContent></Dialog>
|
|
32
41
|
|
|
33
|
-
❌
|
|
42
|
+
❌ hand-assembling a missing component (toast·popover·tabs) out of divs
|
|
34
43
|
✅ npx shadcn@latest add popover → import { Popover } from '@/components/ui/popover'
|
|
35
44
|
```
|
|
36
45
|
|
|
37
|
-
###
|
|
46
|
+
### Style DO / DON'T
|
|
38
47
|
|
|
39
48
|
```tsx
|
|
40
|
-
❌ <Button size="sm" className="h-6 w-14">…</Button> (
|
|
41
|
-
✅ <Button size="sm">…</Button> (
|
|
49
|
+
❌ <Button size="sm" className="h-6 w-14">…</Button> (an arbitrary h-* — data-size wins, so don't write it)
|
|
50
|
+
✅ <Button size="sm">…</Button> (sizes come from the shadcn size variants only)
|
|
42
51
|
|
|
43
|
-
❌ <span className="text-red-600"
|
|
44
|
-
✅ <span className="text-destructive"
|
|
52
|
+
❌ <span className="text-red-600">Deleted</span> · className="bg-[#ff4d5e]"
|
|
53
|
+
✅ <span className="text-destructive">Deleted</span> (colors are semantic tokens only)
|
|
45
54
|
|
|
46
|
-
❌ <span className="text-13">…</span> (
|
|
47
|
-
✅ <span className="text-sm">…</span> (shadcn
|
|
55
|
+
❌ <span className="text-13">…</span> (a custom font token — twMerge mistakes it for a color)
|
|
56
|
+
✅ <span className="text-sm">…</span> (standard shadcn tokens)
|
|
48
57
|
|
|
49
|
-
❌ <div style="margin-top: 8px"> (
|
|
50
|
-
✅ <div className="mt-2"> (
|
|
58
|
+
❌ <div style="margin-top: 8px"> (a static style)
|
|
59
|
+
✅ <div className="mt-2"> (through classes)
|
|
51
60
|
```
|
|
52
61
|
|
|
53
|
-
##
|
|
54
|
-
|
|
55
|
-
### R1.
|
|
56
|
-
-
|
|
57
|
-
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
###
|
|
69
|
-
-
|
|
70
|
-
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
###
|
|
80
|
-
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
-
|
|
86
|
-
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
###
|
|
105
|
-
-
|
|
106
|
-
|
|
107
|
-
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
-
|
|
114
|
-
-
|
|
115
|
-
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
-
|
|
121
|
-
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
62
|
+
## Rules
|
|
63
|
+
|
|
64
|
+
### R1. Creation forms are never always-visible — toolbar button + dialog
|
|
65
|
+
- An always-visible form card competes with the body (the table) and wastes space when unused.
|
|
66
|
+
- Rule: a `[+ Add]` button in the top toolbar → a dialog on click. Short creations with three fields
|
|
67
|
+
or fewer fit a dialog.
|
|
68
|
+
- The dialog's field order matches the table column order (e.g. code→name); the first field takes
|
|
69
|
+
focus (autoFocus).
|
|
70
|
+
|
|
71
|
+
### R2. Row edits are dialogs, not inline — one-shot manipulations excepted
|
|
72
|
+
- In-place inputs inside table cells change the row height, push surrounding content, and fall apart
|
|
73
|
+
with multiple fields.
|
|
74
|
+
- Rule: even a single-field edit goes through a **dialog (or popover)**. Only one-click manipulations
|
|
75
|
+
(an active/inactive toggle, a select choice) execute immediately.
|
|
76
|
+
|
|
77
|
+
### R3. Expose 1~2 row actions — the rest goes into the kebab (⋯) menu
|
|
78
|
+
- Four buttons per row make scanning hard and the table look like a button list.
|
|
79
|
+
- Rule: expose at most the two most-used actions as buttons; the rest goes into the row-end `⋯`
|
|
80
|
+
overflow menu. Destructive actions (delete) take the destructive style inside the menu.
|
|
81
|
+
|
|
82
|
+
### R4. Rare features move to secondary screens — progressive disclosure
|
|
83
|
+
- A rarely used feature occupying permanent space hurts learnability and density.
|
|
84
|
+
- Rule: low-frequency actions (restore, undo-merge) move to a dedicated secondary screen (the history
|
|
85
|
+
page) or an accordion. Ledger (event-log) based actions fit most naturally as a button on the
|
|
86
|
+
corresponding event row of the history screen.
|
|
87
|
+
|
|
88
|
+
### R5. Dialog accessibility minimum
|
|
89
|
+
- Rule: close on Esc, a visible close button, focus trap + focus restored to the trigger on close,
|
|
90
|
+
no dialog inside a dialog. (shadcn Dialog provides these by default — holding as long as you never
|
|
91
|
+
hand-roll one.)
|
|
92
|
+
|
|
93
|
+
### R6. Destructive work warns → confirms, two steps (the gate already owns this)
|
|
94
|
+
- The gate's warning=refusal → force retry pattern IS this rule's implementation.
|
|
95
|
+
- Rule: the UI's confirmation dialog states the outcome explicitly (what gets erased, what is
|
|
96
|
+
preserved), with the recovery path shown alongside.
|
|
97
|
+
|
|
98
|
+
### R7. Tables are shadcn standard — no density·size numbers here
|
|
99
|
+
- Table·cell·control sizes and fonts follow **the shadcn standard as-is** — this guide sets no pixel
|
|
100
|
+
specs.
|
|
101
|
+
- **Pages still on raw `<table>` migrate to `ui/Table` when you touch that page** (`check:ui` flags
|
|
102
|
+
the debt). New code is always `ui/Table`.
|
|
103
|
+
|
|
104
|
+
### R8. Low-information columns·badges become inline cues
|
|
105
|
+
- Columns that repeat what indentation or shape already tells you raise density and compete with the
|
|
106
|
+
body (state·actions).
|
|
107
|
+
- Rule: things structure already shows (hierarchy depth L1/L2…) get no column — indentation only.
|
|
108
|
+
State (active/inactive) also drops its dedicated column in favor of the name's tone
|
|
109
|
+
(inactive=muted) + a tooltip.
|
|
110
|
+
- Long raw data (event payloads etc.) becomes a one-line summary in the app's language in the
|
|
111
|
+
column, with the original in a row tooltip.
|
|
112
|
+
|
|
113
|
+
### R9. Inactive·past states go behind a view toggle — progressive disclosure (view edition)
|
|
114
|
+
- Inactive items in management lists are needed only occasionally (reactivation·inspection).
|
|
115
|
+
Permanent display disturbs scanning the body.
|
|
116
|
+
- Rule: a `[Hide inactive / Show]` toggle in the toolbar (visible by default). Hiding removes the
|
|
117
|
+
items AND their **whole subtree** (no orphans).
|
|
118
|
+
|
|
119
|
+
### R10. Page skeleton — title row / toolbar / table / pagination
|
|
120
|
+
- Skeleton order: title row → toolbar → table → pagination.
|
|
121
|
+
- The title row holds the title·a one-line description only (action buttons go to the toolbar).
|
|
122
|
+
- Toolbar: **filters left**, the primary action (`+ Add`) **right**. With no filters, the whole
|
|
123
|
+
toolbar right-aligns.
|
|
124
|
+
- Hint copy goes as a muted caption under the toolbar. Mid-body labels appear only with two or more
|
|
125
|
+
sections.
|
|
126
|
+
- Time notations are full dates including the year.
|
|
127
|
+
|
|
128
|
+
### R11. Spacing comes from structure
|
|
129
|
+
- No spacing numbers — use shadcn component defaults and the Tailwind utility rhythm as-is.
|
|
130
|
+
- Adding margins to individual elements inside a `space-y` layout breaks the rhythm — change spacing
|
|
131
|
+
through the wrapper structure.
|
|
132
|
+
- Dialog form spacing follows the official shadcn form conventions as-is.
|
|
133
|
+
|
|
134
|
+
### R12. Sizes·typography follow the shadcn scale
|
|
135
|
+
- Control sizes come from the shadcn standard **size variants** only — no arbitrary `h-*` in
|
|
136
|
+
`className` (the data-size class beats a plain `h-*` — tailwind-merge cannot remove it).
|
|
137
|
+
- **Controls side by side on one line share the same size variant** — at default, Button·Input·
|
|
138
|
+
Select align in height. Mixing variants skews the line (sm only when the whole line is sm).
|
|
139
|
+
- Fonts use standard shadcn tokens only — a custom `text-*` token gets mistaken for a color by
|
|
140
|
+
twMerge and is dropped in color variants.
|
|
141
|
+
|
|
142
|
+
### R13. Colors are shadcn semantic tokens only
|
|
143
|
+
- Never reference the palette directly — semantic tokens only.
|
|
144
|
+
|
|
145
|
+
### R14. Repeated values are quiet text — chips are for markers only
|
|
146
|
+
- A column where most rows share one value (e.g. 24 of 25 rows domestic) renders as muted text.
|
|
147
|
+
Wrapping everything in chips only adds information-free noise.
|
|
148
|
+
- Chips mark **structural markers** (a subsidiary) or the few targets that must stand out.
|
|
149
|
+
- To make a specific value (e.g. overseas) stand out, highlight that value alone — not the whole
|
|
150
|
+
column of chips (low-frequency emphasis).
|
|
151
|
+
- No repeated identical labels inside a cell — numbers·colors + a one-line legend (the "2 · 1 · 5"
|
|
152
|
+
matrix cell case).
|
|
153
|
+
|
|
154
|
+
### R15. The component base is shadcn/ui — the official site is the reference
|
|
155
|
+
- Controls (buttons·dialogs·tables·dropdowns…) use the official shadcn/ui components as-is (no
|
|
156
|
+
in-house builds). Looks·variants·a11y follow the official docs.
|
|
157
|
+
- The ui component list (of the reference surface): badge·button·card·dialog·dropdown-menu·input·
|
|
158
|
+
label·scroll-area·select·separator·sheet·sonner·table·textarea. **A control missing from the list
|
|
159
|
+
is added with `npx shadcn@latest add <name>`** (never hand-assembled) — a new app applies the same
|
|
160
|
+
rule to its own list of added components.
|
|
161
|
+
- The theme is the token set extracted from the shadcn create page (Get Code → Theme tab) (tied to
|
|
162
|
+
R13's semantic tokens).
|
|
163
|
+
- When a size you need is absent from the shadcn default variants, add a **size variant** the shadcn
|
|
164
|
+
way — not an arbitrary `className` (R12).
|
|
165
|
+
|
|
166
|
+
### R16. Screen shells come from the official Blocks — never hand-assembled
|
|
167
|
+
- Screen shells (sidebar·dashboard·login) start as-is from the official shadcn Blocks (sidebar·
|
|
168
|
+
dashboard, …) — menu structure·spacing·responsive behavior lock to the official example values
|
|
169
|
+
(as R15 is for components, the same principle for layouts).
|
|
170
|
+
- Only a structure absent from Blocks is built by hand, minimally — still inside R10's skeleton·
|
|
171
|
+
R11's spacing·R12·R13's token principles.
|
|
172
|
+
|
|
173
|
+
### R17. An app has one per-role assignment table — not per-screen decisions
|
|
174
|
+
- At app start, define and document once a per-role typography·spacing assignment table (screen
|
|
175
|
+
title·description·section title·body·page vertical rhythm, … — **standard tokens only**) that
|
|
176
|
+
every screen follows.
|
|
177
|
+
- Even allowed tokens drift when every screen decides anew — consistency comes from "same role, same
|
|
178
|
+
token". The assignment picks which standard value to use; it never invents new ones.
|
|
179
|
+
|
|
180
|
+
### R18. Screen copy is in the user's language — internal references stay hidden
|
|
181
|
+
- Every visible string (descriptions under titles·buttons·labels·states·empty states·errors·
|
|
182
|
+
confirmations) is written in the language of the people using that screen.
|
|
183
|
+
- Forbidden: request-row codes (A1·B2), internal mechanism vocabulary (ledger·gate·command·event·
|
|
184
|
+
projection·delegation token·idempotency·row_hash), development-process wording ("confirmed in the
|
|
185
|
+
screen spec"·"registered via request"). Sentences from the spec·request forms are design documents,
|
|
186
|
+
not screen copy — rewrite from the user's perspective when surfacing.
|
|
187
|
+
- The test: does the string tell the USER what this feature does, or tell a DEVELOPER how the system
|
|
188
|
+
is built — if the latter, remove or rewrite it.
|
|
189
|
+
- Exception: a development-roadmap notice the user asked to see (e.g. "this feature arrives in the
|
|
190
|
+
stage-③ statistics screen") — exposure is the point; stage·feature names only, with internal
|
|
191
|
+
structure mentions following the same rule.
|
|
192
|
+
|
|
193
|
+
## Before you commit — the same bar as `npm run check:ui`
|
|
139
194
|
|
|
140
195
|
```bash
|
|
141
|
-
npm run check:ui #
|
|
196
|
+
npm run check:ui # the list below is checked mechanically (violations fail)
|
|
142
197
|
```
|
|
143
198
|
|
|
144
|
-
- [ ]
|
|
145
|
-
- [ ]
|
|
146
|
-
- [ ] `style="`
|
|
147
|
-
- [ ]
|
|
148
|
-
- [ ] `text-13`
|
|
149
|
-
- [ ]
|
|
150
|
-
|
|
151
|
-
- [ ]
|
|
199
|
+
- [ ] raw `<button>`·`<select>` — zero occurrences outside components/ui
|
|
200
|
+
- [ ] raw `<table>` — zero in new code (existing pages migrate to ui/Table when touched, R7)
|
|
201
|
+
- [ ] zero `style="` strings·static style objects — computed values (tree indentation) only
|
|
202
|
+
- [ ] zero arbitrary colors (`bg-[#…]` etc.) — shadcn semantic tokens only
|
|
203
|
+
- [ ] zero custom font tokens like `text-13` — standard shadcn tokens only
|
|
204
|
+
- [ ] new controls added via shadcn add — nothing hand-assembled for missing-from-ui (custom-widget
|
|
205
|
+
exceptions carry the `check:ui-allow: reason` marker)
|
|
206
|
+
- [ ] pages follow the skeleton order (title row→toolbar→table→pagination)
|
|
207
|
+
- [ ] sizes come from shadcn size variants — no arbitrary className (h-*)
|
|
152
208
|
|
|
153
|
-
## URL
|
|
209
|
+
## URL naming rules
|
|
154
210
|
|
|
155
|
-
-
|
|
211
|
+
- **Singular = a view selecting one target** (`/function`, `/client`); **plural = a list·management**
|
|
212
|
+
(`/notes`, `/functions`, `/clients`) — the notes view IS the list itself, hence plural.
|
|
156
213
|
|
|
157
|
-
##
|
|
214
|
+
## Appendix — the grounds for the rules
|
|
158
215
|
|
|
159
|
-
- R1: [NN/g Modal & Nonmodal Dialogs](https://www.nngroup.com/articles/modal-nonmodal-dialog) (
|
|
160
|
-
- R2: [SaaS UX Patterns](https://www.saasui.design/blog/saas-modal-dialog-ux-patterns), [UX
|
|
161
|
-
- R3: [Carbon Data Table](https://www.carbondesignsystem.com/building-blocks/core/components/data-table), [Carbon Menu Buttons](https://www.carbondesignsystem.com/building-blocks/core/components/menu-buttons), [Ant Design
|
|
216
|
+
- R1: [NN/g Modal & Nonmodal Dialogs](https://www.nngroup.com/articles/modal-nonmodal-dialog) (modals fit short single tasks), [Atlassian Modal Dialog](https://atlassian.design/components/modal-dialog)
|
|
217
|
+
- R2: [SaaS UX Patterns](https://www.saasui.design/blog/saas-modal-dialog-ux-patterns), [a UX case study](https://rakibulism.medium.com/choosing-modals-over-inline-actions-a-ux-case-study-on-table-complexity-2552ee168b5c)
|
|
218
|
+
- R3: [Carbon Data Table](https://www.carbondesignsystem.com/building-blocks/core/components/data-table), [Carbon Menu Buttons](https://www.carbondesignsystem.com/building-blocks/core/components/menu-buttons), [Ant Design recommendation](https://github.com/ant-design/ant-design/issues/25799) (≤2 exposed actions per row), [NN/g Contextual Menus](https://www.nngroup.com/articles/contextual-menus-guidelines)
|
|
162
219
|
- R4·R9: [NN/g Progressive Disclosure](https://www.nngroup.com/articles/progressive-disclosure)
|
|
163
|
-
- R5: [WAI-ARIA Dialog Modal
|
|
164
|
-
- R7: [Carbon Data Table](https://www.carbondesignsystem.com/building-blocks/core/components/data-table) (compact
|
|
220
|
+
- R5: [WAI-ARIA Dialog Modal pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal), [A11y Collective](https://www.a11y-collective.com/blog/modal-vs-dialog)
|
|
221
|
+
- R7: [Carbon Data Table](https://www.carbondesignsystem.com/building-blocks/core/components/data-table) (compact density), [Ant Design Table](https://ant.design/components/table) (size small/middle)
|
|
165
222
|
- R8: [NN/g How Users Read on the Web](https://www.nngroup.com/articles/how-users-read-on-the-web/)
|
package/docs/undo-scope-guide.md
CHANGED
|
@@ -1,92 +1,107 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Undo scope guide
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
The criterion an agent creating or editing a domain uses to decide "which event types do we open to
|
|
4
|
+
the kernel-common undo?" Written against kernel 0.6.1; the kernel-side contract follows the Undo
|
|
5
|
+
section of [packages/kernel/README.md](../README.md).
|
|
5
6
|
|
|
6
|
-
##
|
|
7
|
+
## Principle
|
|
7
8
|
|
|
8
|
-
|
|
9
|
-
|
|
9
|
+
**Open only what is hard to restore by hand after a mistake.** Everything else stays `unavailable`,
|
|
10
|
+
with an alternative written into the reason. Do not try to support everything — every supported event
|
|
11
|
+
type brings its handler, its tests and its event-format management with it.
|
|
10
12
|
|
|
11
|
-
|
|
12
|
-
"
|
|
13
|
+
The kernel requires an undo policy declaration for every event type. The requirement is not "support
|
|
14
|
+
everything" — it is "decide, per type, whether you support it".
|
|
13
15
|
|
|
14
|
-
##
|
|
16
|
+
## Decision order
|
|
15
17
|
|
|
16
|
-
|
|
18
|
+
For each event type, ask top to bottom and decide at the first hit.
|
|
17
19
|
|
|
18
|
-
|
|
|
20
|
+
| # | Question | On a hit |
|
|
19
21
|
|---|---|---|
|
|
20
|
-
| 1 |
|
|
21
|
-
| 2 |
|
|
22
|
-
| 3 |
|
|
23
|
-
| 4 |
|
|
24
|
-
| 5 |
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
1.
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
-
|
|
45
|
-
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
-
|
|
55
|
-
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
-
|
|
76
|
-
`
|
|
77
|
-
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
-
|
|
86
|
-
|
|
87
|
-
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
22
|
+
| 1 | Is it a secret, a right, or an external effect? | Do not support |
|
|
23
|
+
| 2 | Is it a record rather than a state? | Do not support |
|
|
24
|
+
| 3 | Would re-running the same command restore the original? | Do not support |
|
|
25
|
+
| 4 | Does one execution change or remove multiple rows? | **Support candidate** |
|
|
26
|
+
| 5 | Support candidate, but the event carries no prior state? | Fix the event first, then support it |
|
|
27
|
+
|
|
28
|
+
What each question means:
|
|
29
|
+
|
|
30
|
+
1. **Secrets, rights, external effects.** Passwords, roles, delegation issue·revoke, account
|
|
31
|
+
deletion, outgoing mail. Undoing these would flip a security decision, or pretend something
|
|
32
|
+
already outside came back.
|
|
33
|
+
2. **Records.** Decisions, approvals, proposals — things whose meaning is the fact itself, "this
|
|
34
|
+
happened then". You do not erase them; you overlay new records.
|
|
35
|
+
3. **Re-runnable work.** Renames, active toggles, reordering, settings changes — one-value changes.
|
|
36
|
+
An unsupported reason like "set the previous value with the same command" is enough.
|
|
37
|
+
4. **Multi-row work.** Deletes, merges, bulk changes, moves that take descendants along. Restoring
|
|
38
|
+
by hand requires remembering exactly what changed — that is what undo is for.
|
|
39
|
+
5. **Events without prior state.** Undo quality is decided by the information the original event
|
|
40
|
+
carries. Opening it with insufficient data makes the "restore" a rough remake.
|
|
41
|
+
|
|
42
|
+
## Priority
|
|
43
|
+
|
|
44
|
+
When several candidates remain, open them in this order:
|
|
45
|
+
|
|
46
|
+
- **Largest blast radius first.** Data loss, then structure changes, then value changes.
|
|
47
|
+
- **Agent-runnable first.** Commands inside delegation scopes are the most mistake-prone; undo is
|
|
48
|
+
their safety net.
|
|
49
|
+
- **Frequently used first.** Rarely-run commands wait.
|
|
50
|
+
|
|
51
|
+
## Before opening — the checklist
|
|
52
|
+
|
|
53
|
+
For every event type you switch to supported, all of these must hold. If any one fails, it is not
|
|
54
|
+
time yet.
|
|
55
|
+
|
|
56
|
+
- The original event carries every value the restoration needs.
|
|
57
|
+
- The compensation command takes an identifier that points at the exact record, not "the latest one".
|
|
58
|
+
- What undo loses (changes made in between, etc.) can be stated in `losses`.
|
|
59
|
+
- Conditions that make undo impossible (parent gone, name conflict, already restored by hand) can be
|
|
60
|
+
stated in `blockers`.
|
|
61
|
+
- Every event type one command execution writes points at the same handler (otherwise the kernel
|
|
62
|
+
refuses with `undo.operation_mixed_policies`).
|
|
63
|
+
|
|
64
|
+
## Signals you should NOT open it
|
|
65
|
+
|
|
66
|
+
- **You feel a need for undo-of-undo.** Reverting a restoration is "delete it again" — an ordinary
|
|
67
|
+
command does that.
|
|
68
|
+
- **The handler outgrows the compensation.** When the planning code is longer than the actual
|
|
69
|
+
restore code, the model does not fit this domain.
|
|
70
|
+
- **The preview's `changes` is a single line of "recreate everything".** The user gets nothing to
|
|
71
|
+
judge — guide to a re-run instead.
|
|
72
|
+
|
|
73
|
+
## What the domain does
|
|
74
|
+
|
|
75
|
+
For every supported event type:
|
|
76
|
+
|
|
77
|
+
- **The handler declares its compensation command statically** (`compensationCommand`). The plan's
|
|
78
|
+
`command` must equal the declaration.
|
|
79
|
+
- **The handler answers exactly three things.** What changes (`changes`), what is lost (`losses`),
|
|
80
|
+
why not (`blockers`).
|
|
81
|
+
- **`changes.field` carries field names only** — no explanation sentences. Parts that do not restore
|
|
82
|
+
to the original belong in `losses`.
|
|
83
|
+
- **State the plan depends on — not values shown on screen — goes into `dependsOn` as tokens.**
|
|
84
|
+
Do not re-implement the projector or the command's computation inside the handler.
|
|
85
|
+
- **The handler blocks records already restored by hand.** The kernel does not know about a
|
|
86
|
+
compensation command invoked directly; its one-compensation guard only knows the undo path.
|
|
87
|
+
- **Origin-read rules share one judgment function with ledger reads.** What the ledger shows is what
|
|
88
|
+
undo may show. Register it once with `registerUndoReadGate`.
|
|
89
|
+
- **Never remove a compensation command from the assembly.** Removing it refuses the redelivery of
|
|
90
|
+
past undos performed through it — even for the actor who ran them.
|
|
91
|
+
|
|
92
|
+
For unsupported event types, write a concrete reason. Not "not supported" but "rename back with the
|
|
93
|
+
same command" — the next action spelled out. An agent reads this sentence and acts on it.
|
|
94
|
+
|
|
95
|
+
## What the surface does
|
|
96
|
+
|
|
97
|
+
- **The screen never guesses undoability.** No code scanning the event list to compute "already
|
|
98
|
+
undone" — ask the kernel.
|
|
99
|
+
- **The flow is fixed at three steps.** Status decides the button, preview fills the confirmation
|
|
100
|
+
dialog, and the preview's `planHash` executes.
|
|
101
|
+
- **One confirmation dialog for all events.** The preview shape is common to every event type —
|
|
102
|
+
build no per-event-type dialogs.
|
|
103
|
+
- **A visible button can still be refused at preview.** Status does not compute domain blockers —
|
|
104
|
+
there must be a screen that shows the reasons for `blocked`·`unavailable`·`denied`·`already_undone`.
|
|
105
|
+
- **On `undo.plan_changed`, reload the preview and take the confirmation again.**
|
|
106
|
+
- **With losses (`warning`), send `acceptLosses: true` only after the user confirmed them.**
|
|
107
|
+
- **A status query carries at most 100 seqs.** More is an input refusal — page the query.
|