@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.
@@ -1,144 +1,171 @@
1
- # 커널 업그레이드 가이드 — 0.3/0.4/0.5.x → 0.6
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
- 0.5.1에서 되돌리기를 실제 도메인에 처음 붙인 경험으로 계약을 4건 보정했습니다. 뼈대(새 쓰기로서의
6
- 보상, 계획 해시, 손실 확인, 보상 1회 가드, 재전송 권한 재증명)는 그대로입니다.
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
- | ① | **되돌리기 핸들러에 `compensationCommand` 선언이 필수** — 보상 커맨드 하나를 정적으로 선언. 봉인 검사가 등록 여부를 확인하고, 커널이 `plan()` 호출 **전에** 선언된 커맨드의 접근 권한을 검사(거절이면 `denied`로 답하고 계획을 만들지 않음). 계획이 다른 커맨드를 담으면 `undo.plan_invalid` | 핸들러 등록에 한 줄 추가. `mayPreview` 훅은 **선택**으로 내려감(있으면 기본 검사 뒤에 실행) — "보상 커맨드를 쓸 수 있는가"만 검사하던 훅은 삭제 |
11
- | ② | **권한 거절 어휘 통일 — `denied`** — `previewUndo`의 권한 거절(읽기 게이트·핸들러 게이트·보상 커맨드 역할/위임·거절 대상)이 `blocked` 대신 `denied`로 답함. 실행(`executeUndo`)에서도 권한 거절은 원래 단계·코드(1~3, 예: `gate.role_denied`·`gate.delegation_denied`)를 유지 — 8단계 재포장 폐지 | `preview.status === 'blocked'` 분기에서 권한 거절을 가려내던 앱 코드는 `denied` 분기 추가(작업 사실이 없음을 전제로 처리) |
12
- | ③ | **기본 원본 읽기 게이트 `registerUndoReadGate`** — 앱 전체의 `mayRead`를 한 번 등록. 정책 항목의 `mayRead`가 있으면 그것이 우선 | 같은 함수를 이벤트 유형 수만큼 붙이던 조립은 한 번 등록으로 교체. 부팅 조건: "모든 정책에 mayRead 있음 **또는** 기본 게이트 등록"(둘 다 없으면 부팅 실패 — 읽기 권한은 선언된 결정이라는 원칙 유지) |
13
- | ④ | **`undoStatus` 상한** — `sourceSeqs`가 `UNDO_STATUS_MAX_SEQS`(100)를 넘으면 4단계 입력 거절(`gate.schema_invalid`). 100건을 넘기며 앞 100건만 조용히 처리하던 절단 폐지 | 100건 넘는 조회를 하던 화면은 페이지 처리. 상수는 커널에서 export |
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
- 커널 버전 **0.6.0**(핸들러 필수 필드 추가 = 0.x의 breaking → minor 범프), `PROTOCOL_VERSION` **1.1.0**
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 (0.6.0 후속 보정 — 패치)
20
+ ### 0.6.1 (follow-up corrections — patch)
19
21
 
