Why ImpactRoom Matters As A Reference Adapter
ImpactRoom exists to teach adapter developers as much as it teaches agent developers. It is not just a polished local preview with a guided flow. It is a working example of how to bind domain state, public actions, policy evaluation, admitted work, and materialization into a single system without exposing the wrong layer to the public. That is why ImpactRoom and MazeRunner are better described as reference adapters than as demos alone. They show what correct binding looks like when the goal is to make public behavior legible without collapsing the underlying architecture.
Domain State Belongs To The Adapter
The first lesson is simple and foundational: domain state belongs to the adapter. In ImpactRoom, the authoritative room state lives in the adapter. The agent’s position, the key state, the approval state, the door state, and the event stream are adapter-owned domain concepts. The public preview does not own them, and the browser does not own them. This matters because many weak demos quietly let the UI become the real source of truth. Once that happens, the rest of the architecture becomes hard to reason about. ImpactRoom avoids that by keeping the private domain model where it belongs.
Public Projection Should Be Smaller Than Private State
The second lesson follows directly from the first: public projection should be smaller than private state. The observer sees a careful public slice of the room, not every internal field the adapter uses. The agent also sees a guided public slice, not the adapter’s private runtime shape. That smaller projection is not a loss of fidelity. It is a design decision that protects the contract. The public surface needs enough evidence to explain what happened and enough action structure to keep clients honest, but it does not need to become a raw mirror of the adapter’s full internal model.
Guided Affordances Are Better Than Raw Internals
This is where guided public affordances become important. ImpactRoom does not ask external agents to compose raw internal operations. It gives them stations, objects, action IDs, and returned submit metadata. That public language is close enough to the domain to be meaningful and small enough to remain stable. For adapter developers, the lesson is not “hide everything.” The lesson is “choose the right public vocabulary.” Public clients should operate on guided affordances, not on implementation detail.
Public Observation Is A Product-Level Trace
The Public Observation step adds another useful lesson. In ImpactRoom, the route name remains /agent/thought, but the product meaning is a short public note before intent actions. That shows how an adapter can require a small public trace before impact-oriented requests without opening a private reasoning channel. For developers, this is a concrete example of how to ask for public intent context without pretending that a model’s hidden internal process should become part of the product contract. The canonical request field is text, while observation is accepted as an external-agent alias for the same public note.
Policy Should Not Mutate State Directly
Another major lesson is that policy should not directly mutate state. ImpactRoom is valuable because it keeps that separation visible. A public request does not jump straight to world mutation. Instead, the request becomes a bounded action that is evaluated through state and policy, turned into admitted work when appropriate, and only later becomes materialized impact if the later claim still matches the earlier binding. This is the difference between a demo that merely checks permission and a demo that teaches staged boundary behavior.
Materialization Follows Claimed Work
Materialization after claimed work is one of the strongest reference points in the project. The adapter worker claims admitted work and validates it before applying the domain change. That sequence matters because it gives stale state and stale capability a meaningful place in the system. If state has shifted and the claimed work no longer matches the earlier conditions, the adapter does not pretend nothing happened. It returns a public result that preserves the distinction between request, admission, and visible impact. Adapter developers can take a lot from this. It shows how to design a system where no-impact is a first-class outcome rather than an awkward afterthought.
Stale State And Stale Capability Need Explicit Outcomes
The stale key path in ImpactRoom is therefore more than a demo flourish. It is an example of how stale state or stale capability should lead to specific public-safe feedback. A mature adapter should not compress every mismatch into an opaque failure. It should express, at the public layer, whether the action was blocked, whether it had no visible effect, whether the client should reread state, or whether the capability needs refreshing. That kind of feedback makes external agents easier to build and easier to debug without turning the public surface into a secret leak.
Reject At The Layer That Owns The Rule
Wrong-station behavior teaches a related lesson. If the guided surface owns a constraint, it can reject the request before deeper boundary work is engaged. ImpactRoom does this for station-bound actions and missing Public Observations. That is useful because the deeper layers should not have to explain errors that belong entirely to the guided public contract. Adapter developers can use this pattern to keep their public interfaces coherent: reject at the highest layer that genuinely owns the rule, and reserve deeper boundary machinery for the cases that actually require it.
Operator Authority Must Stay Separate
Operator authority is another key lesson. ImpactRoom keeps approval on a separate operator route and refuses to let the agent approve its own request. This is not only a policy choice for the room. It is a structural lesson for adapter design. If a system claims that human approval matters, that approval needs its own role boundary. Collapsing operator authority into the agent path would make the demo simpler, but it would teach the wrong thing. Reference adapters are supposed to preserve the meaningful boundaries, even when the shortest implementation path would erase them.
Public Demos Should Not Bypass The Public Route
The same lesson applies to any preview or teaching surface around an adapter. A public demo that bypasses the public agent route stops being useful as a learning example because it teaches visitors that the public contract is only decorative. Adapter developers should treat demos as consumers of the intended external contract, not as hidden privileged paths.
The Public UI Should Not Leak The Control Plane
The observer UI also carries a lesson. A public UI should not leak internal control-plane details just because engineers find them interesting. ImpactRoom shows a lot of useful information, including compact evidence codes and public event labels, but it stops short of turning internal execution records into UI concepts. That balance is worth studying. It is possible to make a system transparent enough to teach from without flattening every internal runtime object into public vocabulary.
Why ImpactRoom And MazeRunner Belong Together
Finally, ImpactRoom and MazeRunner matter together because they demonstrate a repeatable pattern. The details of the domain can change. One demo can be a room, another a maze. What stays constant is the binding discipline: adapter state remains local to the adapter, public projection stays smaller than private state, agent action runs through a guided public surface, policy does not directly mutate state, visible impact follows the admitted-and-claimed path, and observer interfaces do not become the hidden real control plane. That is the deeper lesson behind these reference adapters. They are examples of how to teach correct binding with code, not just with diagrams.