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

package/dist/spine/processors.d.ts

@@ -0,0 +1,242 @@
+import type { TopicId, TopicPayload } from "../index.js";
+import type { Reading } from "../reading.js";
+import type { TimelinePoint } from "../timeline.js";
+import type { TopicReading } from "./client-reading.js";
+/**
+ * A handle to a processor, as {@link UplinkClientHandle.registerProcessor} or
+ * {@link defineProcessorContract} returns it. Pass it to {@link useProcessor},
+ * or list it in a contribution's `deps`. Its type carries the processor's
+ * result type.
+ *
+ * @typeParam Result - What the processor computes.
+ * @typeParam ProcessorId - Its id.
+ * @typeParam Carried - Whether it returns a `Reading` (see {@link useProcessor}).
+ *
+ * @category Processors
+ */
+export interface ProcessorHandle<Result, ProcessorId extends string = string, Carried extends boolean = boolean> {
+    /** The processor's id, `"<uplink id>:<name>"`. A contribution depending on the handle receives its result under this key. */
+    readonly id: ProcessorId;
+    /** Type-only brand: never present at runtime, carries `Result` through inference. */
+    readonly __resultType?: Result;
+    /** Type-only, never present at runtime: whether the processor returns a `Reading`, which it does when a reading is among its dependencies. */
+    readonly __carriesCurrency?: Carried;
+}
+/**
+ * Whether a dep list makes its processor's result datable.
+ *
+ * Wrapped in a tuple so a union of deps does not distribute: the question is
+ * about the list as a whole, and a distributed `extends never` would decide it
+ * once per member.
+ */
+export type CarriesCurrency<Deps extends readonly Dep[]> = [
+    Extract<Deps[number], ReadingDep>
+] extends [never] ? false : true;
+/**
+ * A dep asking for a Topic's `Reading` rather than its bare payload.
+ *
+ * The wrapper exists because a Topic id is a plain string, so there is nothing
+ * to distinguish "give me the value" from "give me the value and its currency"
+ * without one. `{ reading: "vessel.resources" }` reads at the call site as the
+ * request it is.
+ *
+ * ## Why a processor needs this at all
+ *
+ * A processor resolved a Topic dep to `point.payload`: the VALUE channel alone,
+ * with no staleness, no `validAt` and no model. So a derivation that reasons
+ * ACROSS topics could not tell whether its inputs were current, and during a
+ * blackout it computed on last-contact values and its consumers presented the
+ * result as though it were now. `ShipSystems` does exactly that today: a
+ * time-to-empty derived from levels observed twenty minutes ago, rendered with
+ * nothing anywhere saying so. That is the failure this whole type exists to
+ * prevent, in the widget where it matters most.
+ *
+ * ## Why it composes
+ *
+ * `evaluate` skips a processor whose `lastFrameGeneration` matches the frame,
+ * so it is memoised WITHIN a frame and re-evaluated ACROSS frames.
+ * `sampleReading` re-derives a reading carrying a model whenever the frame's
+ * view time moves. Both are keyed on the same thing, the frame, so a processor
+ * sees a reading built for the moment it is deriving for without any new
+ * invalidation machinery.
+ *
+ * ## What a processor should NOT do with it
+ *
+ * Return it. A `Reading` is one Topic's currency; a cross-resource conclusion
+ * ("four hours of oxygen, but not if the batteries go first") is not one
+ * Topic's anything. A processor whose output is modelled carries its own
+ * provenance instead, the way a projection channel's payload does with
+ * `observed` / `projected` / `lower` / `upper` / `elapsed`.
+ */
+export interface ReadingDep<Topic extends TopicId = TopicId> {
+    readonly reading: Topic;
+}
+/**
+ * A dep whose topic is only known once the FIXED deps have resolved: "the orbit
+ * of whichever vessel this route names", not a topic id anyone can write down.
+ *
+ * ## Why a fixed list cannot express it
+ *
+ * `comms.delay`'s model refuses a relayed route outright, and its own decline
+ * says why: the route home starts at a relay, and where that relay is now sits
+ * on `fleet.<guid>.orbit`, whose guid arrives IN the route. The model has the
+ * guid in hand at reckon time; what it has no way to say is "subscribe that".
+ * Every other dep variety names its topic at declaration time, which is exactly
+ * the thing a subject cannot do.
+ *
+ * ## The payload type is stated, not looked up
+ *
+ * `Payload` is the payload the resolved topic carries, and the author gives it,
+ * the same way `useStream<WireOf<VesselOrbitPayload>>(`fleet.${guid}.orbit`)`
+ * already does at every other dynamic read in the tree. A dynamic topic has no
+ * member in `TopicPayloadMap` to infer from: the ids are computed at runtime,
+ * which is the same reason `dynamicWholeTopicPrefixes` exists rather than a
+ * generated list.
+ *
+ * ## An undeclared subject declines, it does not guess
+ *
+ * `subject` returning `undefined` resolves the dep to `undefined`, which the
+ * store already turns into the `input-absent` decline every other unmet dep
+ * gets. A model that cannot name its subject has not got its input, and saying
+ * so is the same result as an absent channel rather than a new one.
+ */
+export interface SubjectDep<Payload = unknown, Fixed extends readonly unknown[] = readonly unknown[]> {
+    /** The topic to read, given the subject id: `` (id) => `fleet.${id}.orbit` ``. */
+    forSubject(subjectId: string): string;
+    /**
+     * Which subject this reckon is about, read from the point and the fixed deps
+     * resolved beside it. `undefined` means this reckon has no subject, which is
+     * not the same as a missing input: the dep resolves to `undefined` and the
+     * model decides.
+     *
+     * `Fixed` is the prefix of the model's own deps this selector reads, declared
+     * so it destructures typed. Without it `resolved` is `readonly unknown[]` and
+     * every selector opens with an assertion out of `unknown`, which is the thing
+     * `unknown-cast` exists to stop. Declared as a METHOD rather than a property
+     * so the bivariance lets a selector over a narrow tuple still satisfy the
+     * `SubjectDep<unknown>` the `Dep` union carries.
+     */
+    subject(point: TimelinePoint<unknown>, resolved: Fixed): string | undefined;
+    /** Phantom: the payload the resolved topic carries. Never read at runtime. */
+    readonly __payloadType?: Payload;
+}
+/**
+ * A processor dependency: a raw Topic id, a Topic's reading, another
+ * processor's handle, or a per-subject topic resolved at reckon time.
+ *
+ * The last is a RECKONER's to declare. It is in this union rather than in a
+ * second one because a reckoner's inputs are the same kind of thing a
+ * processor's are, and the alternative is two vocabularies to keep in step (see
+ * `ResolvedReckonerDep`, which says the same about resolution). A processor
+ * handed one is refused out loud by the evaluator: a processor has no point to
+ * take a subject from, and resolving it to `undefined` there would be
+ * indistinguishable from an absent input.
+ */
+export type Dep = TopicId | ReadingDep | ProcessorHandle<unknown> | SubjectDep<unknown>;
+/** Whether this dep's topic is computed per subject rather than declared. */
+export declare function isSubjectDep(dep: Dep): dep is SubjectDep<unknown>;
+/**
+ * The resolved value for one dependency: a nested processor resolves to its
+ * result type R; a reading dep resolves to the Topic's `Reading`; a Topic id
+ * resolves to its payload (or undefined when that Topic has produced no frame
+ * yet).
+ */
+type ResolvedDep<Dependency extends Dep> = Dependency extends ProcessorHandle<infer Result, string, true> ? Reading<Result> : Dependency extends ProcessorHandle<infer Result> ? Result : Dependency extends ReadingDep<infer Topic> ? TopicReading<TopicPayload<Topic>> : Dependency extends TopicId ? TopicPayload<Dependency> | undefined : never;
+/** Positionally-mapped tuple of resolved dependency values, in deps order. */
+export type ResolvedDeps<Deps extends readonly Dep[]> = {
+    [Index in keyof Deps]: Deps[Index] extends Dep ? ResolvedDep<Deps[Index]> : never;
+};
+/**
+ * What a `compute` is told about the frame it is running for, beyond its deps.
+ *
+ * Only the frame's view time, and deliberately only that: a processor that
+ * needs to know WHEN it is deriving for is common (anything turning an instant
+ * on the wire into a remaining duration), and a processor that reaches for a
+ * wall clock instead is the bug `readingAge` and the wall-clock ratchet exist
+ * to stop. Handing it the frame's own frozen view time means there is nothing to
+ * reach for.
+ */
+export interface ProcessorFrame {
+    /** The frame's frozen view time. Every read in this frame shares it. */
+    viewUt: number;
+}
+export interface ProcessorDefinition<Deps extends readonly Dep[] = readonly Dep[], Result = unknown> {
+    id: string;
+    owner: string;
+    deps: Deps;
+    compute: (values: ResolvedDeps<Deps>, frame: ProcessorFrame) => Result;
+}
+export type AnyProcessorDefinition = ProcessorDefinition<readonly Dep[], unknown>;
+/**
+ * Declare a Processor. Registers under the owner-stamped id `${owner}:${id}`
+ * (same owner-stamp convention as registerContribution) and returns an opaque
+ * handle other processors and contributions depend on. Re-registering the
+ * exact same definition (same compute reference) is a no-op so a module can be
+ * imported twice; a DIFFERENT definition under an already-used id throws.
+ */
+export declare function defineProcessor<const Deps extends readonly Dep[], Result, const ProcessorId extends string>(def: {
+    id: ProcessorId;
+    owner: string;
+    deps: Deps;
+    compute: (values: ResolvedDeps<Deps>, frame: ProcessorFrame) => Result;
+}): ProcessorHandle<Result, `${string}:${ProcessorId}`, CarriesCurrency<Deps>>;
+/**
+ * Returns a handle to a processor that another Uplink implements, so any
+ * Uplink can read it with {@link useProcessor} without depending on the one
+ * that implements it. Export the handle and its result type from a module
+ * both Uplinks import: a small shared package of your own for two of your
+ * Uplinks, as the SDK does for the ones it ships. The implementing Uplink
+ * registers a processor under the same id and types its `compute` with the
+ * same result type.
+ *
+ * When nothing registers the processor, as when its mod is not installed,
+ * `useProcessor` returns `undefined`.
+ *
+ * Throws when `id` is not `"<uplink id>:<name>"`, the implementing Uplink's
+ * id and then the processor's own name.
+ *
+ * @example One Uplink implements a processor, and any other reads it
+ * ```ts
+ * import {
+ *   defineProcessorContract,
+ *   defineUplinkClient,
+ *   useProcessor,
+ * } from "@ksp-gonogo/sitrep-sdk";
+ *
+ * // In a module both Uplinks import: the result's type and the contract.
+ * interface HabSummary {
+ *   crewDays: number;
+ * }
+ * const HAB_SUMMARY = defineProcessorContract<HabSummary>("habitat:summary");
+ *
+ * // In the Uplink "habitat", which implements it. Its handle puts
+ * // "habitat:" in front of the name, so the id is "habitat:summary".
+ * const HABITAT = defineUplinkClient({
+ *   id: "habitat",
+ *   version: "1.0.0",
+ *   name: "Habitat",
+ *   description: "Life support for a crewed vessel.",
+ * });
+ * HABITAT.registerProcessor({
+ *   id: "summary",
+ *   deps: [],
+ *   compute: (): HabSummary => ({ crewDays: 12 }),
+ * });
+ *
+ * // In any other Uplink's component. A contract does not say whether the
+ * // processor's inputs were readings, so the result is typed as the bare
+ * // HabSummary or a Reading of one, and is undefined while nothing implements it.
+ * function useHabSummary() {
+ *   return useProcessor(HAB_SUMMARY);
+ * }
+ * ```
+ *
+ * @category Processors
+ */
+export declare function defineProcessorContract<Result, const ProcessorId extends string = string>(id: ProcessorId): ProcessorHandle<Result, ProcessorId>;
+export declare function getProcessor(id: string): AnyProcessorDefinition | undefined;
+export declare function getAllProcessors(): AnyProcessorDefinition[];
+/** Test-only: reset the processor registry to empty. */
+export declare function clearProcessors(): void;
+export {};
+//# sourceMappingURL=processors.d.ts.map

