Sky-Parlour -- v1.3.5.2 Addendum¶

This addendum extends the base Sky-Parlour guided demo (src/fcc/demos/skyparlour_demo.py -- 6-step pipeline) with the v1.3.5.2 Phase-17 context-enricher integration. The scenario wires the FCC event bus directly into Sky-Parlour's context enricher and measures end-to-end event-to-visualization throughput.

This addendum intentionally stops at the context-enricher boundary. Autonomous event capture (the p1 layer) lives in a separate future Phase E integration and is deliberately kept out of scope here.

Scenario Overview¶

Sky-Parlour is an external visualization toolchain maintained at /mnt/d/VirtualDataRoom/Technology/Software/Ideate/sky-parlour_poc/sky-parlour. At the time of writing it is on Phase 17 (context enricher, commit 4b7c98e) with 218 registered workflows. The v1.3.5.2 scenario exercises the integration surface between FCC and the Phase-17 enricher without coupling to any future Sky-Parlour phase.

What This Scenario Does¶

Step	Activity	FCC Side	Sky-Parlour Side
1	Bridge setup	`VisualizationBridge.create()`	Enricher process running
2	Custom transformer register	`bridge.register("context_window", fn)`	n/a
3	Event pipeline	`EventBus` fires `workflow.step`	Enricher receives payload
4	D3 payload generation	Transformer returns `D3Payload`	Renderer consumes payload
5	Stream management	Filter on event type / source	Backpressure via transport
6	External consumer	Serialized payload dispatch	Visualization renders

What It Does Not Do¶

It does not depend on the autonomous event-capture layer (p1).
It does not require any Sky-Parlour code beyond Phase 17.
It does not imply a bidirectional coupling: Sky-Parlour is a pure consumer of FCC events in this scenario.

Wiring the Event Bus to the Enricher¶

Bridge Construction¶

The visualization bridge is a thin adapter that sits between the FCC EventBus and any external consumer. It is constructed with the default transformer set (force_graph, sankey, chord, heatmap) and then augmented with a Sky-Parlour specific transformer.

from fcc.demos.skyparlour_demo import create_skyparlour_demo
from fcc.visualization.bridge import VisualizationBridge
from fcc.messaging.bus import EventBus

bridge = VisualizationBridge.default()
bus = EventBus.default()

# Sky-Parlour Phase-17 enricher accepts a "context_window" payload.
def context_window_transformer(event):
    return {
        "type": "context_window",
        "persona_id": event.payload.get("persona_id"),
        "window": event.payload.get("window_ms", 2000),
        "measurements": event.payload.get("metrics", {}),
    }

bridge.register("context_window", context_window_transformer)

# Forward every event through the bridge to the enricher endpoint.
bus.subscribe_all(lambda ev: bridge.forward(ev, target="skyparlour"))

Enricher Endpoint Contract¶

The enricher accepts JSON payloads over a single WebSocket endpoint. The payload shape is simple and stable at Phase 17.

Field	Type	Required	Description
`type`	string	yes	Payload type understood by the enricher
`persona_id`	string	no	Originating persona, when known
`ts`	ISO-8601 string	yes	Event timestamp
`window`	integer (ms)	no	Context window hint for enricher
`measurements`	object	no	Arbitrary numeric metrics

Sky-Parlour validates the payload on arrival and drops malformed messages silently. The recommended pattern is to add a validation step in the transformer rather than relying on the remote validator.

Measuring Throughput¶

Instrumentation¶

The scenario measures two throughput figures:

Measurement	Metric Name	Unit
Event production rate on the FCC side	`events.published`	events/sec
Delivered-to-enricher rate	`viz.bridge.delivered`	payloads/sec

Both are standard FccMetrics counters and are read by the instrumentation harness at 500 ms cadence. End-to-end throughput is the viz.bridge.delivered rate measured at the Sky-Parlour side.

Reference Throughput Numbers¶

The reference bench was executed on the v1.3.5.2 developer machine (WSL2, 8 vCPU). Numbers are illustrative; repeat the measurement on your own hardware before making capacity decisions.

Event Rate	Mode	End-to-End Rate	p95 Latency	Notes
100/sec	Baseline	100/sec	3 ms	Headroom available
500/sec	Steady	500/sec	8 ms	Stable
1000/sec	Burst	985/sec	24 ms	Enricher slightly trails publisher
2500/sec	Stress	~2100/sec	62 ms	Enricher queue grows; apply filters

