@rytass/bpm-core-nestjs-module 0.19.0 → 0.20.0

package/src/lib/condition/expression-function-invocation.js

@@ -0,0 +1,290 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callsUnavailableFunction = exports.isRegistryFunctionName = exports.readExpressionFunctionTable = exports.createExpressionFunctionInvoker = exports.runWithExpressionFunctionFrame = void 0;
+const common_1 = require("@nestjs/common");
+const bpm_core_shared_1 = require("@rytass/bpm-core-shared");
+const expression_function_registry_1 = require("../expression-function/expression-function.registry");
+const expression_engine_failure_1 = require("./expression-engine-failure");
+const expression_result_walker_1 = require("./expression-result.walker");
+/*
+ * The one place a function an expression calls is run (ADR 22 §3.5). Both
+ * engine adapters register the wrappers built here, so the two dialects share
+ * one set of rules:
+ *
+ * - arguments become fresh deep-frozen JSON copies (the walker), so a handler
+ *   can never reach `formData`; writing to one throws `TypeError` in strict mode;
+ * - an argument that does not fit the declared parameter type is
+ *   `EXPRESSION_TYPE_ERROR`, as the engine reports an overload mismatch;
+ * - a handler that throws, returns a thenable, or returns something that is
+ *   not JSON or not its `returnType` is `EXPRESSION_FUNCTION_FAILED`, and its
+ *   message is never kept: only the function name and the code are logged;
+ * - the handler runs inside the evaluation, so its time is charged to the
+ *   expression budget and a handler that does not finish is interrupted
+ *   (`EXPRESSION_BUDGET_EXCEEDED`, the interrupt skips every catch here).
+ */
+const logger = new common_1.Logger('ExpressionFunction');
+let activeFrame = null;
+/**
+ * Runs one engine evaluation and fails it with `EXPRESSION_FUNCTION_FAILED`
+ * when any function it called failed, even if the engine absorbed that error.
+ */
+const runWithExpressionFunctionFrame = (work) => {
+    const previous = activeFrame;
+    // Mutable on purpose: the wrappers below flag it while the engine runs.
+    const frame = { failed: false };
+    activeFrame = frame;
+    try {
+        const result = work();
+        if (frame.failed) {
+            throw new expression_engine_failure_1.ExpressionEngineFailure('EXPRESSION_FUNCTION_FAILED');
+        }
+        return result;
+    }
+    catch (error) {
+        if (frame.failed) {
+            throw new expression_engine_failure_1.ExpressionEngineFailure('EXPRESSION_FUNCTION_FAILED');
+        }
+        throw error;
+    }
+    finally {
+        activeFrame = previous;
+    }
+};
+exports.runWithExpressionFunctionFrame = runWithExpressionFunctionFrame;
+const failFunction = (name, reason) => {
+    if (activeFrame !== null) {
+        activeFrame.failed = true;
+    }
+    // The name is the host's validated identifier and the reason a fixed word;
+    // neither the handler's message nor any argument is ever written.
+    logger.warn(`function=${name} code=EXPRESSION_FUNCTION_FAILED reason=${reason}`);
+    throw new expression_engine_failure_1.ExpressionEngineFailure('EXPRESSION_FUNCTION_FAILED');
+};
+const refuseArgument = () => {
+    throw new expression_engine_failure_1.ExpressionEngineFailure('EXPRESSION_TYPE_ERROR');
+};
+const isPlainMap = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** Whether a JSON value is of a declared type. `dyn` accepts any JSON value. */
+const isOfType = (value, type) => {
+    switch (type) {
+        case 'bool':
+            return typeof value === 'boolean';
+        case 'double':
+            return typeof value === 'number';
+        case 'dyn':
+            return true;
+        case 'int':
+            return typeof value === 'number' && Number.isInteger(value);
+        case 'list':
+            return Array.isArray(value);
+        case 'map':
+            return isPlainMap(value);
+        case 'null':
+            return value === null;
+        case 'string':
+            return typeof value === 'string';
+        default:
+            return false;
+    }
+};
+/**
+ * One argument as the handler sees it: a fresh deep-frozen JSON copy (cel-v2
+ * `int`s become JS numbers). A value that is not JSON — cel-v2 bytes, a
+ * timestamp, a value beyond the result limits — is a type error at the call.
+ */
+const readArgument = (name, raw, type) => {
+    let value;
+    try {
+        value = (0, expression_result_walker_1.normalizeExpressionResult)(raw, name, expression_result_walker_1.DEFAULT_EXPRESSION_RESULT_LIMITS);
+    }
+    catch {
+        return refuseArgument();
+    }
+    return isOfType(value, type) ? value : refuseArgument();
+};
+const isThenable = (value) => (typeof value === 'object' || typeof value === 'function') &&
+    value !== null &&
+    typeof value.then === 'function';
+const ignoreRejection = () => undefined;
+/**
+ * Marks a native promise's rejection as handled, so a rejection nobody awaits
+ * does not become an unhandled rejection in the host process.
+ *
+ * Only a real promise is touched, and through the intrinsic
+ * `Promise.prototype.then`: its brand check throws for anything else before
+ * any host code runs, and an own `then` the host put on a promise is never
+ * called. A foreign thenable is deliberately not adopted — `Promise.resolve`
+ * would call its `then` in a later microtask, after the evaluation and outside
+ * the budget, where it could block the event loop for as long as it likes.
+ * Whatever does run here (a promise subclass's species constructor) runs now,
+ * inside the evaluation and its budget.
+ */
+const silenceNativeRejection = (value) => {
+    try {
+        Reflect.apply(Promise.prototype.then, value, [undefined, ignoreRejection]);
+    }
+    catch {
+        // Not a native promise, or a subclass that refused: nothing to silence.
+    }
+};
+/**
+ * What the engine gets back: the checked JSON result, with a declared `int`
+ * turned into a `bigint` for cel-v2, whose `int` is a `bigint` (a JS number
+ * there is a `double`, and `int` results would silently compare unequal).
+ */
+const toEngineValue = (value, returnType, dialect) => dialect === 'cel-v2' && returnType === 'int' && typeof value === 'number'
+    ? BigInt(value)
+    : value;
+/**
+ * Wraps a registered function for one dialect's engine. The wrapper is what
+ * the engine calls; the handler only ever sees checked, frozen arguments.
+ */
+const createExpressionFunctionInvoker = (fn, dialect) => (...rawArgs) => {
+    // cel-v2 enforces arity through the registered signature; cel-legacy
+    // passes whatever was written.
+    if (rawArgs.length !== fn.parameters.length) {
+        return refuseArgument();
+    }
+    const args = rawArgs.map((raw, index) => readArgument(fn.name, raw, fn.parameters[index].type));
+    let raw;
+    let thenable;
+    try {
+        raw = Reflect.apply(fn.handler, undefined, args);
+        // Inside the `try`: reading `then` can run a host getter.
+        thenable = isThenable(raw);
+    }
+    catch {
+        // Whatever the handler threw — a `TypeError` from writing to a frozen
+        // argument, a host error, even an `ExpressionRuntimeError` that would
+        // otherwise pass through with its own label and code — becomes one code.
+        return failFunction(fn.name, 'threw');
+    }
+    if (thenable) {
+        // Nobody will await it; without a handler a later rejection would be an
+        // unhandled rejection in the host process.
+        silenceNativeRejection(raw);
+        return failFunction(fn.name, 'thenable');
+    }
+    let value;
+    try {
+        value = (0, expression_result_walker_1.normalizeExpressionResult)(raw, fn.name, expression_result_walker_1.DEFAULT_EXPRESSION_RESULT_LIMITS);
+    }
+    catch {
+        return failFunction(fn.name, 'invalid-result');
+    }
+    return isOfType(value, fn.returnType)
+        ? toEngineValue(value, fn.returnType, dialect)
+        : failFunction(fn.name, 'return-type');
+};
+exports.createExpressionFunctionInvoker = createExpressionFunctionInvoker;
+const tables = new WeakMap();
+/** Thrown inside the table read when the registry answered out of shape. */
+class RegistryShapeError extends Error {
+}
+const VALUE_TYPES = new Set(expression_function_registry_1.BPM_EXPRESSION_VALUE_TYPES);
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const refuseShape = () => {
+    throw new RegistryShapeError();
+};
+const readValueType = (value) => typeof value === 'string' && VALUE_TYPES.has(value)
+    ? value
+    : refuseShape();
+/**
+ * A frozen copy of what `get` returned for `name`, or a shape refusal. The
+ * copy is what the wrappers read, so a registry that changes the object it
+ * returned later changes nothing here.
+ */
+const readRegisteredFunction = (candidate, name) => {
+    if (!isRecord(candidate) || candidate.name !== name) {
+        return refuseShape();
+    }
+    const { description, handler, label, parameters, returnType } = candidate;
+    if (typeof handler !== 'function' || !Array.isArray(parameters)) {
+        return refuseShape();
+    }
+    return Object.freeze({
+        description: typeof description === 'string' ? description : '',
+        handler: handler,
+        label: typeof label === 'string' ? label : name,
+        name,
+        parameters: Object.freeze(parameters.map((parameter) => isRecord(parameter) && typeof parameter.name === 'string'
+            ? Object.freeze({
+                name: parameter.name,
+                type: readValueType(parameter.type),
+            })
+            : refuseShape())),
+        returnType: readValueType(returnType),
+    });
+};
+const failRegistry = (reason) => {
+    logger.warn(`code=EXPRESSION_FUNCTION_FAILED reason=${reason}`);
+    throw new expression_engine_failure_1.ExpressionEngineFailure('EXPRESSION_FUNCTION_FAILED');
+};
+const readListedNames = (listed) => {
+    if (!Array.isArray(listed)) {
+        return refuseShape();
+    }
+    const names = listed.map((descriptor) => isRecord(descriptor) &&
+        typeof descriptor.name === 'string' &&
+        (0, exports.isRegistryFunctionName)(descriptor.name)
+        ? descriptor.name
+        : refuseShape());
+    // A name listed twice would register two overloads of one signature.
+    return new Set(names).size === names.length ? names : refuseShape();
+};
+/**
+ * Reads every function a registry lists, through `get`, once per registry.
+ *
+ * The registry is host code (a host may provide its own under
+ * `BPM_EXPRESSION_FUNCTION_REGISTRY`). If `list` or `get` throws, or answers
+ * out of shape — not a list, a name that is not a function name or is listed
+ * twice, `null` for a listed name, an object without a handler or with an
+ * unknown type — the evaluation fails with `EXPRESSION_FUNCTION_FAILED`. The
+ * host's message is never kept: only a fixed reason is logged. A failure is
+ * not cached, so the next evaluation asks the registry again.
+ */
+const readExpressionFunctionTable = (registry) => {
+    const cached = tables.get(registry);
+    if (cached) {
+        return cached;
+    }
+    let functions;
+    try {
+        functions = Object.freeze(readListedNames(registry.list()).map((name) => readRegisteredFunction(registry.get(name), name)));
+    }
+    catch (error) {
+        return failRegistry(error instanceof RegistryShapeError ? 'registry-shape' : 'registry-threw');
+    }
+    const table = Object.freeze({
+        functions,
+        names: new Set(functions.map((fn) => fn.name)),
+    });
+    tables.set(registry, table);
+    return table;
+};
+exports.readExpressionFunctionTable = readExpressionFunctionTable;
+const BUILT_IN_NAMES = new Set(bpm_core_shared_1.BPM_BUILT_IN_EXPRESSION_FUNCTION_NAMES);
+/**
+ * Whether a called name is one a registry decides: shaped like a host function
+ * (`…_vN`) or one of the nine built-ins. The engine's own functions (`size`,
+ * `int`, `matches`, …) never are, and neither is any other unknown name, which
+ * keeps the engine's own error (`EXPRESSION_TYPE_ERROR`) at evaluation and is
+ * refused outright by the publish lint (docs/24 §2.1, 2026-11-07).
+ *
+ * The publish lint, the rollback check and {@link callsUnavailableFunction}
+ * all read this one rule.
+ */
+const isRegistryFunctionName = (name) => BUILT_IN_NAMES.has(name) || bpm_core_shared_1.BPM_EXPRESSION_FUNCTION_NAME_PATTERN.test(name);
+exports.isRegistryFunctionName = isRegistryFunctionName;
+/**
+ * Whether an expression calls a function the registry does not have — a host
+ * function withdrawn after the version was published, or a built-in a custom
+ * registry left out. Only names {@link isRegistryFunctionName} accepts count:
+ * any other unknown name keeps the engine's own error, as before functions
+ * existed. The caller fails the evaluation with `EXPRESSION_FUNCTION_FAILED`
+ * before the engine runs, so the outcome does not depend on which branch the
+ * engine would have reached.
+ */
+const callsUnavailableFunction = (calledNames, table) => calledNames.some((name) => (0, exports.isRegistryFunctionName)(name) && !table.names.has(name));
+exports.callsUnavailableFunction = callsUnavailableFunction;
+//# sourceMappingURL=expression-function-invocation.js.map