package/dist/spine/processors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processors.d.ts","sourceRoot":"","sources":["../../src/spine/processors.ts"],"names":[],"mappings":"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"}

package/dist/spine/processors.js

@@ -0,0 +1,109 @@
+/** Whether this dep's topic is computed per subject rather than declared. */
+export function isSubjectDep(dep) {
+    return typeof dep === "object" && dep !== null && "forSubject" in dep;
+}
+const processors = new Map();
+/**
+ * Declare a Processor. Registers under the owner-stamped id `${owner}:${id}`
+ * (same owner-stamp convention as registerContribution) and returns an opaque
+ * handle other processors and contributions depend on. Re-registering the
+ * exact same definition (same compute reference) is a no-op so a module can be
+ * imported twice; a DIFFERENT definition under an already-used id throws.
+ */
+export function defineProcessor(def) {
+    /* Typed rather than inferred: a template expression widens to `string`, and
+       the stamped id is what a contribution keys this processor's result by, so
+       the shape has to survive as far as the handle. */
+    const stampedId = `${def.owner}:${def.id}`;
+    const existing = processors.get(stampedId);
+    const stamped = {
+        id: stampedId,
+        owner: def.owner,
+        deps: def.deps,
+        compute: def.compute,
+    };
+    if (existing !== undefined) {
+        if (existing.compute === stamped.compute)
+            return { id: stampedId };
+        throw new Error(`Processor id "${stampedId}" is already registered; a different ` +
+            `definition cannot re-use it. Processor ids must be unique within ` +
+            `their owner.`);
+    }
+    processors.set(stampedId, stamped);
+    return { id: stampedId };
+}
+/**
+ * Returns a handle to a processor that another Uplink implements, so any
+ * Uplink can read it with {@link useProcessor} without depending on the one
+ * that implements it. Export the handle and its result type from a module
+ * both Uplinks import: a small shared package of your own for two of your
+ * Uplinks, as the SDK does for the ones it ships. The implementing Uplink
+ * registers a processor under the same id and types its `compute` with the
+ * same result type.
+ *
+ * When nothing registers the processor, as when its mod is not installed,
+ * `useProcessor` returns `undefined`.
+ *
+ * Throws when `id` is not `"<uplink id>:<name>"`, the implementing Uplink's
+ * id and then the processor's own name.
+ *
+ * @example One Uplink implements a processor, and any other reads it
+ * ```ts
+ * import {
+ *   defineProcessorContract,
+ *   defineUplinkClient,
+ *   useProcessor,
+ * } from "@ksp-gonogo/sitrep-sdk";
+ *
+ * // In a module both Uplinks import: the result's type and the contract.
+ * interface HabSummary {
+ *   crewDays: number;
+ * }
+ * const HAB_SUMMARY = defineProcessorContract<HabSummary>("habitat:summary");
+ *
+ * // In the Uplink "habitat", which implements it. Its handle puts
+ * // "habitat:" in front of the name, so the id is "habitat:summary".
+ * const HABITAT = defineUplinkClient({
+ *   id: "habitat",
+ *   version: "1.0.0",
+ *   name: "Habitat",
+ *   description: "Life support for a crewed vessel.",
+ * });
+ * HABITAT.registerProcessor({
+ *   id: "summary",
+ *   deps: [],
+ *   compute: (): HabSummary => ({ crewDays: 12 }),
+ * });
+ *
+ * // In any other Uplink's component. A contract does not say whether the
+ * // processor's inputs were readings, so the result is typed as the bare
+ * // HabSummary or a Reading of one, and is undefined while nothing implements it.
+ * function useHabSummary() {
+ *   return useProcessor(HAB_SUMMARY);
+ * }
+ * ```
+ *
+ * @category Processors
+ */
+export function defineProcessorContract(id) {
+    // A contract names an id `registerProcessor` will STAMP, so it has to be
+    // written owner-first. Checked here because the alternative is a handle that
+    // silently answers `undefined` forever, which is indistinguishable from the
+    // mod not being installed: the one case this is supposed to make legible.
+    if (id.split(":").length !== 2 || id.startsWith(":") || id.endsWith(":")) {
+        throw new Error(`Processor contract id "${id}" must be owner-stamped as "<owner>:<id>", ` +
+            `matching what registerProcessor stamps for the Uplink that implements it.`);
+    }
+    return { id };
+}
+export function getProcessor(id) {
+    return processors.get(id);
+}
+export function getAllProcessors() {
+    return Array.from(processors.values());
+}
+/** Test-only: reset the processor registry to empty. */
+export function clearProcessors() {
+    processors.clear();
+}
+//# sourceMappingURL=processors.js.map

