@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,144 +1,171 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Kernel upgrade guide — 0.3/0.4/0.5.x → 0.6
|
|
2
2
|
|
|
3
|
-
## 0. 0.5.x → 0.6.0 (
|
|
3
|
+
## 0. 0.5.x → 0.6.0 (undo contract corrections)
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
5
|
+
Attaching undo to a real domain for the first time on 0.5.1 surfaced four contract corrections.
|
|
6
|
+
The backbone (compensation as a NEW write, the plan hash, loss confirmation, the one-compensation
|
|
7
|
+
guard, redelivery rights re-proof) is unchanged.
|
|
7
8
|
|
|
8
|
-
| # |
|
|
9
|
+
| # | Change | What you do |
|
|
9
10
|
|---|---|---|
|
|
10
|
-
| ① |
|
|
11
|
-
| ② |
|
|
12
|
-
| ③ |
|
|
13
|
-
| ④ | **`undoStatus`
|
|
11
|
+
| ① | **Undo handlers must declare `compensationCommand`** — one compensation command, declared statically. The seal check verifies it is registered, and the kernel checks the current identity's access to the declared command BEFORE `plan()` runs (a refusal answers `denied` and no plan is computed). A plan naming any other command is `undo.plan_invalid` | Add one line to the handler registration. The `mayPreview` hook becomes OPTIONAL (runs after the base checks when present) — a hook that only checked "can this identity run the compensation command" can be deleted |
|
|
12
|
+
| ② | **One permission vocabulary — `denied`** — permission refusals from `previewUndo` (read gate, handler gate, compensation-command role·delegation, denied targets) answer `denied` instead of `blocked`. On execution (`executeUndo`) permission refusals keep their own stage and code (1~3, e.g. `gate.role_denied`·`gate.delegation_denied`) — the stage-8 re-wrap is gone | App code that mined `preview.status === 'blocked'` for permission refusals adds a `denied` branch (handle it on the premise that no operation facts are present) |
|
|
13
|
+
| ③ | **App-wide origin-read gate `registerUndoReadGate`** — register one `mayRead` for the whole app. A policy-level `mayRead` wins where present | Assemblies that attached the same function once per event type replace it with a single registration. Boot condition: "every policy has `mayRead` OR the default gate is registered" (neither fails the boot — read rights are a declared decision; that principle stands) |
|
|
14
|
+
| ④ | **`undoStatus` cap** — `sourceSeqs` beyond `UNDO_STATUS_MAX_SEQS` (100) is a stage-4 input refusal (`gate.schema_invalid`). The old behavior of quietly handling the first 100 is gone | Screens that queried more than 100 seqs must page. The constant is exported from the kernel |
|
|
14
15
|
|
|
15
|
-
|
|
16
|
-
(
|
|
16
|
+
Kernel version **0.6.0** (a required handler field added = a 0.x breaking change → minor bump),
|
|
17
|
+
`PROTOCOL_VERSION` **1.1.0** (a new status in the preview response and a new field in catalog policy
|
|
18
|
+
entries — additive changes).
|
|
17
19
|
|
|
18
|
-
### 0.6.1 (
|
|
20
|
+
### 0.6.1 (follow-up corrections — patch)
|
|
19
21
|
|
|
20
|
-
0.6.0
|
|
22
|
+
Reviewing 0.6.0 in practice reproduced two inconsistencies. Public types are unchanged, so `^0.6.0`
|
|
23
|
+
consumers receive it automatically.
|
|
21
24
|
|
|
22
|
-
| # |
|
|
25
|
+
| # | Change | What you do |
|
|
23
26
|
|---|---|---|
|
|
24
|
-
| ① |
|
|
25
|
-
| ② |
|
|
27
|
+
| ① | **Status and preview answer the same identity the same way** — the compensation-command access check moved into the shared judgment. An unauthorized identity's `undoStatus` row answers `denied` (code only) instead of `supported` (with handlerId) | Nothing (a correction). A `mayPreview` that only confirmed "this identity may run the compensation command" can now be REMOVED — status answers correctly on its own; the kernel checks before the plan |
|
|
28
|
+
| ② | **Redelivery re-proof no longer depends on the preview state** — when the source operation carries a STORED compensation, its recorded envelope (command·recorded target) re-proves the rights whatever the CURRENT policy consensus says (supported·unavailable·mixed alike — the policy may have moved since the compensation was stored). A removed compensation command leaves nothing re-provable → refused | A resent requestKey being refused after rights were revoked is intended behavior (a restoration of the original principle) |
|
|
26
29
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
`compensationCommand
|
|
32
|
-
|
|
33
|
-
(
|
|
30
|
+
Apps using the physical layer through kernel packages must move to the infra pair built for
|
|
31
|
+
^0.6.0 — **infra-sqlite·infra-postgres 0.5.0** (declare `^0.5.0`) — together: the old pair carries a
|
|
32
|
+
`@sudoke/kernel ^0.5.0` dependency that does not satisfy 0.6.0, so npm nested-installs a registry
|
|
33
|
+
0.5.x kernel that the infra pair binds to instead of your workspace copy. The catalog undo-policy
|
|
34
|
+
entry now publishes `compensationCommand`, so `catalogRevision` moves — read the changes with
|
|
35
|
+
`catalog_status` on reconnect. If a case arises where one handler must plan several compensation
|
|
36
|
+
commands, report it to the kernel (the current contract is one compensation command per handler).
|
|
34
37
|
|
|
35
38
|
---
|
|
36
39
|
|
|
37
|
-
`@sudoke/kernel` 0.3.x/0.4.x
|
|
40
|
+
Moving an app built on `@sudoke/kernel` 0.3.x/0.4.x to **0.5.0**.
|
|
38
41
|
|
|
39
|
-
> **0.5.0
|
|
40
|
-
> **compat/strict
|
|
41
|
-
> `configureKernel`
|
|
42
|
+
> **0.5.0 changes direction.** Through 0.4 the contract regime was opt-in (strict mode); 0.5.0
|
|
43
|
+
> **removes the compat/strict split and applies the contract regime unconditionally** — the legacy
|
|
44
|
+
> compat path is gone, and `configureKernel` itself no longer exists (delete the call).
|
|
42
45
|
>
|
|
43
|
-
>
|
|
44
|
-
>
|
|
45
|
-
>
|
|
46
|
+
> **It does not arrive by itself.** Under semver 0.x, `^0.4.0` does not include 0.5 — this guide is
|
|
47
|
+
> for apps that decided to bump. Not bumping changes nothing. Climbing only to 0.4 and adapting
|
|
48
|
+
> gradually is also fine (0.4 still has compat mode).
|
|
46
49
|
|
|
47
|
-
## 1.
|
|
50
|
+
## 1. Dependency updates
|
|
48
51
|
|
|
49
52
|
```jsonc
|
|
50
53
|
// package.json
|
|
51
54
|
{
|
|
52
55
|
"dependencies": {
|
|
53
56
|
"@sudoke/kernel": "^0.5.0"
|
|
54
|
-
//
|
|
57
|
+
// only apps using the physical layer through kernel packages (the pair must move together):
|
|
55
58
|
, "@sudoke/infra-sqlite": "^0.4.0"
|
|
56
59
|
}
|
|
57
60
|
}
|
|
58
61
|
```
|
|
59
62
|
|
|
60
|
-
- infra 0.4.0
|
|
61
|
-
|
|
62
|
-
-
|
|
63
|
+
- infra 0.4.0 keeps **existing DBs as they are** — if the events table lacks the meta column at boot,
|
|
64
|
+
it adds it in place (a lossless migration). No data move, no backup restore.
|
|
65
|
+
- The same rule for apps on `@sudoke/infra-postgres` (`^0.4.0`, `ADD COLUMN IF NOT EXISTS`).
|
|
66
|
+
- Kernel API details: [packages/kernel/README.md](../README.md) (English, shipped in this package).
|
|
63
67
|
|
|
64
|
-
## 2.
|
|
68
|
+
## 2. Boot requirements — failing these means the app does not start
|
|
65
69
|
|
|
66
|
-
0.5.0
|
|
70
|
+
0.5.0's boot checks are all **unconditional**. At seal time (first execution or an explicit seal):
|
|
67
71
|
|
|
68
|
-
|
|
|
72
|
+
| Requirement | Content |
|
|
69
73
|
|---|---|
|
|
70
|
-
|
|
|
71
|
-
|
|
|
72
|
-
|
|
|
73
|
-
|
|
|
74
|
+
| Command·query versions | every command and query declares a semver like `version: '1.0.0'` |
|
|
75
|
+
| Undo policies | every **registered event type** has a policy — `{kind:'supported', handlerId}` or `{kind:'unavailable', code, reason}`. Support is optional, but **the declaration is mandatory** (silence is a defect) |
|
|
76
|
+
| Read-rights hooks | `mayRead` on every policy, `mayPreview` on every handler — "who reads undo history" must be a declared decision |
|
|
77
|
+
| Storage capability | the physical engine provides operationLedger (infra ^0.4.0 already does) |
|
|
74
78
|
|
|
75
|
-
> **0.6.0
|
|
76
|
-
> (`registerUndoReadGate`)
|
|
77
|
-
> (`compensationCommand`,
|
|
78
|
-
>
|
|
79
|
+
> **From 0.6.0 two rows of this table change** — read rights become "every policy `mayRead` OR one
|
|
80
|
+
> app-wide default gate (`registerUndoReadGate`)", and the handler requirement becomes the
|
|
81
|
+
> **compensation-command declaration (`compensationCommand`, mandatory)** instead of `mayPreview`.
|
|
82
|
+
> See §0 ①·③ above for the migration. The infra pair moves too — infra-sqlite·infra-postgres 0.5.0
|
|
83
|
+
> (their kernel dependency is ^0.6.0) — or npm nested-installs a registry 0.5.x kernel.
|
|
79
84
|
|
|
80
85
|
```ts
|
|
81
|
-
//
|
|
86
|
+
// the common minimal pattern — an app not using undo yet
|
|
82
87
|
registerUndoPolicies(
|
|
83
88
|
Object.fromEntries(
|
|
84
89
|
Object.keys(APP_EVENT_CONTRACTS).map((type) => [
|
|
85
90
|
type,
|
|
86
|
-
{ kind: 'unavailable', code: 'app.not_reversible', reason: '
|
|
91
|
+
{ kind: 'unavailable', code: 'app.not_reversible', reason: 'this event is not reversible', mayRead: async () => {} },
|
|
87
92
|
]),
|
|
88
93
|
),
|
|
89
94
|
)
|
|
90
95
|
```
|
|
91
96
|
|
|
92
|
-
(
|
|
97
|
+
(The `app.not_reversible` code must be registered in `registerErrorCodes`.)
|
|
93
98
|
|
|
94
|
-
## 3.
|
|
99
|
+
## 3. Every write carries a contract — **the core 0.5.0 change**
|
|
95
100
|
|
|
96
|
-
|
|
101
|
+
Attach the contract read from the catalog to every write request:
|
|
97
102
|
|
|
98
103
|
```ts
|
|
99
|
-
{
|
|
104
|
+
{ ...businessInput, contract: { commandVersion, commandRevision, protocolVersion } }
|
|
100
105
|
```
|
|
101
106
|
|
|
102
|
-
-
|
|
103
|
-
-
|
|
104
|
-
-
|
|
105
|
-
|
|
106
|
-
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
107
|
+
- Absent → `gate.contract_required`, stale → `gate.contract_changed` — **the refusal IS the guidance
|
|
108
|
+
to re-read the catalog** (recovery: refresh).
|
|
109
|
+
- **Solve it in ONE place**: the surface's shared api client (a common function like runCommand)
|
|
110
|
+
caches catalog state and attaches the contract automatically. No call-site sweep is needed.
|
|
111
|
+
- **On `gate.contract_changed`, re-learning comes first**: read the catalog state and the change
|
|
112
|
+
record (`catalog_changes`·`command_contract`), understand WHAT changed (version·input
|
|
113
|
+
meaning·warnings), then judge whether the original request still means the same thing. **Bumping
|
|
114
|
+
the revision and auto-resending is not safe** — a MAJOR change like a unit flip from cents to
|
|
115
|
+
dollars passes the new contract check yet executes a different amount than the user intended. The
|
|
116
|
+
kernel cannot prove that the caller understood the new contract.
|
|
117
|
+
- **Auto-retry only when meaning preservation is verifiable**: automate the retry only when the app
|
|
118
|
+
can EXPLICITLY judge that the change record does not touch input meaning ("description text only"),
|
|
119
|
+
and leave that judgment written in the code. "Same MAJOR" alone never substitutes for a meaning
|
|
120
|
+
check. When in doubt, show the new contract to the caller·agent and have the request rebuilt.
|
|
121
|
+
- Idempotent redelivery (a requestKey re-send) is judged BEFORE the contract check — a stored
|
|
122
|
+
success returns as-is even if today's schema changed.
|
|
123
|
+
- MCP tools take a `contract` parameter — external agents read the catalog (the `command_contract`
|
|
124
|
+
tool) first and attach it.
|
|
125
|
+
|
|
126
|
+
## 4. What changed along the way (0.4 changes included)
|
|
127
|
+
|
|
128
|
+
| # | Change | What you do |
|
|
112
129
|
|---|---|---|
|
|
113
|
-
| ① |
|
|
114
|
-
| ② |
|
|
115
|
-
| ③ | MCP `tools/list
|
|
116
|
-
| ④ |
|
|
117
|
-
| ⑤ | MCP
|
|
118
|
-
| ⑥ |
|
|
130
|
+
| ① | Catalog document·status field `version` renamed to **`catalogVersion`** (the old alias is dropped) | Only code reading the kernel catalog renames the field (an app's own state responses are unaffected) |
|
|
131
|
+
| ② | A catalog command's `fields` lists **every field, including undocumented ones** (value `null`) | Handle `null` when iterating fields |
|
|
132
|
+
| ③ | 7 common tools added to MCP `tools/list` — `catalog`·`catalog_status`·`catalog_changes`·`command_contract`·`undo_status`·`undo_preview`·`undo_execute` | Refresh lists validating tool names (tests included) — all snake_case |
|
|
133
|
+
| ④ | **Redelivery (idempotent replay) re-proves rights** — a stored success's re-send is re-judged against the recorded role·delegation range and the current assignments | Flows re-sending the same requestKey after rights were revoked are now refused (intended). **Rows older than producer tracking** are refused too — no re-proof material (the old `{unknown:true}` marker is gone) |
|
|
134
|
+
| ⑤ | MCP write values are now identical to the direct API — the double normalization (coerce·trim twice) is removed | No changes needed. Apps that saw subtly different values now see the same ones |
|
|
135
|
+
| ⑥ | Replay responses carry `producedBy` (the contract that produced the result) | May be ignored (an extra field) |
|
|
119
136
|
|
|
120
|
-
|
|
137
|
+
New error codes: `gate.contract_required`·`gate.contract_changed` (§3) and the ten `undo.*` codes
|
|
138
|
+
(only apps with undo on) — only apps that enumerate codes exhaustively need to update.
|
|
121
139
|
|
|
122
|
-
## 5.
|
|
140
|
+
## 5. From here it is optional — read separately from the mandatory assembly (§2)
|
|
123
141
|
|
|
124
|
-
-
|
|
125
|
-
|
|
142
|
+
- **Undo execution** — §2's policy declaration and `mayRead` are MANDATORY assembly requirements.
|
|
143
|
+
The optional part comes after: attaching an actual handler with `{kind:'supported', handlerId}`
|
|
144
|
+
(`registerUndoHandler`) to turn on `previewUndo`·`executeUndo`·`undoStatus`. Ending at
|
|
145
|
+
`unavailable` declarations boots and runs 0.5.0 completely. Undo is a forward compensation (a
|
|
146
|
+
NEW write); the original history is immutable.
|
|
147
|
+
- **Contract discovery tools** — `command_contract` (a machine-readable contract per command)·
|
|
148
|
+
`catalog_status`·`catalog_changes` (only the delta on reconnect). All optional.
|
|
126
149
|
|
|
127
|
-
## 6.
|
|
150
|
+
## 6. Upgrade procedure
|
|
128
151
|
|
|
129
152
|
```
|
|
130
|
-
1.
|
|
131
|
-
2.
|
|
132
|
-
3.
|
|
133
|
-
4. §4
|
|
134
|
-
5.
|
|
135
|
-
6. (
|
|
153
|
+
1. Dependency bump (§1) → npm install
|
|
154
|
+
2. Meet the boot requirements (§2) — version declarations·undo policies·mayRead — boot the app to verify
|
|
155
|
+
3. Contract auto-attach in the one write path (§3) — contract_changed means re-learn then rebuild; auto-retry only with a meaning-preservation check (§3)
|
|
156
|
+
4. §4 checks (① catalog field names ② fields null ③ tool list ④ replay rights)
|
|
157
|
+
5. Run the app's own checks (smoke/MCP/policy — each app's own)
|
|
158
|
+
6. (Optional) adopting undo is its own task — §5
|
|
136
159
|
```
|
|
137
160
|
|
|
138
161
|
## FAQ
|
|
139
162
|
|
|
140
|
-
**Q.
|
|
141
|
-
**Q. 0.4
|
|
142
|
-
|
|
143
|
-
**Q.
|
|
144
|
-
|
|
163
|
+
**Q. What if I don't upgrade?** — Nothing changes. 0.3.x/0.4.x stay on npm.
|
|
164
|
+
**Q. Can I stop at 0.4?** — Yes. 0.4 has compat mode; §4's checks suffice, and the unconditional 0.5
|
|
165
|
+
regime can wait until you are ready.
|
|
166
|
+
**Q. Must I turn undo on right away?** — No. §2's `unavailable` declaration (mandatory) can be the
|
|
167
|
+
end; actual handlers·UI (optional) can come any time.
|
|
168
|
+
**Q. What about the DB?** — infra 0.4.0 migrates the existing file in place. Backups are always
|
|
169
|
+
wise, but no procedure is required.
|
|
170
|
+
**Q. What if a write carries no contract?** — Every write is refused with `gate.contract_required`.
|
|
171
|
+
Solve it with auto-attach in the one write path.
|