@openmbee/opensysml 0.9.1 → 0.10.0

package/dist/core/verdict.d.ts

@@ -0,0 +1,271 @@
+import type { CaseEvaluation as PbCaseEvaluation, RunAnalysisResponse, RunSweepResponse, ValidateInstanceResponse, Value, Verdict as PbVerdict, VerificationVerdict as PbVerificationVerdict } from "../generated/sysml_pb.js";
+import { FailureReason } from "../generated/sysml_pb.js";
+import { UnsupportedValueError, type ModelDiagnostic } from "./errors.js";
+import type { Instance } from "./model.js";
+import { type EngineBound, type Standing } from "./engines.js";
+import { type SysMLValue, type SysMLVerdict, type VerificationVerdict } from "./values.js";
+/** Verdict kinds, as the service reports them. */
+export declare const KIND_CONSTRAINT = "constraint";
+export declare const KIND_REQUIREMENT = "requirement";
+export declare const KIND_SATISFY = "satisfy";
+export declare const KIND_OBJECTIVE = "objective";
+export declare const KIND_ASSERTION = "assertion";
+export declare const KIND_OBJECT = "object";
+/** VerdictKind values a verification case's body produces. */
+export declare const VERDICT_PASS = "pass";
+export declare const VERDICT_FAIL = "fail";
+export declare const VERDICT_INCONCLUSIVE = "inconclusive";
+export declare const VERDICT_ERROR = "error";
+/** The questions a verification answers. */
+export declare const QUESTION_EVALUATE = "evaluate";
+export declare const QUESTION_HOLDS = "holds";
+export declare const QUESTION_SATISFIABLE = "satisfiable";
+/** The statuses a verdict reports, as the service spells them. */
+export declare const STATUS_HOLDS = "holds";
+export declare const STATUS_VIOLATED = "violated";
+export declare const STATUS_UNDECIDED = "undecided";
+export declare const STATUS_SATISFIABLE = "satisfiable";
+export declare const STATUS_UNSATISFIABLE = "unsatisfiable";
+export type { SysMLVerdict, VerificationVerdict };
+export type { WitnessAssignment } from "./values.js";
+/** A value, or the error decoding it raised. */
+export type ValueOrError = SysMLValue | UnsupportedValueError;
+/** Whether a verdict's condition holds: the arm it decoded to. */
+export declare function verdictHolds(verdict: SysMLVerdict): boolean;
+/** Whether the verdict is an answer about the model at all: not undecided. */
+export declare function verdictEvaluated(verdict: SysMLVerdict): boolean;
+/** Raise an {@link ExecutionError} when the verdict is undecided; else return it. */
+export declare function raiseVerdictError(verdict: SysMLVerdict): SysMLVerdict;
+/** One line saying what the verdict is and why, then its standing when reported. */
+export declare function explainVerdict(verdict: SysMLVerdict): string;
+/** One line saying what a verification case's body answered and why. */
+export declare function explainVerificationVerdict(verdict: VerificationVerdict): string;
+/** Whether a verification-case verdict is a pass. */
+export declare function verificationPassed(verdict: VerificationVerdict): boolean;
+/** Read a wire `VerificationVerdict`. */
+export declare function decodeVerificationVerdict(pb: PbVerificationVerdict): VerificationVerdict;
+/**
+ * A verdict as the response reported it: the union of values.ts plus the
+ * instances and diagnostics its response carried. A verification's verdict is
+ * the answer it gave, never an exception; an undecided arm is an answer too —
+ * a failure to evaluate, reported as `error`.
+ */
+export interface Verdict {
+    readonly verdict: SysMLVerdict;
+    /** The objects the call reported: the one this verdict is about and those reachable from it. */
+    readonly instances: readonly Instance[];
+    /** Diagnostics the service reported. */
+    readonly diagnostics: readonly ModelDiagnostic[];
+}
+/** The arm of a `Verdict`, for callers that switch on it directly. */
+export declare function armOf(verdict: Verdict): SysMLVerdict;
+/** Whether the verdict's condition holds. */
+export declare function holds(verdict: Verdict): boolean;
+/** Raise when the verdict reports the named element is of another kind. */
+export declare function raiseWrongKind(pbVerdict: PbVerdict | undefined, diagnostics: readonly ModelDiagnostic[]): void;
+/** Raise the error a failure the service classified: wrong kind, else a run failure. */
+export declare function raiseFailure(message: string, failureReason: FailureReason, diagnostics: readonly ModelDiagnostic[]): never;
+/** Read the error-or-result of an outputs map: undecodable values stay errors in place. */
+export declare function valuesMap(entries: Iterable<[string, Value | undefined]>): Map<string, ValueOrError>;
+/** The verifications the requirement of `pbVerdict` was reported for. */
+export declare function verificationsFor(verifications: readonly VerificationVerdict[], pbVerdict: PbVerdict): VerificationVerdict[];
+/** Wrap a wire verdict with the instances and diagnostics its response carried,
+ * attaching the verifications of its own requirement — every one the response
+ * carried when `attachAll` is set, as a single-verdict response asks for. */
+export declare function verdictOf(pbVerdict: PbVerdict, instances: readonly Instance[], diagnostics: readonly ModelDiagnostic[], verifications: readonly VerificationVerdict[], attachAll?: boolean): Verdict;
+/** The outputs an invocation computed, or the features a calc usage wrote. */
+export declare class CalcResult {
+    /** The value an invocation returned; undefined when `outputs` carries the answer. */
+    readonly value: ValueOrError | undefined;
+    /** Output features a calc usage computed. */
+    readonly outputs: ReadonlyMap<string, ValueOrError>;
+    readonly diagnostics: readonly ModelDiagnostic[];
+    readonly standing: Standing;
+    constructor(init: {
+        value?: ValueOrError;
+        outputs: ReadonlyMap<string, ValueOrError>;
+        diagnostics?: readonly ModelDiagnostic[];
+        standing?: Standing;
+    });
+    get engine(): string;
+    /** Strength of the evidence the answer rests on; empty when unreported. */
+    get strength(): string;
+    /** The bounds the engine ran under. */
+    get bounds(): readonly EngineBound[];
+    toString(): string;
+}
+/** One application an analysis case made of one of its own calcs as a value. */
+export declare class CaseEvaluation {
+    /** FQN of the calc applied. */
+    readonly functionId: string;
+    /** What it was applied to; an alternative is the instance it is. */
+    readonly arguments: readonly ValueOrError[];
+    /** What it computed; undefined when `error` says why nothing was. */
+    readonly result: ValueOrError | undefined;
+    /** Why the evaluation computed nothing; empty when it did. */
+    readonly error: string;
+    /** Whether the case returned this evaluation's argument: a trade study's selection. */
+    readonly selected: boolean;
+    /** Whether it computed what the selected one did without being selected. */
+    readonly tied: boolean;
+    constructor(init: {
+        functionId: string;
+        arguments: readonly ValueOrError[];
+        result?: ValueOrError;
+        error?: string;
+        selected?: boolean;
+        tied?: boolean;
+    });
+    /** Whether the evaluation computed a result. */
+    get evaluated(): boolean;
+    /** One line saying what was evaluated, what it gave, and whether it was selected. */
+    explain(): string;
+    toString(): string;
+}
+/** What an analysis case computed and decided. */
+export declare class AnalysisResult {
+    /** Output features the case computed, by name. */
+    readonly outputs: ReadonlyMap<string, ValueOrError>;
+    /** The objective and assertion verdicts, in the order the case states them. */
+    readonly verdicts: readonly Verdict[];
+    /** The subject the case ran on and the objects reachable from it. */
+    readonly instances: readonly Instance[];
+    readonly diagnostics: readonly ModelDiagnostic[];
+    /** For a verification case, what its body answered and each subcase's. */
+    readonly verifications: readonly VerificationVerdict[];
+    /** Each application the run made of one of the case's calcs as a value. */
+    readonly evaluations: readonly CaseEvaluation[];
+    readonly standing: Standing;
+    constructor(init: {
+        outputs: ReadonlyMap<string, ValueOrError>;
+        verdicts: readonly Verdict[];
+        instances?: readonly Instance[];
+        diagnostics?: readonly ModelDiagnostic[];
+        verifications?: readonly VerificationVerdict[];
+        evaluations?: readonly CaseEvaluation[];
+        standing?: Standing;
+    });
+    get engine(): string;
+    /** Strength of the evidence the answer rests on; empty when unreported. */
+    get strength(): string;
+    /** The bounds the engine ran under. */
+    get bounds(): readonly EngineBound[];
+    /** The evaluations of the alternatives the case selected; one for a trade study. */
+    get selected(): CaseEvaluation[];
+    /** Whether every objective and assertion holds; a case stating none is satisfied. */
+    get satisfied(): boolean;
+    toString(): string;
+}
+/** Every assertion about one object and the objects it holds, answered. */
+export declare class Validation {
+    /** One per assertion, root first then each held object in traversal order. */
+    readonly verdicts: readonly Verdict[];
+    /** The object's own verdict, of kind 'object'; undefined when the service sent none. */
+    readonly summary: Verdict | undefined;
+    /** The object validated and every object reachable from it. */
+    readonly instances: readonly Instance[];
+    /** Whether traversal stopped at its bound before reaching every held object. */
+    readonly bounded: boolean;
+    readonly diagnostics: readonly ModelDiagnostic[];
+    /** What the bodies of the verification cases of the requirements met answered. */
+    readonly verifications: readonly VerificationVerdict[];
+    constructor(init: {
+        verdicts: readonly Verdict[];
+        summary?: Verdict;
+        instances?: readonly Instance[];
+        bounded?: boolean;
+        diagnostics?: readonly ModelDiagnostic[];
+        verifications?: readonly VerificationVerdict[];
+    });
+    /** The standing of the summary's engine; unreported when the service sent none. */
+    get standing(): Standing;
+    get engine(): string;
+    /** Strength of the evidence the answer rests on; empty when unreported. */
+    get strength(): string;
+    /** The bounds the engine ran under. */
+    get bounds(): readonly EngineBound[];
+    /** Whether the object is shown valid: at least one assertion, every one holding, all reached. */
+    get valid(): boolean;
+    /** The verdicts the model answered false, as opposed to undecided ones. */
+    get violated(): Verdict[];
+    /** The verdicts whose condition could not be evaluated. */
+    get undecided(): Verdict[];
+    /** Raise an {@link ExecutionError} if any assertion could not be decided. */
+    raiseForError(): this;
+    get length(): number;
+    [Symbol.iterator](): Iterator<Verdict>;
+    toString(): string;
+}
+/** One run of a sweep: what it bound, what it produced, and how long it took. */
+export declare class SweepRow {
+    /** The swept parameters as this run bound them, by name. */
+    readonly inputs: ReadonlyMap<string, ValueOrError>;
+    /** What the run produced, by name; a calc's return is named "result". */
+    readonly outputs: ReadonlyMap<string, ValueOrError>;
+    /** The objective and assertion verdicts of an analysis case; empty for a calc. */
+    readonly verdicts: readonly Verdict[];
+    /** Wall time of this run, in seconds. */
+    readonly seconds: number;
+    /** Why this run failed; empty when it did not. */
+    readonly error: string;
+    /** Each application this run made of one of the case's calcs as a value. */
+    readonly evaluations: readonly CaseEvaluation[];
+    constructor(init: {
+        inputs: ReadonlyMap<string, ValueOrError>;
+        outputs: ReadonlyMap<string, ValueOrError>;
+        verdicts: readonly Verdict[];
+        seconds: number;
+        error?: string;
+        evaluations?: readonly CaseEvaluation[];
+    });
+    /** The evaluations of the alternatives this run selected; one for a trade study. */
+    get selected(): CaseEvaluation[];
+    /** Whether this run failed rather than producing outputs. */
+    get failed(): boolean;
+    toString(): string;
+}
+/** Every run of one sweep, in the order the runs were made. */
+export declare class SweepTable {
+    /** One row per run. */
+    readonly rows: readonly SweepRow[];
+    /** The swept parameters, in the order their ranges were given. */
+    readonly parameters: readonly string[];
+    /** Whether the rows were drawn rather than stepped through. */
+    readonly sampled: boolean;
+    /** The seed the rows were drawn from; 0 for a swept table. */
+    readonly seed: bigint;
+    /** The subjects the runs were about and the objects reachable from them. */
+    readonly instances: readonly Instance[];
+    readonly diagnostics: readonly ModelDiagnostic[];
+    readonly standing: Standing;
+    constructor(init: {
+        rows: readonly SweepRow[];
+        parameters: readonly string[];
+        sampled?: boolean;
+        seed?: bigint;
+        instances?: readonly Instance[];
+        diagnostics?: readonly ModelDiagnostic[];
+        standing?: Standing;
+    });
+    get engine(): string;
+    /** Strength of the evidence the answer rests on; empty when unreported. */
+    get strength(): string;
+    /** The bounds the engine ran under. */
+    get bounds(): readonly EngineBound[];
+    /** The runs that failed. */
+    get failures(): SweepRow[];
+    get length(): number;
+    [Symbol.iterator](): Iterator<SweepRow>;
+    row(index: number): SweepRow;
+    toString(): string;
+}
+/** Read the case evaluations of a response, undecodable values kept as errors. */
+export declare function evaluationsOf(evals: readonly PbCaseEvaluation[]): CaseEvaluation[];
+/** Decode one wire `Value`, keeping a decode failure as the error it raised. */
+export declare function valueOrError(pb: Value | undefined): ValueOrError;
+/** Read the verdicts a validation response carries, and its summary. */
+export declare function validationOf(response: ValidateInstanceResponse, instances: readonly Instance[], diagnostics: readonly ModelDiagnostic[]): Validation;
+/** Read a RunAnalysis response, or raise its failure. */
+export declare function analysisResultOf(response: RunAnalysisResponse, instances: readonly Instance[], diagnostics: readonly ModelDiagnostic[]): AnalysisResult;
+/** Read a RunSweep response into a SweepTable. */
+export declare function sweepTableOf(response: RunSweepResponse, instances: readonly Instance[], diagnostics: readonly ModelDiagnostic[]): SweepTable;