@ksp-gonogo/sitrep-sdk 0.0.1 → 0.2.0-rc.10

package/src/spine/use-data-sources.ts

@@ -0,0 +1,43 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { getDataSources } from "../api/registry";
+
+export interface DataSourceState {
+  id: string;
+  name: string;
+  status: import("../api/types").DataSourceStatus;
+}
+
+export function useDataSources(): DataSourceState[] {
+  // subscribe tells React which external events should trigger a re-check.
+  // getDataSources() is called inside the callback so it always sees the
+  // current set of registered sources without needing them as a dependency.
+  const subscribe = useCallback((onStoreChange: () => void) => {
+    const unsubscribers = getDataSources().map((s) =>
+      s.onStatusChange(onStoreChange),
+    );
+    return () =>
+      unsubscribers.forEach((u) => {
+        u();
+      });
+  }, []);
+
+  // getSnapshot returns a primitive so React can compare by equality.
+  const getSnapshot = useCallback(
+    () =>
+      getDataSources()
+        .map((s) => s.status)
+        .join(","),
+    [],
+  );
+
+  // useSyncExternalStore re-reads the snapshot on every onStoreChange call,
+  // and guarantees the update is processed synchronously, eliminating act() warnings
+  // caused by WebSocket/external events updating state outside React's scheduler.
+  useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+  return getDataSources().map((s) => ({
+    id: s.id,
+    name: s.name,
+    status: s.status,
+  }));
+}

package/src/spine/use-late-telemetry-subscribe.ts

@@ -0,0 +1,111 @@
+import { useCallback, useEffect, useRef } from "react";
+import type { TopicId, TopicPayload } from "../topics";
+import { useTelemetryClientOptional } from "./context";
+
+/** Ends one subscription started through `LateTelemetrySubscribe`. Safe to call more than once. */
+export type Unsubscribe = () => void;
+
+/**
+ * The imperative subscribe function `useLateTelemetrySubscribe` returns.
+ * Two overloads, mirroring `useTelemetry`'s canonical/fallback split:
+ *
+ * - a `TopicId` argument infers the payload type from `TopicPayloadMap`,
+ *   the same canonical typing `useTelemetry(topic)` gives a static topic.
+ * - a plain `string` argument (for a runtime-templated topic like
+ *   `scansat.mask.${body}.${scanType}`, which has no fixed member in the
+ *   `TopicId` union) falls back to an explicit `Payload` type argument at the
+ *   call site.
+ */
+export interface LateTelemetrySubscribe {
+  <Topic extends TopicId>(
+    topic: Topic,
+    onValue: (value: TopicPayload<Topic>) => void,
+  ): Unsubscribe;
+  <Payload = unknown>(
+    topic: string,
+    onValue: (value: Payload) => void,
+  ): Unsubscribe;
+}
+
+/**
+ * A narrow, lifecycle-managed escape hatch for subscribing to telemetry
+ * topics that are only known after some async setup resolves, in a count
+ * decided at runtime, rather than a fixed set a component can declare
+ * up front. `useTelemetry`/`useStream` are declarative: every call site
+ * names its topic(s) unconditionally on every render, which cannot express
+ * "subscribe to N topics once an async cache acquire settles for each one".
+ * This hook is the deliberately small seam for that case: it hands back one
+ * stable `subscribe` function instead of the whole `TelemetryClient`, so an
+ * author gets exactly "subscribe a callback to a topic, get an unsubscribe
+ * back" and nothing more.
+ *
+ * `subscribe` reads through the nearest `TelemetryProvider`'s
+ * `TelemetryClient` (`TelemetryClient.subscribe`), the same client
+ * `useTelemetry`'s canonical read and `useStreamEvent` use: sticky last
+ * value replayed synchronously on subscribe, every later arrival delivered
+ * as it lands, no delay gating or per-frame coalescing (a `TimelineStore`
+ * frame sample would introduce both, which is wrong for state that is not
+ * delayed craft telemetry).
+ *
+ * The returned function:
+ * - is stable across renders (safe to put in a `useCallback`/`useEffect`
+ *   dependency array, or to close over once and call later),
+ * - resolves the CURRENT client at CALL time, not the one seen at the
+ *   render that produced it, so it keeps working when called from inside
+ *   an async `.then()` well after this hook's own render,
+ * - can be called any number of times, including zero,
+ * - returns an idempotent `Unsubscribe`: calling it more than once, or
+ *   after this hook's owner has already unmounted, is a no-op.
+ *
+ * Every subscription still open when the calling component unmounts is
+ * torn down automatically (tracked in a ref, swept in one cleanup effect):
+ * a caller only needs to call the returned `Unsubscribe` early, for a
+ * subscription it wants to end before unmount, never on unmount itself.
+ *
+ * Degrades to a no-op subscribe (no throw, no-op returned `Unsubscribe`)
+ * when no `TelemetryProvider` is mounted at call time, matching every other
+ * `*Optional`-shaped hook in this package.
+ */
+export function useLateTelemetrySubscribe(): LateTelemetrySubscribe {
+  const client = useTelemetryClientOptional();
+  // Read fresh at call time (see the doc comment above): `subscribe` may be
+  // invoked long after the render that captured this hook's return value,
+  // by which point `client` here would be stale.
+  const clientRef = useRef(client);
+  clientRef.current = client;
+
+  // Every subscription still open, so unmount can sweep them all. A `Set` of
+  // the `Unsubscribe` closures themselves (not tokens/ids): each closure
+  // removes itself from this set on its own first call, so an early
+  // caller-initiated unsubscribe and the unmount sweep can never double-run
+  // the same teardown.
+  const openRef = useRef<Set<Unsubscribe>>(new Set());
+
+  const subscribe = useCallback(
+    (topic: string, onValue: (value: unknown) => void): Unsubscribe => {
+      const currentClient = clientRef.current;
+      if (!currentClient) return () => {};
+      const unsubscribeFromClient = currentClient.subscribe(topic, onValue);
+      let unsubscribed = false;
+      const unsubscribe: Unsubscribe = () => {
+        if (unsubscribed) return;
+        unsubscribed = true;
+        unsubscribeFromClient();
+        openRef.current.delete(unsubscribe);
+      };
+      openRef.current.add(unsubscribe);
+      return unsubscribe;
+    },
+    [],
+  ) as LateTelemetrySubscribe;
+
+  useEffect(() => {
+    const open = openRef.current;
+    return () => {
+      for (const unsubscribe of open) unsubscribe();
+      open.clear();
+    };
+  }, []);
+
+  return subscribe;
+}

