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

package/dist/docs/guides/engine.md

@@ -0,0 +1,527 @@
+# Engines
+
+The engine is the logic that moves your game forward: it sets up the board, then plays one round each tick. This guide explains how an engine is shaped and why, then covers everything you write in one.
+
+## The model
+
+A game holds one engine, in the `engine/` slot. It:
+
+- Declares the capabilities it reads (`reads`) and writes (`writes`), and the settings resources it reads (`settings`)
+- Exports an optional `Init`, which sets up each team's state before the first tick
+- Exports `Run`, which plays one tick for one team
+- Or, in a multi-team game where teams affect one another, exports `InitAggregate` and `RunAggregate`, which see every team at once
+
+The declarations are what make the data flow explicit. The runtime hands the engine exactly the capabilities it declares, and accepts writes only to the ones in `writes`, so a reader of `engine.sdk.json` knows what the engine touches without reading its code. The engine returns what it writes as a patch rather than mutating anything, so a tick can be replayed, undone and checked.
+
+A simulation with several steps (demand, then sales, then finance) is still one engine: `Run` calls the steps as functions, in the order it wants them. Ordering is a line of code, not a manifest setting.
+
+## Creating an engine
+
+Create the settings the engine reads, then an engine that reads them and writes to a capability:
+
+```bash
+pnpm run sdk new settings '{
+  "definition": {
+    "identifier": "engine",
+    "settingsSchema": {
+      "type": "object",
+      "properties": {
+        "DailySales": { "type": "number", "default": 10 }
+      },
+      "additionalProperties": false
+    }
+  }
+}'
+
+pnpm run sdk new engine '{
+  "definition": {
+    "writes": ["inventory"],
+    "settings": ["engine"]
+  },
+  "logic": {
+    "directory": ".",
+    "entrypoint": "logic.ts"
+  },
+  "rootDirectory": "."
+}'
+```
+
+This creates a settings resource, `settings/engine/`, holding the daily sales amount, and an engine that writes one capability and reads those settings:
+
+```
+engine/
+├── engine.sdk.json      # Reads, writes and settings
+├── logic.ts             # Init and Run
+├── logic.test.ts        # Tests
+└── types.ts             # Generated: Context, Settings, Callbacks
+```
+
+`sdk new engine --aggregate` scaffolds an [aggregate engine](#aggregate-engines) instead.
+
+## Declaring reads, writes and settings
+
+`engine.sdk.json` declares the engine's data flow:
+
+```json
+{
+    "definition": {
+        "reads": ["inventory", "pricing"],
+        "writes": ["revenue"],
+        "settings": ["engine"]
+    },
+    "logic": { "directory": ".", "entrypoint": "logic.ts" },
+    "rootDirectory": "."
+}
+```
+
+- **`reads`**: the capabilities the engine reads. Every declared capability is present in `context` from the first tick, holding its schema defaults until something writes it, so a read is never conditional
+- **`writes`**: the capabilities the engine produces values for, or removes keys from
+- **`settings`**: the settings resources the engine reads. It receives exactly those, keyed by identifier, as `settings`
+
+The build fails on an identifier the package does not declare. A capability with `"lifetime": "session"` cannot appear in either list (see [Lifetime](./capabilities.md#lifetime)). For the rules every resource follows, including what a user interface receives, see [Declaring reads and writes](./capabilities.md#declaring-reads-and-writes).
+
+Your logic reads what it declared by identifier:
+
+```typescript
+export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
+    const { Stock } = context.inventory;
+    const { Price } = context.pricing;
+    const revenue = Stock * Price * settings.engine.ConversionRate;
+
+    return {
+        capabilities: {
+            ...context,
+            revenue: { ...context.revenue, Revenue: revenue },
+        },
+    };
+};
+```
+
+### Settings
+
+Settings are read-only and fixed when play starts. Each one resolves from its default and any overrides before `Init` runs, so `settings` always carries every property: see [Overriding settings](./settings.md#overriding-settings) for the layers.
+
+The schema default is the single source of truth for the game's own value, so a code-level fallback such as `settings.engine.DailySales ?? 10` never fires. Drop it: every property must declare a `default`, so the generated `Settings` type marks none of them optional. To change the default, edit the settings schema and run `pnpm run sdk generate`, not the logic. A `settingsSchema` may not declare `required`, and the build rejects one that does. For a property that may genuinely have no value, widen its type instead (for example `"type": ["string", "null"]` with `"default": null`).
+
+To change a value for one scenario, override it in the scenario's `settings` under the settings identifier. A value participants must never see, such as an answer key, goes in a settings resource that only the engine declares. See [Settings](./settings.md#reading-settings) and [Create settings](../recipes/create-settings.md).
+
+## Implementing Init
+
+`Init` runs once when the game starts, once per team. Use it to set up initial state. It is optional: an engine that exports no `Init` starts every team from its capabilities' `default` values, so leave it out when those defaults already are the starting board. The scaffold writes one for you to fill in or delete:
+
+```typescript
+import { InitializationFunction } from '@seriousgaming/sdk';
+import type { Context, Settings } from './types';
+
+export const Init: InitializationFunction<Context, Settings> = async ({ context, settings }) => {
+    return {
+        capabilities: {
+            ...context,
+            inventory: {
+                ...context.inventory,
+                Stock: settings.engine.InitialStock,
+            },
+        },
+    };
+};
+```
+
+## Implementing Run
+
+`Run` executes every tick. This is where your core logic lives:
+
+```typescript
+import { RunFunction } from '@seriousgaming/sdk';
+import type { Context, Settings } from './types';
+
+export const Run: RunFunction<Context, Settings> = async ({ context, settings }) => {
+    const { Stock } = context.inventory;
+    const newStock = Math.max(0, Stock - settings.engine.DailySales);
+
+    return {
+        capabilities: {
+            ...context,
+            inventory: {
+                ...context.inventory,
+                Stock: newStock,
+            },
+        },
+    };
+};
+```
+
+Never assign to `context`: build a new object with spreads and return it. See [Immutable updates](./capabilities.md#immutable-updates).
+
+### What an engine returns
+
+`Init` and `Run` return what they write, named by kind: capabilities go under `capabilities`, as a patch merged into the team's context, and paths to remove go under `deletes` (see [Removing a key](#removing-a-key)). Hooks and aggregate engines follow the same rule, and a writing endpoint returns `{ response, capabilities, deletes? }`. The runtime refuses a top-level key it does not recognise, so a result that returns capabilities flat (`{ inventory: { ... } }`) fails the call rather than losing its writes.
+
+### How a result folds into the context
+
+What you return under `capabilities` is folded into the team's context one level deep:
+
+- A capability you leave out keeps its value
+- Within a capability you return, each variable you include replaces its old value, and each variable you leave out keeps its value
+- A variable is replaced whole, never merged into. That holds for objects too: return `PendingJunction: {}` and `PendingJunction` becomes `{}`, whatever it held before
+
+So to clear a field, return the value you want it to hold. `{}` empties an object variable, `[]` an array, and `null` clears either, as long as the variable's schema allows `null`.
+
+```typescript
+return {
+    capabilities: {
+        ...context,
+        route: {
+            ...context.route,
+            PendingJunction: {}, // cleared, not merged with the old choice
+        },
+    },
+};
+```
+
+This is not how a UI's `setData` behaves. A UI deep-merges its patch, because it may hold only part of the context. An engine is handed every capability it writes, so it always has the whole variable in hand to return.
+
+### Removing a key
+
+A variable you leave out keeps its value, so a fold can never take an entry out of a map keyed by something arbitrary, such as an order or team id. Name the entry in `deletes` instead:
+
+```typescript
+return {
+    capabilities: { ...context },
+    deletes: [`orders.Open.${orderId}`],
+};
+```
+
+- The runtime folds `capabilities` first and removes the paths after, so one result can replace an entry: write the new key under `capabilities` and delete the old one
+- A path is segments joined by `.`, or an array of segments when a key could contain a dot: `['orders', 'Open', orderId]`
+- A path that does not resolve is not an error
+- Every path must sit under a capability in your `writes`. One under a capability you only read, or did not declare, fails the call, naming it, even if the path does not exist
+
+In an aggregate engine, each `teams` entry carries its own `deletes`, and `shared.deletes` removes paths from shared capabilities. A shared path in a `teams` entry fails, as a shared write there does. These are the same paths, with the same rules, as a UI's `setData(update, { deletes })`.
+
+### Keeping memory between ticks
+
+Some of what an engine knows is nobody else's business: a record of every round so far, a model it carries forward, a random draw it froze at the start. Return it under `state`, beside `capabilities`, and the next call receives it back as `state`:
+
+```typescript
+import type { InitializationFunction, RunFunction, SignatureCallbacks } from '@seriousgaming/sdk';
+import type { Context, Settings } from './types';
+
+interface EngineState {
+    BestProfit: number | null;
+}
+
+export const Init: InitializationFunction<
+    Context,
+    Settings,
+    SignatureCallbacks,
+    EngineState
+> = async ({ context }) => ({ capabilities: context, state: { BestProfit: null } });
+
+export const Run: RunFunction<Context, Settings, SignatureCallbacks, EngineState> = async ({
+    context,
+    state,
+}) => {
+    const best = state?.BestProfit ?? null;
+    const { Profit } = context.profit;
+    return {
+        capabilities: context,
+        state: { BestProfit: best === null ? Profit : Math.max(best, Profit) },
+    };
+};
+```
+
+The rules are short:
+
+- **It is typed, not declared.** The fourth type parameter of `InitializationFunction` and `RunFunction` is the state's type, and the compiler checks it from the value one call returns to the value the next receives. There is no schema, because nothing but the engine reads it
+- **It is the engine's alone.** No surface, hook, validator, tick controller or endpoint ever receives it, and nothing but the engine can write it
+- **It moves with the round.** Each tick snapshot records it, so undo rewinds it and a per-team reset returns it to what `Init` left
+- **It replaces rather than merges.** A result carrying `state` replaces the previous value whole. Leave `state` out and the previous value is kept
+- **It must be JSON.** Plain objects, arrays, strings, finite numbers, booleans and `null`. A `Date`, a `Map`, `NaN` or an `undefined` property fails the tick, naming the engine, because a hosted runtime stores it as JSON and would hand back something different after a restart
+
+A step (`StepFunction`) receives `state` too, so a step can read it; only the exported `Init` and `Run` return it. An aggregate engine has the same pair at both levels: each `teams` entry carries that team's `state`, and `shared.state` is one value for the whole session. A summary step, for instance, can read `state.BestProfit` from the example above to call out a record round.
+
+Reach for a capability instead when anything else reads the value. `scope: 'private'` keeps a capability off every screen while leaving it readable by hooks and endpoints, so a value an endpoint reports on, such as last round's profit for a trend, stays a capability.
+
+## Ordering the simulation
+
+A game holds one engine, so there is no cross-engine ordering to resolve. Split the simulation into steps, one responsibility each, and order them by the order `Run` calls them:
+
+```typescript
+export const Run: RunFunction<Context, Settings> = async (args) => {
+    const withDemand = await runDemand(args);
+    const withSales = await runSales({ ...args, context: withDemand });
+    return { capabilities: await runFinancials({ ...args, context: withSales }) };
+};
+```
+
+Type each step as `StepFunction<Context, Settings>`. A step takes the engine's arguments and returns the next context flat, so steps chain directly, and only the exported `Run` wraps the final context in `{ capabilities }`. If one step reads what another writes, call the writer first.
+
+Below the steps, plain helper functions keep the arithmetic readable and testable on its own:
+
+```typescript
+function calculateDemand(price: number, baseRate: number): number {
+    return baseRate / (1 + price * 0.1);
+}
+```
+
+## Aggregate engines
+
+An aggregate engine runs once across every team rather than once per team. Reach for one when a value depends on every team's data, such as market share from all teams' prices.
+
+An engine is aggregate because of what its logic exports: `InitAggregate` and `RunAggregate`. There is no flag in the bundle. Exporting one without the other fails the build, naming the one that is missing. A per-team `Init` and `Run` are optional beside them; when present, `Run` executes for each team before `RunAggregate`.
+
+Both aggregate functions receive `{ shared, teams, settings, meta, participants, callbacks }`. `shared.context` is the session's shared store, once; `teams` is every team as `{ teamId, index, context }`, sorted by index, each `context` carrying that team's own capabilities only. They return `shared: { capabilities, deletes? }` for shared capabilities and one `{ capabilities, deletes? }` per team, in input order. The generated `types.ts` exports `TeamContext` and `SharedContext` beside `Context` to type the two halves.
+
+Only an aggregate engine may write to a [shared capability](./multi-team-games.md#shared-capabilities), and only under `shared`: a shared capability in a `teams` entry fails the init or tick, even when every team carries the same value. A per-team figure belongs in its own default-scope capability. The build refuses a shared write declared by a hook, a surface or an engine that is not aggregate. A per-team `Init` or `Run` in an aggregate engine that changes a shared capability fails when it runs: the session does not start, or the tick fails.
+
+See [The aggregate functions](./multi-team-games.md#the-aggregate-functions) for a complete example, the argument and return tables, and the execution order.
+
+## The language environment your logic runs in
+
+Engine logic runs in a **bare V8 isolate**. The runtime provides the ECMAScript intrinsics (`Object`, `Array`, `String`, `Number`, `Math`, `JSON`, `Date`, `RegExp`, `Promise`, `Map`, `Set`, the typed-array family, the error types, and the rest) and nothing else. Anything you might think of as 'just there' because Node or a browser provides it is **absent**:
+
+`process`, `require`, `fetch`, `XMLHttpRequest`, `setTimeout` / `setInterval` / `queueMicrotask` and every other timer, `structuredClone`, `Buffer`, `TextEncoder` / `TextDecoder` and the streams family, `URL` / `URLSearchParams`, `crypto`, `atob` / `btoa`, `window`, `document`, `localStorage`.
+
+Referencing one throws `ReferenceError` at tick time. Two things protect you:
+
+- **The dev server and CLI enforce it.** `sdk dev` and `tick` run your logic in the same restricted environment, so the failure surfaces locally rather than on deploy
+- **Lint catches it before you run anything.** A scaffolded package restricts these globals in `engine/`, `tick_controller/`, `hooks/*/logic/`, `validators/*/logic/` and `endpoints/*/logic/`, so `pnpm run lint` (and your editor) flags the reference with the replacement to use. The UI slots are deliberately out of scope: `ui/`, `session/` and `waiting_room/` run in a browser, where these globals exist
+
+### What to use instead
+
+| Instead of                                                    | Use                                                                                                                                          |
+| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `structuredClone(value)`                                      | `JSON.parse(JSON.stringify(value))`: context is JSON-serialisable by contract                                                                |
+| `new TextEncoder().encode(text)`                              | `encodeUtf8(text)` from `@seriousgaming/sdk`                                                                                                 |
+| `new TextDecoder().decode(bytes)`                             | `decodeUtf8(bytes)` from `@seriousgaming/sdk`                                                                                                |
+| `fetch(...)`                                                  | The injected `callbacks` (see [declaring runtime callbacks](#declaring-runtime-callbacks)), or an endpoint                                   |
+| `setTimeout(...)`                                             | Nothing. Ticks are the scheduling primitive: logic runs to completion within one tick                                                        |
+| `process.env.X`                                               | The `settings` argument                                                                                                                      |
+| `crypto.randomUUID()` / `Math.random()` for anything you keep | `deriveSeed` and `seededRandom` from `@seriousgaming/sdk`, seeded from `meta.seed` (see [Randomness you can keep](#randomness-you-can-keep)) |
+| `Date.now()` / `new Date()`                                   | `meta.now` (see [The time](#the-time))                                                                                                       |
+
+`console.log` is the exception and works normally: the SDK compiles a `console` shim into every bundle, so it prints in development and is discarded in production instead of throwing.
+
+`Math.random()` and `Date` are intrinsics and available, so nothing stops you calling them. But your logic may run more than once for one logical tick, and only the last run is kept, so neither is a safe basis for a value you store.
+
+> **Two caveats on the lint rule.** It matches bare identifiers, so `globalThis.fetch(...)` slips past it. Do not route around the rule that way. And it is off for colocated test files, because those run under Vitest in Node where these globals genuinely exist. That means a `logic.test.ts` can pass while the logic it tests would throw in production; the dev server and `tick` are what catch that. See [Testing](./testing.md#the-runtime-your-tests-do-not-reproduce).
+
+### No Node built-ins
+
+Logic cannot import a Node built-in module: not `node:fs` or any other `node:` specifier, and not a bare built-in name such as `fs`, `path`, `os`, `crypto` or `child_process`, whether by `import`, `require` or `import()`. There is no `require` in production to resolve one. `sdk build`, `sdk dev` and `tick` refuse it, naming the file, line and import:
+
+```
+LOGIC_NODE_BUILTIN: engine/stamp.ts:1:25 imports 'os', a Node built-in. ...
+```
+
+The same applies to a dependency you bundle: a library that imports a built-in cannot run in game logic. Move the work to a callback, or compute it from the context and settings.
+
+### The time
+
+`meta.now` is when the operation your call belongs to started, in milliseconds since the epoch: the tick, the hook dispatch, the endpoint call or the validator run. The host takes it once, so every team's `Run` in one tick reads the same value, the tick controller after it reads it too, and a re-run of the tick reads it again. Use it wherever you would have called `Date.now()`:
+
+```typescript
+export const Run: RunFunction<Context, Settings> = async ({ context, meta }) => {
+    return {
+        capabilities: {
+            ...context,
+            orders: { ...context.orders, LastPlacedAt: meta.now },
+        },
+    };
+};
+```
+
+In `sdk dev` it reads the session's clock, so `pnpm run sdk clock advance` moves it on a `--fake-clock` session, and a test passing a `FakeClock` to `createTestSession` controls it.
+
+### Who is on the team
+
+Every call into logic also receives `participants`: a read-only copy of the roster, taken when the operation started. `Init`, `Run` and a team-scoped endpoint see their team's participants; aggregates and the tick controller see every team in `teams`; a hook sees its team on a join and everyone on a move. Read it instead of keeping a roster in context from presence hooks:
+
+```typescript
+export const Run: RunFunction<Context, Settings> = async ({ context, participants }) => {
+    const present = participants.filter((p) => p.connected).length;
+    return {
+        capabilities: {
+            ...context,
+            staffing: { ...context.staffing, Present: present },
+        },
+    };
+};
+```
+
+Each call gets its own copy, so changing it changes nothing. At session start a team may have no participants yet, so `Init` often sees an empty list.
+
+### Randomness you can keep
+
+`meta.seed` is a random seed the host gives you. It is the same for the whole session, the same if a tick re-runs, and the same after a restart. Combine it with whatever identifies the thing you are seeding:
+
+```typescript
+import { deriveSeed, seededRandom } from '@seriousgaming/sdk';
+
+export const RunAggregate: RunAggregateFunction<TeamContext, SharedContext, Settings> = async ({
+    teams,
+    meta,
+}) => {
+    return {
+        shared: { capabilities: {} },
+        teams: teams.map((team) => {
+            // meta.index is not in scope here: each team carries its own,
+            // which is what makes the derived value differ between them.
+            const random = seededRandom(deriveSeed(meta.seed, team.index, 'weather'));
+            return {
+                capabilities: {
+                    ...team.context,
+                    weather: { ...team.context.weather, Rainfall: Math.round(random() * 10) },
+                },
+            };
+        }),
+    };
+};
+```
+
+Per-team functions get the same thing from `meta.index`:
+
+```typescript
+const random = seededRandom(deriveSeed(meta.seed, meta.index, 'weather'));
+```
+
+Two rules worth knowing before you reach for it:
+
+1. **Variation that depends on the other teams belongs in `InitAggregate`.** `Init` runs once for each team, but sees only that team's context, so it cannot tell teams apart beyond `meta.index` or balance one against another. `InitAggregate` sees every team at once, each with its own `index`. See [Multi-team games](./multi-team-games.md)
+2. **Freeze what later ticks depend on.** If tick 5 needs the same value tick 1 dealt, write it into context in tick 1 rather than re-deriving it from parts that may have changed
+
+`meta` also carries `teamId` and `index`, which name the team whose context you were given (`'team-1'` in a single-team game), and `tick` (the tick being executed), `locale`, `now`, and `runKind`.
+
+### Walkthroughs
+
+`meta.runKind` is `'session'` when your game is being played and `'walkthrough'` when it is being demonstrated. A walkthrough is a disposable second run beside the session: one team, one participant, always from tick 0, touching nothing real. It is what a facilitator puts on a projector while talking a room through the game before they play it.
+
+Most games ignore it and are right to. Reach for it when a solo run is missing something a group has, or when a tick reaches outside:
+
+```typescript
+export const Run: RunFunction<Context, Settings> = async ({ context, meta, callbacks }) => {
+    // A walkthrough has one team, so a leaderboard has nobody on it. Fill it
+    // in rather than showing a room an empty board they will never see again.
+    const rivals = meta.runKind === 'walkthrough' ? demonstrationRivals : context.market.Rivals;
+
+    // The model costs money and takes time, and answers differently each run.
+    // Neither is what you want in front of a room.
+    const commentary =
+        meta.runKind === 'walkthrough'
+            ? writtenCommentary(context)
+            : getText(await callbacks.generateText(prompt(context)));
+
+    return {
+        capabilities: {
+            ...context,
+            market: { ...context.market, Rivals: rivals },
+            report: { commentary },
+        },
+    };
+};
+```
+
+**The line to hold:** a walkthrough is a solo run of something built for a group, so fill in the social context it genuinely lacks, and suppress spoilers and anything that reaches outside. Do not change how the game plays. A walkthrough that behaves differently demonstrates a different game, and the room finds out on the first tick.
+
+The value is the host's, never a surface's, and it is the same everywhere in one run and for the whole of it, so a decision your engine takes on it and a decision your interface takes on it cannot disagree. Your surfaces read it with `useRunKind()`. Games that never look at it behave exactly as they always have, because every session reports `'session'`; only the walkthrough beside it differs.
+
+Try it with `sdk dev` and open `/walkthrough`, or from the command line with `sdk tick --walkthrough`.
+
+### Time limits
+
+Every call into your engine (`Init`, `Run`, `InitAggregate`, `RunAggregate`) and into a tick controller has a time limit. A call that runs past it is abandoned: the tick fails, the error is reported to the facilitator, and nothing it would have written is kept. The dev server allows two minutes per call; a production runtime sets its own limit, which may be shorter.
+
+The limit catches a call that is waiting, such as on a slow LLM call. The dev server cannot catch synchronous code that never returns, such as a `while (true)` that never meets its exit condition: it runs logic on its own thread, so the loop blocks the timer too. A command then fails with `DEV_SERVER_UNRESPONSIVE`, and `sdk dev stop` recovers (see [Troubleshooting](../troubleshooting.md#a-command-fails-with-dev_server_unresponsive-or-hangs-after-a-tick)). Do not rely on a production runtime to stop such a loop either.
+
+Keep each tick well inside that. An engine that waits on several LLM calls in a row is the usual way to get close, so run independent calls together with `Promise.all` rather than one after another.
+
+## Declaring runtime callbacks
+
+Engines that call `callbacks.generateText` or `callbacks.extractText` must list the API in the bundle's `uses` array. Calls to undeclared callbacks throw `UndeclaredApiUseError` at runtime, in dev and production alike.
+
+```json
+{
+    "definition": {
+        "reads": ["text"],
+        "writes": ["summary"],
+        "uses": ["generateText"]
+    },
+    "logic": { "directory": ".", "entrypoint": "logic.ts" },
+    "rootDirectory": "."
+}
+```
+
+The per-resource `types.ts` generator narrows the `Callbacks` type alias to the declared APIs. Each declared one is always present, so call it directly, with no `?.` or presence check: a runtime that cannot provide a declared service refuses the package at load instead.
+
+```typescript
+import type { RunFunction } from '@seriousgaming/sdk';
+import type { Context, Settings, Callbacks } from './types';
+
+export const Run: RunFunction<Context, Settings, Callbacks> = async ({ context, callbacks }) => {
+    const summary = await callbacks.generateText('Summarise: ' + context.text);
+    return { capabilities: { ...context, summary: { content: summary.content } } };
+};
+```
+
+See the [declare API uses recipe](../recipes/declare-api-uses.md) and [Declare the APIs a resource uses](./llm-integration.md#declare-the-apis-a-resource-uses) for the full mental model.
+
+## Testing engines
+
+Build the arguments with `logicArgs` from `@seriousgaming/sdk/testing`, which fills in `meta`, `participants` and `callbacks`, and start from the generated defaults:
+
+```typescript
+import { logicArgs } from '@seriousgaming/sdk/testing';
+import { describe, it, expect } from 'vitest';
+import { defaultContext, defaultSettings } from './defaults';
+import { Run } from './logic';
+import type { Context, Settings } from './types';
+
+describe('warehouse engine', () => {
+    it('decreases stock by daily sales', async () => {
+        const context: Context = { ...defaultContext, inventory: { Stock: 100 } };
+        const settings: Settings = { engine: { ...defaultSettings.engine, DailySales: 10 } };
+
+        const result = await Run(logicArgs.run({ context, settings }));
+
+        expect(result.capabilities.inventory.Stock).toBe(90);
+    });
+});
+```
+
+See [Testing](./testing.md#testing-engine-logic) for `Init`, aggregate functions, and LLM callbacks.
+
+## Best practices
+
+1. **Keep steps focused**: one responsibility per step function the engine calls
+    - ✅ One step for inventory, one for pricing
+    - ❌ A single step handling inventory, pricing, and sales
+
+2. **Declare exactly what you use**: list every capability the engine reads or writes, and nothing it does not
+    - ✅ `reads` and `writes` that match the logic
+    - ❌ A capability read 'just in case', or one the logic touches without declaring
+
+3. **Use immutable updates**: always use spread operators
+    - ✅ `{ capabilities: { ...context, sales: { ...context.sales, newField } } }`
+    - ❌ `context.sales.newField = value`
+
+4. **Use generated types**: never use `any` or write types by hand
+    - ✅ `import type { Context, Settings } from './types'` and use them in function signatures
+    - ❌ `const { Price }: any = context.pricing`
+    - See the [type safety guide](./type-safety.md)
+
+5. **Handle edge cases**: prevent invalid states
+    - ✅ Define constraints in the schema, such as `"minimum": 0`, so the range is declared and settings overrides are checked against it
+    - ✅ Bound computed values in logic: the runtime does not clamp what the engine returns to the schema's range
+    - ❌ Allow negative inventory
+    - ❌ Assume a schema constraint corrects a value the engine computes
+
+6. **Test logic**: write unit tests for your functions, then exercise the whole engine with `pnpm run sdk tick` or the dev server
+    - ✅ Test each calculation with different inputs
+    - ❌ Assume it works
+
+## Next steps
+
+- [Capabilities](./capabilities.md): the state model the engine reads and writes
+- [Shaping games](./games.md): wire the engine into a game
+- [Multi-team games](./multi-team-games.md): aggregate engines and shared capabilities
+- [Testing](./testing.md): write comprehensive tests