@wowok/skills 1.2.4 → 1.2.6

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.
Files changed (53) hide show
  1. package/README.md +34 -16
  2. package/dist/cli.js +6 -2
  3. package/dist/cli.js.map +1 -1
  4. package/dist/skills.d.ts +32 -1
  5. package/dist/skills.d.ts.map +1 -1
  6. package/dist/skills.js +63 -0
  7. package/dist/skills.js.map +1 -1
  8. package/dist/types.d.ts +8 -0
  9. package/dist/types.d.ts.map +1 -1
  10. package/examples/Insurance/Insurance.md +543 -475
  11. package/examples/MyShop/MyShop.md +865 -746
  12. package/examples/MyShop_Advanced/MyShop_Advanced.md +1520 -1376
  13. package/examples/ThreeBody_Signature/ThreeBody_Signature.md +891 -651
  14. package/examples/Travel/Travel.md +952 -848
  15. package/package.json +2 -2
  16. package/scripts/install.js +3 -17
  17. package/wowok-arbitrator/SKILL.md +18 -57
  18. package/wowok-auditor/SKILL.md +16 -12
  19. package/wowok-distill/SKILL.md +237 -0
  20. package/wowok-guard/SKILL.md +40 -354
  21. package/wowok-machine/SKILL.md +21 -127
  22. package/wowok-messenger/SKILL.md +14 -59
  23. package/wowok-onboard/SKILL.md +42 -12
  24. package/wowok-order/SKILL.md +20 -169
  25. package/wowok-output/SKILL.md +0 -10
  26. package/wowok-planner/SKILL.md +29 -9
  27. package/wowok-provider/SKILL.md +72 -32
  28. package/wowok-safety/SKILL.md +8 -80
  29. package/wowok-scenario/SKILL.md +70 -102
  30. package/wowok-tools/SKILL.md +68 -107
  31. package/references/glossary.ts +0 -297
  32. package/references/guard-scenario-ledger.md +0 -353
  33. package/references/guard-template-library.md +0 -481
  34. package/references/machine-design-reference.md +0 -398
  35. package/references/machine-scenario-ledger.md +0 -227
  36. package/references/machine-template-library.md +0 -522
  37. package/references/merchant-scenario-coordination.md +0 -383
  38. package/references/object-collaboration.md +0 -362
  39. package/references/onchain-constants.md +0 -81
  40. package/wowok-arbitrator/APPENDIX.md +0 -545
  41. package/wowok-auditor/APPENDIX.md +0 -487
  42. package/wowok-guard/APPENDIX.md +0 -430
  43. package/wowok-machine/APPENDIX.md +0 -407
  44. package/wowok-messenger/APPENDIX.md +0 -550
  45. package/wowok-onboard/APPENDIX.md +0 -502
  46. package/wowok-order/APPENDIX.md +0 -777
  47. package/wowok-output/APPENDIX.md +0 -575
  48. package/wowok-planner/APPENDIX.md +0 -726
  49. package/wowok-provider/APPENDIX.md +0 -455
  50. package/wowok-safety/APPENDIX.md +0 -565
  51. package/wowok-scenario/APPENDIX.md +0 -97
  52. package/wowok-scenario/MODE-DETAILS.md +0 -275
  53. package/wowok-tools/APPENDIX.md +0 -394
