# KEY presentation intent
**Parent document for: KEY renderer spec, KEY visual grammar, KEY stage text**
-----
## The Governing Constraint
> The renderer must reveal the computation, not replace it with a story.
Every decision in the renderer — layout, color, timing, text, what is shown and what is withheld — must be evaluated against this constraint. If a design choice makes the demo feel more dramatic but less honest, it fails. If it makes it feel clearer and more honest, it passes.
-----
## A. Core Communication Goals
What the viewer must leave believing — not as claimed conclusions, but as experienced understanding:
**1. This system does not guess.**
It does not produce an answer and then check it. The system cannot produce an answer unless structure has survived. This is not a design preference — it is a structural impossibility in this architecture.
**2. It only keeps what survives.**
Candidates are not filtered by appearance. They are eliminated by constraint. The world does not recognize a good answer — it enforces admissibility. What passes did not look right. It held.
**3. Abstraction is earned, not assigned.**
The promoted structure is not labeled. It is lifted because it survived. The viewer should experience this as a transition — something changing status, not something being named.
**4. Composition is real.**
The key is not designed. It emerges from combining two structures that had no knowledge of each other. The composition search fails many times before it succeeds. That failure is not a warmup — it is the search.
**5. The world enforces structure.**
The world does not compare the candidate to a stored answer. It evaluates constraint equations. Failure is physical. Success is physical. The world is indifferent to the system’s internal confidence.
**6. Survival history distinguishes truth from luck.**
An accidental candidate can pass. But it cannot hold. The perturbation test demonstrates this directly: the GIE candidate passes the perturbed world because its structure was tested repeatedly under variation. The accidental candidate passes once and fails when the world shifts slightly.
-----
## B. Misinterpretations to Prevent
These are the specific wrong conclusions the renderer must not permit.
**The renderer must not look like a scripted animation.**
Mitigation: the pacing of each stage is driven by actual computational events — generation completions, promotion gates firing, world evaluations returning. Nothing advances on a timer.
**The renderer must not look like shape fitting.**
Mitigation: candidate transforms are shown as relationships between point clouds, not as shapes being matched to a template. The viewer never sees a target shape. The viewer sees survival pressure.
**The renderer must not look like a special-purpose key builder.**
Mitigation: the same kernel is shown operating at multiple levels. The visual language of the composition stage must be recognizably the same as the signal stage — same survival mechanics, different substrate. If the composition stage looks qualitatively different, the reuse claim is not felt.
**The renderer must not look like just another GA.**
Mitigation: the fitness function shown is dual-pressure — invariance AND world admissibility simultaneously. The hard-veto eliminations must be visually distinct from soft non-survival. A GA optimizes. This survives. The viewer must feel the difference.
**The renderer must not suggest recognition rather than construction.**
Mitigation: the lock/world should not be visible until the consequence stage. The viewer should not be able to predict where the system is going. The destination should be revealed by the structure, not telegraphed by the display.
**The renderer must not make accidental success look like earned success.**
Mitigation: the contrast branch and perturbation test must have equal visual weight to the GIE success path. The accidental candidate’s lack of survival history must be visually legible — perhaps through the absence of the survival trajectory that the GIE candidate shows.
-----
## C. Stage Meanings
Each stage has one dominant message. The renderer’s job is to make that message the only thing the viewer can reasonably conclude.
|Stage |Dominant Message |
|-------------------|----------------------------------------------------------------------------------------------------------------------------------------|
|Raw signals |Ambiguity. No answer exists yet. Two independent sources, each uninformative in its native form. |
|Lens search (arm 1)|Many candidates fail. The constraint eliminates before the viewer can predict what will survive. |
|Survival (arm 1) |Something held. Not because it looked right — because it kept holding. |
|Promotion (arm 1) |The structure departs from the signal. It is no longer raw data. It is an independent object. |
|Lens search (arm 2)|Same mechanics, different signal, different survival timing. The reuse is felt, not announced. |
|Promotion (arm 2) |A second independent structure exists. Neither knows about the other. |
|Composition search |Same kernel. New substrate. The search now operates on survived structures, not raw points. Most compositions fail. The failure is real.|
|World success |The evolved object satisfies the world. The world did not recognize it. It enforced structure. The mechanism transitions state. |
|Contrast branch |The accidental candidate looks similar. It passes the original world. The viewer should feel uncertain — maybe it works? |
|Perturbation test |The world shifts slightly. The accidental fails. The GIE candidate holds. The viewer understands: one was lucky, one was built. |
-----
## D. Layout Philosophy
### Single main panel or multi-panel?
**Multi-panel — but with strict hierarchy.**
The main panel (largest, center or left) shows the active computational event: the current survival search, the promotion moment, the world interaction.
The secondary panel (smaller, persistent) shows the survival trajectory: best score per generation, inadmissibility rate, composition stage indicators. This is the evidence that the main panel is honest — the viewer can see the search history.
The tertiary element (bottom or corner) shows on-screen text: sparse, declarative, following the computation.
No panel should be decorative. Every visible element must answer the question: “why is this shown?”
### Lock/world visibility
The lock must not be visible until the consequence stage. Showing the lock early telegraphs the destination. The viewer should not know what the system is building toward. They should see structure emerging and then — only then — see what the world requires.
This is not withholding information for drama. It is preserving the honest sequence: the system did not know the lock existed during lens search. The viewer’s experience should match the system’s actual epistemic state.
### Candidate populations
Show populations as distributions, not individual thumbnails during search. Individual candidates are not meaningful during search — only the distribution shape matters. When a candidate is promoted, show it individually. That is the moment individuality is earned.
Exception: failed compositions in the contrast branch should be shown individually because individual failure is the point.
### Pacing
Every transition is triggered by a computational event. The renderer polls the `RendererSnapshot` queue and updates display when a new snapshot arrives. It does not interpolate, animate, or smooth between states in ways that misrepresent what happened computationally.
Slow moments in the search (many generations without promotion) should appear slow. Fast moments (rapid convergence) should appear fast. The viewer should feel the difficulty of the search, not a designed narrative arc.
-----
## E. Text Philosophy
This is the complete contract for KEY_stage_text.
**Text should name what just happened, not explain what is about to happen.**
Text that says “Now the system will search for…” is narrator voice. It imposes a story.
Text that says “Candidate lenses tested under survival.” is system voice. It names the event.
**Text must be declarative, not interpretive.**
Wrong: “The system is discovering structure.”
Right: “Invariance survived. Structure promoted.”
Wrong: “This is where GIE proves its power.”
Right: “Same kernel. New substrate.”
**Text must not overclaim.**
The text cannot say more than the visuals support. If the visuals show a candidate passing the world, the text can say “The world accepted the structure.” It cannot say “GIE has proven its superiority.” That claim requires more than one demo.
**Text must not be empty.**
“Loading…” is empty. “Please wait…” is empty.
Even transition moments have honest text: “Search continues.” “No structure promoted yet.”
**Text scale:**
Maximum one sentence visible at a time. Sentences are short. They appear when the event they describe completes — not before, not after.
**The seven locked text strings (from the spec, non-negotiable):**
1. “Two independent signals. No solution exists yet.”
1. “Candidate lenses tested under survival.”
1. “Invariance survived. Structure promoted.”
1. “Same kernel. New substrate.”
1. “Composition attempted under hard constraint.”
1. “Plausible is not sufficient.”
1. “The world enforces structure.”
1. “State transition.”
Plus the opening line (before any computation runs):
> “The system doesn’t search for the key. It survives in a space where only keys can exist.”
And the perturbation test line (output 7):
> “One worked once. The other held.”
-----
## F. What Belongs Where
|Content type |Goes in |
|-----------------------------------|----------------------------------------------|
|Computational events |Main panel — drives display |
|Survival trajectory (score history)|Secondary panel — always visible |
|Hard-veto count |Secondary panel — always visible |
|Promotion moment |Main panel — individual candidate shown |
|World interaction |Main panel — full attention |
|Perturbation test |Main panel — side-by-side comparison |
|Stage text |Bottom overlay — one sentence, event-triggered|
|Code comment layer |Source only — for serious reviewers |
-----
## G. The Three-Layer Contract (canonical)
|Layer |Purpose |Failure mode to avoid |
|------|--------------------|-------------------------------------|
|Visual|Experiential truth |Looks scripted, looks like animation |
|Text |Interpretive clarity|Overclaims, explains ahead, misleads |
|Code |Structural proof |Hides special cases, introduces seams|
All three layers must tell the same story at different resolutions. If any layer diverges, credibility is lost — not reduced, lost.
-----
## H. What to Build Next
With this document locked, the three downstream files are well-constrained:
**KEY renderer spec** — architecture of the renderer layer: how RendererSnapshot objects are consumed, how state is projected to the display, what the polling loop looks like, what is never permitted (timers driving state, interpolation misrepresenting computation).
**KEY visual grammar** — the specific visual language: colors, shapes, motion primitives, how a surviving candidate looks different from an inadmissible one, how the promotion event is shown, how the contrast branch is visually distinguished from the GIE path.
**KEY stage text** — the complete on-screen text contract: every string, every trigger condition, every rule about what text cannot say.
-----
## I. Failure Must Be Visible
Failure is not incidental. It is structural evidence.
The renderer must show inadmissible candidates (hard veto) as visually distinct from admissible but non-surviving candidates. These are architecturally different outcomes and the viewer must be able to tell them apart.
The viewer must see:
- that most candidates fail
- that failure precedes success
- that success is rare and earned
If failure is visually minimized, accelerated, or hidden, the demo misrepresents the computation.
**The viewer must feel that success was difficult.**
This has a direct implementation consequence: the pacing of failure must not be compressed. Failed generations must occupy real time on screen. The inadmissibility count must be visible throughout the search, not hidden until the end. The contrast branch failure must receive the same visual weight and screen time as the GIE success.
Without this, the demo can still read as: “it quickly found the answer.” That destroys the core message. The difficulty of the search is not background context — it is the argument.
**Two failure types that must be visually distinct:**
|Type |Meaning |Visual treatment |
|------------------------|----------------------------------------------------------------|---------------------------------------------------------|
|Hard veto (inadmissible)|Structurally incompatible with world — eliminated before scoring|Distinct color/mark — immediate removal, no score shown |
|Admissible non-surviving|Passed world pre-screen but failed invariance test |Different color/mark — score shown, falls below threshold|
The viewer who can distinguish these two types understands something real about the architecture: the world is enforcing constraints before invariance is even measured. That is the dual-pressure claim made visible.
-----
## One-Line Reason This Document Exists
> The renderer must reveal the computation, not replace it with a story.
-----
## What This Document Actually Is
This is not a renderer spec. It is not a visual design guide.
It is an epistemic contract for representation.
It defines what can and cannot be shown, what can and cannot be claimed, and what the viewer is and is not permitted to conclude — given what the system actually does.
That makes it reusable beyond this demo. The same contract applies to papers, productization, regulatory submissions, and any other context where a computational system must be represented honestly to an audience that did not watch it run.
The renderer spec, visual grammar, and stage text are implementations of this contract. They are bounded by it. Any decision in those documents that conflicts with this one is wrong — not suboptimal, wrong.
-----
*This document is the conceptual lock. No renderer decision should be made without checking it here first.*