Principles of Experience Definition

Human-Centred Design

P001 XDL Declares Intent

Public framing

OpenXP puts the designer in charge. The designer's creative vision and intent is written into a single “experience” file as structured data, not filed away as a brief no one reads. Every line of the Experience Definition Language (XDL) is a commitment to what the experience will be — what the participant inhabits, what touchpoints exist, why specific actions fire. The runtime command (# openxp run my-experience.xdl --venue my-venue.xpvenue) serves that commitment; sensors, agents, and environmental variation cannot silently override it. This is what separates XDL from a runtime configuration language: the designer authors intent once, and the platform binds against that intent everywhere — at validation time, at execution time, at the verifier's static-analysis pass. A camera reading a room, an agent proposing a cue, an operator stepping in at the desk: all of them serve the declaration. None of them redefine it.

Technical framing

XDL is a declarative language. Every primitive — every field, every block, every annotation — is a declaration of what the designer commits the experience to be. There are no observation primitives, no descriptive primitives, no inferred-from-runtime primitives in XDL. Declaration is the only mode the language operates in.

This is the foundational principle. Every other principle, every primitive shape, every rule and verifier, every export to runtime is in service of this commitment.

Three levels of intent declaration

XDL declares intent at three levels, each more specific than the last:

1. Architectural Primitives declare the shape of the experience — what kind it is and what it commits to as a state of being: realm, domain, modality, synchronicity, senses, accessibility, processing. These are commitments, not constraints: the experience IS this shape from declaration onward; nothing toggles them at runtime. Together they answer "what kind of experience is this, what senses does it engage, who is it for, and how does it handle data?"
2. Structural primitives declare the capability and boundary the designer commits to expose — what the experience can do and within what limits: touchpoints (the perceptual, output, sensor, and control surfaces — including all perception.X subtypes per Principle P002), journey and state (the state-machine spine), actors and agents (live human delivery + AI participants), policies (the active operational rules per Principles 9–10), ensembles (bounded participant groupings), environments and zones (spatial regions), plus associated pipeline primitives (capture, deliver) and supporting structures (timelines, properties, safety, assets, schema). Each is exhaustively defined in XDL specification (xdl-spec-X.X.json); the list here is representative of the structural-intent surface, not exhaustive.
3. Operational annotations declare the human purpose behind specific actions and transitions: the intent: field is mandatory at experience-body and journey-body, and inherits down the scope tree (per Principle P601). Declaring intent not only defines the specific mechanical operations, it also defines why that moment in the experience exists.

All three levels carry equal weight as declarations. They are not "primitives plus annotations" — they are intent declared at three different scales of the experience.

Commitment vs Constraint. Architectural primitives are commitments — they describe what the experience IS, durably and unconditionally. processing declares the experience's privacy posture; accessibility declares the experience's commitment to participant needs; realm declares where it lives. These are inviolable at runtime. Structural primitives include both capability surfaces (touchpoints, journeys, ensembles — things the experience HAS) and active rules (policies — things the experience ENFORCES). A designer who treats processing as a togglable rule rather than a foundational commitment has misread the level.

Declarations describe actual instances, not conceptual possibility

Every XDL declaration refers to the actual thing the experience commits to. A touchpoint's realm declares where that touchpoint instance actually exists; not where similar touchpoints could exist, not where a participant might perceive it as existing, not where a future implementation might place it. A modality declaration commits to which sense channels actually carry the experience; not which channels could conceivably carry it. A domain declaration commits to what the experience actually IS; not which conceptual categories it could be classified under.

The distinction matters because XDL is executing an experience, not describing a possibility space. An output.lighting instance connected to DMX lighting hardware exists in the physical realm because the rendering happens in physical space. The same touchpoint type backed by AR rendering of light exists in the augmented realm because the rendering happens in augmented space. These are different instances of the same touchpoint type, with different realm declarations. Neither is a "conceptual" lighting touchpoint; both are actual lighting instances, differing only in where they actually render.

This is what eliminates ambiguity from XDL. Without the actual-not-conceptual rule, every declaration becomes negotiable: "could a participant perceive this lighting as part of an AR experience? maybe? so should it be declared augmented?" — and the declaration carries no commitment. With the rule, the declaration is unambiguous: where does the actual lighting render? That is its realm. Whether a participant perceives it as part of an AR scene or not is a separate question, answered elsewhere in the experience definition (typically by the journey's state realm, not by the touchpoint's realm).

Rationale

A specification that conflates declaration with observation is a specification where designer commitment can be silently overridden — by runtime conditions, by sensor input, by agent inference, by environmental variation. XDL exists to make designer commitment first-class and durable across all of these.

XDL captures designer commitment. The runtime, the agents, the simulators, the actors, the sensors, and the accessibility systems serve that commitment — they make immersion felt, lighting warm, agent reasoning coherent, accessibility real. Participant experience is the whole point of the work.

Runtime input is integral to this. A camera detecting boredom in an experience whose intent is "excitement" does not redefine the intent — it informs the runtime that reality has diverged from the designer's commitment, so the runtime, the actors, and the agents can act to restore it. Sensors, AI agents, and human actors form a closed loop that tracks the declared intent as its set-point. Inputs drive and measure the objective; declared intent is the objective.

The principle is one of authority, not isolation. Observation flows up; declarations stay constant; runtime closes the gap.

Operational intent annotations are not comments; they are functional metadata. The same is true at the structural and architectural levels — fields are not configuration values, they are design commitments. When an AI agent needs to adapt an experience for a different venue, audience, or mood, it consults the declarations at every level: what kind of experience is this (architectural), what capabilities does it expose (structural), what human purpose drives this specific action (operational). The agent serves the declarations; it does not overrule them.

Intent Compounds Through Inheritance. Intent declarations inherit down the lexical scope tree from experience to journey to state to transition. At every level, the resolved intent is the chain of declared intents from experience root to the current block. The deliberative agent (and any consumer of the XDL) MUST receive the full resolved chain — not just the local declaration — to construct an accurate mental model of why this block exists. Override semantics are REPLACE-on-override (per Principle P601); the parent chain remains traversable. Intent is mandatory at experience-body (the experience's soul) and journey-body (the journey's spine); optional at lower scopes where inheritance applies. Where omitted, the block inherits the nearest enclosing intent.

P002 Experiences Serve Perception

Public framing

OpenXP gives designers a vocabulary for what people actually feel. Six perceptions — warmth, energy, tension, calm, wonder, and presence — are the design surface XDL exposes. A designer working in OpenXP doesn't begin by wiring DMX channels or scripting cue lists; they begin by naming the perception the moment is built to produce. Warmth is the texture of welcome. Energy is the pulse of a room alive. Tension is the held breath before resolution. Calm is where thoughts settle. Wonder is the moment everything shifts. Presence is the feeling of being truly here, now. The runtime, the lighting rig, the spatial audio, the actor's read of the room — all of them serve those declarations. The compilation from "design for wonder" to "DMX universe 1, channels 1–24, warm amber at 70%" lives below the line; the designer stays above it.

P002 is the direct extension of P001 at the level of perception. P001 says every primitive in XDL is a declaration of intent; P002 says that at the human level, intent is expressed in the language of feeling and perception. This is the language Shakespeare wrote into his stage directions, the language ritual, ceremony, and theatre have carried for thousands of years, the through-line that every memorable experience — from a play, to a museum gallery, to a theme park attraction, to a brand activation — is built on. XDL is the first specification to make that language declarative, structured, and portable. It encodes a long inheritance of creative practice into a form a runtime can execute, a venue can carry forward, and another designer can read.