package/src/spine/use-orbit-trajectory.ts

@@ -0,0 +1,50 @@
+import { useViewClockOptional } from "./context";
+import {
+  type OrbitTrajectory,
+  type OrbitTrajectoryInput,
+  orbitTrajectory,
+} from "./orbit-trajectory";
+
+/**
+ * How the craft's path may be drawn at the instant on screen, for a
+ * `vessel.orbit` value you have already read.
+ *
+ * Pass the whole payload, horizon included: the horizon says how far ahead the
+ * elements hold, and the answer will not reach past it. You decide which
+ * reading counts as the craft's orbit (observed only, or a modelled one too),
+ * and the hook does not subscribe to anything itself.
+ *
+ * The view instant is read when your widget renders, not on every frame, so the
+ * answer moves with your own telemetry.
+ *
+ * `null` means the question could not be put: no elements yet, or no clock. It
+ * is not a refusal, which arrives as a `withheld` answer carrying its reason, so
+ * do not render the two alike.
+ *
+ * `readFrame` asks for the curve in a frame of your choosing, which changes
+ * nothing in the game. Omit it for the frame it was computed in. Either way an
+ * arc carries its `frame`, which is what to name beside it.
+ *
+ * @category Frames of reference
+ */
+export function useOrbitTrajectory(
+  orbit: OrbitTrajectoryInput["orbit"] | undefined,
+  options?: Pick<OrbitTrajectoryInput, "samples" | "readFrame">,
+): OrbitTrajectory | null {
+  /*
+   * Read non-reactively: every input moves on the store frame anyway (the
+   * elements, the horizon, a scrub), so an onFrame subscription would add a
+   * 60 Hz re-render of a sampled path, and state updates outside act, for
+   * nothing.
+   */
+  const clock = useViewClockOptional();
+  const viewUt = clock?.viewUt();
+  if (orbit === undefined) return null;
+  if (viewUt === undefined || !Number.isFinite(viewUt)) return null;
+  return orbitTrajectory({
+    orbit,
+    viewUt,
+    samples: options?.samples,
+    readFrame: options?.readFrame,
+  });
+}