package/dist/spine/processors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processors.js","sourceRoot":"","sources":["../../src/spine/processors.ts"],"names":[],"mappings":"AAuKA,6EAA6E;AAC7E,MAAM,UAAU,YAAY,CAAC,GAAQ;IACnC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,YAAY,IAAI,GAAG,CAAC;AACxE,CAAC;AAwDD,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkC,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAI7B,GAKD;IACC;;wDAEoD;IACpD,MAAM,SAAS,GAA+B,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;IACvE,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC3C,MAAM,OAAO,GAA2B;QACtC,EAAE,EAAE,SAAS;QACb,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,OAAO,EAAE,GAAG,CAAC,OAGD;KACb,CAAC;IACF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,QAAQ,CAAC,OAAO,KAAK,OAAO,CAAC,OAAO;YAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CACb,iBAAiB,SAAS,uCAAuC;YAC/D,mEAAmE;YACnE,cAAc,CACjB,CAAC;IACJ,CAAC;IACD,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,MAAM,UAAU,uBAAuB,CAGrC,EAAe;IACf,yEAAyE;IACzE,6EAA6E;IAC7E,4EAA4E;IAC5E,0EAA0E;IAC1E,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACzE,MAAM,IAAI,KAAK,CACb,0BAA0B,EAAE,6CAA6C;YACvE,2EAA2E,CAC9E,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,OAAO,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,eAAe;IAC7B,UAAU,CAAC,KAAK,EAAE,CAAC;AACrB,CAAC"}

