Representation: The Current Situational Model
The requirements spec's Section 3 is specific about what Representation is for: it holds "the current situational model, including a self-model entry." components/representation.patlang is a deliberately small piece of code — smaller than most of the components around it — because that job is narrow. It is not where reasoning happens; it is where the results of everything upstream come to rest so Reason/Plan has one place to look.
Two topics, one state file
Representation persists a single JSON object to .patlang_queue/representation_state.json: a current_percept field and a predictions list, capped at 20 entries (representation_max_predictions()) with the oldest dropped first once that cap is hit. Two queue topics feed it. short_term_representation carries the latest percept and simply overwrites current_percept each tick. representation_updates carries labelled entries — JSON strings pushed onto the bounded predictions list. Both are handled with a plain claim-and-ack (qh_claim_one/queue_ack); the source comment notes this is deliberately simpler than the non-consuming observer pattern used elsewhere in the codebase (lib/topic_observer.patlang), because Representation is the sole consumer of both its input topics — nothing else needs to see the same message twice.
A snapshot signal is the entire read API: it returns the current state object verbatim, stringified. features/representation.feature checks the whole round trip directly — publish a percept to the source topic, publish a labelled update to representation_updates, and confirm the resulting snapshot shows the current percept and includes the labelled update among its predictions.
Where the self-model entry actually lives
The "self-model entry" the spec names is not a special field — it's whatever labelled entry Self-Model chooses to publish to representation_updates when it is running in opaque mode. The source comment in representation.patlang spells out the corresponding negative case just as precisely: Self-Model's transparent-mode predictions never reach Representation at all — Requirements Spec 4.3 requires no path by which Reason/Plan, which consults Representation, can access them. Representation's own code has no branching logic for mode at all; the mode switch lives entirely on Self-Model's side, in which topic it chooses to publish to. Representation simply reflects the correlation-free consequence of that choice: an opaque prediction becomes a queryable entry here; a transparent one is invisible from this component's vantage point, full stop.
Schema feedback is a separate channel entirely
It's worth being precise about a channel Representation does not touch. lib/schema_feedback.patlang implements Abstraction's schema-driven expectation loop back into Perception — a non-consuming, peek-only topic (perception_schema_feedback) that Perception instances read directly. That is a separate mechanism from Representation's predictions list, even though both ultimately originate from the same handful of upstream components. Self-Model's transparent mode publishes to the schema-feedback topic precisely so its prediction takes the Abstraction-style route into Perception instead of the Representation-style route into Reason/Plan — the two channels are how the opaque/transparent distinction is enforced structurally rather than by a runtime permission check.
Ordinary component lifecycle
Representation composes lib/component_base.patlang like every other long-running component here: it claims a signals port, announces itself for dashboard discovery, answers status with an instrumentation snapshot (its extra field is simply prediction_count), and shuts down cleanly on quit. None of that is bespoke to Representation — see features/component_lifecycle.feature for the generic contract every component in this project satisfies.
See also
Representation's two inputs are Short Term (the current percept) and Abstraction's downstream effects via Self-Model's opaque-mode predictions; Reason/Plan is its consumer. See the architecture page for the full data-flow diagram.