Technical framing

The fundamental unit of design is human perception — what someone sees, hears, feels, or senses — not a DMX channel, MIDI note, or API call. You describe what people experience, and what machines execute. The mechanical substrate (hardware protocols, sensor readings, actuator commands) exists to produce perceptions. XDL provides a human layer above this mechanical layer: designers author in terms of perceptions and intents; the runtime compiles these down to mechanical operations.

P002 stands on its own terms. The declaration is valuable whether or not any sensor will later corroborate it. An actor reading the XDL knows what to deliver. A lighting designer knows what mood to compose. A producer knows the arc the audience will travel. The measurement of an experience is not a sensor reading; it is the way one guest describes the show to another, the photograph that gets shared, the memory that returns years later. The network that carries an experience is human connection, not wires.

The six core perceptions are the design vocabulary. Each names something the designer commits the experience to produce, expressed in terms a human reader recognises. They are authored intent, not telemetry. The runtime — actors, agents, and mechanical outputs together — works to deliver them.

Warmth

The emotional tone of welcome. How a space says hello before anyone speaks.

Energy

Collective vitality. The pulse of a room full of people alive to what's happening.

Tension

The held breath of a moment that hasn't resolved. The shape of suspense.

Calm

The peaceful quality of a contemplative space. Where thoughts settle.

Wonder

Awe and discovery. The moment everything shifts.

Presence

Spatial awareness. The feeling of being truly here, now.

Rationale

Donald Hoffman's Interface Theory of Perception demonstrates that our perceptions are not faithful representations of objective reality — they are adaptive interfaces shaped by evolution for fitness, not truth. A red warning light is not "really" red; redness is an interface our visual system constructs. XDL takes this insight seriously: we design experiences at the interface level (perceptions, feelings, intents) because that is the level at which humans actually operate. The mechanical substrate is the hidden reality behind the interface. Hoffman's work informs this hierarchy but XDL uses its own terminology — perception, intent, senses — rather than claiming to implement any other formal framework.

P003 Feelings Are First-Class

Technical framing

Where P002 establishes the design language of perception and feeling, P003 establishes that the same affective qualities can also enter the runtime as signals, when the technology is available to support it. Emotions, comfort levels, excitement, and other affective states are not side effects — they are first-class inputs to the state machine, as legitimate as an NFC tap or a button press. XDL treats feelings as typed data with units, ranges, and sensor mappings.

P003 augments P002; it does not validate it. An XDL experience expressed in P002 is complete on its own — an actor-led piece with no sensors is a fully valid XDL experience, and many of the most memorable experiences ever staged were exactly that. What P003 adds is responsiveness in time: when a runtime can read affect, it can support the declared intent more attentively. Cues can adjust to the room. Actors can prompt changes, and be prompted. Deliberative agents can respond to intended perceptions, and reach for the next palette.

Mechanically, P003 inherits from P002. The same perception.warmth declaration that authors warmth as intent in P002 also exposes it as a channel the runtime can read when a source is bound. The declaration is not duplicated — same name, same range, now optionally readable. P003 does not introduce a parallel vocabulary; it activates the one P002 already established.

A biometric reading is a perception. A crowd energy level is a perception. A dwell time indicating boredom is a perception. These are not metadata — they are first-class inputs to the state machine. A sensor or an actor can trigger transitions on wonder, shape scenes with calm, and adapt entire journeys to the emotional arc of the room.

The source of a perception reading is not fixed. An actor can declare a reading through an actor.* touchpoint (per Principle P005). A reactive agent can derive a value from a window of lower-level signals. A camera can yield a crowd-energy aggregate. Whatever the source, the reading enters the state machine through the same first-class channel.

P002 and P003 are separate principles because both halves stand alone in different ways. A designer can author a complete P002-compliant experience without any P003 measurement: actors and static cues deliver the declared targets, and the experience holds. A runtime can stream rich P003 readings without any P002 declarations, but those readings would be telemetry without creative meaning — numbers without an intent to serve. Together they form the cycle of authored intent and responsive delivery: P002 declares, the runtime executes, P003 listens, the runtime adapts, the declaration holds. Both halves are real on their own terms; together they close the cycle.

Rationale

Every experience produces emotional responses. P003 makes them legible to the runtime as structured signals — typed, ranged, sourced — rather than leaving them implicit in the room. When the runtime can read affect, it can support the designer's intent more responsively. The transmission of the experience itself is still human: guest to friend, photo to feed, memory across time. P003 is how the runtime listens in real time, in service of the intent declared in P002.

P004 The Participant Completes the Experience

Public framing

An OpenXP experience is deliberately incomplete. The XDL file is not a script the participant performs; it is a set of conditions the participant inhabits and finishes in their own way. Shakespeare's plays endure across four centuries because they admit the audience as the final author of meaning, and remain different on every staging. Keats called this Negative Capability — the capacity to hold uncertainty without collapsing it into a fixed reading. OpenXP makes this architectural rather than incidental. Designers commit to conditions — moments, perceptions, materials, cues, actor judgment, agent attention — and trust the human in the room to inhabit them. An experience that tries to control how participants feel is brittle, because human response refuses control. An experience that encodes conditions and trusts the participant to complete them holds, because it admits human variation as the architecture rather than as the edge case.

Technical framing

The participant is the only first-class entity in an experience whose presence cannot be declared and whose behaviour cannot be specified. They arrive, inhabit, interpret, and depart, bringing with them their own perception, history, attention, and meaning. P001 declares the designer's intent. P002 expresses that intent in the language of perception. P003 lets the runtime listen for affective signals when the technology supports it. P004 names the asymmetry the other three depend on: the XDL file encodes the conditions for the experience; the participant completes it.

This is not a limitation of the language. It is the architecture. An experience that tries to control participant response is brittle, because human response cannot be controlled. An experience that encodes conditions — moments, perceptions, materials, cues, actor judgment, agent attention — and trusts the participant to inhabit them is robust, because it admits human variation as foundational rather than as edge case. Shakespeare's plays endure across four centuries and every culture they have travelled to because they are deliberately incomplete; the audience completes them, and completes them differently every time. Keats called this quality Negative Capability — the capacity to be in uncertainties, mysteries, and doubts, without irritable reaching after fact and reason. XDL is the first executable specification that names this quality as a design principle.

P004 makes the other three principles cohere by clarifying what they each claim and what they do not.

P001's declarations describe what the experience commits to be, not what each participant will feel. A realm: physical declaration commits the experience to physical delivery; it does not commit the participant to a physical experience of presence — some participants may feel dislocated, transported, or absent. The declaration is real; the response is not predicted.

P002's design vocabulary is for authoring conditions, not for engineering response. A perception.warmth { intent: "welcome" } declaration commits the experience to producing the conditions of welcome; whether a particular participant feels welcome on a particular day is the participant's completion, not the system's verification.

P003's measurement, where present, supports responsiveness, never validation. A camera reading low crowd energy does not mean the design failed; it means the runtime now has the information to adjust in service of the declared intent. Absence of measurement does not mean the experience failed either; it means the participant's completion is happening privately, as it does in every actor-led piece staged for millennia.

