@forgeax/engine-runtime 0.1.7 → 0.1.19

package/README.md

@@ -1,5 +1,50 @@
 # `@forgeax/engine-runtime`
 
+## Host entry and frame evidence
+
+`createRenderer` is the host assembly entry. It selects the backend services
+and returns the render package's single `Renderer` contract; game code does
+not construct a device, graph, or second submit path. Pass the attached lease,
+camera, and environment facts to `draw`, then bind diagnostics to the
+returned `FrameReceipt`:
+
+```ts
+const result = await createRenderer(canvas);
+if (!result.ok) throw result.error;
+const renderer = result.value;
+const lease = renderer.attach(world);
+if (!lease.ok) throw lease.error;
+const frame = renderer.draw({
+  leases: [lease.value],
+  camera: { lease: lease.value },
+  environment: { lease: lease.value },
+});
+if (!frame.ok) throw frame.error;
+const facts = renderer.inspect();
+const observation = await renderer.observe(frame.value, { include: ['timings'] });
+void facts;
+void observation;
+```
+
+## Progressive recovery index
+
+Start with the public host route: `createRenderer`, `attach`, and `draw`. Then
+use `inspect()` for detached state and `observe(receipt, request)` for evidence
+bound to the successful receipt. If `draw` returns an error, use its closed
+`code` and typed `detail` to repair the named producer or capability, and retry
+the identical request. Do not parse text or reach into graph, device, or
+history state.
+
+Carrier manifests and schemas expose current source/build provenance, backend,
+runner, and frame identity. Structural graph checks are distinct from real
+Browser/Dawn readback and PNG evidence; a historical oracle is reference data,
+not a runtime pass. `unavailable` remains an explicit result.
+
+`inspect()` is detached and bounded. `observe()` is receipt-bound, so a
+stale receipt is a structured failure rather than an implicit read of the
+current frame. Repair the owner named by `error.detail`, then retry the same
+request.
+
 ## Render happy path
 
 `createRenderer -> attach -> draw -> inspect/observe/recover` assembles one