package/dist/spine/propagation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Orbit scalars read straight off streamed elements, for a caller that already
+ * holds them and wants a closed-form property of the ellipse.
+ *
+ * Nothing here propagates. Advancing elements to a future UT is
+ * `orbit-trajectory.ts`'s job, because that question cannot be answered from
+ * the elements alone: it needs the elected provider's `PropagationHorizon` for
+ * how far they may be extrapolated and for whether a conic is the right
+ * renderer at all. `orbitalPeriod` needs neither, being a property of the
+ * ellipse wherever the craft is on it.
+ */
+import type { OrbitElements } from "./kepler.js";
+/** Re-exported for this module's long-standing importers; declared in the unit system. */
+export { STANDARD_GRAVITY } from "../unit-system/definitions.js";
+/** Orbital period (seconds) of an ellipse: `2π·sqrt(sma³/mu)`. `null` for a non-bound (sma ≤ 0) or non-finite orbit. */
+export declare function orbitalPeriod(elements: OrbitElements): number | null;
+//# sourceMappingURL=propagation.d.ts.map

package/dist/spine/propagation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.d.ts","sourceRoot":"","sources":["../../src/spine/propagation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAI9C,0FAA0F;AAC1F,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAE9D,wHAAwH;AACxH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAIpE"}

package/dist/spine/propagation.js