package/src/spine/use-processor.ts

@@ -0,0 +1,56 @@
+import { useCallback, useEffect, useSyncExternalStore } from "react";
+import type { Reading } from "../reading";
+import { useTelemetryStoreOptional } from "./context";
+import { processorRuntimeFor } from "./processorEvaluator";
+import type { ProcessorHandle } from "./processors";
+
+/** What a processor answers with: a datable reading, or the bare result. */
+export type ProcessorResult<
+  Result,
+  Carried extends boolean,
+> = Carried extends true ? Reading<Result> : Result;
+
+/**
+ * Reactively read a Processor's current, frame-memoised value: the augment-side
+ * consumption form, a hook wrapper around
+ * the same evaluator a Contribution's compute() pulls from directly via a
+ * ProcessorHandle dep (Task 3.5). Activates the processor for the life of the
+ * calling component (ref-counted, so N widgets reading the same processor
+ * share one evaluation) and deactivates on unmount.
+ *
+ * The value is there from the mount: the processor is evaluated against the
+ * nearest provider's store, at its current frame as it activates, then again
+ * on every frame boundary. Degrades to undefined with no TelemetryProvider
+ * mounted, matching every other useStream-family hook's disconnected contract.
+ *
+ * ## What comes back says how current it is, where the derivation can know
+ *
+ * A processor whose own deps include a reading answers a `Reading<Result>`: its
+ * inputs carried currency, so its answer is datable and says so. One depending
+ * only on raw topic ids answers the bare `Result` it always did, because there is
+ * nothing to date it by.
+ *
+ * Which of the two is decided by the dep list and read off the handle, so a
+ * processor that gains or loses a reading dep changes its consumers' TYPES
+ * rather than changing what they receive behind their backs.
+ */
+export function useProcessor<Result, Carried extends boolean>(
+  handle: ProcessorHandle<Result, string, Carried>,
+): ProcessorResult<Result, Carried> | undefined {
+  const store = useTelemetryStoreOptional();
+  const runtime = store ? processorRuntimeFor(store) : undefined;
+
+  useEffect(() => runtime?.activate(handle.id), [runtime, handle.id]);
+
+  const subscribe = useCallback(
+    (onChange: () => void) =>
+      runtime ? runtime.subscribe(handle.id, onChange) : () => {},
+    [runtime, handle.id],
+  );
+  const getSnapshot = useCallback(
+    () => runtime?.value<ProcessorResult<Result, Carried>>(handle.id),
+    [runtime, handle.id],
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot);
+}

package/src/spine/use-route-commands.ts

@@ -0,0 +1,57 @@
+import { useRef } from "react";
+import {
+  type CommsDelayLike,
+  currentMode,
+  type DelayMode,
+  deriveInFlight,
+  type InFlightCommand,
+  latchForward,
+  type PendingEntry,
+} from "../command-delay";
+import { useUtNow } from "./context";
+import { useLatestValue } from "./use-stream";
+
+/** Structural subset of the `PendingUplinkQueue` wire payload this hook reads. */
+export interface PendingUplinkQueueLike {
+  pending: PendingEntry[];
+}
+
+export interface UseRouteCommandsResult {
+  items: InFlightCommand[];
+  mode: DelayMode;
+}
+
+/**
+ * Cross-origin route reader: every currently-pending command addressed to
+ * `topic` (e.g. `kos/7`), regardless of which command centre dispatched it
+ * (`PendingUplink.vantage`): the one thing `useCommand`'s own-dispatch
+ * memory can't see. Queue-only, no memory of its own: an entry that ages
+ * out of `system.uplink.pending` simply stops appearing here (a caller that
+ * needs failure detection after age-out wants `useCommand`'s `inFlight`
+ * instead, for its OWN dispatches).
+ *
+ * Reads `system.uplink.pending` (real-time command-centre bookkeeping) and
+ * `comms.delay` (a Delayed readout, read off the wire rather than through the
+ * horizon it sizes) via `useLatestValue`, and
+ * `nowUt` via `useUtNow`: the same real-time clock reads the kOS terminal's
+ * original hand-rolled strip used, for the same reason (see `useLatestValue`'s
+ * own doc). `latchForward` guards the returned phases against a transient
+ * `nowUt` judder.
+ */
+export function useRouteCommands(topic: string): UseRouteCommandsResult {
+  const queue = useLatestValue<PendingUplinkQueueLike>("system.uplink.pending");
+  const commsDelay = useLatestValue<CommsDelayLike>("comms.delay");
+  const nowUt = useUtNow() ?? 0;
+  const latchMemory = useRef<Map<string, InFlightCommand>>(new Map());
+
+  const entries = (queue?.pending ?? []).filter(
+    (entry) => entry.topic === topic,
+  );
+  const items = latchForward(
+    deriveInFlight(entries, nowUt),
+    latchMemory.current,
+  );
+  const mode = currentMode(commsDelay);
+
+  return { items, mode };
+}

