@cyberart-io/engine 0.0.7 → 0.0.9

package/docs/production-scenario.md

@@ -0,0 +1,81 @@
+# Production scenario
+
+End-to-end production composition harness. One scenario definition mounts the real host adapter, reducer, runtime group, production carts, DOM layers, compositor, visual/semantic layers, bindings, sequences, asset path, and headless audio. Isolated effect tests are not a substitute: omitting a required cart or compositor layer fails closed.
+
+Related: [Browser harness](browser-harness.md), [Compositor](compositor.md), [Visual layers](visual-layers.md), [Semantic layers](semantic-layers.md), [Presentation sequences](presentation-sequences.md), [Presentation bindings](presentation-bindings.md), [Audio](audio.md), [Replay inspector](replay-inspector.md), [Snapshots](snapshots.md), [Runtime group](runtime-group.md), [Asset resolver](asset-resolver.md). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-82-production-scenario.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `defineProductionScenario` / `createProductionScenarioRunner` from `@cyberart-io/engine` | Prove the shipped composition, not a second runtime. Persist `save()` envelopes in hostState. |
+| Vitest / jsdom | same, or `@cyberart-io/engine/headless` | `installHeadlessCanvas()` first. CI and local must pass the **same** scenario definition object. |
+
+This module composes existing harnesses. It does not reimplement Canvas2D, routing, or playback. Audio is the headless adapter: invocation and provenance only, never physical speakers.
+
+Generic fixture ids only: `whistle`, `ripple`, `room`, `npc`.
+
+## Contract
+
+1. **Definition.** `schemaVersion` `1`, stable `id`, `seed`, `required.participants`, `required.layers`. JSON only. Callbacks and incomplete steps (a `click` without `selector` or `x`/`y`, a `key` without `key`) fail closed at define time. Invalid sequence or binding manifests throw when the runner is created, never silently dropped.
+2. **Required composition.** After mount, every required participant and compositor layer must be present. Omitting the cart under test is a failure, not a skipped assertion. Missing participant localizes to `routing`; missing layer localizes to `pixels`.
+3. **Input.** Pointer and keyboard go through the browser harness (DOM coordinates and a11y ids), then the host reducer, then the group router.
+4. **Observation.** Evidence records reducer accept/reject, routed envelopes, selected bindings, cue sequences, composed pixels, captions, audio invocation, focus, and cleanup.
+5. **Save / reload / replay.** `save()` writes a snapshot envelope. `reload` restores host + presentation sidecars. `replay` re-runs the inspector tape on a fresh composition and compares traces.
+6. **Matrix.** Desktop/mobile viewport, DPR, reduced-motion, mute, failed-asset ids, and audio fallback are fields on the same definition. Not every cell needs a unique golden.
+7. **Evidence bundle.** `ProductionScenarioEvidenceBundle` carries pixel/semantic/a11y/trace/snapshot/asset hashes, revisions, traces, screenshot metadata, and `firstBrokenBoundary` localization: input → reducer → routing → binding → cue → pixels/caption/audio → save-replay. The optional `selectionTrace` field holds a [selection trace](selection-trace.md) export (`attachSelectionTrace(bundle, exported)`); the runner never populates it itself.
+8. **CI = local.** `run(steps)` executes the definition’s steps (or a shared step list). Do not fork scenario JSON for CI.
+
+```ts
+import {
+  createProductionScenarioRunner,
+  defineProductionScenario,
+} from '@cyberart-io/engine';
+import { installHeadlessCanvas } from '@cyberart-io/engine/headless';
+
+installHeadlessCanvas();
+
+const defined = defineProductionScenario({
+  id: 'room-whistle',
+  schemaVersion: 1,
+  seed: `0x${'82'.repeat(32)}`,
+  required: { participants: ['room', 'ripple'], layers: ['room', 'ripple'] },
+  matrix: { viewport: 'desktop', dpr: 1 },
+  steps: [
+    { type: 'click', selector: '#whistle' },
+    { type: 'step', frames: 2 },
+    { type: 'save' },
+    { type: 'replay' },
+  ],
+});
+if (!defined.ok) throw new Error(defined.errors.map((e) => e.detail).join('; '));
+
+const runner = createProductionScenarioRunner({
+  scenario: defined.scenario,
+  participants,
+  compositorLayers,
+  visualLayers,
+  semanticRegions,
+  sequences,
+  bindings,
+  geometry,
+  host,
+});
+
+const evidence = await runner.run();
+runner.destroy();
+```
+
+| Event | When |
+|---|---|
+| `production.scenario.state.observed` | Evidence captured with no broken boundary |
+| `production.scenario.state.failed` | Required composition missing, or an expectation failed |
+| `production.scenario.diagnostic.lifecycle` | Machine-readable rejection detail (`code`, `boundary`); emitted alongside every `state.failed` |
+
+Contracts: `productionScenarioEventContracts()`.

