@primmel/primmel 1.20.0 → 1.21.0

package/dist/src/runtime.js

@@ -0,0 +1,648 @@
+"use strict";
+// ─────────────────────────────────────────────────────────────────────
+// The Primmel runtime (the full flow's phase 4 — the execution plane):
+// a model RUN is a replayable object — the test programs as executed,
+// the verdicts derived from the authored data, the state trajectory,
+// and the evidence records the evidence law requires. Deterministic by
+// construction: no clock, no randomness, JSON-stable — the same model,
+// instance and inputs always produce the same run.
+//
+// The evaluator covers the closed-derivation subset the checks
+// guarantee (C149: every referenced name is declared): literals,
+// attribute references, `.` field access into the dimension values'
+// typed payloads, arithmetic, comparisons, if/then/else, and abs/min/
+// max. Nothing else is legal in a declared derivation, so nothing else
+// is evaluated.
+// ─────────────────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateExpression = evaluateExpression;
+exports.projectCertificate = projectCertificate;
+exports.executeRun = executeRun;
+const operational_state_1 = require("./operational-state");
+function tokenize(src) {
+    const out = [];
+    let i = 0;
+    const s = src;
+    while (i < s.length) {
+        const ch = s[i];
+        if (/\s/.test(ch)) {
+            i++;
+            continue;
+        }
+        if (/[0-9]/.test(ch) || (ch === '.' && /[0-9]/.test(s[i + 1] ?? ''))) {
+            let j = i;
+            while (j < s.length && /[0-9.]/.test(s[j])) {
+                j++;
+            }
+            out.push({ t: 'num', v: Number(s.slice(i, j)) });
+            i = j;
+            continue;
+        }
+        if (/[A-Za-z_]/.test(ch)) {
+            let j = i;
+            while (j < s.length && /[A-Za-z0-9_]/.test(s[j])) {
+                j++;
+            }
+            out.push({ t: 'id', v: s.slice(i, j) });
+            i = j;
+            continue;
+        }
+        if (s.startsWith('<=', i) ||
+            s.startsWith('>=', i) ||
+            s.startsWith('!=', i)) {
+            out.push({ t: 'op', v: s.slice(i, i + 2) });
+            i += 2;
+            continue;
+        }
+        if ('+-*/()<>=,.'.includes(ch)) {
+            out.push({ t: 'op', v: ch });
+            i++;
+            continue;
+        }
+        throw new Error(`runtime: the derivation uses a character the evaluator does not know: "${ch}"`);
+    }
+    return out;
+}
+class Reader {
+    toks;
+    constructor(toks) {
+        this.toks = toks;
+    }
+    pos = 0;
+    peek() {
+        return this.toks[this.pos];
+    }
+    next() {
+        const t = this.toks[this.pos];
+        if (!t) {
+            throw new Error('runtime: the derivation ended unexpectedly');
+        }
+        this.pos++;
+        return t;
+    }
+    expectOp(v) {
+        const t = this.next();
+        if (t.t !== 'op' || t.v !== v) {
+            throw new Error(`runtime: the derivation expected "${v}"`);
+        }
+    }
+}
+function evalExpr(r, env) {
+    return evalIf(r, env);
+}
+// if <cond> then <expr> else <expr> — R 60's tier selection rides it.
+function evalIf(r, env) {
+    const t = r.peek();
+    if (t && t.t === 'id' && t.v === 'if') {
+        r.next();
+        const cond = evalComparison(r, env);
+        const thenT = r.next();
+        if (thenT.t !== 'id' || thenT.v !== 'then') {
+            throw new Error('runtime: the derivation expected "then"');
+        }
+        const a = evalIf(r, env);
+        const elseT = r.next();
+        if (elseT.t !== 'id' || elseT.v !== 'else') {
+            throw new Error('runtime: the derivation expected "else"');
+        }
+        const b = evalIf(r, env);
+        return cond ? a : b;
+    }
+    return evalComparison(r, env);
+}
+function evalComparison(r, env) {
+    const left = evalAdd(r, env);
+    const t = r.peek();
+    if (t && t.t === 'op' && ['<=', '>=', '<', '>', '=', '!='].includes(t.v)) {
+        r.next();
+        const right = evalAdd(r, env);
+        switch (t.v) {
+            case '<=':
+                return left <= right ? 1 : 0;
+            case '>=':
+                return left >= right ? 1 : 0;
+            case '<':
+                return left < right ? 1 : 0;
+            case '>':
+                return left > right ? 1 : 0;
+            case '=':
+                return left === right ? 1 : 0;
+            case '!=':
+                return left !== right ? 1 : 0;
+        }
+    }
+    return left;
+}
+function evalAdd(r, env) {
+    let v = evalMul(r, env);
+    for (;;) {
+        const t = r.peek();
+        if (t && t.t === 'op' && (t.v === '+' || t.v === '-')) {
+            r.next();
+            const rhs = evalMul(r, env);
+            v = t.v === '+' ? v + rhs : v - rhs;
+            continue;
+        }
+        return v;
+    }
+}
+function evalMul(r, env) {
+    let v = evalUnary(r, env);
+    for (;;) {
+        const t = r.peek();
+        if (t && t.t === 'op' && (t.v === '*' || t.v === '/')) {
+            r.next();
+            const rhs = evalUnary(r, env);
+            v = t.v === '*' ? v * rhs : v / rhs;
+            continue;
+        }
+        return v;
+    }
+}
+function evalUnary(r, env) {
+    const t = r.peek();
+    if (t && t.t === 'op' && (t.v === '-' || t.v === '+')) {
+        r.next();
+        const v = evalUnary(r, env);
+        return t.v === '-' ? -v : v;
+    }
+    return evalPostfix(r, env);
+}
+function evalPostfix(r, env) {
+    let v = evalAtom(r, env);
+    for (;;) {
+        const t = r.peek();
+        if (t && t.t === 'op' && t.v === '.') {
+            r.next();
+            const field = r.next();
+            if (field.t !== 'id') {
+                throw new Error('runtime: the derivation expected a field name');
+            }
+            if (v === null || typeof v !== 'object') {
+                throw new Error(`runtime: the derivation reads "${field.v}" off a plain value`);
+            }
+            const scope = v;
+            const next = scope[field.v];
+            if (next === undefined) {
+                throw new Error(`runtime: the derivation reads the undeclared field "${field.v}"`);
+            }
+            v = next;
+            continue;
+        }
+        return v;
+    }
+}
+function evalAtom(r, env) {
+    const t = r.next();
+    if (t.t === 'num') {
+        return t.v;
+    }
+    if (t.t === 'id') {
+        if (t.v === 'abs' || t.v === 'min' || t.v === 'max') {
+            r.expectOp('(');
+            const a = evalExpr(r, env);
+            let b = null;
+            const comma = r.peek();
+            if (comma && comma.t === 'op' && comma.v === ',') {
+                r.next();
+                b = evalExpr(r, env);
+            }
+            r.expectOp(')');
+            if (t.v === 'abs') {
+                return Math.abs(a);
+            }
+            if (b === null) {
+                throw new Error(`runtime: ${t.v} needs two arguments`);
+            }
+            return t.v === 'min' ? Math.min(a, b) : Math.max(a, b);
+        }
+        if (t.v === 'ocl') {
+            // The calculation idiom's wrapping token — the expression inside
+            // the braces was already unwrapped by the caller.
+            r.expectOp('(');
+            const v = evalExpr(r, env);
+            r.expectOp(')');
+            return v;
+        }
+        if (t.v === 'true') {
+            return 1;
+        }
+        if (t.v === 'false') {
+            return 0;
+        }
+        if (!(t.v in env)) {
+            throw new Error(`runtime: the derivation names "${t.v}", which the run scope does not bind`);
+        }
+        const v = env[t.v];
+        if (typeof v === 'object') {
+            return v;
+        } // a payload object for '.' access
+        return typeof v === 'string' ? Number(v) : v;
+    }
+    if (t.t === 'op' && t.v === '(') {
+        const v = evalExpr(r, env);
+        r.expectOp(')');
+        return v;
+    }
+    throw new Error(`runtime: the derivation has an unexpected token`);
+}
+/** Evaluate one closed derivation over the run scope. The checks
+ *  guarantee every referenced name is declared (C149); this throws —
+ *  never silently indeterminates — when the scope lacks one. */
+function evaluateExpression(expr, env) {
+    const cleaned = expr
+        .replace(/^ocl\{/, '')
+        .replace(/\}$/, '')
+        .trim();
+    const r = new Reader(tokenize(cleaned));
+    const v = evalExpr(r, env);
+    if (r.peek() !== undefined) {
+        throw new Error('runtime: the derivation has trailing tokens');
+    }
+    return v;
+}
+/** Project the certificate from an executed run: the attestation's
+ *  claims, each judged by the run verdict its validated_by names. */
+function projectCertificate(standard, run, attestationId) {
+    const att = standard.attestations?.find(a => a.id === attestationId);
+    if (!att) {
+        throw new Error(`runtime: no attestation "${attestationId}" is declared`);
+    }
+    // The declared values: the lineage instance each claim names — the
+    // claim's declared path's leading id is the declaration instance.
+    const claims = [];
+    for (const claim of att.claims ?? []) {
+        const id = claim.promise;
+        // The declared path names the declaration stage (e.g. the
+        // application declaration's id); the lineage INSTANCE carries the
+        // suffix -declared on it — resolve either spelling.
+        const declaredId = claim.declared?.split('.')[0] ?? '';
+        const source = standard.instances.find(i => i.id === declaredId) ??
+            standard.instances.find(i => i.id === `${declaredId}-declared`) ??
+            standard.instances.find(i => i.id === att.subject);
+        // The declared value rides the attributes — or, for a
+        // classification claim, the dimensions map.
+        const raw = source
+            ? (source.has?.attributes?.[id] ??
+                source.has?.dimensions?.[id])
+            : undefined;
+        const value = typeof raw === 'object' && raw !== null
+            ? raw.value
+            : raw;
+        const declared = value === undefined
+            ? undefined
+            : {
+                value: (typeof value === 'object' && value !== null
+                    ? value.value
+                    : value),
+                unit: raw?.unit,
+                source: raw
+                    ?.provenance?.source,
+            };
+        const verdictId = claim.validatedBy ?? '';
+        const matched = run.verdicts.filter(v => v.id === verdictId || verdictId === '');
+        const outcome = verdictId === ''
+            ? 'unexecuted'
+            : matched.length === 0
+                ? 'unexecuted'
+                : matched.every(v => v.outcome === 'pass')
+                    ? 'pass'
+                    : matched.some(v => v.outcome === 'fail')
+                        ? 'fail'
+                        : 'indeterminate';
+        claims.push({
+            id,
+            declared,
+            validatedBy: verdictId || undefined,
+            outcome,
+            value: matched.length > 0 ? matched[matched.length - 1].value : undefined,
+        });
+    }
+    return {
+        attestation: att.id,
+        subject: att.subject,
+        statement: att.statement,
+        claims,
+    };
+}
+function attrValue(inst, id) {
+    const raw = inst.has?.attributes?.[id];
+    if (raw !== undefined &&
+        raw !== null &&
+        typeof raw === 'object' &&
+        'value' in raw) {
+        return raw;
+    }
+    return raw !== undefined ? { value: raw } : undefined;
+}
+/** The accuracy-class dimension value's typed payload (the class's
+ *  defining data — Table 1 limits, Table 4 tiers), as the evaluator's
+ *  nested scope. */
+function classPayload(standard, dimValue) {
+    const instrument = standard.instruments[0];
+    const dim = instrument?.dimensions.find(d => d.id === 'accuracy_class');
+    const valueId = dimValue;
+    const value = dim?.values.find(v => v.id === valueId);
+    const out = {};
+    const payload = value?.payload ?? {};
+    for (const [k, v] of Object.entries(payload)) {
+        const n = Number(v);
+        out[k] = Number.isNaN(n) ? String(v) : n;
+    }
+    return out;
+}
+/** Execute one deterministic run: the test's programs as applied, the
+ *  verdict chain derived from the authored data, the state trajectory
+ *  of the bound machine, and the evidence record. The same call with
+ *  the same arguments always returns the same run. */
+function executeRun(standard, options) {
+    const inst = standard.instances.find(i => i.id === options.instance);
+    if (!inst) {
+        throw new Error(`runtime: no instance "${options.instance}" is declared`);
+    }
+    // The run scope: the instance's declared attributes (p_lc, e_max,
+    // n_lc, ...) plus the typed class payload behind the dimension value.
+    const dimValue = inst.has?.dimensions?.accuracy_class;
+    const payload = classPayload(standard, dimValue);
+    const scope = { ...payload, accuracy_class: payload };
+    for (const [id] of Object.entries(inst.has?.attributes ?? {})) {
+        const v = attrValue(inst, id);
+        if (v === undefined) {
+            continue;
+        }
+        const n = Number(typeof v.value === 'object'
+            ? v.value.value
+            : v.value);
+        if (!Number.isNaN(n)) {
+            scope[id] = n;
+        }
+    }
+    // The programs: the test's ordered steps with their argument
+    // expressions evaluated over the run scope.
+    const programs = [];
+    const test = options.test
+        ? standard.conformanceTests.find(t => t.id === options.test)
+        : undefined;
+    if (test) {
+        for (const step of test.preparation?.entries ?? []) {
+            const args = {};
+            for (const [k, expr] of Object.entries(step.args ?? {})) {
+                try {
+                    args[k] = evaluateExpression(String(expr), scope);
+                }
+                catch {
+                    args[k] = String(expr);
+                }
+            }
+            programs.push({
+                program: 'preparation',
+                order: step.order ?? null,
+                drive: step.drive ?? '',
+                args,
+                hold: step.hold || undefined,
+            });
+        }
+        for (const point of test.stimulus?.entries ?? []) {
+            const args = {};
+            for (const [k, expr] of Object.entries(point.args ?? {})) {
+                try {
+                    args[k] = evaluateExpression(String(expr), scope);
+                }
+                catch {
+                    args[k] = String(expr);
+                }
+            }
+            programs.push({
+                program: 'stimulus',
+                order: point.order ?? null,
+                drive: point.drive ?? '',
+                args,
+                hold: point.hold || undefined,
+                acceptance: point.acceptance || undefined,
+            });
+        }
+    }
+    // The verdicts: the bound requirement's limit's accepted verdicts,
+    // evaluated per input — |e_l| against the MPE the model derives.
+    const verdicts = [];
+    const reqIds = [
+        ...(options.requirement ? [options.requirement] : []),
+        ...(test?.targets ?? []),
+    ];
+    const reqs = standard.requirements.filter(r => reqIds.includes(r.id));
+    const limitChain = reqs.flatMap(r => (r.limit ? [r] : []));
+    const verdictDefs = standard.verdicts;
+    for (const input of options.inputs) {
+        const runScope = {
+            ...scope,
+            load_v: input.load_v,
+            e_l: input.e_l,
+            indication: input.e_l,
+            reference: 0,
+        };
+        for (const req of limitChain) {
+            const limit = req.limit;
+            const accepts = limit.accepts ? [limit.accepts] : [];
+            for (const acc of accepts) {
+                const vdef = verdictDefs.find(v => v.id === acc.verdict);
+                if (!vdef) {
+                    continue;
+                }
+                let value;
+                try {
+                    value = evaluateExpression(vdef.derive, runScope);
+                }
+                catch {
+                    value = Number.NaN;
+                }
+                // The bound: the limit expression evaluated over the same scope
+                // (the MPE derivation — the tier selection over the applied
+                // load, scaled by the apportioning factor).
+                let bound = null;
+                const boundExpr = (limit.expression ?? '').trim();
+                if (boundExpr !== '') {
+                    const calc = standard.calculations.find(c => c.id === boundExpr);
+                    if (calc) {
+                        try {
+                            bound = evaluateExpression(calc.expression ?? '', runScope);
+                        }
+                        catch {
+                            bound = null;
+                        }
+                    }
+                    else {
+                        try {
+                            bound = evaluateExpression(boundExpr, runScope);
+                        }
+                        catch {
+                            bound = null;
+                        }
+                    }
+                }
+                const op = acc.op ?? 'lte';
+                const outcome = Number.isNaN(value) || bound === null
+                    ? 'indeterminate'
+                    : op === 'lte'
+                        ? value <= bound
+                            ? 'pass'
+                            : 'fail'
+                        : op === 'lt'
+                            ? value < bound
+                                ? 'pass'
+                                : 'fail'
+                            : op === 'gte'
+                                ? value >= bound
+                                    ? 'pass'
+                                    : 'fail'
+                                : op === 'gt'
+                                    ? value > bound
+                                        ? 'pass'
+                                        : 'fail'
+                                    : value === bound
+                                        ? 'pass'
+                                        : 'fail';
+                verdicts.push({
+                    id: vdef.id,
+                    derive: vdef.derive,
+                    inputs: { e_l: input.e_l, load_v: input.load_v },
+                    value,
+                    unit: vdef.unit || undefined,
+                    limit: boundExpr
+                        ? { expression: boundExpr, op, bound: bound ?? Number.NaN }
+                        : undefined,
+                    outcome,
+                });
+            }
+            // The formula leg: a limit whose uses name a declared calculation
+            // (R 60's `formula:mpe` — the tier selection) binds through it:
+            // the observed error against the calculation's value.
+            for (const use of limit.uses ?? []) {
+                if (!use.startsWith('formula:')) {
+                    continue;
+                }
+                const calc = standard.calculations.find(c => c.id === use.slice('formula:'.length));
+                if (!calc?.expression) {
+                    continue;
+                }
+                let bound;
+                try {
+                    bound = evaluateExpression(calc.expression, runScope);
+                }
+                catch {
+                    continue;
+                }
+                verdicts.push({
+                    id: calc.id,
+                    derive: calc.expression,
+                    inputs: { e_l: input.e_l, load_v: input.load_v },
+                    value: input.e_l,
+                    limit: { expression: calc.id, op: 'lte', bound },
+                    outcome: input.e_l <= bound ? 'pass' : 'fail',
+                });
+            }
+        }
+        // The named verdicts: the attestation claims' validated_by set.
+        // Every declared calculation's value binds into the scope under
+        // its id (mpe-verdict's derive reads `mpe`), then the derive
+        // evaluates as the judgment — truthy passes, falsy fails.
+        for (const vid of options.verdicts ?? []) {
+            const vdef = standard.verdicts.find(v => v.id === vid);
+            if (!vdef) {
+                continue;
+            }
+            const judgeScope = { ...runScope };
+            for (const calc of standard.calculations) {
+                if (!calc.expression || calc.id in judgeScope) {
+                    continue;
+                }
+                try {
+                    judgeScope[calc.id] = evaluateExpression(calc.expression, runScope);
+                }
+                catch {
+                    // an unrestorable binding stays absent — the derive's own
+                    // evaluation reports it
+                }
+            }
+            let outcome = 'indeterminate';
+            try {
+                outcome = evaluateExpression(vdef.derive, judgeScope) ? 'pass' : 'fail';
+            }
+            catch {
+                outcome = 'indeterminate';
+            }
+            verdicts.push({
+                id: vdef.id,
+                derive: vdef.derive,
+                inputs: { e_l: input.e_l, load_v: input.load_v },
+                value: input.e_l,
+                unit: vdef.unit || undefined,
+                outcome,
+            });
+        }
+    }
+    // The trajectory: the bound operational machine's fired steps (the
+    // runtime records what the run drove; the steps name transitions).
+    let trajectory = [];
+    const subject = standard.subjects.find(sub => sub.id === inst.of || sub.extends === inst.of);
+    const machineId = subject?.has?.state ?? '';
+    const machine = machineId
+        ? standard.stateMachines.find(m => m.id === machineId ||
+            m.entityName === machineId)
+        : undefined;
+    if (machine) {
+        const fired = [];
+        for (const p of programs) {
+            const action = p.drive;
+            if (action && machine.transitions.some(t => t.actionName === action)) {
+                fired.push({
+                    id: `${p.program}:${p.order ?? ''}`,
+                    fires: action,
+                    at: String(fired.length),
+                });
+            }
+        }
+        if (fired.length > 0) {
+            try {
+                trajectory = (0, operational_state_1.foldTrajectory)(machine, { state: machine.initialState, at: '0' }, fired);
+            }
+            catch {
+                trajectory = [];
+            }
+        }
+    }
+    // The evidence record: the run's outputs, per value with its
+    // provenance carried from the source attribute (the law's loop).
+    const evidence = [];
+    if (options.evidenceRegistry) {
+        const record = {
+            registry: options.evidenceRegistry,
+            run: options.runId ??
+                (options.test
+                    ? `${options.instance}:${options.test}`
+                    : options.instance),
+            values: [
+                ...options.inputs.map((inp, i) => ({
+                    id: `load_v[${i}]`,
+                    value: inp.load_v,
+                    provenance: undefined,
+                })),
+                ...verdicts.map((v, i) => ({
+                    id: `${v.id}[${i}]`,
+                    value: v.value,
+                    unit: v.unit,
+                    provenance: undefined,
+                })),
+            ],
+        };
+        evidence.push(record);
+    }
+    return {
+        instance: options.instance,
+        test: options.test,
+        programs,
+        verdicts,
+        trajectory,
+        evidence,
+    };
+}
+//# sourceMappingURL=runtime.js.map