package/src/spine/use-selected-vantage.ts

@@ -0,0 +1,23 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { useTelemetryClientOptional } from "./context";
+
+/**
+ * The selected command-centre vantage (Plan 3), reactively: the component
+ * re-renders when `client.setVantage` changes it, so a widget can reflect
+ * "viewing from: <centre>" without owning the selection itself.
+ *
+ * `undefined` until the client chooses a centre, and when no
+ * `TelemetryProvider` is mounted. Until then the mod has put the connection at
+ * the home command, which only the mod can name: pair this with
+ * `useObservedVantage` to learn where that is.
+ */
+export function useSelectedVantage(): string | undefined {
+  const client = useTelemetryClientOptional();
+  const subscribe = useCallback(
+    (onChange: () => void) =>
+      client ? client.onSelectedVantageChange(onChange) : () => {},
+    [client],
+  );
+  const getSnapshot = useCallback(() => client?.selectedVantage, [client]);
+  return useSyncExternalStore(subscribe, getSnapshot);
+}

package/src/spine/use-stream-event.ts

@@ -0,0 +1,54 @@
+import { useEffect, useRef } from "react";
+import { useTelemetryClientOptional } from "./context";
+
+/**
+ * Fires `handler` for each discrete event delivered on `topic`, the
+ * consumption side of a `ReliableOrdered` channel (e.g. `crash.lastCrash`),
+ * where every frame the server publishes is delivered in order and none is
+ * coalesced away. Where `useStream` reads the sticky latest VALUE of a state
+ * topic and re-renders, this hook reacts to each ARRIVAL: the natural shape for
+ * a widget that must do something once per event (raise a crash alarm, push a
+ * notification, log a mission line) rather than render a current reading.
+ *
+ * Subscribes straight through the `TelemetryClient` rather than the
+ * `TimelineStore`/frame path `useStream` uses: the store coalesces ingests to
+ * one `beginFrame()` per animation frame, which would drop the second of two
+ * events landing in the same tick: exactly the coalescing the reliable lane
+ * exists to prevent. The client's per-topic fan-out delivers every
+ * `stream-data` frame individually, so a burst of events each fire the handler.
+ *
+ * The sticky last value the client replays synchronously on subscribe is NOT
+ * treated as an event: it is the already-seen latest, so a widget mounting
+ * after a crash does not re-raise the alarm for it (and remounts, StrictMode,
+ * a layout change; never re-fire). Only frames arriving after subscription
+ * count. A widget that instead wants to RENDER the last event should read it
+ * with `useStream(topic)`.
+ *
+ * `handler` may change identity every render without re-subscribing, the
+ * latest one is always called (held in a ref), so callers need not memoize it.
+ */
+export function useStreamEvent<Payload>(
+  topic: string,
+  handler: (payload: Payload) => void,
+): void {
+  // Degrade to a no-op when no `TelemetryProvider` is mounted (disconnected),
+  // same `*Optional` contract as `useStream`/`useTelemetry`.
+  const client = useTelemetryClientOptional();
+  const handlerRef = useRef(handler);
+  handlerRef.current = handler;
+
+  useEffect(() => {
+    if (!client) return;
+    // `client.subscribe` replays the sticky last value synchronously, inside
+    // this call: flag that window so the replay is skipped and only genuinely
+    // new deliveries (which arrive on a later tick, with `replayingSticky`
+    // already cleared) reach the handler.
+    let replayingSticky = true;
+    const unsubscribe = client.subscribe(topic, (payload) => {
+      if (replayingSticky) return;
+      handlerRef.current(payload as Payload);
+    });
+    replayingSticky = false;
+    return unsubscribe;
+  }, [client, topic]);
+}

package/src/spine/use-stream.ts

