@openmbee/opensysml 0.9.2 → 0.10.0

package/dist/core/typed.d.ts

@@ -0,0 +1,71 @@
+import type { Instance } from "./model.js";
+import { type ComplexValue, type EnumValue, type QuantityValue, type RationalValue, type SysMLValue } from "./values.js";
+/** A quantity feature value: a magnitude and the unit it is expressed in. */
+export type Quantity = {
+    kind: "quantity";
+} & QuantityValue;
+/** Resolves a nested feature value's instance id to its Instance, when known. */
+export type InstanceResolver = (id: bigint) => Instance | undefined;
+/** One decoder: a raw feature value to the typed value a getter returns. */
+export type FeatureDecoder<T> = (featureName: string, value: SysMLValue, resolve: InstanceResolver | undefined) => T;
+/** Register a generated class so {@link TypedObject.fromInstance} can tell a wrong type from an unknown one. */
+export declare function registerTyped(ctor: TypedObjectClass): void;
+/** Base class of generated typed views over an {@link Instance}. */
+export declare class TypedObject {
+    #private;
+    /** FQN of the SysML definition this class was generated from. */
+    static readonly sysmlId: string;
+    constructor(instance: Instance, resolve?: InstanceResolver);
+    /** Return a typed view over `instance`, rejecting one of another type.
+     *
+     * Accepted: an instance of exactly this class's definition; an instance of a
+     * definition that specializes it and has a generated class of its own; and an
+     * instance whose type no generated class in this process describes — the
+     * service reports the type of an instantiated *usage* as the usage's own
+     * FQN, which no generated class carries, so it cannot be related to a
+     * definition at all.
+     *
+     * Use {@link TypedObject.unchecked} to bypass this deliberately.
+     */
+    static fromInstance<C extends TypedObjectClass>(this: C, instance: Instance, resolve?: InstanceResolver): InstanceType<C>;
+    /** Return a typed view over `instance` without checking its type. */
+    static unchecked<C extends TypedObjectClass>(this: C, instance: Instance, resolve?: InstanceResolver): InstanceType<C>;
+    /** The underlying Tier 1 instance. */
+    get instance(): Instance;
+    /** The resolver nested feature values resolve instance ids through, if any. */
+    get resolver(): InstanceResolver | undefined;
+    /** Two views are equal over the same instance of the same generated class. */
+    equals(other: unknown): boolean;
+    toString(): string;
+}
+/** Decode a Boolean feature value. */
+export declare function asBoolean(featureName: string, value: SysMLValue): boolean;
+/** Decode an Integer/Natural feature value. */
+export declare function asInt(featureName: string, value: SysMLValue): bigint;
+/** Decode a Real feature value; an Integer or exact Rational widens to the nearest double. */
+export declare function asReal(featureName: string, value: SysMLValue): number;
+/** Decode a Rational feature value exactly, whichever wire arm carried it. */
+export declare function asRational(featureName: string, value: SysMLValue): RationalValue;
+/** Decode a Complex feature value; a real value widens to complex. */
+export declare function asComplex(featureName: string, value: SysMLValue): ComplexValue;
+/** Decode a String feature value. */
+export declare function asString(featureName: string, value: SysMLValue): string;
+/** Decode a quantity feature value: a magnitude and the unit it is expressed in. */
+export declare function asQuantity(featureName: string, value: SysMLValue): Quantity;
+/** Decode an enumeration-typed feature, which holds a literal rather than an instance. */
+export declare function asEnum(featureName: string, value: SysMLValue): EnumValue;
+/** Decode a feature value whose SysML type has no sound TypeScript type. */
+export declare function asObject(_featureName: string, value: SysMLValue): SysMLValue;
+/** A generated typed class: the constructor plus the sysmlId it was generated for. */
+export interface TypedObjectClass<T extends TypedObject = TypedObject> {
+    new (instance: Instance, resolve?: InstanceResolver): T;
+    readonly sysmlId: string;
+}
+/** Return a decoder wrapping a nested instance in the generated class `cls`. */
+export declare function asTyped<T extends TypedObject>(cls: TypedObjectClass<T>): FeatureDecoder<T>;
+/** The decoded value of a required single-valued feature. */
+export declare function featureValue<T>(obj: TypedObject, featureName: string, decode: FeatureDecoder<T>): T;
+/** The decoded value of a `0..1` feature, or undefined when it holds no value. */
+export declare function optionalFeatureValue<T>(obj: TypedObject, featureName: string, decode: FeatureDecoder<T>): T | undefined;
+/** The decoded values of a multi-valued feature; one holding no value is empty. */
+export declare function listFeatureValue<T>(obj: TypedObject, featureName: string, decode: FeatureDecoder<T>): T[];