@@ -0,0 +1,22 @@
+/**
+ * Orbit scalars read straight off streamed elements, for a caller that already
+ * holds them and wants a closed-form property of the ellipse.
+ *
+ * Nothing here propagates. Advancing elements to a future UT is
+ * `orbit-trajectory.ts`'s job, because that question cannot be answered from
+ * the elements alone: it needs the elected provider's `PropagationHorizon` for
+ * how far they may be extrapolated and for whether a conic is the right
+ * renderer at all. `orbitalPeriod` needs neither, being a property of the
+ * ellipse wherever the craft is on it.
+ */
+const TWO_PI = 2 * Math.PI;
+/** Re-exported for this module's long-standing importers; declared in the unit system. */
+export { STANDARD_GRAVITY } from "../unit-system/definitions.js";
+/** Orbital period (seconds) of an ellipse: `2π·sqrt(sma³/mu)`. `null` for a non-bound (sma ≤ 0) or non-finite orbit. */
+export function orbitalPeriod(elements) {
+    if (elements.sma <= 0 || !Number.isFinite(elements.sma))
+        return null;
+    const period = TWO_PI * Math.sqrt(elements.sma ** 3 / elements.mu);
+    return Number.isFinite(period) ? period : null;
+}
+//# sourceMappingURL=propagation.js.map