package/docs/remote-cart-manifest.md

@@ -0,0 +1,66 @@
+# Remote cart manifests
+
+Signed, versioned cart catalogs for third-party worlds. HMAC signatures, declared asset hashes, and deny-by-default host grants. Isolation is in-process (trusted factories), not `eval` / `Function`.
+
+Related: [capability manifest](capability-manifest.md) (optional nested `capabilities` + `grants`), [asset resolver](asset-resolver.md) (`createDeclaredAssetResolver`), [executable modules](executable-modules.md), [snapshots](snapshots.md) (`provenance`). Built on this: [content revision](content-revision.md) (`createRemoteContentAdapter` verifies the same signed JSON), [portal lifecycle](portal-lifecycle.md) (`HostGrantSet` transfer to the child cart). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-74-remote-cart-manifest.repro.spec.ts
+```
+
+## Load path
+
+1. Parse a signed JSON envelope `{ body, signature }`.
+2. Verify `hmac-sha256` over the canonical body (sorted keys) with a host key id.
+3. Check `cartVersion` when the host asked for an exact version.
+4. List `requestedGrants` (`audio`, `controller`, `network`, `persistence`, `fullscreen`).
+5. Host applies a subset via `createHostGrantSet` (inspectable, revocable, restore fail-closed).
+6. `createDeclaredAssetResolver` may fetch **only** declared URLs; hash mismatch or missing bytes refuse load.
+7. Capability bag APIs throw `RemoteCartCapabilityError` (`capability-denied`) when ungranted. Granted `network.fetch` still cannot reach undeclared URLs, and returns a copy of signed bytes.
+8. `createRemoteCartSandbox` takes the same `keys` map and re-verifies HMAC on `loadAssets`. Nested `capabilities.grants` are checked against the **host** grant set, not the cart's own list.
+
+Tests inject a registry map or `fetch` adapter. There is no ambient network.
+
+```ts
+import {
+  createRemoteCartRegistry,
+  createRemoteCartSandbox,
+  loadRemoteCart,
+  signRemoteCartManifest,
+} from '@cyberart-io/engine';
+
+const signed = await signRemoteCartManifest(body, secret, 'cyb-74-test');
+if (!signed.ok) throw new Error(signed.errors.map((e) => e.detail).join('; '));
+
+const loaded = await loadRemoteCart({
+  source: { kind: 'registry', id: 'cyb-74.remote' },
+  keys: { 'cyb-74-test': secret },
+  registry: createRemoteCartRegistry({ 'cyb-74.remote': signed.manifest }),
+  expectedVersion: '1.0.0',
+});
+if (!loaded.ok) throw new Error(loaded.errors.map((e) => e.detail).join('; '));
+
+const sandbox = createRemoteCartSandbox({
+  manifest: loaded.manifest,
+  keys: { 'cyb-74-test': secret },
+  grants: ['audio'],
+  bytesByUrl: { 'https://registry.test/cyb-74/sprite.bin': bytes },
+});
+sandbox.listRequestedGrants(); // before run
+await sandbox.loadAssets(); // re-verifies HMAC; forged envelopes refuse here
+sandbox.inspect(); // publisher, version, signature id/alg, grant set
+```
+
+`snapshotProvenance()` fills envelope `provenance` (`publisher`, `version`, `signature`, `grants`) for `defineSnapshot`.
+
+| Diagnostic `code` | When |
+|---|---|
+| `invalid-json` / `invalid-manifest` | Envelope is not parseable JSON or the wrong shape. |
+| `invalid-version` | Body version or expected `cartVersion` mismatch. |
+| `invalid-signature` / `unknown-key` | HMAC missing, wrong, or key id unknown. |
+| `undeclared-asset` | Resolver or granted `network.fetch` used a URL not on the manifest. |
+| `hash-mismatch` / `unsigned-bytes` | Declared hash does not match bytes, or bytes/hash missing. |
+| `capability-denied` | Cart called an API the host did not grant. |
+| `destroyed` | Sandbox was torn down. |

package/docs/replay-inspector.md

@@ -2,7 +2,7 @@
 
 Embeddable debug API for multi-cart routing. It records router decisions, builds a causation tree, redacts configured payload keys, bounds retention, and exports a JSON tape that the headless harness can replay. There is no Player UI.
 
-Related: [events](events.md), [runtime group](runtime-group.md), [headless harness](headless-harness.md), [deterministic mode](deterministic-mode.md).
+Related: [events](events.md), [runtime group](runtime-group.md), [headless harness](headless-harness.md), [deterministic mode](deterministic-mode.md). Built on this: [selection trace](selection-trace.md) (reuses correlation ids, `DEFAULT_SENSITIVE_KEYS` / `REDACTED_VALUE`), [production scenario](production-scenario.md) (inspector records in the evidence bundle), [job orchestration](job-orchestration.md) and [world patch](world-patch.md) (redacted trace export).
 
 Back to the [package README](../README.md).
 

package/docs/runtime-group.md

@@ -4,7 +4,7 @@ Host helper that mounts several production `createRuntime` carts, attaches each
 
 Capability-manifest integration is optional and structural (`capability?: { emit, subscribe, authoritative }`). This module does not import the manifest.
 
-Related: [events](events.md), [headless harness](headless-harness.md), [deterministic mode](deterministic-mode.md), [compositor](compositor.md), [replay inspector](replay-inspector.md), [calculation carts](calculation-carts.md).
+Related: [events](events.md), [headless harness](headless-harness.md), [deterministic mode](deterministic-mode.md), [compositor](compositor.md), [replay inspector](replay-inspector.md), [calculation carts](calculation-carts.md). Built on this: [portal lifecycle](portal-lifecycle.md) (per-participant suspend while a child cart is entered), [production scenario](production-scenario.md) (required participants are checked against this group).
 
 Back to the [package README](../README.md).
 

package/docs/selection-trace.md

@@ -0,0 +1,60 @@
+# Selection trace
+
+Content-selection and presentation-decision diagnostics. Hosts record which projection revision, binding, content hash, sequence step, layer, caption, and fallback actually won. The same query/export API is browser-safe (`@cyberart-io/engine`) and headless. There is no Player UI.
+
+Related: [Replay inspector](replay-inspector.md) (CYB-65 causation ids, `DEFAULT_SENSITIVE_KEYS` / `REDACTED_VALUE`, bounded export), [Production scenario](production-scenario.md) (CYB-82 evidence bundle `selectionTrace` field), [Content revision](content-revision.md) (CYB-79), [Presentation bindings](presentation-bindings.md) (CYB-83), [Presentation sequences](presentation-sequences.md) (CYB-78). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-85-selection-trace.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createSelectionTrace` from `@cyberart-io/engine` | Call `recordSelectionDecision` as bindings, revisions, assets, and sequences resolve. Export JSON. |
+| Vitest / jsdom | same, or `@cyberart-io/engine/headless` | Query/export/import the same records. `attachSelectionTrace` hangs the export on a CYB-82 evidence bundle. |
+
+Compose with `createReplayInspector` — import it, do not replace it. Link records with `correlationId` / `causationId` / `envelopeId`.
+
+Generic fixture ids only: `whistle`, `ripple`, `room`, `npc`, revision `8` vs `9`.
+
+## Contract
+
+1. **Decision record.** One JSON object covers state-projection revision, each binding predicate/priority/winner, requested vs activated content identity (revision, manifest version, publisher/source, hashes), staging/cache/supersession/rejection/rollback/last-known-good, resolved asset ref/hash/readiness/fallback, sequence invocation/step/track/interrupt/skip/replay, layer/region/caption/audio intent, and snapshot/replay provenance.
+2. **Reason codes.** `binding-conflict`, `asset-failure`, `revision-rollback`, `sequence-interruption`, and `text-only-fallback` are distinct. Hosts may add more strings.
+3. **Correlation.** Records carry `correlationId` / `causationId` / `envelopeId` plus `initiatingEventType`. Export includes matching CYB-65 inspector records when an inspector is attached or imported.
+4. **Redaction.** Credentials, private prompts, signed URLs, and non-whitelisted host-projection fields become `REDACTED_VALUE`. Hosts whitelist safe projection keys; an empty whitelist redacts every projection field. Array projections are whitelisted per element; a bare primitive projection is redacted. Signed URLs pasted into prose (`summary`, `staging.detail`, `rejectedReason`) are replaced in place.
+5. **Bounds.** `maxRecords` (default 512) drops oldest rows. `sampleRate` may drop noise; the five distinct failure codes always record.
+6. **Export / import.** JSON-serializable. Import restores records, inspector linkage, and snapshot revision/seed. Same query API in browser and headless.
+7. **Evidence.** `attachSelectionTrace(bundle, export)` sets `ProductionScenarioEvidenceBundle.selectionTrace`. The scenario runner is unchanged.
+
+```ts
+import {
+  attachSelectionTrace,
+  createReplayInspector,
+  createSelectionTrace,
+} from '@cyberart-io/engine';
+
+const inspector = createReplayInspector();
+const trace = createSelectionTrace({
+  inspector,
+  projectionWhitelist: ['inventory', 'roomId', 'lineId'],
+});
+trace.recordSelectionDecision({
+  kind: 'asset',
+  reason: 'text-only-fallback',
+  summary: 'npc audio not ready; caption selected',
+  correlationId: envelope.correlationId,
+  envelopeId: envelope.id,
+  initiatingEventType: 'host.state.accepted',
+  asset: { logicalRef: 'npc.line.audio', ready: false, fallback: 'npc.line.caption' },
+});
+trace.setSnapshotProvenance({ revision: 8, schemaVersion: 2, seed });
+const exported = trace.exportTrace({ correlationId: envelope.correlationId });
+const evidence = attachSelectionTrace(bundle, exported);
+inspector.destroy();
+trace.destroy();
+```