20
- 0.6.0을 실제로 검토하며 재현된 두 불일치를 고쳤습니다. 공개 타입은 그대로라 `^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
- | ① | **상태 조회와 미리보기가 같은 신원에게 같은 답을 한다** — 보상 커맨드 접근 검사가 공유 판정 안으로 이동. 권한 없는 신원의 `undoStatus` 행이 `supported`(handlerId 포함) 대신 `denied`(코드만)로 답한다 | 없음(교정). `mayPreview`가 "보상 커맨드를 쓸 수 있는 신원인가" 확인뿐이면 **이제 제거해도 상태 조회가 올바르게 답한다** — 커널이 계획 앞에서 검사함 |
25
- | ② | **재전송 재증명이 미리보기 상태와 무관** — 저장된 보상이 있으면 현재 정책(지원·미지원·혼합 무관)과 무관하게 기록된 봉투(커맨드·기록된 대상)로 권한 재증명. 커맨드가 제거됐으면 재료 부재로 거절 | 권한이 회수된 뒤 같은 requestKey 재요청이 거절되는 것은 의도된 동작(기존 원칙의 누락 복원) |
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
- 쓰는 앱은 **infra ^0.6.0 짝(infra-sqlite·infra-postgres 0.5.0)**으로 함께 올려야 로컬 워크스페이스
29
- 커널과 연결됩니다(^0.5.0은 0.6.0과 맞지 않아 npm이 레지스트리 0.5.x를 중첩 설치합니다).
30
- 카탈로그 되돌리기 정책 항목에
31
- `compensationCommand`가 함께 공개되므로 `catalogRevision`이 이동합니다 — 재접속 시 `catalog_status`로
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로 만든 앱을 **0.5.0**으로 올리는 안내.
40
+ Moving an app built on `@sudoke/kernel` 0.3.x/0.4.x to **0.5.0**.
38
41
 
39
- > **0.5.0은 방향이 다릅니다.** 0.4까지는 계약 체제가 선택(strict 모드)이었지만, 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
- > **자동으로 올라가지 않습니다.** semver 0.x에서 `^0.4.0`은 0.5를 포함하지 않습니다 —
44
- > 이 가이드는 직접 버전을 올리기로 한 앱을 위한 문서입니다. 올리지 않으면 아무 것도 바뀌지 않습니다.
45
- > 0.4까지만 올려 점진적으로 적응하는 것도 좋습니다(0.4는 여전히 compat 모드가 있습니다).
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은 **기존 DB를 그대로** 씁니다 — 부팅 시 events 테이블에 meta 열이 없으면 그 자리에서 추가합니다(무손실 마이그레이션). 데이터 이동·백업 복원이 필요 없습니다.
61
- - `@sudoke/infra-postgres`를 쓰는 앱도 같은 규칙(`^0.4.0`, `ADD COLUMN IF NOT EXISTS`).
62
- - 커널 API 상세는 [packages/kernel/README.md](../README.md) (영어, 이 패키지에 동봉).
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의 부팅 검사는 전부 **무조건**입니다. 봉인(첫 실행 또는 명시적 seal) 시점에:
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
- | 커맨드·조회 버전 | 모든 커맨드와 조회에 `version: '1.0.0'` 같은 semver 선언 |
71
- | 되돌리기 정책 | 등록된 **모든 이벤트 유형**에 정책 — `{kind:'supported', handlerId}` 또는 `{kind:'unavailable', code, reason}`. 지원은 선택이지만 **선언은 필수** (없는 침묵은 결함) |
72
- | 읽기 권한 훅 | 모든 정책에 `mayRead`, 모든 핸들러에 `mayPreview` — "누가 되돌림 내역을 읽나"는 선언된 결정이어야 함 |
73
- | 저장소 능력 | 물리 엔진이 operationLedger 제공 (infra ^0.4.0이면 이미 갖춰짐) |
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부터 이 표의 두 행이 바뀝니다** — 읽기 권한은 "모든 정책 `mayRead` **또는** 앱 전체 기본 게이트
76
- > (`registerUndoReadGate`) 한 번", 핸들러 요건은 `mayPreview` 대신 **보상 커맨드 선언
77
- > (`compensationCommand`, 필수)**. 자세한 이행은 맨 위 §0의 ①·③을 보세요. infra 짝 버전도
78
- > ^0.5.0 → ^0.6.0(infra 0.5.0)으로 올라야 로컬 워크스페이스 커널과 연결됩니다.
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: '이 이벤트는 되돌림 없음', mayRead: async () => {} },
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
- (이때 `app.not_reversible` 코드는 `registerErrorCodes`에 등록돼 있어야 합니다.)
97
+ (The `app.not_reversible` code must be registered in `registerErrorCodes`.)
93
98
 
94
- ## 3. 모든 쓰기에 계약 첨부 — **0.5.0의 핵심 변화**
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
- { ...비즈니스입력, contract: { commandVersion, commandRevision, protocolVersion } }
104
+ { ...businessInput, contract: { commandVersion, commandRevision, protocolVersion } }
100
105
  ```
101
106
 