The stress row shows the value of the stream filters described in the 6-step skyparlour demo: dropping uninteresting event types at the bridge keeps the enricher's input queue bounded.

Latency Breakdown¶

Each payload traverses four hops. A healthy run distributes latency roughly evenly across the two serialization hops and the transport, with the transformer contributing almost nothing.

Hop	Typical Share of Latency
`EventBus.publish` to subscriber	~10%
Transformer execution	<5%
JSON serialization	~35%
Transport + enricher ingest	~50%

Integrating with the 6-Step Demo¶

The v1.3.5.2 scenario slots into the existing 6-step demo without changing the step interface. Each existing step is retained; the addendum only changes what the pipeline does with its output.

Base Step	v1.3.5.2 Augmentation
sp_01: VisualizationBridge Setup	Also configure the `context_window` transformer
sp_02: Custom Transformer	Use `context_window` as the example (replaces synthetic sample)
sp_03: Event-to-Viz Pipeline	Subscribe the bridge to the live bus (not a canned list)
sp_04: D3 Payload Generation	Emit payloads to the enricher endpoint
sp_05: Stream Management	Configure filters for enricher backpressure
sp_06: External Consumer	Verify payloads were received by Phase-17 enricher

Event-Type Inventory¶

The scenario focuses on three event types that carry the most useful information for a context-enricher:

Event Type	Source	Why It Matters for Enrichment
`workflow.step`	`action_engine`	Per-step context window, persona, and action
`simulation.turn.completed`	`simulation_engine`	Higher-level flow context
`collaboration.score.recorded`	`collaboration.scoring`	Human evaluation signal for enrichment

Additional event types can be added to the filter set by updating the stream_filter step in the base demo. Avoid forwarding low-value events like metrics.*; they flood the enricher without adding usable context.

Running the Scenario¶

Prerequisites¶

Sky-Parlour Phase 17 checkout at commit 4b7c98e (or later, provided the enricher payload contract has not changed).
FCC installed with [full] extras.
Sky-Parlour enricher process running and listening on its configured WebSocket port.

Launch¶

# Terminal 1 -- Sky-Parlour enricher (from Sky-Parlour checkout)
python -m skyparlour.phase17.enricher --port 9501

# Terminal 2 -- FCC bridge + harness
python -m fcc.demos.skyparlour_demo --target ws://localhost:9501/enrich

The harness walks through the 6 steps of the base demo, and the terminal output reports throughput and latency at each transition.

Verifying the Integration¶

Check	How
Enricher received payloads	Enricher logs report `received type=context_window`
Payload schema valid	Enricher does not log `validation.dropped`
No FCC backpressure	`events.dropped` counter remains at zero
Latency acceptable	`viz.bridge.delivered.latency_ms` p95 < 50 ms

Operational Considerations¶

Bounded Queues¶

The bridge maintains an internal outbound queue to the enricher. When the queue reaches its high-water mark, incoming events are either dropped (default) or routed to the DLQ (opt-in). For the Phase-17 scenario the recommendation is to drop silently: the enricher processes context windows statistically and a small amount of dropped traffic is acceptable.

Security Boundary¶

Sky-Parlour is an external process; the transport between FCC and Sky-Parlour crosses a trust boundary. Two hardening steps are recommended before running this scenario in a shared environment:

Terminate the WebSocket with TLS (even locally, via a self-signed certificate).
Add an authentication header that the enricher validates.

Neither is required for the local developer demo but both should be addressed before any multi-user deployment.

Decoupling from Future Phases¶

Later Sky-Parlour phases may add autonomous event capture (the p1 layer) and bidirectional state flow. The current scenario is designed to survive those additions unchanged: adding new payload types is additive, and the bridge's forward path never assumes a response. Keep the transformer registration and the filter set explicit; do not rely on implicit "send everything" behaviour.

Tips¶

Start with the default transformer set and only add a Phase-17 transformer once the baseline pipeline is flowing.
Run the harness with --verbose to see per-step timings; this is the fastest way to spot a slow transformer.
If you see persistent drops at low event rates, the enricher is the bottleneck -- profile it with its own tooling, not FCC's.
When capturing a reproducible benchmark run, pin both the FCC commit and the Sky-Parlour commit in the run metadata.