package/dist/core/typed.js

@@ -0,0 +1,245 @@
+// Runtime support for generated, statically typed views over instances.
+//
+// A generated class derives from TypedObject and exposes one getter per SysML
+// feature, each delegating to the underlying Tier 1 Instance through
+// featureValue, optionalFeatureValue or listFeatureValue. Decoding is
+// unchanged: this layer only states what type a decoded value is expected to
+// have, and reports a mismatch rather than returning a wrongly typed value.
+import { FeatureValueError, InstanceTypeError, TypeMismatchError, } from "./errors.js";
+import { rationalOfDouble, rationalToNumber, } from "./values.js";
+const ABSENT = Symbol("absent");
+function readRaw(instance, featureName) {
+    const feature = instance.get(featureName);
+    if (feature === undefined) {
+        return ABSENT;
+    }
+    if (feature.kind === "error") {
+        throw new FeatureValueError(featureName, feature.error);
+    }
+    if (feature.kind === "many") {
+        return feature.values;
+    }
+    if (feature.value.kind === "absent") {
+        if (feature.materialized) {
+            return [];
+        }
+        throw new FeatureValueError(featureName, "feature value is not materialized");
+    }
+    return feature.value;
+}
+function isMany(raw) {
+    return Array.isArray(raw);
+}
+function isUnset(value) {
+    return value.kind === "unset";
+}
+function isNull(value) {
+    return value.kind === "null";
+}
+function mismatch(featureName, expected, value) {
+    return new TypeMismatchError(featureName, expected, value);
+}
+// Every sysmlId a generated class in this process answers for, so a wrong type
+// is distinguishable from one this client has never heard of.
+const GENERATED = new Map();
+/** Register a generated class so {@link TypedObject.fromInstance} can tell a wrong type from an unknown one. */
+export function registerTyped(ctor) {
+    if (ctor.sysmlId !== "") {
+        GENERATED.set(ctor.sysmlId, ctor);
+    }
+}
+/** Base class of generated typed views over an {@link Instance}. */
+export class TypedObject {
+    /** FQN of the SysML definition this class was generated from. */
+    static sysmlId = "";
+    #instance;
+    #resolve;
+    constructor(instance, resolve) {
+        this.#instance = instance;
+        this.#resolve = resolve;
+    }
+    /** Return a typed view over `instance`, rejecting one of another type.
+     *
+     * Accepted: an instance of exactly this class's definition; an instance of a
+     * definition that specializes it and has a generated class of its own; and an
+     * instance whose type no generated class in this process describes — the
+     * service reports the type of an instantiated *usage* as the usage's own
+     * FQN, which no generated class carries, so it cannot be related to a
+     * definition at all.
+     *
+     * Use {@link TypedObject.unchecked} to bypass this deliberately.
+     */
+    static fromInstance(instance, resolve) {
+        const actual = instance.typeId;
+        const generated = actual === "" ? undefined : GENERATED.get(actual);
+        if (actual !== "" && actual !== this.sysmlId && generated !== undefined) {
+            if (!(generated.prototype instanceof this)) {
+                throw new InstanceTypeError(this.sysmlId || this.name, actual);
+            }
+        }
+        return new this(instance, resolve);
+    }
+    /** Return a typed view over `instance` without checking its type. */
+    static unchecked(instance, resolve) {
+        return new this(instance, resolve);
+    }
+    /** The underlying Tier 1 instance. */
+    get instance() {
+        return this.#instance;
+    }
+    /** The resolver nested feature values resolve instance ids through, if any. */
+    get resolver() {
+        return this.#resolve;
+    }
+    /** Two views are equal over the same instance of the same generated class. */
+    equals(other) {
+        return (other instanceof TypedObject &&
+            other.constructor === this.constructor &&
+            other.instance.id === this.instance.id);
+    }
+    toString() {
+        return `${this.constructor.name}(instance=${this.#instance.id.toString()})`;
+    }
+}
+/** Decode a Boolean feature value. */
+export function asBoolean(featureName, value) {
+    if (value.kind === "boolean") {
+        return value.value;
+    }
+    throw mismatch(featureName, "bool", value);
+}
+/** Decode an Integer/Natural feature value. */
+export function asInt(featureName, value) {
+    if (value.kind === "int") {
+        return value.value;
+    }
+    throw mismatch(featureName, "int", value);
+}
+/** Decode a Real feature value; an Integer or exact Rational widens to the nearest double. */
+export function asReal(featureName, value) {
+    if (value.kind === "real") {
+        return value.value;
+    }
+    if (value.kind === "int") {
+        return Number(value.value);
+    }
+    if (value.kind === "rational") {
+        return rationalToNumber(value);
+    }
+    throw mismatch(featureName, "float", value);
+}
+/** Decode a Rational feature value exactly, whichever wire arm carried it. */
+export function asRational(featureName, value) {
+    if (value.kind === "rational") {
+        return { numerator: value.numerator, denominator: value.denominator };
+    }
+    if (value.kind === "int") {
+        return { numerator: value.value, denominator: 1n };
+    }
+    if (value.kind === "real" && Number.isFinite(value.value)) {
+        const { numerator, denominator } = rationalOfDouble(value.value);
+        return { numerator, denominator };
+    }
+    throw mismatch(featureName, "Rational", value);
+}
+/** Decode a Complex feature value; a real value widens to complex. */
+export function asComplex(featureName, value) {
+    if (value.kind === "complex") {
+        return value.value;
+    }
+    if (value.kind === "real") {
+        return { real: value.value, imaginary: 0 };
+    }
+    if (value.kind === "int") {
+        return { real: Number(value.value), imaginary: 0 };
+    }
+    throw mismatch(featureName, "complex", value);
+}
+/** Decode a String feature value. */
+export function asString(featureName, value) {
+    if (value.kind === "string") {
+        return value.value;
+    }
+    throw mismatch(featureName, "str", value);
+}
+/** Decode a quantity feature value: a magnitude and the unit it is expressed in. */
+export function asQuantity(featureName, value) {
+    if (value.kind === "quantity") {
+        return value;
+    }
+    throw mismatch(featureName, "Quantity", value);
+}
+/** Decode an enumeration-typed feature, which holds a literal rather than an instance. */
+export function asEnum(featureName, value) {
+    if (value.kind === "enum") {
+        return value.value;
+    }
+    throw mismatch(featureName, "EnumLiteral", value);
+}
+/** Decode a feature value whose SysML type has no sound TypeScript type. */
+export function asObject(_featureName, value) {
+    return value;
+}
+/** Return a decoder wrapping a nested instance in the generated class `cls`. */
+export function asTyped(cls) {
+    return (featureName, value, resolve) => {
+        if (value.kind === "instance") {
+            const nested = resolve?.(value.id);
+            if (nested !== undefined) {
+                return TypedObject.fromInstance.call(cls, nested, resolve);
+            }
+        }
+        throw mismatch(featureName, cls.name, value);
+    };
+}
+/** The decoded value of a required single-valued feature. */
+export function featureValue(obj, featureName, decode) {
+    const raw = readRaw(obj.instance, featureName);
+    if (raw === ABSENT) {
+        throw mismatch(featureName, "a value", undefined);
+    }
+    if (isMany(raw)) {
+        throw mismatch(featureName, "a single value", raw);
+    }
+    if (isNull(raw)) {
+        throw mismatch(featureName, "a value", null);
+    }
+    return decode(featureName, raw, obj.resolver);
+}
+/** The decoded value of a `0..1` feature, or undefined when it holds no value. */
+export function optionalFeatureValue(obj, featureName, decode) {
+    const raw = readRaw(obj.instance, featureName);
+    if (raw === ABSENT) {
+        return undefined;
+    }
+    if (isMany(raw)) {
+        if (raw.length === 0) {
+            return undefined;
+        }
+        if (raw.length > 1) {
+            throw mismatch(featureName, "at most one value", raw);
+        }
+        const element = raw[0];
+        return isNull(element) || isUnset(element)
+            ? undefined
+            : decode(featureName, element, obj.resolver);
+    }
+    if (isNull(raw) || isUnset(raw)) {
+        return undefined;
+    }
+    return decode(featureName, raw, obj.resolver);
+}
+/** The decoded values of a multi-valued feature; one holding no value is empty. */
+export function listFeatureValue(obj, featureName, decode) {
+    const raw = readRaw(obj.instance, featureName);
+    if (raw === ABSENT) {
+        return [];
+    }
+    if (isMany(raw)) {
+        return raw.map((element) => decode(featureName, element, obj.resolver));
+    }
+    if (isNull(raw) || isUnset(raw)) {
+        return [];
+    }
+    return [decode(featureName, raw, obj.resolver)];
+}