102
- - 없으면 `gate.contract_required`, 낡았으면 `gate.contract_changed` — **거부는 계약을 다시 읽으라는 안내**입니다(recovery: refresh).
103
- - **통로 한 곳에서 해결합니다**: 화면·스크립트의 api 클라이언트(runCommand 같은 공통 함수)가 카탈로그 상태를 캐시해 자동 첨부합니다. 호출부 전면 수정은 필요 없습니다.
104
- - **`gate.contract_changed`를 받으면 재학습이 먼저입니다**: ① 카탈로그 상태와 변경 내용(`catalog_changes`·`command_contract`)을 읽고 ② 무엇이 바뀌었는지(버전·입력 의미·경고) 확인한 뒤 ③ 기존 요청의 의미가 그대로 유효한지 판단합니다. **revision만 바꿔 자동 재전송하는 것은 안전하지 않습니다** — 같은 숫자라도 단위가 센트에서 달러로 바뀐 MAJOR 변경이라면 새 계약 검사는 통과하지만 사용자의 원래 의도와 다른 금액으로 실행될 수 있습니다. 커널은 "호출자가 새 계약을 이해했는지"를 증명할 수 없습니다.
105
- - **자동 재시도는 의미 보존을 확인할 수 있을 때만**: 변경 기록이 "설명 문구만 바뀜"처럼 입력 의미에 닿지 않음을 **앱이 명시적으로 판정할 수 있는 경우에만** 재시도를 자동화하고, 그 판정 근거를 코드에 남기세요. "같은 MAJOR 안"이라는 사실만으로 의미 확인을 대체할 수 없습니다. 판단이 서지 않으면 호출자·에이전트에게 새 계약을 보여주고 요청을 다시 구성하게 합니다.
106
- - 멱등 재전송(requestKey 재요청)은 계약 검사보다 **먼저** 판정됩니다 — 이미 저장된 성공은 오늘의 스키마가 바뀌었어도 그대로 반환됩니다.
107
- - MCP 도구는 `contract` 파라미터를 받습니다 — 외부 에이전트는 카탈로그(`command_contract` 도구)를 먼저 읽고 첨부합니다.
108
-
109
- ## 4. 함께 달라진 것 (0.4 변경분 포함)
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
- | ① | 카탈로그 문서·상태의 버전 필드명 `version` → **`catalogVersion`** (옛 이름 alias 폐지) | 커널 카탈로그를 읽는 코드만 필드명 교체 (앱이 스스로 내놓는 상태 응답은 무관) |
114
- | ② | 카탈로그 커맨드 항목의 `fields`가 **문서화되지 않은 필드까지 전부 나열** (값 `null`) | fields를 순회하는 코드에서 `null` 처리 |
115
- | ③ | MCP `tools/list`에 공통 도구 7종 추가 — `catalog`·`catalog_status`·`catalog_changes`·`command_contract`·`undo_status`·`undo_preview`·`undo_execute` | 도구 이름을 검증하는 목록(테스트 포함) 갱신 — 전부 snake_case |
116
- | ④ | **재전송(멱등 재생)이 권한을 재증명** — 저장된 성공의 재요청은 기록된 역할·위임 범위·현행 할당으로 다시 판정 | 권한이 회수된 뒤 같은 requestKey로 재요청하던 흐름은 이제 거부(의도된 동작). **생산자 추적 이전의 오래된 행**도 재증명 재료가 없어 거부됩니다(예전의 `{unknown:true}` 마커 폐지) |
117
- | ⑤ | MCP 쓰기 값이 직접 API와 동일해짐 — 이중 정규화(coerce·trim 두 번) 제거 | 수정 불필요. 미묘하게 값이 달라지던 앱은 이제 같음 |
118
- | ⑥ | 재생 응답에 `producedBy`(그 결과를 만든 계약) 부가 | 무시해도 됨 (부가 필드) |
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
- 새 오류 코드: `gate.contract_required`·`gate.contract_changed`(§3)와 `undo.*` 10종(되돌리기를 켠 앱만) — **코드 목록을 전수 검증하는 앱만** 사전 갱신.
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. 여기서부턴 선택 — 필수 조립(§2)과 구분해서 읽으세요
140
+ ## 5. From here it is optional — read separately from the mandatory assembly (§2)
123
141
 
124
- - **되돌리기 실행 기능** — §2의 정책 선언과 `mayRead`는 **필수 조립 요건**입니다. 선택인 것은 그 다음: `{kind:'supported', handlerId}`로 실제 핸들러(`registerUndoHandler` — 플랜 계산·`mayPreview`)를 붙여 `previewUndo`·`executeUndo`·`undoStatus`를 켜는 일. `unavailable` 선언만으로 끝내도 0.5.0은 완전히 부팅·동작합니다. 되돌림은 순방향 보상(새 쓰기)이고 원본 이력은 불변입니다.
125
- - **계약 발견 도구** — `command_contract`(커맨드 하나의 기계 판독 계약)·`catalog_status`·`catalog_changes`(재접속 시 변경분만). 쓰지 않아도 무방합니다.
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. 의존성 범프(§1) → npm install
131
- 2. 부팅 요건 충족(§2) — 버전 선언·되돌리기 정책·mayRead — 앱을 켜서 부팅 확인
132
- 3. 쓰기 통로에 계약 자동 첨부(§3) — contract_changed는 재학습 후 재구성, 자동 재시도는 의미 보존 판정이 있을 때만(§3)
133
- 4. §4의 확인(① 카탈로그 필드명 ② fields null ③ 도구 목록 ④ 재전송 권한)
134
- 5. 앱 자체 검증 실행 (스모크/MCP/정책 — 각 앱의 것)
135
- 6. (선택) 되돌리기 도입은 별도 작업으로 — §5
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. 안 올리면?** — 아무 변화 없음. 0.3.x/0.4.x는 그대로 npm에 있습니다.
141
- **Q. 0.4까지만 올려도 되나요?** — 됩니다. 0.4는 compat 모드가 있어 §4의 확인만으로 충분하고, 0.5의 무조건 체제는 준비되면 갑니다.
142
- **Q. 되돌리기를 바로 켜야 하나요?** — 아니요. §2의 `unavailable` 선언(필수)으로 끝낼 수 있고, 실제 핸들러·UI 도입(선택)은 나중에 언제든.
143
- **Q. DB는?** — infra 0.4.0이 기존 파일을 그 자리에서 마이그레이션합니다. 백업은 늘 권장하지만 절차는 필요 없습니다.
144
- **Q. 계약 첨부를 안 하면?** — 모든 쓰기가 `gate.contract_required`로 거부됩니다. 통로 한 곳에서 자동 첨부로 해결하세요.
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.