package/docs/semantic-layers.md

@@ -0,0 +1,72 @@
+# Semantic layers
+
+Named visual regions published by the cart: mask, polygon, and/or depth in the shared [normalized](normalized-geometry.md) coordinate system. The host drives hover / focus / selected and supplies accessibility names and roles. Geometry, blend, and hit-test policy stay with the cart.
+
+Related: [visual layers](visual-layers.md), [compositor](compositor.md), [normalized geometry](normalized-geometry.md), [browser harness](browser-harness.md). Built on this: [presentation sequences](presentation-sequences.md) (focus track), [presentation bindings](presentation-bindings.md) (`setRegionState`, hit-test policy via `restore`), [production scenario](production-scenario.md) (semantic hash in the evidence bundle). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-73-semantic-layers.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createSemanticLayerController` from `@cyberart-io/engine` | Enumerate published regions, `setRegionState`, `setRegionA11y`, `hitTest`. |
+| Vitest / jsdom | same, after `installHeadlessCanvas()` | `inspectPublished()` — no DOM overlay. |
+| Browser harness | `semanticLayers` on `createBrowserHarness` | A11y snapshot lists published ids / names / roles. |
+
+Generic ids only: `cabinet`, `plaque`, `stage`. The cart authors geometry; the host owns the a11y tree and pointer focus.
+
+## Hit-test policies
+
+| Policy | Behavior |
+|---|---|
+| `pass-through` | Published for SAM / a11y, never wins `hitTest`. |
+| `absorb` | First absorbing hit (after exclusive/depth sort) claims the pointer. |
+| `exclusive` | Exclusive hits beat non-exclusive overlapping regions. |
+| `depth-ordered` | Among remaining hits, higher `geometry.depth` wins, then `order`. |
+
+## `createSemanticLayerController(options)`
+
+```ts
+import { createSemanticLayerController } from '@cyberart-io/engine';
+
+const regions = createSemanticLayerController({
+  compositor,
+  visualLayers,
+  regions: [
+    {
+      id: 'cabinet',
+      hitTest: 'absorb',
+      blend: 'source-over',
+      compositorLayerId: 'hotspot',
+      visualLayerId: 'hotspot',
+      geometry: {
+        polygon: [
+          { x: 0.2, y: 0.2 },
+          { x: 0.5, y: 0.2 },
+          { x: 0.5, y: 0.5 },
+          { x: 0.2, y: 0.5 },
+        ],
+        depth: 0.4,
+      },
+      visuals: {
+        idle: { version: 'idle', blend: 'source-over' },
+        hover: { version: 'hover', blend: 'screen' },
+      },
+    },
+  ],
+});
+
+regions.setRegionA11y('cabinet', { name: 'Arcade cabinet', role: 'button' });
+regions.setRegionState('cabinet', { hover: true });
+const hit = regions.hitTest({ x: 0.3, y: 0.3 });
+const sam = regions.inspectPublished();
+```
+
+`inspectPublished()` returns `{ id, geometryKinds, a11y }` so a Segment Anything–style client can label cart-authored regions instead of reverse-engineering pixels. `geometryKinds` lists `mask`, `polygon`, `rect`, and/or `depth` as declared — a box is `rect`, not a full-frame depth field.
+
+Hosts persist `regions.snapshot()` JSON inside envelope `hostState`. Restore validates the full region set (ids, geometry, mask, blend, hit-test policy) before mutating. Tampered or unknown-id JSON returns `{ ok: false }` and leaves live state unchanged. Unknown visual-layer versions fail restore or throw from `setRegionState`; a missing compositor layer is skipped until the host creates it.

package/docs/snapshots.md

@@ -2,7 +2,7 @@
 
 Portable save envelope for carts and embedding hosts. Schema **1** is the previous engine-owned `CartStateBundle` (`CART_STATE_BUNDLE_VERSION = 1`). Schema **2** wraps that blob in `engineState` and keeps host-owned data in `hostState` / `hostStateRef`. Cyberart migrates envelopes in memory; the host owns persistence (local storage, a database, cross-user saves). This package is not the database of record.
 
-Related: [deterministic mode](deterministic-mode.md) (`rng` / clock), [capability manifest](capability-manifest.md) (cart id). Back to the [package README](../README.md).
+Related: [deterministic mode](deterministic-mode.md) (`rng` / clock), [capability manifest](capability-manifest.md) (cart id). Modules that persist their own `snapshot()` JSON inside envelope `hostState` and validate before restore: [semantic layers](semantic-layers.md), [presentation bindings](presentation-bindings.md), [portal lifecycle](portal-lifecycle.md), [job orchestration](job-orchestration.md), [world graph](world-graph.md), [world patch](world-patch.md), [content revision](content-revision.md). Envelope `provenance` comes from [remote cart manifests](remote-cart-manifest.md). Back to the [package README](../README.md).
 
 ## One-command reproduce (this repo)
 

package/docs/visual-layers.md

@@ -4,7 +4,7 @@ Versioned overlay / mask / sprite declarations with deterministic show, hide, re
 
 Hosts persist `controller.snapshot()` JSON inside envelope `hostState`. This module does not edit the snapshot envelope.
 
-Related: [presentation cue](presentation-cue.md), [compositor](compositor.md), [asset resolver](asset-resolver.md), [snapshots](snapshots.md). Back to the [package README](../README.md).
+Related: [presentation cue](presentation-cue.md), [compositor](compositor.md), [asset resolver](asset-resolver.md), [snapshots](snapshots.md). Built on this: [semantic layers](semantic-layers.md) (named regions over these layers), [presentation sequences](presentation-sequences.md) (visual track), [presentation bindings](presentation-bindings.md) (`visual-layer` targets, one accepted revision is one layer set). Back to the [package README](../README.md).
 
 ## One-command reproduce (this repo)
 

package/docs/world-graph.md

@@ -0,0 +1,39 @@
+# World graph
+
+Optional, headless-capable spatial graph for rooms, regions, frontiers, discovery, and entity transit. Hosts supply cost/policy functions and semantic time. The module does not render maps, run an economy, or encode combat, quest, or narrative rules.
+
+Related: [Events and router](events.md) (CYB-59 contracts), [Snapshots](snapshots.md), [Job orchestration](job-orchestration.md) (generated frontier *work*, not graph identity). Built on this: [World patch](world-patch.md) (optional graph composition; a patch's node/edge ops are applied here atomically with the world revision). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-81-world-graph.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createWorldGraph` from `@cyberart-io/engine` | Persist `snapshot()` in envelope `hostState`. Call `findPath` / `reachable` with host policy. |
+| Vitest / jsdom | same, or `@cyberart-io/engine/headless` | Same API. `inspect()` is enough for calculation carts. Projections are data, not pixels. |
+
+## Contract
+
+1. **Stable IDs.** Nodes and edges keep host-authored ids and integer `version`s. Add/remove does not rewrite unrelated identities.
+2. **Canonical vs known.** `projectCanonical()` is the full graph. `projectKnown(observerId)` is only discovered nodes/edges plus unresolved frontiers adjacent to known edges. `visibility: 'canonical'` edges are always known.
+3. **Access.** Edges are `open`, `locked`, or `disabled`. Lock requirements are opaque JSON for the host policy. Traversal never inspects real time.
+4. **Semantic time.** `departedAt`, `expectedArrival`, and query `semanticTime` are host numbers. Completing transit is an explicit `completeTransit` call.
+5. **Patches.** `applyPatch` adds nodes/edges atomically; failure rolls back. Generated Room Eight is a patch, not a rename.
+6. **Restore** validates JSON, schema version, and referential integrity before mutate. Tampered snapshots return `{ ok: false }` and leave the graph unchanged. Pass `migrations` (`SnapshotMigration`, n → n+1) to lift older snapshots.
+7. **Events.** Typed `world.graph.state.*` / `world.graph.diagnostic.*` contracts from `worldGraphEventContracts()`.
+
+```ts
+import { createWorldGraph } from '@cyberart-io/engine/headless';
+
+const graph = createWorldGraph({ graphId: 'adventure' });
+graph.applyPatch({ nodes, edges });
+graph.discover('walker', { nodeIds: ['lodge', 'room-1'], edgeIds: ['lodge-room-1'] });
+const minimap = graph.projectLocal('walker', 'room-1');
+const bigMap = graph.projectRegional('walker');
+const path = graph.findPath('lodge', 'station', hostPolicy, { semanticTime: day });
+```

