@teurons/vds-diagrams 0.0.0-stage → 0.3.0

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 (51) hide show
  1. package/README.md +170 -2
  2. package/dist/cli.js +2244 -0
  3. package/dist/diagrams.css +991 -0
  4. package/dist/grid.d.ts +1 -0
  5. package/dist/grid.js +283 -0
  6. package/dist/index.d.ts +1 -0
  7. package/dist/index.js +2044 -0
  8. package/dist/skills/vds-aggregates/SKILL.md +115 -0
  9. package/dist/skills/vds-ask-or-park/SKILL.md +101 -0
  10. package/dist/skills/vds-book-to-spec/SKILL.md +136 -0
  11. package/dist/skills/vds-build-from-published/SKILL.md +89 -0
  12. package/dist/skills/vds-change/SKILL.md +113 -0
  13. package/dist/skills/vds-context-map/SKILL.md +125 -0
  14. package/dist/skills/vds-contexts/SKILL.md +134 -0
  15. package/dist/skills/vds-diagrams/SKILL.md +88 -0
  16. package/dist/skills/vds-entities-and-values/SKILL.md +108 -0
  17. package/dist/skills/vds-language/SKILL.md +106 -0
  18. package/dist/skills/vds-model-review/SKILL.md +123 -0
  19. package/dist/skills/vds-ports-and-adapters/SKILL.md +119 -0
  20. package/dist/skills/vds-publish/SKILL.md +123 -0
  21. package/dist/skills/vds-reframe/SKILL.md +122 -0
  22. package/dist/skills/vds-requirements/SKILL.md +128 -0
  23. package/dist/skills/vds-requirements-review/SKILL.md +121 -0
  24. package/dist/skills/vds-scenarios/SKILL.md +142 -0
  25. package/dist/skills/vds-slice-blocks/SKILL.md +127 -0
  26. package/dist/skills/vds-story-walk/SKILL.md +128 -0
  27. package/dist/skills/vds-strip-invented/SKILL.md +130 -0
  28. package/dist/skills/vds-subdomains/SKILL.md +127 -0
  29. package/dist/skills/vds-which-skill/FILE-SHAPES.md +312 -0
  30. package/dist/skills/vds-which-skill/SKILL.md +125 -0
  31. package/dist/types/diagrams/src/grid/camera.d.ts +32 -0
  32. package/dist/types/diagrams/src/grid/capability.d.ts +11 -0
  33. package/dist/types/diagrams/src/grid/fold-uj.d.ts +2 -0
  34. package/dist/types/diagrams/src/grid/grid-canvas.d.ts +95 -0
  35. package/dist/types/diagrams/src/grid/index.d.ts +5 -0
  36. package/dist/types/diagrams/src/grid/input.d.ts +93 -0
  37. package/dist/types/diagrams/src/grid/route.d.ts +21 -0
  38. package/dist/types/engine/js/bridge.d.ts +12 -0
  39. package/dist/types/engine/js/index.d.ts +73 -0
  40. package/dist/types/vds-diagrams/src/canvas.d.ts +43 -0
  41. package/dist/types/vds-diagrams/src/from-scenarios.d.ts +4 -0
  42. package/dist/types/vds-diagrams/src/grid-folds.d.ts +1 -0
  43. package/dist/types/vds-diagrams/src/grid.d.ts +2 -0
  44. package/dist/types/vds-diagrams/src/index.d.ts +6 -0
  45. package/dist/types/vds-diagrams/src/types.d.ts +39 -0
  46. package/dist/types/vds-diagrams/src/user-journey.d.ts +54 -0
  47. package/dist/types/vds-diagrams/src/workspace.d.ts +25 -0
  48. package/dist/vds_engine.wasm +0 -0
  49. package/dist/workspace.d.ts +1 -0
  50. package/dist/workspace.js +113 -0
  51. package/package.json +68 -3