P005's actors are the principal vehicles of participant completion when sensors and agents are absent — an actor reading the room is the runtime's oldest measurement channel, predating every electronic sensor by thousands of years.

The principle has a practical consequence the spec must honour. Where measurement of perception is possible, the design should consider whether to measure — not to validate the design, but to remain responsive to the participants who are completing it. Where measurement is not possible, the absence is not a defect; the participant completes the experience anyway, through actors, through designed cues, through their own attention. The XDL must accommodate both modes without privileging the measured one. This is what R308 enforces: every perception touchpoint declaration must record a source consideration — source: authored, a concrete source: binding, or source.consider: [...] — but the validator emits an advisory, not an error, when none are present. The principle prompts the designer to consider; it does not force them to bind.

Rationale

The most durable creative artefacts in human history — Shakespeare's plays, Greek tragedy, ritual, ceremony, the great novels, the great films — are durable because they are incomplete. They create conditions for human response without dictating it. They train interpretation rather than collapsing it. Donald Hoffman's Interface Theory, cited in P002, tells us that perception is an active construction, not a passive reception; the participant's completion of an experience is the same active construction at the level of meaning. An experience-orchestration language that aspires to the durability of Shakespeare's plays — to be carried across venues, across decades, across cultures, by readers who were not in the original room — must encode this asymmetry as a foundational principle, not as an afterthought.

The principle also speaks to a practical truth every experienced designer knows. Humans will find unexpected paths through any experience, often in the most surprising ways. They will misread, repurpose, ignore, redirect, transcend, and surprise. A logical approach to a mechanical problem is always upended by humans. An experience that does not account for this will fail at first contact with reality. An experience that admits it as the architecture — that encodes conditions and trusts the participant to inhabit them — will hold.

P005 The Actor Is a First-Class Participant

Public framing

Live actors carry the most transformative immersive experiences, and OpenXP is designed around that fact rather than against it. The performer, the host, the guide, the musician, the puppeteer — these are the highest-bandwidth instruments in an immersive production, and the technology stack serves them rather than replacing them. The journey graph offers an actor cues; the actor reads the room and chooses the next moment. The AI agent proposes a lighting change; the actor's creative judgment overrides it without ceremony. This is not nostalgia for hand-crafted theatre amongst sensor-driven systems. It is a hierarchy: the technology serves the actor, the actor serves the audience, and the audience completes the experience. OpenXP encodes that hierarchy at the language level so a production team — designer, runtime, operator, performer — can rely on it.

Technical framing

The human actor — performer, stage manager, facilitator, guide, musician, puppeteer — is the most potent creative element in an immersive experience. XDL recognises the actor as a distinct event source whose creative decisions in the moment carry higher authority than any AI agent tier (per the Event Authority Hierarchy, Principle P106).

An actor is not an operator. An operator intervenes against the system's intended behaviour — holding, resetting, overriding in response to technical or safety concerns. An actor works within the system's intended behaviour — advancing, selecting, improvising within the creative director's declared constraints.

An actor is not a sensor. A sensor fires when a physical condition is met. An actor fires when a creative judgment is made. The runtime distinguishes between these because they carry different authority, different audit semantics, and different verification requirements.

Rationale

A language that treats a trained artist's creative decision identically to an MQTT message has failed to understand what makes immersive experiences work. The most transformative, memorable immersive experiences consistently rely on live actors — the highest-impact productions are actor-driven with minimal technology. The technology serves the actor. The actor serves the audience. This hierarchy is operational, not philosophical. When a deliberative agent proposes a lighting change and an actor triggers a scene transition, the actor's creative judgment — constrained by the creator's declared artistic policies — takes precedence.

P006 Human-Readable Code

Technical framing

XDL is a text format with a grammar designed for human authorship and review. It is not a serialisation format that happens to be readable. Designers should be able to read, write, and understand XDL without specialised tooling.

Rationale

Experience design is a collaborative discipline. Designers, producers, account managers, engineers, and operators all need to understand what an experience does. A format that requires a programmer to decode it excludes most of the team. XDL's syntax — curly braces, colons, named blocks — is also deliberately familiar to anyone who has worked with human friendly formats such as CSS, JSON, or a configuration file.

Determinism and Safety

P101 Non-Turing-Complete by Design

Technical framing

XDL is intentionally not a full programming language. It has no loops, no variables, no conditionals beyond guards, no recursion, no function definitions. It is a declaration language: you declare states, transitions, guards, and actions. The runtime executes them.

This is not a limitation — it is a safety guarantee. An XDL file cannot contain an infinite loop, a stack overflow, a race condition, or an undecidable computation. Every XDL file terminates. Every state machine is finite. Every guard is a pure boolean expression.

Rationale

XDL files control physical environments where people are present. An infinite loop in a lighting controller is a safety hazard. An undecidable guard expression is an unpredictable experience. By restricting expressiveness, XDL guarantees that every file can be fully analysed, simulated, and verified before deployment.

P102 Deterministic Execution

Technical framing

Given the same XDL file and the same sequence of events, the runtime MUST produce the same sequence of state transitions and actions. There is no hidden state, no randomness in the core execution model, no ordering ambiguity.

Declaration order is evaluation order. If two transitions could fire on the same event, the first one declared wins. If two policies conflict, priority tier resolves it; within the same tier, declaration order wins.

Scope of the determinism invariant. Determinism governs the behaviour of a single journey instance. If Alice's journey is at state gallery and a proximity_sensor.detected event arrives, the runtime produces exactly the transition the XDL declares for that state and event. Replay the same sequence of events into the same starting state and you get the same outcome — Alice's journey entrance → gallery → finale → gift_shop is fully deterministic from the moment she begins until she leaves. This is the runtime's core promise to designers, verifiers, and operators.

Files read as a single linear narrative; execution is a graph. An XDL file reads from top to bottom as a single, coherent declaration of intent — each phase, moment, and state written once, in place, in the order a designer would narrate it. The runtime executes that content as a graph of state transitions driven by live events, not as a sequence following the file's lexical order. Declaration order resolves guard conflicts within a state (see above) but does not imply that the runtime traverses states top-to-bottom. A participant's actual path through an experience is determined entirely by the events that arrive and the guards that evaluate, which may traverse states in any order the transition graph permits. Global interrupts (emergency stop, fire, venue-wide abort) live in experience-root safety {} and policies {}, evaluated on every event under Safety > Operator > Artistic — they are orthogonal to the narrative hierarchy (R134; D-21) and do not alter this guarantee.