package/src/lib/condition/expression-function-invocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression-function-invocation.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/condition/expression-function-invocation.ts"],"names":[],"mappings":"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"}

package/src/lib/condition/expression-result.walker.d.ts

@@ -0,0 +1,18 @@
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export interface ExpressionResultLimits {
+    readonly maxDepth: number;
+    readonly maxNodes: number;
+    /** Upper bound on the size the value would have as JSON, estimated while walking. */
+    readonly maxBytes: number;
+}
+export declare const DEFAULT_EXPRESSION_RESULT_LIMITS: ExpressionResultLimits;
+/**
+ * Turns whatever an engine returned into a fresh, deep-frozen JSON value, or
+ * throws `EXPRESSION_INVALID_RESULT`. Functions, promises, class instances,
+ * `undefined`, non-finite numbers and out-of-range integers are all refused. The
+ * size is estimated while walking, not with `JSON.stringify`, so a huge shared
+ * string cannot cost much before it is refused.
+ */
+export declare const normalizeExpressionResult: (raw: unknown, label: string, limits?: ExpressionResultLimits) => JsonValue;

package/src/lib/condition/expression-result.walker.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeExpressionResult = exports.DEFAULT_EXPRESSION_RESULT_LIMITS = void 0;
+const expression_errors_1 = require("./expression-errors");
+exports.DEFAULT_EXPRESSION_RESULT_LIMITS = {
+    maxBytes: 64 * 1024,
+    maxDepth: 32,
+    maxNodes: 10_000,
+};
+// Writing these as object keys would let a result reach a prototype when a
+// consumer merges it. Rejected at any depth where they are own keys of the
+// value the engine returned. What reaches the walker depends on the engine
+// (verified on both real engines 2026-11-07; differential corpus P43–P45):
+// - cel-legacy (cel-js 0.8.2) builds a map literal by assignment, so
+//   `{"constructor": 1}` arrives with that own key and is refused here, and
+//   `{"__proto__": {...}}` swaps the prototype and is refused by
+//   `isPlainObject`.
+// - cel-v2 (@marcbachmann/cel-js 8.0.0) drops all three keys while building
+//   the map, so `{"constructor": 1}` arrives as `{}` and nothing is refused:
+//   no pollution, but the key is lost silently instead of failing closed.
+//   Refusing it needs the AST, which is P2's (docs/24 §2.5).
+const FORBIDDEN_KEYS = new Set([
+    '__proto__',
+    'constructor',
+    'prototype',
+]);
+const NUMBER_BYTES = 24;
+const LITERAL_BYTES = 5;
+const KEY_OVERHEAD_BYTES = 4;
+/**
+ * A map the walker may copy: its prototype is `Object.prototype` or `null`, and
+ * it is neither `Object.prototype` itself nor an array. `Object.prototype` has a `null`
+ * prototype, so without the second check an engine that handed back the shared
+ * prototype would have it accepted as an empty map.
+ */
+const isPlainObject = (value) => {
+    // An array whose prototype was swapped for Object.prototype is still an
+    // array exotic object; it is refused, not copied as a map of indexes.
+    if (value === Object.prototype || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+/**
+ * A list the walker may copy: a real array whose prototype is
+ * `Array.prototype`. `Array.isArray` alone also accepts `Array.prototype`
+ * itself, arrays from another realm and arrays whose prototype was replaced.
+ */
+const isPlainArray = (value) => Array.isArray(value) &&
+    value !== Array.prototype &&
+    Object.getPrototypeOf(value) === Array.prototype;
+/**
+ * Reads an own property without running code. An accessor is refused rather
+ * than called: a getter would run outside the time budget, and what it returns
+ * could differ from one read to the next.
+ */
+const readDataProperty = (value, key, refuse) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor && 'value' in descriptor ? descriptor.value : refuse();
+};
+/**
+ * Turns whatever an engine returned into a fresh, deep-frozen JSON value, or
+ * throws `EXPRESSION_INVALID_RESULT`. Functions, promises, class instances,
+ * `undefined`, non-finite numbers and out-of-range integers are all refused. The
+ * size is estimated while walking, not with `JSON.stringify`, so a huge shared
+ * string cannot cost much before it is refused.
+ */
+const normalizeExpressionResult = (raw, label, limits = exports.DEFAULT_EXPRESSION_RESULT_LIMITS) => {
+    // Mutable on purpose: one ledger spans the whole walk, and returning the
+    // counts from every recursive call would make the walker harder to read.
+    const ledger = { bytes: 0, nodes: 0 };
+    const refuse = () => {
+        throw new expression_errors_1.ExpressionRuntimeError('EXPRESSION_INVALID_RESULT', label);
+    };
+    const charge = (bytes) => {
+        ledger.bytes += bytes;
+        if (ledger.bytes > limits.maxBytes) {
+            refuse();
+        }
+    };
+    const walk = (value, depth) => {
+        if (depth > limits.maxDepth) {
+            refuse();
+        }
+        ledger.nodes += 1;
+        if (ledger.nodes > limits.maxNodes) {
+            refuse();
+        }
+        if (value === null) {
+            charge(LITERAL_BYTES);
+            return null;
+        }
+        if (typeof value === 'boolean') {
+            charge(LITERAL_BYTES);
+            return value;
+        }
+        if (typeof value === 'number') {
+            // Every double beyond 2^53 is an integer, so this is exactly the out-of-
+            // safe-range case. cel-legacy returns numbers, not bigints, so this is the
+            // branch that actually sees an oversized integer result.
+            if (!Number.isFinite(value) ||
+                Math.abs(value) > Number.MAX_SAFE_INTEGER) {
+                refuse();
+            }
+            charge(NUMBER_BYTES);
+            return value;
+        }
+        if (typeof value === 'bigint') {
+            if (value > BigInt(Number.MAX_SAFE_INTEGER) ||
+                value < BigInt(Number.MIN_SAFE_INTEGER)) {
+                refuse();
+            }
+            charge(NUMBER_BYTES);
+            return Number(value);
+        }
+        if (typeof value === 'string') {
+            // UTF-8 never takes fewer bytes than UTF-16 code units, so a string longer
+            // than the whole allowance is refused before its bytes are counted.
+            if (value.length > limits.maxBytes - ledger.bytes) {
+                refuse();
+            }
+            charge(Buffer.byteLength(value, 'utf8'));
+            return value;
+        }
+        if (typeof value === 'object' && isPlainArray(value)) {
+            const list = value;
+            // Indexes are read as data properties, so a getter on an index (or a hole
+            // that would read through to the prototype) is refused, not run.
+            return Object.freeze(Array.from({ length: list.length }, (_item, index) => walk(readDataProperty(list, String(index), refuse), depth + 1)));
+        }
+        if (typeof value === 'object' && value !== null && isPlainObject(value)) {
+            // Symbol keys cannot be written as JSON; a value that carries one is not
+            // the plain map it looks like.
+            if (Object.getOwnPropertySymbols(value).length > 0) {
+                refuse();
+            }
+            const entries = Object.keys(value).map((key) => {
+                if (FORBIDDEN_KEYS.has(key)) {
+                    refuse();
+                }
+                charge(Buffer.byteLength(key, 'utf8') + KEY_OVERHEAD_BYTES);
+                return [key, walk(readDataProperty(value, key, refuse), depth + 1)];
+            });
+            return Object.freeze(Object.fromEntries(entries));
+        }
+        return refuse();
+    };
+    return walk(raw, 0);
+};
+exports.normalizeExpressionResult = normalizeExpressionResult;
+//# sourceMappingURL=expression-result.walker.js.map

package/src/lib/condition/expression-result.walker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression-result.walker.js","sourceRoot":"","sources":["../../../../../../libs/bpm-core/src/lib/condition/expression-result.walker.ts"],"names":[],"mappings":"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"}

package/src/lib/condition/expression-runtime.d.ts

@@ -0,0 +1,70 @@
+import type { ExpressionBudget } from './expression-budget';
+import { type JsonValue } from './expression-result.walker';
+import type { BPMExpressionFunctionRegistry } from '../expression-function/expression-function.types';
+import { type ExpressionDialect } from './expression-dialect';
+/** An engine's compiled form of one expression. `native` is never read outside its adapter. */
+export interface ExpressionHandle {
+    readonly native: unknown;
+}
+/**
+ * One engine behind the runtime. `compile` runs before any budget starts and
+ * returns `null` when the expression does not parse. `evaluate` runs inside the
+ * budget and may throw whatever the engine throws; the runtime maps it.
+ */
+export interface ExpressionEngineAdapter {
+    compile(expression: string): ExpressionHandle | null;
+    evaluate(handle: ExpressionHandle, roots: Readonly<Record<string, unknown>>): unknown;
+}
+export interface ExpressionEvalRequest {
+    readonly expression: string;
+    /** Names the use point in errors and logs. Must never contain a context value. */
+    readonly label: string;
+    /** Only the roots the use point allows. */
+    readonly roots: Readonly<Record<string, unknown>>;
+    readonly budget: ExpressionBudget;
+    /**
+     * The engine to evaluate with: the dialect of the definition or rule the
+     * expression belongs to. Absent means `cel-legacy` (ADR 22 §3.3).
+     */
+    readonly dialect?: ExpressionDialect;
+}
+/**
+ * The single place where an expression is compiled and evaluated (ADR 22 §3.2).
+ * Every caller goes through here: nothing reaches an engine directly.
+ *
+ * Order: compile (outside any budget, so an interrupt cannot land in module
+ * loading), check the budget, evaluate under `runWithinTimeBudget`, normalize
+ * the result, and map any failure to an {@link ExpressionRuntimeError}.
+ *
+ * A timeout raises `EXPRESSION_BUDGET_EXCEEDED`. It never returns `false`: an
+ * expression that did not finish is not the same as one that is false.
+ */
+export declare class ExpressionRuntime {
+    private readonly legacyAdapter;
+    private readonly v2Adapter;
+    /**
+     * Without arguments the runtime calls the nine built-in functions only
+     * (ADR 22 §3.5); use {@link ExpressionRuntime.withFunctions} for a host's.
+     */
+    constructor(legacyAdapter?: ExpressionEngineAdapter, v2Adapter?: ExpressionEngineAdapter);
+    /**
+     * The runtime for a function registry: both dialects call the functions it
+     * lists, through the same argument, result and failure rules. One runtime
+     * per registry, cached, so every caller shares its compiled environments.
+     * The built-ins-only registry gets the default adapters.
+     */
+    static withFunctions(registry: BPMExpressionFunctionRegistry): ExpressionRuntime;
+    /**
+     * Compiles with the dialect's engine. This is also what loads that engine,
+     * so callers that compile before starting a budget never have an interrupt
+     * land inside module loading.
+     */
+    compile(expression: string, label: string, dialect?: ExpressionDialect): ExpressionHandle;
+    evaluate(request: ExpressionEvalRequest): JsonValue;
+    private readAdapter;
+    /**
+     * Logs only the label, the dialect, the code and the elapsed time. The message, the key
+     * name and the expression are not logged: they can carry case data.
+     */
+    private logFailure;
+}