@@ -0,0 +1,137 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { type TopicReading, topicReading } from "../reading";
+import {
+  useTelemetryClientOptional,
+  useTelemetryStoreOptional,
+} from "./context";
+import { useClaimCapability } from "./lock-scope";
+import { subscribeTopicRead } from "./subscribe-read";
+
+/**
+ * Reactively reads `topic`, raw OR derived, as a {@link TopicReading}: the
+ * latest value AND how current it is, from the `TimelineStore` supplied
+ * (indirectly, via `TelemetryProvider`'s auto-built default) by the nearest
+ * `TelemetryProvider`.
+ *
+ * A reading rather than the bare payload because the payload outlives the
+ * data: the store keeps the last sample after a topic stops arriving, so a bare
+ * read goes on handing a widget a confident figure the link has stopped
+ * vouching for. The reading makes the caller branch first, exactly as
+ * `useTelemetry` does for a typed Topic: `observed` is current, `held` is the
+ * last real observation held (with its instant and grade), and `pending`,
+ * `unowned` and `absent` carry no value at all. A derived channel computes its
+ * own currency from its inputs, so its reading is as honest as a raw one.
+ *
+ * It goes through `store.sampleReading(topic, store.currentFrame())`, never
+ * `client.getValue(topic)`. `getValue` only ever sees raw `stream-data` frames
+ * whose `topic` matches literally, so it is permanently `undefined` for a
+ * derived topic like `system.state.bodyCount`: no server channel ever sends
+ * that literal topic string. The store resolves BOTH kinds transparently.
+ *
+ * `subscribe` does two things, both required for a DERIVED topic to ever
+ * actually receive data:
+ * - **Everything the read needs held up** (`subscribeTopicRead`): every RAW
+ *   input topic `topic` transitively depends on (itself, for an ordinary raw
+ *   topic) plus the deps its elected reckoner declared, ref-counted through
+ *   `client.subscribe`, redirected to the topics the server actually
+ *   understands instead of the derived topic name. That seam is shared with
+ *   every other read path in the tree; see its doc for why the reckoner half
+ *   belongs there.
+ * - **Frame-driven reactivity** (`store.subscribeFrame`): re-renders on every
+ *   frame the provider mints, not on a raw per-topic callback, since a derived
+ *   value can change from an ingest on any of several input topics.
+ *
+ * `sampleReading` keeps a reading's identity while its point, status and epoch
+ * are unchanged, so `useSyncExternalStore` bails out of re-rendering when
+ * nothing relevant to `topic` changed.
+ *
+ * `pending` with no provider mounted (disconnected, or the frame before
+ * `SitrepTelemetryProvider`'s client is built), so a stream widget renders an
+ * empty state instead of throwing.
+ */
+export function useStream<Payload>(topic: string): TopicReading<Payload> {
+  const client = useTelemetryClientOptional();
+  const store = useTelemetryStoreOptional();
+  useClaimCapability("topic", topic);
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      if (!client || !store) return () => {};
+      const releaseInputs = subscribeTopicRead(client, store, topic);
+      const unsubscribeFrame = store.subscribeFrame(onStoreChange);
+      return () => {
+        unsubscribeFrame();
+        releaseInputs();
+      };
+    },
+    [client, store, topic],
+  );
+
+  const getSnapshot = useCallback((): TopicReading<Payload> => {
+    if (!store) return NO_PROVIDER as TopicReading<Payload>;
+    return store.sampleReading<Payload>(topic, store.currentFrame());
+  }, [store, topic]);
+
+  return useSyncExternalStore(subscribe, getSnapshot);
+}
+
+/**
+ * One shared `pending` for the no-provider path: a fresh object per call would
+ * fail `useSyncExternalStore`'s reference comparison and loop.
+ */
+const NO_PROVIDER = topicReading<never>({
+  state: "pending",
+  reckoning: { status: "none" },
+});
+
+/**
+ * Reactively reads the latest RAW value for `topic` straight off
+ * `TelemetryClient`: `client.getValue(topic)`, kept live via
+ * `client.subscribe`: bypassing the delayed/certainty-gated `TimelineStore`
+ * frame `useStream` samples through.
+ *
+ * `useStream` is correct for delayed CRAFT telemetry: it deliberately shows
+ * only what the view clock's certainty horizon has reached, so a widget
+ * counting down against delayed data stays in step with that same delay.
+ * But some topics are command-centre REAL-time bookkeeping, not delayed
+ * craft telemetry: `system.uplink.pending` (dispatch timestamps stamped
+ * the instant a command leaves the ground station) and `system.uplink.gates`
+ * are the current examples. Sampling those through the delayed
+ * frame makes them appear (and clear) a whole one-way-delay late; this hook
+ * is the fix, it reads the client's sticky last value directly, the same
+ * "arrived on the wire, available now" semantics `client.subscribe` already
+ * gives a non-React caller.
+ *
+ * `comms.delay` and `comms.path` are read through here too, and no longer
+ * because they are real-time: both are Delayed channels now, so the wire has
+ * already held them for a light-time and this hook shows each one the moment it
+ * lands rather than any earlier. What it still buys them is independence from
+ * the certainty horizon, which matters because `comms.delay` is what sizes that
+ * horizon: reading it through the gated frame would ask the view clock for a
+ * value the view clock is waiting on.
+ *
+ * No derived-topic support (unlike `useStream`): `client.getValue` only
+ * ever sees raw `stream-data` frames whose `topic` matches literally, so
+ * this hook is for raw command-centre topics only, never a derived channel.
+ *
+ * Degrades to `undefined` with no `TelemetryProvider` mounted, or before
+ * anything has arrived for `topic`.
+ */
+export function useLatestValue<Payload>(topic: string): Payload | undefined {
+  const client = useTelemetryClientOptional();
+
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      if (!client) return () => {};
+      return client.subscribe(topic, onStoreChange);
+    },
+    [client, topic],
+  );
+
+  const getSnapshot = useCallback((): Payload | undefined => {
+    if (!client) return undefined;
+    return client.getValue(topic) as Payload | undefined;
+  }, [client, topic]);
+
+  return useSyncExternalStore(subscribe, getSnapshot);
+}