Determinism does NOT govern the relative ordering of events that arrive from multiple participants or external sources at the same moment. Cross-instance arrival order is the concern of the underlying transport (DMX HTP/LTP, OSC ordering, media-server cue semantics) and the policy contention rules (Principle P103's four-tier priority). If Alice and Bob both reach gallery and both trigger proximity events within the same millisecond, the runtime resolves the contention deterministically per the priority tiers — but the specific arrival order is a property of the world, not of XDL.

Rationale

Non-determinism in experience execution means unpredictable guest outcomes. A theme park ride that sometimes skips a cue, a retail display that occasionally shows the wrong content, a safety system that fires inconsistently — these are not acceptable. Determinism is the foundation on which operators build trust. A producer who walks through an XDL file can predict what the runtime will do. A venue operator can reproduce a guest's reported issue by replaying their event log. A legal reviewer can audit a privacy-sensitive sequence without running the experience. None of this is possible if the runtime might skip a cue, reorder a transition, or branch on a non-XDL condition.

P103 Four-Tier Priority

Public framing

Every risk in OpenXP is a policy, and every policy carries one of four labels — safety, privacy, operational, design — that determine which wins when two of them collide. Safety is always at the top, and design is always at the bottom. Fire detection beats throughput. Consent beats schedule. Schedule beats aesthetic preference. The four labels are a total order: every policy belongs to exactly one of them, and the order does not move between experiences. A producer reading an XDL file knows the chain of precedence without consulting the rule book. A safety reviewer can prove that nothing the language declares can quietly outrank the safety tier. A venue operator can build trust on a contract that is the same on every show. The tiers are public, named, and fixed by the language rather than by the deployment. Declared policies bind on every action source — AI agent decisions, journey-transition do: actions, and any other mechanism that dispatches work into the runtime — so no action category is exempt from the priority order.

Technical framing

Every policy in XDL is declared at one of exactly four priority tiers — safety, privacy, operational, design — evaluated in strict order. Safety always wins. Declared policies { priority: ... } bind on every action source: journey-transition do: actions, AI-agent-produced actions, and any future action source. No action category receives an implicit exemption from the priority guarantee. The runtime evaluates the full transition batch against applicable policies before any action executes — if any action in the batch is blocked, no action in the batch executes and the policy's P104 response governs (see P104 — Graduated Response Model for the stop/halt/degrade/advisory vocabulary).

1. safety — human wellbeing, physical limits, emergency stops
2. privacy — data protection, consent, biometric handling
3. operational — throughput, scheduling, resource management
4. design — creative intent, aesthetic quality, content standards

A lower-tier policy can never override a higher-tier policy. The tiers are total-ordered: every policy belongs to exactly one tier, and tier priority is fixed across the spec — designers cannot re-rank tiers experience-by-experience.

Distinguishing safety { } from policies { priority: safety }: XDL provides two distinct safety mechanisms with different runtime scopes. The safety { } block gates journey transitions at event granularity — it runs before the state-machine tick and can prevent a transition from firing entirely. Declared policies { priority: safety } bind the four-tier priority guarantee on every action source dispatched within an accepted transition — they operate at action-dispatch granularity, one batch per transition. The two mechanisms are complementary: safety { } holds the journey at its current state before a potentially-unsafe transition advances; policies { priority: safety } ensures that any action dispatched during an accepted transition cannot bypass the safety tier. Designers may use both in the same experience.

Rationale

Three-tier priority (safety/operational/design) leaves privacy floating between safety and operations. In physical venues with biometric sensors, cameras, and tracking systems, privacy deserves its own tier — higher than operational convenience, lower than physical safety. The four-tier model makes the hierarchy explicit and unambiguous, and lets verifiers prove that safety-critical and privacy-critical effects always reach the runtime. Binding policies on every action source — not only AI-agent decisions — closes the gap where journey-driven do: actions could otherwise bypass declared constraints, making the priority guarantee verifiable end-to-end across all XDL execution paths.

P104 Graduated Response Model

Technical framing

Policy enforcement is not all-or-nothing. Each policy declares its response level — stop, halt, degrade, or advisory — which the runtime applies when the policy fires.

The four response levels:

• stop — terminate the action; the violating event is not processed; the runtime emits a diagnostic and the journey holds in the current state. Default for safety-tier policies.
• halt — pause the journey at a safe boundary; the runtime waits for operator or policy clearance before resuming. Default for privacy-tier policies.
• degrade — execute a fallback action declared by the policy; the journey continues with reduced fidelity. Default for operational-tier policies.
• advisory — log the violation; the journey continues unchanged; downstream review tooling surfaces the diagnostic. Default for design-tier policies.

Each tier has a sensible default but designers can override the default per-policy when needed (e.g., a design-tier policy that fails closed via stop because the creator deemed the violation intolerable).

Rationale

Not every violation is an emergency. A stop for a content quality issue would ruin the experience. An advisory for a fire alarm would endanger lives. The graduated model forces designers to think about proportionality and gives the runtime clear instructions for each scenario, while keeping the maximum-severity option (stop) available for the violations that need it.

P105 Three-Stage Policy Lifecycle

Technical framing

Every policy in XDL flows through three stages — Author, Validate, and Runtime — and is identified by name, tier, response level, and effect at every stage. Each stage has clear ownership: authors write policies; the validator proves them sound; the runtime executes them.

Rationale

A policy that is only checked at runtime is a policy that surprises operators. A policy that is only checked at design time is a policy that may not behave as expected under real conditions. The three-stage lifecycle separates concerns: design-time intent (Author), pre-deployment proof (Validate), and execution-time enforcement (Runtime). Every policy has a clear contract at each stage and is auditable end to end.

P106 Event Authority Hierarchy

Technical framing

XDL declares a strict authority hierarchy that governs which event source wins when two or more sources attempt to influence the same journey state at the same moment. The hierarchy has eight levels, from highest authority to lowest:

1. Safety Interlock — physical-safety hardware (e-stop, fire alarm, harness sensor) and runtime safety guards. Highest authority. Bypasses all other sources.
2. Operator Intent — explicit operator command (hold, resume, skip, reset, override). The named human running the experience.
3. Actor Intent — human-initiated event from an actor.* touchpoint. Live creative judgment.
4. Artistic Policy — designer-declared policies in the design tier (Principle P103).
5. Compositional Agent — agent.compositional proposing journey-scale structural changes over minute-scale horizons.
6. Deliberative Agent — agent.deliberative proposing considered, multi-step adjustments. LLM-backed.
7. Reactive Agent — agent.reactive responding to immediate sensor input. Rule-based, sub-second.
8. XDL Journey — the declared journey graph itself.

When two sources fire on the same target at the same moment, the higher-authority source's effect wins; the lower-authority source's event is logged as "superseded" in the Decision Log and does not affect the journey state. Where a level holds standing authority (e.g. an operator places the journey in hold), all lower levels are blocked until that authority releases.

The three agent tiers — Reactive, Deliberative, Compositional — each have a fixed contract for latency, model dependence, and runtime fallback. Reactive: <100ms, rule-based, no LLM. Deliberative: 1–30s, LLM-backed creative decisions, mandatory fallback. Compositional: minute-scale pipelines (video compositing, artwork generation, souvenir production), no required LLM in the core contract but mandatory fallback.

Rationale

Without a hierarchy, a reactive agent firing on a participant's facial expression could overrule an actor’s creative judgment, or an operator's emergency hold could be undone by a journey-graph transition. The hierarchy gives every event a known place in the priority order and lets verifiers prove that human authority — the operator at the desk, the actor on the floor — is never silently overruled by an AI proposal or a journey-graph quirk. Hierarchy enforcement is the validator's job (Phase B) and the runtime's job (R409).

P107 Simulation Precedes Production

Technical framing

An XDL experience cannot run in production until the same bundle has produced a successful end-to-end simulation pass against the target venue. The production runtime refuses to start without a matching simulation receipt — same XDL hash, same venue fingerprint, same touchpoint inventory.

The simulation requirement is a hard gate, not a recommendation. Production runtimes embed the receipt check; they have no flag, environment variable, or configuration override that disables it. Designers, operators, and venue staff cannot bypass it. The only way to satisfy the gate is to run a clean simulation.

Rationale

Live immersive experiences run with paying guests in physical venues. The cost of a journey graph that "almost works" is not a stack trace in a log; it is a guest stuck in a dark room, an actor delivering a cue to silence, a queue collapsing under load. Simulation against the target venue catches the categorical failures — unreachable states, dangling touchpoints, missing assets — before they reach guests. The pre-production gate enforces this discipline at the language level instead of trusting that operators will remember to run the simulator.

Privacy and Consent

P201 Privacy by Design

Public framing

Privacy is written into the XDL next to the sensor that captures the data, not assembled later in a compliance document nobody reads. When a heart-rate monitor is declared in an OpenXP experience, the file states what mode the data lives in (transient, scoped, or retained), what purpose it serves, what lawful basis supports it, and how long it survives — all in a processing { } block attached to the touchpoint itself. The producer of the data sits inline with the contract that governs it. A privacy reviewer can audit the file directly without learning a separate compliance toolchain. An operator cannot deploy a biometric sensor without declaring its processing contract first. This is what privacy by design means at the language level: the contract travels with the capture, the language refuses to separate them, and the discipline becomes the default rather than the exception.

Technical framing

Privacy is not a configuration setting, an external compliance layer, or an afterthought. Privacy by Design is a core architectural posture: every touchpoint that captures data encodes its data-governance contract within the experience definition itself, not in a separate compliance document or runtime configuration. XDL encodes this intent in the processing { } block — a language primitive that binds data mode (transient, scoped, or retained), purpose, lawful basis, and retention semantics directly to the touchpoint producing or consuming the data.

Rationale

When privacy is a separate configuration file, a deployment setting, or a compliance checkbox, it gets forgotten, misconfigured, or overridden. When the processing { } contract is written into the experience definition itself — right next to the sensor that captures the data — it is visible to every reviewer, auditable by every tool, and enforceable by the runtime. You cannot deploy a biometric sensor without declaring its processing contract. The block name processing aligns the spec with GDPR Article 4(2) ("processing of personal data") and ISO/IEC 27701 vocabulary; the architectural principle of "Privacy by Design" (GDPR Article 25; Cavoukian's 7 PbD foundational principles) is the strategic posture this language primitive implements.

P202 Special Category Data Requires Explicit Declaration

Technical framing

When a touchpoint captures special category data as defined by GDPR Article 9 — biometric data used for identification, health data, racial or ethnic origin, political opinions, religious or philosophical beliefs, sex life, sexual orientation, genetic data, or trade union membership — the XDL must declare an explicit processing { } block on that touchpoint. The block carries the processing contract directly inline with the touchpoint that captures the data.

R505 (Special Category Data Declaration) constrains the lawful.basis to one of the Article 9(2) conditions — these are the ten legitimate bases under GDPR for processing special category data. The XDL spec does not narrow that set further; jurisdictions that constrain it more tightly (e.g. national implementations of Article 9(4)) apply downstream. R509 (Processing Block Required on Special Category Touchpoints) enforces the principle's "explicit declaration" requirement: no implicit processing on biometric or other special-category touchpoints.

Rationale

GDPR Article 9 treats special category data as fundamentally riskier than ordinary personal data and demands an explicit lawful basis. Encoding the requirement at the language level — not in a separate compliance layer, not in deployment review, not in operator discretion — means every special-category capture surfaces its processing contract inline with the capture itself. Privacy regulators and ethics reviewers can audit the file directly; the requirement cannot be lost between layers. The spec stays as permissive as the law allows; downstream policy and jurisdiction-specific rules narrow as needed.

P203 Ephemeral by Default

Technical framing

Data captured by XDL experiences is ephemeral unless explicitly declared otherwise. The default value of mode is transient — biometric readings, facial recognition data, location tracking, and other sensitive signals exist only for the duration of the session. They are not persisted, not exported, not retained.

To retain data beyond the session, the designer must explicitly opt in with mode: retained and a declared retention.period.

Rationale

The safest default is to keep nothing. In a world of GDPR, CCPA, and evolving privacy regulation, the default must be privacy-preserving. Designers who need to retain data must consciously choose to do so, and that choice is visible in the XDL file for audit and review.

P204 Scoped Data Visibility

Technical framing

Data flows in XDL are scoped. A touchpoint's data is visible only within the lexical scope where its processing { } block sits — declared once at the level the designer intends (experience, journey, or state), inherited inward, and invisible outside (resolved per R209 container inheritance). There is no global data bus; visibility is declared, not assumed.

Rationale

In a physical venue with dozens of sensors and cameras, unrestricted data flow creates surveillance. Scoping ensures that a heart rate monitor in a wellness zone cannot be read by a marketing integration in the gift shop. Data goes where the designer sends it, nowhere else.

P205 Adaptive Without Surveillance

Technical framing

XDL enables experiences that adapt to participants in real time without building persistent profiles. Three primitives compose to make this possible: realm (Principle P301) declares the medium of presence the designer commits the experience to and constrains the signals available within it; perception captures or infers participant state in the moment; processing modes (Principles 14–17) guarantee that captured state is used immediately and discarded.

The trade-off is explicit at the language level. A designer who wants higher-fidelity perception — gaze tracking, biometric depth, fine-grained gesture — must commit to stronger transient guarantees in the same block. The trade-off cannot be moved to deployment, to a separate configuration, or to operator discretion.

Rationale

The result is a posture: the participant is fully present, fully read, and fully forgotten. An experience can respond to an emotional peak without recording who felt it. A queue can balance throughput against fatigue without retaining a fatigue history. A wearable can drive an adaptive scene without the scene becoming a profile. This is what separates an adaptive experience from a surveillance system, and XDL puts the boundary at the language level — not at the policy layer, not at the deployment review, not at the operator's discretion. By the time an XDL file describes adaptive behaviour, the discard contract is already written.

Realm Fluidity

P301 Experiences Flow Across Realms

Public framing

An OpenXP experience is not bound to one medium. A guest might begin in a physical queue, continue on a digital companion app, dive into a virtual reality world, and search for a hidden augmented souvenir — all within the same journey. XDL treats realms as first-class declarations: each realm is the designer's commitment to a medium of presence, where the participant actually inhabits the experience at that moment. The four realms are a closed set — physical, digital, augmented, virtual — and the journey flows between them through explicit transitions written into the file. The runtime, the agents, and the touchpoints serve the realm declaration; sensor inference and runtime conditions cannot silently override what the designer has committed the participant to. Modern experiences are not single-channel; OpenXP models the full spectrum without collapsing it into the hardware layer.

Technical framing

XDL declares the realm an experience is designed for — the medium of presence the designer commits the participant to inhabit. Realm is a designer commitment, not a perceptual observation: a state declared realm: physical is an experience the designer has committed to delivering through on-site venue hardware, regardless of what sensors might infer about the participant in the moment.

The four realms are a closed enum:

• physical — on-site venue hardware, real-world installations, mobile-companion experiences anchored in physical space.
• digital — screens and apps, software-only interfaces, no physical-world coupling required.
• augmented — actual world layered with constructed elements (AR overlays, projection mapping, headset-augmented venue space).
• virtual — wholly constructed environments (VR headsets, immersive 3D worlds, fully-rendered virtual spaces).

These are not categories of what the participant perceives — they are categories of what the designer commits the experience to be. An experience declared realm: augmented is a commitment to design for augmented presence; the runtime, agents, sensors, and actors then serve that commitment. This anchors the realm primitive in declaration semantics per Principle P001.

Realm is not confined to a single value across an experience. A guest might begin in a physical queue, continue on a digital companion app, enter a virtual pre-show, and return to physical for the main event — all within a single XDL experience. Container inheritance (Principle P601) propagates realm down through journey, state, and touchpoint scopes; inner blocks can redeclare without affecting siblings (Principle P302). Participants inhabit exactly one realm at a time (Principle P303), with cross-realm content delivery handled by touchpoints declared in any realm (Principle P304). Lexical-scope resolution and transition emission live in R209; touchpoint-realm validation lives in R604; per-touchpoint compatibility is declared in the realm.compatibility table in xdl-spec-1.0.json.

Realm portability is asymmetric. Physical-realm declarations generally embed into less-constrained realms — a digital companion experience can ship alongside a physical experience; augmented overlays can layer onto a physical state. Virtual-realm declarations cannot generally be transposed back to physical without redesign: a wholly-constructed environment loses the physical-anchored constraints (proximity, lighting, room scale) that physical experiences depend on. Designers committing to virtual-realm experiences are committing to a narrower portability profile. v1.0 surfaces the asymmetry as architectural truth; a formal portability matrix may land in a future revision.

Rationale

Modern experiences are not single-channel. A theme-park app extends the ride. An AR layer enhances a museum exhibit. A virtual pre-show prepares guests for a physical experience. XDL must model the full spectrum, not just the hardware layer. By declaring realm as designer commitment rather than perceptual observation, XDL keeps designer authority first-class and lets runtime systems serve that authority.

P302 Layered Realm Defaults

Technical framing

The experience declares a default realm; individual journey states, touchpoints, and other inner blocks can override it. Overrides at inner levels do not leak to siblings — a single state declared realm: virtual does not change the realm of neighbouring states. The R209 lexical-scope walk resolves the effective realm for each block by walking outward until it finds a declaration.

Rationale

Most experiences are primarily in one realm with exceptions. A physical venue experience might have a digital companion app and a virtual preview. Declaring every component's realm individually would be tedious and error-prone. Layered defaults keep the common case simple and the exceptions explicit.

P303 Sequential Realm Inhabitation

Technical framing

A participant is in exactly one realm at a time. The realm of the current state determines which realm — this is a designer commitment, not a phenomenological description of what the participant feels. A VR-coaster rider feels both G-force and a rendered environment simultaneously; the designer commits the state to realm: virtual and treats the physical motion as cross-realm content delivery into that virtual state.

Transitions between realms are first-class runtime events (per R209 and R603). The four-realm enum is closed: no implicit fifth realm, no tacit blending of two declared realms into a third. Where an experience feels hybrid, the designer must commit to one realm and treat the others as content delivered into it.

Rationale

Modern blended experiences — theme-park guest queueing in physical, donning AR glasses for a pre-show in augmented, entering a fully immersive room in virtual — pass through multiple realms on a single journey. Without strict singularity at the state level, the language would have to admit hybrid realms (physical+augmented, virtual+haptic, …) and the combinatorics would explode. By forcing the designer to commit to one realm per state, XDL keeps the runtime contract finite, the verifier walk decidable, and the journey itself legible to anyone reading the file. The asymmetry between "what the participant is committed to" and "what touchpoints deliver" is what Principle P304 (Cross-Realm Content Delivery) handles.

P304 Cross-Realm Content Delivery

Technical framing

The realm of a state declares where the participant is committed to being. The realm of a touchpoint declares where the touchpoint's mechanical operation lives. These are independent declarations: a touchpoint declared in one realm can deliver content into a state declared in another, and the runtime bridges them.

The pattern has directional asymmetry. Physical-realm touchpoints can deliver into any state realm (a physical haptic device reaches a participant whose state-realm is virtual; physical room speakers reach a participant in an augmented state). Digital and augmented touchpoints can deliver into states of equal or greater immersion. Virtual-realm touchpoints can only deliver into virtual states — a rendering inside a headset cannot reach a participant who isn't in the headset. Designers commit to the most-immersive state realm an experience requires; physical touchpoints flex to serve it.

Realm is single-valued. XDL does not support multi-valued realm declarations like realm: [virtual, physical]. Where an experience feels multi-realm — a VR coaster, an AR theatre, a haptic companion device for a physical ride — the designer declares the realm the participant is committed to, and uses cross-realm content delivery to model touchpoints from other realms. Multi-valued declarations would break inheritance resolution, transition events, verifier reachability, and the asymmetric portability of Principle P301.

Rationale

Modern experiences depend on this independence. A VR coaster's motion is mechanically physical but experientially virtual. A theme-park companion app's notifications are mechanically digital but contextually physical. A museum's room audio is mechanically physical but layered onto an augmented state. If touchpoint realm were forced to match state realm, every cross-realm pattern in immersive experience design would be unrepresentable in XDL. Decoupling them lets the language describe what experiences actually are, not what a single-realm model can fit.

Composability and Extensibility

P401 Universal Primitives, Optional Vocabulary Packs

Public framing

OpenXP is one open standard, with a small core of universal primitives that every experience uses and a set of optional vocabulary packs that extend the language for specific industries. The core covers touchpoints, actions, guards, and policies — the structural surface a designer needs whether the work is a theme park ride, a museum gallery, a retail flagship, a wellness journey, or a learning programme. Domain-specific vocabulary loads on top via the use: directive: a theme-park pack adds ride vehicles and queue management; a healthcare pack adds clinical roles and pathway primitives; a museum pack adds exhibit and dwell-time vocabulary. The author learns the core once, and the same language carries across every domain a venue might serve. Cross-domain experiences — a museum that hosts a learning programme and a retail flagship — compose without translation layers.

Technical framing

XDL ships with a core set of universal primitives — the touchpoint categories, action types, guard functions, and policy constructs that every experience needs. Domain-specific vocabulary (theme park rides, retail stores, concert venues, museums) is loaded via optional vocabulary packs declared with the use: directive. Pack-defined subtypes use the dot-form category.subtype notation per R112.

Single declaration, no parallel enumeration. Every construct in XDL is declared exactly once, in exactly one place. Design-time views — visual arc diagrams, storyboards, walkthrough previews, journey maps — are projections derived from the canonical source by tooling at authoring and display time. They are never authored separately and linked back by string key. A beat written once in its moment block is the only authoritative form; every other representation of that beat is generated from it, like a table of contents auto-built from chapter headings. This is the structural expression of P001 (XDL Declares Intent) at the journey level: intent is declared once, not duplicated. Governed by R134 (Single Journey Enumeration) for the phase ⊃ moment ⊃ state hierarchy.

Rationale

A language that tries to include every domain's vocabulary in its core spec becomes bloated and opinionated. A language that provides no vocabulary at all requires every project to reinvent the wheel. Vocabulary packs split the difference: the core is small and universal, domain packs add richness without bloating the base.

Adding new language primitives raises the bar. Top-level blocks, transition forms, action shapes, and guard expressions are the language's structural surface — distinct from vocabulary (subtypes), which lives in packs. A new primitive is justified only when an existing primitive demonstrably cannot express the use case through composition. Three things must be published with any proposal: at least one real use case (cross-industry preferred); a worked attempt to express it with existing primitives; a clear demonstration that composition fails or produces unmanageable cost. New primitives may not be added pre-emptively, "for symmetry," or to "round out the design." The language stays sparse by construction; richness is delivered via vocabulary packs (Principle P406).

The single-declaration discipline gives the same return on the narrative structure that vocabulary packs give on the vocabulary surface: a sparse, authoritative source with derived representations as needed. A parallel journey.map block re-stating the journey's moments is exactly the kind of design-time duplication this principle forbids — it doubles the authoring surface, creates a synchronisation obligation, and violates single-source-of-truth. The journey { phase ⊃ moment ⊃ state } hierarchy is the single canonical tree; tooling projects it into arc views on demand.

P402 One Canonical Format

Technical framing

There is exactly one way to represent an XDL experience. There is no "compact mode", no "binary format", no "alternative syntax". The text format is the canonical format. The runtime may optimise internally (pre-compiled state tables, indexed lookups, compressed assets) but the source of truth is always the human-readable text.

Source mapping connects runtime execution back to authoring-time line numbers, enabling debugging and audit trails.

Rationale

Multiple formats create translation bugs, versioning headaches, and tooling fragmentation. One format means one parser, one validator, one set of fixtures, one source of truth. The runtime's internal representation is an optimisation detail, not a format.

P403 Self-Describing

Technical framing

XDL should be capable of describing its own tools, processes, and governance. The language’s own evolution — how spec changes are proposed, validated, and released — can be expressed as an XDL experience.

This is not a theoretical curiosity. It is a concrete design goal: the OpenXP platform's governance process is itself an XDL file (platform.xdl) that defines the states, transitions, policies, and actions of spec evolution.

Rationale

A language that cannot describe its own tools is incomplete. Self-description validates that XDL is expressive enough for real-world processes, provides a living example of the language, and enables the agentic evolution loop where AI agents propose spec changes governed by XDL policies.

P404 Abstraction and Compartmentalisation

Technical framing

Complex experiences should compose from simpler building blocks. XDL supports inclusion of sub-experiences, asset references, and modular journey definitions. Each component can be authored, tested, and validated independently.

Rationale

A 500-line monolithic XDL file is as unmanageable as a 5000-line monolithic program. Composability enables teams to work in parallel, test components in isolation, and reuse proven building blocks across experiences. A theme park's queue management module should work identically whether it is used in a ride, a restaurant, or a retail store.

P405 One Naming, Two Forms

Technical framing

Every named entity and operation in XDL is identified by a category and a member: category.subtype for entities that exist, category.verb for operations that fire. The form follows the role. A touchpoint is declared as a block; an action is invoked as a call. The grammar makes the distinction visible to anyone reading a file.

When a designer writes actor.host, they are naming a thing — a host who participates in the journey, declared once and referenced by other constructs. When they write cue(), record(), or merge(), they are firing an operation — a runtime event with arguments and a return point. The block-versus-call distinction is not decorative. It mirrors the underlying semantics: entities are stable across a state's lifetime; operations are momentary, ordered, and traceable.

Rationale

This duality keeps XDL legible at scale. A reader scanning a journey can distinguish "what exists" from "what happens" at a glance, without consulting the spec to decide whether cue is a touchpoint or an action. The naming rule and the parser cooperate: the parser rejects verb-first or noun-first forms in the wrong position, so misuse fails early rather than producing surprising runtime behaviour.

P406 One Catalogue, Many Domains

Technical framing

XDL has one catalogue of categories and subtypes. There are no aliases, no domain dialects, no parallel namespaces. A clinical pathway, an immersive activation, and a learning experience all reach into the same vocabulary; they differ in which subtypes they emphasise, not in which language they speak.

Vocabulary packs extend the catalogue with domain-specific subtypes within the existing category structure. A medical pack adds actor.clinician under the same actor category that already houses actor.host and actor.guide. A retail pack adds wearable.watch.smart.acme under the same wearable.watch.smart family. New subtypes nest under existing categories; they do not invent new top-level vocabularies that compete with the base.

Rationale

This is the rationale that animates the catalogue naming convention. If two domains were free to fork the catalogue, the language would fragment into mutually unintelligible dialects within a year of release. By forcing every subtype into the same compositional shape — and by validating that shape at pack registration — XDL stays one language across every domain that adopts it. Authors learn the catalogue once. Tools index it once. Cross-domain experiences (a museum that hosts a learning programme and a retail flagship) compose without translation layers.

Vocabulary packs may be delivered as files (cross-experience scope) or as inline extend {} blocks (experience-local scope). Both flow through the same registration pipeline; both honor R112 and R116.

No subtyping, leaf-typed. XDL declares no subtype relation. Every type is its own primitive; relationships between types are advisory metadata, never substitutability. realm.compatibility documents which realms can flow content into which others — it describes flow direction, not partial order, and a value declared realm: virtual is never substitutable for realm: physical even if the compatibility table permits content flow between them. Type predicates evaluate by exact match against the catalogue. This forecloses an entire class of evolution traps: introducing subtyping additively in a future major release is permitted (R802-safe); declaring a partial order now and backtracking would re-classify existing programs (R802-breaking). The leaf-typed posture preserves the option without committing the cost. See spec/RULES.md R807 + R808 for stability tier mechanics; see Principle P701 (Warn-but-Preserve for Forward Compatibility) for handling of unknown metadata keys.

One declaration, derived projections. P406's "one catalogue" discipline extends to the narrative structure: there is one declaration of each journey beat, in exactly one place in the journey { phase ⊃ moment ⊃ state } tree. No parallel enumeration — no journey.map alongside the journey, no group re-listing states already declared in the transition graph. Design-time views (arc diagrams, storyboards, visual journey maps) are projections computed from the single canonical tree; they are generated by tooling, never retyped. This is the P406 "one catalogue" guarantee applied to authoring: the catalogue of beats is the journey hierarchy itself, not a separate arc-authoring surface that must be kept in sync. Cross-reference: P401 (single-declaration discipline), R134 (Single Journey Enumeration — governs the phase ⊃ moment ⊃ state hierarchy).

Governance and Evolution

P501 Immutable Released Versions

Technical framing

Once a spec version is released (e.g., openxp/1.0), it is frozen. No fields are added, removed, or changed. All evolution happens in the next version. The spec.hash in every XDL file header creates a tamper-evident link between the file and the spec version it was authored against.

Rationale

Mutable specs create a class of bugs where the same file parses differently depending on when you downloaded the spec. Immutable versions guarantee that a file that parses today will parse identically in ten years.

P502 Additive Within Major, Breaking at Major

Technical framing

Within a major version (1.x), changes are strictly additive: new touchpoint types, new actions, new keywords. No existing construct is removed or changed in meaning. Breaking changes — removal of types, changed semantics, restructured blocks — require a new major version (2.0).

Rationale

Additive evolution means that every valid 1.0 file is also a valid 1.x file. Designers can adopt new features at their own pace. Parsers can be forward-compatible within a major version. This is the same contract used by semantic versioning, HTTP, and every successful protocol.

P503 Self-Governing Evolution Loop

Public framing

OpenXP is designed to evolve openly, with AI proposals and human judgment working at different speeds. An AI agent can propose a new touchpoint subtype, a new guard function, a new vocabulary pack. The proposal flows through the fixtures that validate it, the CI that propagates it across the platform, and the human gate that approves breaking changes. The platform's own governance is itself an XDL experience — a journey of states and transitions the runtime executes. This is not a theoretical curiosity. It is the operational shape of how OpenXP gets better without losing the discipline that makes it trustworthy: AI speed paired with human approval, automated validation paired with manual review, continuous evolution paired with immutable releases.

Technical framing

The spec, fixtures, sync tooling, and CI drift checks form the foundation for a self-governing evolution loop: an AI agent proposes spec changes, fixtures validate them, CI propagates them, humans approve breaking changes. The loop is governed by XDL policies (Principle P403) and protected by immutable versioning (Principle P501).

Rationale

A language that evolves only through human committee meetings evolves slowly. A language that evolves only through AI proposals evolves dangerously. The self-governing loop combines AI speed with human judgment, automated validation with manual review, continuous evolution with immutable releases.

P504 Embedded Spec

Technical framing

Every XDL runtime embeds its spec version at compile time. The runtime does not download, fetch, or discover its spec at startup. This guarantees that the runtime's behaviour is fully determined by its build, not by external state.

Rationale

External spec resolution introduces network dependencies, version confusion, and a class of "works on my machine" bugs. Embedding the spec makes the runtime self-contained: if you have the binary and the XDL file, you have everything needed to execute the experience. No internet required. No configuration drift possible.

P505 XDL Scope Integrity

Technical framing

XDL's domain is experience execution. Its vocabulary — touchpoints, states, journeys, agents, policies, actions — forms a structural graph that the runtime traverses when executing an experience. Every construct in the XDL spec must participate in this graph: it must be reachable from, referenced by, or capable of affecting a touchpoint, state, or journey.

Authoring-time tools, creative thinking aids, design-phase annotations, and configuration formats that share no structural elements with the experience execution graph are not XDL constructs. Expressing them in XDL syntax, extending the spec with their keywords, or including them in .xdl files does not make them XDL — it makes the spec incoherent.

The litmus test is direct: Can this construct appear inside an experience { } block and be meaningfully referenced by or participate in a journey? If the answer is no, it must not extend the XDL spec.

This principle exists in productive tension with Principle P403 (Self-Describing). Self-description means that the platform's own evolution process can be expressed as an experience — with touchpoints, states, and journeys the runtime can execute. It does not mean that every tool the platform uses becomes XDL vocabulary. The self-describing property applies to processes that fit the execution model, not to every artefact in the platform's ecosystem.

Rationale

A spec that absorbs the vocabulary of every adjacent tool loses its identity. XDL's execution model guarantees — determinism, safety, policy enforcement, source mapping — derive from its bounded scope. When non-executable constructs enter the spec, those guarantees become undefined at their boundaries. A spec-compliant parser given an unknown block name must produce an error (R105). Allowing authoring tools to extend the spec either forces the runtime to silently ignore those blocks or forces every parser implementer to distinguish "real" runtime blocks from "merely" authoring-time blocks. That distinction has no place in a spec document.

Inheritance

P601 Container Inheritance for Declarations

Technical framing

Block-scoped declarations — realm, senses, processing, intent, and other context-defining properties — inherit from the enclosing block unless explicitly overridden. A state inside a journey inherits the journey's realm and processing mode; a transition inside a state inherits the state's realm. Exiting an inner block restores the outer block's declaration; a child's override does not leak upward.

Container inheritance is type-correct: each field's merge behaviour matches its semantic type. For fields whose semantic type is one-of-many enum — realm (physical / digital / augmented / virtual), processing.mode (transient / scoped / retained), intent — inheritance applies replace semantics: the innermost declaration wins and the outer value is not consulted further. For fields whose semantic type is many-coexisting envelope — senses (sight + sound + touch can all be present simultaneously) — inheritance applies additive merge: child fields union with parent fields in declaration order, without duplicates.

Per-field merge mode is declared in spec/xdl-spec-1.0.json inheritable: blocks (merge: replace | additive). Sense Suppression — removing a specific inherited sense within a scoped block (e.g. senses { !sight } for a "dark zone inside a sighted realm") — is deferred to v2.x; v1.0 supports additive merge only.

Rationale

Inheritance reduces repetition without hiding intent. A predominantly-physical experience declares realm: physical once at the experience level; only the scenes that step into augmented or virtual restate it. A reader scanning the file can rely on the rule mechanically — find the nearest enclosing declaration walking outward — without needing to track an accumulated state of merged values. The verifier resolves declarations the same way the human reader does, which keeps tooling and intuition aligned. Cross-reference: R209 (Container Inheritance Resolution).

Forward Compatibility Discipline

P701 Warn-but-Preserve for Forward Compatibility

Technical framing

XDL files outlive the runtimes that first author them. A retail brand publishing an experience pack today expects every venue to play it tomorrow — including venues running last year's runtime, and venues that will update next year. Warn-but-Preserve is the rule that makes this work: when an older runtime encounters something in a file it does not recognise, it tells the operator about it and keeps the unfamiliar content intact. It does not crash and refuse the file. It does not silently delete what it did not understand. The unknown content survives, flagged, until a runtime that recognises it picks up the file.

The formal contract: when a validator or parser meets a key it does not recognise on a metadata field, it MUST emit a diagnostic warning that names the key and the spec version known to the runtime, AND it MUST preserve the unknown key intact through any round-trip. The unknown key is not silently dropped, not promoted to an error, and not mutated. This applies to metadata surfaces — realm.compatibility and the capture { } / deliver { } / schema { } block bodies (R125, R126, R127), and any additive metadata block introduced under R802. It does not apply to structural surfaces — touchpoint categories, journey/state/transition block shapes, action names — which remain hard errors under R105 (reject unknown top-level blocks) and R702 (catalogue uniqueness).

A v1.0 runtime parsing this file warns: "unknown realm.compatibility metadata key bidirectional on edge physical ↔ augmented (runtime knows spec 1.0; key may be defined in a later minor)" — and round-trips the value through emit unchanged. A v1.2 runtime accepts the key without warning. No code path branches on spec version; the warn-and-preserve behaviour is uniform.

Rationale

Warn-but-Preserve trades a verbose log line for forward-compatibility insurance. The trade is heavily worth it: the verbose log is fixable by updating the runtime; the lost data is not. Putting the principle at the language level — not in deployment review, not in a separate compatibility layer — means every runtime, validator, and tool that parses XDL inherits the contract automatically. Forward compatibility is not a feature opt-in; it is the language's default posture.

Origin & narrative voice

I love this industry. The people are extraordinary. The ambition is often audacious. But there is a technical challenge at the heart of everything we do:

“We design for what people should feel, and then we build experiences with tools that only speak in what machines should do.”

Somewhere between the original creative vision and the technical delivery, the human intent often gets watered down, or lost. The deeper the experience, the higher the risk — more systems, more vendors, more integration, more points of failure, and more cost. Often invisible until you are on-site at 3am asking ”…whose responsibility is that?” — if the idea even made it that far to begin with.

The industry needs a common experience design language that starts with human perception, not hardware protocols.

Foundations that raise the floor, and the ceiling, so that everyone — from the kid in their bedroom to the team delivering something no one has ever built, in a place they have never been, to a deadline they did not set — is building on solid ground. A language that is open, accessible, and belongs to the industry, not locked into one vendor’s ecosystem.