@@ -0,0 +1,130 @@
1
+ ---
2
+ name: vds-strip-invented
3
+ description: "Requirements and scenarios of one capability, once written and before any read-back: trace every requirement, scenario, limit value and term to something a person said, and remove or turn into a hot spot whatever has no source. Use after a requirement discovery session, when a draft looks too complete, or when nobody remembers saying a rule. During a live session use vds-ask-or-park; for the read-back and the ready or not-ready report use vds-requirements-review."
4
+ ---
5
+
6
+ # Strip invented
7
+
8
+ Every requirement, scenario, limit value and term in a capability traces to something a person said or gave, or it leaves the capability.
9
+
10
+ An agent writing requirements fills gaps with what typical apps do. The result reads as complete and nobody can tell which rules were stated. Event modeling (Dilger) warns that indirect communication "is always 'Stille Post'" (p133): each relay drifts from what the business person said. An invented rule is one more relay with no person at the start.
11
+
12
+ ## When to use
13
+
14
+ - After a requirement discovery session, before the person hears the capability read back.
15
+ - Owned by a sibling: the live choice to ask or park during a session is vds-ask-or-park. Writing a requirement or scenario is vds-requirements or vds-scenarios. The read-back and the ready or not-ready report is vds-requirements-review, which runs after this pass.
16
+ - Run it in an agent that did not write the requirements. Review is never run by the agent that wrote the material; the writer reads its own inventions as stated.
17
+
18
+ ## Where the source lives
19
+
20
+ The spec has no field for the source of a requirement. Nothing records who said it or in which session, so invented and stated rules look the same in the files. Trace against these, in order:
21
+
22
+ 1. The session transcript, or notes the person kept of it.
23
+ 2. A document the person gave: a brief, a screenshot, a policy, an email.
24
+ 3. An open or addressed hot spot whose text the person gave.
25
+
26
+ Never add a source field or comment to a file to record the trace. Keep the trace in the report you hand on.
27
+
28
+ No transcript and no document: ask the person one question, "Is there a record of the session or a note you wrote?" If there is none, every rule is untraced. Remove nothing. Turn each untraced rule into a hot spot, so the person can confirm or drop it at the read-back.
29
+
30
+ ## The pass
31
+
32
+ 1. List every item: each requirement statement, each scenario's Given, When and Then lines, each limit name and value, each term a person would read. Done when the list counts every requirement and every scenario in the capability.
33
+ 2. Trace each item to a quote or a document line. Write the quote beside it. A paraphrase that adds a number, a case or a field has no source for the addition. Done when every item has a quote or is marked untraced.
34
+ 3. Sweep the untraced items for the marks below. They are the places to look hardest, and an item without a mark can still be invented. Done when every mark in the table has been looked for.
35
+ 4. Decide each untraced item with the table under "Remove or park". Done when no untraced item is left as a rule.
36
+ 5. Write the change through the vds tools in one checked change: `vds apply` (or the `vds_apply` tool), since removing a requirement also removes its scenario file and its exits. Run `vds check`. If the change is refused because a command, event or read model is left with no scenario naming it, stop and hand that block to vds-slice-blocks. Done when the check passes and every new hot spot points `on` the screen or a requirement that remains; when neither remains, it has no `on` and names the step in `text` (file format: vds-ask-or-park).
37
+ 6. Hand on the trace: what was kept with its quote, what was removed, what became a hot spot. Done when vds-requirements-review has the list. Ask the person nothing more in this pass.
38
+
39
+ ## The marks an agent leaves
40
+
41
+ | Mark | Looks like | Ask |
42
+ |---|---|---|
43
+ | Round-number limit nobody gave | `lockMinutes: 15`, `passwordMinLength: 8`, "within 24 hours" | Who said the number? A rule with a stated name and no stated value keeps the name; the value becomes a hot spot. |
44
+ | "Standard" security rule | lock after N tries, session timeout, password strength, rate limits | Did a person ask for it, or does every app have it? |
45
+ | Error case nobody raised | "SHALL show an error when the network fails" | Did anyone mention this failure? Failures nobody raised are questions. |
46
+ | Field copied from typical apps | name, email, phone, avatar, date of birth on a screen nobody listed | Did the person name each field? |
47
+ | Tidy symmetry | a create with a delete, an add with an edit, a login with a logout | Did anyone ask for the other half? |
48
+ | Term nobody used | "user" where the person says "investor"; "OTP" where they say "code" | Use the person's word. Recording terms is vds-language. |
49
+ | Then line with an extra outcome | an event or a screen in a scenario the person never described | Trace each Then line on its own. |
50
+
51
+ ## Remove or park
52
+
53
+ | The untraced item... | Do |
54
+ |---|---|
55
+ | hides a choice the business must make (a number, a failure, a rule, a field) | remove the rule; write a hot spot with the question it hides |
56
+ | hides no choice: a restatement, a duplicate, padding words | remove it |
57
+ | has a stated rule and an unstated value | keep the rule and its number (the check needs it); a hot spot on that requirement says nobody gave the number, and vds-requirements-review reports it as not ready |
58
+ | was said by the agent and agreed to by nobody | treat as untraced; a person staying silent is no source |
59
+
60
+ Write the question in the person's words and from their example. A hot spot is storming (Brandolini): an inconclusive point gets one, and "it won't be forgotten" (p95-96). The person may answer it at the read-back. vds-requirements-review writes nothing: the owning skill records the answer afterwards, and vds-ask-or-park marks the hot spot addressed.
61
+
62
+ ## Right and wrong
63
+
64
+ A security rule nobody stated, left as a requirement:
65
+
66
+ ```yaml
67
+ # wrong
68
+ - id: REQ-AUTH-0040
69
+ title: Expire idle sessions
70
+ type: nfr
71
+ statement: The system SHALL end the session after 30 minutes without activity.
72
+ ```
73
+
74
+ Removed, and the question it hid parked on the screen where it would apply:
75
+
76
+ ```yaml
77
+ # right
78
+ id: HOT-AUTH--idle-session
79
+ text: "Should an investor be signed out after some time without activity?"
80
+ "on": SCR-AUTH-07
81
+ status: open
82
+ ```
83
+
84
+ A stated rule with an invented value. The person said "lock it after too many wrong MPINs" and gave no number:
85
+
86
+ ```yaml
87
+ # wrong: the number stands with no hot spot, so it reads as decided
88
+ limits:
89
+ lockAfterWrong: 5
90
+ ```
91
+
92
+ ```yaml
93
+ # right: the rule stays; the number is asked (and stays in `limits:`, see below)
94
+ id: HOT-AUTH--lock-count
95
+ text: "After how many wrong MPINs is the account locked?"
96
+ "on": REQ-AUTH-0028
97
+ status: open
98
+ ```
99
+
100
+ Keep the number in `limits:` while any statement or scenario names `{lockAfterWrong}`: removing it is refused as `unknown limit {lockAfterWrong}`. Say in the hot spot's `text` that nobody gave the number.
101
+
102
+ A scenario with an outcome nobody described:
103
+
104
+ ```gherkin
105
+ # wrong: the email nobody asked for
106
+ Then EVT-AUTH--code-sent with channel mobile, purpose SignIn
107
+ And EVT-AUTH--welcome-email-sent
108
+ ```
109
+
110
+ Drop the last line. If someone wondered about a welcome message, park it: "Do new investors get a welcome email?"
111
+
112
+ ## Symptoms
113
+
114
+ | What you see or hear | Do |
115
+ |---|---|
116
+ | The capability has a delete for every create | trace each delete; park the untraced ones as "Can an investor remove X?" |
117
+ | Limits are all round numbers and one session produced them | trace which numbers a person gave; park the rest |
118
+ | Every screen has an error requirement | keep the failures someone raised; park the others as questions |
119
+ | "We never talked about that" at any point | the rule is invented; remove or park it, then rerun the pass on its neighbours |
120
+
121
+ ## Never
122
+
123
+ Never leave a plausible rule nobody stated. Never answer a hidden question yourself to keep a rule; the question goes into a hot spot.
124
+
125
+ ## Not covered
126
+
127
+ - How to ask a question live in a session: vds-ask-or-park.
128
+ - Reading the capability back and saying ready or not: vds-requirements-review.
129
+ - Invented commands, events or read models in the model: vds-model-review.
130
+ - The book notes give no method for tracing a requirement to its source; the trace rules here are VDS's own.
@@ -0,0 +1,127 @@
1
+ ---
2
+ name: vds-subdomains
3
+ description: "Subdomain of a VDS workspace: one part of the business this product needs, marked core, supporting or generic. Use when the day-1 working subdomain needs its real name, when a person names a part of the business the product leans on, when a mark is unclear or disputed, or when a context serves no subdomain. Boundaries and the day-1 working context belong to vds-contexts; relations between contexts to vds-context-map; terms to vds-language."
4
+ ---
5
+
6
+ # Subdomains
7
+
8
+ Name each part of the business this product needs, in the business's words, and give it one mark that says how much effort it deserves.
9
+
10
+ Use it in strategic design, between requirement discovery sessions. On day 1 vds-contexts opens one working subdomain beside the working context, with a working mark from the person's answer to one question; this skill refines name and mark later from what the sessions left.
11
+ Siblings own the neighbours. Where a boundary goes, and the day-1 pair, is vds-contexts. Who depends on whom is vds-context-map. A word and its meaning is vds-language. A question nobody can answer is vds-ask-or-park.
12
+
13
+ When you write a file whose whole shape no skill shows, read `../vds-which-skill/FILE-SHAPES.md`.
14
+ ## Method
15
+
16
+ 1. **Read what exists.** Read every subdomain and every context's `serves:` line (`vds show <ID>`). Done when each subdomain is listed beside the contexts that serve it.
17
+ 2. **List the parts this product needs.** Take them from what people said in the sessions: what the product does itself, and what it leans on from elsewhere. A workspace is one product, and Vernon sets the problem space per initiative, "usually different from project to project" (p56). Done when every part on the list traces to something a person said, and no part is there only because the business has it.
18
+ 3. **Name each part in the business's words.** Use the words the domain expert uses for that part. Done when each name is a phrase a person said, and `does:` is one sentence a product team member would agree with.
19
+ 4. **Mark each part** with the table below. Ask the person; Vernon's instruction is "Ask the Domain Experts!" (p52). One question at a time. Done when each part has one mark and `why:` gives the person's reason for it.
20
+ 5. **Tie each part to a context.** Each subdomain is served by at least one context, and each context of kind ours serves a subdomain. One subdomain to one context is the goal (p57). Done when no subdomain and no context of kind ours is left untied.
21
+ 6. **Land it in one checked change.** Read the revision with `vds status`. Write the subdomains and the changed `serves:` lines together with `vds apply --base <rev>`. Done when the change is accepted and `vds check` reports 0 problems.
22
+ 7. **Tell the person what the marks change.** Say which part gets the most care and which is bought or reused. Done when the person has confirmed the marks or named the one to change.
23
+
24
+ ## Pick the mark
25
+
26
+ Ask in order. Take the first yes.
27
+
28
+ | # | Question to the person | Yes means | Source |
29
+ |---|---|---|---|
30
+ | 1 | Is this why the business wins, the part it must be better at than anyone? | core | Vernon p51-52: primary importance, the business must excel |
31
+ | 2 | Is it something any business needs in the same form, with nothing special to this one? | generic | Vernon p51-52: "captures nothing special", still required |
32
+ | 3 | Is it essential and specific to this business, without being what it competes on? | supporting | Vernon p51-52: essential, "somewhat specialized", so it is created |
33
+
34
+ No yes on any row: the part may not be needed by this product. Ask what breaks without it, or drop it.
35
+
36
+ What the mark changes:
37
+
38
+ | Mark | Effect |
39
+ |---|---|
40
+ | core | The best developers, the domain experts and first priority go here (p51-52). Model it most carefully. |
41
+ | supporting | Built in-house because it is specialized. Needed, with no need to excel (p52). |
42
+ | generic | Buy or reuse where a provider sells it. Its context is then usually of kind external. This is VDS's reading of the example: both generic subdomains there are served by external contexts. |
43
+
44
+ Rules for the mark:
45
+ - The mark is relative to this business. Mapping is generic for a company that uses maps and core for the company that sells them (p61).
46
+ - The mark depends on use. A bought module can be generic as a whole and work as supporting where it is used (p60).
47
+ - The marks are a moment in time. Review them when the business's goals change (p52).
48
+ - Supporting and generic never mean unimportant (p52). Say so when a person hears a mark as a put-down.
49
+
50
+ ## What the check enforces
51
+
52
+ Tested on a copy of the example:
53
+ - `type` is core, supporting or generic. Anything else is a problem.
54
+ - `does` and `why` must be filled. `name` is not checked; write it anyway.
55
+ - Every subdomain needs a context that serves it. A subdomain written alone is refused, so it lands with its context's `serves:` line in one change.
56
+ - A context of kind ours or legacy must serve a subdomain. A context of kind external may serve none.
57
+ - `serves:` naming an id with no subdomain file is a problem.
58
+ - A context may serve several subdomains. The check accepts it; Vernon sees it mostly in legacy systems (p48).
59
+ - The check never judges whether a mark is true. That is this skill's work.
60
+
61
+ ## Right and wrong
62
+
63
+ Right (the example):
64
+ ```yaml
65
+ id: SD-AUTH--investor-access
66
+ name: Investor Access
67
+ type: supporting
68
+ does: Lets an investor sign up, log in and reset their MPIN.
69
+ why: Essential before investing and specific to investors, but it is not what the business competes on.
70
+ ```
71
+ Wrong (named after the software, marked core to sound important, reason is no reason):
72
+ ```yaml
73
+ id: SD-AUTH--auth-service
74
+ name: Auth Service
75
+ type: core
76
+ does: Handles JWT sessions and the login API.
77
+ why: It is critical.
78
+ ```
79
+
80
+ Right (a generic part, served by a context of kind external):
81
+ ```yaml
82
+ id: SD-AUTH--identity-data-lookup
83
+ name: Identity Data Lookup
84
+ type: generic
85
+ does: Fills in an investor's profile (email, bank account, gender, income) from an outside data provider.
86
+ why: Any business onboarding people can use it, and a provider sells it; we integrate Cybrilla's APIs rather than build it.
87
+ ```
88
+ ```yaml
89
+ id: BC-AUTH--cybrilla
90
+ name: Cybrilla Context
91
+ serves: [SD-AUTH--identity-data-lookup]
92
+ kind: external
93
+ ```
94
+ Wrong (one part cut by who builds it):
95
+ ```yaml
96
+ id: SD-AUTH--investor-access-frontend
97
+ name: Investor Access Frontend
98
+ type: supporting
99
+ does: The screens the mobile team builds for sign up and login.
100
+ why: The mobile team owns it.
101
+ ```
102
+
103
+ ## Symptoms
104
+
105
+ | The person says, or the draft shows | Do |
106
+ |---|---|
107
+ | "Everything is core" | Ask question 1 about each part, one at a time. Mark core only on a yes. |
108
+ | No part gets a yes on question 1 | Write no core. The example has none: two supporting, two generic. Tell the person the product has no core subdomain yet and ask whether that is true of the product. |
109
+ | A name that is a system, a team or a vendor | Ask what the business calls that part. The vendor's name belongs on the context. |
110
+ | "We also have billing, HR, ..." | Ask whether this product needs it. A part the product never touches stays out. |
111
+ | The working subdomain from day 1 still has its working name, or a `why:` that starts "Working mark:" | Rename it from the sessions' words and ask the three mark questions; change every `serves:` line in the same change. |
112
+ | A subdomain with no context | Ask which context does this work. None yet: hand to vds-contexts. |
113
+ | A tiny part, a few rules or a calculation | Vernon: it can be a module inside a context, no subdomain of its own (p48). |
114
+ | The person cannot say why the business wins | Park it as a hot spot through vds-ask-or-park. Never pick the mark yourself. |
115
+
116
+ ## Never
117
+
118
+ Never split a subdomain to hand out work. Split only when the business names two parts, or two parts earn two different marks. Vernon gives this rule for bounded contexts: splitting to give tasks to developers makes fake contexts and a fragmented language (p68-71). Applying it to subdomains is VDS's reading.
119
+
120
+ Never assess the whole business. The subdomains are the parts this one product needs (p56).
121
+
122
+ ## Not covered
123
+
124
+ - Several core subdomains in one product. Vernon words the problem space around one new core (p56); the Vernon notes do not say two are forbidden.
125
+ - A product with no core at all. Vernon anchors the problem space on a new Core Domain (p56) and the example has none. The check asks `no core subdomain: what is this product for?`; put that question to the person.
126
+ - "Could it be bought" as a test for generic. Vernon's test is "captures nothing special"; buying appears in his solution space questions (p59-60) and in the example's `why:` lines.
127
+ - Writes go through `vds apply` or `vds write` (MCP: `vds_apply`, `vds_write`); read with `vds show <ID>` and `vds status`; check with `vds check`.
@@ -0,0 +1,312 @@
1
+ # File shapes
2
+
3
+ Paths change when folders are renamed; trust the workspace's VDS.md over this file.
4
+
5
+ Every file below is copied whole from the repo's examples (`packages/spec/workspace/0.1/examples/mini` and `investor-auth`), which pass `vds check`. Paths are relative to the workspace's `domain/`. `<BC>` is a context folder like `BC-NOM--nominees`; `<CAP>` is a capability folder like `CAP-NOM`.
6
+
7
+ A file's `id` must match its file name. Never write `flows/` or `diagrams/` folders; `vds compile` does.
8
+
9
+ ## Capability and requirement
10
+
11
+ Lives in `contexts/<BC>/<CAP>/problem/capability.yaml`. Every requirement is an entry in `requirements:` of that one file. There is no file per requirement.
12
+
13
+ ```yaml
14
+ # Every REQ lives here. screen and exits place it; entries, a screen's REQs, Commands and Shows are generated.
15
+ id: CAP-NOM
16
+ title: Add a nominee
17
+ requirements:
18
+ - id: REQ-NOM-0001
19
+ title: Show the nominees
20
+ type: state_view
21
+ screen: SCR-NOM-01
22
+ start: SCN-NOM-0001-01
23
+ read_model: [RM-NOM--nominees]
24
+ statement: The system SHALL show how many nominees the account has.
25
+ - id: REQ-NOM-0002
26
+ title: Add a nominee
27
+ type: state_change
28
+ screen: SCR-NOM-01
29
+ exits:
30
+ - { scn: SCN-NOM-0002-01, to: none }
31
+ statement: The system SHALL add a nominee the holder names.
32
+ ```
33
+
34
+ Refused most often: an `exits` scn that is not one of the requirement's scenarios. A `screen` with no screen file yet ("unknown screen SCR-NOM-09") is listed as a step not modelled yet, and publish refuses it.
35
+
36
+ Other requirement types (all in `investor-auth`, same file): `automation` (has `trigger`, `command`, `read_model`, `sees`; every field its command carries is in `sees`), `translation` (has `external`, `command` and `event`), `nfr` (has `limits` or nothing), `analytics`:
37
+
38
+ ```yaml
39
+ - id: REQ-AUTH-0046
40
+ title: Track mobile entry
41
+ type: analytics
42
+ "on": CMD-AUTH--submit-mobile
43
+ sends: investor.auth.mobile_entry.submitted
44
+ attributes: [screen, attempt, mobile_valid]
45
+ statement: When the investor submits a mobile, the system SHALL send investor.auth.mobile_entry.submitted with the screen, the attempt and whether the mobile is valid, never the number.
46
+ ```
47
+
48
+ ## Scenario file
49
+
50
+ Lives in `contexts/<BC>/<CAP>/problem/scenarios/REQ-<id>.feature`. One file per requirement, one or more scenarios in it. Each scenario has an `@SCN-` tag.
51
+
52
+ ```gherkin
53
+ @CAP-NOM @REQ-NOM-0002
54
+ Feature: Add a nominee
55
+
56
+ @SCN-NOM-0002-01
57
+ Scenario: A nominee is added
58
+ Given no EVT-NOM--nominee-added
59
+ When CMD-NOM--add-nominee
60
+ Then EVT-NOM--nominee-submitted
61
+ And EVT-NOM--nominee-added
62
+ ```
63
+
64
+ Refused most often: an event after Then that the command does not produce ("CMD-NOM--add-nominee does not produce EVT-NOM--ghost"). An event or command named before its file is written is listed as a step not modelled yet.
65
+
66
+ ## Screen
67
+
68
+ Lives in `contexts/<BC>/<CAP>/solution/screens/SCR-<SCOPE>-<nn>.yaml`. Only id and title are written. Its requirements, entries, exits, commands and shows are generated.
69
+
70
+ ```yaml
71
+ # REQs, Entries, Exits, Commands and Shows are generated.
72
+ id: SCR-NOM-01
73
+ title: Nominees
74
+ ```
75
+
76
+ "a screen needs an actor, found none" is a step not modelled yet: who acts on the screen comes from the `by` of the commands the screen's requirements use, so a screen saved before its command is accepted in the draft and refused by publish. Commands by two people raise an open question. It also shows up when the screen id does not match its file.
77
+
78
+ ## Subdomain
79
+
80
+ Lives in `subdomains/SD-<SCOPE>--<code>.yaml`.
81
+
82
+ ```yaml
83
+ id: SD-NOM--nominees
84
+ name: Nominees
85
+ type: supporting
86
+ does: Keeps who receives an account's holdings when its holder dies.
87
+ why: Required for every account, but not what the business competes on.
88
+ ```
89
+ Refused most often: `type` other than core, supporting or generic.
90
+
91
+ ## Bounded context
92
+
93
+ Lives in `contexts/<BC>/context.yaml`, with its terms in `contexts/<BC>/language.yaml`.
94
+
95
+ ```yaml
96
+ id: BC-NOM--nominees
97
+ name: Nominees Context
98
+ serves: [SD-NOM--nominees]
99
+ kind: ours
100
+ ```
101
+
102
+ An outside system is `kind: external`:
103
+
104
+ ```yaml
105
+ id: BC-AUTH--captcha-provider
106
+ name: Captcha Provider Context
107
+ serves: [SD-AUTH--bot-protection]
108
+ kind: external
109
+ ```
110
+
111
+ ```yaml
112
+ terms:
113
+ - term: Account Holder
114
+ means: "The person who owns the account and names its nominees."
115
+ ```
116
+
117
+ Refused most often: `kind` other than ours, external or legacy.
118
+
119
+ The relationships between contexts live in one file, `context-map.yaml`. A workspace with one context has `relationships: []`. From `investor-auth`:
120
+
121
+ ```yaml
122
+ relationships:
123
+ - type: upstream-downstream
124
+ upstream:
125
+ context: BC-AUTH--captcha-provider
126
+ downstream:
127
+ context: BC-AUTH--investor-access
128
+ roles: [ACL]
129
+ via: [sync]
130
+ ```
131
+
132
+ ## People
133
+
134
+ Lives in `people/PPL-<SCOPE>--<code>.yaml`. A command names its person in `by`.
135
+
136
+ ```yaml
137
+ id: PPL-NOM--holder
138
+ name: Account Holder
139
+ ```
140
+
141
+ Refused most often: a command whose `by` names a person with no file ("unknown person PPL-NOM--nobody").
142
+
143
+ ## External event
144
+
145
+ Lives in `contexts/<outside BC>/EVT-<SCOPE>--<code>.yaml`, directly in the external context's folder, not in a model. `source: system` and `system` name the outside context. A `translation` requirement turns it into one of our events.
146
+
147
+ ```yaml
148
+ id: EVT-AUTH--captcha-result
149
+ name: Captcha Result
150
+ source: system
151
+ system: BC-AUTH--captcha-provider
152
+ attributes:
153
+ - name: occurredOn
154
+ type: date
155
+ - name: valid
156
+ type: boolean
157
+ ```
158
+
159
+ ## Command
160
+
161
+ Lives in `contexts/<BC>/<CAP>/solution/commands/CMD-<SCOPE>--<code>.yaml`.
162
+
163
+ ```yaml
164
+ id: CMD-NOM--add-nominee
165
+ name: Add Nominee
166
+ does: Take the nominee the holder names
167
+ to: [BC-NOM--nominees]
168
+ by: PPL-NOM--holder
169
+ attributes:
170
+ - name: nomineeName
171
+ type: string
172
+ produces:
173
+ - EVT-NOM--nominee-submitted
174
+ - EVT-NOM--nominee-added
175
+ ```
176
+
177
+ Refused most often: a scenario Then that names an event missing from `produces`; an unknown `by`.
178
+
179
+ A command sent to another context names it in `to:` and the person it reaches as one id, as in investor-auth's `CMD-AUTH--send-code.yaml`: `to: [BC-AUTH--neptune]` and `reaches: PPL-AUTH--investor`. Such a command still produces an event of ours, filed under our aggregate: `to` says who is asked, our aggregate records that it asked. The pair needs a relation on the context map; its `via:` is optional and, when written, holds `sync`, `async` or both.
180
+
181
+ ## Domain event
182
+
183
+ Two homes.
184
+
185
+ - An event an aggregate stores: `contexts/<BC>/solution/model/<MOD>/<AGG>/EVT-<SCOPE>--<code>.yaml`.
186
+ - An event no aggregate owns yet: `contexts/<BC>/<CAP>/solution/events/EVT-<SCOPE>--<code>.yaml`, with a comment saying so.
187
+
188
+ ```yaml
189
+ id: EVT-NOM--nominee-added
190
+ name: Nominee Added
191
+ attributes:
192
+ - name: occurredOn
193
+ type: date
194
+ - name: nomineeId
195
+ type: string
196
+ - name: nomineeName
197
+ type: string
198
+ ```
199
+
200
+ An optional attribute adds `optional: true`; an attribute typed by a value object writes `type: VO-AUTH--email`. For the no-aggregate home, the file starts with `# It has no Aggregate yet.` (see `EVT-AUTH--security-limits-overridden`).
201
+
202
+ Refused most often: "no scenario uses it" for an event no scenario names.
203
+
204
+ ## Read model
205
+
206
+ Lives in `contexts/<BC>/<CAP>/solution/read-models/RM-<SCOPE>--<code>.yaml`. Each attribute has a `kind`: copy, count, exists or computed. `of` lists the events (or event attributes) it is built from.
207
+
208
+ ```yaml
209
+ id: RM-NOM--nominees
210
+ name: Nominees
211
+ attributes:
212
+ - name: count
213
+ type: integer
214
+ kind: count
215
+ of: [EVT-NOM--nominee-added]
216
+ ```
217
+
218
+ A computed attribute adds a `rule`:
219
+
220
+ ```yaml
221
+ id: RM-AUTH--code-status
222
+ name: Code Status
223
+ attributes:
224
+ - name: maskedTarget
225
+ type: string
226
+ kind: computed
227
+ of: [EVT-AUTH--mobile-submitted.mobile, EVT-AUTH--email-submitted.email]
228
+ rule: the submitted mobile or email, masked
229
+ - name: resendAvailableAt
230
+ type: date
231
+ kind: computed
232
+ of: [EVT-AUTH--code-sent.occurredOn, EVT-AUTH--code-resent.resendAvailableAt]
233
+ rule: "{resendAfterSeconds} seconds after the code was sent, or the latest resend"
234
+ ```
235
+
236
+ Refused most often: `kind` outside copy, count, exists, computed.
237
+
238
+ ## Aggregate
239
+
240
+ Lives in `contexts/<BC>/solution/model/<MOD>/<AGG>/aggregate.yaml`. The module's `module.yaml` (id, name) sits one folder up.
241
+
242
+ ```yaml
243
+ id: AGG-NOM--nominee
244
+ name: Nominee
245
+ module: MOD-NOM--nomination
246
+ root: ENT-NOM--nominee
247
+ invariants: [REQ-NOM-0002]
248
+ ```
249
+
250
+ Refused most often: `root` naming an entity that does not exist, or one in another aggregate's folder ("its root ... does not sit in its folder").
251
+
252
+ ## Entity
253
+
254
+ Lives beside its aggregate: `.../<MOD>/<AGG>/ENT-<SCOPE>--<code>.yaml`. The root entity is the one `aggregate.yaml` names. Any other entity in that folder is held inside the aggregate and reached only through the root; it has the same fields, and the command that creates it inside the root carries `creates: true` on it. An entity outside an aggregate's folder is refused.
255
+
256
+ ```yaml
257
+ id: ENT-NOM--nominee
258
+ name: Nominee
259
+ why: Each nominee is its own, and is added and later changed over time.
260
+ identity:
261
+ attributes: [nomineeId]
262
+ source: application
263
+ timing: early
264
+ attributes:
265
+ - name: nomineeName
266
+ type: string
267
+ required: true
268
+ commands:
269
+ - command: CMD-NOM--add-nominee
270
+ creates: true
271
+ ```
272
+
273
+ ## Value object
274
+
275
+ Lives beside the aggregate that uses it, in the module when two aggregates share it, or in `solution/model/` when the whole context shares it: `VO-<SCOPE>--<code>.yaml`.
276
+
277
+ ```yaml
278
+ id: VO-AUTH--channel
279
+ name: Channel
280
+ describes: Where a code goes.
281
+ values: [mobile, email]
282
+ ```
283
+
284
+ ## Port and adapter
285
+
286
+ Lives in `contexts/<BC>/solution/ports/<PORT>/port.yaml`, with adapters in `contexts/<BC>/solution/ports/<PORT>/adapters/ADP-*.yaml`. VDS.md says a port has name, side (driving or driven), with and does, and an adapter has name and does.
287
+
288
+ No example in the repo. Neither example folder has a port or adapter file. Do not guess the fields beyond what VDS.md lists.
289
+
290
+ ## Hot spot
291
+
292
+ Lives in `contexts/<BC>/<CAP>/problem/hot-spots/HOT-<SCOPE>--<code>.yaml`, beside the capability, not in the model. `on` names the block the question is about. `on` is quoted, as the example does.
293
+
294
+ ```yaml
295
+ id: HOT-AUTH--resend-limit
296
+ text: "Is there a limit on resends?"
297
+ "on": CMD-AUTH--resend-code
298
+ status: open
299
+ ```
300
+
301
+ Refused most often: an `on` that names nothing in the workspace ("on names unknown CMD-NOM--nope").
302
+
303
+ ## Several files in one change
304
+
305
+ `vds apply --base <rev> --from changes.json` (or the JSON on stdin) reads one JSON object. Each key is a path under `domain/`, and each value is the file's whole text, or `null` to delete the file. Any problem the change adds refuses the whole change.
306
+
307
+ ```json
308
+ {
309
+ "contexts/BC-NOM--nominees/CAP-NOM/problem/capability.yaml": "id: CAP-NOM\ntitle: Add a nominee\nrequirements: []\n",
310
+ "contexts/BC-NOM--nominees/CAP-NOM/solution/screens/SCR-NOM-02.yaml": null
311
+ }
312
+ ```