MCCF V6 Design Specification: Event Clusters and EBPS Traceability
Watch the MCCF demo
A short video of the Multi-Channel Coherence Field working in an X3D scene. Watch it on YouTube.
Event Clusters and EBPS Traceability
Associates semantically related events across modalities, preserves their causal relationships, and makes the evolution of EBPS state inspectable over narrative time, without adding a second source of truth.
| Status | Draft specification for review (revision 2) |
| Date | 30 October 2026 |
| Basis | Working proposal of 30 October 2026, revised against the V5 implementation and a reviewer's reading of Agent.observe() |
| Posture | Additive. V5 EBPS dynamics are unchanged and remain authoritative |
| Primary users | Authors, integrators, diagnosticians, researchers |
| Primary concern | Observability and provenance |
What this revision changes. The proposal is adopted in full with six amendments, each grounded in the V5 code: (1) the transition record is reconciled with what Agent.observe() actually changes (verified in code, and by an independent reading of the public main source); (2) Gardener interventions are traced; (3) three separate ordering concepts are defined: take time, a server sequence and a source sequence; (4) an event is a typed reference to existing identities, not a new stream; (5) the first clusters are seeded from structure V5 already has; (6) a non-interference acceptance test is added that seeds every random source. Appendix A lists what was verified against V5 and what remains to confirm.
1. Purpose and scope
The EBPS dashboard shows the present behaviour of the field. It does not keep a durable, inspectable history of how the field arrived there, how that change was expressed across modalities, and what followed. This specification adds an event-cluster and EBPS-trace capability around the existing event pipeline. A cluster groups semantically related occurrences. Transition records link field changes to what caused them. Timeline, dashboard overlay, replay and diagnostic views are projections of this trace.
Decisions this specification makes:
- Adopt event clusters as semantic associations over existing event identities.
- Record EBPS transitions with event references, sequence, input and changed fields, and cause.
- Represent modality as event metadata, not as a separate semantic universe.
- Build timeline and diagnostic views from the trace, not the other way round.
- Defer cross-modal inference and any coherence scoring until the trace model is validated.
Out of scope for this increment is listed in Section 16.
2. Terminology
| Term | Meaning in V6 | Distinction |
|---|---|---|
| Event | A uniquely identified occurrence: a dialogue line, a cue, an engine episode, a Gardener action. | Has its own identity, time, source and payload or reference. |
| Modality | The channel through which an event is observed or expressed: speech, face, gesture, action, narration, sound. | A property of an event instance, not the semantic occurrence. |
| Event cluster | A semantic association of events that take part in one narrative occurrence or causal episode. | An association, not a replacement for its members. |
| EBPS transition | A recorded change to the state the EBPS engine holds, linked to what caused it. | The live engine state stays authoritative. The record explains its evolution. |
| Provenance | The traceable source, sequence and cause of an event or transition. | Supports explanation. Never asserts more certainty than the recorded evidence. |
| Event cue (V5) | A timeline entry in the Events Editor (the Cue element of a scene). | Not the same as a trace event. A cue may be the source of one. The Guide glossary must say so. |
The term "observation modality" means the channel through which an event is sensed, represented or expressed. It does not make the dashboard a modality, and speech, facial and gesture events are not interchangeable records. They remain distinct events that may be associated with one occurrence.
3. Architecture
A traceability layer sits beside the existing event and EBPS path. It observes and records. It does not take ownership of any EBPS calculation.
Figure 1. Processing flow
Figure 1. The trace layer records references and transitions. The engine continues to compute field behaviour.
3.1 Logical model
Figure 2. A cluster associates event records and transition records. Views are projections over these records.
Membership is associative. An event may belong to more than one cluster, and a cluster may hold several events and transitions. The trace supports these relationships:
- memberOf: event to cluster.
- causedBy: transition to event, action or rule.
- expresses / observes: event to semantic occurrence or associated event, where known.
- respondsTo: event to preceding event, where the sequencing is known. V5 dialogue already carries this (see Section 4).
- affects: transition to agent or field scope.
4. Event identity (amendment 4)
V5 has no single event envelope. Different parts of the system identify things differently, so a "V6 event stream" would create exactly the parallel identities this specification forbids. Instead, an event is a typed reference to an identity that already exists, plus the trace metadata.
| Source in V5 | Identity today | Reference form | Change needed |
|---|---|---|---|
| Dialogue line | Line id (for example line_new_v5t92). Unique, checked by Schematron. | dialogue:<lineId> | None. Its trigger (declared:n or sensed:<lineId>) already gives a respondsTo link. |
| Timeline cue | triggerRef only (for example EC_cue_restored_1). No id attribute. | cue:<triggerRef> | Give each cue a stable id; keep triggerRef working. |
| Engine episode | None. A dict in the episode log with from, to, channels, outcome_delta, timestamp. | episode:<id> | Issue an id, a sequence number and an interaction id when the episode is logged. |
| Gardener action | Entry in the intervention log with action, agent, reason, timestamp. | gardener:<id> | Issue an id and sequence; route it into the trace as a transition. |
| Zone, waypoint, camera | Name or id in the scene file. | zone:<id> etc. | None for Phase 1. |
Rule: the trace never copies a payload. It stores the reference, modality, direction, agent and target, source, sequence and time. The payload stays where it already lives.
5. Timebase and ordering (amendment 3)
The EBPS engine runs on the server. Cues, gesture playback and X3D animation run in the browser. These are two clocks. The channel vector today carries a floating-point wall-clock time, and ordering is only the position in an in-memory list, which is lost on restart. A single server sequence is necessary but not sufficient. Three separate concepts are kept:
| Concept | Issued by | Purpose |
|---|---|---|
| takeTime | Shared playback timeline of the take (seconds from take start) | Aligns browser cues, gestures and audio with server-side interactions. It is the alignment mechanism. |
| sequence | Server, when a record is accepted into the take trace | One unambiguous, persisted append order. The canonical recording order. Not necessarily the order in which things happened in the browser. |
| sourceSequence | Each event producer, in particular the browser | Preserves the producer's own order when events arrive late, batched or out of order. Lets the trace detect missing or reordered browser events. |
The server also keeps receipt time for diagnostics. Wall-clock time is not used to synchronise across systems. Where clocks cannot be reconciled the trace says so (see Section 12, incomplete intervals) rather than inventing an order.
6. EBPS transition record (amendment 1)
The proposal sketched a transition as before and after values for the E and B channels. V5 does not work that way. E, B, P and S arrive as the input to Agent.observe(), called from CoherenceField.interact(). One call to observe() does the following (checked in the local V5 source and, independently, in the public main source):
| Step in observe() | What it does |
|---|---|
| 1. Pair record | Creates or retrieves the directed CoherenceRecord for the other agent. If the fidelity limit is reached, the new record is created inactive with a shortened history. |
| 2. Regulation | Applies the agent's affect regulation to the incoming E value, producing a regulated vector. B, P and S pass through. Regulation itself is not changed by observe(). |
| 3. History | Appends the regulated vector to the pair history, which also updates the record's credibility. |
| 4. MetaState | Recomputes coherence, surprise, learning progress, uncertainty, novelty, valence, intrinsic reward and mode. MetaState is an aggregate over all the agent's known relationships, so one observation can change the whole agent, not only the pair. |
| 5. Identity | Updates identity traits and the episode count. |
| 6. CCS | Updates coupling strength and appends to its history. |
| 7. Delta history | Appends the outcome delta to the rolling window, evicting the oldest entry when full. |
Two further facts shape the record. interact() builds a perturbed, mirrored vector for the second agent, so the two agents receive related but different inputs. And the pair coherence score is computed from the record history when asked for. It is derived, not independent stored state.
Record a transition for each observation the engine commits, and tie the two observations of one interaction together with an interaction id. Fields:
| Field | Content |
|---|---|
| transitionId, interaction | Unique id, and the id of the interaction that links both agents' observations. The originating event is referenced. |
| takeTime, sequence, sourceSequence | As in Section 5. |
| agent, counterpart | The direction of this observation. |
| input | The actual E, B, P, S vector this agent received, with outcome delta and dissonance flag. For the second agent this is the mirrored vector, not the originator's. |
| regulated | The vector actually appended to the pair history. |
| pairRecord | Creation, fidelity status, the history append, and the credibility change. |
| metaState | Before and after for each stored MetaState field. |
| identity | Trait deltas and episode count. |
| ccs | Previous and new coupling strength, and the history entry. |
| deltaHistory | The appended outcome delta and any rolling-window eviction. |
| provenance | Cause (interact, gardener, coupler, rule, operation), mechanism, and causeRef to the event or action. |
| engine version | Version and schema identifier sufficient to interpret the record, and the source commit it was built from. |
Stored versus derived. Pair coherence, echo risk, entanglement and alignment coherence are derived from recorded history and the engine version. They are not stored as independent state. Where a snapshot is useful for inspection, it is labelled a snapshot and is never authoritative.
6.1 The Gardener is a source of transitions (amendment 2)
The Gardener can adjust regulation, reweight channels, reset identity drift to the cultivar baseline, nudge a mode and set coupling strength. These change state outside interact() and are logged separately with a reason. If they are not traced, an author will see a character change with no event to explain it. Each intervention is recorded as a transition with cause gardener, its reason, and before and after for the fields it changed (regulation, channel weights, identity traits, mode conditions, CCS). A reset of identity drift is shown as such on the timeline.
Prefer recording only changed fields plus a reference to the prior state or checkpoint. Full snapshots may be taken at cluster boundaries and checkpoints. They are not copied into every event.
7. Constituent event metadata
Retain each existing event contract. Add or standardise, where not already present:
- modality: speech, facial, gesture, action, narration, audio, visual observation, or a declared extension value.
- direction: inputToEBPS, outputFromEBPS, bidirectional, notApplicable.
- agent and target: the originating and affected entities, where known.
- seq and t: as in Section 5.
- source: subsystem, authoring asset, sensor, dialogue engine, sequencer, external input.
- confidence / status: optional, always distinct from EBPS values.
8. Event clusters (amendment 5)
A cluster is a lightweight association: a stable id, an author-facing label, participants, member references, derived time bounds, and optional relationships. It never duplicates event payloads and never forces a single-cluster partition.
Seed clusters from structure V5 already has. A dialogue line, its generated audio, and the gesture and face cues that accompany it, chained by trigger (declared or sensed), already form a natural cluster. The first increment derives these automatically and read-only. Authoring and annotation of clusters wait for Phase 5. The reference test scene is Garden of the Goddess, which has two Anna lines connected by a sensed trigger.
9. Vocabulary, storage and validation
- Namespace. The trace has its own namespace and version, for example
http://mccf.artistinprocess.com/trace/v1, used as the default namespace of the trace document. The proposal's mccf: prefix does not match V5 practice. - Validation. A dedicated XSD and Schematron pair, built as the PI lesson schema was, validated with the existing validator and fixtures.
- Storage. One append-only trace file per take under
scenes/<scene>/arcs/<take>/, written in batches. A record sent again with the same id replaces its earlier line. Nothing blocks the tick on storage. - Header. MCCF version, schema version, engine and build identifiers, trace level, clock mapping, and any incomplete intervals.
9.1 Illustrative XML
Conceptual only. Element names, cardinalities and datatypes must be reconciled with the V5 schema before implementation. All numbers, ids and the engine identifier are illustrative.
<Trace xmlns="http://mccf.artistinprocess.com/trace/v1" schemaVersion="1.0"
scene="GardenOfTheGoddess_Scene01" take="take_003" level="summary"
engine="mccf-core" source="commit:TO-BE-FROZEN">
<Event id="ev-41" ref="dialogue:line_new_v5t92" modality="speech"
direction="inputToEBPS" agent="Anna" target="Jack" source="dialogEngine"
takeTime="12.30" sequence="41" sourceSequence="7"/>
<Transition id="tr-42" interaction="ix-17" agent="Jack" counterpart="Anna"
cause="interact" causeRef="ev-41"
takeTime="12.31" sequence="42">
<Input E="0.40" B="0.30" P="0.20" S="0.10"/>
<Regulated E="0.28" B="0.30" P="0.20" S="0.10"/>
<PairRecord credibilityBefore="0.80" credibilityAfter="0.78"/>
<MetaState field="mode" before="explore" after="repair"/>
<Ccs before="0.70" after="0.71"/>
</Transition>
<Transition id="tr-43" interaction="ix-17" agent="Anna" counterpart="Jack"
cause="interact" causeRef="ev-41"
takeTime="12.31" sequence="43">
<Input E="0.43" B="0.29" P="0.22" S="0.10"/> <!-- mirrored, perturbed -->
...
</Transition>
<Transition id="tr-45" agent="Jack" cause="gardener" causeRef="gardener:int-3"
takeTime="19.80" sequence="45">
<Intervention action="regulate" before="0.60" after="0.70"
reason="stagnation report"/>
</Transition>
<Cluster id="cl-1042" label="Jack learns of the pregnancy">
<Member eventRef="ev-41"/>
<Member transitionRef="tr-42"/>
<Member transitionRef="tr-43"/>
</Cluster>
</Trace>
10. Timeline and authoring experience
The principal user-facing deliverable is an event-cluster timeline that aligns events, modalities and EBPS transitions on one axis.
Figure 3. Illustrative cluster timeline. Events keep their own identities. Transitions are linked to the event or action that caused them. The Gardener appears as its own lane.
10.1 Capabilities
- Expand and collapse a cluster to inspect its events.
- Filter by agent, modality, source, EBPS field, or transition cause.
- Overlay EBPS fields and selected derived measures against the sequence.
- Select a transition to see input, before and after values, cause and linked events.
- Select an expressive event to see the recorded state at the time it was produced, where recorded.
- Replay a cluster in sequence, optionally synchronised with the dashboard.
- Compare intended, generated and received expression when the source data holds those distinctions.
10.2 Reaper analogy and a shared component
The authoring model is a multitrack audio workstation: the event stream is the performance, transitions are automation curves, modalities are tracks, and a cluster is a named passage. The analogy concerns aligned inspection and editing. It does not make EBPS audio, and it does not mean every transition is authorable. The lane view is also what the Route Editor needs to show timer imports and exports (register item IMPL-R36), so the lane component should be built once and shared.
11. Coherence: what to measure and what not to
V6 lets an author inspect relationships across modalities. It does not impose a rule that all modalities agree numerically. Concealment, restraint, irony and misreading are valid narrative choices. Anna may feel compassion, speak reassuringly, show sadness and use a restrained gesture, and Jack may read that gesture differently from her intention. The sequence can be coherent because of those differences.
The distinctions below are kept in metadata and links where V5 already has the concept. V5 has no data for the last three, so they are optional unknown fields and are not Phase 1 deliverables.
| Concept | Meaning | V5 data today |
|---|---|---|
| Field state | What the EBPS engine currently holds. | Yes (engine state, Librarian snapshots) |
| Expression | What the agent emits through speech, face, gesture or action. | Yes (dialogue lines, cues, gesture and expression clips) |
| Perception | What another agent or subsystem receives or infers. | No |
| Interpretation | The meaning a character, subsystem or author assigns. | No |
| Audience knowledge | What the narrative makes available to the observer. | No |
12. Runtime, persistence and replay
- Emit transition records at a defined commit boundary after the engine has calculated and accepted a change.
- Use stable ids plus deterministic sequence numbers so order survives equal timestamps.
- Support trace levels: off, summary, detailed. Verbose collection is never mandatory for normal playback.
- Buffer or batch persistence. Never block scene behaviour on slow storage. The trace never sits in the tick path as a synchronous write.
- Make loss visible. If records are dropped, mark the affected interval or cluster as incomplete rather than presenting a misleading complete history.
- Keep live state and trace history separate.
A trace supports visualisation and diagnostic replay. It does not guarantee deterministic reconstruction. Deterministic replay also needs all relevant inputs, timing decisions, random seeds (V5 scenes carry a seed attribute), engine versions, external dependencies and state checkpoints. Every replay is labelled with the fidelity it can actually provide: visual, diagnostic, or deterministic.
13. Versioning, compatibility and migration
- V5 event and EBPS behaviour works unchanged when tracing is off.
- The trace vocabulary is versioned in its own namespace.
- Existing ids are reused where stable. No parallel identities are created for the same event.
- Older events that lack modality, direction or provenance are marked unknown, not guessed.
- V5 scenes and assets load without clusters. Clusters are added incrementally.
- Exported traces carry the MCCF version, schema version and engine and build identifiers.
14. Validation and acceptance criteria (amendment 6)
| Area | Criterion |
|---|---|
| Identity | Every trace event and transition has a stable, resolvable id. Cluster membership does not duplicate payloads. |
| Causality | A transition names its cause, its causing event or action, its sequence and agent scope. |
| State fidelity | Recorded input, regulated vector and before and after values agree with the engine's committed state at the capture boundary. Each agent's own received vector is recorded. |
| Ordering | The timeline gives a stable order from sequence numbers even when timestamps are equal or coarse. |
| Modality | The same modality can be input or output depending on the event instance. |
| Multiplicity | A cluster can hold several modalities and events. An event can belong to several clusters. |
| Gardener | Every Gardener intervention in a take appears as a transition with its reason. |
| Performance | Trace collection does not materially disturb real-time sequencing. Levels and buffering are configurable. |
| Compatibility | V5 assets run unchanged with tracing off, and can be annotated incrementally. |
| Non-interference | Run the same scene with tracing off and then on, with every random source reset identically (the novelty term in compute_meta_state() uses random.uniform, and the mirrored vector in interact() uses random.gauss). The tracing path must not consume random values. Compare the full final state: MetaState, identity, CCS, pair histories and credibility, delta history, not just the visible coherence field. |
| Diagnostics | An unexpected transition can be navigated to its event, source and cluster. |
| Honesty | Incomplete intervals and replay limits are stated explicitly. |
15. Implementation sequence
| Phase | Work |
|---|---|
| 1. Vocabulary and contract | Give cues and engine episodes stable ids and server sequence numbers. Define the trace namespace, XSD and Schematron. Define the minimal event, transition and cluster contracts. Freeze the transition table against one source commit. Validate on fixtures. |
| 2. Runtime instrumentation | Optional capture at the commit boundary in interact() (both observations, one interaction id) and in each Gardener method. Link transitions to events. Trace levels. Incomplete-trace signalling. Write the per-take trace file. |
| 3. Inspection and timeline | |
| 4. Replay and diagnostics | Cluster replay where supported, dashboard synchronisation, trace export, regression fixtures including the non-interference test. |
| 5. Authoring assistance | Create and manage clusters, annotate relationships, compare expressions, inspect cross-modal coherence. Automated suggestions only after trace quality is established. |
Risks and mitigations
| Risk | Mitigation |
|---|---|
| Over-instrumentation raises runtime cost. | Trace levels, selective capture, batching, profiling. |
| The trace becomes a second source of truth. | Engine state is authoritative. Records are observations of committed transitions. The non-interference test enforces it. |
| False causal certainty. | Record explicit causes separately from inferred associations. Mark unknown or inferred links. |
| Ambiguous cluster boundaries. | Allow overlapping associations. Never force a single partition. |
| Brittle modality list. | Controlled values with namespace-qualified extensions. Preserve unknown values. |
| Coherence metrics flatten dramatic nuance. | Start with inspectable relationships and author annotations, not a scalar score. |
| Replay mistaken for determinism. | Declare replay fidelity and capture requirements. |
| Two clocks disagree. | Server sequence is authoritative. State the clock mapping. Mark unreconcilable intervals. |
16. Out of scope for the initial V6 increment
- Replacing or redesigning EBPS field equations, couplings or tick semantics.
- Requiring every event to belong to exactly one cluster.
- Treating any one modality as the canonical form of an event.
- Automatically inferring character intent, audience interpretation or emotional truth from expression.
- A universal cross-modal coherence score.
- Guaranteeing deterministic replay without complete capture of runtime dependencies.
- Changing V5 asset validity or requiring a server-side service for local scene operation.
Appendix A. Findings against the V5 implementation
The proposal listed seven questions to resolve against V5. Answers from the code, with what remains to confirm.
| Question | Finding |
|---|---|
| Authoritative event envelope and ID policy? | None. Dialogue lines have ids; cues have triggerRef only; engine episodes have no id. Schematron checks id uniqueness for dialogue lines only. Resolved by the typed-reference rule (Section 4). |
| Where is a transition committed? | CoherenceField.interact(): observe() on the first agent, a perturbed mirrored observe() on the second, then the episode is appended to the log. Gardener methods change state separately. observe() changes the pair record and credibility, MetaState, identity, CCS and the delta history (Section 6). |
| Are values timestamped or sequenced? | Timestamped with wall-clock floats. Not sequenced. Order is list position, lost on restart. Resolved by takeTime, sequence and sourceSequence (Section 5). |
| State, delta or derived? | Input: channel vector (raw, then regulated). Stored: pair history and credibility, MetaState, identity, CCS and history, delta history. Derived: pair coherence, echo risk, entanglement, alignment coherence. Resolved in Section 6. |
| Does the event model express source, target, cause, response? | Episodes: source and target (from, to), no cause. Dialogue: a response link through the trigger. Cues: triggerRef. Gardener: action, agent and reason. Cause must be added to episodes. |
| Which persistence options fit local-host? | Takes already live in scenes/<scene>/arcs/<take>/. A per-take append-only file fits. The PI performance log already uses the same pattern. |
| Which schemas own validation? | mccf.xsd and mccf_rules.sch exist for scenes. The trace gets its own pair and namespace. |
Still to confirm
- The exact source commit the transition table is frozen against (local tree versus public main).
- How browser-side cue and playback time is reported to the server per take, and how late or out-of-order batches are handled.
- The cost of adding ids to cues and episodes for existing scenes (migration).
- Whether credibility is updated inside add_episode() on every path (confirmed only from the call site, not its body).
Revision 2 incorporates an independent review of Agent.observe() against the public main source. Prepared as a design specification for review. XML fragments and diagrams are illustrative; final names and contracts are reconciled against the V5 schema and documentation during Phase 1.
Comments
Post a Comment