@@ -1,362 +0,0 @@
1
- # Object Collaboration Reference
2
-
3
- > Single authoritative reference for skills needing object collaboration, constraints, and capacity limits.
4
- > Covers the 22-object collaboration DAG and boundary conditions.
5
-
6
- ---
7
-
8
- ## 1. 22-Object Collaboration DAG
9
-
10
- ### 1.1 Mermaid Diagram
11
-
12
- ```mermaid
13
- graph TB
14
- %% ── Core Layer ──
15
- PERM[Permission<br/>R1 Required]
16
- TREAS[Treasury<br/>R2 Required]
17
- ALLOC[Allocation<br/>R3 Required]
18
- SERV[Service<br/>R4 Required]
19
- ORDER[Order<br/>Runtime]
20
- PROG[Progress<br/>Runtime]
21
- ARB[Arbitration<br/>C6 Optional]
22
-
23
- %% ── Trust Layer ──
24
- GUARD[Guard<br/>R5 Required]
25
- MACH[Machine<br/>R6 Required]
26
- PASS[Passport<br/>Runtime]
27
- PROOF[Proof<br/>Runtime]
28
-
29
- %% ── Data Layer ──
30
- REPO[Repository<br/>C7 Optional]
31
- DEMAND[Demand<br/>Phase 0]
32
- REWD[Reward<br/>C8 Optional]
33
- CONT[Contact<br/>C1 Conditional]
34
- PERS[Personal<br/>C5 Conditional]
35
-
36
- %% ── User Layer ──
37
- REG[Registrar+Entity<br/>E9]
38
- RES[Resource<br/>Tool]
39
- PAY[Payment<br/>Funds]
40
- ARBN[Arb Node<br/>Arbitration Node]
41
- UTIL[Util<br/>Tool]
42
- BRIDGE[Bridge<br/>Cross-chain]
43
-
44
- %% ── Core Layer Dependencies ──
45
- PERM --> TREAS
46
- PERM --> ALLOC
47
- PERM --> SERV
48
- PERM --> ARB
49
- TREAS --> ALLOC
50
- ALLOC --> SERV
51
- SERV --> ORDER
52
- MACH --> ORDER
53
- ORDER --> PROG
54
- ORDER --> ARB
55
- PROG --> ALLOC
56
-
57
- %% ── Trust Layer Dependencies ──
58
- PERM --> GUARD
59
- GUARD --> MACH
60
- GUARD --> PASS
61
- MACH --> SERV
62
- MACH --> PROG
63
- PASS --> PROOF
64
- PROOF --> ARB
65
-
66
- %% ── Data Layer Dependencies ──
67
- PERM --> REPO
68
- GUARD --> REPO
69
- REPO --> REWD
70
- PERM --> REWD
71
- GUARD --> REWD
72
- REWD --> DEMAND
73
- PERM --> DEMAND
74
- GUARD --> DEMAND
75
- PERM --> CONT
76
- REG --> CONT
77
- SERV --> CONT
78
- PERS --> SERV
79
-
80
- %% ── User Layer Dependencies ──
81
- REG --> PERS
82
- RES --> REG
83
- PAY --> TREAS
84
- PAY --> ALLOC
85
- ARB --> ARBN
86
- UTIL --> ALL[All Objects]
87
- BRIDGE -.->|mainnet only| TREAS
88
-
89
- %% ── Styles ──
90
- classDef required fill:#ffeb3b,stroke:#f57f17,stroke-width:2px
91
- classDef runtime fill:#81c784,stroke:#1b5e20,stroke-width:1px
92
- classDef optional fill:#bbdefb,stroke:#0d47a1,stroke-width:1px
93
- classDef tool fill:#eeeeee,stroke:#424242,stroke-width:1px,stroke-dasharray: 5 5
94
-
95
- class PERM,TREAS,ALLOC,SERV,GUARD,MACH required
96
- class ORDER,PROG,PASS,PROOF,ARB runtime
97
- class REPO,DEMAND,REWD,CONT,PERS,REG,ARBN optional
98
- class RES,PAY,UTIL,BRIDGE tool
99
- ```
100
-
101
- ### 1.2 ASCII Overview
102
-
103
- ```
104
- [CORE LAYER - Merchant Build Pipeline]
105
- Permission(1) ──┬──► Treasury(2) ──► Allocation(3) ──┐
106
- │ │
107
- ├──► Service(4) ◄──────────────────────┘
108
- │ │
109
- │ ▼
110
- │ Order(5) ──► Progress(6)
111
- │ │ │
112
- │ ▼ ▼
113
- └──► Arbitration(7) ◄──┘
114
-
115
-
116
- Arb Node(17)
117
-
118
- [TRUST LAYER - Workflow & Evidence]
119
- Permission(1) ──► Guard ──┬──► Machine ──► Service(4)
120
- │ │ │
121
- │ ▼ ▼
122
- │ Order(5) Progress(6)
123
-
124
- └──► Passport(9) ──► Proof(10) ──► Arbitration(7)
125
-
126
- [DATA LAYER - Strategy & Incentives]
127
- Permission(1) ─┬──► Repository(11) ──► Reward(8) ──► Demand(12)
128
- │ ▲ │
129
- └──► Reward(8) ────────────┘ │
130
- └──► Demand(12) ◄──────────────────────────┘
131
- Guard ──► Repository(11)
132
- Guard ──► Reward(8)
133
- Guard ──► Demand(12)
134
-
135
- [USER LAYER - Contact & Personal]
136
- Permission(1) ──► Contact(13) ──► Service(4).um
137
- Registrar+Entity(14) ──► Contact(13)
138
- Registrar+Entity(14) ──► Personal(18) ──► Service(4).customer_required
139
-
140
- [TOOL LAYER - Auxiliary]
141
- Resource(15) ──► Registrar(14)
142
- Payment(16) ──► Treasury(2) / Allocation(3)
143
- Util(19) ──► All Objects
144
- Bridge(20) ──► Treasury(2) (mainnet only)
145
- ```
146
-
147
- ### 1.3 Object Distribution by Layer
148
-
149
- | Layer | Objects | Count | Role |
150
- |-------|---------|-------|------|
151
- | Core | Permission, Treasury, Allocation, Service, Order, Progress, Arbitration | 7 | Business pipeline |
152
- | Trust | Guard, Machine, Passport, Proof | 4 | Workflow & evidence |
153
- | Data | Repository, Reward, Demand | 3 | Strategy & incentives |
154
- | User | Contact, Personal, Registrar+Entity | 3 | Contact & personal |
155
- | Tool | Resource, Payment, Util, Bridge, Arb Node | 5 | Auxiliary |
156
- | **Total** | | **22** | (includes Guard + Machine) |
157
-
158
- ### 1.4 Collaboration Types (5 Categories)
159
-
160
- | Type | Meaning | Count | Example |
161
- |------|---------|-------|---------|
162
- | **CREATE** | A creates B (B is child of A) | 18 | Permission creates Service |
163
- | **BIND** | A references B (B is a field of A) | 35 | Service.machine = Machine |
164
- | **TRIGGER** | A triggers an operation on B | 12 | Order triggers Progress |
165
- | **VALIDATE** | A validates B's state | 10 | Guard validates Service |
166
- | **CONSUME** | A consumes B's output | 8 | Proof consumes Passport |
167
- | **Total** | | **83** | |
168
-
169
- ### 1.5 Top 5 High-Frequency Collaboration Objects
170
-
171
- | Rank | Object | In-degree | Out-degree | Total |
172
- |------|--------|-----------|------------|-------|
173
- | 1 | Permission | 13 | 0 | 13 |
174
- | 2 | Guard | 9 | 8 | 17 |
175
- | 3 | Service | 6 | 8 | 14 |
176
- | 4 | Machine | 4 | 3 | 7 |
177
- | 5 | Treasury | 4 | 2 | 6 |
178
-
179
- Key observations:
180
- - **Permission** is the highest in-degree object (13), the "gatekeeper" of all writes
181
- - **Guard** is the highest out-degree object (8), the "validator"
182
- - **Service** is the "hub" connecting merchant-side and user-side
183
-
184
- ### 1.6 Permission Reverse Reference (9 Objects with BuiltinPermissionIndex)
185
-
186
- | Object | Index Range | Count | Usage |
187
- |--------|------------|-------|-------|
188
- | Repository | 100-105 | 6 | Repository operations |
189
- | Reward | 150-157 | 8 | Reward operations |
190
- | Machine | 200-208 | 8 | Machine operations |
191
- | Progress | 220-225 | 6 | Progress operations |
192
- | Treasury | 250-258 | 9 | Treasury operations |
193
- | Service | 300-320 | 21 | Service operations |
194
- | Arbitration | 350-368 | 19 | Arbitration operations |
195
- | Demand | 400-408 | 9 | Demand operations |
196
- | Contact | 450-454 | 5 | Contact operations |
197
-
198
- Note: Permission and Order do NOT hold BuiltinPermissionIndex entries. Permission is the carrier referenced by other objects; Order references Permission indirectly through Service snapshot.
199
-
200
- ---
201
-
202
- ## 2. 5-Dimension Boundary Condition Model
203
-
204
- ```
205
- ┌─────────────────────────────────────────────────────────────────────┐
206
- │ Object Boundary Condition 5-Dimension Model │
207
- └─────────────────────────────────────────────────────────────────────┘
208
-
209
- [1. Mutability] [2. Prerequisites] [3. Capacity Limits] [4. Permissions] [5. Irreversibility]
210
- │ │ │ │ │
211
- ▼ ▼ ▼ ▼ ▼
212
- Fields modifiable? What must exist Quantity limits? Operation Operations
213
- before create permissions? irreversible?
214
- or publish?
215
- ```
216
-
217
- | Dimension | Meaning | Values |
218
- |-----------|---------|--------|
219
- | 1. Mutability | Whether fields can be modified after creation | `MUTABLE` / `IMMUTABLE_AFTER_PUBLISH` / `IMMUTABLE_AFTER_CREATE` / `FROZEN` |
220
- | 2. Prerequisites | Conditions that must be met before create/operation | Object list + stage requirements |
221
- | 3. Capacity Limits | Quantity/size upper bounds | Numeric constants |
222
- | 4. Permissions | Permission index required for operations | Index value or `owner_only` |
223
- | 5. Irreversibility | Whether operations can be undone | `REVERSIBLE` / `IRREVERSIBLE` |
224
-
225
- ---
226
-
227
- ## 3. Main Boundary Condition Table (All 22 Objects)
228
-
229
- | Object | Mutability | Prerequisites | Capacity Limits | Permissions | Irreversibility |
230
- |--------|-----------|---------------|-----------------|-------------|-----------------|
231
- | Permission | permission list mutable | None | MAX_PERM_FOR_ENTITY=1000, MAX_ADMIN_COUNT=500 | owner_only | Adding index reversible |
232
- | Treasury | external_guard/owner_receive/um mutable | Permission | — | owner + 250-258 | deposit/withdraw reversible |
233
- | Allocation | permission/sharing mutable | Treasury + Permission | MAX_SHARING_COUNT=100 | owner + allocation_guard | allocate irreversible |
234
- | Service | machine immutable after publish | Permission | MAX_ARBITRATION_COUNT=20 | owner + 300-320 | publish irreversible |
235
- | Order | service/machine immutable | Service(published) + Machine(published) | MAX_AGENT_COUNT=10 (actual 11), MAX_DISPUTE_COUNT=10 | owner (via Service snapshot) | create irreversible |
236
- | Progress | machine/order immutable | Order + Machine | — | owner + 220-225 | forward irreversible |
237
- | Arbitration | permission mutable | Order + Permission | MAX_VOTING_GUARD_COUNT=50 | owner + 350-368 | ruling irreversible |
238
- | Reward | permission/guard mutable | Repository + Permission | — | owner + 150-157 | distribution irreversible |
239
- | Passport | — | Guard | Time bound | gen_passport | expiry irreversible |
240
- | Proof | — | Passport | — | submitter | submission irreversible |
241
- | Repository | permission/guard mutable | Permission | MAX_POLICY_COUNT=50, MAX_ID_COUNT_ONCE=100 | owner + 100-105 | write reversible |
242
- | Demand | permission/guard/service mutable | Permission | MAX_GUARD_COUNT_DEMAND=20, MAX_FEEDBACK_COUNT=20 (SDK) | owner + 400-408 | present irreversible |
243
- | Contact | permission mutable | Permission + Registrar | — | owner + 450-454 | message irreversible |
244
- | Registrar | — | — | MAX_RECORD_COUNT_REGISTRAR=1000 | owner | registration irreversible |
245
- | Entity | — | Registrar | — | registrar owner | registration irreversible |
246
- | Resource | — | — | — | owner | create reversible (delete) |
247
- | Payment | FROZEN | — | — | — | create = freeze |
248
- | Arb Node | can exit | Arbitration | — | owner | join reversible (exit) |
249
- | Personal | registrar immutable | Registrar | — | owner | create reversible (delete) |
250
- | Util | — | — | — | — | Tool module |
251
- | Bridge | — | — | — | owner | cross-chain irreversible |
252
- | Guard | named_operator mutable | Permission | MAX_GUARD_COUNT_PASSPORT=20 | owner | gen_passport regenerable |
253
- | Machine | permission mutable, nodes immutable after publish | Permission | MAX_NODE_COUNT_SDK=100, MAX_FORWARD_COUNT=20, MAX_FORWARD_ORDER_COUNT=20, MAX_NODE_PAIR_COUNT=40 | owner + 200-208 | publish irreversible |
254
-
255
- ### Key Observations
256
-
257
- 1. **Payment** is the only FROZEN object (created in terminal state)
258
- 2. **Service/Machine** are the only two objects with IMMUTABLE_AFTER_PUBLISH semantics
259
- 3. **Order/Progress/Arbitration** are runtime-irreversible objects
260
- 4. **Permission** is the central node, depended on by 9 objects
261
- 5. **Guard** has 3 different MAX_GUARD_COUNT constants (Demand/Passport=20, Reward=200)
262
-
263
- ---
264
-
265
- ## 4. Capacity Limits (On-Chain Constants)
266
-
267
- | Constant | Value | Source | Applies To | Notes |
268
- |----------|-------|--------|-----------|-------|
269
- | `MAX_NODE_COUNT_ONCHAIN` | 200 | machine.move | Machine | On-chain limit |
270
- | `MAX_NODE_COUNT_SDK` | 100 | onchain-constants.ts | Machine | SDK/MCP stricter |
271
- | `MAX_FORWARD_COUNT` | 20 | machine.move | Machine | Forwards per Pair |
272
- | `MAX_FORWARD_ORDER_COUNT` | 20 | machine.move | Machine | Forward order count |
273
- | `MAX_NODE_PAIR_COUNT` | 40 | machine.move | Machine | Pairs per node |
274
- | `USER_DEFINED_PERM_INDEX_START` | 1000 | permission.move | Permission | Custom permission start |
275
- | `MAX_PERM_FOR_ENTITY` | 1000 | permission.move | Permission | Permissions per Entity |
276
- | `MAX_ADMIN_COUNT` | 500 | permission.move | Permission | Admin count limit |
277
- | `MAX_AGENT_COUNT` | 10 | order.move | Order | Actual 11 (off-by-one bug) |
278
- | `MAX_DISPUTE_COUNT` | 10 | order.move | Order | Dispute count limit |
279
- | `MAX_SHARING_COUNT` | 100 | allocation.move | Allocation | Sharing count limit |
280
- | `MAX_VOTING_GUARD_COUNT` | 50 | arbitration.move | Arbitration | Voting guard limit |
281
- | `MAX_POLICY_COUNT` | 50 | repository.move | Repository | Policy count limit |
282
- | `MAX_ID_COUNT_ONCE` | 100 | repository.move | Repository | Single ID batch limit |
283
- | `MAX_GUARD_COUNT_DEMAND` | 20 | demand.move | Demand | Guard count for Demand |
284
- | `MAX_GUARD_COUNT_PASSPORT` | 20 | passport.move | Passport | Guard count for Passport |
285
- | `MAX_GUARD_COUNT_REWARD` | 200 | reward.move | Reward | Guard count for Reward |
286
- | `MAX_RECORD_COUNT_REWARD` | 5200 | reward.move | Reward | Records per recipient |
287
- | `MAX_RECORD_COUNT_REGISTRAR` | 1000 | registrar.move | Registrar | Registrar record count |
288
- | `MAX_REWARD_COUNT` | 20 | demand.move | Demand | Rewards per Demand |
289
- | `MAX_CONTEXT_REPOSITORY_COUNT` | 30 | progress.move | Progress | Context repository count |
290
- | `MAX_ARBITRATION_COUNT` | 20 | service.move | Service | Arbitrations per Service |
291
- | `MAX_FEEDBACK_COUNT` | 20 | demand.ts (SDK) | Demand | SDK-only, no Move check |
292
- | `DEFAULT_SETTING_LOCK_DURATION` | 2592000000 | service.move | Service | 30 days (ms) |
293
-
294
- ### MAX_GUARD_COUNT Name Collision
295
-
296
- | Object | Value | Constant Name |
297
- |--------|-------|--------------|
298
- | Demand | 20 | MAX_GUARD_COUNT_DEMAND |
299
- | Passport | 20 | MAX_GUARD_COUNT_PASSPORT |
300
- | Reward | 200 | MAX_GUARD_COUNT_REWARD |
301
-
302
- ---
303
-
304
- ## 5. Key Observations
305
-
306
- ### 5.1 Irreversibility Summary
307
-
308
- | Object | Operation | Irreversibility Reason | Recovery |
309
- |--------|-----------|----------------------|----------|
310
- | Service | publish | On-chain state irreversible | New Service |
311
- | Machine | publish | On-chain state irreversible | New Machine |
312
- | Order | create | On-chain record cannot be deleted | Wait for TERMINATED |
313
- | Payment | create | freeze_object | Unrecoverable |
314
- | Progress | forward | Node flow irreversible | Wait for terminal |
315
- | Arbitration | dispute/execute | Dispute/verdict irreversible | Unrecoverable |
316
- | Allocation | allocate | Fund allocation irreversible | Unrecoverable |
317
- | Reward | claim | Reward distribution irreversible | Unrecoverable |
318
-
319
- ### 5.2 Service Field Mutability (Critical)
320
-
321
- | Field | CONFIGURED | PUBLISHED | ACTIVE |
322
- |-------|------------|-----------|--------|
323
- | permission | MUTABLE | MUTABLE | MUTABLE |
324
- | machine | MUTABLE | **IMMUTABLE** | **IMMUTABLE** |
325
- | order_allocators | MUTABLE | — | MUTABLE |
326
- | arbitrations | MUTABLE | — | MUTABLE |
327
- | buy_guard | MUTABLE | — | MUTABLE |
328
- | price | MUTABLE | — | MUTABLE |
329
- | publish_state | — | **SET ONCE** | — |
330
-
331
- **Critical constraint**: `Service.machine` is the only core field that becomes immutable after publish.
332
-
333
- ### 5.3 Prerequisites Summary
334
-
335
- | Object | Must Exist Before Create |
336
- |--------|-------------------------|
337
- | Treasury | Permission |
338
- | Allocation | Treasury + Permission |
339
- | Service | Permission |
340
- | Machine | Permission |
341
- | Guard | Permission |
342
- | Order | Service (published) + Machine (published) |
343
- | Progress | Order + Machine |
344
- | Arbitration | Order + Permission |
345
- | Reward | Repository + Permission |
346
- | Passport | Guard |
347
- | Proof | Passport |
348
- | Repository | Permission |
349
- | Demand | Permission |
350
- | Contact | Permission + Registrar |
351
- | Personal | Registrar |
352
- | Arb Node | Arbitration |
353
-
354
- ### 5.4 Network Differences
355
-
356
- | Aspect | testnet | mainnet |
357
- |--------|---------|---------|
358
- | CREATE | replaceExistName=true, repeatable | replaceExistName=false, no overwrite |
359
- | BIND | Rebinding allowed | Locked after creation |
360
- | TRIGGER | Repeatable | Irreversible |
361
- | VALIDATE | Guard can be rebuilt | Guard rebuild requires updating all references |
362
- | Bridge | ❌ Not supported | ✅ Supported |
@@ -1,81 +0,0 @@
1
- # On-Chain Constants — Unified Management Reference
2
-
3
- > **Status**: Unified management reference for on-chain numeric constants across three layers (Move contracts, SDK, MCP).
4
-
5
- ## Why Unified Management
6
-
7
- Before GLM4, on-chain numeric constants were scattered across three layers:
8
-
9
- - **Smart contract layer**: Each `.move` file has its own `const MAX_* = N;` (on-chain authority)
10
- - **SDK layer**: Each `.ts` call file has its own `export const MAX_* = N;` (prone to drift from chain)
11
- - **MCP layer**: Hardcoded magic numbers (`100`, `1000`, etc.) with no import links
12
-
13
- This caused drift risk, magic numbers in MCP, and implicit differences between SDK and on-chain values.
14
-
15
- **Solution**: SDK is the single authoritative TS definition; MCP imports from SDK; Move contracts remain unchanged.
16
-
17
- ## 3-Layer Sync Architecture
18
-
19
- ```
20
- ┌──────────────────────┐ import ┌──────────────────────┐
21
- │ Move smart contracts │ ──────────► │ SDK onchain-constants │
22
- │ (*.move const MAX_*) │ │ (canonical TS source) │
23
- └──────────────────────┘ └──────────┬───────────┘
24
- │ import
25
-
26
- ┌──────────────────────┐
27
- │ MCP onchain-constants │
28
- │ (re-export from SDK) │
29
- └──────────────────────┘
30
- ```
31
-
32
- ### Sync Guarantees
33
-
34
- - **SDK ↔ Move**: A spec test parses `.move` files and asserts SDK values match Move `const` declarations
35
- - **MCP ↔ SDK**: The same test asserts MCP import values equal SDK export values
36
- - **CI Integration**: Sync tests run on every PR to prevent drift across all three layers
37
-
38
- ## 18 Constant Entries
39
-
40
- | # | Name | Value | Move Source | Purpose |
41
- |---|------|-------|-------------|---------|
42
- | 1 | `MAX_NODE_COUNT_ONCHAIN` | 200 | `machine.move:23` | Max nodes on-chain (chain authority) |
43
- | 2 | `MAX_NODE_COUNT_SDK` | 100 | (SDK custom) | Stricter limit for SDK/MCP (easier human review) |
44
- | 3 | `MAX_FORWARD_COUNT` | 20 | `machine.move:26` | Max global forwards per Machine |
45
- | 4 | `MAX_FORWARD_ORDER_COUNT` | 20 | `machine.move:21` | Max forwards per pair |
46
- | 5 | `MAX_NODE_PAIR_COUNT` | 40 | `machine.move:22` | Max pairs per node |
47
- | 6 | `USER_DEFINED_PERM_INDEX_START` | 1000 | (convention) | Custom permission_index start (0-999 reserved for built-in) |
48
- | 7 | `MAX_PERM_FOR_ENTITY` | 1000 | `permission.move:15` | Max permissions per Entity |
49
- | 8 | `MAX_ADMIN_COUNT` | 500 | `permission.move:17` | Max admins per Permission object |
50
- | 9 | `MAX_AGENT_COUNT` | 10 | `order.move:12` | Max agents per Order |
51
- | 10 | `MAX_DISPUTE_COUNT` | 10 | `order.move:13` | Max concurrent disputes per Order |
52
- | 11 | `MAX_SHARING_COUNT` | 100 | `allocation.move:17` | Max sharing entries per allocator |
53
- | 12 | `MAX_VOTING_GUARD_COUNT` | 50 | `arbitration.move:25` | Max voting guards per Arbitration |
54
- | 13 | `MAX_POLICY_COUNT` | 50 | `repository.move:22` | Max policies per Repository |
55
- | 14 | `MAX_ID_COUNT_ONCE` | 100 | `repository.move:25` | Max IDs per Repository operation |
56
- | 15 | `MAX_REWARD_COUNT` | 20 | `demand.move:21` + `repository.move:26` | Max rewards per Demand/Repository (same name, same value, different scopes) |
57
- | 16 | `MAX_CONTEXT_REPOSITORY_COUNT` | 30 | `progress.move:23` | Max context repositories per Progress |
58
- | 17 | `MAX_NAMED_OPERATOR_COUNT` | 60 | `progress.move:24` | Max named operators per Forward |
59
- | 18 | `MAX_NAMED_OPERATOR_ADDRESS_COUNT` | 80 | `progress.move:25` | Max addresses per named operator |
60
-
61
- > Note: 18 entries total (including `MAX_NODE_COUNT_ONCHAIN` and `MAX_NODE_COUNT_SDK` as two variants), corresponding to 15 unique on-chain constant concepts.
62
-
63
- ## Naming Conventions
64
-
65
- - Constant names match Move names exactly (e.g., `MAX_FORWARD_ORDER_COUNT`, not rewritten)
66
- - When the SDK is intentionally stricter than on-chain: chain value uses `*_ONCHAIN` suffix, SDK value uses `*_SDK` suffix, bare name (e.g., `MAX_NODE_COUNT`) aliases the SDK value
67
- - `USER_DEFINED_PERM_INDEX_START` is a **convention**, not a Move `const` (permission.move implicitly reserves 0-999)
68
-
69
- ## Special Case: `MAX_REWARD_COUNT`
70
-
71
- `MAX_REWARD_COUNT = 20` is defined in both `demand.move:21` (Demand reward cap) and `repository.move:26` (Repository reward cap). Same name and value but semantically independent. If the chain ever diverges, split into `MAX_REWARD_COUNT_DEMAND` and `MAX_REWARD_COUNT_REPOSITORY`.
72
-
73
- ## Key Design Principles
74
-
75
- 1. **Move contracts are the ultimate source of truth**: SDK must always align with Move. When a discrepancy is found, **fix the SDK** (unless the Move contract itself has a bug requiring an on-chain upgrade).
76
- 2. **SDK is the single authoritative definition**: `onchain-constants.ts` in the SDK is the sole canonical source for the SDK/MCP layer; MCP does not redefine constants.
77
- 3. **Explicit imports**: MCP uses explicit imports (not `export *`) for auditability.
78
- 4. **Three-way sync**: SDK ↔ Move ↔ MCP are kept consistent via automated tests.
79
- 5. **On-chain vs SDK distinction**: When the SDK is stricter than on-chain, use `*_ONCHAIN` / `*_SDK` suffixes to make the difference explicit.
80
- 6. **JSDoc with Move source**: Every constant's JSDoc must annotate the source Move file location.
81
- 7. **Consumer mapping**: `ONCHAIN_CONSTANT_MCP_CONSUMERS` records where each constant is used in MCP for audit purposes.