package/dist/spine/propagation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.js","sourceRoot":"","sources":["../../src/spine/propagation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;AAE3B,0FAA0F;AAC1F,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAE9D,wHAAwH;AACxH,MAAM,UAAU,aAAa,CAAC,QAAuB;IACnD,IAAI,QAAQ,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACrE,MAAM,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC;IACnE,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC"}

package/dist/spine/rail-registry.d.ts

@@ -0,0 +1,21 @@
+import type { UseCommandResult } from "./use-command.js";
+/** One command handle as the rail holds it, keyed by an id stable for the registering hook's life. */
+export type RailedCommand = Omit<UseCommandResult, "send" | "gateFor"> & {
+    id: string;
+};
+/**
+ * Where a widget's live command handles are collected for the panel's delay
+ * rail to draw: in flight, refused, lost, found and never sent. `useCommand`
+ * registers every handle it returns with the nearest one, so a command's
+ * outcome is shown without the widget wiring anything.
+ */
+export interface RailRegistry {
+    /** Add or replace a handle, keyed on its `id`. Returns its deregister function. */
+    register(entry: RailedCommand): () => void;
+    /** Update a registered handle in place; a no-op when nothing moved. */
+    update(id: string, next: Omit<RailedCommand, "id">): void;
+}
+/** The nearest rail, or `null` where none is mounted. */
+export declare const RailRegistryContext: import("react").Context<RailRegistry | null>;
+export declare function useRailRegistry(): RailRegistry | null;
+//# sourceMappingURL=rail-registry.d.ts.map

package/dist/spine/rail-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rail-registry.d.ts","sourceRoot":"","sources":["../../src/spine/rail-registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,sGAAsG;AACtG,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG;IACvE,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,IAAI,CAAC;IAC3C,uEAAuE;IACvE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3D;AAED,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,8CAA2C,CAAC;AAE5E,wBAAgB,eAAe,IAAI,YAAY,GAAG,IAAI,CAErD"}

package/dist/spine/rail-registry.js

@@ -0,0 +1,7 @@
+import { createContext, useContext } from "react";
+/** The nearest rail, or `null` where none is mounted. */
+export const RailRegistryContext = createContext(null);
+export function useRailRegistry() {
+    return useContext(RailRegistryContext);
+}
+//# sourceMappingURL=rail-registry.js.map

