@fiducian/compiler 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import type { TraceEvent, Violation } from "@fiducian/conductor";
+import type { PropertySpec } from "@fiducian/spec";
+export interface MonitorState {
+    step: number;
+    bindings: Record<string, unknown>;
+    status: "watching" | "passed" | "violated";
+    violation?: Violation;
+}
+export interface Monitor {
+    onEvent(event: TraceEvent): MonitorState;
+    snapshot(): MonitorState;
+}
+export declare function compileMonitor(spec: PropertySpec): Monitor;
+export declare function evaluateTrace(spec: PropertySpec, events: TraceEvent[]): {
+    passed: boolean;
+    violations: Violation[];
+    passedContexts: string[];
+};

package/dist/index.js

@@ -0,0 +1,147 @@
+function matchesSignature(event, from, to) {
+    return event.from === from && event.to === to && event.op === "send";
+}
+function evalConstraint(constraint, payload, bindings) {
+    switch (constraint.kind) {
+        case "true":
+            return true;
+        case "eq": {
+            const value = payload[constraint.left] ?? bindings[constraint.left];
+            return value === constraint.right;
+        }
+        case "fieldEq": {
+            const left = payload[constraint.left] ?? bindings[constraint.left];
+            const right = payload[String(constraint.right)] ??
+                bindings[String(constraint.right)];
+            return left === right;
+        }
+        default:
+            return false;
+    }
+}
+export function compileMonitor(spec) {
+    const steps = spec.steps;
+    const createState = () => ({
+        step: 0,
+        bindings: {},
+        status: "watching",
+    });
+    let state = createState();
+    const contexts = new Map();
+    const onEvent = (event) => {
+        if (spec.modal === "omega" || spec.modal === "none") {
+            return onEventForContext(event, contexts, steps, createState);
+        }
+        return onEventForContext(event, contexts, steps, createState);
+    };
+    return {
+        onEvent,
+        snapshot: () => ({ ...state }),
+    };
+}
+function allRemainingOptional(steps, step) {
+    return step >= steps.length || steps.slice(step).every((s) => s.optional);
+}
+function onEventForContext(event, contexts, steps, createState) {
+    let ctxState = contexts.get(event.contextId);
+    if (!ctxState) {
+        ctxState = createState();
+        contexts.set(event.contextId, ctxState);
+    }
+    if (ctxState.status !== "watching") {
+        return ctxState;
+    }
+    while (ctxState.step < steps.length &&
+        steps[ctxState.step].optional &&
+        !matchesSignature(event, steps[ctxState.step].signature.from, steps[ctxState.step].signature.to)) {
+        let matchesLater = false;
+        for (let j = ctxState.step + 1; j < steps.length; j++) {
+            const sig = steps[j].signature;
+            if (matchesSignature(event, sig.from, sig.to)) {
+                matchesLater = true;
+                break;
+            }
+        }
+        if (matchesLater) {
+            ctxState.step += 1;
+            continue;
+        }
+        break;
+    }
+    for (let future = ctxState.step + 1; future < steps.length; future++) {
+        if (steps[future].optional)
+            continue;
+        const futureSig = steps[future].signature;
+        if (matchesSignature(event, futureSig.from, futureSig.to)) {
+            ctxState.status = "violated";
+            ctxState.violation = {
+                contextId: event.contextId,
+                step: ctxState.step,
+                message: `Out-of-order step: saw ${futureSig.from}->${futureSig.to} before completing step ${ctxState.step + 1} (${steps[ctxState.step].signature.from}->${steps[ctxState.step].signature.to})`,
+                event,
+            };
+            return ctxState;
+        }
+    }
+    const expected = steps[ctxState.step];
+    if (!expected) {
+        ctxState.status = "passed";
+        return ctxState;
+    }
+    const { signature, constraint } = expected;
+    if (!matchesSignature(event, signature.from, signature.to)) {
+        return ctxState;
+    }
+    for (const field of signature.fields) {
+        if (field in event.payload) {
+            ctxState.bindings[field] = event.payload[field];
+        }
+    }
+    if (!evalConstraint(constraint, event.payload, ctxState.bindings)) {
+        ctxState.status = "violated";
+        ctxState.violation = {
+            contextId: event.contextId,
+            step: ctxState.step,
+            message: `Constraint failed at step ${ctxState.step + 1}: ${signature.from}->${signature.to}`,
+            event,
+        };
+        return ctxState;
+    }
+    ctxState.step += 1;
+    if (allRemainingOptional(steps, ctxState.step)) {
+        ctxState.status = "passed";
+    }
+    return ctxState;
+}
+export function evaluateTrace(spec, events) {
+    const monitor = compileMonitor(spec);
+    const violations = [];
+    const passedContexts = new Set();
+    const contextStates = new Map();
+    for (const event of events) {
+        const state = monitor.onEvent(event);
+        contextStates.set(event.contextId, state);
+    }
+    for (const [contextId, state] of contextStates) {
+        if (state.status === "violated" && state.violation) {
+            violations.push(state.violation);
+        }
+        else if (state.status === "passed") {
+            passedContexts.add(contextId);
+        }
+        else if (state.step > 0 && !allRemainingOptional(spec.steps, state.step)) {
+            violations.push({
+                contextId,
+                message: `Incomplete chain: stopped at step ${state.step + 1} of ${spec.steps.length}`,
+            });
+        }
+    }
+    const passed = violations.length === 0 &&
+        passedContexts.size > 0 &&
+        [...contextStates.values()].every((s) => s.status === "passed" || s.step === 0);
+    return {
+        passed,
+        violations,
+        passedContexts: [...passedContexts],
+    };
+}

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,57 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parseWaltzFile } from "@fiducian/spec";
+import { evaluateTrace } from "./index.js";
+const spec = parseWaltzFile(`
+  Omega(
+    send client->order{orderId} : true
+    ;
+    send order->kitchen{orderId, accepted} : accepted == true
+    ;
+    send order->billing{orderId, charged} : charged == true
+  )
+`);
+function ev(contextId, from, to, payload) {
+    return {
+        contextId,
+        from,
+        to,
+        op: "send",
+        payload,
+        timestamp: 0,
+    };
+}
+test("evaluateTrace passes correct order", () => {
+    const result = evaluateTrace(spec, [
+        ev("c1", "client", "order", { orderId: "42" }),
+        ev("c1", "order", "kitchen", { orderId: "42", accepted: true }),
+        ev("c1", "order", "billing", { orderId: "42", charged: true }),
+    ]);
+    assert.equal(result.passed, true);
+    assert.equal(result.violations.length, 0);
+});
+test("evaluateTrace fails when billing before kitchen", () => {
+    const result = evaluateTrace(spec, [
+        ev("c1", "client", "order", { orderId: "42" }),
+        ev("c1", "order", "billing", { orderId: "42", charged: true }),
+        ev("c1", "order", "kitchen", { orderId: "42", accepted: true }),
+    ]);
+    assert.equal(result.passed, false);
+    assert.ok(result.violations.length > 0);
+});
+test("evaluateTrace skips optional audit step", () => {
+    const optionalSpec = parseWaltzFile(`
+    Omega(
+      send client->order{orderId} : true
+      ;
+      optional send order->audit{orderId} : true
+      ;
+      send order->kitchen{orderId, accepted} : accepted == true
+    )
+  `);
+    const result = evaluateTrace(optionalSpec, [
+        ev("c1", "client", "order", { orderId: "42" }),
+        ev("c1", "order", "kitchen", { orderId: "42", accepted: true }),
+    ]);
+    assert.equal(result.passed, true);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@fiducian/compiler",
+  "version": "0.4.0",
+  "description": "Compile WALTZ specs into FiduciaTrace monitor state machines",
+  "license": "AGPL-3.0-or-later",
+  "keywords": ["fiducia", "fiducia", "compiler", "waltz", "monitor"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thesnmc/Fiducian.git",
+    "directory": "trace/packages/compiler"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@fiducian/spec": "0.4.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test dist/**/*.test.js",
+    "prepublishOnly": "npm run build"
+  }
+}