package/dist/core/values.d.ts

@@ -1,11 +1,19 @@
-import type { Bound, Value, Verdict } from "../generated/sysml_pb.js";
+import type { Bound, Quantity, Rational, Value, Verdict } from "../generated/sysml_pb.js";
 import { FailureReason } from "../generated/sysml_pb.js";
+import { type ServerInfo } from "./capabilities.js";
 import { type FailureCause } from "./errors.js";
-/** A quantity's magnitude: an integer or a real, never both. */
+/** An exact Rational in lowest terms over a positive denominator. */
+export interface RationalValue {
+    numerator: bigint;
+    denominator: bigint;
+}
+/** A quantity's magnitude: an Integer, an exact Rational or a Real, kept apart. */
 export type Magnitude = {
     kind: "int";
     value: bigint;
-} | {
+} | ({
+    kind: "rational";
+} & RationalValue) | {
     kind: "real";
     value: number;
 };
@@ -116,7 +124,9 @@ export interface UndeterminedValue {
 export type SysMLValue = {
     kind: "int";
     value: bigint;
-} | {
+} | ({
+    kind: "rational";
+} & RationalValue) | {
     kind: "real";
     value: number;
 } | {
@@ -170,9 +180,9 @@ export type SysMLValue = {
 } | {
     kind: "absent";
 };
-/** What a verification answered about. Kept for the verification RPCs of a later version. */
+/** What a verification answered about. */
 export interface VerdictSubject {
-    /** "constraint", "requirement" or "satisfy". */
+    /** "constraint", "requirement", "satisfy", "objective", "assertion" or "object". */
     kind: string;
     /** FQN of the verified element; empty for an anonymous satisfy assertion. */
     elementId: string;
@@ -181,6 +191,34 @@ export interface VerdictSubject {
     /** The instance verified against, when there was one. */
     instanceId?: bigint;
     instanceTypeId?: string;
+    /** FQN of the requirement a "satisfy" verdict asserts satisfied; empty for every other kind. */
+    requirementId?: string;
+    /** Where the object this verdict is about sits in a validated one (`engine.injector`, `wheels[2]`). */
+    instancePath?: string;
+}
+/** One feature's value in the assignment witnessing a verdict. */
+export interface WitnessAssignment {
+    /** The qualified feature name, chain steps appended with '.'. */
+    feature: string;
+    /** The value the evaluator replayed for the feature. */
+    value: SysMLValue;
+    /** The base units the magnitude is expressed in; empty for a value that has none. */
+    unit: string;
+    /** The solver's exact value as text. */
+    exact: string;
+}
+/** What the body of a verification case answered when it ran. */
+export interface VerificationVerdict {
+    /** FQN of the verification case that ran. */
+    caseId: string;
+    /** The VerdictKind the body produced: "pass", "fail", "inconclusive" or "error". */
+    kind: string;
+    /** Why an inconclusive body decided nothing, or the error that stopped the run. */
+    detail: string;
+    /** Whether this is the verdict of a case performed by another. */
+    subcase: boolean;
+    /** FQN of the requirement this verdict was reported for; empty for a case run for itself. */
+    requirementId: string;
 }
 /** One limit an engine ran under, and whether the run stopped at it. */
 export interface VerdictBound {
@@ -201,27 +239,45 @@ export interface VerdictStanding {
     /** "not covered", "observed", "witnessed", "bounded" or "proved". */
     strength: string;
     bounds: VerdictBound[];
+    /** Whether the service reported a standing at all. */
+    reported: boolean;
+    /** The bounds the engine stopped at. */
+    reached: 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.
+ * the `standing` its evidence rests on, the `question` asked and the `status`
+ * the service answered with, the `witness` assignment when the answer carries
+ * one, and the `verifications` the requirement's verification cases produced.
  */
 export type SysMLVerdict = {
     kind: "holds";
     subject: VerdictSubject;
     standing: VerdictStanding;
+    question: string;
+    status: string;
+    witness: WitnessAssignment[];
+    verifications: VerificationVerdict[];
 } | {
     kind: "fails";
     subject: VerdictSubject;
     condition: string;
     standing: VerdictStanding;
+    question: string;
+    status: string;
+    witness: WitnessAssignment[];
+    verifications: VerificationVerdict[];
 } | {
     kind: "undecided";
     subject: VerdictSubject;
     error: string;
     cause: FailureCause;
     standing: VerdictStanding;
+    question: string;
+    status: string;
+    witness: WitnessAssignment[];
+    verifications: VerificationVerdict[];
 };
 /**
  * Decodes a `sysml.Value` into the union.
@@ -244,7 +300,7 @@ export declare function decodeValue(value: Value | undefined): SysMLValue;
  */
 export declare function encodeValue(value: SysMLValue): Value;
 /** Decodes a `sysml.Verdict` into the union. */
-export declare function decodeVerdict(verdict: Verdict): SysMLVerdict;
+export declare function decodeVerdict(verdict: Verdict, verifications?: readonly VerificationVerdict[]): SysMLVerdict;
 /** Reads the standing fields the `engines` capability adds to a verdict. */
 export declare function decodeStanding(verdict: {
     engine: string;
@@ -255,6 +311,43 @@ export declare function decodeStanding(verdict: {
 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;
+/** A terminating Rational as its decimal, `0.1`; any other as `numerator/denominator`, `1/3`. */
+export declare function formatRational(value: RationalValue): string;
+/** A quantity magnitude as the wire's `Quantity.magnitude` oneof writes it. */
+export declare function encodeQuantityMagnitude(magnitude: Magnitude): Quantity["magnitude"];
+/** Whether an Integer travels as `int_value`; one beyond int64 travels as `big_int_value`. */
+export declare function fitsInt64(value: bigint): boolean;
+/** Reads the decimal of a `big_int_value` or `big_int_magnitude`. */
+export declare function decodeBigInteger(text: string): bigint;
+/**
+ * Rewrites in place each Rational arm of a wire value a double holds exactly as
+ * that double: the form a service without `rational_values` reads. A Rational
+ * no double holds is left as it is; a collection's elements are values of their own.
+ */
+export declare function rationalsAsReals(value: Value): void;
+/** Rewrites a quantity's Rational magnitude a double holds exactly as `real_magnitude`. */
+export declare function quantityRationalAsReal(quantity: Quantity): void;
+/** The `Rational` message of an exact Rational, numerator and denominator in full. */
+export declare function encodeRational(value: RationalValue): Rational;
+/**
+ * Reads a `rational_value` or `rational_magnitude`.
+ *
+ * @throws {MalformedValueError} for one not in lowest terms over a positive
+ *   denominator, or one a double holds, which travels as `real_value`.
+ */
+export declare function decodeRational(rational: Rational): RationalValue;
+/** The exact Rational `numerator/denominator`, reduced; throws a RangeError over a zero denominator. */
+export declare function rational(numerator: bigint, denominator?: bigint): {
+    kind: "rational";
+} & RationalValue;
+/** The exact Rational a finite double holds. */
+export declare function rationalOfDouble(x: number): {
+    kind: "rational";
+} & RationalValue;
+/** The double that holds a reduced Rational exactly, or undefined where none does. */
+export declare function rationalAsDouble(value: RationalValue): number | undefined;
+/** The double nearest the Rational: how a Real reads one. */
+export declare function rationalToNumber(value: RationalValue): number;
 /**
  * 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
@@ -269,3 +362,29 @@ export declare function formatValue(value: SysMLValue): string;
  * value however spelt.
  */
 export declare function valuesEqual(a: SysMLValue, b: SysMLValue): boolean;
+/** What a caller may pass as an argument or input to a run. A wire `Value`
+ * passes through untouched, which is how a caller sends a shape the typing
+ * layer would normalize away — including one the service is meant to refuse.
+ * A JavaScript array encodes as a sequence and a `Set` as a set, as Python's
+ * list and set do; collection elements accept every input form, not only
+ * `SysMLValue`s. */
+export type ValueInput = SysMLValue | Value | boolean | string | bigint | number | readonly ValueInput[] | ReadonlySet<ValueInput> | {
+    kind: "sequence";
+    elements: readonly ValueInput[];
+} | {
+    kind: "set";
+    elements: readonly ValueInput[];
+} | ({
+    kind: "array";
+    elements: readonly ValueInput[];
+} & Omit<ArrayValue, "elements">);
+/**
+ * Encodes a caller-facing value for the wire, requiring of `info` each
+ * capability a value kind needs before the call is sent — exactly the checks
+ * Python's `Connection._python_to_value` makes. A `SysMLValue` encodes as
+ * itself; a boolean, string, bigint and number encode as the scalar arms; a
+ * JavaScript array and `Set` encode as a sequence and a set.
+ */
+export declare function toValue(input: ValueInput, info: ServerInfo): Value;
+/** The capabilities one input value needs of the service that will decode it. */
+export declare function requireInput(value: SysMLValue, info: ServerInfo): void;