package/docs/world-patch.md

@@ -0,0 +1,61 @@
+# World patch
+
+Transactional validation and atomic application of a generated world patch. Rooms, exits, characters, assets, dialogue, graph edges, and presentation bindings become one world revision or none. This is not a generic database transaction and does not make Cyberart the host's database of record.
+
+Related: [Job orchestration](job-orchestration.md) (typed job result, host-owned apply), [World graph](world-graph.md) (optional `applyPatch` composition), [Content revision](content-revision.md) and [Presentation bindings](presentation-bindings.md) (availability checks, not activation), [Replay inspector](replay-inspector.md) (`DEFAULT_SENSITIVE_KEYS` / `REDACTED_VALUE`), [Snapshots](snapshots.md). Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-84-world-patch.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createWorldPatchApplier` from `@cyberart-io/engine` | Inject a persistence adapter. Persist `snapshot()` in envelope `hostState`. Call `commit` only under host policy. |
+| Vitest / jsdom | same, or `@cyberart-io/engine/headless` | `createMemoryWorldPersistence` is enough. Tests may supply a copy-on-write host adapter. |
+
+The host owns domain policy, authorization, persistence, and when a ready patch may become canon. Job completion time does not leak into canonical game time: `dryRun` a validated patch and `commit` later.
+
+## Contract
+
+1. **Envelope.** `patchId`, `schemaVersion`, `baseRevision`, `idempotencyKey`, typed operations, producer/job provenance. Unknown fields and unknown ops fail closed.
+2. **Dry-run.** `dryRun(patch)` validates schema, referential integrity, preconditions, cycles, asset/content availability, binding targets, and host domain validators. `inspect()` is unchanged.
+3. **Atomic commit.** `commit` dry-runs, then swaps one complete world revision. Observers never see a half-applied multi-entity patch.
+4. **Stale base.** A patch whose `baseRevision` is not the current revision is rejected with `stale-base` and structured expected/actual revisions. There is no silent rebase.
+5. **Idempotency.** Re-submitting an accepted `patchId` returns the same revision and does not emit again. A new patch may `supersedes` an accepted id.
+6. **Persistence.** Hosts inject `begin` / `applyWorldRevision` / `commit` / `rollback`, plus optional `publish`. `createMemoryWorldPersistence` is the in-memory reference; `rollback` restores the `begin()` snapshot. If post-commit publication throws, the previous revision is restored via `persistWorld`, not rollback-after-commit.
+7. **Ordering.** Operations sort by explicit `order`, then `(op, kind, id)` — never `Object.keys` order.
+8. **Events.** Exactly one `world.patch.state.accepted` per newly accepted revision: patch id, old/new revision, changed identities, producer/content provenance. Rejected and superseded patches are audited.
+9. **Restore.** `restore` validates snapshot schema before mutate. It reloads the accepted world revision and, when present, the optional sidecar `graph` snapshot; it does not rerun the producing job. Failed graph restore reverts the world to the pre-restore revision.
+10. **Limits.** Operation, entity, byte, and diagnostic counts are bounded.
+11. **Graph composition.** Optional `WorldGraph` is applied by restoring a computed snapshot: `add` sets missing nodes/edges, `replace`/`revise` overwrite, `link` overwrites edges (including `from`/`to`), and `remove`/`tombstone`/`unlink` delete. Failure is `graph-apply-failed` and leaves canon unchanged.
+
+```ts
+import {
+  createMemoryWorldPersistence,
+  createWorldPatchApplier,
+} from '@cyberart-io/engine';
+
+const world = createWorldPatchApplier({
+  persistence: createMemoryWorldPersistence(),
+  content: { available: [{ revision: '8' }] },
+  bindings: { listedIds: ['lobby-room'] },
+  now: () => hostClock,
+});
+
+world.dryRun(patch); // diagnostics only
+world.commit(patch); // one revision, or the previous world unchanged
+world.snapshot();    // exact revision for hostState, plus optional graph
+```
+
+| Event | When |
+|---|---|
+| `world.patch.state.accepted` | Atomic commit of one complete revision: patch id, old/new revision, producer, jobId, contentRevisions |
+| `world.patch.state.rejected` | Validation, stale-base, graph, or publish failure; canon unchanged |
+| `world.patch.state.superseded` | An accepted patch id was replaced |
+| `world.patch.diagnostic.lifecycle` | Machine-readable rejection detail |
+
+Contracts: `worldPatchEventContracts()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyberart-io/engine",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "CyberArt host engine: mount carts, events, capability manifests, geometry, runtime groups, and a Node/jsdom headless entry.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -9,7 +9,8 @@
     "dist/index.d.ts",
     "dist/headless.js",
     "dist/headless.d.ts",
-    "docs"
+    "docs",
+    "CHANGELOG.md"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",