@cyberart-io/engine 0.0.4 → 0.0.5

package/docs/replay-inspector.md

@@ -0,0 +1,88 @@
+# Replay inspector
+
+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).
+
+Back to the [package README](../README.md).
+
+## One-command reproduce (this repo)
+
+```bash
+pnpm exec vitest run packages/engine/src/canvas/cyb-65-replay-inspector.repro.spec.ts
+```
+
+## When to use
+
+| Surface | Import | Use |
+|---|---|---|
+| Production host | `createReplayInspector` from `@cyberart-io/engine` | Attach to `createEventRouter` or `createRuntimeGroup`. |
+| Vitest / CI | same API, or from `@cyberart-io/engine/headless` | `replayExportedTrace` against `createHeadlessMultiCartHarness`. |
+
+Hosts attach this inspector to a router or runtime group. Event types stay host-defined.
+
+## `createReplayInspector(options?)`
+
+```ts
+import { createReplayInspector } from '@cyberart-io/engine';
+import { createHeadlessMultiCartHarness } from '@cyberart-io/engine/headless';
+
+const group = createHeadlessMultiCartHarness({
+  origin: 0,
+  participants: [
+    { id: 'effects', cart: effectsCart, emit: ['overlay.intent.*'], subscribe: ['host.state.*'] },
+    { id: 'ambience', cart: ambienceCart, subscribe: ['overlay.intent.*'] },
+  ],
+});
+
+const inspector = createReplayInspector({
+  redactedKeys: ['token'],
+  maxRecords: 512,
+});
+const session = inspector.bind(group);
+session.publish({ type: 'host.state.accepted', kind: 'state', payload: { token: 'secret' } });
+await session.step(2);
+const exported = await session.exportTrace();
+inspector.destroy();
+group.destroy();
+```
+
+`host.state.accepted` delivered to `effects` causes `overlay.intent.play` for `ambience`. The inspector tree is that chain plus any later rejects.
+
+### Options (`CreateReplayInspectorOptions`)
+
+| Option | Default | Meaning |
+|---|---|---|
+| `redactedKeys` | `[]` | Object keys replaced with `REDACTED_VALUE` in payloads and cart state summaries. |
+| `maxRecords` | `512` | Oldest records drop; `report().dropped` counts them. |
+| `registry` | none | `ContractRegistry.get` annotates `payloadSchemaVersion`. |
+
+### Bind vs watch
+
+| Method | Meaning |
+|---|---|
+| `watchRouter(router)` | Copy existing `inspectDecisions()`, then subscribe. |
+| `bind(group)` | Watch the group router and record a `publish` / `dispatch` / `step` / asset tape. `publish` extras (`cause`) are stored and replayed. `unbind()` drops the decision subscription. |
+| `importTrace(json)` | Load an export for inspection without replaying. |
+| `exportTrace(filter?)` | JSON: participants, tape, redacted records, snapshots. |
+| `report(filter?)` | Machine-readable CI report: participants, records, trees, dropped. |
+| `causationTree(correlationId?)` | Forest of accepted/rejected nodes. Duplicates are omitted. |
+| `replayExportedTrace(export, group)` | Play the tape on a fresh group; compare with `compareReplayTraces`. |
+
+`dispatch` of `cyberart.asset.ready` / `cyberart.asset.failed` is stored as tape `kind: 'asset'`.
+
+Cart summaries include `emit` / `subscribe` / `authoritative`, clock, redacted state, and `errorCount` / `lastError` (message only).
+
+## Router traces
+
+`createEventRouter` now also exposes:
+
+| Method | Meaning |
+|---|---|
+| `inspectParticipants()` | id, emit, subscribe, authoritative. |
+| `inspectDecisions()` | Bounded decision log (`maxDecisions`, default 256). |
+| `subscribeDecision(listener)` | Live accepted / rejected / duplicate records. |
+
+`RuntimeGroup.inspectParticipants()` adds `kind`. Group `inspect()` includes the same attach fields. `maxTrace` bounds the accepted-event envelope log (default 1024).
+
+Duplicate idempotency hits are `outcome: 'duplicate'` / `reason: 'duplicate'` and do not fan out. Permission failures stay `unauthorized`; missing targets `unknown-target`; spent TTL `hop-limit`.

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).
+Related: [events](events.md), [headless harness](headless-harness.md), [deterministic mode](deterministic-mode.md), [compositor](compositor.md), [replay inspector](replay-inspector.md).
 
 Back to the [package README](../README.md).
 
@@ -40,7 +40,7 @@ const group = createRuntimeGroup({
       cart: effectsCart,
       seed: `0x${'61'.repeat(32)}`,
       emit: ['ambience.intent.*'],
-      subscribe: ['adventure.state.*'],
+      subscribe: ['host.state.*'],
     },
     {
       id: 'ambience',
@@ -53,16 +53,16 @@ const group = createRuntimeGroup({
 });
 
 group.publish({
-  type: 'adventure.state.loon-whistle',
+  type: 'host.state.accepted',
   kind: 'state',
-  payload: { habitat: 'pond' },
+  payload: { id: 'north' },
 });
 await group.step(2);
 const { participants, trace, diagnostics } = await group.inspect();
 group.destroy();
 ```
 
-Adventure-style mapping (fixture, not Adventure Kit): an accepted `adventure.state.loon-whistle` is consumed by the effects cart, which emits `ambience.intent.play`; the router delivers that cue to the ambience cart. No project-specific bridge.
+Example mapping: an accepted `host.state.accepted` is consumed by the effects cart, which emits `ambience.intent.play`; the router delivers that cue to the ambience cart. No project-specific bridge.
 
 ### Options (`CreateRuntimeGroupOptions`)
 
@@ -74,6 +74,7 @@ Adventure-style mapping (fixture, not Adventure Kit): an accepted `adventure.sta
 | `createId` / `now` | `evt-1`… / first cart clock | Injected into the **one** shared router. |
 | `validate` | none | Router `validate` for cart-originated events. |
 | `router` | `{}` | Extra `createEventRouter` options (`maxHops`, `maxPerTurn`, …). |
+| `maxTrace` | `1024` | Bound on the accepted-event inspect trace. |
 
 ### Participant config
 
@@ -98,10 +99,11 @@ Adventure-style mapping (fixture, not Adventure Kit): an accepted `adventure.sta
 | `reset` | Remounts every cart to its initial state, clears traces / logs, `router.turn()`. Does not change `paused`; call `resume()` if you need lockstep after a paused reset. |
 | `dispatch(id, event)` | Mailbox inbound on that participant. |
 | `publish(event)` | Host `router.publish`. Unknown `target` → `unknown-target` rejection. |
-| `inspect()` | `{ participants: Record<id, { state, events, errors, kind, clock }>, trace, diagnostics }`. |
+| `inspect()` | `{ participants: Record<id, { state, events, errors, kind, clock, emit, subscribe, authoritative }>, trace, diagnostics }`. |
+| `inspectParticipants()` | Sync attach view (`id`, `kind`, `emit`, `subscribe`, `authoritative`). |
 | `destroy()` | Detach router listeners, `runtime.destroy()` each cart, remove owned containers. Idempotent. |
 
-Idempotency, correlation, causation, unauthorized emit, hop/loop checks are the existing router. The group only attaches and locksteps.
+Idempotency, correlation, causation, unauthorized emit, hop/loop checks are the existing router. The group only attaches and locksteps. For “why did this effect not fire?”, attach [`createReplayInspector`](replay-inspector.md).
 
 ## `createHeadlessMultiCartHarness(options)`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyberart-io/engine",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "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",