@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 CHANGED
@@ -241,22 +241,18 @@ npm run validate:releases <previous.json|null> <current.json> # release manife
241
241
  `validate:releases` is a REPOSITORY check command — `scripts/` is deliberately outside the published
242
242
  `files` list; installed consumers validate manifests through `validateReleaseManifest` (exported).
243
243
 
244
- ## Builder guides (Korean — shipped in this package)
245
-
246
- The guides below ship inside the npm tarball (`docs/`), so agents building an app on the kernel need
247
- nothing but the installed package:
248
-
249
- - [docs/kernel-upgrade-guide.md](docs/kernel-upgrade-guide.md) — upgrading an app across kernel
250
- versions (dependency pairing, boot requirements, the contract-carried writes and how to migrate).
251
- - [docs/undo-scope-guide.md](docs/undo-scope-guide.md) — deciding which event types to open to the
252
- common undo, and what a domain·surface must provide for each.
253
- - [docs/domain-development-guide.md](docs/domain-development-guide.md) — writing a domain: commands,
254
- policies, projections, event contracts, the check suite.
255
- - [docs/surface-development-guide.md](docs/surface-development-guide.md) — building a surface over
256
- the kernel's catalog·queries (UI conventions, the shared check).
257
-
258
- ## Upgrading from 0.3.x
259
-
260
- See [the upgrade guide](docs/kernel-upgrade-guide.md) — dependency bumps, the 0.4→0.5 check items
261
- (`catalogVersion` rename, full `fields` listing, new MCP common tools, replay rights re-proof) and
262
- the now-mandatory contract regime.
244
+ ## Builder guides (shipped in this package)
245
+
246
+ The guides below ship inside the npm tarball (`docs/`), so an agent building an app on the kernel
247
+ needs nothing beyond the installed package (`node_modules/@sudoke/kernel/docs/`). The links resolve
248
+ through unpkg, which serves the published tarball directly:
249
+
250
+ - [Domain development guide](https://unpkg.com/@sudoke/kernel/docs/domain-development-guide.md) —
251
+ writing a domain: commands, policies, projections, event contracts, the check suite.
252
+ - [Surface development guide](https://unpkg.com/@sudoke/kernel/docs/surface-development-guide.md) —
253
+ building a surface over the kernel's catalog·queries (UI conventions, the shared check).
254
+ - [Undo scope guide](https://unpkg.com/@sudoke/kernel/docs/undo-scope-guide.md) — deciding which
255
+ event types to open to the common undo, and what a domain·surface must provide for each.
256
+ - [Kernel upgrade guide](https://unpkg.com/@sudoke/kernel/docs/kernel-upgrade-guide.md) — upgrading
257
+ an app across kernel versions (dependency pairing, boot requirements, contract-carried writes,
258
+ migration).
@@ -1,96 +1,130 @@
1
- # 도메인 개발 가이드 — 커맨드를 작성하는 법
2
-
3
- > 이 문서는 도메인을 개발하는 에이전트에게 필요한 실무 지식을 담는다.
4
- > 배경과 원리가 궁금하면 정의서로, 지금 커맨드를 만들어야 하면 이 문서를 본다.
5
-
6
- 새 앱 개발의 실질적인 일은 "커맨드를 잘 쓰는 것"이다. 커맨드 하나 = 하나의 업무 의도(신청서).
7
-
8
- ## 0. 계약 — 이 5줄은 예외 없음
9
-
10
- 1. **모든 쓰기는 커맨드다** — `execute()`는 **이벤트만 반환**한다. DB 직접 수정(UPDATE·INSERT·DELETE)을 하지 않는다. 투영 적용·감사 기록은 커널이 같은 트랜잭션에서 한다.
11
- 2. **거절은 GateError + 등록된 코드** — `throw new Error`를 쓰지 않는다. 새 코드는 `domain/error-codes.ts`에 먼저 등록하고 커맨드 `errors`에 선언한다(등록 안 된 코드를 선언하면 조립이 실패).
12
- 3. **한 파일 = 한 커맨드, `commands/<오브젝트>/<동사>.ts`** — 커맨드명이 곧 경로다(`client.setRegion` → `commands/client/setRegion.ts`). 도메인 전체를 한 파일에 몰아넣지 않는다 — 등록소는 몰라도 검증·탐색이 안다.
13
- 4. **새 커맨드는 요청서 한 장에서 시작한다**(`feature-request-guide.md`) — 코드에서 시작하지 않는다.
14
- 5. **추가는 5종 세트** — 정의 파일 + 등록부 1줄 + (새 이벤트면) 계약·투영·이력 요약 + 지도 2줄 + 스모크 성공/거절 쌍. 하나라도 빠지면 빌드·조립·검증이 실패한다.
15
-
16
- **검증**: `npm run check:domain` — 세트 누락(등록부·지도·이력 요약)과 문서 수치를 기계적으로 검사한다(아래 "커밋 전 점검"과 같은 기준).
17
-
18
- ## 1. 시작은 요청서 — 자연어로 먼저 쓴다
19
-
20
- 커맨드를 만들기 전에 기획자 양식(`docs/agents/dev/feature-request-guide.md`: 한 문장 / 절차 / 규칙)을 채운다. 기술 용어 없이.
21
-
22
- - **한 문장**: "[불편한 이유] [누가 무엇을 하면] [무엇이 되기를 바란다]" — 한 문장으로 안 쓰이면 의도가 두 개다. 두 장으로 나눈다.
23
- - **절차**는 셋 중 하나: 한 번에 끝나는 일(대부분) / 상태를 거치는 일(예: 제안→확정) / 한 번에 몰아서 해야 하는 묶음(예: 이체). 이 선택이 구조(단순 커맨드 / 상태 절차 / 묶음 처리)를 결정한다.
24
- - **규칙은 거절로 옮길 수 있게**: "적절히 관리한다" ❌ → "이미 확정된 건은 다시 제안할 수 없다" ⭕ — 형식(부정문·긍정문)은 자유이되, 어기는 시도를 거절로 옮길 수 있어야 게이트 검증·테스트가 된다.
25
-
26
- 번역 대응: 문장의 **행동 → 커맨드**, **바라는 결과 → 도메인 이벤트**, **절차 → 전이표**, **규칙 → 게이트 단계(권한·전제·불변식·전이)**.
27
-
28
- 아래는 이 대응으로 실제 시스템이 만들어진 예시들이다 — 요청서 한 장이 커맨드 한 개로 번역된 사례집:
29
-
30
- | # | 1a. 불편 (은행 비유) | 1b. 행동 | 1c. 결과 | 규칙 하이라이트 | → 커맨드 |
1
+ # Domain development guide — how to write commands
2
+
3
+ > This document holds the practical knowledge an agent developing a domain needs.
4
+ > For background and principles, go to the concept documents; when you must write a command NOW,
5
+ > read this one.
6
+
7
+ The real work of building a new app is "writing commands well". One command = one business intent
8
+ (one application form).
9
+
10
+ ## 0. Contract — these 5 lines have no exceptions
11
+
12
+ 1. **Every write is a command** — `execute()` returns **events only**. No direct DB mutation
13
+ (UPDATE·INSERT·DELETE). The kernel applies projections and records audit in the same transaction.
14
+ 2. **Refusals are GateError + a registered code** — never `throw new Error`. Register new codes in
15
+ `domain/error-codes.ts` first and declare them on the command's `errors` (declaring an
16
+ unregistered code fails the assembly).
17
+ 3. **One file = one command, `commands/<object>/<verb>.ts`** — the command name IS the path
18
+ (`client.setRegion` → `commands/client/setRegion.ts`). Never pile a whole domain into one file —
19
+ the registries may not care, but the checks and navigation do.
20
+ 4. **Every new command starts from a one-page feature request** (the planner's form: one sentence /
21
+ procedure / rules) — never from code.
22
+ 5. **An addition is a five-part set** — the definition file + one registry line + (for a new event
23
+ type) contract·projection·history summary + two map lines + a smoke success/refusal pair. Missing
24
+ any one part fails the build·assembly·checks.
25
+
26
+ **Check**: `npm run check:domain` — mechanically verifies the set (registry·maps·history summary)
27
+ and the documented counts (the same bar as "before you commit" below).
28
+
29
+ ## 1. Start from the request — write it in plain language first
30
+
31
+ Before writing a command, fill in the planner's form (one sentence / procedure / rules) — with no
32
+ technical terms.
33
+
34
+ - **One sentence**: "[why it hurts] [someone does something] [what should become true]" — if it will
35
+ not fit in one sentence, the intent is two. Split it into two requests.
36
+ - **The procedure is one of three**: a one-shot task (most) / a state-passing task (e.g.
37
+ propose→confirm) / a bundle that must go at once (e.g. a transfer). This choice decides the shape
38
+ (a plain command / a state machine / a batch).
39
+ - **Rules must translate into refusals**: "manage it appropriately" ❌ → "a confirmed item cannot be
40
+ proposed again" ⭕ — positive or negative phrasing is free, but violating the rule must be
41
+ expressible as a refusal, or the gate cannot verify it and the tests cannot check it.
42
+
43
+ Translation mapping: the sentence's **action → a command**, **desired outcome → a domain event**,
44
+ **procedure → the transition table**, **rules → gate stages (rights·preconditions·invariants·
45
+ transitions)**.
46
+
47
+ Below are real examples built through this mapping — a casebook of one-page requests translated
48
+ into single commands:
49
+
50
+ | # | 1a. Pain (bank analogy) | 1b. Action | 1c. Outcome | Rule highlights | → command |
31
51
  | --- | --- | --- | --- | --- | --- |
32
- | 1 | 통장 거래 내역에 메모를 못 붙임 | 작성자가 메모를 고친다 | 수정 이력이 남은 채 반영 | 작성자만 / 동시 수정 거절 / 흔적 보존 | note.update |
33
- | 2 | 그만둔 직원의 결재권이 남아있음 | 관리자가 결재권을 회수한다 | 그 고객 창구 업무 즉시 불가 | 즉시 효력 / 회수 기록 | client.unassignManager |
34
- | 3 | 계좌가 잘못된 상품 아래에 있음 | 관리자가 상품을 바꿔 옮긴다 | 하위 계좌까지 함께 이동 | 사이클 금지 / depth 유지 / 동명 거절 / 연결 유지 | function.move |
35
- | 4 | 고객이 상호를 변경함 | 관리자가 예금주 명의를 고친다 | 전 화면 반영 | 계좌번호(코드) 불변 | client.rename |
36
- | 5 | 직원의 직급이 바뀜 | 관리자가 직급을 바꾼다 | 즉시 권한 반영 | 직급 내리면 담당 계좌 무관 즉시 박탈 | user.setRole |
37
- | 6 | 퇴사한 직원 처리 | 관리자가 사번을 비활성화한다 | 로그인·권한 즉시 소멸 | 거래 기록 보존 / 재활성 가능 | user.setActive |
38
- | 7 | 해지된 자회사 계좌가 목록에 남음 | 관리자가 계좌를 해지 상태로 둔다 | 조회에서 제외 | 신규 거래 금지 / 거래 내역 보존 / 재개 가능 | client.setActive |
39
-
40
- 읽는 법: 세로로 보면 각 열이 번역 결과와 정렬된다 — **불편은 배경으로 남고, 행동이 커맨드가 되고, 결과가 이벤트가 되고, 규칙이 게이트 검증이 된다.** "즉시 불가/즉시 소멸" 같은 규칙은 실행 순간마다 게이트가 다시 검사하므로 별도 동기화 코드가 필요 없다.
41
-
42
- **접수 — 사용자에게 묻는 법.** 사용자에게 받는 것은 의도(불편·행동·결과)로 충분하다 — 절차 선택·행동 분리·규칙 문구는 에이전트가 표준 패턴과 도메인 정의에서 초안으로 채운다(기획자는 여전히 최대한 채워 오는 것이 좋다). 채우다가 **사용자의 판단이 필요한 것** — 정책(허용/금지), 운영 사실("당일 이체 마감은 몇 시인가"), 데이터 범위(무엇을 저장할지) — 을 발견하면 그 자리에서 정답을 지어 쓰지 말고 **순서대로 하나씩** 묻는다: 선택지와 추천을 함께 붙여 답이 한 단어로 끝나게. 받은 답은 요청서의 규칙 칸에 옮겨 적는다 — 확정된 요청서만 계약이고, 안 쓴 것은 지켜지지 않는다.
43
-
44
- ## 2. 커맨드 정의 양식 — 각 칸이 게이트 단계와 연결된다
52
+ | 1 | Cannot attach memos to account transactions | the author edits the memo | reflected with an edit trail | author only / concurrent edit refused / trail preserved | note.update |
53
+ | 2 | A departed employee's approval rights linger | an admin revokes the approval right | that client's counter service is immediately unavailable | immediate effect / revocation recorded | client.unassignManager |
54
+ | 3 | An account sits under the wrong product | an admin moves it | descendant accounts move together | no cycles / depth kept / same-name refused / links kept | function.move |
55
+ | 4 | A client changed its trade name | an admin corrects the account holder name | reflected on every screen | the account number (code) is immutable | client.rename |
56
+ | 5 | An employee's title changed | an admin changes the title | rights reflect immediately | a demotion strips assigned accounts at once, unconditionally | user.setRole |
57
+ | 6 | Handling a departed employee | an admin deactivates the employee number | login·rights vanish immediately | transaction history preserved / reactivatable | user.setActive |
58
+ | 7 | A dissolved subsidiary's accounts linger in lists | an admin marks the account dissolved | excluded from queries | new transactions forbidden / history preserved / reopenable | client.setActive |
59
+
60
+ How to read it: read vertically and each column aligns with a translation output — **the pain stays
61
+ as background, the action becomes the command, the outcome becomes the event, the rules become gate
62
+ checks.** Rules like "immediately unavailable / vanishes immediately" are re-checked by the gate at
63
+ every execution, so no separate synchronization code is needed.
64
+
65
+ **Intake — how to ask the user.** What you take from the user is the intent (pain·action·outcome),
66
+ and that is enough — the procedure choice, the action splitting and the rule wording are drafted by
67
+ the agent from standard patterns and the domain definitions (planners should still fill in as much
68
+ as they can). While filling, when you hit something that **needs the user's judgment** — a policy
69
+ (allow/deny), an operational fact ("what time is the same-day transfer cutoff?"), a data scope (what
70
+ to store) — never invent the answer on the spot; ask **one at a time, in order**: attach options and
71
+ a recommendation so the answer fits in one word. Write every answer back into the request's rules
72
+ column — only the confirmed request is a contract; what is not written is not kept.
73
+
74
+ ## 2. The command definition form — every field connects to a gate stage
45
75
 
46
76
  ```ts
47
77
  {
48
- name: 'client.recode', // 오브젝트.동사 — REST·MCP 툴 이름의 원천 (배포 후 불변)
49
- description: '고객 코드 변경 — …', // 카탈로그에 그대로 노출 (에이전트가 읽는다)
78
+ name: 'client.recode', // object.verb — the source of the REST·MCP tool name (immutable after deployment)
79
+ description: 'Change a client code — …', // exposed verbatim in the catalog (agents read it)
50
80
  example: 'POST /api/commands/client.recode {"clientId":"…","newCode":"DAEHYUN"}',
51
- allowedRoles: ['admin'], // ③ 정책: 누가
52
- scope: 'none' | 'client', // ③ 정책: 담당 범위 검사 대상 여부
53
- targetOf: (i) => i.clientId, // ③ 정책: 범위 검사가 쓸 고객 추출기 (scope:'client'일 때, 동기)
54
- input: z.object({ … }), // ④ 스키마 — 필드마다 .describe() (카탈로그 설명의 원천)
55
- output: z.object({ … }).strict(), // ⑧ 실행 — 성공 result의 모양 (게이트가 커밋 전에 검사·위반 시 롤백)
56
- errors: ['client.code_conflict'], // 이 커맨드가 낼 수 있는 업무 오류 코드 (카탈로그에 공개)
57
- transition: { machine, command, current: async (i) => ({ id, status }) }, // ⑦ 전이 — 상태가 있는 도메인만
58
- precondition: async (i) => {}, // ⑤ 전제조건 — "존재하는가" (거절은 GateError+코드로)
59
- invariants: async (i, identity) => {}, // ⑥ 불변식 — "규칙에 맞는가" (요청서의 규칙이 여기 들어간다)
60
- execute: async (i, identity) => ({ events, result }), // ⑧ 실행 — 이벤트만 반환 (result는 output과 대조된다)
61
- version: '1.0.0', // 선택(2026-11-13) — 커맨드 계약의 호환성 버전. strict 조립에서는 필수
62
- behaviorRevision: '…', // 선택 — 지문이 못 잡는 의미 변화(함수 몸통·업무 로직)를 바꿀 때 직접 선언
81
+ allowedRoles: ['admin'], // ③ policy: who
82
+ scope: 'none' | 'client', // ③ policy: whether the assignment-scope check applies
83
+ targetOf: (i) => i.clientId, // ③ policy: the client extractor the scope check uses (when scope:'client', synchronous)
84
+ input: z.object({ … }), // ④ schema — .describe() on every field (the source of catalog descriptions)
85
+ output: z.object({ … }).strict(), // ⑧ execution — the shape of a successful result (the gate checks it before commit·rolls back on mismatch)
86
+ errors: ['client.code_conflict'], // business error codes this command can produce (published in the catalog)
87
+ transition: { machine, command, current: async (i) => ({ id, status }) }, // ⑦ transition — stateful domains only
88
+ precondition: async (i) => {}, // ⑤ precondition — "does it exist" (refuse with GateError+code)
89
+ invariants: async (i, identity) => {}, // ⑥ invariants — "is it allowed by the rules" (the request's rules land here)
90
+ execute: async (i, identity) => ({ events, result }), // ⑧ execution — returns events only (result is checked against output)
91
+ version: '1.0.0', // required — the command contract's compatibility semver
92
+ behaviorRevision: '…', // optional — declare by hand when a meaning the fingerprint cannot capture changes (function bodies·business logic)
63
93
  }
64
94
  ```
65
95
 
66
- **저장을 읽는 훅은 전부 async다** — `transition.current`·`precondition`·`invariants`·`execute`는 `async`로 선언하고 안의 `db.prepare(…).get/all/run(…)`마다 `await`를 붙인다(저장 포트가 비동기 계약이므로). `targetOf`만 동기다(입력에서 id를 뽑는 순수 함수 — 저장을 안 읽는다). db를 읽지 않는 훅도 `async`는 붙인다 — 계약이 Promise 반환을 요구한다.
96
+ **Every hook that reads storage is async** — declare `transition.current`·`precondition`·
97
+ `invariants`·`execute` as `async` and `await` every `db.prepare(…).get/all/run(…)` inside (the
98
+ storage port is an async contract). Only `targetOf` is synchronous (a pure function extracting an id
99
+ from the input — it reads no storage). Hooks that read nothing still take `async` — the contract
100
+ requires a Promise.
67
101
 
68
- 거절 throw의 형태 — 문장(reason)과 기계용 계약(code)을 함께:
102
+ The refusal throw — the human sentence (reason) and the machine contract (code) together:
69
103
 
70
104
  ```ts
71
- throw new GateError(5, 'precondition', '고객이 존재하지 않습니다', {
72
- code: 'client.not_found', // domain/error-codes.ts에 등록된 코드 (문구가 바뀌어도 유지)
73
- recovery: { query: 'clients' }, // 선택: refresh 행동에서 다시 읽을 조회
105
+ throw new GateError(5, 'precondition', 'Client not found', {
106
+ code: 'client.not_found', // a code registered in domain/error-codes.ts (survives wording changes)
107
+ recovery: { query: 'clients' }, // optional: the query the refresh action re-reads
74
108
  })
75
109
  ```
76
110
 
77
- ### 실제 파일 전체 — `client/setRegion.ts` (여기서 복사해 시작한다)
111
+ ### A complete real file — `client/setRegion.ts` (copy this to start)
78
112
 
79
113
  ```ts
80
114
  import { z } from 'zod'
81
115
  import { db, GateError, type CommandDefinition } from '@sudoke/kernel'
82
116
  const input = z.object({
83
- clientId: z.string().uuid().describe('고객 id'),
84
- region: z.enum(['domestic', 'overseas']).describe('변경할 국내/해외 (domestic=국내, overseas=해외)'),
117
+ clientId: z.string().uuid().describe('client id'),
118
+ region: z.enum(['domestic', 'overseas']).describe('the region to set (domestic | overseas)'),
85
119
  })
86
120
  const output = z.object({
87
- clientId: z.string().uuid().describe('고객 id'),
88
- region: z.enum(['domestic', 'overseas']).describe('변경된 국내/해외 값'),
121
+ clientId: z.string().uuid().describe('client id'),
122
+ region: z.enum(['domestic', 'overseas']).describe('the region after the change'),
89
123
  }).strict()
90
124
 
91
125
  export const clientSetRegion: CommandDefinition<z.infer<typeof input>, z.infer<typeof output>> = {
92
126
  name: 'client.setRegion',
93
- description: '고객의 국내/해외 변경 (관리자만)',
127
+ description: "Change a client's region (admins only)",
94
128
  example: 'POST /api/commands/client.setRegion {"clientId":"…","region":"overseas"}',
95
129
  allowedRoles: ['admin'],
96
130
  scope: 'none',
@@ -99,12 +133,12 @@ export const clientSetRegion: CommandDefinition<z.infer<typeof input>, z.infer<t
99
133
  errors: ['client.not_found', 'client.same_region'],
100
134
  precondition: async (i) => {
101
135
  if (!(await db.prepare(`SELECT id FROM clients WHERE id=?`).get(i.clientId)))
102
- throw new GateError(5, 'precondition', '고객이 존재하지 않습니다', { code: 'client.not_found', recovery: { query: 'clients' } })
136
+ throw new GateError(5, 'precondition', 'Client not found', { code: 'client.not_found', recovery: { query: 'clients' } })
103
137
  },
104
138
  execute: async (i, identity) => {
105
139
  const c = (await db.prepare(`SELECT name, region FROM clients WHERE id=?`).get(i.clientId)) as any
106
140
  if (c.region === i.region)
107
- throw new GateError(5, 'precondition', `이미 ${i.region === 'domestic' ? '국내' : '해외'}입니다`, { code: 'client.same_region' })
141
+ throw new GateError(5, 'precondition', `Already ${i.region}`, { code: 'client.same_region' })
108
142
  return {
109
143
  events: [
110
144
  {
@@ -120,119 +154,194 @@ export const clientSetRegion: CommandDefinition<z.infer<typeof input>, z.infer<t
120
154
  }
121
155
  ```
122
156
 
123
- ### 5종 세트 — 정의 파일 밖에 손대는 곳
157
+ ### The five-part set — what you touch beyond the definition file
124
158
 
125
159
  ```ts
126
- // ① 등록부 (src/domain/commands/index.ts) — import 1줄 + 배열에 이름
160
+ // ① the registry (src/domain/commands/index.ts) — one import + the name on the export list
127
161
  import { clientSetRegion } from './client/setRegion.js'
128
- // … export 목록에 clientSetRegion 추가
162
+ // … add clientSetRegion to the export list
129
163
 
130
- // ② 이벤트 계약 (src/domain/event-contracts.ts) — 새 이벤트 타입이면
164
+ // ② the event contract (src/domain/event-contracts.ts) — when the event type is new
131
165
  'client.regionChanged': z.object({ clientId: z.string(), oldRegion: z.string(), newRegion: z.string(), changedBy: z.string() }),
132
166
 
133
- // ③ 투영 규칙 (src/domain/app-projector.ts) — on('client.regionChanged', …)
134
- // ④ 이력 요약 — 기본 서피스의 summarize switch에 한국어 한 줄 케이스 (위치는 서피스의 자유 — 앱 1은 pages/Events.tsx)
167
+ // ③ the projection rule (src/domain/app-projector.ts) — on('client.regionChanged', …)
168
+ // ④ the history summary — a one-line case in the default surface's summarize switch, in the app's language
169
+ // (placement is the surface's freedom — app 1 uses pages/Events.tsx)
135
170
  case 'client.regionChanged':
136
- return `국내/해외 변경 — ${client(p.clientId)} ${…}`
171
+ return `Region changed — ${client(p.clientId)} ${…}`
137
172
 
138
- // ⑤ 서피스 계약 지도 (src/domain/command-input-map.ts) — 입력·출력 두 지도에 각각 한 줄
173
+ // ⑤ the surface contract maps (src/domain/command-input-map.ts) — one line on each of the two maps
139
174
  'client.setRegion': InputOf<typeof clientSetRegion>
140
175
  'client.setRegion': OutputOf<typeof clientSetRegion>
141
176
  ```
142
177
 
143
178
  ```js
144
- // ⑥ 스모크 (smoke.mjs) — 성공과 거절을 항상 세트로 (거절도 계약이다)
145
- show('국내/해외 변경 성공', await call(admin, 'POST', '/api/commands/client.setRegion', { clientId: cRoots[0], region: 'overseas' }), (r) => r.ok === true && r.result.region === 'overseas')
146
- show('같은 값 재설정 → 5단계 거절', await call(admin, 'POST', '/api/commands/client.setRegion', { clientId: cRoots[0], region: 'overseas' }), (r) => r.status === 409 && r.stage === 5)
179
+ // ⑥ smoke (smoke.mjs) — always a success/refusal pair (a refusal is a contract too)
180
+ show('region change succeeds', await call(admin, 'POST', '/api/commands/client.setRegion', { clientId: cRoots[0], region: 'overseas' }), (r) => r.ok === true && r.result.region === 'overseas')
181
+ show('same value again → stage-5 refusal', await call(admin, 'POST', '/api/commands/client.setRegion', { clientId: cRoots[0], region: 'overseas' }), (r) => r.status === 409 && r.stage === 5)
147
182
  ```
148
183
 
149
- ### 선택 등록 — 계약 버전·되돌리기 (커널 2026-11-13 제공, 앱 1은 아직 미사용)
184
+ ### Undo policies and command versions (provided by the kernel)
150
185
 
151
- 커널이 공통 되돌리기 계약과 커맨드 버전·지문 관리를 제공한다(앱 1은 호환 모드라 등록 없이 그대로 동작). 쓰고 싶을 때 조립 계층에 더하는 등록 네 가지 — 계약·예제는 `packages/kernel/README.md`:
186
+ The kernel ships the common undo contract and command version·fingerprint management — a single
187
+ regime since 0.5.0 (no compat mode, no `configureKernel`): every event type declares an undo policy
188
+ at boot and every command·query declares a version. What you choose per event type is support vs
189
+ `unavailable`. Registrations added at the assembly layer — the contract and examples live in
190
+ [packages/kernel/README.md](../README.md):
152
191
 
153
192
  ```ts
154
- configureKernel({ mode: 'strict' }) // strict — 되돌리기 정책 전 커버·전 커맨드/조회 버전·쓰기 계약 지문 필수
155
- registerUndoPolicies({ 'client.deleted': { kind: 'supported', handlerId: 'client-undo' } }) // 이벤트별 되돌림 가능 여부(불가도 명시)
156
- registerUndoHandler({ id: 'client-undo', version: '1.0.0', plan: async (source, identity) => ({ … }) }) // 보상 계획(읽기 전용)
157
- registerCatalogRelease({ catalogVersion: '4.0.0', changes: […] }) // 이번 릴리스가 뭘 바꿨는지 — 변경 내역 조회·검증기의 원천
193
+ registerUndoPolicies({ 'client.deleted': { kind: 'supported', handlerId: 'client-undo' } }) // per event type — unsupported must be declared too
194
+ registerUndoHandler({ id: 'client-undo', version: '1.0.0', compensationCommand: 'client.restore', plan: async (source, identity) => ({ … }) }) // the compensation planner (read-only); declares its one compensation command
195
+ registerCatalogRelease({ catalogVersion: '4.0.0', changes: […] }) // what this release changed — the source for change queries and the release validator
158
196
  ```
159
197
 
160
- ## 3. 작성 원칙 (체크리스트)
161
-
162
- 1. **이름**: `오브젝트.동사`. 폴더=오브젝트, 파일=동사 (예: `client/recode.ts`). **커맨드명은 한 번 배포하면 불변** — 카탈로그 계약이므로 바꾸면 MAJOR 버전.
163
- 2. **execute는 순수하게**: DB를 직접 고치지 않고 **이벤트만 반환**한다. 투영(읽기 테이블) 적용과 감사 기록은 커널이 같은 트랜잭션에서 한다. 그래야 재생·감사·되돌림이 성립한다.
164
- 3. **입력·출력 필드마다 `.describe()`**: 이 설명이 카탈로그의 필드 문서가 되어 에이전트가 읽는다. description·example도 "에이전트가 읽는 설명서"라고 생각하고 쓴다.
165
- 4. **출력 계약은 필수**: `output`이 없으면 조립이 실패한다. execute의 반환 모양과 정확히 일치해야 하고(불일치는 커밋 전 8단계 거절·롤백), 반환값이 없으면 `z.null()`로 명시한다.
166
- 5. **검증의 배치**: 존재 확인은 precondition(5단계), 도메인 규칙은 invariants(6단계), 상태는 전이(7단계). **거절은 GateError + 오류 코드**로: 문구(reason)는 다음 행동을 알려주는 한국어 문장, 코드는 기계용 식별자. 새 코드는 `domain/error-codes.ts`에 먼저 등록하고(복구 행동·canForce 포함) 커맨드 `errors`에 선언 — 등록 안 된 코드를 선언하면 조립이 실패한다.
167
- 6. **위험한 일은 경고 패턴으로**: 되돌리기 어려운 삭제·병합은 그냥 실행하지 않고 **한 번 거절로 알려주고**, 확인 재시도(force:true)로만 실행 — 경고 코드는 등록소에 `canForce: true`로 표시한다. 동시에 **이벤트 payload에 스냅샷**을 남겨 복원 가능하게.
168
- 7. **공통 옵션은 커맨드에 선언하지 않는다**: `requestKey`(멱등)·`dryRun`(사전 판정)은 게이트가 커맨드 몰래 처리하는 프로토콜 옵션이다 — 커맨드의 zod 스키마에 넣지 않는다.
169
- 8. **상태가 있는 기능은 전이표를 채운다**: 커맨드마다 if-else를 짜는 게 아니라 `{from, to, command, roles}` 표를 채우면 게이트 7단계가 집행하고, 그 표는 카탈로그(transitions)에 노출돼 에이전트가 "다음 합법적 수"를 안다.
170
- 9. **되돌림 커맨드는 "대상이 사라지는" 오퍼레이션에만**: 삭제·병합 → 전용 restore를 만든다(사라진 대상은 정상 커맨드로 복구할 길이 없다). 살아있는 대상의 변경(이름·위치·상태·코드) → 되돌림 커맨드를 만들지 않는다 — 원래 값으로 다시 실행하면 복구되고(옛값은 장부 이력으로 확인), 상태가 있으면 전이표의 뒤로 가는 전이(예: 승인 취소)가 담당한다. 되돌림은 rewind가 아니라 **게이트를 통과하는 순방향 보상(새로운 쓰기)**이다 — 과거로 되감으면 그 이후의 변경과 충돌한다. (2026-11-13 — 커널이 이 원칙의 공통 계약을 제공한다: 되돌리기 등록·미리보기·실행. 위 "선택 등록" 참고. 앱이 직접 만드는 restore 커맨드와 배치되는 관계는 채택 시점에 정한다.)
171
- 10. **카탈로그는 접속자 권한별 안이다**: `allowedRoles`·위임 스코프가 같은 원천으로 카탈로그·도구 목록을 거르고, 대상 제한(`scope`≠none·위임 `커맨드:대상`)은 `restriction`으로 조건을 표시한다(커널 가시성 파생 — 실행은 게이트가 재판정). 역할 제한 조회는 **정의의 `allowedRoles`로 선언**한다(핸들러 안에서 역할을 가리지 않는다 — 실행(executeQuery)·카탈로그가 같은 선언을 쓰고, 어긴 선언은 조립이 실패한다). `public`과 `allowedRoles`는 함께 쓰지 않는다(공개 조회는 역할과 무관하므로 모순 — 조립 실패). 행 단위 범위(위임 토큰의 고객·테넌트 필터)는 여전히 핸들러가 담당한다.
172
-
173
- ## DO / DON'T — 쓰기와 거절의 형태
198
+ ## 3. Writing principles (checklist)
199
+
200
+ 1. **Name**: `object.verb`. Folder=object, file=verb (e.g. `client/recode.ts`). **A command name is
201
+ immutable once deployed** — it is a catalog contract; renaming is a MAJOR bump.
202
+ 2. **Keep execute pure**: no direct DB mutation — **return events only**. Projection application
203
+ (read tables) and audit recording happen in the kernel's transaction. That is what makes
204
+ replay·audit·undo possible.
205
+ 3. **`.describe()` on every input·output field**: those descriptions become the catalog's field
206
+ documentation that agents read. Write description·example as "the manual an agent reads".
207
+ 4. **The output contract is mandatory**: assembly fails without `output`. It must match execute's
208
+ return shape exactly (a mismatch is a stage-8 refusal before commit·rollback); declare `z.null()`
209
+ when there is nothing to return.
210
+ 5. **Where checks go**: existence → precondition (stage 5), domain rules → invariants (stage 6),
211
+ state → transitions (stage 7). **Refusals are GateError + an error code**: the reason is a
212
+ next-action sentence in the app's user language, the code is the machine identifier. Register new
213
+ codes in `domain/error-codes.ts` first (with recovery·canForce) and declare them on the command's
214
+ `errors` — declaring an unregistered code fails the assembly.
215
+ 6. **Dangerous work follows the warning pattern**: hard-to-reverse deletes·merges are not executed
216
+ outright — they **refuse once as a warning** and run only on a confirmed retry (force:true); the
217
+ warning code is marked `canForce: true` in the registry. At the same time, leave a **snapshot in
218
+ the event payload** so restoration stays possible.
219
+ 7. **Common options are never declared on the command**: `requestKey` (idempotency)·`dryRun`
220
+ (pre-judgment) are protocol options the gate handles behind the command's back — keep them out
221
+ of the command's zod schema.
222
+ 8. **Stateful features fill the transition table**: instead of if-else per command, fill the
223
+ `{from, to, command, roles}` table — stage 7 enforces it, and the table is exposed in the catalog
224
+ (transitions) so agents know "the next legal move".
225
+ 9. **Dedicated restore commands only for operations where the target VANISHES**: delete·merge →
226
+ build a restore (a vanished target has no recovery path through ordinary commands). Changes to
227
+ living targets (name·position·state·code) → build no restore command — re-running with the
228
+ original value restores it (the old value is in the ledger history), and when a state machine is
229
+ involved, the backward transition (e.g. approval cancel) owns it. Undo is not rewind — it is a
230
+ **forward compensation passing the gate (a NEW write)**; rewinding to the past collides with
231
+ everything after it. (2026-11-13 — the kernel now provides this principle's common contract:
232
+ undo registration·preview·execution. See "Undo policies and command versions" above; how
233
+ hand-made restore commands coexist with it is decided at adoption time.)
234
+ 10. **The catalog is per-accessor**: `allowedRoles`·delegation scopes filter the catalog·tool lists
235
+ from the same source, and target restrictions (`scope`≠none·delegation `command:target`) surface
236
+ as `restriction` hints (a kernel visibility derivation — the gate re-judges at execution).
237
+ Role-restricted queries are **declared through the definition's `allowedRoles`** (never
238
+ role-check inside the handler — executeQuery and the catalog share the same declaration, and a
239
+ mismatched declaration fails the assembly). `public` and `allowedRoles` are never combined (a
240
+ public query is role-independent — a contradiction; the assembly fails). Row-level scopes (a
241
+ delegation token's client·tenant filter) remain the handler's job.
242
+
243
+ ## DO / DON'T — the shape of writes and refusals
174
244
 
175
245
  ```ts
176
246
  ❌ execute: async (i) => { await db.prepare('UPDATE clients SET region=?').run(i.region); return { events: [], result: null } }
177
247
  ✅ execute: async (i) => ({ events: [{ type: 'client.regionChanged', …, payload: { … } }], result: { … } })
178
- // DB는 읽어도(조회, await) 고치지 않는다 — 상태 변화는 이벤트가 일으킨다
248
+ // the DB may be READ (queries, awaited) but never mutated — events cause every state change
179
249
 
180
- ❌ throw new Error('이미 국내입니다')
181
- ✅ throw new GateError(5, 'precondition', '이미 국내입니다', { code: 'client.same_region' })
250
+ ❌ throw new Error('already domestic')
251
+ ✅ throw new GateError(5, 'precondition', 'Already domestic', { code: 'client.same_region' })
182
252
 
183
- ❌ errors: ['client.duplicated'] // error-codes.ts에 등록 안 한 코드
184
- ✅ domain/error-codes.ts에 먼저 등록(복구 행동·canForce 포함) → errors에 선언
253
+ ❌ errors: ['client.duplicated'] // a code never registered in error-codes.ts
254
+ ✅ register it in domain/error-codes.ts first (recovery·canForce included) → then declare it in errors
185
255
 
186
- ❌ output 생략 // 조립이 실패한다
187
- ✅ output: z.object({ … }).strict() // 반환값이 없으면 z.null()
256
+ ❌ omitting output // the assembly fails
257
+ ✅ output: z.object({ … }).strict() // nothing to return → z.null()
188
258
 
189
259
  ❌ input: z.object({ name: z.string(), requestKey: z.string().optional() })
190
- ✅ input: z.object({ name: z.string() }) // requestKey·dryRun은 게이트의 프로토콜 옵션 — 넣지 않는다
260
+ ✅ input: z.object({ name: z.string() }) // requestKey·dryRun are gate protocol options — keep them out
191
261
 
192
- ❌ 나중에 커맨드명 정리: 'client.changeRegion' → 'client.setRegion'
193
- ✅ name은 배포 후 불변 — 카탈로그 계약이므로 바꾸면 MAJOR. 처음에 제대로 짓는다
262
+ ❌ renaming the command later: 'client.changeRegion' → 'client.setRegion'
263
+ ✅ name is immutable after deployment — it is a catalog contract; renaming is MAJOR. Name it right the first time
194
264
  ```
195
265
 
196
- ## 4. 새 커맨드를 추가할 때 함께할 일
266
+ ## 4. What accompanies a new command
197
267
 
198
- - 등록부 목록(`src/domain/commands/index.ts`)에 추가 → **REST·MCP에 자동 파생** (서피스는 손댈 곳 없음)
199
- - 서피스가 그 커맨드를 부르면 `domain/command-input-map.ts`의 **입력·출력 두 지도에 각각 한 줄** 추가 (빠뜨리면 서피스 빌드가 실패)
200
- - 새 이벤트 타입이면: 이벤트 계약(`domain/event-contracts.ts`) + 투영(재생) case + 이력 화면 요약 케이스 추가 (빠뜨리면 쓰기가 거절되거나 화면에 영어 타입이 그대로 보인다)
201
- - 스모크 확장 — **성공 경로와 거절 경로를 항상 세트로** (거절이 1급 결과이므로 거절도 계약이다. 코드·복구까지 대조)
202
- - 카탈로그 개수·문서 수치 갱신 + 버전 범프 (추가=minor)
268
+ - Add to the registry list (`src/domain/commands/index.ts`) → **REST·MCP derive automatically**
269
+ (surfaces touch nothing)
270
+ - When a surface calls the command, add one line to EACH of the input·output maps in
271
+ `domain/command-input-map.ts` (missing it fails the surface build)
272
+ - For a new event type: add the event contract (`domain/event-contracts.ts`) + the projection
273
+ (replay) case + a history-screen summary case (missing it refuses writes or shows the raw event
274
+ type on screen)
275
+ - Extend the smoke — **always a success path and a refusal path as a pair** (a refusal is a
276
+ first-class result — a contract; assert the code·recovery too)
277
+ - Update the catalog counts·documented numbers + a version bump (an addition = minor)
203
278
 
204
- ### 커밋 전 점검 — `npm run check:domain`과 같은 기준
279
+ ### Before you commit — the same bar as `npm run check:domain`
205
280
 
206
281
  ```bash
207
- npm run check:domain # 아래 세트 누락·수치가 기계적으로 검사된다 (위반 시 실패)
208
- npm run typecheck && npm run smoke # + mcp:test·policy:test (커널 계약·전이표·권한을 건드렸다면)
282
+ npm run check:domain # missing set parts·counts are checked mechanically (violations fail)
283
+ npm run typecheck && npm run smoke # + mcp:test·policy:test (when kernel contracts·transitions·rights are touched)
209
284
  ```
210
285
 
211
- - [ ] 등록부 1줄·지도 2줄·(새 이벤트면) 계약+투영+이력 요약 — 세트 누락 0건
212
- - [ ] 한 파일=한 커맨드, `commands/<오브젝트>/<동사>.ts` — 커맨드명이 곧 경로다
213
- - [ ] 스모크에 성공·거절 **쌍** 추가 — 거절도 계약(코드·복구까지 대조)
214
- - [ ] execute가 이벤트만 반환 — DB 직접 쓰기 0건
215
- - [ ] 새 오류 코드는 error-codes.ts에 먼저 등록했는가
216
- - [ ] 카탈로그 개수·AGENTS 수치 갱신 + 카탈로그 버전 범프(minor)
217
-
218
- ## 5. 새 앱을 시작할 때 — 체크리스트 (순서대로)
219
-
220
- 1. **도메인 정의** — 데이터(엔티티·계층) · 프로세스(상태와 전이표) · 권한(역할·고객 범위)을 먼저 표로 정리
221
- 2. **커맨드 카탈로그 설계** — 정의한 도메인을 요청서→번역(위 §1~3 절차)으로 커맨드로 쌓는다
222
- 3. **커널·물리 계층 확보** — 커널 `@sudoke/kernel`(게이트·장부·등록소·권한 판정 빈칸·장부 반영 빈칸·물리 저장 포트. 업무·물리 import 0건 — 새로 안 짜도 된다)과 물리 구현 패키지를 가져간다 — 동기 엔진이면 `@sudoke/infra-sqlite`, 네트워크 Postgres(Supabase 등)면 `@sudoke/infra-postgres`. **저장 포트는 비동기 계약이다** — 포트 계약(쓰기 잠금 선점·순차 장부 적립·멱등 유일성·겹치는 트랜잭션 직렬화)을 지키는 엔진이라면 커널은 그대로 두고 **물리 패키지만 새로 쓴다**(SQLite 구현이 동기 엔진을 감싼 예시, Postgres 구현이 네트워크 엔진의 예시다). 계약을 지킬 수 없는 엔진(트랜잭션 없는 KV 저장소 등)은 애초에 이 포트의 밖이다
223
- 4. **도메인 작성 + 조립** — 커맨드·전이표·app-policy(권한 판정)·app-projector(투영 규칙)·schema·이벤트 형식 계약·오류 코드를 쓰고 주입(assemble.ts가 단일 원천). **주입 순서: 물리 계층이 무엇보다 먼저** — `sqliteStorage({ dataDir: process.env.XXX_DATA_DIR, jwtSecret: process.env.XXX_JWT_SECRET })` 한 줄, 이어 ensureAppSchema. `db`는 여전히 `@sudoke/kernel`에서 import한다(등록된 물리 계층으로 연결되는 핸들 — 도메인 SQL 작성법은 변함없음). **모든 등록(커맨드·전이표·계약·정책·투영·프로토콜·조회·물리 계층)은 조립 시점에 끝난다 — 조립 완료 후 등록은 실패한다(등록소 봉인, assembleApp은 프로세스에 한 번)**. `--rebuild` 재구성 동작
224
- 5. **자기설명 카탈로그** — 버전·프로토콜 프리앰블(거절=결과, code·recovery·canForce, force, dry-run, requestKey, batch, 커서, 전이표)·조회 메타·전이표·오류 코드 사전. **카탈로그는 접속자 권한별로 나온다**(현재 역할·위임 범위 안의 커맨드·조회·전이 규칙만 — 서피스는 커널 가시성 파생을 쓴다)
225
- 6. **조회** — 설명·범위 표시, 공개 허용목록, 역할 제한은 정의의 `allowedRoles` 선언(생략=모든 역할), (에이전트 도입 시) 행 필터
226
- 7. **인증** — 사람 로그인 + **위임 토큰**(처음부터 actor 감사 포함). 비밀번호는 코어 로그인에서만
227
- 8. **서피스 2개로 시작** — 관리 UI 하나 + 시작 안내 페이지(첫 메시지 복사 + 위임 발급 패널)
228
- 9. **검증 자동화** — 스모크(게이트 전 단계 + 재생 검증), 검증 격리(임시 DB·자유 포트), typecheck. **계약 검사는 공유 패키지 `@sudoke/dev-checks`**(의존성 0, 파일 2개 — 커널과 함께 배포). 앱 루트 `package.json`에 등록한다:
286
+ - [ ] registry 1 line·maps 2 lines·(new event type) contract+projection+history summary — zero
287
+ missing parts
288
+ - [ ] one file=one command, `commands/<object>/<verb>.ts` — the command name is the path
289
+ - [ ] the smoke gained a success·refusal PAIR — refusals are contracts (assert the code·recovery)
290
+ - [ ] execute returns events only — zero direct DB writes
291
+ - [ ] new error codes registered in error-codes.ts first
292
+ - [ ] catalog counts·AGENTS numbers updated + a catalog version bump (minor)
293
+
294
+ ## 5. Starting a new app — checklist (in order)
295
+
296
+ 1. **Define the domain** — data (entities·hierarchy) · processes (states·transition tables) · rights
297
+ (roles·client scopes) as tables first
298
+ 2. **Design the command catalog** — build the defined domain into commands through
299
+ request→translation (§1~3 above)
300
+ 3. **Get the kernel·physical layer** — take `@sudoke/kernel` (the gate·ledger·registries·the
301
+ rights-judgment slot·the ledger-reflection slot·the storage port. Zero business·physical imports —
302
+ you never rewrite it) and a physical implementation package: a synchronous engine →
303
+ `@sudoke/infra-sqlite`, a network Postgres (Supabase etc.) → `@sudoke/infra-postgres`. **The
304
+ storage port is an async contract** — any engine honoring the port contract (write-lock
305
+ acquisition·sequential ledger appends·idempotency uniqueness·overlapping-transaction
306
+ serialization) plugs in; when needed you write only the physical package (the SQLite
307
+ implementation wraps a synchronous engine; the Postgres one is the network-engine example).
308
+ Engines that cannot honor the contract (transactionless KV stores) are outside this port to begin
309
+ with
310
+ 4. **Write the domain + assemble** — commands·transition tables·app-policy (rights judgment)·
311
+ app-projector (projection rules)·schema·event format contracts·error codes, then inject them
312
+ (assemble.ts is the single source). **Injection order: the physical layer before anything else** —
313
+ one line `sqliteStorage({ dataDir: process.env.XXX_DATA_DIR, jwtSecret: process.env.XXX_JWT_SECRET })`,
314
+ then ensureAppSchema. `db` is still imported from `@sudoke/kernel` (the handle connecting to the
315
+ registered physical layer — how you write domain SQL is unchanged). **Every registration
316
+ (commands·transitions·contracts·policies·projections·protocol·queries·physical layer) ends at
317
+ assembly time — registering after assembly fails (registry seal; assembleApp runs once per
318
+ process)**. `--rebuild` reconstructs
319
+ 5. **The self-describing catalog** — versions·the protocol preamble (refusal=result,
320
+ code·recovery·canForce, force, dry-run, requestKey, batch, cursors, transitions)·query metadata·
321
+ transition tables·the error-code dictionary. **The catalog comes out per accessor** (only the
322
+ commands·queries·transition rules inside the current role·delegation range — surfaces use the
323
+ kernel visibility derivation)
324
+ 6. **Queries** — descriptions·scope labels, the public allowlist, role restrictions declared through
325
+ the definition's `allowedRoles` (omitted = every role), row filters (when agents arrive)
326
+ 7. **Auth** — human login + **delegation tokens** (actor audit from day one). Passwords only in the
327
+ core login
328
+ 8. **Start with two surfaces** — one admin UI + a getting-started page (copy the first message + a
329
+ delegation-issue panel)
330
+ 9. **Automate the checks** — smoke (every gate stage + replay verification), check isolation (temp
331
+ DBs·free ports), typecheck. **The contract checks live in the shared package `@sudoke/dev-checks`**
332
+ (zero dependencies, two files — shipped beside the kernel). Register it in the app root
333
+ `package.json`:
229
334
  ```jsonc
230
- // 같은 저장소 안의 앱 — 의존성으로 연결(복사 금지 — 단일 원천)
335
+ // an app in the same repository — connect as a dependency (never copy — single source)
231
336
  "dependencies": { "@sudoke/dev-checks": "*" },
232
337
  "scripts": { "check:domain": "node ../dev-checks/check-domain.mjs", "check:ui": "node ../dev-checks/check-ui.mjs" }
233
338
 
234
- // 저장소 밖 앱 — 패키지의 check-domain.mjs·check-ui.mjs 두 파일을 앱 scripts/에 복사한 뒤
339
+ // an app outside the repository — copy the package's check-domain.mjs·check-ui.mjs into the app's scripts/, then
235
340
  "scripts": { "check:domain": "node scripts/check-domain.mjs", "check:ui": "node scripts/check-ui.mjs" }
236
341
  ```
237
- 앱 루트에서 `npm run check:domain`·`npm run check:ui`로 실행한다 — 도메인 파일 이름(commands/·event-contracts·app-projector·command-input-map)이 이 가이드 구조 그대로여야 검증이 돈다(이력 요약의 위치만 서피스의 자유다).
238
- 10. **운영 규칙** — 백업=데이터 디렉터리 하나, 카탈로그 버전 범프 규칙, 요청서 절차로 기능 추가, 시드·데모는 자연스러운 이름으로(데모의 품질이 검증의 품질)
342
+ Run from the app root: `npm run check:domain`·`npm run check:ui` — the domain file names
343
+ (commands/·event-contracts·app-projector·command-input-map) must match this guide's structure for
344
+ the checks to run (only the history summary's placement is the surface's freedom)
345
+ 10. **Operations** — backup = the one data directory, catalog version-bump rules, feature additions
346
+ through the request procedure, seeds·demo data in natural names (the demo's quality is the
347
+ checks' quality)