@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.1

package/dist/docs/guides/capabilities.md

@@ -0,0 +1,460 @@
+# Capabilities
+
+Capabilities hold your game's state. This guide explains the state model, who sees and writes each capability, and how long its values last, then covers creating capabilities and every kind of variable they hold.
+
+## The state model
+
+A capability is a named collection of related variables, declared by a schema. For example:
+
+- `inventory` holds `Stock` and `Reorder`
+- `sales` holds `Revenue` and `UnitsSold`
+- `pricing` holds `Price` and `PricingStrategy`
+
+Each capability declares its variables in a `variablesSchema`: a full JSON Schema 7 object whose properties are the variables, each with a type, a `default`, and any constraints. Every capability starts from those defaults, so its variables exist from the first tick for anything that declares it.
+
+### Context is scoped by capability
+
+A team's state, the context, is one object keyed by capability identifier, each value holding that capability's variables:
+
+```typescript
+{
+    inventory: { Stock: 100, Reorder: false },
+    sales: { Revenue: 5000, UnitsSold: 50 },
+    production: { Output: 75 },
+}
+```
+
+Logic reads a variable through its capability: `context.inventory.Stock`. Scoping variables under their capability prevents name clashes between capabilities and keeps related variables together, and it is what lets every resource declare, by identifier, exactly which slices of state it touches.
+
+### Immutable updates
+
+Never assign to `context`. Build a new object with spreads and return what you write under `capabilities`:
+
+```typescript
+// ❌ Don't
+context.inventory.Stock = 50;
+
+// ✅ Do
+return {
+    capabilities: {
+        ...context,
+        inventory: {
+            ...context.inventory,
+            Stock: 50,
+        },
+    },
+};
+```
+
+The runtime folds the result into the context one level deep, and removes keys only through `deletes`. See [How a result folds into the context](./engine.md#how-a-result-folds-into-the-context).
+
+### How state moves through a tick
+
+1. **Initialisation**: every capability starts from its defaults, then the engine's `Init`, if it has one, sets up each team's starting state
+2. **Each tick**: the engine's `Run` plays the round, calling the simulation's steps in the order it writes them, each step's output becoming the next step's input
+3. **Between ticks**: surfaces, endpoints and hooks change the capabilities they declare in `writes`, and the next tick reads the result
+
+See [Ordering the simulation](./engine.md#ordering-the-simulation).
+
+## Declaring reads and writes
+
+Every resource that touches state declares the capabilities it reads and writes, by identifier:
+
+```json
+{
+    "reads": ["inventory", "discounts"],
+    "writes": ["revenue"]
+}
+```
+
+- **`reads`**: the capabilities the resource consumes. Every declared capability is present from the first tick, holding its schema defaults until something writes it, so a read is never conditional. The build fails if an identifier names no capability in the package
+- **`writes`**: the capabilities the resource produces values for, or removes keys from
+
+### A declaration is what gets delivered
+
+A resource receives exactly the capabilities it declares, in `reads` or in `writes`, and nothing else.
+
+On a user interface (game, session or waiting room) two things follow:
+
+- A capability you forgot to declare is **absent** from `data`, not just undocumented. Your generated `Context` already says so, so TypeScript catches it before you run
+- A capability you declare but never render is payload you pay for on every update, to every participant
+
+Writes count because a screen that sets a value almost always shows it: a decisions panel writes `price` and displays the current price in the same field.
+
+`writes` is also what a game or waiting room UI is allowed to change. The runtime refuses a `setData` naming a capability the UI only `reads`, or anything that is not a capability, as `denied`. A session UI's team writes are the facilitator's and are not held to it.
+
+The engine, hooks, validators, tick controllers, and endpoints follow the same rule: their logic is handed exactly the capabilities in `reads` and `writes`. What a resource returns under `capabilities` is folded over the wider context as a patch, so a resource cannot drop a capability it was never shown. A result that changes a capability not in its `writes`, whether it only reads it or never declared it, fails the call, naming it; this holds an aggregate engine's `shared` slice and each `teams` entry too. A capability returned unchanged, as `{ ...context }` returns it, is not a change. A result removes a key by naming its path in `deletes`, and only under a capability in its `writes`: a delete under one it only reads fails the call.
+
+## Scope
+
+A capability's `scope` controls who may write it and who may see it:
+
+| Scope            | Meaning                                                                                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `team` (default) | One value per team, delivered to that team's surfaces                                                                                                    |
+| `team-readable`  | Each team writes only its own copy, but user interfaces on other teams can observe every team's value live (shared-state games only)                     |
+| `shared`         | One value for all teams, written by an aggregate engine, by the facilitator (a session UI that declares it in `writes`), or by a session-scoped endpoint |
+| `private`        | Per team like `team`, but never delivered to any user interface. For engine bookkeeping                                                                  |
+
+```json
+{
+    "definition": {
+        "scope": "team-readable",
+        "variablesSchema": { "...": "..." }
+    }
+}
+```
+
+See [Multi-team games](./multi-team-games.md) for the full rules and the `useUserInterfaceCrossTeamData` hook.
+
+### Private capabilities
+
+Simulations accumulate state that exists only to get from one tick to the next: a serialised engine, a smoothing accumulator, a seed, a ledger the next tick consumes. Nothing on screen needs it, and under team scope all of it is sent to every screen on every update.
+
+`scope: 'private'` says so out loud. A private capability reaches your engine, hooks, validators, tick controller, and endpoints exactly as a team-scoped one does, and reaches no interface at all. Declaring one on an interface fails the build, naming the interface and the capability.
+
+```json
+{
+    "definition": {
+        "scope": "private",
+        "variablesSchema": {
+            "type": "object",
+            "properties": {
+                "PreviousProfit": { "type": "number", "default": 0 }
+            },
+            "required": ["PreviousProfit"],
+            "additionalProperties": false
+        }
+    }
+}
+```
+
+A `trend` capability like this one carries last tick's profit, so the engine's report can say whether things are improving, and no UI can read it.
+
+Reach for it whenever a screen would have no reason to render the value. When nothing but the engine reads it either, the engine's own `state` is simpler still: no capability, no schema, typed by TypeScript (see [Keeping memory between ticks](./engine.md#keeping-memory-between-ticks)). It costs nothing to change your mind later: widening `private` to `team` is a one-word edit, where narrowing `team` to `private` means finding out which screens had come to depend on it.
+
+## Lifetime
+
+Most state belongs to the round it was written in: undo a tick and it goes back, reset the session and it starts again from its defaults. Some state does not. That setup is complete, the round a facilitator has opened, the announcement on everyone's screen: undoing a mistaken tick should not wipe any of those.
+
+Set `lifetime` to `session` for that kind of value:
+
+```json
+{
+    "definition": {
+        "scope": "shared",
+        "lifetime": "session",
+        "variablesSchema": {
+            "type": "object",
+            "properties": {
+                "Message": { "type": "string", "default": "" }
+            },
+            "required": ["Message"],
+            "additionalProperties": false
+        }
+    }
+}
+```
+
+A session-lifetime value:
+
+- **Is left alone by undo and reset.** Per team for a team-scoped capability, in the one store for a shared one
+- **Is not part of any round.** `getPastState` never reports it, because a past round did not hold it
+- **Starts from its defaults once,** when the session is created or a team is added
+- **Is not the engine's.** The build refuses one in the engine's `reads` or `writes`. A tick has to be replayable from its snapshot, and a value that undo leaves alone would change under it. Surfaces, endpoints, hooks, validators and the tick controller use it as its `scope` allows
+
+`lifetime` is independent of `scope`: `scope` says who sees a value, `lifetime` how long it lasts. The default, `tick`, keeps a value in each tick snapshot. The starter game makes its facilitator `briefing` session-lifetime, so an undo never takes a note back off the teams' screens.
+
+## Creating a capability
+
+Create a capability with the CLI. The identifier becomes the directory name:
+
+```bash
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "inventory",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "Stock": { "type": "number", "default": 100 }
+      },
+      "required": ["Stock"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+This writes `capabilities/inventory/capability.sdk.json`, a capability with one numeric variable that starts at 100. A capability directory may also hold TypeScript files its schema names through [`tsType`](#a-typescript-type-of-your-own), such as `capabilities/chathistory/message.ts`.
+
+A capability can hold several variables of different types:
+
+```bash
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "warehouse",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "CurrentStock": {
+          "type": "number",
+          "default": 500,
+          "minimum": 0,
+          "description": "Current stock level"
+        },
+        "LastRestockDate": {
+          "type": "string",
+          "default": "2024-01-01",
+          "description": "Date of last restock"
+        },
+        "IsOperating": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether warehouse is open"
+        }
+      },
+      "required": ["CurrentStock", "LastRestockDate", "IsOperating"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+Then list it in the `reads` or `writes` of each resource that uses it.
+
+### Defaults
+
+A variable's `default` is its tick-0 value, so it must itself satisfy the subschema that declares it. `sdk build` fails on a default that does not, so an object default cannot carry an undeclared field under `additionalProperties: false`, and a value your logic only produces later (a status that starts as `'Unknown'`) still has to be admitted by the `enum`. See [Schema defaults](../cli-reference.md#schema-defaults).
+
+A default seeds the value and nothing else: the generated type comes from the schema's `type`, `properties`, `items`, `enum` and `const`. See [Where a precise type comes from](./type-safety.md#where-a-precise-type-comes-from).
+
+## Variable types
+
+### Number
+
+```json
+{
+    "StockLevel": {
+        "type": "number",
+        "default": 0,
+        "minimum": 0,
+        "maximum": 1000,
+        "description": "Current stock"
+    }
+}
+```
+
+### String
+
+```json
+{
+    "Status": {
+        "type": "string",
+        "default": "pending",
+        "description": "Current status"
+    }
+}
+```
+
+### Boolean
+
+```json
+{
+    "IsActive": {
+        "type": "boolean",
+        "default": true,
+        "description": "Is capability active"
+    }
+}
+```
+
+### Object
+
+```json
+{
+    "Preferences": {
+        "type": "object",
+        "properties": {
+            "Theme": { "type": "string" }
+        },
+        "required": ["Theme"],
+        "additionalProperties": false,
+        "default": {
+            "Theme": "light"
+        },
+        "description": "Preferences object"
+    }
+}
+```
+
+Declare the object's `properties`: an object with only a `default` generates `{ [k: string]: unknown }`.
+
+### Array
+
+```json
+{
+    "Items": {
+        "type": "array",
+        "default": [],
+        "description": "List of items"
+    }
+}
+```
+
+An array replaces whole when a write merges, so it is the wrong shape for anything several participants add to at once: two people each sending a list is two lists, and the last one wins. Use a keyed collection instead.
+
+### Keyed collection
+
+A collection several participants write at the same time is an object keyed by a stable id, not an array. Concurrent writes then touch different keys and the merge unions them, rather than replacing each other's list.
+
+Describe the item under `additionalProperties`, and give it a `title`:
+
+```json
+{
+    "Notes": {
+        "type": "object",
+        "default": {},
+        "description": "One sticky note per participant, keyed by participant id",
+        "additionalProperties": {
+            "title": "PinboardNote",
+            "type": "object",
+            "properties": {
+                "Author": { "type": "string" },
+                "Text": { "type": "string" }
+            },
+            "required": ["Author", "Text"],
+            "additionalProperties": false
+        }
+    }
+}
+```
+
+The `title` is what gives the item a name in the generated types, so surfaces and engine logic can refer to it:
+
+```typescript
+import type { Context, PinboardNote } from '../types';
+
+const render = (note: PinboardNote) => note.Text;
+```
+
+Without one you still get the right shape, `{ [k: string]: { Author: string; Text: string } }`, but nothing to name it, and every function taking an item has to index back into the map that holds it.
+
+Where the order of the collection matters, carry it on the entry (a rank, or when it was added) and sort on read. A separate ordered array is an array again, with the same problem.
+
+See [Design state for concurrent writes](../recipes/design-state-for-concurrent-writes.md) for the full set of rules this belongs to.
+
+### A TypeScript type of your own
+
+The generated types are only as precise as the schema. A schema that says `{ "type": "object" }` for a deep structure, such as a model's output, generates `{ [k: string]: unknown }`, and every read of it needs a cast. Where you already have the type in TypeScript, name it with `tsType` and the generated `types.ts` files use it instead:
+
+```json
+{
+    "Messages": {
+        "type": "array",
+        "default": [],
+        "items": {
+            "type": "object",
+            "tsType": "import('./message').ChatMessage",
+            "properties": {
+                "role": { "type": "string", "enum": ["user", "assistant"] },
+                "content": { "type": "string" }
+            },
+            "required": ["role", "content"],
+            "additionalProperties": false
+        }
+    }
+}
+```
+
+- **The path is relative to the capability's own directory,** as an import in a file beside `capability.sdk.json` would be. Each generated `types.ts` sits somewhere different, so the generator rewrites the path for each one. A bare module name (`import('some-package').Thing`) is left alone, and so is a `tsType` with no import (`"'low' | 'high'"`)
+- **The build checks the reference.** A path that resolves to no module, or a name the module does not export, fails the build, naming the capability
+- **The schema still does the rest.** `default` still seeds the value, and the runtime still validates against `properties`. `tsType` changes only what TypeScript sees, so keep the two describing the same thing
+
+The type lives in a file beside the bundle, here `capabilities/chathistory/message.ts`:
+
+```typescript
+export interface ChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+}
+```
+
+For engine bookkeeping nothing else reads, the engine's own [state](./engine.md#keeping-memory-between-ticks) is simpler still: no capability and no schema at all.
+
+## Updating capabilities
+
+Update an existing capability:
+
+```bash
+pnpm run sdk update capability inventory '{
+  "definition": {
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "Stock": { "type": "number", "default": 100 },
+        "MinimumStock": { "type": "number", "default": 20 }
+      },
+      "required": ["Stock", "MinimumStock"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+## Deleting capabilities
+
+Remove a capability:
+
+```bash
+pnpm run sdk delete capability inventory
+```
+
+Deleting a capability also removes every read and write of it, from whichever resources declared them.
+
+## Best practices
+
+1. **Use meaningful identifiers**: a short directory name that says what the variables are
+    - ✅ `inventory`
+    - ❌ `data1`
+
+2. **Keep variables related**: group related variables in one capability
+    - ✅ One capability for inventory variables
+    - ❌ Mix inventory and sales in one capability
+
+3. **Provide descriptions**: document what each variable means
+    - ✅ `"description": "Current stock level in units"`
+    - ❌ `"description": "stock"`
+
+4. **Set sensible defaults**: initialise variables to realistic values
+    - ✅ `"default": 100`
+    - ❌ `"default": 0` for a stock level that shouldn't be zero
+
+5. **Use constraints**: apply minimum/maximum to numeric values
+    - ✅ `"minimum": 0` for quantities that can't be negative
+    - ❌ No constraints on bounded values
+
+6. **Use proper types**: never use a string to hold JSON or complex data
+    - ✅ Use an `object` type with `properties`
+    - ❌ Use a string type with JSON: `{ "type": "string", "default": "{\"key\": \"value\"}" }`
+    - See the [type safety guide](./type-safety.md)
+
+7. **Define array elements**: use an `items` schema with property definitions
+    - ✅ `{ "type": "array", "items": { "type": "object", "properties": {...} }, "default": [...] }`
+    - ❌ `{ "type": "array", "default": [] }` (no type info)
+    - See the [type safety guide](./type-safety.md)
+
+8. **Mark engine bookkeeping private**: state that no screen reads it
+    - ✅ `"scope": "private"` for a serialised engine, an accumulator, a seed, a ledger the next tick consumes
+    - ❌ Leaving it team-scoped, where it is delivered to every screen on every update and a screen can quietly start depending on it
+    - See [Private capabilities](#private-capabilities)
+
+9. **Declare only what a screen renders**: a user interface receives exactly its declared capabilities
+    - ✅ A `reads` list that matches what the screen actually displays
+    - ❌ A long `reads` list kept 'just in case', which is payload sent to every participant on every update
+    - Logic resources follow the same rule: the engine, hooks, validators, tick controllers, and endpoints receive only what they declare
+
+## Next steps
+
+- [Engines](./engine.md): read and write these capabilities each tick
+- [Multi-team games](./multi-team-games.md): shared and team-readable capabilities in practice
+- [Design state for concurrent writes](../recipes/design-state-for-concurrent-writes.md): shaping state several participants write at once