@ue-shed/observatory 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 UE Shed contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,53 @@
1
+ # `@ue-shed/observatory`
2
+
3
+ Actor discovery, stable identity, bounded snapshots and deltas, retained spatial projection, and
4
+ focus operations. The first implemented slice powers Map Review's Live World Scout through validated
5
+ Remote Control calls and a local binary transform stream.
6
+
7
+ ```sh
8
+ npm install --save-exact @ue-shed/observatory @ue-shed/unreal-connection
9
+ ```
10
+
11
+ Install the matching `UEShedObservatory` plugin from the same release manifest. The package is
12
+ headless: a host owns its own IPC/UI adaptation and no Workbench or extension UI is required.
13
+
14
+ ## Live actor observation
15
+
16
+ `Observatory.observe(endpoint, options)` owns the full demand-driven observation lifecycle and
17
+ returns an Effect `Stream` of `WorldObservationState`:
18
+
19
+ ```ts
20
+ Observatory.observe(endpoint, { cadenceHz: 30 }).pipe(
21
+ Stream.runForEach((state) => Effect.sync(() => render(state)))
22
+ );
23
+ ```
24
+
25
+ It negotiates `StartActorObservation` over Remote Control, opens a scoped named-pipe server for the
26
+ returned pipe name, installs the actor catalog, and applies decoded USOT v1 transform batches into
27
+ `WorldObservationState` (`connecting` → `live` → `stale` → …). Resets and session changes reacquire a
28
+ fresh catalog automatically; sustained rejection or negotiation failure surfaces a typed
29
+ `ActorObservationSessionError` or `ActorObservationRecoveryExhaustedError` after a bounded number of
30
+ recovery attempts. `StopActorObservation` is always called when the stream's scope closes.
31
+ `Observatory.setObservationCadence(endpoint, cadenceHz)` retunes a running producer without closing
32
+ that stream's named-pipe session.
33
+
34
+ When the connected editor cannot stream (`not_supported`, e.g. non-Windows), `observe` falls back to
35
+ bounded `GetActorSnapshot` polling at ≤10 Hz and emits `polling_fallback` states instead of failing.
36
+
37
+ `snapshot` and `focus` remain for one-shot CLI and compatibility use.
38
+
39
+ The lower-level `ActorFeed` service (`actorFeedLayer`, `acquireActorFeedScoped`) owns just the
40
+ named-pipe transport and incremental USOT decoding, with a bounded sliding `PubSub` so a slow
41
+ subscriber only ever sees the newest packet rather than an unbounded backlog.
42
+
43
+ ## Performance evidence
44
+
45
+ ```powershell
46
+ pnpm benchmark:observatory # deterministic host decode/apply + Canvas paint
47
+ pnpm benchmark:observatory:live # running fixture editor in PIE; host + Workbench IPC/Canvas
48
+ ```
49
+
50
+ The live command defaults to `http://127.0.0.1:30001`; set `UE_SHED_REMOTE_CONTROL_ENDPOINT` to
51
+ override it. It validates `L_CameraLoad`, the three fixture class counts, and PIE before measuring
52
+ the Unreal producer, named-pipe host, and a real Electron Workbench World Scout presentation. The
53
+ Workbench phase must sustain at least 10 painted transform sequences per second.
@@ -0,0 +1,90 @@
1
+ import { type RemoteControlClientShape } from "@ue-shed/unreal-connection";
2
+ import { Context, Effect, Layer, Schema, type Scope, Stream } from "effect";
3
+ import { type ActorStreamPacket } from "./actor-stream-protocol.js";
4
+ import { type WorldObservationState } from "./world-observation.js";
5
+ export interface ActorFeedMetrics {
6
+ readonly bytesReceived: number;
7
+ readonly decodeLimitDrops: number;
8
+ readonly deliveryReplacements: number;
9
+ readonly malformedPackets: number;
10
+ readonly packetsReceived: number;
11
+ readonly startedMonotonicMs: number;
12
+ readonly transportErrors: number;
13
+ }
14
+ /** One accepted live packet as observed at the host boundary, for benchmarks and diagnostics. */
15
+ export interface ActorObservationDiagnostic {
16
+ readonly actorsChanged: number;
17
+ readonly actorsSampled: number;
18
+ readonly decodeApplyMs: number;
19
+ readonly missingSequences: number;
20
+ readonly producerReplacements: number;
21
+ readonly receiverReplacements: number;
22
+ readonly samplingDurationMicros: number;
23
+ readonly sequence: bigint;
24
+ }
25
+ declare const ActorFeedError_base: Schema.Class<ActorFeedError, Schema.TaggedStruct<"ActorFeedError", {
26
+ readonly message: Schema.String;
27
+ readonly operation: Schema.Literals<readonly ["listen", "decode_limit"]>;
28
+ readonly pipeName: Schema.String;
29
+ readonly retrySafe: Schema.Boolean;
30
+ }>, import("effect/Cause").YieldableError>;
31
+ export declare class ActorFeedError extends ActorFeedError_base {
32
+ }
33
+ export interface ActorFeedShape {
34
+ readonly latestPacket: Effect.Effect<ActorStreamPacket | undefined>;
35
+ readonly metrics: Effect.Effect<ActorFeedMetrics>;
36
+ readonly packets: Stream.Stream<ActorStreamPacket>;
37
+ }
38
+ declare const ActorFeed_base: Context.ServiceClass<ActorFeed, "@ue-shed/observatory/ActorFeed", ActorFeedShape>;
39
+ export declare class ActorFeed extends ActorFeed_base {
40
+ }
41
+ export interface ActorFeedOptions {
42
+ readonly capacity?: number;
43
+ readonly maxMalformedPackets?: number;
44
+ readonly pipeName: string;
45
+ }
46
+ /** Scoped acquisition usable directly (bypassing `Context`) when the pipe name is dynamic. */
47
+ export declare function acquireActorFeedScoped(options: ActorFeedOptions): Effect.Effect<ActorFeedShape, ActorFeedError, Scope.Scope>;
48
+ export declare function actorFeedLayer(options: ActorFeedOptions): Layer.Layer<ActorFeed, ActorFeedError>;
49
+ export declare function makeActorFeedTestLayer(feed?: Partial<ActorFeedShape>): Layer.Layer<ActorFeed>;
50
+ declare const ActorObservationControlError_base: Schema.Class<ActorObservationControlError, Schema.TaggedStruct<"ActorObservationControlError", {
51
+ readonly endpoint: Schema.String;
52
+ readonly message: Schema.String;
53
+ readonly operation: Schema.Literals<readonly ["start", "stop", "status"]>;
54
+ readonly retrySafe: Schema.Boolean;
55
+ readonly status: Schema.optional<Schema.Number>;
56
+ }>, import("effect/Cause").YieldableError>;
57
+ export declare class ActorObservationControlError extends ActorObservationControlError_base {
58
+ }
59
+ declare const ActorObservationSessionError_base: Schema.Class<ActorObservationSessionError, Schema.TaggedStruct<"ActorObservationSessionError", {
60
+ readonly endpoint: Schema.String;
61
+ readonly expectedSessionId: Schema.String;
62
+ readonly message: Schema.String;
63
+ readonly receivedSessionId: Schema.String;
64
+ }>, import("effect/Cause").YieldableError>;
65
+ export declare class ActorObservationSessionError extends ActorObservationSessionError_base {
66
+ }
67
+ declare const ActorObservationRecoveryExhaustedError_base: Schema.Class<ActorObservationRecoveryExhaustedError, Schema.TaggedStruct<"ActorObservationRecoveryExhaustedError", {
68
+ readonly attempts: Schema.Int;
69
+ readonly endpoint: Schema.String;
70
+ readonly message: Schema.String;
71
+ }>, import("effect/Cause").YieldableError>;
72
+ export declare class ActorObservationRecoveryExhaustedError extends ActorObservationRecoveryExhaustedError_base {
73
+ }
74
+ export interface ObserveActorFeedOptions {
75
+ readonly cadenceHz: number;
76
+ readonly capacity?: number;
77
+ readonly maxConsecutiveRejectedBatches?: number;
78
+ readonly maxMalformedPackets?: number;
79
+ readonly maxRecoveryAttempts?: number;
80
+ readonly onDiagnostic?: (diagnostic: ActorObservationDiagnostic) => Effect.Effect<void>;
81
+ readonly pipeName?: string;
82
+ }
83
+ /**
84
+ * Own the full observation lifecycle: negotiate `StartActorObservation`, install/reacquire
85
+ * catalogs, decode and apply transform packets, recover from reset/session faults with a bounded
86
+ * attempt budget, and always call `StopActorObservation` when the returned stream's scope closes.
87
+ */
88
+ export declare function observeActorFeed(remote: RemoteControlClientShape, endpoint: string, options: ObserveActorFeedOptions): Stream.Stream<WorldObservationState, ActorObservationSessionError | ActorObservationRecoveryExhaustedError>;
89
+ export {};
90
+ //# sourceMappingURL=actor-feed.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"actor-feed.d.ts","sourceRoot":"","sources":["../src/actor-feed.ts"],"names":[],"mappings":"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"}