package/dist/spine/rail-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rail-registry.js","sourceRoot":"","sources":["../../src/spine/rail-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAqBlD,yDAAyD;AACzD,MAAM,CAAC,MAAM,mBAAmB,GAAG,aAAa,CAAsB,IAAI,CAAC,CAAC;AAE5E,MAAM,UAAU,eAAe;IAC7B,OAAO,UAAU,CAAC,mBAAmB,CAAC,CAAC;AACzC,CAAC"}

package/dist/spine/reckoners.d.ts

@@ -0,0 +1,133 @@
+import type { AnyReckonerDefinition, DepWindows, ReckonerDefinition, ReckonerInputRule } from "../reading.js";
+import type { TopicId, TopicPayload } from "../topics.js";
+import type { Dep } from "./processors.js";
+/**
+ * The owner core's own vanilla models register under. An Uplink cannot use it:
+ * `defineUplinkClient` stamps the client's own id, and `CORE_UPLINK_CLIENT` is
+ * the one handle carrying this one.
+ */
+export declare const CORE_RECKONER_OWNER = "core";
+/**
+ * Register `owner`'s forward model for `topic`.
+ *
+ * `owner` is a required argument rather than a convention because ownership has
+ * to be readable by something other than a person: the boundary ratchet and any
+ * health surface both want to know which Uplink is modelling what. An Uplink
+ * client should call its handle's bound `registerReckoner` instead of naming
+ * itself here.
+ *
+ * ## The topic is the typed union, so the payload type falls out of it
+ *
+ * `topic` was a bare `string`, and it cost twice. A name with a typo was not a
+ * compile error at all: it registered a model under a topic nothing would ever
+ * read, and the only symptom was a value that stayed unreckoned forever. And
+ * `T` could not be inferred from it, so every author annotated the payload by
+ * hand and the annotation was free to disagree with the topic it was registered
+ * against.
+ *
+ * Taking `TopicId` and resolving `TopicPayload<Topic>` fixes both at once,
+ * through the map `useTelemetry` and `Dep` already resolve through. `Deps` and
+ * `Projection` were already inferable and are simply left to infer: a definition that
+ * annotates neither is the shorter one AND the one that cannot drift.
+ *
+ * An Uplink-owned Topic reaches the union the same way it reaches
+ * `useTelemetry`: the Uplink's client augments `TopicPayloadMap` through
+ * `declare module "@ksp-gonogo/sitrep-sdk"`, and any program that statically
+ * imports that module can register a model for it.
+ */
+export declare function registerReckoner<const Topic extends TopicId, Projection = TopicPayload<Topic>, const Deps extends readonly Dep[] = readonly Dep[], const Windows extends DepWindows<Deps> = Record<never, never>>(topic: Topic, owner: string, reckoner: ReckonerDefinition<TopicPayload<Topic>, Projection, Deps, Windows>): void;
+/** One model's declared opt-out from one input rule, and who declared it. */
+export interface ReckonerExemption {
+    readonly topic: string;
+    readonly owner: string;
+    readonly rule: ReckonerInputRule;
+    readonly reason: string;
+    /** Present where the opt-out is narrowed to models produced on one basis. */
+    readonly basis?: string;
+    /** Present where it is narrowed to one declared input, which is the honest form. */
+    readonly input?: string;
+}
+/**
+ * Every input-rule opt-out any registered model declared, sorted by topic, then
+ * owner, then rule.
+ *
+ * The point of the rules is that a model gets them without writing anything, so
+ * the exceptions are the only part anyone has to read, and they have to be
+ * readable in ONE place rather than found by grepping twelve Uplinks. An
+ * Uplink's generated page lists its own off this, and the ledger suite pins the
+ * whole set so a new exemption arrives as a reviewed diff rather than as a line
+ * inside a model nobody re-reads.
+ *
+ * Sorted rather than in registration order for the same reason
+ * `getReckonedTopics` is: a generated page whose rows depend on module import
+ * order churns on every bundler change.
+ */
+export declare function getReckonerExemptions(): ReckonerExemption[];
+/** The elected model for a topic, and which owner it belongs to. */
+export interface ElectedReckoner {
+    readonly owner: string;
+    readonly definition: AnyReckonerDefinition;
+}
+/**
+ * The model to actually use for `topic`, and who owns it.
+ *
+ * ## The election, and why withholding everything stopped being right
+ *
+ * This used to answer `undefined` for a contested topic as well as an
+ * unmodelled one, on the reasoning that two Uplinks claiming one topic should
+ * be served by neither. That reasoning holds for the two Uplinks and stops
+ * holding once CORE ships a vanilla: withholding then serves nothing while a
+ * working model sits registered, which is a silent outage rather than a
+ * withheld opinion, and on a value the CONTRACT declares reckonable the type
+ * has already promised a model is on offer.
+ *
+ * So the ladder is: the sole non-core owner (an Uplink that owns the physics
+ * beats the vanilla), else core's own registration (which is what a contest
+ * falls back to, and what an uncontested core-only topic uses), else nothing.
+ * A contest that core cannot cover still answers with nothing, and
+ * `TimelineStore` turns that into `declined: { reason: "contested" }` rather
+ * than a silence.
+ *
+ * {@link getReckonerConflicts} is unchanged and still names every contested
+ * topic, because "these two Uplinks disagree" is worth telling an operator
+ * whether or not core covered for them.
+ */
+export declare function getReckoner(topic: string): ElectedReckoner | undefined;
+/** A topic two or more NON-CORE owners have both registered a model for. */
+export interface ReckonerConflict {
+    topic: string;
+    /**
+     * The competing owners, sorted, core included where it also registered. Every
+     * CONTENDER is withheld; core is not a contender and covers where it has a
+     * model. See {@link getReckoner}.
+     */
+    owners: string[];
+}
+/**
+ * Every contested topic in the registry, for a host that wants to tell the
+ * operator which Uplinks disagree. Mirrors `getReplacementConflicts`, and its
+ * emptiness is the normal case.
+ *
+ * Core is not counted as a party to the contest. Core ships a vanilla for every
+ * marked Topic, so counting it would make one Uplink electing itself over the
+ * vanilla read as a disagreement, which is the normal and intended case and the
+ * one {@link getReckoner} serves without hesitating. A contest is two owners who
+ * both think they own the physics.
+ */
+export declare function getReckonerConflicts(): ReckonerConflict[];
+/**
+ * Every topic anyone has registered a model for, with its owners.
+ *
+ * `getReckoner` answers with the model and `getReckonerConflicts` with the
+ * contested subset, and neither can tell you that one owner models six topics,
+ * which is what a docs surface enumerating an Uplink's contributions needs.
+ * Sorted by topic so a generated page's ordering does not depend on module
+ * import order.
+ */
+export declare function getReckonedTopics(): {
+    topic: string;
+    owners: string[];
+}[];
+/** Test-only: reset the registry to empty. */
+export declare function clearReckoners(): void;
+//# sourceMappingURL=reckoners.d.ts.map

package/dist/spine/reckoners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reckoners.d.ts","sourceRoot":"","sources":["../../src/spine/reckoners.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAwCxC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,SAAS,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,CAAC,KAAK,SAAS,OAAO,EAC3B,UAAU,GAAG,YAAY,CAAC,KAAK,CAAC,EAChC,KAAK,CAAC,IAAI,SAAS,SAAS,GAAG,EAAE,GAAG,SAAS,GAAG,EAAE,EAClD,KAAK,CAAC,OAAO,SAAS,UAAU,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAE7D,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,kBAAkB,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,CAAC,GAC3E,IAAI,CAiEN;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,IAAI,iBAAiB,EAAE,CAgC3D;AAED,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAYtE;AAED,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,IAAI,gBAAgB,EAAE,CAWzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,CAIzE;AAED,8CAA8C;AAC9C,wBAAgB,cAAc,IAAI,IAAI,CAErC"}