package/src/spine/use-telemetry.ts

@@ -0,0 +1,142 @@
+import { useCallback, useSyncExternalStore } from "react";
+import type {
+  ReckonableReading,
+  TopicReading,
+  UnmodelledReading,
+} from "../reading";
+import { topicReading } from "../reading";
+import type { ReckonableFields, ReckonableTopic } from "../reckonability";
+import type { TopicId, TopicPayload } from "../topics";
+import {
+  useTelemetryClientOptional,
+  useTelemetryStoreOptional,
+} from "./context";
+import { useClaimCapability } from "./lock-scope";
+import type { NeverReckonable } from "./never-reckonable";
+import { subscribeTopicRead } from "./subscribe-read";
+import { useTelemetrySubscriberLabel } from "./subscriber-identity";
+
+/**
+ * One shared `pending` for the no-provider path. A fresh object per
+ * call would fail `useSyncExternalStore`'s reference comparison and loop.
+ */
+const NO_PROVIDER = topicReading<never>({
+  state: "pending",
+  reckoning: { status: "none" },
+});
+
+/**
+ * Subscribe to a live value. The canonical telemetry read hook of the Uplink
+ * architecture, keyed by a typed `TopicId`: it reads that Topic straight off
+ * the mounted `TimelineStore` and answers with the Topic's `Reading`.
+ *
+ *   const orbit = useTelemetry("vessel.orbit");
+ *
+ * A read with no `TelemetryProvider` mounted answers `pending`. A Topic with no
+ * `TopicId` member (a per-subject dynamic namespace such as
+ * `vessel.partActions.<flightId>`) is read with `useStream` instead.
+ *
+ * ## Why the reading and not the payload
+ *
+ * `Reading`'s whole justification is that "reaching a value at all requires
+ * branching on how current it is". There is no way to reach a value without
+ * confronting its currency, because the only hook that hands one over makes
+ * you write the discriminant first.
+ *
+ * For a topic in `NEVER_RECKONABLE` the return narrows to `UnmodelledReading`,
+ * which drops every `reckoning: "available"` member, so a caller cannot write a
+ * branch for a case that can never occur. Reckonability is a SECOND
+ * discriminant rather than an arm of `state`, so nothing is dropped from
+ * `state` itself: `held` remains, and remains the judgement.
+ *
+ * ## The three-way narrowing, and why the marked arm is not simply `Reading`
+ *
+ * A topic the CONTRACT declares reckonable answers with `ReckonableReading`,
+ * whose `reckoned` is `Pick<payload, the declared fields>` rather than the whole
+ * payload. That is the point of declaring per value: `vessel.flight` carries an
+ * altitude a conic advances beside a `situation` the game switches, and reading
+ * the second off a modelled value is a mistake the projection makes impossible
+ * rather than merely documented.
+ *
+ * It is deliberately NOT assignable to `TopicReading<payload>`, so a call site that
+ * hands one to a helper typed for the whole payload stops compiling. The overlay
+ * is `{ ...reading.value, ...reading.reckoning.value }`, written where it happens
+ * because that spread IS the judgement.
+ *
+ * The three arms are exclusive by construction: a marked topic in
+ * `NEVER_RECKONABLE` is a contradiction, and `never-reckonable.test.ts` fails on
+ * it, so the order the conditional tests them in cannot be load-bearing.
+ *
+ * ## Why there are THREE arms and not the two the design asked for
+ *
+ * The design said two: `ReckonableReading` where a model exists, plain
+ * `Reading` with no `reckoned` member anywhere else. The middle arm is what
+ * survives of the second half, and it keeps the whole-payload `reckoned` for the
+ * population the CONTRACT cannot speak for.
+ *
+ * That is an UPLINK-registered model: `registerReckoner` is keyed by topic
+ * string, and an Uplink's own contract slice has no reckonability emission of its own yet (see
+ * `RtConfig.EmitReckonability`), so a model it registers on a wire topic has
+ * nowhere but this arm to land.
+ *
+ * The cost is honest and worth stating: 35 wire topics fall here today, each
+ * typed with a `reckoned` covering the WHOLE payload, and for each of them core
+ * registers nothing, so the arm is reachable only if someone registers a model.
+ * Narrowing them to `UnmodelledReading` would type away the Uplink seam, which
+ * is the one thing the middle arm is holding open.
+ *
+ * ## The compile break does NOT always happen, and this is the trap
+ *
+ * Passing this hook's result straight into something that wants the PAYLOAD is
+ * meant to be a type error, and usually is. It is not when the payload type has
+ * every field optional, which most generated Uplink payloads do: a `Reading` is
+ * then structurally assignable to it, so `<Widget weather={useTelemetry(...)} />`
+ * typechecks and hands the widget an object carrying none of its fields.
+ *
+ * That is not hypothetical. An Uplink's radiation-trend test drove a "live
+ * trend" off two samples that measured nothing, for exactly this reason, and
+ * passed for as long as the widget rendered absence as zero. Unwrap the
+ * discriminant, even where the compiler does not force you to.
+ */
+export function useTelemetry<Topic extends TopicId>(
+  topic: Topic,
+): Topic extends ReckonableTopic
+  ? ReckonableReading<
+      TopicPayload<Topic>,
+      ReckonableFields<Topic> & keyof TopicPayload<Topic>
+    >
+  : Topic extends NeverReckonable
+    ? UnmodelledReading<TopicPayload<Topic>>
+    : TopicReading<TopicPayload<Topic>>;
+
+export function useTelemetry(topic: TopicId): unknown {
+  const client = useTelemetryClientOptional();
+  const store = useTelemetryStoreOptional();
+  useClaimCapability("topic", topic);
+
+  // Diagnostics only: which widget this read belongs to, so a topic nothing publishes can be reported with the name of the thing that asked for it.
+  const subscriberLabel = useTelemetrySubscriberLabel();
+  const subscribeStream = useCallback(
+    (onStoreChange: () => void) => {
+      if (!client || !store) return () => {};
+      const releaseInputs = subscribeTopicRead(
+        client,
+        store,
+        topic,
+        subscriberLabel,
+      );
+      const unsubscribeFrame = store.subscribeFrame(onStoreChange);
+      return () => {
+        unsubscribeFrame();
+        releaseInputs();
+      };
+    },
+    [client, store, topic, subscriberLabel],
+  );
+  // `sampleReading` memoizes on the store's per-frame cache, and `useSyncExternalStore` compares snapshots by reference, so a fresh object per call would loop.
+  const getStreamSnapshot = useCallback(() => {
+    if (!client || !store) return NO_PROVIDER;
+    return store.sampleReading(topic, store.currentFrame());
+  }, [client, store, topic]);
+  return useSyncExternalStore(subscribeStream, getStreamSnapshot);
+}