@openmbee/opensysml 0.9.1

package/dist/core/values.d.ts

@@ -0,0 +1,271 @@
+import type { Bound, Value, Verdict } from "../generated/sysml_pb.js";
+import { FailureReason } from "../generated/sysml_pb.js";
+import { type FailureCause } from "./errors.js";
+/** A quantity's magnitude: an integer or a real, never both. */
+export type Magnitude = {
+    kind: "int";
+    value: bigint;
+} | {
+    kind: "real";
+    value: number;
+};
+/** One unit raised to an exponent, as the service factorises a derived unit. */
+export interface UnitFactor {
+    unitId: string;
+    exponent: number;
+}
+/** A unit as a scale factor over base-unit powers, when the service reports one. */
+export interface UnitFactorization {
+    scaleNum: number;
+    scaleDen: number;
+    factors: UnitFactor[];
+}
+/** A complex number in rectangular form: one value, never a sequence of two reals. */
+export interface ComplexValue {
+    real: number;
+    imaginary: number;
+}
+/** An enumeration literal, identified by the enumeration that declares it. */
+export interface EnumValue {
+    name: string;
+    literalId: string;
+    enumerationId: string;
+    /** The scalar the literal equals when its enumeration specializes a scalar type (`high = 3`). */
+    value?: SysMLValue;
+}
+/** A magnitude in a unit as written, with the unit's reduction when the service reports one. */
+export interface QuantityValue {
+    magnitude: Magnitude;
+    unit: string;
+    unitTerm?: UnitFactorization;
+}
+/**
+ * A measurement unit held as a value by itself, with no magnitude: `SI::m`, or
+ * `m / s` as an operation composed it. `unitTerm` is its reduction, which the
+ * service always sends and requires; `unitId` is the FQN of the one declaration
+ * it names (`SI::kilometre`), absent for a unit an operation composed.
+ */
+export interface MeasurementRefValue {
+    unit: string;
+    unitTerm: UnitFactorization;
+    unitId?: string;
+}
+/**
+ * A calc held as a value — a calc definition, or a calc usage with an input no
+ * read could supply — named by the FQN of its declaration, which is its identity.
+ * `selfId` is the object its feature names resolve against, for a calc usage
+ * read off a part (`holder.scale`); absent for a function closing over no object.
+ */
+export interface FunctionValue {
+    calcId: string;
+    selfId?: bigint;
+}
+/**
+ * An element of the model held as an instance of its reflective metaclass: what
+ * `x meta KerML::Feature`, or the last element of `x.metadata`, evaluates to.
+ * `elementId` is the FQN of the element reflected on, which is its identity;
+ * `metaclassId` is the FQN of the element's own metaclass
+ * (`SysML::Systems::PartUsage`), not the type it was cast to. The service always
+ * sends it; one sent to the service may leave it empty to have the model's used,
+ * but one naming a metaclass that is not the element's is refused. The
+ * metaobject's features (`declaredName`, `ownedFeature`, ...) are read in the
+ * model, not carried.
+ */
+export interface MetaobjectValue {
+    elementId: string;
+    metaclassId: string;
+}
+/**
+ * A multidimensional array: `dimensions` gives the extent of each dimension and
+ * `elements` the elements flattened row-major, the last dimension varying
+ * fastest. A rank-0 array holds one element; an element may itself be an array.
+ */
+export interface ArrayValue {
+    dimensions: bigint[];
+    elements: SysMLValue[];
+}
+/**
+ * A tensor quantity of any rank: `dimensions` gives the extent of each dimension
+ * and `components` one quantity per component, flattened row-major as an
+ * array's elements are. A tensor of rank one is not a `vectorQuantity`.
+ */
+export interface TensorQuantityValue {
+    dimensions: bigint[];
+    components: QuantityValue[];
+}
+/**
+ * A model-level result the model leaves open (an unbound feature, an unfixed count):
+ * `reason` says why, `countLower`/`countUpper` bound its count as `MultiplicityInfo` spells them.
+ */
+export interface UndeterminedValue {
+    reason: string;
+    countLower: string;
+    countUpper: string;
+}
+/**
+ * A value the service computed. `absent` is the case a service sent no value at
+ * all for, which is distinct from `unset` — a feature that exists and has none —
+ * and from `undetermined`, a model-level answer the model leaves open.
+ * A `vector` is one value of numeric components, never a sequence of numbers,
+ * and a `vectorQuantity` carries one quantity per component, each with its own unit.
+ * A `set` is a unique, unordered collection — a `Collections::Set`'s elements —
+ * distinct from a `sequence`, whose order is part of its value: the service
+ * sends its elements in canonical order, so equal sets arrive alike, and reads
+ * one sent in any order, refusing one that lists an element twice.
+ */
+export type SysMLValue = {
+    kind: "int";
+    value: bigint;
+} | {
+    kind: "real";
+    value: number;
+} | {
+    kind: "complex";
+    value: ComplexValue;
+} | {
+    kind: "boolean";
+    value: boolean;
+} | {
+    kind: "string";
+    value: string;
+} | {
+    kind: "instance";
+    id: bigint;
+} | {
+    kind: "sequence";
+    elements: SysMLValue[];
+} | ({
+    kind: "quantity";
+} & QuantityValue) | ({
+    kind: "measurementRef";
+} & MeasurementRefValue) | ({
+    kind: "function";
+} & FunctionValue) | {
+    kind: "enum";
+    value: EnumValue;
+} | ({
+    kind: "array";
+} & ArrayValue) | {
+    kind: "vector";
+    components: Magnitude[];
+} | {
+    kind: "vectorQuantity";
+    components: QuantityValue[];
+} | {
+    kind: "set";
+    elements: SysMLValue[];
+} | ({
+    kind: "tensorQuantity";
+} & TensorQuantityValue) | ({
+    kind: "metaobject";
+} & MetaobjectValue) | {
+    kind: "null";
+    reason: string;
+} | {
+    kind: "unset";
+} | ({
+    kind: "undetermined";
+} & UndeterminedValue) | {
+    kind: "infinity";
+} | {
+    kind: "absent";
+};
+/** What a verification answered about. Kept for the verification RPCs of a later version. */
+export interface VerdictSubject {
+    /** "constraint", "requirement" or "satisfy". */
+    kind: string;
+    /** FQN of the verified element; empty for an anonymous satisfy assertion. */
+    elementId: string;
+    /** The element as a reader names it. */
+    element: string;
+    /** The instance verified against, when there was one. */
+    instanceId?: bigint;
+    instanceTypeId?: string;
+}
+/** One limit an engine ran under, and whether the run stopped at it. */
+export interface VerdictBound {
+    /** The bound's name as the budget spells it: "runs", "depth", "steps", "solver". */
+    name: string;
+    limit: bigint;
+    /** True when the run stopped at the limit, which lowers the verdict's strength. */
+    reached: boolean;
+}
+/**
+ * What a verdict rests on: the engine that answered, the strength of its
+ * evidence and the bounds it ran under. Empty from a service without the
+ * `engines` capability, or for a verdict decided before any engine was asked.
+ */
+export interface VerdictStanding {
+    /** The engine as `ListEngines` names it. */
+    engine: string;
+    /** "not covered", "observed", "witnessed", "bounded" or "proved". */
+    strength: string;
+    bounds: VerdictBound[];
+}
+/**
+ * One verification's answer. `undecided` is the service reporting it could not
+ * answer, which a `holds: false` alone does not distinguish. Every arm carries
+ * the `standing` its evidence rests on.
+ */
+export type SysMLVerdict = {
+    kind: "holds";
+    subject: VerdictSubject;
+    standing: VerdictStanding;
+} | {
+    kind: "fails";
+    subject: VerdictSubject;
+    condition: string;
+    standing: VerdictStanding;
+} | {
+    kind: "undecided";
+    subject: VerdictSubject;
+    error: string;
+    cause: FailureCause;
+    standing: VerdictStanding;
+};
+/**
+ * Decodes a `sysml.Value` into the union.
+ *
+ * @throws {MalformedValueError} for a value that contradicts itself: an array
+ *   whose elements do not fill its dimensions, a vector with a component that
+ *   is not a number, a vector quantity with no components, a set listing a
+ *   member twice, a tensor quantity whose components do not fill its
+ *   dimensions, a quantity (alone or as a component) with no magnitude, a
+ *   measurement reference naming no unit or a unit without its reduction, or a
+ *   metaobject naming no element.
+ */
+export declare function decodeValue(value: Value | undefined): SysMLValue;
+/**
+ * Encodes the union as the `sysml.Value` the service decodes: the inverse of
+ * {@link decodeValue} for every kind but `absent`, which is no value at all.
+ *
+ * @throws {MalformedValueError} for an `absent` value, or a structured value
+ *   the service would refuse (see {@link decodeValue}).
+ */
+export declare function encodeValue(value: SysMLValue): Value;
+/** Decodes a `sysml.Verdict` into the union. */
+export declare function decodeVerdict(verdict: Verdict): SysMLVerdict;
+/** Reads the standing fields the `engines` capability adds to a verdict. */
+export declare function decodeStanding(verdict: {
+    engine: string;
+    strength: string;
+    bounds: Bound[];
+}): VerdictStanding;
+/** Names the enum the service reports for a failure it could not answer through. */
+export declare function failureCause(reason: FailureReason): FailureCause;
+/** Renders a value the way the REPL prints one, for logs and error messages. */
+export declare function formatValue(value: SysMLValue): string;
+/**
+ * Whether two values are the same value to the model, as the service judges a
+ * set's membership: numbers by value, so a whole `real` is the `int` of its
+ * value and a `complex` on the real axis is its real part, exactly across the
+ * whole `int` range; a `sequence`'s order counts and a `set`'s does not, nor
+ * does a member it lists twice; a quantity is the same over its base units; a
+ * `measurementRef` is one reduction at one scale however spelt, except that a
+ * named unit of dimension one is only its own declaration (`rad` is not `sr`);
+ * an `enum` is its `literalId`, whatever else describes it; a `function` is
+ * its `calcId` read against its `selfId`; a `null` is the same whatever its
+ * reason, and the same as an empty `sequence` or `set` — the model's absent
+ * value however spelt.
+ */
+export declare function valuesEqual(a: SysMLValue, b: SysMLValue): boolean;